NATS : notions et définitions essentielles — subjects, JetStream, NKEYS, accounts

Avant d’écrire une seule ligne de code NATS, il faut verrouiller le vocabulaire. C’est l’objectif du chapitre 02 de la formation NATS de xavki : les notions et définitions qui vont structurer tout le reste de la série. Subject, message, queue group, wildcards, JetStream, durable, retention, acks, KV, ObjectStore, NKEYS, JWT, account, operator, leaf node — autant de mots qui reviendront dans chaque chapitre suivant. Cet article reprend le lexique présenté dans les slides de 02-notions-definitions du dépôt tutorials-nats, aligné sur la vidéo “NATS – 02. Notions & Définitions”. L’idée du chapitre : si les mots sont clairs, l’API devient beaucoup plus facile.

TL;DR

• Core NATS : subject, message, connection, publisher, subscriber, queue group, wildcards, request/reply.
• JetStream : stream, consumer, durable, replicas, retention, acks — la couche de persistance et de rejeu.
• Extras : KV store, ObjectStore, mirror, source, déduplication.
• Trust : token, NKEYS, JWT, account, operator — la chaîne d’authentification décentralisée.
• Topologie : cluster, leaf node, super-cluster, gateway, MQTT.
• Règle du chapitre : “c’est la carte” — si les mots sont clairs, l’API devient évidente.

La vidéo de référence

La vidéo NATS – 02. Notions & Définitions est le deuxième épisode de la formation NATS de la chaîne xavki, publiée le 3 août 2026 (~22 min). Elle fait partie du cours NATS – Tutorials de la chaîne, un parcours de 48 chapitres couvert par le dépôt tutorials-nats.

Le support de cours est le fichier 02-notions-definitions/slides.md, rendu dans le terminal avec mdp. C’est la carte du territoire : chaque mot posé ici sera réutilisé dans les chapitres suivants.

Note : la vidéo ne dispose pas de transcription sous-titrée, cet article s’appuie donc sur le contenu des slides du dépôt, qui sert de colonne vertébrale factuelle à la série.

Subject : la clé de routage

Le subject est la clé de routage de NATS : une chaîne dot-separated comme orders.eu.created. Les publishers envoient vers un subject, les subscribers expriment leur intérêt sur un subject. C’est à la fois l’adresse et une partie du design :

• un bon nommage rend le routage, le filtrage et la propriété plus faciles
• un mauvais nommage crée des consommateurs bruyants et des refactors douloureux plus tard

Exemple des slides : billing.invoice.paid — chaque service intéressé par les événements de facture payée peut s’y abonner.

Message : ce qui voyage dans NATS

Le message est ce qui circule réellement dans NATS :

• un payload de bytes bruts
• un subject qui dit au serveur où il va
• des headers optionnels pour la métadonnée
• un reply subject optionnel pour le request/reply

L’état d’esprit important : NATS ne se soucie pas du format du payload (JSON, texte, protobuf ou binaire). C’est l’application qui choisit le format et doit s’accorder dessus. Dans JetStream, le même message peut ensuite être rejoué depuis la persistance. Exemple des slides :

• subject : orders.created
• payload : {"id":42,"region":"eu"}
• headers : trace-id=abc123

Connection, Publisher, Subscriber

• Connection : un client relié à un nats-server. En général, un processus ouvre une connexion et la réutilise ; les librairies clientes gèrent les reconnexions et le failover de cluster.
• Publisher : du code qui appelle publish(). Il envoie un message et, en général, ne sait pas qui le reçoit.
• Subscriber : du code qui appelle subscribe(). Il reçoit les messages correspondant aux subjects demandés — c’est là que l’intention de routage devient du travail réel.

Exemple des slides : un service API publie users.created ; un service email s’abonne et envoie un email de bienvenue ; un service analytics s’abonne et incrémente des compteurs.

Queue Group : le load-balancing de NATS

Un queue group est un ensemble de subscribers partageant le même nom de queue. Tous écoutent le même subject, mais le serveur délivre chaque message à un seul membre. C’est le mécanisme de load-balancing de NATS, utile pour les workers, les consommateurs, les jobs en arrière-plan et les services sans état. Sur le même subject, des noms de queue différents créent des groupes indépendants ; sans queue group, chaque subscriber reçoit sa propre copie. Exemple des slides : 3 workers s’abonnent à image.resize dans la queue resizers — chaque job de resize part vers un seul worker.

Subjects et wildcards

Hiérarchie de subjects :

orders
orders.eu
orders.eu.created
orders.eu.created.priority-1Langage du code : CSS (css)

Wildcards :

• * = exactement un token : orders.*.created matche orders.eu.created mais pas orders.eu.fr.created
• > = le reste de la queue du subject : orders.> matche tout ce qui est sous orders — très puissant, à utiliser avec précaution en production

Exemple des slides : orders.*.created est idéal pour un niveau de région ; orders.> est préférable pour les subscribers d’audit ou de debug.

