Aller au contenu principal

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​

  1. Accédez à votre cluster NATS
  2. Cliquez sur l'onglet JetStream
  3. Cliquez sur Créer un stream
  4. Configurez les paramètres du stream

Configuration du stream​

ChampDescription
NameIdentifiant unique du stream
SubjectsPatterns de sujets à capturer (ex: orders.*)
RetentionComment les messages sont conservés
StorageFile (persistant) ou Memory (rapide)
ReplicasNombre de copies pour la durabilité
Max MessagesNombre maximum de messages
Max BytesTaille maximale de stockage
Max AgeTTL 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 :

PatternDescriptionCorrespondances
*Jeton uniqueorders.* → orders.created, orders.updated
>Jetons multiplesevents.> → 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​

ChampDescription
Durable NameNom persistant du consumer
Deliver PolicyOù commencer (all, new, by_start_time)
Ack PolicyComment accuser réception (none, all, explicit)
Max DeliverTentatives de livraison maximales
Filter SubjectRecevoir 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​

  1. Accédez à votre cluster NATS
  2. Naviguez vers Key-Value dans l'onglet JetStream
  3. Cliquez sur Créer un store KV

Configuration KV​

ChampDescription
NameNom du store
HistoryNombre de révisions à garder par clé
TTLTime-to-live des entrées
Max Value SizeTaille maximale des valeurs en octets
Max BytesLimite totale de stockage
ReplicasNombre 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​

  1. Accédez à votre cluster NATS
  2. Naviguez vers Object Store dans l'onglet JetStream
  3. Cliquez sur Créer un store d'objets

Configuration du store d'objets​

ChampDescription
NameNom du store
Max BytesLimite totale de stockage
StorageFile ou Memory
ReplicasNombre 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
});

Prochaines étapes​