Aller au contenu

Aller au sommaire de la doc

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.

Voir en Markdown

Files de messages NATS JetStream gardées sur disque : le travail passe d’un service à l’autre sur un tapis roulant

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 :

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 :

VariableCe qu’elle contient
NATS_URLL’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 :

OffreFilesPlace en tout
Libre2256 Mio
Pro42 Gio
Entreprise810 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.

Les outils MCP de votre agent

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

Donnez la phrase à votre IA, elle s’occupe du reste

À donner à votre IA

Lis while.sh/agents et aide-moi à démarrer avec while.

Copier la phrase

En 3 minutes, sans inscription, l’outil a son adresse. Pour le garder, créez votre compte.

Pour un projet d’entreprise, écrivez à l’équipe de while : hello@while.sh