Request / Reply : du RPC sur de la messagerie

Le requester envoie un message et attend une réponse : await nc.request(subject, payload, timeout=...). Le client crée un subject de réponse temporaire comme _INBOX.<id> — c’est simplement l’adresse de retour de la réponse. Le responder s’abonne sur le subject de requête, lit le payload et répond à msg.reply. Du point de vue du client, cela ressemble à du RPC construit sur de la messagerie. Point important : si personne n’écoute, un NATS moderne peut renvoyer un signal rapide no responders / 503, mieux qu’un long timeout quand le service n’existe pas. Exemple des slides : une app demande auth.verify, le service auth répond ok ou denied ; si auth est down, l’appelant échoue vite au lieu de rester suspendu.

JetStream, Stream, Consumer : la persistance

JetStream est la couche de persistance de NATS : opt-in, activée sur le serveur avec -js. Elle transforme NATS de fire-and-forget en messagerie durable avec rejeu. Stream : un log append-only lié à un ou plusieurs subjects. Exemple : le stream ORDERS stocke tous les messages orders.>. Les streams définissent stockage, retention, réplicas et limites. Consumer : une position de lecture dans un stream. Deux modes :

• push consumer : le serveur pousse les messages
• pull consumer : le client récupère des lots quand il est prêt

Exemple des slides : le stream ORDERS stocke orders.> ; un consumer “accounting” lit tous les événements de commande plus tard, même après un redémarrage.

Durable, réplicas, mode de livraison

Durable name : une identité persistante pour un consumer, qui se souvient où il s’est arrêté après un redémarrage — indispensable pour reprendre un travail proprement. Ephemeral consumer : un consumer temporaire sans identité durable — utile pour les lectures ad hoc, les tests, le debug et les outils de courte durée. Réplicas : combien de copies de l’état du stream existent dans le cluster. 1 pour les setups locaux de dev les plus simples ; 3 est le choix courant en production pour la tolérance de panne. Plus de réplicas = plus de sécurité mais aussi plus de coût d’écriture. Exemple des slides : le consumer billing-worker reprend au dernier message acké après un déploiement ; un stream avec replicas=3 survit mieux à la perte d’un nœud qu’avec replicas=1.

Retention et acks

Politiques de retention — quand un message peut-il quitter le stream ?

• Limits : garder les messages jusqu’à ce que les limites de taille / nombre / âge soient atteintes — le plus proche d’un journal d’événements borné.
• Interest : garder les messages tant qu’au moins un consumer en a besoin.
• WorkQueue : retirer un message dès qu’un worker l’acke avec succès — le plus proche d’une sémantique de file de tâches.

Sémantique d’ack — ce que le consumer dit au serveur :

• ack : traité avec succès
• nak : échec, réessayer bientôt
• term : arrêter de retenter ce message empoisonné
• in_progress : toujours en cours, prolonger le timer d’ack

Exemple des slides : un worker reçoit payment.capture ; l’API externe est lente, il envoie in_progress ; après succès il envoie ack.

KV / ObjectStore / Mirror / Source / Déduplication

• KV store : une API clé-valeur construite sur des streams — idéale pour la config, l’aide à l’élection de leader et le suivi d’état. Les opérations paraissent plus simples que d’utiliser directement les subjects bruts.
• Object Store : de gros blobs découpés (chunked) sur des streams — utile pour les fichiers, artefacts, gros payloads et snapshots.
• Mirror : une copie en lecture seule d’un autre stream.
• Source : un stream qui ingère depuis un ou plusieurs streams.
• Déduplication : le publisher définit Nats-Msg-Id, le serveur ignore les doublons dans la fenêtre de déduplication.

Exemple des slides : un bucket KV stocke des feature flags ; un Object Store garde un fichier de modèle ou une archive de backup ; la dédup évite la double écriture quand un publisher retente le même événement de commande.

Token / NKEYS / JWT / Account / Operator

La chaîne de confiance de NATS, du plus simple au plus structuré :

• Token : un secret partagé entre client et serveur — le client le présente pour être accepté. Le modèle d’authentification le plus simple, facile à démarrer mais plus dur à rotater et à gérer proprement à l’échelle.
• NKEYS : authentification par clé publique/privée Ed25519. Le client prouve qu’il possède la clé privée en signant un challenge ; évite de passer un secret partagé réutilisable sur le fil ; un pas commun au-dessus de l’auth par token.
• JWT : un document signé d’identité et de permissions — décrit un utilisateur ou un compte et ce qu’il a le droit de faire.
• Account : la frontière de tenant dans NATS. Chaque compte a son espace de subjects isolé par défaut ; le trafic inter-comptes ne passe que par des exports/imports explicites.
• Operator : la racine de confiance du déploiement NATS. Il signe les JWTs des comptes et permet la confiance décentralisée et les setups multi-tenants.

Exemple des slides : le compte team-a ne peut publier que team-a.> ; le compte team-b ne voit pas ces subjects sans export/import explicite.

