Guide JetStream
JetStream est le moteur de persistance intégré de NATS, fournissant un stockage de messages durable, des stores key-value et des stores d'objets.
Streams
Les streams sont le mécanisme de persistance principal dans JetStream. Ils stockent les messages publiés sur des sujets spécifiques.
Créer un stream
- Accédez à votre cluster NATS
- Cliquez sur l'onglet JetStream
- Cliquez sur Créer un stream
- Configurez les paramètres du stream
Configuration du stream
| Champ | Description |
|---|---|
| Name | Identifiant unique du stream |
| Subjects | Patterns de sujets à capturer (ex: orders.*) |
| Retention | Comment les messages sont conservés |
| Storage | File (persistant) ou Memory (rapide) |
| Replicas | Nombre de copies pour la durabilité |
| Max Messages | Nombre maximum de messages |
| Max Bytes | Taille maximale de stockage |
| Max Age | TTL des messages au format de durée Go (ex. : 168h, 24h) |
Politiques de rétention
Choisissez en fonction de votre cas d'utilisation :
Limits (Par défaut)
Messages conservés jusqu'aux limites atteintes :
// Le stream garde les messages jusqu'à maxMsgs ou maxBytes
const stream = await jsm.streams.add({
name: 'EVENTS',
subjects: ['events.*'],
retention: RetentionPolicy.Limits,
max_msgs: 1000000,
max_bytes: 1024 * 1024 * 1024 // 1GB
});
Idéal pour : Event sourcing, logs d'audit, scénarios de rejeu
Interest
Messages conservés uniquement tant que des consumers existent :
const stream = await jsm.streams.add({
name: 'NOTIFICATIONS',
subjects: ['notifications.*'],
retention: RetentionPolicy.Interest
});
Idéal pour : Notifications en temps réel, mises à jour en direct
Work Queue
Chaque message délivré exactement une fois, puis supprimé :
const stream = await jsm.streams.add({
name: 'TASKS',
subjects: ['tasks.*'],
retention: RetentionPolicy.Workqueue
});
Idéal pour : Jobs en arrière-plan, traitement de tâches
Wildcards de sujets
NATS supporte des wildcards de sujets puissants :
| Pattern | Description | Correspondances |
|---|---|---|
* | Jeton unique | orders.* → orders.created, orders.updated |
> | Jetons multiples | events.> → events.user.signup, events.order.created |
// Capturer tous les événements de commandes
const stream = await jsm.streams.add({
name: 'ORDERS',
subjects: ['orders.*', 'orders.*.status']
});
// Capturer tous les événements
const stream = await jsm.streams.add({
name: 'ALL_EVENTS',
subjects: ['events.>']
});
Opérations sur les streams
Publier des messages
const js = nc.jetstream();
// Publier avec accusé de réception
const ack = await js.publish('orders.created', JSON.stringify({
orderId: 'order-123',
total: 99.99
}));
console.log(`Publié dans le stream : ${ack.stream}, seq : ${ack.seq}`);
Obtenir les infos du stream
const stream = await js.streams.get('ORDERS');
const info = await stream.info();
console.log(`Messages : ${info.state.messages}`);
console.log(`Octets : ${info.state.bytes}`);
console.log(`Consumers : ${info.state.consumer_count}`);
Purger un stream
// Supprimer tous les messages
await jsm.streams.purge('ORDERS');
// Supprimer les messages plus vieux d'une heure
await jsm.streams.purge('ORDERS', {
keep: 0,
seq: 0,
filter: 'orders.old'
});
Consumers
Les consumers définissent comment les messages sont délivrés depuis les streams.
Types de consumers
Push Consumer
Messages automatiquement délivrés aux abonnés :
const consumer = await js.consumers.get('ORDERS', 'order-processor');
// Messages poussés automatiquement
const messages = await consumer.consume();
for await (const msg of messages) {
await processOrder(JSON.parse(msg.data));
msg.ack();
}
Pull Consumer
Le client récupère explicitement les messages :
const consumer = await js.consumers.get('ORDERS', 'batch-processor');
// Récupérer un lot de messages
const messages = await consumer.fetch({ max_messages: 100 });
for await (const msg of messages) {
await processOrder(JSON.parse(msg.data));
msg.ack();
}
Durable vs Ephemeral
Consumers durables
L'état persiste à travers les redémarrages :
const consumer = await jsm.consumers.add('ORDERS', {
durable_name: 'order-processor',
ack_policy: AckPolicy.Explicit
});
À utiliser quand : Le traitement doit reprendre après les redémarrages
Consumers éphémères
Temporaires, supprimés quand inactifs :
const consumer = await jsm.consumers.add('ORDERS', {
inactive_threshold: 300000000000 // 5 minutes en nanosecondes
});
À utiliser quand : Monitoring en temps réel, traitement ponctuel
Configuration des consumers
| Champ | Description |
|---|---|
| Durable Name | Nom persistant du consumer |
| Deliver Policy | Où commencer (all, new, by_start_time) |
| Ack Policy | Comment accuser réception (none, all, explicit) |
| Max Deliver | Tentatives de livraison maximales |
| Filter Subject | Recevoir uniquement les messages correspondants |
Accusé de réception des messages
Toujours accuser réception des messages pour éviter la re-livraison :
for await (const msg of messages) {
try {
await processMessage(msg);
msg.ack(); // Succès
} catch (error) {
msg.nak(); // Demander la re-livraison
// Ou : msg.term() // Ne pas re-livrer
}
}
Stores Key-Value
JetStream fournit un stockage key-value distribué.
Créer un store KV
- Accédez à votre cluster NATS
- Naviguez vers Key-Value dans l'onglet JetStream
- Cliquez sur Créer un store KV
Configuration KV
| Champ | Description |
|---|---|
| Name | Nom du store |
| History | Nombre de révisions à garder par clé |
| TTL | Time-to-live des entrées |
| Max Value Size | Taille maximale des valeurs en octets |
| Max Bytes | Limite totale de stockage |
| Replicas | Nombre de copies |
Opérations KV
Définir des valeurs
const kv = await js.views.kv('CONFIG');
// Définir une valeur
await kv.put('app.theme', 'dark');
await kv.put('app.language', 'fr');
// Définir avec JSON
await kv.put('user.preferences', JSON.stringify({
notifications: true,
timezone: 'Europe/Paris'
}));
Obtenir des valeurs
// Obtenir la valeur actuelle
const entry = await kv.get('app.theme');
console.log(entry.string()); // 'dark'
// Obtenir toutes les clés
const keys = await kv.keys();
for await (const key of keys) {
console.log(key);
}
Surveiller les changements
// Surveiller une clé spécifique
const watch = await kv.watch({ key: 'app.theme' });
for await (const entry of watch) {
console.log(`Thème changé en : ${entry.string()}`);
updateTheme(entry.string());
}
// Surveiller toutes les clés
const watchAll = await kv.watch();
for await (const entry of watchAll) {
console.log(`${entry.key} = ${entry.string()}`);
}
Supprimer des valeurs
// Supprimer une clé
await kv.delete('app.theme');
// Purger toutes les révisions
await kv.purge('app.theme');
Cas d'utilisation
- Gestion de configuration : Stocker les paramètres d'application
- Feature flags : Basculer les fonctionnalités dynamiquement
- Stockage de session : Stocker les sessions utilisateur
- Verrous distribués : Implémenter l'élection de leader
Stores d'objets
Stockez de gros objets binaires dans JetStream.
Créer un store d'objets
- Accédez à votre cluster NATS
- Naviguez vers Object Store dans l'onglet JetStream
- Cliquez sur Créer un store d'objets
Configuration du store d'objets
| Champ | Description |
|---|---|
| Name | Nom du store |
| Max Bytes | Limite totale de stockage |
| Storage | File ou Memory |
| Replicas | Nombre de copies |
Opérations sur les objets
Stocker des objets
const os = await js.views.os('FILES');
// Stocker depuis un buffer
const data = Buffer.from('Hello, World!');
await os.put({ name: 'hello.txt' }, data);
// Stocker avec métadonnées
await os.put({
name: 'report.pdf',
description: 'Rapport mensuel',
headers: {
'Content-Type': 'application/pdf'
}
}, pdfBuffer);
Récupérer des objets
// Obtenir les infos de l'objet
const info = await os.info('hello.txt');
console.log(`Taille : ${info.size} octets`);
console.log(`Modifié : ${info.mtime}`);
// Télécharger l'objet
const result = await os.get('hello.txt');
const data = await result.data;
console.log(data.toString());
Lister les objets
const objects = await os.list();
for await (const obj of objects) {
console.log(`${obj.name} : ${obj.size} octets`);
}
Supprimer des objets
await os.delete('hello.txt');
Cas d'utilisation
- Stockage de fichiers : Stocker les uploads utilisateur
- Distribution d'assets : Distribuer des fichiers média
- Stockage de backups : Stocker les sauvegardes d'application
- Stockage de documents : Stocker PDFs, images
Bonnes pratiques
1. Concevoir une hiérarchie de sujets
# Bon - hiérarchique et spécifique
orders.created
orders.updated
orders.{orderId}.status
users.{userId}.profile.updated
# Mauvais - plat et ambigu
order_created
user_update
2. Définir des limites appropriées
const stream = await jsm.streams.add({
name: 'EVENTS',
subjects: ['events.>'],
max_msgs: 10000000, // 10M messages
max_bytes: 10737418240, // 10GB
max_age: 604800000000000 // 7 jours en nanosecondes
});
3. Utiliser des accusés de réception explicites
// Toujours accuser réception pour éviter la perte de messages
for await (const msg of messages) {
try {
await process(msg);
msg.ack();
} catch (error) {
msg.nak({ delay: 5000 }); // Réessayer après 5 secondes
}
}
4. Surveiller le retard des consumers
Configurez des alertes quand les consumers prennent du retard :
const info = await consumer.info();
if (info.num_pending > 10000) {
alert('Le retard du consumer est élevé !');
}
5. Utiliser des réplicas pour la durabilité
Utilisez toujours 3+ réplicas pour les streams de production :
const stream = await jsm.streams.add({
name: 'CRITICAL_EVENTS',
subjects: ['critical.>'],
num_replicas: 3
});