import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common'; import { AckPolicy, DeliverPolicy, nanos, ReplayPolicy, RetentionPolicy, StorageType, StringCodec, } from 'nats'; import type { ConsumerMessages, JsMsg, Msg, NatsConnection, PubAck, Subscription, } from 'nats'; import { NATS_CLIENT } from './nats.constants'; export type NatsMessageHandler = ( data: T, msg: Msg, ) => Promise | void; export type JetStreamRetention = 'workqueue' | 'limits'; export type JetStreamMessageHandler = ( data: T, msg: JsMsg, ) => Promise | void; export interface JetStreamStreamOptions { name: string; subjects: string[]; retention: JetStreamRetention; maxAgeDays?: number; replicas?: number; } export interface JetStreamConsumerOptions { stream: string; durable: string; filterSubject: string; description?: string; ackWaitMs?: number; backoffMs?: number[]; maxDeliver?: number; maxAckPending?: number; replicas?: number; } export interface JetStreamConsumeOptions { stream: string; durable: string; maxMessages?: number; expiresMs?: number; nakDelayMs?: number; restartDelayMilliseconds?: number; } const JET_STREAM_CONSUMER_RESTART_DELAY_MILLISECONDS = 1_000; @Injectable() export class NatsService implements OnModuleDestroy { private readonly logger = new Logger(NatsService.name); private readonly stringCodec = StringCodec(); private readonly subscriptions = new Set(); private readonly jetStreamConsumers = new Set(); private isDestroying = false; constructor( @Inject(NATS_CLIENT) private readonly natsClient: NatsConnection, ) {} async onModuleDestroy() { this.isDestroying = true; for (const consumer of this.jetStreamConsumers) { try { await consumer.close(); } catch { // ignore } } this.jetStreamConsumers.clear(); for (const sub of this.subscriptions) { try { sub.unsubscribe(); } catch { // ignore } } this.subscriptions.clear(); try { const closed = this.natsClient.closed(); await this.natsClient.drain(); const err = await closed; if (err) this.logger.error(`NATS closed with error: ${err}`); } catch { try { await this.natsClient.close(); } catch { // ignore } } } public async publish(subject: string, data: T): Promise { this.natsClient.publish( subject, this.stringCodec.encode(JSON.stringify(data)), ); await this.natsClient.flush(); } public subscribe( subject: string, handler: NatsMessageHandler, options?: { queue?: string }, ): Subscription { const sub = this.natsClient.subscribe(subject, { queue: options?.queue, }); this.subscriptions.add(sub); void this.consumeSubscription(sub, handler); return sub; } public async publishJetStream( subject: string, data: T, options?: { messageId?: string; timeoutMs?: number }, ): Promise { const ack = await this.natsClient .jetstream() .publish(subject, this.stringCodec.encode(JSON.stringify(data)), { msgID: options?.messageId, timeout: options?.timeoutMs ?? 5000, }); return ack; } public async ensureJetStreamStream( options: JetStreamStreamOptions, ): Promise { const manager = await this.natsClient.jetstreamManager(); const config = { name: options.name, subjects: options.subjects, retention: this.toRetentionPolicy(options.retention), storage: StorageType.File, num_replicas: options.replicas ?? 1, max_age: options.maxAgeDays ? nanos(options.maxAgeDays * 24 * 60 * 60 * 1000) : 0, }; try { await manager.streams.info(options.name); await manager.streams.update(options.name, { subjects: config.subjects, max_age: config.max_age, num_replicas: config.num_replicas, }); return; } catch { await manager.streams.add(config); } } public async ensureJetStreamConsumer( options: JetStreamConsumerOptions, ): Promise { const manager = await this.natsClient.jetstreamManager(); const config = { durable_name: options.durable, name: options.durable, description: options.description, filter_subject: options.filterSubject, deliver_policy: DeliverPolicy.All, ack_policy: AckPolicy.Explicit, replay_policy: ReplayPolicy.Instant, ack_wait: nanos(options.ackWaitMs ?? 30000), backoff: (options.backoffMs ?? [5000, 30000, 120000, 600000]).map( (entry) => nanos(entry), ), max_deliver: options.maxDeliver ?? 10, max_ack_pending: options.maxAckPending ?? 50, num_replicas: options.replicas ?? 1, }; try { await manager.consumers.info(options.stream, options.durable); await manager.consumers.update(options.stream, options.durable, config); return; } catch { await manager.consumers.add(options.stream, config); } } public async consumeJetStream( options: JetStreamConsumeOptions, handler: JetStreamMessageHandler, ): Promise { while (!this.isDestroying) { try { const consumer = await this.natsClient .jetstream() .consumers.get(options.stream, options.durable); const messages = await consumer.consume({ max_messages: options.maxMessages ?? 10, expires: options.expiresMs ?? 30000, }); this.jetStreamConsumers.add(messages); try { for await (const msg of messages) { await this.dispatchJetStream(msg, handler, options); } } finally { this.jetStreamConsumers.delete(messages); } } catch (err) { if (this.isDestroying) return; this.logger.error( `JetStream consumer stream="${options.stream}" durable="${options.durable}" terminated: ${ (err as Error)?.stack ?? err }`, ); } await this.sleep( options.restartDelayMilliseconds ?? JET_STREAM_CONSUMER_RESTART_DELAY_MILLISECONDS, ); } } private async consumeSubscription( sub: Subscription, handler: NatsMessageHandler, ): Promise { try { for await (const msg of sub) { await this.dispatch(msg, handler); } } catch (err) { this.logger.error( `NATS subscription on subject="${sub.getSubject()}" terminated: ${ (err as Error)?.message ?? err }`, ); } finally { this.subscriptions.delete(sub); } } private async dispatch( msg: Msg, handler: NatsMessageHandler, ): Promise { let data: T; try { const decoded = this.stringCodec.decode(msg.data); data = JSON.parse(decoded) as T; } catch (err) { this.logger.warn( `Failed to decode NATS message on subject="${msg.subject}": ${ (err as Error)?.message ?? err }`, ); return; } try { await handler(data, msg); } catch (err) { this.logger.error( `Handler error on subject="${msg.subject}": ${ (err as Error)?.stack ?? err }`, ); } } private async dispatchJetStream( msg: JsMsg, handler: JetStreamMessageHandler, options: JetStreamConsumeOptions, ): Promise { let data: T; try { data = JSON.parse(msg.string()) as T; } catch (err) { this.logger.warn( `Terminating undecodable JetStream message subject="${msg.subject}" stream="${options.stream}": ${ (err as Error)?.message ?? err }`, ); msg.term('invalid_json'); return; } try { await handler(data, msg); const acked = await msg.ackAck({ timeout: 5000 }); if (!acked) { this.logger.warn( `JetStream ack was not confirmed subject="${msg.subject}" stream="${options.stream}" seq=${msg.seq}`, ); } } catch (err) { this.logger.error( `JetStream handler error subject="${msg.subject}" stream="${options.stream}" seq=${msg.seq}: ${ (err as Error)?.stack ?? err }`, ); msg.nak(options.nakDelayMs ?? 5000); } } private toRetentionPolicy(retention: JetStreamRetention): RetentionPolicy { return retention === 'workqueue' ? RetentionPolicy.Workqueue : RetentionPolicy.Limits; } private sleep(durationMilliseconds: number): Promise { return new Promise((resolve) => setTimeout(resolve, durationMilliseconds)); } }