---
title: "Files de messages NATS JetStream : la doc de while.sh"
url: https://while.sh/fr/docs/briques/nats/
updated: 2026-11-21
---

# Files de messages (NATS)

Une file de messages entre vos services et vos tâches : le site y dépose le travail, le worker le prend quand il peut. Tout client NATS marche.

> Vous, à votre IA : Ajoute une file de tâches entre le site et le worker.

## Ce que votre agent écrit

Votre agent l'écrit dans while.yaml, à la racine de votre appli :

```yaml titre="while.yaml"
apiVersion: while/v1
project: my-app
services:
  - name: web
    port: 3000
queues:
  - name: taches
```

## Ce que reçoit votre appli

Votre appli reçoit ces variables d'environnement à chaque mise en ligne :

| Variable | Ce qu'elle contient |
|---|---|
| `NATS_URL` | L'adresse du serveur NATS. |

## Quand vous en servir

Servez-vous-en pour passer du travail d'un service à un autre, ou à une tâche planifiée : le site dépose une tâche et répond tout de suite, le worker la traite ensuite. Un message attend dans la file jusqu'à ce qu'il soit lu, même si le worker redémarre.

Une file se partage entre les services et les tâches d'un même environnement : la production a les siennes, chaque prévisualisation aussi. Deux projets ne partagent jamais une file.

## Comment ça marche

Chaque file du while.yaml est un flux NATS JetStream, gardé sur disque en trois exemplaires. Chaque service et chaque tâche reçoit l'adresse du serveur dans `NATS_URL`, et son identifiant dans le fichier `/run/secrets/NATS_CREDS`. Tout client NATS se connecte avec les deux, par exemple en Node.js :

```js
import { readFileSync } from 'node:fs';
import { connect, credsAuthenticator } from 'nats';

const nc = await connect({
  servers: process.env.NATS_URL,
  authenticator: credsAuthenticator(readFileSync('/run/secrets/NATS_CREDS')),
});
```

Les sujets d'une file sont sous son nom. Par défaut, la file `taches` garde les sujets `taches.>` : `taches.nouvelle` ou `taches.urgente.42`, mais pas `taches` seul. Publiez sous un sous-sujet, ou ajoutez `taches` à `subjects`.

Votre appli publie, lit, crée ses consommateurs et vide une file. Elle n'en crée ni n'en retire : ses files sont celles du while.yaml. Retirer une file du while.yaml efface ses messages ; détruire un environnement efface ceux de toutes ses files.

Votre agent suit chaque file avec `get_environment { view: "queues" }` : ses messages, sa taille, ses consommateurs et le retard du plus lent.

Selon l'offre :

| Offre | Files | Place en tout |
|---|---|---|
| Libre | 2 | 256 Mio |
| Pro | 4 | 2 Gio |
| Entreprise | 8 | 10 Gio |

La place en tout est la somme des `max_bytes` des files d'un environnement. Une mise en ligne qui dépasse le nombre de files ou la place de l'offre est refusée, et le refus dit l'offre et sa limite. Un message fait 1 Mio au plus.

## Tailles, versions et réglages

- `retention` : `work` par défaut, chaque message est lu une fois, puis retiré ; avec `limits`, les messages restent jusqu'à `max_age` ou `max_bytes`, et se relisent.

- `max_age` : combien de temps un message est gardé au plus, `7d` par défaut (`30m`, `24h`…).

- `max_bytes` : la place que la file prend au plus, `128Mi` par défaut. Avec ce défaut, autant de files que l'offre en permet tiennent toujours.

- `subjects` : huit sujets au plus, tous sous le nom de la file.

- Sur une file `work`, deux consommateurs ne peuvent pas lire le même sujet : donnez à chacun le sien (`filter_subject`).

- Chaque clé, avec ses bornes : [la référence de while.yaml](/fr/docs/reference/while-yaml/#les-files-de-messages).

## Les outils MCP de votre agent

Votre agent s'en occupe avec les outils `deploy_app` et `get_environment`.
