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.
Mis à jour le 21 novembre 2026.
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 :
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 :
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:workpar défaut, chaque message est lu une fois, puis retiré ; aveclimits, les messages restent jusqu’àmax_ageoumax_bytes, et se relisent. -
max_age: combien de temps un message est gardé au plus,7dpar défaut (30m,24h…). -
max_bytes: la place que la file prend au plus,128Mipar 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.
Les outils MCP de votre agent
Votre agent s’en occupe avec les outils deploy_app et get_environment.