Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(session): commit each chat's messages in arrival order
Yudhi Armyndharis34c4c787d6ff
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.mdindex be7a162e3..f658f3d76 100644--- a/docs/19-plugin-architecture.md+++ b/docs/19-plugin-architecture.md@@ -518,6 +518,14 @@ is blocked: a handler that re-fires the event it is handling is short-circuitedre-entry only). Plugins never call `HookManager` directly — they use `ctx.registerHook(...)`, whichalso applies the per-session activation gate.+Chains for different messages run concurrently, so a handler can see one chat's messages out of order.+The gateway still stores and emits each chat's messages in arrival order: the `message:received` and+`message:sent` chains run concurrently, but the row insert, the websocket event, `message:persisted` and+the webhook enqueue wait for every earlier message of the same chat. A slow handler therefore delays that+chat's later messages, by at most its 5 s hook timeout (`SANDBOX_HOOK_TIMEOUT_MS`) for a sandboxed+plugin. Webhook HTTP deliveries still run concurrently, so a receiver that needs order should sort by+`timestamp`.+## 19.6 Plugin Loader`PluginLoaderService` (`src/core/plugins/plugin-loader.service.ts`) is the NestJS provider thatdiff --git a/src/modules/session/message-projector.service.spec.ts b/src/modules/session/message-projector.service.spec.tsindex 970403d8a..49da49c32 100644--- a/src/modules/session/message-projector.service.spec.ts+++ b/src/modules/session/message-projector.service.spec.ts@@ -4,7 +4,7 @@ import { ConfigService } from '@nestjs/config';import { MessageProjector, PERSIST_RETRY_DELAY_MS } from './message-projector.service';import { EngineRegistry } from '../../engine/engine-registry.service';import type { Repository } from 'typeorm';-import { Message, MessageDirection } from '../message/entities/message.entity';+import { Message, MessageDirection, MessageStatus } from '../message/entities/message.entity';import { Session } from './entities/session.entity';import { EventsGateway } from '../events/events.gateway';import { WebhookService } from '../webhook/webhook.service';@@ -719,6 +719,206 @@ describe('MessageProjector (inbound projection)', () => {});});+ // Hook chains for different messages finish in any order. A slow chain for one message must not let+ // a later message of the same chat be stored and announced first.+ describe('commit order within a chat', () => {+ const flush = async (): Promise<void> => {+ for (let i = 0; i < 10; i++) await new Promise(resolve => setImmediate(resolve));+ };+ /** Holds each message's message:received / message:sent chain until the test releases it by id. */+ const holdHooks = (): Map<string, (fail?: boolean) => void> => {+ const release = new Map<string, (fail?: boolean) => void>();+ hookManager.execute.mockImplementation((event: string, data: IncomingMessage) => {+ if (event !== 'message:received' && event !== 'message:sent') return Promise.resolve({ continue: true, data });+ return new Promise((resolve, reject) =>+ release.set(data.id, fail => (fail ? reject(new Error('hook blew up')) : resolve({ continue: true, data }))),+ );+ });+ return release;+ };+ const inserted = (): unknown[] =>+ messageRepository.insert.mock.calls.map(([row]) => (row as { waMessageId: string }).waMessageId);+ const dispatched = (): unknown[] =>+ webhookService.dispatch.mock.calls.map(([, event, payload]) => `${event}:${(payload as { id: string }).id}`);+ const chatA = '[email protected]';++ it('stores and dispatches in arrival order when a later hook finishes first', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'B', chatId: chatA }));+ // Both chains started: hooks still run concurrently.+ expect(hookManager.execute).toHaveBeenCalledTimes(2);++ release.get('B')!();+ await flush();+ expect(inserted()).toEqual([]);++ release.get('A')!();+ await flush();+ expect(inserted()).toEqual(['A', 'B']);+ expect(dispatched()).toEqual(['message.received:A', 'message.received:B']);+ expect(eventsGateway.emitMessage.mock.calls.map(([, m]) => (m as { id: string }).id)).toEqual(['A', 'B']);+ });++ it('does not hold back another chat', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'C', chatId: '[email protected]' }));+ release.get('C')!();+ await flush();++ expect(inserted()).toEqual(['C']);+ });++ it('still commits a later message when an earlier hook chain fails', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'B', chatId: chatA }));+ release.get('A')!(true);+ release.get('B')!();+ await flush();++ expect(inserted()).toEqual(['B']);+ expect(dispatched()).toEqual(['message.received:B']);+ });++ it('drops queued messages once the engine is retired', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'B', chatId: chatA }));+ release.get('B')!();+ await flush();+ engines.set(SESSION_ID, makeEngine());+ release.get('A')!();+ await flush();++ expect(inserted()).toEqual([]);+ expect(dispatched()).toEqual([]);+ });++ it('applies a revoke that lands while a message waits for its turn', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'B', chatId: chatA }));+ release.get('B')!();+ await flush();+ projector.handleMessageRevoked(SESSION_ID, engine, { id: 'B' } as never);+ release.get('A')!();+ await flush();++ const insertedB = messageRepository.insert.mock.invocationCallOrder[1];+ const afterB = messageRepository.update.mock.calls.filter(+ (_call, i) => messageRepository.update.mock.invocationCallOrder[i] > insertedB,+ );+ expect(afterB).toEqual([+ [{ sessionId: SESSION_ID, waMessageId: 'B' }, expect.objectContaining({ type: 'revoked' })],+ ]);+ });++ it('orders an own-send echo after an earlier inbound message of the same chat', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleOwnSendEcho(SESSION_ID, engine, makeIncoming({ id: 'S', chatId: chatA, fromMe: true }));+ release.get('S')!();+ await flush();+ expect(inserted()).toEqual([]);++ release.get('A')!();+ await flush();+ expect(inserted()).toEqual(['A', 'S']);+ expect(dispatched()).toEqual(['message.received:A', 'message.sent:S']);+ });++ describe('a change to an own-send echo that waits behind an earlier message', () => {+ /** Echo S is ready but queued behind inbound A; `change` runs while S has no row yet. */+ const echoWaitingBehindA = async (): Promise<{ engine: IWhatsAppEngine; releaseA: () => void }> => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const release = holdHooks();+ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming({ id: 'A', chatId: chatA }));+ projector.handleOwnSendEcho(SESSION_ID, engine, makeIncoming({ id: 'S', chatId: chatA, fromMe: true }));+ release.get('S')!();+ await flush();+ return { engine, releaseA: () => release.get('A')!() };+ };+ /** The update calls issued after S was inserted, as [where, change]. */+ const updatesAfterS = (): unknown[] => {+ const insertedS = messageRepository.insert.mock.invocationCallOrder[inserted().indexOf('S')];+ return messageRepository.update.mock.calls.filter(+ (_call, i) => messageRepository.update.mock.invocationCallOrder[i] > insertedS,+ );+ };+ const whereS = { sessionId: SESSION_ID, waMessageId: 'S' };++ beforeEach(() => {+ Object.assign(eventsGateway, { emitMessageEdited: jest.fn() });+ messageRepository.update.mockResolvedValue({ affected: 0 });+ });++ it('empties the echo row once it is written', async () => {+ const { engine, releaseA } = await echoWaitingBehindA();+ projector.handleMessageRevoked(SESSION_ID, engine, { id: 'S' } as never);+ releaseA();+ await flush();++ expect(inserted()).toEqual(['A', 'S']);+ expect(updatesAfterS()).toEqual([[whereS, expect.objectContaining({ body: '', type: 'revoked' })]]);+ });++ it('writes an edit onto the echo row once it is written', async () => {+ const { releaseA } = await echoWaitingBehindA();+ projector.applyMessageEditQueued(SESSION_ID, { messageId: 'S', body: 'fixed' } as never);+ releaseA();+ await flush();++ expect(updatesAfterS()).toEqual([[whereS, { body: 'fixed' }]]);+ });++ it('advances the echo row to the furthest ack that arrived before it was written', async () => {+ const { engine, releaseA } = await echoWaitingBehindA();+ projector.handleMessageAck(SESSION_ID, engine, 'S', 'read');+ projector.handleMessageAck(SESSION_ID, engine, 'S', 'delivered');+ releaseA();+ await flush();++ expect(updatesAfterS()).toEqual([[expect.objectContaining(whereS), { status: MessageStatus.READ }]]);+ });++ it('stores reactions that arrived before the row, without announcing them again', async () => {+ const emitMessageReaction = jest.fn();+ Object.assign(eventsGateway, { emitMessageReaction });+ const stored = { metadata: { keep: 1, reactions: { '[email protected]': 'hi' } } };+ messageRepository.findOne.mockImplementation(() => Promise.resolve(inserted().includes('S') ? stored : null));+ const { releaseA } = await echoWaitingBehindA();+ projector.applyReactionQueued(SESSION_ID, { messageId: 'S', senderId: '[email protected]', reaction: 'ok' } as never);+ projector.applyReactionQueued(SESSION_ID, { messageId: 'S', senderId: '[email protected]', reaction: '' } as never);+ releaseA();+ await flush();++ expect(updatesAfterS()).toEqual([[whereS, { metadata: { keep: 1, reactions: { '[email protected]': 'ok' } } }]]);+ expect(emitMessageReaction).toHaveBeenCalledTimes(2);+ });+ });+ });+// One transient insert failure (lock contention, a dropped connection, a pool timeout) used to lose// the row for good: the engine delivers each message once, and nothing retried the insert.describe('a transient insert failure', () => {@@ -822,6 +1022,33 @@ describe('MessageProjector (inbound projection)', () => {]);});+ it('clears an own-send echo row the same way', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ messageRepository.insert.mockRejectedValueOnce(busy()).mockRejectedValueOnce(dup());+ let releaseHook!: () => void;+ hookManager.execute.mockImplementationOnce(async (_event: string, data: unknown) => {+ await new Promise<void>(resolve => (releaseHook = resolve));+ return { continue: true, data };+ });++ projector.handleOwnSendEcho(SESSION_ID, engine, makeIncoming({ fromMe: true }));+ await flush();+ projector.handleMessageRevoked(SESSION_ID, engine, { id: 'wamid.1' } as never);+ releaseHook();+ await flush();+ await jest.advanceTimersByTimeAsync(PERSIST_RETRY_DELAY_MS);+ await flush();++ const retriedAt = messageRepository.insert.mock.invocationCallOrder[1];+ const afterRetry = messageRepository.update.mock.calls.filter(+ (_call, i) => messageRepository.update.mock.invocationCallOrder[i] > retriedAt,+ );+ expect(afterRetry).toEqual([+ [{ sessionId: SESSION_ID, waMessageId: 'wamid.1' }, expect.objectContaining({ body: '', type: 'revoked' })],+ ]);+ });+it('drops the retry when the engine is retired while it waits', async () => {const engine = makeEngine();engines.set(SESSION_ID, engine);diff --git a/src/modules/session/message-projector.service.ts b/src/modules/session/message-projector.service.tsindex dd38b49e3..85a9988ee 100644--- a/src/modules/session/message-projector.service.ts+++ b/src/modules/session/message-projector.service.ts@@ -100,13 +100,27 @@ export class MessageProjector {this.logger.error(`Unexpected failure applying message mutation: ${key}`, String(err));});- // Inbound messages whose `message:received` chain is running, by `${sessionId}:${waMessageId}`. The- // row is written only after the chain, so a handler that quotes the message reads it from here, and- // a revoke or edit landing meanwhile finds no row to update: it is recorded here and applied once- // the row is written (see applyChangesMadeInFlight).+ // Serializes the insert and dispatch of each chat's messages, by `${sessionId}:${chatId}`: hook+ // chains finish in any order, but a chat's rows, websocket events and webhooks follow arrival.+ private readonly chatCommits = new KeyedMutationQueue((key, err) => {+ this.logger.error(`Unexpected failure committing a message: ${key}`, String(err));+ });++ // Messages not yet written, by `${sessionId}:${waMessageId}`: inbound ones from the start of their+ // `message:received` chain, own-send echoes from the start of their `message:sent` chain, each until+ // its commit (which may wait behind earlier messages of the chat) ends. A handler that quotes the+ // message reads it from here, and a revoke, edit or ack landing meanwhile finds no row to update: it+ // is recorded here and applied once the row is written (see applyChangesMadeInFlight).private readonly inboundInFlight = new Map<string,- { message: InboundMessageData; revoked?: boolean; editedBody?: string }+ {+ message: InboundMessageData;+ revoked?: boolean;+ editedBody?: string;+ ackStatus?: MessageStatus;+ // Latest reaction per sender; '' means the sender withdrew theirs.+ reactions?: Record<string, string>;+ }>();// Reaction/edit applies, extracted to a plain collaborator. It shares this instance's@@ -163,13 +177,16 @@ export class MessageProjector {const messageData = { ...message };// Tracks the chain's current copy, so a quote taken mid-chain carries an earlier handler's rewrite.const inFlightKey = `${id}:${message.id}`;- // A re-fire of the same id keeps a change recorded against the chain it replaces.- const { revoked, editedBody } = this.inboundInFlight.get(inFlightKey) ?? {};- const inFlight = { message: messageData, revoked, editedBody };- this.inboundInFlight.set(inFlightKey, inFlight);+ const inFlight = this.trackInFlight(inFlightKey, messageData);- // Execute hook for message received - plugins can modify or stop processing- void this.hookManager+ const onFailure = (err: unknown): null => {+ this.logger.error(`onMessage handler failed for ${id}`, String(err));+ return null;+ };+ // Execute hook for message received - plugins can modify or stop processing. The hook chain and+ // sender resolution run concurrently across messages; the catch is attached now so a failure+ // while the commit waits its turn is never an unhandled rejection.+ const prepared = this.hookManager.execute('message:received', messageData, {sessionId: id,source: 'Engine',@@ -180,13 +197,42 @@ export class MessageProjector {},}).then(({ data }) =>- this.projectInboundMessage(id, engine, this.messageOrEngineCopy(id, 'message:received', data, message)),+ this.prepareInboundMessage(id, this.messageOrEngineCopy(id, 'message:received', data, message)),)- .catch(err => this.logger.error(`onMessage handler failed for ${id}`, String(err)))- .finally(() => {- // A re-fire of the same id may have replaced the entry; leave that one to its own chain.- if (this.inboundInFlight.get(inFlightKey) === inFlight) this.inboundInFlight.delete(inFlightKey);- });+ .catch(onFailure);+ this.chatCommits.enqueue(this.chatCommitKey(id, message), async () => {+ try {+ const finalMessage = await prepared;+ if (finalMessage) await this.commitInboundMessage(id, engine, finalMessage);+ } catch (err) {+ onFailure(err);+ } finally {+ this.untrackInFlight(inFlightKey, inFlight);+ }+ });+ }++ /** Record a message as not yet written; a re-fire of the same id keeps the changes recorded so far. */+ private trackInFlight(key: string, message: InboundMessageData) {+ const { revoked, editedBody, ackStatus, reactions } = this.inboundInFlight.get(key) ?? {};+ const inFlight = { message, revoked, editedBody, ackStatus, reactions };+ this.inboundInFlight.set(key, inFlight);+ return inFlight;+ }++ /** Drop the entry once its commit ended, unless a re-fire of the same id replaced it. */+ private untrackInFlight(key: string, inFlight: object): void {+ if (this.inboundInFlight.get(key) === inFlight) this.inboundInFlight.delete(key);+ }++ /**+ * Key of the per-chat commit queue. A slow hook chain for one message must not let a later message+ * of the same chat be stored and announced first, so the insert and dispatch of every message in a+ * chat (inbound and own-send echo alike) run in arrival order. Keyed on the engine's chatId, not+ * on a hook's rewrite.+ */+ private chatCommitKey(id: string, message: IncomingMessage): string {+ return `${id}:${message.chatId}`;}/**@@ -206,7 +252,7 @@ export class MessageProjector {* ({@link isMessagePayload}), keeping an earlier handler's rewrite; this is the last guard. A plugin* returning `data: null` to mean "I consumed it" used to throw below and erase the message from* history, webhooks and the websocket. A plugin may rewrite a message; it cannot make the gateway- * forget it (see projectInboundMessage).+ * forget it (see {@link prepareInboundMessage}).*/private messageOrEngineCopy(id: string,@@ -277,12 +323,8 @@ export class MessageProjector {return false;}- /** Post-hook continuation of {@link handleInboundMessage}: resolve sender, persist, dispatch. */- private async projectInboundMessage(- id: string,- engine: IWhatsAppEngine,- finalMessage: InboundMessageData,- ): Promise<void> {+ /** Post-hook continuation of {@link handleInboundMessage} that may run concurrently: resolve the sender. */+ private async prepareInboundMessage(id: string, finalMessage: InboundMessageData): Promise<InboundMessageData> {// `continue: false` is deliberately NOT read here. It means "stop the handler chain", which// HookManager has already done — the plugins after the one that returned it never ran. It// does not mean "this message never happened".@@ -309,8 +351,16 @@ export class MessageProjector {if (resolveFeatureFlags(this.configService).resolveLidToPhone && incoming.isLidSender && !incoming.fromMe) {incoming.senderPhone = await this.lidResolver.resolveSenderPhone(id, incoming.author ?? incoming.from);}+ return finalMessage;+ }- const outcome = await this.persistInboundMessage(id, engine, incoming);+ /** Per-chat, in-order stage of {@link handleInboundMessage}: persist, then dispatch. */+ private async commitInboundMessage(+ id: string,+ engine: IWhatsAppEngine,+ finalMessage: InboundMessageData,+ ): Promise<void> {+ const outcome = await this.persistInboundMessage(id, engine, finalMessage);if (!outcome) return;this.dispatchInboundMessage(id, finalMessage, outcome);}@@ -418,24 +468,50 @@ export class MessageProjector {}/**- * Write a revoke or edit that arrived while the message's `message:received` chain ran onto the row- * that chain just inserted: its own UPDATE matched no row then. Queued on the message's mutation- * chain, so it lands after any edit already queued, and a revoke wins over an edit. A change arriving- * after the insert finds the row itself.+ * Write a revoke, edit, reaction or ack that arrived before the message's row existed onto the row+ * just inserted: its own write matched no row then. Queued on the message's mutation chain, so it+ * lands after any edit already queued, and a revoke wins over the rest. A change arriving after the+ * insert finds the row itself. Reactions are only stored here; their event already went out.*/private applyChangesMadeInFlight(id: string, waMessageId: string): void {const pending = waMessageId ? this.inboundInFlight.get(`${id}:${waMessageId}`) : undefined;- if (!pending?.revoked && pending?.editedBody === undefined) return;+ const ackStatus = pending?.ackStatus;+ if (ackStatus) {+ void this.advanceAck(id, waMessageId, ackStatus).catch(err =>+ this.logger.error(`Failed to advance ack for ${waMessageId}`, String(err)),+ );+ }+ if (!pending?.revoked && pending?.editedBody === undefined && !pending?.reactions) return;this.enqueueMessageMutation(id, waMessageId, async () => {- const change = pending.revoked ? { body: '', type: 'revoked' } : { body: pending.editedBody };try {- await this.messageRepository.update({ sessionId: id, waMessageId }, change);+ if (pending.revoked) {+ await this.messageRepository.update({ sessionId: id, waMessageId }, { body: '', type: 'revoked' });+ return;+ }+ if (pending.editedBody !== undefined) {+ await this.messageRepository.update({ sessionId: id, waMessageId }, { body: pending.editedBody });+ }+ if (pending.reactions) await this.storeReactions(id, waMessageId, pending.reactions);} catch (err) {- this.logger.error(`Failed to apply a revoke or edit to message ${waMessageId}`, String(err));+ this.logger.error(`Failed to apply changes to message ${waMessageId}`, String(err));}});}+ /** Merge reactions into the row's metadata, withdrawing a sender's on ''. Must run on the mutation chain. */+ private async storeReactions(id: string, waMessageId: string, changes: Record<string, string>): Promise<void> {+ const row = await this.messageRepository.findOne({ where: { sessionId: id, waMessageId } });+ if (!row) return;+ const metadata = row.metadata ?? {};+ const reactions = { ...(metadata.reactions as Record<string, string> | undefined) };+ for (const [sender, reaction] of Object.entries(changes)) {+ if (reaction) reactions[sender] = reaction;+ else delete reactions[sender];+ }+ // Only the metadata column, so a concurrent ack UPDATE is not overwritten.+ await this.messageRepository.update({ sessionId: id, waMessageId }, { metadata: { ...metadata, reactions } });+ }+/** Fan an accepted inbound message out: `message:persisted` plugin hook, webhook, websocket emit. */private dispatchInboundMessage(id: string, finalMessage: InboundMessageData, outcome: InboundPersistOutcome): void {const { dbMessage, persisted } = outcome;@@ -498,85 +574,113 @@ export class MessageProjector {void this.sessionRepository.update(id, { lastActiveAt: new Date() }).catch(() => undefined);const messageData = { ...message };- // Execute hook for message sent - plugins can modify or stop processing- void this.hookManager+ const onFailure = (err: unknown): null => {+ this.logger.error(`onMessageCreate handler failed for ${id}`, String(err));+ return null;+ };+ // Execute hook for message sent - plugins can modify or stop processing. Like the inbound path,+ // the hook chain runs concurrently and the commit waits its turn on the chat's queue.+ const prepared = this.hookManager.execute('message:sent', messageData, {sessionId: id,source: 'Engine',accept: isMessagePayload,})- .then(async ({ data }) => {- const finalMessage = this.messageOrEngineCopy(id, 'message:sent', data, message);- // `continue: false` is not read here, for the same reason as the message:received path- // above: the send has already happened, so a plugin can stop the handler chain but cannot- // un-send it. Skipping the persist below dropped the operator's own outgoing message from- // history and from `message.sent` webhooks.-- // Persist the outgoing message so local history reflects sends composed on a linked phone- // (message_create is the ONLY event those produce). It also fires for API-originated sends,- // which the REST send path persists itself — the UNIQUE(sessionId, waMessageId) index is- // the atomic dedup oracle between the two writers: the loser skips its insert, and- // persistSentState additionally drops its redundant PENDING row when the echo won. The- // webhook/WS dispatch below is identical whether the insert won, lost, or failed — the- // message.sent contract is unchanged.- const outgoing: IncomingMessage = finalMessage;- const metadata = buildMessageMetadata(outgoing, true);-- // The ephemeral opt-out gates STORAGE only (mirrors onMessage); the live dispatch below- // is today's contract and stays.- const mayPersist =- resolveFeatureFlags(this.configService).storeEphemeralMessages ||- !(outgoing.ephemeralDuration && outgoing.ephemeralDuration > 0);-- if (mayPersist) {- const dbMessage = this.messageRepository.create({- sessionId: id,- waMessageId: storableWaMessageId(outgoing.id),- chatId: outgoing.chatId,- from: outgoing.from,- to: outgoing.to,- body: outgoing.body,- type: outgoing.type,- direction: MessageDirection.OUTGOING,- timestamp: outgoing.timestamp,- status: MessageStatus.SENT,- metadata,- });- // The hook chain above is async; a delete()/teardown can retire this engine while it- // awaits. Re-check liveness so a late continuation can't persist an orphan row- // (mirrors onMessage).- if (!this.engines.isLive(id, engine)) return;- // A unique violation means the REST send path already persisted this API-originated- // send: the dedup oracle working as intended, not an error. Any other failure (after the- // one transient retry) fails open, so a real send is never dropped on a DB fault.- const outcome = await this.insertWithRetry(id, engine, dbMessage, 'outgoing');- if (outcome.landed === 'stale') return;- if (outcome.landed === 'yes') {- // Fire-and-forget, mirroring onMessage: plugin providers (search etc.) see phone-- // composed sends exactly like API sends.- void this.hookManager- .execute(- 'message:persisted',- { sessionId: id, message: dbMessage },- { sessionId: id, source: 'SessionService' },- )- .catch(() => undefined);-- // Archive this send's media, mirroring onMessage. This is the ONLY path a phone-composed- // send takes, so the REST-side chokepoint would never see it. Opt-in twice over- // (CHAT_MEDIA_ARCHIVE_ENABLED + _OUTBOUND) and a no-op otherwise; archive() itself- // refuses a row that is already archived, so the REST writer racing us costs nothing.- if (this.configService?.get<boolean>('chatMedia.archiveOutbound', false) === true) {- void this.chatMediaArchive?.archive(dbMessage).catch(() => undefined);- }- }+ .then(({ data }) => this.messageOrEngineCopy(id, 'message:sent', data, message))+ .catch(onFailure);+ // The commit may wait behind a slow earlier message of the chat; a revoke, edit or ack of this+ // send landing meanwhile is recorded here and applied once the row is written.+ const inFlightKey = `${id}:${message.id}`;+ const inFlight = this.trackInFlight(inFlightKey, messageData);+ this.chatCommits.enqueue(this.chatCommitKey(id, message), async () => {+ try {+ const finalMessage = await prepared;+ if (finalMessage) await this.commitOwnSendEcho(id, engine, finalMessage);+ } catch (err) {+ onFailure(err);+ } finally {+ this.untrackInFlight(inFlightKey, inFlight);+ }+ });+ }++ /** Per-chat, in-order stage of {@link handleOwnSendEcho}: persist, then dispatch `message.sent`. */+ private async commitOwnSendEcho(+ id: string,+ engine: IWhatsAppEngine,+ finalMessage: InboundMessageData,+ ): Promise<void> {+ // `continue: false` is not read here, for the same reason as the message:received path+ // above: the send has already happened, so a plugin can stop the handler chain but cannot+ // un-send it. Skipping the persist below dropped the operator's own outgoing message from+ // history and from `message.sent` webhooks.++ // Persist the outgoing message so local history reflects sends composed on a linked phone+ // (message_create is the ONLY event those produce). It also fires for API-originated sends,+ // which the REST send path persists itself; the UNIQUE(sessionId, waMessageId) index is+ // the atomic dedup oracle between the two writers: the loser skips its insert, and+ // persistSentState additionally drops its redundant PENDING row when the echo won. The+ // webhook/WS dispatch below is identical whether the insert won, lost, or failed: the+ // message.sent contract is unchanged.+ const outgoing: IncomingMessage = finalMessage;+ const metadata = buildMessageMetadata(outgoing, true);++ // The ephemeral opt-out gates STORAGE only (mirrors onMessage); the live dispatch below+ // is today's contract and stays.+ const mayPersist =+ resolveFeatureFlags(this.configService).storeEphemeralMessages ||+ !(outgoing.ephemeralDuration && outgoing.ephemeralDuration > 0);++ if (mayPersist) {+ const dbMessage = this.messageRepository.create({+ sessionId: id,+ waMessageId: storableWaMessageId(outgoing.id),+ chatId: outgoing.chatId,+ from: outgoing.from,+ to: outgoing.to,+ body: outgoing.body,+ type: outgoing.type,+ direction: MessageDirection.OUTGOING,+ timestamp: outgoing.timestamp,+ status: MessageStatus.SENT,+ metadata,+ });+ // The hook chain above is async; a delete()/teardown can retire this engine while it+ // awaits. Re-check liveness so a late continuation can't persist an orphan row+ // (mirrors onMessage).+ if (!this.engines.isLive(id, engine)) return;+ // A unique violation means the REST send path already persisted this API-originated+ // send: the dedup oracle working as intended, not an error. Any other failure (after the+ // one transient retry) fails open, so a real send is never dropped on a DB fault.+ const outcome = await this.insertWithRetry(id, engine, dbMessage, 'outgoing');+ if (outcome.landed === 'stale') return;+ // The first attempt may have committed before its error: that row still takes what arrived.+ if (outcome.landed === 'dup' && outcome.retried) this.applyChangesMadeInFlight(id, outgoing.id);+ if (outcome.landed === 'yes') {+ this.applyChangesMadeInFlight(id, outgoing.id);+ // Fire-and-forget, mirroring onMessage: plugin providers (search etc.) see phone-+ // composed sends exactly like API sends.+ void this.hookManager+ .execute(+ 'message:persisted',+ { sessionId: id, message: dbMessage },+ { sessionId: id, source: 'SessionService' },+ )+ .catch(() => undefined);++ // Archive this send's media, mirroring onMessage. This is the ONLY path a phone-composed+ // send takes, so the REST-side chokepoint would never see it. Opt-in twice over+ // (CHAT_MEDIA_ARCHIVE_ENABLED + _OUTBOUND) and a no-op otherwise; archive() itself+ // refuses a row that is already archived, so the REST writer racing us costs nothing.+ if (this.configService?.get<boolean>('chatMedia.archiveOutbound', false) === true) {+ void this.chatMediaArchive?.archive(dbMessage).catch(() => undefined);}+ }+ }- void this.webhookService.dispatch(id, 'message.sent', finalMessage);- // Emit real-time event to WebSocket clients (as message.sent, not message.received)- this.eventsGateway.emitMessageSent(id, finalMessage);- })- .catch(err => this.logger.error(`onMessageCreate handler failed for ${id}`, String(err)));+ void this.webhookService.dispatch(id, 'message.sent', finalMessage);+ // Emit real-time event to WebSocket clients (as message.sent, not message.received)+ this.eventsGateway.emitMessageSent(id, finalMessage);}/** Engine callback body, lifted out of initializeEngine so the wiring table stays readable. */@@ -596,16 +700,13 @@ export class MessageProjector {// fire-and-forget writes race-safe at the DB level.const messageStatus = deliveryStatusToMessageStatus(status);if (messageStatus) {- // Scope by sessionId: waMessageId is unique per account/chat, not global — an ack on one- // session must never advance a same-id row in another session. The In() guard makes the- // UPDATE forward-only (a late/out-of-order ack can't downgrade) and idempotent on retry.- const advanceAck = (): Promise<number> =>- this.messageRepository- .update(- { sessionId: id, waMessageId: messageId, status: In(ackStatusTransitionFrom(messageStatus)) },- { status: messageStatus },- )- .then(result => result.affected ?? 0);+ // A message not written yet (its commit waits behind an earlier one of the chat) keeps the+ // furthest ack for when its row lands; the UPDATEs below would match nothing.+ const inFlight = this.inboundInFlight.get(`${id}:${messageId}`);+ if (inFlight && (!inFlight.ackStatus || ackStatusTransitionFrom(messageStatus).includes(inFlight.ackStatus))) {+ inFlight.ackStatus = messageStatus;+ }+ const advanceAck = (): Promise<number> => this.advanceAck(id, messageId, messageStatus);const logNoop = (): void =>this.logger.debug(`Message ack ${messageId}: no status row advanced to ${messageStatus} (${status})`, {@@ -668,6 +769,21 @@ export class MessageProjector {);}+ /**+ * Advance a stored message's delivery status, returning the rows changed. Scoped by sessionId:+ * waMessageId is unique per account/chat, not global, so an ack on one session must never advance a+ * same-id row in another session. The In() guard makes the UPDATE forward-only (a late/out-of-order+ * ack can't downgrade) and idempotent on retry.+ */+ private advanceAck(id: string, messageId: string, messageStatus: MessageStatus): Promise<number> {+ return this.messageRepository+ .update(+ { sessionId: id, waMessageId: messageId, status: In(ackStatusTransitionFrom(messageStatus)) },+ { status: messageStatus },+ )+ .then(result => result.affected ?? 0);+ }+/** Engine callback body, lifted out of initializeEngine so the wiring table stays readable. */handleMessageRevoked(id: string, engine: IWhatsAppEngine, message: RevokedMessage): void {if (!this.engines.isLive(id, engine)) return;@@ -709,6 +825,9 @@ export class MessageProjector {/** Reaction apply, queued on the per-message mutation chain — see MessageMutationProjector. */applyReactionQueued(id: string, event: ReactionEvent): void {+ // A message not written yet keeps the reaction for its row; the live event still goes out now.+ const inFlight = event.messageId ? this.inboundInFlight.get(`${id}:${event.messageId}`) : undefined;+ if (inFlight) (inFlight.reactions ??= {})[event.senderId] = event.reaction ?? '';this.mutationProjector.applyReactionQueued(id, event);}