Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(baileys): report an ack merged into an own upsert

Yudhi Armyndharis1a5fcae06ff5
diff --git a/src/engine/adapters/baileys-events.spec.ts b/src/engine/adapters/baileys-events.spec.ts
index 94513f677..a85d20691 100644
--- a/src/engine/adapters/baileys-events.spec.ts
+++ b/src/engine/adapters/baileys-events.spec.ts
@@ -827,6 +827,135 @@ describe('BaileysEvents.handleMessagesUpsert receipts merged into the upsert', (
});
});
+// The same buffer merges a 1:1 delivery or read ack that lands within about 100 ms of a message's own upsert
+// into that upsert as `status`, and raises no messages.update for it, and so does a rejection by the server
+// (status ERROR). An echo carries PENDING and a message the phone typed carries SERVER_ACK before any ack.
+describe('BaileysEvents.handleMessagesUpsert acks merged into the upsert', () => {
+ const partner = '[email protected]';
+ const group = '[email protected]';
+ const flush = (): Promise<void> => new Promise(resolve => setImmediate(resolve));
+ const settle = async (): Promise<void> => {
+ for (let i = 0; i < 8; i++) await flush();
+ };
+ const upsert = (
+ status: number | null | undefined,
+ over: { fromMe?: boolean; remoteJid?: string } = {},
+ ): Parameters<BaileysEvents['handleMessagesUpsert']>[0] => ({
+ type: 'append',
+ messages: [
+ {
+ key: { id: 'OUT1', remoteJid: over.remoteJid ?? partner, fromMe: over.fromMe ?? true },
+ messageTimestamp: 1_700_000_000,
+ message: { conversation: 'hi' },
+ ...(status === undefined ? {} : { status }),
+ },
+ ],
+ });
+
+ it.each([
+ [3, 'delivered'],
+ [4, 'read'],
+ [5, 'read'],
+ [0, 'failed'],
+ ])(
+ 'reports status %i of the echo of a message this session sent as %s, and still skips the echo',
+ async (status, expected) => {
+ const onMessageAck = jest.fn();
+ const onMessageCreate = jest.fn();
+ const events = new BaileysEvents(
+ makeHost({
+ getOnMessageAck: () => onMessageAck,
+ getOnMessageCreate: () => onMessageCreate,
+ consumeOwnSend: id => id === 'OUT1',
+ }),
+ );
+
+ events.handleMessagesUpsert(upsert(status));
+ await settle();
+
+ expect(onMessageAck).toHaveBeenCalledTimes(1);
+ expect(onMessageAck).toHaveBeenCalledWith('OUT1', expected, partner);
+ expect(onMessageCreate).not.toHaveBeenCalled();
+ },
+ );
+
+ it.each([
+ ['PENDING, which every echo carries', upsert(1), true],
+ ['SERVER_ACK, which a message typed on the phone carries', upsert(2), false],
+ ['no status', upsert(undefined), true],
+ ['a null status', upsert(null), true],
+ ['a delivery status on a message the account did not send', upsert(3, { fromMe: false }), false],
+ ['a delivery status on a group message, which is reported as receipts', upsert(3, { remoteJid: group }), true],
+ ])('reports no ack for %s', async (_label, event, echo) => {
+ const onMessageAck = jest.fn();
+ const events = new BaileysEvents(makeHost({ getOnMessageAck: () => onMessageAck, consumeOwnSend: () => echo }));
+
+ events.handleMessagesUpsert(event);
+ await settle();
+
+ expect(onMessageAck).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ['a group', group],
+ ['a status post', 'status@broadcast'],
+ ])('reports a rejection by the server merged into the echo of a message sent to %s', async (_label, remoteJid) => {
+ const onMessageAck = jest.fn();
+ const events = new BaileysEvents(makeHost({ getOnMessageAck: () => onMessageAck, consumeOwnSend: () => true }));
+
+ events.handleMessagesUpsert(upsert(0, { remoteJid }));
+ await settle();
+
+ expect(onMessageAck).toHaveBeenCalledWith('OUT1', 'failed', remoteJid);
+ });
+
+ it('holds the ack of a message the phone sent while the gateway was down until that message was handed on', async () => {
+ const order: string[] = [];
+ let release!: () => void;
+ const held = new Promise<undefined>(resolve => (release = () => resolve(undefined)));
+ const events = new BaileysEvents(
+ makeHost({
+ // The repeat-delivery check is the first thing processing waits for.
+ getStoredMessage: () => held as unknown as ReturnType<BaileysEventsHost['getStoredMessage']>,
+ getOnMessageCreate: () => () => {
+ order.push('created');
+ },
+ getOnMessageAck: () => (id, status) => {
+ order.push(`ack ${id} ${status}`);
+ },
+ }),
+ );
+
+ events.handleMessagesUpsert(upsert(3));
+ await settle();
+ expect(order).toEqual([]);
+
+ release();
+ await settle();
+
+ expect(order).toEqual(['created', 'ack OUT1 delivered']);
+ });
+
+ it('still reports the ack of a replayed message that is processed no further', async () => {
+ const onMessageAck = jest.fn();
+ const onMessageCreate = jest.fn();
+ const events = new BaileysEvents(
+ makeHost({
+ getStoredMessage: () =>
+ ({ key: { id: 'OUT1' } }) as unknown as ReturnType<BaileysEventsHost['getStoredMessage']>,
+ getOnMessageAck: () => onMessageAck,
+ getOnMessageCreate: () => onMessageCreate,
+ }),
+ );
+
+ events.handleMessagesUpsert(upsert(4));
+ await settle();
+
+ expect(onMessageCreate).not.toHaveBeenCalled();
+ expect(onMessageAck).toHaveBeenCalledWith('OUT1', 'read', partner);
+ });
+});
+
describe('BaileysEvents record of conflicting copies removed', () => {
it('forgets the id removed longest ago once it holds its limit', async () => {
const limit = BaileysEvents.DELETED_FOR_EVERYONE_LIMIT;
diff --git a/src/engine/adapters/baileys-events.ts b/src/engine/adapters/baileys-events.ts
index b3cdf3534..4a91c9583 100644
--- a/src/engine/adapters/baileys-events.ts
+++ b/src/engine/adapters/baileys-events.ts
@@ -451,6 +451,10 @@ export class BaileysEvents {
if (msg.userReceipt?.length) {
this.handleMessageReceiptUpdate(msg.userReceipt.map(receipt => ({ key: msg.key, receipt })));
}
+ // The same buffer merges a 1:1 delivery or read ack, or a rejection by the server, into the upsert as
+ // `status` and raises no messages.update. What a message carries before any ack (PENDING on an echo,
+ // SERVER_ACK on one the phone typed) maps to pending or sent and is not one.
+ const mergedAck = this.mergedAck(msg);
// Baileys echoes every message this session sends through the API back through this same
// path, tagged 'append', and sendContent() already emits onMessageCreate for those via
// emitOwnSendEcho(). WhatsApp replays what the account typed on its phone while the gateway
@@ -473,6 +477,9 @@ export class BaileysEvents {
// insert oracle both absorb; a loss is not recoverable, because Baileys acks the node before
// it emits the upsert.
if (msg.key.fromMe === true && this.host.consumeOwnSend(msg.key.id)) {
+ // The send returned about 100 ms ago (the buffer holds the upsert that long), so the message
+ // already has its row, or its entry in the projector.
+ if (mergedAck) this.handleMessagesUpdate([mergedAck]);
this.host.logger.debug('Skipping the echo of a message this session sent', {
msgId: msg.key.id ?? 'unknown',
type: event.type,
@@ -520,6 +527,9 @@ export class BaileysEvents {
// The room stays held until the processing settles too, and a message never emitted drops its turn.
ticket?.holdUntil(processed);
void processed.finally(() => ticket?.drop());
+ // A message the phone typed is created by that processing, and an ack that reached the projector
+ // first would find nothing to advance, so it waits until the message was handed on.
+ if (mergedAck) void processed.then(() => this.handleMessagesUpdate([mergedAck]));
const id = msg.key.id;
if (id) {
// A repeat delivery can arrive while the first is still downloading and finish before it, so
@@ -542,6 +552,18 @@ export class BaileysEvents {
}
}
+ /** The ack Baileys' event buffer merged into the upsert of a message the account sent, as an update. */
+ private mergedAck(msg: WAMessage): BaileysMessageUpdate | undefined {
+ if (msg.key.fromMe !== true) return undefined;
+ const status = mapBaileysStatus(msg.status);
+ // A delivery or read ack is a 1:1 event (groups and statuses report receipts instead); the server
+ // rejecting a message is reported for every kind of chat.
+ const reported =
+ status === 'failed' ||
+ ((status === 'delivered' || status === 'read') && chatKind(msg.key.remoteJid!) === 'individual');
+ return reported ? { key: msg.key, update: { status: msg.status } } : undefined;
+ }
+
/**
* Whether two keys of one id provably name different messages: another chat, another side of the
* conversation, or (outside the account's own messages) another sender. Fails open, like
diff --git a/src/modules/session/message-projector.merged-ack.spec.ts b/src/modules/session/message-projector.merged-ack.spec.ts
new file mode 100644
index 000000000..5b9a1a7d8
--- /dev/null
+++ b/src/modules/session/message-projector.merged-ack.spec.ts
@@ -0,0 +1,294 @@
+import { randomUUID } from 'crypto';
+import { DataSource, type Repository } from 'typeorm';
+import type { WAMessage, WASocket } from '@whiskeysockets/baileys';
+import { BaileysEvents, type BaileysEventsHost } from '../../engine/adapters/baileys-events';
+import { createLogger } from '../../common/services/logger.service';
+import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
+import { EngineRegistry } from '../../engine/engine-registry.service';
+import type { IncomingMessage, IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
+import { Message, MessageDirection, MessageStatus } from '../message/entities/message.entity';
+import { Session } from './entities/session.entity';
+import { ACK_RECONCILE_DELAY_MS, MessageProjector } from './message-projector.service';
+import type { EventsGateway } from '../events/events.gateway';
+import type { WebhookService } from '../webhook/webhook.service';
+import type { HookManager } from '../../core/hooks';
+import type { StatusStoreService } from '../status-store/status-store.service';
+import type { SessionLidResolver } from './session-lid-resolver.service';
+
+/**
+ * Baileys' event buffer merges a 1:1 ack that lands within about 100 ms of a message's own upsert into that
+ * upsert, as `status` (and `messageTimestamp`), and raises no messages.update for it. This runs the adapter's
+ * upsert handler against the real projector and a real database (SQLite here, the postgres:16 service when
+ * DATABASE_TYPE=postgres) to show that the stored status advances for the two kinds of message that can carry
+ * one: the echo of an API send, and a message the phone typed while the gateway was down.
+ */
+
+const SESSION = 's1';
+const CHAT = '[email protected]';
+const SELF = '[email protected]';
+
+type Pending = { promise: Promise<void>; release: () => void };
+const gate = (): Pending => {
+ let release!: () => void;
+ const promise = new Promise<void>(resolve => (release = resolve));
+ return { promise, release };
+};
+const pause = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+const settle = async (): Promise<void> => {
+ for (let i = 0; i < 10; i++) await new Promise(resolve => setImmediate(resolve));
+};
+/** Polls until `read` answers `expected` or two seconds pass; a PostgreSQL write takes real time to land. */
+const eventually = async <T>(read: () => Promise<T>, expected: T): Promise<T> => {
+ let last = await read();
+ for (const start = Date.now(); last !== expected && Date.now() - start < 2000;) {
+ await pause(20);
+ last = await read();
+ }
+ return last;
+};
+
+// Only what processing a plain text message reads from the library.
+const libStub = {
+ normalizeMessageContent: (content: unknown) => content,
+ extractMessageContent: (content: unknown) => content,
+ getContentType: (content: Record<string, unknown> | undefined) =>
+ Object.keys(content ?? {}).find(k => k === 'conversation' || k.endsWith('Message')),
+} as unknown as Awaited<ReturnType<BaileysEventsHost['loadLib']>>;
+
+describe('an ack merged into a message upsert reaches the stored row', () => {
+ let db: DataSource;
+ let repo: Repository<Message>;
+ let projector: MessageProjector;
+ let events: BaileysEvents;
+ let ownSends: Set<string>;
+ let hookGate: Promise<void> | undefined;
+ let storedReadGate: Promise<void> | undefined;
+ let retries: Array<ReturnType<typeof setTimeout>>;
+ const engine = { tag: 'merged-ack' } as unknown as IWhatsAppEngine;
+
+ beforeEach(async () => {
+ // The projector retries an ack that found no row once, after ACK_RECONCILE_DELAY_MS. Kept so a test that
+ // has ended cannot fire it into the database the next test has replaced.
+ retries = [];
+ const realSetTimeout = global.setTimeout;
+ jest.spyOn(global, 'setTimeout').mockImplementation((fn: () => void, ms?: number) => {
+ const timer = realSetTimeout(fn, ms);
+ if (ms === ACK_RECONCILE_DELAY_MS) retries.push(timer);
+ return timer;
+ });
+ db = new DataSource(
+ process.env.DATABASE_TYPE === 'postgres'
+ ? {
+ type: 'postgres',
+ host: process.env.DATABASE_HOST || 'localhost',
+ port: Number(process.env.DATABASE_PORT || 5432),
+ username: process.env.DATABASE_USERNAME || 'openwa',
+ password: process.env.DATABASE_PASSWORD || 'openwa',
+ database: process.env.DATABASE_NAME || 'openwa',
+ schema: `merged_ack_${randomUUID().replace(/-/g, '')}`,
+ entities: [Session, Message],
+ synchronize: false,
+ }
+ : { type: 'better-sqlite3', database: ':memory:', entities: [Session, Message], synchronize: true },
+ );
+ await db.initialize();
+ if (db.options.type === 'postgres') {
+ await db.query(`CREATE SCHEMA "${db.options.schema}"`);
+ await db.synchronize();
+ }
+ repo = db.getRepository(Message);
+ hookGate = undefined;
+ storedReadGate = undefined;
+ ownSends = new Set();
+
+ const engines = new EngineRegistry();
+ engines.set(SESSION, engine);
+ projector = new MessageProjector(
+ repo,
+ { update: jest.fn().mockResolvedValue({ affected: 1 }) } as unknown as Repository<Session>,
+ engines,
+ {
+ emitMessage: jest.fn(),
+ emitMessageSent: jest.fn(),
+ emitMessageAck: jest.fn(),
+ } as unknown as EventsGateway,
+ { dispatch: jest.fn().mockResolvedValue(undefined) } as unknown as WebhookService,
+ {
+ // A slow hook chain holds the commit of a message, as a plugin on message:sent can.
+ execute: jest.fn(async (_event: string, data: unknown) => {
+ await hookGate;
+ return { continue: true, data };
+ }),
+ } as unknown as HookManager,
+ { ingest: jest.fn() } as unknown as StatusStoreService,
+ { resolveSenderPhone: jest.fn().mockResolvedValue(null) } as unknown as SessionLidResolver,
+ );
+
+ const noop = (): void => undefined;
+ const host: BaileysEventsHost = {
+ getSocket: () => ({ updateMediaMessage: jest.fn() }) as unknown as WASocket,
+ getSocketOrNull: () => null,
+ logger: createLogger('MergedAckSpec'),
+ loadLib: () => Promise.resolve(libStub),
+ getFetchDispatcher: () => undefined,
+ toNeutralJid: (jid: string) => jid,
+ normalizedSelfJid: () => SELF,
+ inboundLimiter: new ConcurrencyLimiter(2),
+ recordKeyLidMappings: noop,
+ recordMessage: noop,
+ recordMessageEdit: noop,
+ consumeOwnSend: id => (id ? ownSends.delete(id) : false),
+ getStoredMessage: async () => {
+ await storedReadGate;
+ return null;
+ },
+ putStoredMessage: () => undefined,
+ updateStoredMessage: () => undefined,
+ removeStoredMessage: () => undefined,
+ getOnMessage: () => undefined,
+ getOnMessageCreate: () => (message, ticket) => projector.handleOwnSendEcho(SESSION, engine, message, ticket),
+ getOnMessageRevoked: () => undefined,
+ getOnMessageEdited: () => undefined,
+ getOnMessageReaction: () => undefined,
+ getOnMessageAck: () => (id, status, chatId) => projector.handleMessageAck(SESSION, engine, id, status, chatId),
+ getOnMessageReceipt: () => undefined,
+ getOnGroupEvent: () => undefined,
+ getOnEventResponse: () => undefined,
+ findContact: () => null,
+ getOnCall: () => undefined,
+ getOnPresenceUpdate: () => undefined,
+ getOnCallOutcome: () => undefined,
+ // As the session wiring installs it: PostgreSQL only.
+ getAdmitInbound: () => (projector.holdsInbound ? a => projector.admitInbound(SESSION, engine, a) : undefined),
+ };
+ events = new BaileysEvents(host);
+ });
+
+ afterEach(async () => {
+ retries.forEach(timer => clearTimeout(timer));
+ jest.restoreAllMocks();
+ if (db.options.type === 'postgres') await db.query(`DROP SCHEMA IF EXISTS "${String(db.options.schema)}" CASCADE`);
+ await db.destroy();
+ });
+
+ /** As the event buffer leaves an upsert after an ack was merged into it (Object.assign of the update). */
+ const mergedUpsert = (id: string, fromMe: boolean, status: number): { messages: WAMessage[]; type: string } => ({
+ type: 'append',
+ messages: [
+ {
+ key: { id, remoteJid: CHAT, fromMe },
+ message: { conversation: 'hi' },
+ // The ack's own time replaces the message's.
+ messageTimestamp: 1_700_000_100,
+ status,
+ },
+ ],
+ });
+
+ const statusOf = async (id: string): Promise<MessageStatus | undefined> =>
+ (await repo.findOne({ where: { sessionId: SESSION, waMessageId: id } }))?.status;
+
+ /** The row the REST send leaves once the engine accepted the message. */
+ const sentRow = (id: string): Promise<Message> =>
+ repo.save(
+ repo.create({
+ sessionId: SESSION,
+ waMessageId: id,
+ chatId: CHAT,
+ from: 'me',
+ to: CHAT,
+ body: 'hi',
+ type: 'text',
+ direction: MessageDirection.OUTGOING,
+ timestamp: 1_700_000_000,
+ status: MessageStatus.SENT,
+ }),
+ );
+
+ /** The neutral message the adapter hands the projector for its own send. */
+ const echoOf = (id: string): IncomingMessage => ({
+ id,
+ chatId: CHAT,
+ from: SELF,
+ to: CHAT,
+ body: 'hi',
+ type: 'text',
+ timestamp: 1_700_000_000,
+ fromMe: true,
+ isGroup: false,
+ kind: 'individual',
+ });
+
+ it.each([
+ [3, MessageStatus.DELIVERED],
+ [4, MessageStatus.READ],
+ ])('advances the row of an API send when status %i is merged into its echo', async (status, expected) => {
+ await sentRow('API1');
+ ownSends.add('API1');
+
+ events.handleMessagesUpsert(mergedUpsert('API1', true, status));
+ await settle();
+
+ expect(await eventually(() => statusOf('API1'), expected)).toBe(expected);
+ });
+
+ it('advances an API send whose echo row is still waiting behind a slow hook when the ack arrives', async () => {
+ const slow = gate();
+ hookGate = slow.promise;
+ ownSends.add('API2');
+ // What emitOwnSendEcho hands the projector right after the send; its row is not written yet.
+ projector.handleOwnSendEcho(SESSION, engine, echoOf('API2'));
+
+ events.handleMessagesUpsert(mergedUpsert('API2', true, 3));
+ await settle();
+ expect(await statusOf('API2')).toBeUndefined();
+
+ slow.release();
+ await settle();
+
+ expect(await eventually(() => statusOf('API2'), MessageStatus.DELIVERED)).toBe(MessageStatus.DELIVERED);
+ });
+
+ it('marks an API send failed when the server rejection is merged into its echo', async () => {
+ await sentRow('API3');
+ ownSends.add('API3');
+
+ events.handleMessagesUpsert(mergedUpsert('API3', true, 0));
+ await settle();
+
+ expect(await eventually(() => statusOf('API3'), MessageStatus.FAILED)).toBe(MessageStatus.FAILED);
+ });
+
+ it('creates a message the phone typed offline and advances it, however long its processing takes', async () => {
+ // Longer than the one retry the projector gives an ack that found no row.
+ const slow = gate();
+ storedReadGate = slow.promise;
+
+ events.handleMessagesUpsert(mergedUpsert('PHONE1', true, 4));
+ await pause(ACK_RECONCILE_DELAY_MS + 150);
+ slow.release();
+ await settle();
+
+ expect(await eventually(() => statusOf('PHONE1'), MessageStatus.READ)).toBe(MessageStatus.READ);
+ });
+
+ it('creates a message the phone typed offline and advances it when its hook chain is slow', async () => {
+ const slow = gate();
+ hookGate = slow.promise;
+
+ events.handleMessagesUpsert(mergedUpsert('PHONE2', true, 3));
+ await pause(ACK_RECONCILE_DELAY_MS + 150);
+ expect(await statusOf('PHONE2')).toBeUndefined();
+ slow.release();
+ await settle();
+
+ expect(await eventually(() => statusOf('PHONE2'), MessageStatus.DELIVERED)).toBe(MessageStatus.DELIVERED);
+ });
+
+ it('leaves a message the phone typed at sent when it carries no ack', async () => {
+ events.handleMessagesUpsert(mergedUpsert('PHONE3', true, 2));
+ await settle();
+
+ expect(await eventually(() => statusOf('PHONE3'), MessageStatus.SENT)).toBe(MessageStatus.SENT);
+ });
+});