Cluster / Leaf Node / Super-cluster / Gateway / MQTT

La topologie NATS, du local au multi-DC :

• Cluster : plusieurs nœuds nats-server dans la même zone de confiance. Les clients se connectent à un nœud, le cluster partage état et routage.
• Leaf Node : un serveur en aval ou en edge attaché à un cluster central — utile pour les agences, usines, magasins, véhicules et sites distants. Réduit le besoin pour chaque client edge de se connecter directement au cœur.
• Super-cluster : plusieurs clusters reliés entre eux.
• Gateway : le lien inter-clusters qui transporte l’intérêt des subjects entre clusters.
• MQTT bridge / support MQTT : nats-server accepte directement les clients MQTT 3.1.1 et 5.0 — utile quand les devices IoT et les services NATS doivent partager le même backbone.

Exemple des slides : les serveurs de magasins se connectent en leaf nodes à un cluster régional central ; des capteurs MQTT publient des températures, des services back-end NATS les consomment.

Le récap du chapitre

Les slides concluent par la “carte” complète :

• Core NATS : subject, message, connection, subscriber, queue group, request/reply
• JetStream : stream, consumer, durable, replicas, retention, acks
• Extras : KV, ObjectStore, mirror, source, dédup
• Trust : token, NKEYS, JWT, account, operator
• Topologie : cluster, leaf node, super-cluster, gateway, MQTT

Liens utiles

• Dépôt tutorials-nats (GitLab) — les 48 chapitres de la formation
• Chapitre 02 – Notions et Définitions (slides)
• Vidéo de référence (YouTube)
• Chaîne xavki (YouTube)
• Xavki Blog
• Documentation officielle NATS
• NATS by Example — exemples officiels par pattern
• SDK Python nats.py
• CLI nats

FAQ

Qu’est-ce qu’un subject dans NATS ?
C’est la clé de routage : une chaîne dot-separated (ex. orders.eu.created) vers laquelle les publishers envoient et sur laquelle les subscribers expriment leur intérêt. C’est à la fois l’adresse et une partie du design.

Quelle est la différence entre Core NATS et JetStream ?
Core NATS est du pub/sub + request/reply fire-and-forget (at-most-once). JetStream, activé avec nats-server -js, ajoute une couche de persistance durable (streams, consumers) avec rejeu — du at-least-once.

Comment NATS fait-il du load-balancing ?
Avec les queue groups : plusieurs subscribers partagent le même nom de queue, le serveur délivre chaque message à un seul membre. Sans queue group, chaque subscriber reçoit sa propre copie.

Que signifient * et > dans un subject ?
* matche exactement un token (orders.*.created), > matche le reste de la queue (orders.>). > est très puissant, à utiliser avec précaution en production.

Qu’est-ce qu’un durable dans JetStream ?
C’est une identité persistante pour un consumer qui se souvient de sa position après un redémarrage. À l’inverse, un consumer ephemeral n’a pas d’identité durable (lecture ad hoc, tests, debug).

Quelles sont les politiques de retention JetStream ?
Limits (jusqu’aux limites de taille/nombre/âge), Interest (tant qu’un consumer en a besoin) et WorkQueue (retrait dès qu’un worker acke).

Quelle est la différence entre token, NKEYS et JWT ?
Le token est un secret partagé simple ; NKEYS est une authentification Ed25519 par preuve de possession de clé privée ; JWT est un document signé d’identité et de permissions. L’operator signe les JWTs des comptes, ce qui permet la confiance décentralisée et le multi-tenant.

Comment sécuriser l’isolation entre équipes ?
Avec les accounts : chaque compte a un espace de subjects isolé par défaut. Le trafic inter-comptes ne passe que par des exports/imports explicites. L’operator est la racine de confiance qui signe les JWTs des comptes.

À quoi sert un leaf node ?
À attacher un serveur edge (agence, usine, magasin, véhicule) à un cluster central, en réduisant le besoin pour chaque client edge de se connecter directement au cœur. C’est le modèle hub-and-spoke de NATS.

NATS supporte-t-il MQTT ?
Oui : nats-server accepte nativement les clients MQTT 3.1.1 et 5.0, utile quand les devices IoT et les services NATS doivent partager le même backbone.

Conclusion

Le chapitre 02 de la formation NATS de xavki est la carte du territoire : verrouiller le vocabulaire avant d’écrire du code. Core NATS (subject, message, queue group, wildcards, request/reply), JetStream (stream, consumer, durable, retention, acks), les extras (KV, ObjectStore, mirror, source, dédup), la chaîne de confiance (token, NKEYS, JWT, account, operator) et la topologie (cluster, leaf node, super-cluster, gateway, MQTT). Une fois ces notions posées, l’API de NATS devient beaucoup plus lisible. La suite logique est le chapitre 03 — NATS vs Alternatives — qui compare NATS à Kafka, RabbitMQ et Redis Streams.