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.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 commeorders.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
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
- 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.
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)*= exactement un token :orders.*.createdmatcheorders.eu.createdmais pasorders.eu.fr.created>= le reste de la queue du subject :orders.>matche tout ce qui est sousorders— très puissant, à utiliser avec précaution en production
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
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.
ack: traité avec succèsnak: échec, réessayer bientôtterm: arrêter de retenter ce message empoisonnéin_progress: toujours en cours, prolonger le timer d’ack
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.
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.
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-serverdans 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-serveraccepte 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.
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.