Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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-circuited
re-entry only). Plugins never call `HookManager` directly — they use `ctx.registerHook(...)`, which
also 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 that
diff --git a/src/modules/session/message-projector.service.spec.ts b/src/modules/session/message-projector.service.spec.ts
index 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.ts
index 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);
}