From d0d578b2b0d5753a24b520587f187f92d1fc8269 Mon Sep 17 00:00:00 2001 From: dahyeon Date: Sun, 7 Jun 2026 00:35:18 -0700 Subject: [PATCH] feat(dakao): add jetstream outbox delivery flow --- .../src/modules/dakao/dakao-inbox.service.ts | 123 ++++++++++ .../dakao/dakao-jetstream-resource.service.ts | 64 ++++++ .../dakao/dakao-outbox-sweeper.service.ts | 47 ++++ .../src/modules/dakao/dakao-outbox.service.ts | 171 ++++++++++++++ .../dakao/dakao-send-result.subscriber.ts | 81 +++++++ apps/api/src/modules/dakao/dakao.module.ts | 17 +- .../modules/dakao/dakao.nats-names.spec.ts | 38 ++++ .../api/src/modules/dakao/dakao.nats-names.ts | 68 ++++++ .../src/modules/dakao/dakao.publisher.spec.ts | 59 +++-- apps/api/src/modules/dakao/dakao.publisher.ts | 83 +++---- .../api/src/modules/dakao/dakao.subscriber.ts | 102 ++++++--- apps/api/src/modules/dakao/dakao.types.ts | 19 +- .../api/src/modules/global/database/schema.ts | 191 ++++++++++++++++ .../src/modules/global/nats/nats.service.ts | 213 +++++++++++++++++- 14 files changed, 1154 insertions(+), 122 deletions(-) create mode 100644 apps/api/src/modules/dakao/dakao-inbox.service.ts create mode 100644 apps/api/src/modules/dakao/dakao-jetstream-resource.service.ts create mode 100644 apps/api/src/modules/dakao/dakao-outbox-sweeper.service.ts create mode 100644 apps/api/src/modules/dakao/dakao-outbox.service.ts create mode 100644 apps/api/src/modules/dakao/dakao-send-result.subscriber.ts create mode 100644 apps/api/src/modules/dakao/dakao.nats-names.spec.ts create mode 100644 apps/api/src/modules/dakao/dakao.nats-names.ts diff --git a/apps/api/src/modules/dakao/dakao-inbox.service.ts b/apps/api/src/modules/dakao/dakao-inbox.service.ts new file mode 100644 index 00000000..642a0597 --- /dev/null +++ b/apps/api/src/modules/dakao/dakao-inbox.service.ts @@ -0,0 +1,123 @@ +import { Injectable } from '@nestjs/common'; +import { ConnectionService } from '../global/database/connection.service'; + +const DEFAULT_LEASE_MS = 5 * 60 * 1000; + +export type DakaoInboxClaimResult = + | { status: 'claimed' } + | { status: 'duplicate' } + | { status: 'inflight' }; + +@Injectable() +export class DakaoInboxService { + constructor(private readonly connectionService: ConnectionService) {} + + public async claim(params: { + consumer: string; + projectId: string; + chatLogLogId: string; + leaseMs?: number; + }): Promise { + const Model = await this.connectionService.getModel('dakaoInboundMessage'); + const now = new Date(); + const processingExpiresAt = new Date( + now.getTime() + (params.leaseMs ?? DEFAULT_LEASE_MS), + ); + + try { + await Model.create({ + consumer: params.consumer, + projectId: params.projectId, + chatLogLogId: params.chatLogLogId, + state: 'processing', + attempts: 1, + processingExpiresAt, + }); + return { status: 'claimed' }; + } catch (err) { + if ((err as { code?: number })?.code !== 11000) throw err; + } + + const existing = await Model.findOne({ + consumer: params.consumer, + projectId: params.projectId, + chatLogLogId: params.chatLogLogId, + }) + .lean() + .exec(); + if (!existing) return { status: 'inflight' }; + if (existing.state === 'processed') return { status: 'duplicate' }; + if ( + existing.state === 'processing' && + existing.processingExpiresAt && + existing.processingExpiresAt > now + ) { + return { status: 'inflight' }; + } + + const updated = await Model.updateOne( + { + _id: existing._id, + $or: [ + { state: 'failed' }, + { state: 'processing', processingExpiresAt: { $lte: now } }, + ], + }, + { + $set: { + state: 'processing', + processingExpiresAt, + }, + $inc: { attempts: 1 }, + }, + ).exec(); + return updated.modifiedCount > 0 + ? { status: 'claimed' } + : { status: 'inflight' }; + } + + public async markProcessed(params: { + consumer: string; + projectId: string; + chatLogLogId: string; + }): Promise { + const Model = await this.connectionService.getModel('dakaoInboundMessage'); + await Model.updateOne( + { + consumer: params.consumer, + projectId: params.projectId, + chatLogLogId: params.chatLogLogId, + }, + { + $set: { + state: 'processed', + processedAt: new Date(), + }, + $unset: { processingExpiresAt: '', lastError: '' }, + }, + ).exec(); + } + + public async markFailed(params: { + consumer: string; + projectId: string; + chatLogLogId: string; + error: unknown; + }): Promise { + const Model = await this.connectionService.getModel('dakaoInboundMessage'); + await Model.updateOne( + { + consumer: params.consumer, + projectId: params.projectId, + chatLogLogId: params.chatLogLogId, + }, + { + $set: { + state: 'failed', + lastError: (params.error as Error)?.message ?? String(params.error), + }, + $unset: { processingExpiresAt: '' }, + }, + ).exec(); + } +} diff --git a/apps/api/src/modules/dakao/dakao-jetstream-resource.service.ts b/apps/api/src/modules/dakao/dakao-jetstream-resource.service.ts new file mode 100644 index 00000000..497171b9 --- /dev/null +++ b/apps/api/src/modules/dakao/dakao-jetstream-resource.service.ts @@ -0,0 +1,64 @@ +import { Injectable } from '@nestjs/common'; +import { NatsService } from '../global/nats/nats.service'; +import { resolveDakaoNatsNames } from './dakao.nats-names'; + +@Injectable() +export class DakaoJetStreamResourceService { + private ensurePromise: Promise | null = null; + + constructor(private readonly natsService: NatsService) {} + + public async ensure(): Promise { + this.ensurePromise ??= this.ensureInternal(); + await this.ensurePromise; + } + + private async ensureInternal(): Promise { + const names = resolveDakaoNatsNames(); + await this.natsService.ensureJetStreamStream({ + name: names.streams.botCommand, + subjects: [names.subjects.botCommandSubmitted], + retention: 'workqueue', + replicas: 1, + }); + await this.natsService.ensureJetStreamConsumer({ + stream: names.streams.botCommand, + durable: names.consumers.botCommand, + filterSubject: names.subjects.botCommandSubmitted, + description: 'LolyMpus Dakao bot command handler', + replicas: 1, + }); + + await this.natsService.ensureJetStreamStream({ + name: names.streams.sendRequest, + subjects: [names.subjects.chatSendMessage], + retention: 'workqueue', + replicas: 1, + }); + await this.natsService.ensureJetStreamConsumer({ + stream: names.streams.sendRequest, + durable: names.consumers.sendRequest, + filterSubject: names.subjects.chatSendMessage, + description: 'Dakao send-message worker', + replicas: 1, + }); + + await this.natsService.ensureJetStreamStream({ + name: names.streams.sendResult, + subjects: [ + names.subjects.chatSendMessageSucceeded, + names.subjects.chatSendMessageFailed, + ], + retention: 'limits', + maxAgeDays: 30, + replicas: 1, + }); + await this.natsService.ensureJetStreamConsumer({ + stream: names.streams.sendResult, + durable: names.consumers.sendResult, + filterSubject: `${names.env}.lolympus.dakao.chat.send-message.*.v1`, + description: 'LolyMpus Dakao send-message result handler', + replicas: 1, + }); + } +} diff --git a/apps/api/src/modules/dakao/dakao-outbox-sweeper.service.ts b/apps/api/src/modules/dakao/dakao-outbox-sweeper.service.ts new file mode 100644 index 00000000..ab2c3ebb --- /dev/null +++ b/apps/api/src/modules/dakao/dakao-outbox-sweeper.service.ts @@ -0,0 +1,47 @@ +import { + Injectable, + Logger, + OnModuleDestroy, + OnModuleInit, +} from '@nestjs/common'; +import { DakaoOutboxService } from './dakao-outbox.service'; + +const SWEEP_INTERVAL_MS = 60 * 1000; +const STALE_OUTBOX_MS = 5 * 60 * 1000; + +@Injectable() +export class DakaoOutboxSweeperService + implements OnModuleInit, OnModuleDestroy +{ + private readonly logger = new Logger(DakaoOutboxSweeperService.name); + private timer: NodeJS.Timeout | undefined; + + constructor(private readonly outboxService: DakaoOutboxService) {} + + onModuleInit() { + this.timer = setInterval(() => { + void this.sweep(); + }, SWEEP_INTERVAL_MS); + this.timer.unref(); + } + + onModuleDestroy() { + if (this.timer) clearInterval(this.timer); + } + + private async sweep(): Promise { + try { + const swept = await this.outboxService.sweepStale({ + staleMs: STALE_OUTBOX_MS, + limit: 20, + }); + if (swept > 0) { + this.logger.warn(`Re-published ${swept} stale Dakao outbox messages.`); + } + } catch (err) { + this.logger.error( + `Dakao outbox sweep failed: ${(err as Error)?.stack ?? err}`, + ); + } + } +} diff --git a/apps/api/src/modules/dakao/dakao-outbox.service.ts b/apps/api/src/modules/dakao/dakao-outbox.service.ts new file mode 100644 index 00000000..ca58d2cd --- /dev/null +++ b/apps/api/src/modules/dakao/dakao-outbox.service.ts @@ -0,0 +1,171 @@ +import { Injectable, Logger } from '@nestjs/common'; +import { ConnectionService } from '../global/database/connection.service'; +import { NatsService } from '../global/nats/nats.service'; +import { DakaoCommandEnvelope, DakaoResultEnvelope } from './dakao.types'; + +const TERMINAL_STATES = ['sent', 'failed'] as const; + +@Injectable() +export class DakaoOutboxService { + private readonly logger = new Logger(DakaoOutboxService.name); + + constructor( + private readonly connectionService: ConnectionService, + private readonly natsService: NatsService, + ) {} + + public async enqueueAndPublish(params: { + subject: string; + eventId: string; + envelope: DakaoCommandEnvelope; + }): Promise { + const OutboxModel = + await this.connectionService.getModel('dakaoOutboxMessage'); + await OutboxModel.findOneAndUpdate( + { eventId: params.eventId }, + { + $setOnInsert: { + eventId: params.eventId, + eventSource: params.envelope.eventSource, + type: params.envelope.type, + subject: params.subject, + correlationId: params.envelope.correlationId, + payload: params.envelope.payload as Record, + state: 'pending', + publishAttempts: 0, + compensationState: 'none', + }, + }, + { upsert: true, returnDocument: 'after', setDefaultsOnInsert: true }, + ).exec(); + + try { + await this.natsService.publishJetStream(params.subject, params.envelope, { + messageId: params.eventId, + }); + await OutboxModel.updateOne( + { + eventId: params.eventId, + state: { $nin: TERMINAL_STATES }, + }, + { + $set: { + state: 'published', + publishedAt: new Date(), + }, + $inc: { publishAttempts: 1 }, + $unset: { lastPublishError: '' }, + }, + ).exec(); + } catch (err) { + await OutboxModel.updateOne( + { + eventId: params.eventId, + state: { $nin: TERMINAL_STATES }, + }, + { + $inc: { publishAttempts: 1 }, + $set: { + lastPublishError: (err as Error)?.message ?? String(err), + }, + }, + ).exec(); + this.logger.error( + `Failed to publish Dakao outbox eventId=${params.eventId}: ${ + (err as Error)?.stack ?? err + }`, + ); + } + } + + public async applySendResult(params: { + subject: string; + envelope: DakaoResultEnvelope; + }): Promise<{ duplicate: boolean; terminalState?: 'sent' | 'failed' }> { + const ResultModel = await this.connectionService.getModel( + 'dakaoSendResultEvent', + ); + const OutboxModel = + await this.connectionService.getModel('dakaoOutboxMessage'); + + try { + await ResultModel.create({ + eventId: params.envelope.eventId, + requestEventId: params.envelope.requestEventId, + eventSource: params.envelope.eventSource, + requestEventSource: params.envelope.requestEventSource, + type: params.envelope.type, + subject: params.subject, + status: params.envelope.status, + correlationId: params.envelope.correlationId, + handledAt: new Date(params.envelope.handledAt), + providerMessageId: params.envelope.providerMessageId, + error: params.envelope.error, + raw: params.envelope as unknown as Record, + }); + } catch (err) { + if ((err as { code?: number })?.code === 11000) { + return { duplicate: true }; + } + throw err; + } + + const terminalState = + params.envelope.status === 'succeeded' ? 'sent' : 'failed'; + await OutboxModel.updateOne( + { + eventId: params.envelope.requestEventId, + state: { $nin: TERMINAL_STATES }, + }, + { + $set: { + state: terminalState, + terminalAt: new Date(), + resultEventId: params.envelope.eventId, + terminalError: params.envelope.error, + compensationState: + params.envelope.status === 'failed' ? 'pending' : 'none', + compensationReason: params.envelope.error?.code, + }, + }, + ).exec(); + + return { duplicate: false, terminalState }; + } + + public async sweepStale(params?: { + staleMs?: number; + limit?: number; + }): Promise { + const OutboxModel = + await this.connectionService.getModel('dakaoOutboxMessage'); + const staleBefore = new Date( + Date.now() - (params?.staleMs ?? 5 * 60 * 1000), + ); + const rows = await OutboxModel.find({ + state: { $in: ['pending', 'published'] }, + updatedAt: { $lte: staleBefore }, + }) + .sort({ updatedAt: 1 }) + .limit(params?.limit ?? 20) + .lean() + .exec(); + + for (const row of rows) { + await this.enqueueAndPublish({ + subject: row.subject, + eventId: row.eventId, + envelope: { + schema: 'dakao.command.v1', + eventId: row.eventId, + type: row.type, + eventSource: row.eventSource, + correlationId: row.correlationId, + payload: row.payload, + }, + }); + } + + return rows.length; + } +} diff --git a/apps/api/src/modules/dakao/dakao-send-result.subscriber.ts b/apps/api/src/modules/dakao/dakao-send-result.subscriber.ts new file mode 100644 index 00000000..ae3ac5ed --- /dev/null +++ b/apps/api/src/modules/dakao/dakao-send-result.subscriber.ts @@ -0,0 +1,81 @@ +import { Injectable, Logger, OnModuleInit } from '@nestjs/common'; +import { NatsService } from '../global/nats/nats.service'; +import { DakaoJetStreamResourceService } from './dakao-jetstream-resource.service'; +import { resolveDakaoNatsNames } from './dakao.nats-names'; +import { DakaoOutboxService } from './dakao-outbox.service'; +import { DakaoResultEnvelope } from './dakao.types'; + +@Injectable() +export class DakaoSendResultSubscriber implements OnModuleInit { + private readonly logger = new Logger(DakaoSendResultSubscriber.name); + + constructor( + private readonly natsService: NatsService, + private readonly resources: DakaoJetStreamResourceService, + private readonly outboxService: DakaoOutboxService, + ) {} + + async onModuleInit() { + await this.resources.ensure(); + const names = resolveDakaoNatsNames(); + void this.natsService.consumeJetStream( + { + stream: names.streams.sendResult, + durable: names.consumers.sendResult, + }, + (event, msg) => this.handleResult(event, msg.subject), + ); + this.logger.log( + `Dakao send-result subscriber ready on stream="${names.streams.sendResult}" durable="${names.consumers.sendResult}"`, + ); + } + + private async handleResult( + event: DakaoResultEnvelope, + subject: string, + ): Promise { + if (!this.validate(event)) { + this.logger.warn(`Ignoring invalid Dakao send-result on ${subject}`); + return; + } + + const result = await this.outboxService.applySendResult({ + subject, + envelope: event, + }); + if (result.duplicate) { + this.logger.log( + `Duplicate Dakao result ignored eventId=${event.eventId}`, + ); + return; + } + this.logger.log( + `Dakao result applied eventId=${event.eventId} requestEventId=${event.requestEventId} state=${result.terminalState ?? '-'}`, + ); + } + + private validate(event: unknown): event is DakaoResultEnvelope { + if (!event || typeof event !== 'object') return false; + const e = event as Partial; + if (e.schema !== 'dakao.result.v1') return false; + if (typeof e.eventId !== 'string' || e.eventId.length === 0) return false; + if (typeof e.requestEventId !== 'string' || e.requestEventId.length === 0) { + return false; + } + if (typeof e.eventSource !== 'string' || e.eventSource.length === 0) + return false; + if ( + typeof e.requestEventSource !== 'string' || + e.requestEventSource.length === 0 + ) { + return false; + } + if (e.status !== 'succeeded' && e.status !== 'failed') return false; + if ( + typeof e.handledAt !== 'string' || + Number.isNaN(Date.parse(e.handledAt)) + ) + return false; + return true; + } +} diff --git a/apps/api/src/modules/dakao/dakao.module.ts b/apps/api/src/modules/dakao/dakao.module.ts index 4ffe65d7..c9520727 100644 --- a/apps/api/src/modules/dakao/dakao.module.ts +++ b/apps/api/src/modules/dakao/dakao.module.ts @@ -1,14 +1,15 @@ import { Module } from '@nestjs/common'; import { MatchModule } from '../match/match.module'; import { RiotModule } from '../riot/riot.module'; -import { - DAKAO_OPTIONS, - createDefaultDakaoOptions, -} from './dakao.options'; +import { DAKAO_OPTIONS, createDefaultDakaoOptions } from './dakao.options'; import { DakaoPublisher } from './dakao.publisher'; import { DakaoSubscriber } from './dakao.subscriber'; +import { DakaoInboxService } from './dakao-inbox.service'; +import { DakaoJetStreamResourceService } from './dakao-jetstream-resource.service'; +import { DakaoOutboxSweeperService } from './dakao-outbox-sweeper.service'; +import { DakaoOutboxService } from './dakao-outbox.service'; import { DakaoUserService } from './dakao-user.service'; -import { IdempotencyCache } from './idempotency.cache'; +import { DakaoSendResultSubscriber } from './dakao-send-result.subscriber'; import { AccountRegisterHandler } from './handlers/account-register.handler'; import { MatchCancelHandler } from './handlers/match-cancel.handler'; import { MatchJoinHandler } from './handlers/match-join.handler'; @@ -22,10 +23,14 @@ import { PreferredPositionRegisterHandler } from './handlers/preferred-position- provide: DAKAO_OPTIONS, useFactory: createDefaultDakaoOptions, }, + DakaoOutboxService, + DakaoOutboxSweeperService, + DakaoInboxService, + DakaoJetStreamResourceService, DakaoPublisher, DakaoSubscriber, + DakaoSendResultSubscriber, DakaoUserService, - IdempotencyCache, AccountRegisterHandler, MatchListHandler, MatchJoinHandler, diff --git a/apps/api/src/modules/dakao/dakao.nats-names.spec.ts b/apps/api/src/modules/dakao/dakao.nats-names.spec.ts new file mode 100644 index 00000000..7ecc2915 --- /dev/null +++ b/apps/api/src/modules/dakao/dakao.nats-names.spec.ts @@ -0,0 +1,38 @@ +import { resolveDakaoNatsNames } from './dakao.nats-names'; + +describe('resolveDakaoNatsNames', () => { + it('resolves staging subjects and JetStream resources from NODE_ENV=test', () => { + expect(resolveDakaoNatsNames('test')).toEqual({ + env: 'staging', + shortEnv: 'STG', + subjects: { + botCommandSubmitted: 'staging.lolympus.dakao.bot-command.submitted.v1', + chatSendMessage: 'staging.dakao.chat.send-message.v1', + chatSendMessageSucceeded: + 'staging.lolympus.dakao.chat.send-message.succeeded.v1', + chatSendMessageFailed: + 'staging.lolympus.dakao.chat.send-message.failed.v1', + }, + streams: { + botCommand: 'STG_DAKAO_TO_LOLYMPUS_BOTCMD', + sendRequest: 'STG_DAKAO_SENDREQ', + sendResult: 'STG_DAKAO_TO_LOLYMPUS_SENDRES', + }, + consumers: { + botCommand: 'STG_LOLYMPUS_BOTCMD', + sendRequest: 'STG_DAKAO_SENDREQ_WORKER', + sendResult: 'STG_LOLYMPUS_SENDRES', + }, + }); + }); + + it('keeps JetStream resource names within the 32 character safety target', () => { + const names = resolveDakaoNatsNames('prod'); + const resources = [ + ...Object.values(names.streams), + ...Object.values(names.consumers), + ]; + + expect(resources.every((name) => name.length <= 32)).toBe(true); + }); +}); diff --git a/apps/api/src/modules/dakao/dakao.nats-names.ts b/apps/api/src/modules/dakao/dakao.nats-names.ts new file mode 100644 index 00000000..7c14a0e8 --- /dev/null +++ b/apps/api/src/modules/dakao/dakao.nats-names.ts @@ -0,0 +1,68 @@ +export type DakaoRuntimeEnv = 'dev' | 'staging' | 'prod'; +export type DakaoShortEnv = 'DEV' | 'STG' | 'PROD'; + +export interface DakaoNatsNames { + env: DakaoRuntimeEnv; + shortEnv: DakaoShortEnv; + subjects: { + botCommandSubmitted: string; + chatSendMessage: string; + chatSendMessageSucceeded: string; + chatSendMessageFailed: string; + }; + streams: { + botCommand: string; + sendRequest: string; + sendResult: string; + }; + consumers: { + botCommand: string; + sendRequest: string; + sendResult: string; + }; +} + +export function resolveDakaoNatsNames( + nodeEnv = process.env.NODE_ENV, +): DakaoNatsNames { + const env = resolveRuntimeEnv(nodeEnv); + const shortEnv = toShortEnv(env); + + return { + env, + shortEnv, + subjects: { + botCommandSubmitted: `${env}.lolympus.dakao.bot-command.submitted.v1`, + chatSendMessage: `${env}.dakao.chat.send-message.v1`, + chatSendMessageSucceeded: `${env}.lolympus.dakao.chat.send-message.succeeded.v1`, + chatSendMessageFailed: `${env}.lolympus.dakao.chat.send-message.failed.v1`, + }, + streams: { + botCommand: `${shortEnv}_DAKAO_TO_LOLYMPUS_BOTCMD`, + sendRequest: `${shortEnv}_DAKAO_SENDREQ`, + sendResult: `${shortEnv}_DAKAO_TO_LOLYMPUS_SENDRES`, + }, + consumers: { + botCommand: `${shortEnv}_LOLYMPUS_BOTCMD`, + sendRequest: `${shortEnv}_DAKAO_SENDREQ_WORKER`, + sendResult: `${shortEnv}_LOLYMPUS_SENDRES`, + }, + }; +} + +function resolveRuntimeEnv(nodeEnv?: string): DakaoRuntimeEnv { + if (nodeEnv === 'prod' || nodeEnv === 'production') return 'prod'; + if (nodeEnv === 'test' || nodeEnv === 'staging') return 'staging'; + return 'dev'; +} + +function toShortEnv(env: DakaoRuntimeEnv): DakaoShortEnv { + switch (env) { + case 'prod': + return 'PROD'; + case 'staging': + return 'STG'; + case 'dev': + return 'DEV'; + } +} diff --git a/apps/api/src/modules/dakao/dakao.publisher.spec.ts b/apps/api/src/modules/dakao/dakao.publisher.spec.ts index abc0e676..ad388e95 100644 --- a/apps/api/src/modules/dakao/dakao.publisher.spec.ts +++ b/apps/api/src/modules/dakao/dakao.publisher.spec.ts @@ -1,32 +1,31 @@ import { SecretService } from '../global/secret/secret.service'; -import { NatsService } from '../global/nats/nats.service'; import { DakaoCommandEnvelope, DakaoSendMessagePayload } from './dakao.types'; import { DakaoPublisher } from './dakao.publisher'; +import { DakaoOutboxService } from './dakao-outbox.service'; function makePublisher() { - const natsService = { - publish: jest.fn().mockResolvedValue(undefined), - subscribe: jest.fn(), - } as unknown as NatsService; + const outboxService = { + enqueueAndPublish: jest.fn().mockResolvedValue(undefined), + } as unknown as DakaoOutboxService; const secretService = {} as SecretService; - const publisher = new DakaoPublisher(natsService, secretService, { + const publisher = new DakaoPublisher(secretService, outboxService, { instanceId: 'test', }); - return { publisher, natsService }; + return { publisher, outboxService }; } -function getPublishedPayload(natsService: NatsService): DakaoSendMessagePayload { - const publish = natsService.publish as jest.Mock; - const envelope = publish.mock.calls[0][1] as DakaoCommandEnvelope< - DakaoSendMessagePayload - >; - return envelope.payload; +function getPublishedEnvelope( + outboxService: DakaoOutboxService, +): DakaoCommandEnvelope { + const enqueue = outboxService.enqueueAndPublish as jest.Mock; + return enqueue.mock.calls[0][0] + .envelope as DakaoCommandEnvelope; } describe('DakaoPublisher', () => { it('keeps valid mention segments intact', async () => { - const { publisher, natsService } = makePublisher(); + const { publisher, outboxService } = makePublisher(); await publisher.sendMessage({ chatroomId: '18474390111480678', @@ -40,7 +39,7 @@ describe('DakaoPublisher', () => { ], }); - expect(getPublishedPayload(natsService).segments).toEqual([ + expect(getPublishedEnvelope(outboxService).payload.segments).toEqual([ { kind: 'mention', userId: '6215844374579825921', @@ -51,7 +50,7 @@ describe('DakaoPublisher', () => { }); it('downgrades invalid mention segments to text before publishing', async () => { - const { publisher, natsService } = makePublisher(); + const { publisher, outboxService } = makePublisher(); await publisher.sendMessage({ chatroomId: '18474390111480678', @@ -65,9 +64,35 @@ describe('DakaoPublisher', () => { ], }); - expect(getPublishedPayload(natsService).segments).toEqual([ + expect(getPublishedEnvelope(outboxService).payload.segments).toEqual([ { kind: 'text', text: '@소쿠리' }, { kind: 'text', text: ' 신청 완료' }, ]); }); + + it('uses deterministic event ids and the shared Dakao send subject', async () => { + const { publisher, outboxService } = makePublisher(); + + await publisher.sendMessage({ + chatroomId: '18474390111480678', + segments: [{ kind: 'text', text: '신청 완료' }], + correlationId: 'chat-log-1', + }); + + const enqueue = outboxService.enqueueAndPublish as jest.Mock; + expect(enqueue.mock.calls[0][0]).toMatchObject({ + subject: 'staging.dakao.chat.send-message.v1', + eventId: 'lolympus:chat.send-message:chat-log-1', + }); + expect(getPublishedEnvelope(outboxService)).toMatchObject({ + schema: 'dakao.command.v1', + eventId: 'lolympus:chat.send-message:chat-log-1', + eventSource: 'lolympus', + type: 'chat.send-message', + correlationId: 'chat-log-1', + }); + expect(getPublishedEnvelope(outboxService)).not.toHaveProperty( + 'replySubject', + ); + }); }); diff --git a/apps/api/src/modules/dakao/dakao.publisher.ts b/apps/api/src/modules/dakao/dakao.publisher.ts index 21d49c99..0d788af4 100644 --- a/apps/api/src/modules/dakao/dakao.publisher.ts +++ b/apps/api/src/modules/dakao/dakao.publisher.ts @@ -1,86 +1,75 @@ -import { - Inject, - Injectable, - Logger, - OnModuleDestroy, - OnModuleInit, -} from '@nestjs/common'; +import { Inject, Injectable, Logger, OnModuleInit } from '@nestjs/common'; import { randomUUID } from 'crypto'; import { SecretService } from '../global/secret/secret.service'; -import { NatsService } from '../global/nats/nats.service'; import { DakaoCommandEnvelope, - DakaoResultEnvelope, DakaoSegment, DakaoSendMessagePayload, } from './dakao.types'; import type { DakaoOptions } from './dakao.options'; import { DAKAO_OPTIONS } from './dakao.options'; +import { resolveDakaoNatsNames } from './dakao.nats-names'; +import { DakaoOutboxService } from './dakao-outbox.service'; -const SEND_MESSAGE_SUBJECT_DEFAULT = 'dakao.command.chat.send-message.v1'; -const COMMAND_SOURCE_DEFAULT = 'lolympus-tournament-support'; +const EVENT_SOURCE_DEFAULT = 'lolympus'; @Injectable() -export class DakaoPublisher implements OnModuleInit, OnModuleDestroy { +export class DakaoPublisher implements OnModuleInit { private readonly logger = new Logger(DakaoPublisher.name); - private replySubject = ''; - private sendMessageSubject = SEND_MESSAGE_SUBJECT_DEFAULT; - private source = COMMAND_SOURCE_DEFAULT; + private sendMessageSubject = resolveDakaoNatsNames().subjects.chatSendMessage; + private eventSource = EVENT_SOURCE_DEFAULT; constructor( - private readonly natsService: NatsService, private readonly secretService: SecretService, + private readonly outboxService: DakaoOutboxService, @Inject(DAKAO_OPTIONS) private readonly options: DakaoOptions, ) {} async onModuleInit() { - const replyOverride = await this.secretService - .get('DAKAO_REPLY_SUBJECT_PREFIX') - .catch(() => undefined); const sendOverride = await this.secretService - .get('DAKAO_NATS_COMMAND_CHAT_SEND_MESSAGE_SUBJECT') + .get('DAKAO_CHAT_SEND_MESSAGE_SUBJECT') .catch(() => undefined); const sourceOverride = await this.secretService - .get('DAKAO_COMMAND_SOURCE') + .get('DAKAO_EVENT_SOURCE') .catch(() => undefined); - const replyPrefix = replyOverride || `dakao.result.${COMMAND_SOURCE_DEFAULT}`; - this.replySubject = `${replyPrefix}.${this.options.instanceId}`; - this.sendMessageSubject = sendOverride || SEND_MESSAGE_SUBJECT_DEFAULT; - this.source = sourceOverride || COMMAND_SOURCE_DEFAULT; + this.sendMessageSubject = + sendOverride || resolveDakaoNatsNames().subjects.chatSendMessage; + this.eventSource = sourceOverride || EVENT_SOURCE_DEFAULT; - this.natsService.subscribe( - this.replySubject, - (data) => this.handleReply(data), - ); this.logger.log( - `Dakao reply subscriber ready on subject="${this.replySubject}"`, + `Dakao send-message publisher ready on subject="${this.sendMessageSubject}" source="${this.eventSource}" instanceId="${this.options.instanceId}"`, ); } - async onModuleDestroy() { - // NatsService 가 subscription 정리한다. - } - public async sendMessage(params: { chatroomId: string; segments: DakaoSegment[]; correlationId?: string; + eventId?: string; }): Promise { + const eventId = + params.eventId ?? + (params.correlationId + ? `${this.eventSource}:chat.send-message:${params.correlationId}` + : `${this.eventSource}:chat.send-message:${randomUUID()}`); const payload: DakaoSendMessagePayload = { chatroomId: params.chatroomId, segments: this.normalizeSegments(params.segments), }; const envelope: DakaoCommandEnvelope = { schema: 'dakao.command.v1', - id: randomUUID(), + eventId, type: 'chat.send-message', - source: this.source, + eventSource: this.eventSource, correlationId: params.correlationId, - replySubject: this.replySubject, payload, }; - await this.natsService.publish(this.sendMessageSubject, envelope); + await this.outboxService.enqueueAndPublish({ + subject: this.sendMessageSubject, + eventId, + envelope, + }); } private normalizeSegments(segments: DakaoSegment[]): DakaoSegment[] { @@ -111,11 +100,7 @@ export class DakaoPublisher implements OnModuleInit, OnModuleDestroy { const id = segment.id.trim(); const altText = segment.altText.trim(); - if ( - id.length > 0 && - altText.length > 0 && - !/[()@]/.test(altText) - ) { + if (id.length > 0 && altText.length > 0 && !/[()@]/.test(altText)) { normalized.push({ kind: 'emoticon', id, altText }); continue; } @@ -139,16 +124,4 @@ export class DakaoPublisher implements OnModuleInit, OnModuleDestroy { const label = displayText || userId || '사용자'; return label.startsWith('@') ? label : `@${label}`; } - - private handleReply(reply: DakaoResultEnvelope): void { - if (reply.status === 'succeeded') { - this.logger.log( - `Dakao reply succeeded id=${reply.id} type=${reply.type} correlationId=${reply.correlationId ?? '-'}`, - ); - return; - } - this.logger.warn( - `Dakao reply failed id=${reply.id} type=${reply.type} code=${reply.error?.code ?? '-'} retryable=${reply.error?.retryable ?? false} message=${reply.error?.message ?? '-'}`, - ); - } } diff --git a/apps/api/src/modules/dakao/dakao.subscriber.ts b/apps/api/src/modules/dakao/dakao.subscriber.ts index 258fff2e..2a73644b 100644 --- a/apps/api/src/modules/dakao/dakao.subscriber.ts +++ b/apps/api/src/modules/dakao/dakao.subscriber.ts @@ -6,19 +6,19 @@ import { CommandParseError, parseCommand } from './parsers/command.parser'; import { DakaoInboundEvent, DakaoLong, DakaoSegment } from './dakao.types'; import { DakaoPublisher } from './dakao.publisher'; import { DakaoUserError, DakaoUserService } from './dakao-user.service'; -import { IdempotencyCache } from './idempotency.cache'; import { AccountRegisterHandler } from './handlers/account-register.handler'; import { MatchCancelHandler } from './handlers/match-cancel.handler'; import { MatchJoinHandler } from './handlers/match-join.handler'; import { MatchListHandler } from './handlers/match-list.handler'; import { PreferredPositionRegisterHandler } from './handlers/preferred-position-register.handler'; - -const INBOUND_SUBJECT_DEFAULT = 'lolympus-tournament-support.kakaotalk.command'; +import { resolveDakaoNatsNames } from './dakao.nats-names'; +import { DakaoInboxService } from './dakao-inbox.service'; +import { DakaoJetStreamResourceService } from './dakao-jetstream-resource.service'; @Injectable() export class DakaoSubscriber implements OnModuleInit { private readonly logger = new Logger(DakaoSubscriber.name); - private inboundSubject = INBOUND_SUBJECT_DEFAULT; + private readonly natsNames = resolveDakaoNatsNames(); private botUserId: string | undefined; constructor( @@ -26,7 +26,8 @@ export class DakaoSubscriber implements OnModuleInit { private readonly secretService: SecretService, private readonly dakaoUserService: DakaoUserService, private readonly publisher: DakaoPublisher, - private readonly idempotency: IdempotencyCache, + private readonly inbox: DakaoInboxService, + private readonly resources: DakaoJetStreamResourceService, private readonly accountRegisterHandler: AccountRegisterHandler, private readonly matchListHandler: MatchListHandler, private readonly matchJoinHandler: MatchJoinHandler, @@ -35,21 +36,20 @@ export class DakaoSubscriber implements OnModuleInit { ) {} async onModuleInit() { - const subjectOverride = await this.secretService - .get('DAKAO_INBOUND_SUBJECT') - .catch(() => undefined); - this.inboundSubject = subjectOverride || INBOUND_SUBJECT_DEFAULT; - this.botUserId = await this.secretService .get('DAKAO_BOT_USER_ID') .catch(() => undefined); - this.natsService.subscribe( - this.inboundSubject, + await this.resources.ensure(); + void this.natsService.consumeJetStream( + { + stream: this.natsNames.streams.botCommand, + durable: this.natsNames.consumers.botCommand, + }, (event) => this.handleEvent(event), ); this.logger.log( - `Dakao inbound subscriber ready on subject="${this.inboundSubject}"`, + `Dakao inbound subscriber ready on stream="${this.natsNames.streams.botCommand}" durable="${this.natsNames.consumers.botCommand}"`, ); } @@ -60,35 +60,52 @@ export class DakaoSubscriber implements OnModuleInit { return; } - const logIdKey = this.deriveLogIdKey(event); - if (logIdKey && this.idempotency.has(logIdKey)) { - return; + const chatLogLogId = this.serializeDakaoLong(event.origin.chatLog.logId); + let claimed = false; + if (chatLogLogId) { + const claim = await this.inbox.claim({ + consumer: this.natsNames.consumers.botCommand, + projectId: event.projectId, + chatLogLogId, + }); + if (claim.status === 'duplicate') return; + if (claim.status === 'inflight') { + throw new Error( + `Dakao event is already being processed projectId=${event.projectId} logId=${chatLogLogId}`, + ); + } + claimed = true; } - if (logIdKey) this.idempotency.remember(logIdKey); let communityId: mongoose.Types.ObjectId; try { - communityId = await this.dakaoUserService.resolveCommunityIdByDakaoProjectId( - event.projectId, - ); + communityId = + await this.dakaoUserService.resolveCommunityIdByDakaoProjectId( + event.projectId, + ); } catch (err) { if (err instanceof DakaoUserError) { if (err.code === 'invalid_project_id') { - this.logger.warn(`Invalid dakao projectId format: ${event.projectId}`); + this.logger.warn( + `Invalid dakao projectId format: ${event.projectId}`, + ); + if (claimed) await this.markProcessed(event, chatLogLogId); return; } if (err.code === 'community_not_found') { // 우리 쪽이 모르는 projectId. 메시지를 보내봤자 컨텍스트가 없으므로 로그만. this.logger.warn(`Unknown dakao projectId: ${event.projectId}`); + if (claimed) await this.markProcessed(event, chatLogLogId); return; } } + if (claimed) await this.markFailed(event, chatLogLogId, err); throw err; } let segments: DakaoSegment[]; const senderNickname = this.resolveSenderNickname(event); - const correlationId = this.serializeDakaoLong(event.origin.chatLog.logId); + const correlationId = chatLogLogId; try { const command = parseCommand(event.origin.chatLog.message); @@ -141,27 +158,35 @@ export class DakaoSubscriber implements OnModuleInit { segments, correlationId, }); + if (claimed) await this.markProcessed(event, chatLogLogId); } catch (err) { if (err instanceof CommandParseError) { // not_a_command 는 명령이 아닌 일반 메시지 → 무시. - if (err.code === 'not_a_command') return; + if (err.code === 'not_a_command') { + if (claimed) await this.markProcessed(event, chatLogLogId); + return; + } await this.publisher.sendMessage({ chatroomId: event.chatroomId, segments: this.parseErrorReply(event, senderNickname, err), correlationId, }); + if (claimed) await this.markProcessed(event, chatLogLogId); return; } this.logger.error( `Unhandled dakao event error: ${(err as Error)?.stack ?? err}`, ); + if (claimed) await this.markFailed(event, chatLogLogId, err); + throw err; } } private validate(event: unknown): event is DakaoInboundEvent { if (!event || typeof event !== 'object') return false; const e = event as Partial; - if (typeof e.projectId !== 'string' || e.projectId.length === 0) return false; + if (typeof e.projectId !== 'string' || e.projectId.length === 0) + return false; if (typeof e.chatroomId !== 'string' || e.chatroomId.length === 0) return false; if (typeof e.nickname !== 'string') return false; @@ -174,11 +199,6 @@ export class DakaoSubscriber implements OnModuleInit { return true; } - private deriveLogIdKey(event: DakaoInboundEvent): string | null { - const serialized = this.serializeDakaoLong(event.origin.chatLog.logId); - return serialized ? `${event.projectId}:${serialized}` : null; - } - private serializeDakaoLong(value: DakaoLong | string | undefined): string { if (typeof value === 'string') return value; if (!value || typeof value !== 'object') return ''; @@ -197,6 +217,30 @@ export class DakaoSubscriber implements OnModuleInit { return fallback ?? ''; } + private async markProcessed( + event: DakaoInboundEvent, + chatLogLogId: string, + ): Promise { + await this.inbox.markProcessed({ + consumer: this.natsNames.consumers.botCommand, + projectId: event.projectId, + chatLogLogId, + }); + } + + private async markFailed( + event: DakaoInboundEvent, + chatLogLogId: string, + error: unknown, + ): Promise { + await this.inbox.markFailed({ + consumer: this.natsNames.consumers.botCommand, + projectId: event.projectId, + chatLogLogId, + error, + }); + } + private parseErrorReply( event: DakaoInboundEvent, senderNickname: string, diff --git a/apps/api/src/modules/dakao/dakao.types.ts b/apps/api/src/modules/dakao/dakao.types.ts index 554b3bed..251d5c5f 100644 --- a/apps/api/src/modules/dakao/dakao.types.ts +++ b/apps/api/src/modules/dakao/dakao.types.ts @@ -1,7 +1,7 @@ // dakao NATS contracts -// inbound: dakao 가 lolympus-tournament-support.kakaotalk.command 로 발행하는 이벤트 -// outbound: 우리가 dakao.command.chat.send-message.v1 로 발행하는 명령 -// reply: dakao 가 우리 envelope 의 replySubject 로 publish 하는 결과 +// inbound: dakao 가 {env}.lolympus.dakao.bot-command.submitted.v1 로 발행하는 이벤트 +// outbound: 우리가 {env}.dakao.chat.send-message.v1 로 발행하는 명령 +// result: dakao 가 {env}.lolympus.dakao.chat.send-message.{succeeded|failed}.v1 로 발행하는 결과 이벤트 // ===== Inbound ===== export interface DakaoLong { @@ -77,22 +77,25 @@ export interface DakaoSendMessagePayload { export interface DakaoCommandEnvelope { schema: 'dakao.command.v1'; - id: string; + eventId: string; type: string; - source: string; + eventSource: string; correlationId?: string; - replySubject?: string; payload: TPayload; } -// ===== Reply ===== +// ===== Result ===== export interface DakaoResultEnvelope { schema: 'dakao.result.v1'; - id: string; + eventId: string; + requestEventId: string; type: string; + eventSource: string; + requestEventSource: string; status: 'succeeded' | 'failed'; handledAt: string; correlationId?: string; + providerMessageId?: string; result?: Record; error?: { code: string; diff --git a/apps/api/src/modules/global/database/schema.ts b/apps/api/src/modules/global/database/schema.ts index 560778dc..9aef3702 100644 --- a/apps/api/src/modules/global/database/schema.ts +++ b/apps/api/src/modules/global/database/schema.ts @@ -91,6 +91,39 @@ export const LEGACY_IMPORT_JOB_STATES: LegacyImportJobState[] = [ 'cancelled', ]; +export type DakaoInboundMessageState = 'processing' | 'processed' | 'failed'; +export const DAKAO_INBOUND_MESSAGE_STATES: DakaoInboundMessageState[] = [ + 'processing', + 'processed', + 'failed', +]; + +export type DakaoOutboxMessageState = + | 'pending' + | 'published' + | 'sent' + | 'failed'; +export const DAKAO_OUTBOX_MESSAGE_STATES: DakaoOutboxMessageState[] = [ + 'pending', + 'published', + 'sent', + 'failed', +]; + +export type DakaoOutboxCompensationState = + | 'none' + | 'pending' + | 'completed' + | 'failed'; +export const DAKAO_OUTBOX_COMPENSATION_STATES: DakaoOutboxCompensationState[] = + ['none', 'pending', 'completed', 'failed']; + +export type DakaoSendResultStatus = 'succeeded' | 'failed'; +export const DAKAO_SEND_RESULT_STATUSES: DakaoSendResultStatus[] = [ + 'succeeded', + 'failed', +]; + export interface PositionPreference { position: Position; priority: number; // 1 = 최우선, 숫자가 작을수록 높은 우선순위 @@ -300,9 +333,57 @@ export interface CommunitySeason { endedAt?: Date; } +export interface DakaoInboundMessage extends MongooseTimestamps { + consumer: string; + projectId: string; + chatLogLogId: string; + state: DakaoInboundMessageState; + attempts: number; + processingExpiresAt?: Date; + processedAt?: Date; + lastError?: string; +} + +export interface DakaoOutboxMessage extends MongooseTimestamps { + eventId: string; + eventSource: string; + type: string; + subject: string; + correlationId?: string; + payload: Record; + state: DakaoOutboxMessageState; + publishAttempts: number; + publishedAt?: Date; + terminalAt?: Date; + resultEventId?: string; + lastPublishError?: string; + terminalError?: Record; + compensationState: DakaoOutboxCompensationState; + compensationReason?: string; +} + +export interface DakaoSendResultEvent extends MongooseTimestamps { + eventId: string; + requestEventId: string; + eventSource: string; + requestEventSource: string; + type: string; + subject: string; + status: DakaoSendResultStatus; + correlationId?: string; + handledAt: Date; + providerMessageId?: string; + error?: Record; + raw: Record; +} + export type CommunityDocument = HydratedDocument; export type IdentityDocument = HydratedDocument; export type UserDocument = HydratedDocument; +export type DakaoInboundMessageDocument = HydratedDocument; +export type DakaoOutboxMessageDocument = HydratedDocument; +export type DakaoSendResultEventDocument = + HydratedDocument; // ===== RiotMatch (Riot 원본 매치 아카이브) ===== export interface RiotMatch extends MongooseTimestamps { @@ -844,6 +925,98 @@ CommunitySchema.index({ name: 1 }, { unique: true }); CommunitySchema.index({ ownerUserId: 1 }); CommunitySchema.index({ dakaoProjectId: 1 }, { unique: true, sparse: true }); +export const DakaoInboundMessageSchema = new Schema( + { + consumer: { type: String, required: true }, + projectId: { type: String, required: true }, + chatLogLogId: { type: String, required: true }, + state: { + type: String, + enum: DAKAO_INBOUND_MESSAGE_STATES, + required: true, + default: 'processing', + }, + attempts: { type: Number, required: true, default: 1 }, + processingExpiresAt: { type: Date }, + processedAt: { type: Date }, + lastError: { type: String }, + }, + { + timestamps: true, + collection: 'dakao_inbound_message', + }, +); + +DakaoInboundMessageSchema.index( + { consumer: 1, projectId: 1, chatLogLogId: 1 }, + { unique: true }, +); +DakaoInboundMessageSchema.index({ state: 1, processingExpiresAt: 1 }); + +export const DakaoOutboxMessageSchema = new Schema( + { + eventId: { type: String, required: true, unique: true }, + eventSource: { type: String, required: true }, + type: { type: String, required: true }, + subject: { type: String, required: true }, + correlationId: { type: String }, + payload: { type: Schema.Types.Mixed, required: true }, + state: { + type: String, + enum: DAKAO_OUTBOX_MESSAGE_STATES, + required: true, + default: 'pending', + }, + publishAttempts: { type: Number, required: true, default: 0 }, + publishedAt: { type: Date }, + terminalAt: { type: Date }, + resultEventId: { type: String }, + lastPublishError: { type: String }, + terminalError: { type: Schema.Types.Mixed }, + compensationState: { + type: String, + enum: DAKAO_OUTBOX_COMPENSATION_STATES, + required: true, + default: 'none', + }, + compensationReason: { type: String }, + }, + { + timestamps: true, + collection: 'dakao_outbox_message', + }, +); + +DakaoOutboxMessageSchema.index({ state: 1, updatedAt: 1 }); +DakaoOutboxMessageSchema.index({ correlationId: 1 }, { sparse: true }); + +export const DakaoSendResultEventSchema = new Schema( + { + eventId: { type: String, required: true, unique: true }, + requestEventId: { type: String, required: true }, + eventSource: { type: String, required: true }, + requestEventSource: { type: String, required: true }, + type: { type: String, required: true }, + subject: { type: String, required: true }, + status: { + type: String, + enum: DAKAO_SEND_RESULT_STATUSES, + required: true, + }, + correlationId: { type: String }, + handledAt: { type: Date, required: true }, + providerMessageId: { type: String }, + error: { type: Schema.Types.Mixed }, + raw: { type: Schema.Types.Mixed, required: true }, + }, + { + timestamps: true, + collection: 'dakao_send_result_event', + }, +); + +DakaoSendResultEventSchema.index({ requestEventId: 1, status: 1 }); + export const UserSchema = new Schema( { communityId: { @@ -1519,6 +1692,21 @@ MatchStatsSchema.index({ communityId: 1, championIds: 1 }); export const tournamentModelDefinitions: ModelDefinition[] = [ { name: 'identity', schema: IdentitySchema, schemaName: 'identity' }, { name: 'community', schema: CommunitySchema, schemaName: 'community' }, + { + name: 'dakaoInboundMessage', + schema: DakaoInboundMessageSchema, + schemaName: 'dakaoInboundMessage', + }, + { + name: 'dakaoOutboxMessage', + schema: DakaoOutboxMessageSchema, + schemaName: 'dakaoOutboxMessage', + }, + { + name: 'dakaoSendResultEvent', + schema: DakaoSendResultEventSchema, + schemaName: 'dakaoSendResultEvent', + }, { name: 'user', schema: UserSchema, schemaName: 'user' }, { name: 'riotMatch', schema: RiotMatchSchema, schemaName: 'riotMatch' }, { @@ -1548,6 +1736,9 @@ export const tournamentModelDefinitions: ModelDefinition[] = [ export interface TournamentModelTypes { identity: Identity; community: Community; + dakaoInboundMessage: DakaoInboundMessage; + dakaoOutboxMessage: DakaoOutboxMessage; + dakaoSendResultEvent: DakaoSendResultEvent; user: User; riotMatch: RiotMatch; tournamentCode: TournamentCode; diff --git a/apps/api/src/modules/global/nats/nats.service.ts b/apps/api/src/modules/global/nats/nats.service.ts index eb456d00..acbc2b3b 100644 --- a/apps/api/src/modules/global/nats/nats.service.ts +++ b/apps/api/src/modules/global/nats/nats.service.ts @@ -1,11 +1,21 @@ +import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common'; import { - Inject, - Injectable, - Logger, - OnModuleDestroy, -} from '@nestjs/common'; -import { StringCodec } from 'nats'; -import type { Msg, NatsConnection, Subscription } from 'nats'; + 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 = ( @@ -13,17 +23,62 @@ export type NatsMessageHandler = ( 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; +} + @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(); constructor( @Inject(NATS_CLIENT) private readonly natsClient: NatsConnection, ) {} async onModuleDestroy() { + for (const consumer of this.jetStreamConsumers) { + try { + await consumer.close(); + } catch { + // ignore + } + } + this.jetStreamConsumers.clear(); + for (const sub of this.subscriptions) { try { sub.unsubscribe(); @@ -68,6 +123,108 @@ export class NatsService implements OnModuleDestroy { 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 { + 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) { + this.logger.error( + `JetStream consumer stream="${options.stream}" durable="${options.durable}" terminated: ${ + (err as Error)?.stack ?? err + }`, + ); + } + } + private async consumeSubscription( sub: Subscription, handler: NatsMessageHandler, @@ -114,4 +271,46 @@ export class NatsService implements OnModuleDestroy { ); } } + + 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; + } }