Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(messaging): preserve deferred session operations

Yudhi Armyndharis626c5ddde634
diff --git a/src/common/utils/session-write-scope.spec.ts b/src/common/utils/session-write-scope.spec.ts
new file mode 100644
index 000000000..abed09f02
--- /dev/null
+++ b/src/common/utils/session-write-scope.spec.ts
@@ -0,0 +1,137 @@
+import { captureSessionWrites, closeSessionWrites } from './session-write-scope';
+
+function pause() {
+ let resume!: () => void;
+ const promise = new Promise<void>(resolve => {
+ resume = resolve;
+ });
+ return { promise, resume };
+}
+
+describe('Session write lifetimes', () => {
+ it('notifies retirement synchronously after closing write admission', () => {
+ const source = {};
+ const lifetime = captureSessionWrites(source, 'session');
+ const notified = jest.fn(() => {
+ expect(() => lifetime.assertCurrent()).toThrow('no longer available');
+ });
+ lifetime.onRetire(notified);
+
+ const deletion = closeSessionWrites(source, 'session');
+
+ expect(notified).toHaveBeenCalledTimes(1);
+ deletion.release();
+ lifetime.close();
+ });
+
+ it('immediately notifies a subscription registered after its generation retired', () => {
+ const source = {};
+ const lifetime = captureSessionWrites(source, 'session');
+ const deletion = closeSessionWrites(source, 'session');
+ deletion.release();
+ const notified = jest.fn();
+
+ lifetime.onRetire(notified);
+
+ expect(notified).toHaveBeenCalledTimes(1);
+ lifetime.close();
+ });
+
+ it('removes subscriptions when disposed or their scope closes', () => {
+ const source = {};
+ const disposed = captureSessionWrites(source, 'session');
+ const closed = captureSessionWrites(source, 'session');
+ const notified = jest.fn();
+ const dispose = disposed.onRetire(notified);
+ closed.onRetire(notified);
+ dispose();
+ dispose();
+ closed.close();
+
+ const deletion = closeSessionWrites(source, 'session');
+
+ expect(notified).not.toHaveBeenCalled();
+ deletion.release();
+ disposed.close();
+ });
+
+ it('continues retirement after a subscriber throws and never notifies it again', () => {
+ const source = {};
+ const lifetime = captureSessionWrites(source, 'session');
+ const throwing = jest.fn(() => {
+ throw new Error('cleanup failed');
+ });
+ const notified = jest.fn();
+ lifetime.onRetire(throwing);
+ lifetime.onRetire(notified);
+
+ const deletion = closeSessionWrites(source, 'session');
+ expect(throwing).toHaveBeenCalledTimes(1);
+ expect(notified).toHaveBeenCalledTimes(1);
+ deletion.release();
+ const nextDeletion = closeSessionWrites(source, 'session');
+ expect(throwing).toHaveBeenCalledTimes(1);
+ expect(notified).toHaveBeenCalledTimes(1);
+ nextDeletion.release();
+ lifetime.close();
+ });
+
+ it('keeps pending database work visible to a retried deletion', async () => {
+ const source = {};
+ const pending = pause();
+ const lifetime = captureSessionWrites(source, 'session');
+ const write = lifetime.write(() => pending.promise);
+ const firstDelete = closeSessionWrites(source, 'session');
+ firstDelete.release();
+ const retry = closeSessionWrites(source, 'session');
+ let drained = false;
+ const drainedWrite = retry.drain().then(() => {
+ drained = true;
+ });
+ await new Promise<void>(setImmediate);
+ expect(drained).toBe(false);
+ pending.resume();
+ await Promise.all([write, drainedWrite]);
+ retry.release();
+ lifetime.close();
+ });
+
+ it('opens fresh admission after a failed deletion without reviving an older lifetime', async () => {
+ const source = {};
+ const old = captureSessionWrites(source, 'session');
+ const deletion = closeSessionWrites(source, 'session');
+ await deletion.drain();
+ deletion.release();
+ const current = captureSessionWrites(source, 'session');
+ await expect(old.write(() => Promise.resolve('old'))).rejects.toThrow('no longer available');
+ await expect(current.write(() => Promise.resolve('current'))).resolves.toBe('current');
+ current.close();
+ old.close();
+ });
+
+ it('does not reopen admission until overlapping deletions both release', async () => {
+ const source = {};
+ const first = closeSessionWrites(source, 'session');
+ const second = closeSessionWrites(source, 'session');
+ first.release();
+ const blocked = captureSessionWrites(source, 'session');
+ await expect(blocked.write(() => Promise.resolve('blocked'))).rejects.toThrow('no longer available');
+ second.release();
+ const current = captureSessionWrites(source, 'session');
+ await expect(current.write(() => Promise.resolve('current'))).resolves.toBe('current');
+ blocked.close();
+ current.close();
+ });
+
+ it('isolates data sources and session ids', async () => {
+ const source = {};
+ const deletion = closeSessionWrites(source, 'session');
+ const otherSession = captureSessionWrites(source, 'other');
+ const otherSource = captureSessionWrites({}, 'session');
+ await expect(otherSession.write(() => Promise.resolve(1))).resolves.toBe(1);
+ await expect(otherSource.write(() => Promise.resolve(2))).resolves.toBe(2);
+ deletion.release();
+ otherSession.close();
+ otherSource.close();
+ });
+});
diff --git a/src/common/utils/session-write-scope.ts b/src/common/utils/session-write-scope.ts
new file mode 100644
index 000000000..a63633dcb
--- /dev/null
+++ b/src/common/utils/session-write-scope.ts
@@ -0,0 +1,116 @@
+import { NotFoundException } from '@nestjs/common';
+
+interface WriteState {
+ captures: number;
+ closing: number;
+ generation: { retired: boolean; listeners: Set<() => void> };
+ writes: Set<Promise<unknown>>;
+}
+
+const sources = new WeakMap<object, Map<string, WriteState>>();
+
+function stateFor(source: object, sessionId: string): [Map<string, WriteState>, WriteState] {
+ let sessions = sources.get(source);
+ if (!sessions) sources.set(source, (sessions = new Map<string, WriteState>()));
+ let state = sessions.get(sessionId);
+ if (!state) {
+ state = { captures: 0, closing: 0, generation: { retired: false, listeners: new Set() }, writes: new Set() };
+ sessions.set(sessionId, state);
+ }
+ return [sessions, state];
+}
+
+function releaseIdle(sessions: Map<string, WriteState>, sessionId: string, state: WriteState): void {
+ if (!state.captures && !state.closing && !state.writes.size && sessions.get(sessionId) === state) {
+ sessions.delete(sessionId);
+ }
+}
+
+export interface SessionWriteScope {
+ assertCurrent(): void;
+ /** Release preparation resources immediately on retirement; close() also disposes the subscription. */
+ onRetire(listener: () => void): () => void;
+ write<T>(operation: () => Promise<T>): Promise<T>;
+ close(): void;
+}
+
+/** Captures a lifetime without holding deletion across network or storage waits. */
+export function captureSessionWrites(source: object, sessionId: string): SessionWriteScope {
+ const [sessions, state] = stateFor(source, sessionId);
+ const generation = state.generation;
+ state.captures++;
+ let closed = false;
+ const subscriptions = new Set<() => void>();
+ const assertCurrent = (): void => {
+ if (closed || generation.retired || state.closing || sessions.get(sessionId) !== state) {
+ throw new NotFoundException(`Session '${sessionId}' is no longer available`);
+ }
+ };
+ return {
+ assertCurrent,
+ onRetire(listener: () => void): () => void {
+ if (closed || generation.retired || state.closing || sessions.get(sessionId) !== state) {
+ listener();
+ return () => undefined;
+ }
+ const dispose = (): void => {
+ generation.listeners.delete(notify);
+ subscriptions.delete(dispose);
+ };
+ const notify = (): void => {
+ dispose();
+ listener();
+ };
+ generation.listeners.add(notify);
+ subscriptions.add(dispose);
+ return dispose;
+ },
+ async write<T>(operation: () => Promise<T>): Promise<T> {
+ assertCurrent();
+ const pending = Promise.resolve().then(operation);
+ state.writes.add(pending);
+ try {
+ return await pending;
+ } finally {
+ state.writes.delete(pending);
+ releaseIdle(sessions, sessionId, state);
+ }
+ },
+ close(): void {
+ if (closed) return;
+ closed = true;
+ for (const dispose of subscriptions) dispose();
+ state.captures--;
+ releaseIdle(sessions, sessionId, state);
+ },
+ };
+}
+
+/** Close admission synchronously; drain only database operations before deleting their parent. */
+export function closeSessionWrites(source: object, sessionId: string): { drain(): Promise<void>; release(): void } {
+ const [sessions, state] = stateFor(source, sessionId);
+ state.closing++;
+ state.generation.retired = true;
+ for (const notify of state.generation.listeners) {
+ try {
+ notify();
+ } catch {
+ // A preparation cleanup failure must not prevent session deletion or other notifications.
+ }
+ }
+ state.generation.listeners.clear();
+ let released = false;
+ return {
+ async drain(): Promise<void> {
+ await Promise.allSettled([...state.writes]);
+ },
+ release(): void {
+ if (released) return;
+ released = true;
+ state.closing--;
+ // A retry must still drain older writes; only the captured generation is retired.
+ if (!state.closing) state.generation = { retired: false, listeners: new Set() };
+ releaseIdle(sessions, sessionId, state);
+ },
+ };
+}
diff --git a/src/modules/chat-media/chat-media-archive.service.spec.ts b/src/modules/chat-media/chat-media-archive.service.spec.ts
index 8f28b733c..a812974d4 100644
--- a/src/modules/chat-media/chat-media-archive.service.spec.ts
+++ b/src/modules/chat-media/chat-media-archive.service.spec.ts
@@ -191,7 +191,15 @@ describe('ChatMediaArchiveService', () => {
{ assertSendAllowed: () => Promise.resolve(), recordSendSuccess: () => undefined } as never,
fakeConfigService({ 'features.simulateTyping': false }),
);
- jest.spyOn(repository, 'update').mockRejectedValueOnce(new Error('SQLITE_BUSY'));
+ const update = repository.update.bind(repository);
+ let mergeFailed = false;
+ jest.spyOn(repository, 'update').mockImplementation((where, patch) => {
+ if (!mergeFailed && patch.metadata && typeof where === 'object' && where !== null && 'waMessageId' in where) {
+ mergeFailed = true;
+ return Promise.reject(new Error('SQLITE_BUSY'));
+ }
+ return update(where, patch);
+ });
const media = { mimetype: 'image/png', data: PNG.toString('base64') };
if (mode === 'bulk') {
await sender.saveOutgoingMessage('sess-1', {
@@ -204,6 +212,7 @@ describe('ChatMediaArchiveService', () => {
} else {
await sender.sendImage('sess-1', { chatId: row.chatId, base64: media.data, mimetype: media.mimetype });
}
+ expect(mergeFailed).toBe(true);
const retained = await repository.findOneByOrFail({ sessionId: 'sess-1', waMessageId: IsNull() });
expect(retained.status).toBe(MessageStatus.SENT);
expect(retained.metadata.media).toEqual(media);
diff --git a/src/modules/message/bulk-content-lifetime.spec.ts b/src/modules/message/bulk-content-lifetime.spec.ts
new file mode 100644
index 000000000..16f897c4e
--- /dev/null
+++ b/src/modules/message/bulk-content-lifetime.spec.ts
@@ -0,0 +1,377 @@
+import { ConfigService } from '@nestjs/config';
+import { DataSource } from 'typeorm';
+import { captureSessionWrites, closeSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
+import { HookManager } from '../../core/hooks';
+import { EngineRegistry } from '../../engine/engine-registry.service';
+import type { IWhatsAppEngine, MessageResult } from '../../engine/interfaces/whatsapp-engine.interface';
+import { Session } from '../session/entities/session.entity';
+import type { SessionService } from '../session/session.service';
+import type { TemplateService } from '../template/template.service';
+import { BulkMessageService } from './bulk-message.service';
+import { MessageSendService } from './message-send.service';
+import type { MessageService } from './message.service';
+import { MessageBatch, BatchStatus } from './entities/message-batch.entity';
+import { Message } from './entities/message.entity';
+import { SendPacingService } from './send-pacing.service';
+
+function deferred<T = void>() {
+ let resolve!: (value: T | PromiseLike<T>) => void;
+ const promise = new Promise<T>(yes => {
+ resolve = yes;
+ });
+ return { promise, resolve };
+}
+
+describe('Bulk content lifetimes', () => {
+ let db: DataSource;
+ let engines: EngineRegistry;
+ let bulk: BulkMessageService;
+ let hooks: HookManager;
+
+ beforeEach(async () => {
+ db = new DataSource({
+ type: 'better-sqlite3',
+ database: ':memory:',
+ entities: [Session, Message, MessageBatch],
+ synchronize: true,
+ });
+ await db.initialize();
+ engines = new EngineRegistry();
+ hooks = new HookManager();
+ const pacing = new SendPacingService(db.getRepository(Message), db.getRepository(Session), new ConfigService({}));
+ const sender = new MessageSendService(
+ db.getRepository(Message),
+ { findOne: (id: string) => db.getRepository(Session).findOneByOrFail({ id }) } as unknown as SessionService,
+ engines,
+ hooks,
+ {} as TemplateService,
+ pacing,
+ );
+ bulk = new BulkMessageService(
+ db.getRepository(MessageBatch),
+ engines,
+ sender as unknown as MessageService,
+ hooks,
+ pacing,
+ );
+ });
+
+ afterEach(async () => {
+ jest.restoreAllMocks();
+ await db.destroy();
+ });
+
+ async function removeSession(id: string): Promise<void> {
+ const writes = closeSessionWrites(db, id);
+ engines.delete(id);
+ try {
+ await writes.drain();
+ await db.transaction(async manager => {
+ await manager.delete(Message, { sessionId: id });
+ await manager.delete(MessageBatch, { sessionId: id });
+ await manager.delete(Session, { id });
+ });
+ } finally {
+ writes.release();
+ }
+ }
+
+ for (const [recreate, restoreBatch] of [
+ [false, false],
+ [true, false],
+ [true, true],
+ ]) {
+ it(`does not persist an old accepted item after deletion with replacement=${recreate}, restored batch=${restoreBatch}`, async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const id = session.id;
+ const started = deferred();
+ const result = deferred<MessageResult>();
+ engines.set(id, {
+ sendTextMessage: () => {
+ started.resolve();
+ return result.promise;
+ },
+ } as unknown as IWhatsAppEngine);
+ const batch = await db.getRepository(MessageBatch).save({
+ batchId: 'original-batch',
+ sessionId: id,
+ status: BatchStatus.PENDING,
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'old item' } }],
+ options: { delayBetweenMessages: 0, randomizeDelay: false, stopOnError: false },
+ progress: { total: 1, sent: 0, failed: 0, pending: 1, cancelled: 0 },
+ results: [],
+ currentIndex: 0,
+ });
+ const run = (
+ bulk as unknown as { processBatch(id: string, reserved: boolean, lifetime: SessionWriteScope): Promise<void> }
+ ).processBatch(batch.id, false, captureSessionWrites(db, id));
+ const settled = run.catch(() => undefined);
+ await started.promise;
+ await removeSession(id);
+ if (recreate) await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ if (restoreBatch) await db.getRepository(MessageBatch).save({ ...batch, status: BatchStatus.PROCESSING });
+ result.resolve({ id: 'old-result', timestamp: 1700000000 });
+ await settled;
+ expect(await db.getRepository(Message).count()).toBe(0);
+ expect(await db.getRepository(MessageBatch).count()).toBe(restoreBatch ? 1 : 0);
+ if (restoreBatch) {
+ const current = await db.getRepository(MessageBatch).findOneByOrFail({ id: batch.id });
+ expect(current.status).toBe(BatchStatus.PROCESSING);
+ expect(current.progress.sent).toBe(0);
+ expect(current.currentIndex).toBe(0);
+ }
+ });
+ }
+
+ it('does not create a batch when its session is deleted during duplicate lookup', async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const id = session.id;
+ engines.set(id, {} as IWhatsAppEngine);
+ const repo = db.getRepository(MessageBatch);
+ const find = repo.findOne.bind(repo);
+ const started = deferred();
+ const lookup = deferred();
+ jest.spyOn(repo, 'findOne').mockImplementationOnce(async options => {
+ const existing = await find(options);
+ started.resolve();
+ await lookup.promise;
+ return existing;
+ });
+ const creating = bulk.createBatch(id, {
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'old item' } }],
+ });
+ const rejected = expect(creating).rejects.toThrow('no longer available');
+ await started.promise;
+ await removeSession(id);
+ await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ lookup.resolve();
+ await rejected;
+ expect(await repo.count()).toBe(0);
+ });
+ it('does not dispatch through a replacement session after a delayed sending hook', async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const id = session.id;
+ const started = deferred();
+ const gate = deferred();
+ hooks.register('moderation', 'message:sending', async () => {
+ started.resolve();
+ await gate.promise;
+ return { continue: true };
+ });
+ let sends = 0;
+ const engine = {
+ sendTextMessage: () => {
+ sends++;
+ return Promise.resolve({ id: 'replacement-result', timestamp: 1700000000 });
+ },
+ };
+ engines.set(id, engine as unknown as IWhatsAppEngine);
+ const batch = await db.getRepository(MessageBatch).save({
+ batchId: 'original-batch',
+ sessionId: id,
+ status: BatchStatus.PENDING,
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'old item' } }],
+ options: { delayBetweenMessages: 0, randomizeDelay: false, stopOnError: false },
+ progress: { total: 1, sent: 0, failed: 0, pending: 1, cancelled: 0 },
+ results: [],
+ currentIndex: 0,
+ });
+ const run = (
+ bulk as unknown as { processBatch(id: string, reserved: boolean, lifetime: SessionWriteScope): Promise<void> }
+ ).processBatch(batch.id, false, captureSessionWrites(db, id));
+ const settled = run.catch(() => undefined);
+ await started.promise;
+ await removeSession(id);
+ await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ engines.set(id, engine as unknown as IWhatsAppEngine);
+ gate.resolve();
+ await settled;
+ expect(sends).toBe(0);
+ expect(await db.getRepository(Message).count()).toBe(0);
+ });
+
+ it('drains an admitted initial batch save before deleting session content', async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const id = session.id;
+ engines.set(id, {} as IWhatsAppEngine);
+ const repo = db.getRepository(MessageBatch);
+ const save = repo.save.bind(repo);
+ const started = deferred();
+ const saving = deferred();
+ jest.spyOn(repo, 'save').mockImplementationOnce(async (value, options) => {
+ started.resolve();
+ await saving.promise;
+ return save(value, options);
+ });
+ const creating = bulk.createBatch(id, {
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'old item' } }],
+ });
+ const created = creating.catch(() => undefined);
+ await started.promise;
+ let deleted = false;
+ const deletion = removeSession(id).then(() => {
+ deleted = true;
+ });
+ await new Promise<void>(setImmediate);
+ const deletedBeforeSave = deleted;
+ saving.resolve();
+ await Promise.all([deletion, created]);
+ await new Promise<void>(setImmediate);
+ expect(deletedBeforeSave).toBe(false);
+ expect(await repo.count()).toBe(0);
+ });
+ it('does not resume the next item through a replacement session after the batch delay', async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const id = session.id;
+ let originalSends = 0;
+ let replacementSends = 0;
+ engines.set(id, {
+ sendTextMessage: () => {
+ originalSends++;
+ return Promise.resolve({ id: 'first-result', timestamp: 1700000000 });
+ },
+ } as unknown as IWhatsAppEngine);
+ const repo = db.getRepository(MessageBatch);
+ const update = repo.update.bind(repo);
+ const firstProgress = deferred();
+ jest.spyOn(repo, 'update').mockImplementation(async (where, changes) => {
+ const updated = await update(where, changes);
+ if (changes.currentIndex === 1) firstProgress.resolve();
+ return updated;
+ });
+ const batch = await repo.save({
+ batchId: 'delayed-batch',
+ sessionId: id,
+ status: BatchStatus.PENDING,
+ messages: [
+ { chatId: '[email protected]', type: 'text', content: { text: 'first item' } },
+ { chatId: '[email protected]', type: 'text', content: { text: 'second item' } },
+ ],
+ options: { delayBetweenMessages: 500, randomizeDelay: false, stopOnError: false },
+ progress: { total: 2, sent: 0, failed: 0, pending: 2, cancelled: 0 },
+ results: [],
+ currentIndex: 0,
+ });
+ const run = (
+ bulk as unknown as { processBatch(id: string, reserved: boolean, lifetime: SessionWriteScope): Promise<void> }
+ ).processBatch(batch.id, false, captureSessionWrites(db, id));
+ const settled = run.catch(() => undefined);
+ await firstProgress.promise;
+ await new Promise<void>(setImmediate);
+ await removeSession(id);
+ await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ engines.set(id, {
+ sendTextMessage: () => {
+ replacementSends++;
+ return Promise.resolve({ id: 'second-result', timestamp: 1700000001 });
+ },
+ } as unknown as IWhatsAppEngine);
+ await settled;
+ expect(originalSends).toBe(1);
+ expect(replacementSends).toBe(0);
+ expect(await db.getRepository(Message).count()).toBe(0);
+ expect(await repo.count()).toBe(0);
+ });
+
+ for (const stage of ['pickup read', 'processing transition']) {
+ it(`does not adopt restored batch content after a pending ${stage}`, async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const id = session.id;
+ let sends = 0;
+ const engine = {
+ sendTextMessage: () => {
+ sends++;
+ return Promise.resolve({ id: 'old-result', timestamp: 1700000000 });
+ },
+ };
+ engines.set(id, engine as unknown as IWhatsAppEngine);
+ const repo = db.getRepository(MessageBatch);
+ const batch = await repo.save({
+ batchId: 'pending-pickup',
+ sessionId: id,
+ status: BatchStatus.PENDING,
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'old item' } }],
+ options: { delayBetweenMessages: 0, randomizeDelay: false, stopOnError: false },
+ progress: { total: 1, sent: 0, failed: 0, pending: 1, cancelled: 0 },
+ results: [],
+ currentIndex: 0,
+ });
+ const find = repo.findOne.bind(repo);
+ const started = deferred();
+ const pickup = deferred();
+ if (stage === 'pickup read') {
+ jest.spyOn(repo, 'findOne').mockImplementationOnce(async options => {
+ const value = await find(options);
+ started.resolve();
+ await pickup.promise;
+ return value;
+ });
+ } else {
+ const update = repo.update.bind(repo);
+ jest.spyOn(repo, 'update').mockImplementationOnce(async (where, changes) => {
+ const value = await update(where, changes);
+ started.resolve();
+ await pickup.promise;
+ return value;
+ });
+ }
+ const run = (
+ bulk as unknown as { processBatch(id: string, reserved: boolean, lifetime: SessionWriteScope): Promise<void> }
+ ).processBatch(batch.id, false, captureSessionWrites(db, id));
+ const settled = run.catch(() => undefined);
+ await started.promise;
+ let completedBeforeTransition = false;
+ if (stage === 'processing transition') {
+ let completed = false;
+ const deletion = removeSession(id).then(() => {
+ completed = true;
+ });
+ await new Promise<void>(setImmediate);
+ completedBeforeTransition = completed;
+ pickup.resolve();
+ await deletion;
+ } else await removeSession(id);
+ await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ await repo.save(batch);
+ if (stage === 'pickup read') engines.set(id, engine as unknown as IWhatsAppEngine);
+ pickup.resolve();
+ await settled;
+ expect(completedBeforeTransition).toBe(false);
+ expect(sends).toBe(0);
+ expect((await repo.findOneByOrFail({ id: batch.id })).status).toBe(BatchStatus.PENDING);
+ expect(await db.getRepository(Message).count()).toBe(0);
+ });
+ }
+ it('keeps the created batch lifetime through asynchronous pickup and accepted completion', async () => {
+ const session = await db.getRepository(Session).save({ name: 'original', config: {} });
+ const result = deferred<MessageResult>();
+ const started = deferred();
+ engines.set(session.id, {
+ sendTextMessage: () => {
+ started.resolve();
+ return result.promise;
+ },
+ } as unknown as IWhatsAppEngine);
+ const runner = bulk as unknown as {
+ processBatch(id: string, reserved: boolean, lifetime: SessionWriteScope): Promise<void>;
+ };
+ const process = runner.processBatch.bind(bulk);
+ let running!: Promise<void>;
+ jest.spyOn(runner, 'processBatch').mockImplementation((...args) => {
+ running = process(...args);
+ return running;
+ });
+ const batch = await bulk.createBatch(session.id, {
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'current item' } }],
+ });
+ await started.promise;
+ result.resolve({ id: 'accepted-result', timestamp: 1700000000 });
+ await running;
+ const stored = await db.getRepository(MessageBatch).findOneByOrFail({ id: batch.id });
+ expect(stored.status).toBe(BatchStatus.COMPLETED);
+ expect(stored.progress.sent).toBe(1);
+ expect(await db.getRepository(Message).count()).toBe(1);
+ expect((bulk as unknown as { inFlightBatches: number }).inFlightBatches).toBe(0);
+ expect((bulk as unknown as { processingBatches: Map<string, boolean> }).processingBatches.size).toBe(0);
+ });
+});
diff --git a/src/modules/message/bulk-message.service.spec.ts b/src/modules/message/bulk-message.service.spec.ts
index f9db8b556..ee9bc6c1a 100644
--- a/src/modules/message/bulk-message.service.spec.ts
+++ b/src/modules/message/bulk-message.service.spec.ts
@@ -1,3 +1,4 @@
+import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
import { Test, TestingModule } from '@nestjs/testing';
import {
BadRequestException,
@@ -419,7 +420,11 @@ describe('BulkMessageService.processBatch', () => {
});
const runProcessBatch = (): Promise<void> =>
- (service as unknown as { processBatch: (id: string) => Promise<void> }).processBatch('b1');
+ (
+ service as unknown as {
+ processBatch: (id: string, reserved: boolean, lifetime: SessionWriteScope) => Promise<void>;
+ }
+ ).processBatch('b1', false, captureSessionWrites(repo, 's1'));
const inFlightMarkers = (): Map<string, boolean> =>
(service as unknown as { processingBatches: Map<string, boolean> }).processingBatches;
@@ -997,6 +1002,7 @@ describe('BulkMessageService.processBatch', () => {
type: 'text',
status: MessageStatus.SENT,
}),
+ expect.anything(),
);
});
@@ -1027,10 +1033,12 @@ describe('BulkMessageService.processBatch', () => {
body: 'clip',
metadata: { media: { mimetype: 'video/mp4', data: 'AAAA', filename: undefined } },
}),
+ expect.anything(),
);
expect(messageService.saveOutgoingMessage).toHaveBeenCalledWith(
's1',
expect.objectContaining({ chatId: '[email protected]', body: 'hi', metadata: undefined }),
+ expect.anything(),
);
});
@@ -1048,6 +1056,7 @@ describe('BulkMessageService.processBatch', () => {
expect(messageService.saveOutgoingMessage).toHaveBeenCalledWith(
's1',
expect.objectContaining({ metadata: { media: { mimetype: 'image/jpeg', data: 'AAAA', filename: undefined } } }),
+ expect.anything(),
);
});
@@ -1285,7 +1294,11 @@ describe('BulkMessageService.processBatch', () => {
expect.objectContaining({ ptt: true, mimetype: 'audio/ogg; codecs=opus' }),
);
- expect(messageService.saveOutgoingMessage).toHaveBeenCalledWith('s1', expect.objectContaining({ type: 'voice' }));
+ expect(messageService.saveOutgoingMessage).toHaveBeenCalledWith(
+ 's1',
+ expect.objectContaining({ type: 'voice' }),
+ expect.anything(),
+ );
});
it('strips base64 media payloads from the stored batch once it completes (footprint)', async () => {
@@ -2121,7 +2134,11 @@ describe('BulkMessageService.createBatch base64 media cap', () => {
// createBatch's own fire-and-forget processBatch saw no persisted row (findOne β†’ undefined);
// drive the processing explicitly with the created batch now "in the DB".
repo.findOne.mockResolvedValue(batch);
- await (service as unknown as { processBatch: (id: string) => Promise<void> }).processBatch(batch.id);
+ await (
+ service as unknown as {
+ processBatch: (id: string, reserved: boolean, lifetime: SessionWriteScope) => Promise<void>;
+ }
+ ).processBatch(batch.id, false, captureSessionWrites(repo, batch.sessionId));
expect(engine.sendTextMessage).toHaveBeenCalledTimes(2);
expect(engine.sendTextMessage).toHaveBeenNthCalledWith(1, '[email protected]', 'first');
@@ -2145,7 +2162,11 @@ describe('BulkMessageService.createBatch base64 media cap', () => {
const batch = await service.createBatch('s1', dto);
// Same fire-and-forget caveat as above β€” drive processing explicitly with the batch "in the DB".
repo.findOne.mockResolvedValue(batch);
- await (service as unknown as { processBatch: (id: string) => Promise<void> }).processBatch(batch.id);
+ await (
+ service as unknown as {
+ processBatch: (id: string, reserved: boolean, lifetime: SessionWriteScope) => Promise<void>;
+ }
+ ).processBatch(batch.id, false, captureSessionWrites(repo, batch.sessionId));
expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
expect(engine.sendTextMessage).toHaveBeenCalledWith('[email protected]', 'part 1');
diff --git a/src/modules/message/bulk-message.service.ts b/src/modules/message/bulk-message.service.ts
index 3638f8a36..ab1ae3fab 100644
--- a/src/modules/message/bulk-message.service.ts
+++ b/src/modules/message/bulk-message.service.ts
@@ -13,6 +13,7 @@ import {
import { createLogger } from '../../common/services/logger.service';
import { ShutdownService } from '../../common/services/shutdown.service';
import { ConfigService } from '@nestjs/config';
+import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
import { InjectRepository } from '@nestjs/typeorm';
import { In, IsNull, Not, QueryDeepPartialEntity, Repository } from 'typeorm';
import { createHash, randomUUID } from 'crypto';
@@ -318,110 +319,117 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
// Check if this batchId already exists FOR THIS SESSION. Scoping by sessionId (matching how
// getBatchStatus/cancelBatch already query) makes (sessionId, batchId) the namespace: one session
// can't deny another a batchId, and the 400-vs-202 difference can't probe another session's ids.
- const existing = await this.batchRepository.findOne({ where: { batchId, sessionId } });
- if (existing) {
- throw new BadRequestException(`Batch ID '${batchId}' already exists`);
- }
-
- // Refused from the start of the drain: a batch accepted then would be failed part-sent when the
- // teardown runs. Checked in the same turn as the registration below: a create that passes here is
- // either seen by the shutdown fail or failed at its pickup in processBatch.
- if (this.shuttingDown || this.shutdownService?.isShuttingDown() === true) {
- throw new ServiceUnavailableException('The server is shutting down; retry the batch shortly');
- }
+ const lifetime = captureSessionWrites(this.batchRepository.manager?.connection ?? this.batchRepository, sessionId);
+ let handedOff = false;
+ try {
+ const existing = await this.batchRepository.findOne({ where: { batchId, sessionId } });
+ if (existing) {
+ throw new BadRequestException(`Batch ID '${batchId}' already exists`);
+ }
- // Reject before persisting a row when too many batches are already processing, so a burst can't
- // hold an unbounded number of full message sets (base64 media included) in memory at once.
- const maxConcurrentBatches = resolveMaxConcurrentBatches();
- if (maxConcurrentBatches > 0 && this.inFlightBatches >= maxConcurrentBatches) {
- throw new HttpException(
- `Too many bulk batches in progress (max ${maxConcurrentBatches}); retry shortly`,
- HttpStatus.TOO_MANY_REQUESTS,
- );
- }
- const options = {
- delayBetweenMessages: dto.options?.delayBetweenMessages ?? 3000,
- randomizeDelay: dto.options?.randomizeDelay ?? true,
- stopOnError: dto.options?.stopOnError ?? false,
- };
+ // Refused from the start of the drain: a batch accepted then would be failed part-sent when the
+ // teardown runs. Checked in the same turn as the registration below: a create that passes here is
+ // either seen by the shutdown fail or failed at its pickup in processBatch.
+ if (this.shuttingDown || this.shutdownService?.isShuttingDown() === true) {
+ throw new ServiceUnavailableException('The server is shutting down; retry the batch shortly');
+ }
- const progress: BatchProgress = {
- total: messages.length,
- sent: 0,
- failed: 0,
- pending: messages.length,
- cancelled: 0,
- };
+ // Reject before persisting a row when too many batches are already processing, so a burst can't
+ // hold an unbounded number of full message sets (base64 media included) in memory at once.
+ const maxConcurrentBatches = resolveMaxConcurrentBatches();
+ if (maxConcurrentBatches > 0 && this.inFlightBatches >= maxConcurrentBatches) {
+ throw new HttpException(
+ `Too many bulk batches in progress (max ${maxConcurrentBatches}); retry shortly`,
+ HttpStatus.TOO_MANY_REQUESTS,
+ );
+ }
+ const options = {
+ delayBetweenMessages: dto.options?.delayBetweenMessages ?? 3000,
+ randomizeDelay: dto.options?.randomizeDelay ?? true,
+ stopOnError: dto.options?.stopOnError ?? false,
+ };
+
+ const progress: BatchProgress = {
+ total: messages.length,
+ sent: 0,
+ failed: 0,
+ pending: messages.length,
+ cancelled: 0,
+ };
+
+ const batch = this.batchRepository.create({
+ // Assigned here rather than by the database, so the batch is registered below before its row
+ // exists anywhere.
+ id: randomUUID(),
+ batchId,
+ sessionId,
+ status: BatchStatus.PENDING,
+ messages: messages as MessageBatch['messages'],
+ options,
+ progress,
+ results: [],
+ currentIndex: 0,
+ });
- const batch = this.batchRepository.create({
- // Assigned here rather than by the database, so the batch is registered below before its row
- // exists anywhere.
- id: randomUUID(),
- batchId,
- sessionId,
- status: BatchStatus.PENDING,
- messages: messages as MessageBatch['messages'],
- options,
- progress,
- results: [],
- currentIndex: 0,
- });
+ // Registered before the row exists, so a reap for this session (a claim that took the session
+ // from another holder) can never read this process's own batch unregistered. A cancel can only
+ // find the row once it is committed, and the false it sets then stands for the pickup check.
+ this.processingBatches.set(batch.id, true);
+ // Reserve synchronously in the same turn as the cap check. There is deliberately no await between
+ // them, so a burst cannot all observe the same stale count and overshoot the ceiling.
+ this.inFlightBatches++;
+ try {
+ // No transaction of its own: on SQLite's single shared connection the rollback of the unique
+ // violation handled below would also discard what other callers wrote while it was open.
+ await lifetime.write(() => this.batchRepository.save(batch, { transaction: false }));
+ } catch (error) {
+ this.inFlightBatches--;
+ this.processingBatches.delete(batch.id);
+ // Two concurrent creates with the same caller-supplied batchId both pass the read above; the
+ // unique index decides, and the loser gets the same 400 as the sequential case.
+ if (isUniqueViolation(error)) {
+ throw new BadRequestException(`Batch ID '${batchId}' already exists`);
+ }
+ throw error;
+ }
+ this.logger.log(
+ `Created batch ${batchId} with ${messages.length} messages` +
+ (messages.length === dto.messages.length
+ ? ''
+ : ` (${dto.messages.length - messages.length} exact duplicate entr${dto.messages.length - messages.length === 1 ? 'y' : 'ies'} dropped)`),
+ );
- // Registered before the row exists, so a reap for this session (a claim that took the session
- // from another holder) can never read this process's own batch unregistered. A cancel can only
- // find the row once it is committed, and the false it sets then stands for the pickup check.
- this.processingBatches.set(batch.id, true);
- // Reserve synchronously in the same turn as the cap check. There is deliberately no await between
- // them, so a burst cannot all observe the same stale count and overshoot the ceiling.
- this.inFlightBatches++;
- try {
- // No transaction of its own: on SQLite's single shared connection the rollback of the unique
- // violation handled below would also discard what other callers wrote while it was open.
- await this.batchRepository.save(batch, { transaction: false });
- } catch (error) {
- this.inFlightBatches--;
- this.processingBatches.delete(batch.id);
- // Two concurrent creates with the same caller-supplied batchId both pass the read above; the
- // unique index decides, and the loser gets the same 400 as the sequential case.
- if (isUniqueViolation(error)) {
- throw new BadRequestException(`Batch ID '${batchId}' already exists`);
+ // Start processing asynchronously
+ const pickup = this.processBatch(batch.id, true, lifetime).catch(err => {
+ this.logger.error(`Batch ${batchId} processing error: ${String(err)}`);
+ });
+ handedOff = true;
+ // Teardown began during the save, so the pickup only fails the row. Awaited here, because the
+ // HTTP server's close waits for this request and the database closes after it; a detached write
+ // could find the connection gone and leave the row PENDING. Nothing was sent, so the row is then
+ // deleted and the answer is a 503: a retry of the same batchId (an SDK replaying the 503) is not
+ // refused as a duplicate of a batch that never ran. Only this process drives the batch, and the
+ // guard on startedAt keeps any row that began sending.
+ if (this.shuttingDown) {
+ await pickup;
+ const freed = await this.batchRepository.delete({ id: batch.id, startedAt: IsNull() }).then(
+ result => Boolean(result.affected),
+ (error: unknown) => {
+ this.logger.error(`Could not delete unsent batch ${batchId} on shutdown: ${String(error)}`);
+ return false;
+ },
+ );
+ throw new ServiceUnavailableException(
+ freed
+ ? 'The server is shutting down; retry the batch shortly'
+ : `The server is shutting down; batch '${batchId}' was not sent. Retry it shortly under a new batch ID`,
+ );
}
- throw error;
- }
- this.logger.log(
- `Created batch ${batchId} with ${messages.length} messages` +
- (messages.length === dto.messages.length
- ? ''
- : ` (${dto.messages.length - messages.length} exact duplicate entr${dto.messages.length - messages.length === 1 ? 'y' : 'ies'} dropped)`),
- );
- // Start processing asynchronously
- const pickup = this.processBatch(batch.id, true).catch(err => {
- this.logger.error(`Batch ${batchId} processing error: ${String(err)}`);
- });
- // Teardown began during the save, so the pickup only fails the row. Awaited here, because the
- // HTTP server's close waits for this request and the database closes after it; a detached write
- // could find the connection gone and leave the row PENDING. Nothing was sent, so the row is then
- // deleted and the answer is a 503: a retry of the same batchId (an SDK replaying the 503) is not
- // refused as a duplicate of a batch that never ran. Only this process drives the batch, and the
- // guard on startedAt keeps any row that began sending.
- if (this.shuttingDown) {
- await pickup;
- const freed = await this.batchRepository.delete({ id: batch.id, startedAt: IsNull() }).then(
- result => Boolean(result.affected),
- (error: unknown) => {
- this.logger.error(`Could not delete unsent batch ${batchId} on shutdown: ${String(error)}`);
- return false;
- },
- );
- throw new ServiceUnavailableException(
- freed
- ? 'The server is shutting down; retry the batch shortly'
- : `The server is shutting down; batch '${batchId}' was not sent. Retry it shortly under a new batch ID`,
- );
+ return batch;
+ } finally {
+ if (!handedOff) lifetime.close();
}
-
- return batch;
}
async getBatchStatus(sessionId: string, batchId: string): Promise<MessageBatch> {
@@ -488,13 +496,14 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
return batch;
}
- private async processBatch(batchDbId: string, reserved = false): Promise<void> {
+ private async processBatch(batchDbId: string, reserved: boolean, lifetime: SessionWriteScope): Promise<void> {
let batch: MessageBatch | null = null;
// Always release the in-flight marker on every exit path (engine-not-found early return, a thrown
// save/send, or normal completion) β€” otherwise the map leaks an entry per such batch.
try {
batch = await this.batchRepository.findOne({ where: { id: batchDbId } });
if (!batch) return;
+ lifetime.assertCurrent();
// A cancel that landed before this run picked the batch up must not be revived β€” neither the
// in-memory flag nor a persisted CANCELLED may be flipped back. The guarded status UPDATE in
// executeBatch closes the remaining race (a cancel committing after this read).
@@ -505,40 +514,45 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
// Saved while the shutdown fail ran, which could not see the row yet: fail it unsent rather
// than start a run after this process began tearing down.
if (this.shuttingDown) {
- await this.failOrphanedBatch(batch);
+ await lifetime.write(() => this.failOrphanedBatch(batch as MessageBatch));
this.logger.warn(`Batch ${batch.batchId} was failed before processing started: shutting down`);
return;
}
this.processingBatches.set(batch.id, true);
- await this.executeBatch(batch);
+ await this.executeBatch(batch, lifetime);
} catch (error) {
+ lifetime.assertCurrent();
// A throw here (a DB error on the pickup read, the start transition or a progress write) would
// leave the row PENDING or PROCESSING, and nothing else moves it on while this process lives:
// the reapers run only at boot and on a session takeover. Best effort, since the database that
// just failed may fail again. The row gets what this run sent, so delivered items are not
// reported as pending.
- await this.failOrphanedBatch(batch ?? { id: batchDbId }, true).catch((failError: unknown) => {
- this.logger.error(`Could not mark batch ${batchDbId} FAILED after its run threw: ${String(failError)}`);
- });
+ await lifetime
+ .write(() => this.failOrphanedBatch(batch ?? { id: batchDbId }, true))
+ .catch((failError: unknown) => {
+ this.logger.error(`Could not mark batch ${batchDbId} FAILED after its run threw: ${String(failError)}`);
+ });
throw error;
} finally {
if (reserved) this.inFlightBatches--;
this.processingBatches.delete(batchDbId);
+ lifetime.close();
}
}
- private async executeBatch(batch: MessageBatch): Promise<void> {
- if (!(await this.markBatchProcessing(batch))) return;
+ private async executeBatch(batch: MessageBatch, lifetime: SessionWriteScope): Promise<void> {
+ if (!(await lifetime.write(() => this.markBatchProcessing(batch)))) return;
+ lifetime.assertCurrent();
if (!this.engines.get(batch.sessionId)) {
- await this.failBatchWithoutEngine(batch);
+ await lifetime.write(() => this.failBatchWithoutEngine(batch));
return;
}
const results: BatchMessageResult[] = batch.results || [];
const state: BatchExecutionState = { results, stoppedOnError: false, cancelledByDb: false, endedElsewhere: false };
- await this.processBatchMessages(batch, state);
- await this.finalizeBatch(batch, state);
+ await this.processBatchMessages(batch, state, lifetime);
+ await lifetime.write(() => this.finalizeBatch(batch, state));
}
/** Returns false when the batch left PENDING before this start UPDATE, so nothing is sent. */
@@ -571,9 +585,14 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
} as QueryDeepPartialEntity<MessageBatch>);
}
- private async processBatchMessages(batch: MessageBatch, state: BatchExecutionState): Promise<void> {
+ private async processBatchMessages(
+ batch: MessageBatch,
+ state: BatchExecutionState,
+ lifetime: SessionWriteScope,
+ ): Promise<void> {
for (let i = batch.currentIndex; i < batch.messages.length; i++) {
- if (!(await this.processBatchMessage(batch, i, state))) break;
+ lifetime.assertCurrent();
+ if (!(await this.processBatchMessage(batch, i, state, lifetime))) break;
}
}
@@ -581,7 +600,12 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
* Send one batch message through the moderation gate, record the outcome, and persist progress.
* Returns false when the batch loop must stop (cancellation or stopOnError).
*/
- private async processBatchMessage(batch: MessageBatch, i: number, state: BatchExecutionState): Promise<boolean> {
+ private async processBatchMessage(
+ batch: MessageBatch,
+ i: number,
+ state: BatchExecutionState,
+ lifetime: SessionWriteScope,
+ ): Promise<boolean> {
const { results } = state;
// Check for cancellation
if (!this.processingBatches.get(batch.id)) {
@@ -659,6 +683,7 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
// Resolved per item, not once per batch: a session restart or reconnect registers a fresh
// adapter, and a batch still holding the retired one would fail every remaining item.
+ lifetime.assertCurrent();
const engine = this.engines.get(batch.sessionId);
if (!engine) throw new EngineNotReadyError();
@@ -695,7 +720,7 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
// mapping β€” the engine echo (onMessageCreate) writes its own OUTGOING row, but only with what
// the engine reported, and a Baileys API send echoes a media-less marker. The two writers
// dedup on UNIQUE(sessionId, waMessageId).
- await this.persistSentMessage(batch.sessionId, msg.chatId, msg.type, content, messageResult);
+ await this.persistSentMessage(batch.sessionId, msg.chatId, msg.type, content, messageResult, lifetime);
this.logger.debug(`Batch ${batch.batchId}: Sent message ${i + 1}/${batch.messages.length} to ${msg.chatId}`);
} catch (error) {
@@ -742,6 +767,7 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
}
}
+ lifetime.assertCurrent();
results.push(result);
batch.currentIndex = i + 1;
batch.results = results;
@@ -751,9 +777,11 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
// only sees same-process cancels), and a reap that failed the batch after another node took the
// session over. The guard lives IN the UPDATE (not a read-then-write), so neither can be written
// over: zero affected rows stops the loop, and the row says which of the two it was.
- const progressSaved = await this.batchRepository.update(
- { id: batch.id, status: BatchStatus.PROCESSING },
- { progress: batch.progress, results, currentIndex: batch.currentIndex },
+ const progressSaved = await lifetime.write(() =>
+ this.batchRepository.update(
+ { id: batch.id, status: BatchStatus.PROCESSING },
+ { progress: batch.progress, results, currentIndex: batch.currentIndex },
+ ),
);
if (!progressSaved.affected) {
await this.noteRowLeftProcessing(batch, state, `at index ${i}`);
@@ -990,6 +1018,7 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
type: string,
content: BulkMessageContent,
result: MessageResult,
+ lifetime: SessionWriteScope,
): Promise<void> {
// Store what sendMessage sent: the media under the item's own type key, and the caption for a
// media item (audio carries none). Other keys on the item were never delivered.
@@ -998,23 +1027,27 @@ export class BulkMessageService implements OnModuleInit, OnApplicationBootstrap,
// A bulk audio item flagged ptt is a voice note; store it in the 'voice' bucket like inbound PTT.
const persistType = type === 'audio' && content.audio?.ptt ? 'voice' : type;
try {
- await this.messageService.saveOutgoingMessage(sessionId, {
- waMessageId: result.id,
- chatId,
- body: body ?? '',
- type: persistType,
- timestamp: result.timestamp,
- status: MessageStatus.SENT,
- metadata: media
- ? {
- media: {
- mimetype: this.mediaMimetype(type, content),
- data: stripBase64DataUri(media.base64) || media.url,
- filename: media.filename,
- },
- }
- : undefined,
- });
+ await this.messageService.saveOutgoingMessage(
+ sessionId,
+ {
+ waMessageId: result.id,
+ chatId,
+ body: body ?? '',
+ type: persistType,
+ timestamp: result.timestamp,
+ status: MessageStatus.SENT,
+ metadata: media
+ ? {
+ media: {
+ mimetype: this.mediaMimetype(type, content),
+ data: stripBase64DataUri(media.base64) || media.url,
+ filename: media.filename,
+ },
+ }
+ : undefined,
+ },
+ lifetime,
+ );
} catch (error) {
// Losing the dedup race to the own-send echo is no longer an error here β€” saveOutgoingMessage
// merges onto the echo's row. Anything reaching this point is a real persistence fault.
diff --git a/src/modules/message/message-send-pacing.spec.ts b/src/modules/message/message-send-pacing.spec.ts
new file mode 100644
index 000000000..2725c34b4
--- /dev/null
+++ b/src/modules/message/message-send-pacing.spec.ts
@@ -0,0 +1,379 @@
+import { ConfigService } from '@nestjs/config';
+import { HttpException } from '@nestjs/common';
+import { DataSource, Repository } from 'typeorm';
+import { EngineRegistry } from '../../engine/engine-registry.service';
+import { type IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
+import { HookManager, type HookContext } from '../../core/hooks';
+import { Session } from '../session/entities/session.entity';
+import { Message, MessageDirection } from './entities/message.entity';
+import { MessageSendService } from './message-send.service';
+import { SEND_PACING_LIMITED, SendPacingService } from './send-pacing.service';
+import { computeSendPacingConfig } from './send-pacing.config';
+import { closeSessionWrites } from '../../common/utils/session-write-scope';
+
+const NOW = new Date('2026-06-01T12:00:00Z');
+const deferred = () => {
+ let resolve!: () => void;
+ const promise = new Promise<void>(res => (resolve = res));
+ return { promise, resolve };
+};
+
+describe('MessageSendService preparation pacing', () => {
+ let ds: DataSource;
+ let messages: Repository<Message>;
+ let sender: MessageSendService;
+ let hooks: HookManager;
+ let engines: EngineRegistry;
+ let engine: Record<string, jest.Mock>;
+ let pacingConfig: ReturnType<typeof computeSendPacingConfig>;
+ let pacing: SendPacingService;
+
+ const send = () => sender.sendText('s1', { chatId: '[email protected]', text: 'hello' });
+ const replaceSession = async () => {
+ const deletion = closeSessionWrites(ds, 's1');
+ await deletion.drain();
+ engines.delete('s1');
+ await ds.transaction(async manager => {
+ await manager.delete(Message, { sessionId: 's1' });
+ await manager.delete(Session, { id: 's1' });
+ });
+ deletion.release();
+ await ds.getRepository(Session).save({ id: 's1', name: 'replacement', createdAt: new Date() });
+ engines.set('s1', engine as unknown as IWhatsAppEngine);
+ };
+ const expectLimited = async () => {
+ try {
+ await sender.sendText('s1', { chatId: '[email protected]', text: 'second' });
+ throw new Error('Expected the send to be paced');
+ } catch (error) {
+ expect(error).toBeInstanceOf(HttpException);
+ const response = (error as HttpException).getResponse() as { code: string; retryAfterSeconds: number };
+ expect(response.code).toBe(SEND_PACING_LIMITED);
+ expect(Number.isFinite(response.retryAfterSeconds)).toBe(true);
+ expect(response.retryAfterSeconds).toBeGreaterThan(0);
+ }
+ };
+
+ beforeEach(async () => {
+ process.env.SIMULATE_TYPING = 'false';
+ jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate', 'queueMicrotask'] }).setSystemTime(NOW);
+ ds = new DataSource({
+ type: 'better-sqlite3',
+ database: ':memory:',
+ entities: [Session, Message],
+ synchronize: true,
+ });
+ await ds.initialize();
+ const sessions = ds.getRepository(Session);
+ await sessions.save({ id: 's1', name: 'sender', createdAt: NOW });
+ messages = ds.getRepository(Message);
+ pacingConfig = { ...computeSendPacingConfig({}), enabled: true, warmupSchedule: [1], coldSchedule: [] };
+ const config = { get: (key: string) => (key === 'sendPacing' ? pacingConfig : undefined) } as ConfigService;
+ pacing = new SendPacingService(messages, sessions, config);
+ hooks = new HookManager();
+ engines = new EngineRegistry();
+ engine = {};
+ let sent = 0;
+ for (const method of [
+ 'sendTextMessage',
+ 'sendImageMessage',
+ 'sendVideoMessage',
+ 'sendAudioMessage',
+ 'sendDocumentMessage',
+ 'sendStickerMessage',
+ 'sendLocationMessage',
+ 'sendContactMessage',
+ 'sendPollMessage',
+ 'replyToMessage',
+ 'clickButton',
+ 'forwardMessage',
+ ])
+ engine[method] = jest
+ .fn()
+ .mockImplementation(() => Promise.resolve({ id: `sent-${++sent}`, timestamp: Date.now() / 1000 }));
+ engines.set('s1', engine as unknown as IWhatsAppEngine);
+ sender = new MessageSendService(
+ messages,
+ { findOne: (id: string) => sessions.findOneByOrFail({ id }) } as never,
+ engines,
+ hooks,
+ {} as never,
+ pacing,
+ config,
+ );
+ });
+
+ afterEach(async () => {
+ jest.useRealTimers();
+ delete process.env.SIMULATE_TYPING;
+ jest.restoreAllMocks();
+ await ds.destroy();
+ });
+
+ it.each(['daily', 'cold'])('holds the %s allowance while a hook takes more than five minutes', async cap => {
+ if (cap === 'cold') {
+ pacingConfig.warmupSchedule = [100];
+ pacingConfig.coldSchedule = [1];
+ }
+ const entered = deferred();
+ const finish = deferred();
+ let calls = 0;
+ hooks.register('moderation', 'message:sending', async context => {
+ if (++calls === 1) {
+ entered.resolve();
+ await finish.promise;
+ }
+ return { continue: true, data: context.data };
+ });
+ const pending = send();
+ await entered.promise;
+ expect(await messages.count()).toBe(0);
+ jest.setSystemTime(NOW.getTime() + 5 * 60_000 + 1);
+ try {
+ await expectLimited();
+ expect(calls).toBe(1);
+ } finally {
+ finish.resolve();
+ await pending;
+ }
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
+ expect(await messages.count()).toBe(1);
+ await expectLimited();
+ });
+
+ it.each(['reply', 'clickButton', 'save'])('holds the allowance through delayed %s preparation', async stage => {
+ const entered = deferred();
+ const finish = deferred();
+ if (stage === 'save') {
+ const save = messages.save.bind(messages);
+ jest.spyOn(messages, 'save').mockImplementationOnce(async message => {
+ entered.resolve();
+ await finish.promise;
+ return save(message);
+ });
+ } else {
+ jest
+ .spyOn(sender as unknown as { resolveQuotedBody: () => Promise<string> }, 'resolveQuotedBody')
+ .mockImplementationOnce(async () => {
+ entered.resolve();
+ await finish.promise;
+ return 'prompt';
+ });
+ }
+ const pending =
+ stage === 'reply'
+ ? sender.reply('s1', { chatId: '[email protected]', quotedMessageId: 'prompt', text: 'reply' })
+ : stage === 'clickButton'
+ ? sender.clickButton('s1', { chatId: '[email protected]', messageId: 'prompt', buttonId: 'yes' })
+ : send();
+ await entered.promise;
+ jest.setSystemTime(NOW.getTime() + 5 * 60_000 + 1);
+ try {
+ await expectLimited();
+ } finally {
+ finish.resolve();
+ await pending;
+ }
+ expect(await messages.count()).toBe(1);
+ });
+
+ it.each(['veto', 'missing engine', 'invalid media', 'quote lookup', 'initial save'])(
+ 'refunds a no-row send after %s',
+ async reason => {
+ if (reason === 'veto')
+ hooks.register('moderation', 'message:sending', () => Promise.resolve({ continue: false }));
+ if (reason === 'missing engine') engines.delete('s1');
+ if (reason === 'initial save') jest.spyOn(messages, 'save').mockRejectedValueOnce(new Error('write failed'));
+ if (reason === 'quote lookup') {
+ jest
+ .spyOn(sender as unknown as { resolveQuotedBody: () => Promise<string> }, 'resolveQuotedBody')
+ .mockRejectedValueOnce(new Error('quote lookup failed'));
+ }
+
+ const pending =
+ reason === 'invalid media'
+ ? sender.sendImage('s1', { chatId: '[email protected]' })
+ : reason === 'quote lookup'
+ ? sender.reply('s1', { chatId: '[email protected]', quotedMessageId: 'prompt', text: 'reply' })
+ : send();
+ await expect(pending).rejects.toThrow();
+
+ expect(await messages.count()).toBe(0);
+ expect(engine.sendTextMessage).not.toHaveBeenCalled();
+ hooks.unregisterPlugin('moderation');
+ engines.set('s1', engine as unknown as IWhatsAppEngine);
+ await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
+ expect(await messages.count()).toBe(1);
+ },
+ );
+
+ it('counts the durable row once after handing off its admission', async () => {
+ pacingConfig.warmupSchedule = [2];
+
+ await send();
+ await send();
+
+ expect(await messages.count()).toBe(2);
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(2);
+ await expectLimited();
+ });
+
+ it('keeps pacing optional', async () => {
+ pacingConfig.enabled = false;
+
+ await send();
+ await send();
+
+ expect(await messages.count()).toBe(2);
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(2);
+ });
+
+ it.each(['daily', 'cold'])('carries a preparing %s admission across UTC midnight', async cap => {
+ if (cap === 'cold') {
+ pacingConfig.warmupSchedule = [100];
+ pacingConfig.coldSchedule = [1];
+ }
+ const entered = deferred();
+ const finish = deferred();
+ let calls = 0;
+ hooks.register('moderation', 'message:sending', async context => {
+ if (++calls === 1) {
+ entered.resolve();
+ await finish.promise;
+ }
+ return { continue: true, data: context.data };
+ });
+ const pending = send();
+ await entered.promise;
+ jest.setSystemTime(new Date('2026-06-02T00:00:01Z'));
+ try {
+ await expectLimited();
+ } finally {
+ finish.resolve();
+ await pending;
+ }
+ expect(await messages.count()).toBe(1);
+ });
+
+ it.each(['daily', 'cold'])('includes current-day rows when carrying a preparing %s admission', async cap => {
+ pacingConfig.warmupSchedule = cap === 'daily' ? [2] : [100];
+ pacingConfig.coldSchedule = cap === 'cold' ? [2] : [];
+ const entered = deferred();
+ const finish = deferred();
+ let calls = 0;
+ hooks.register('moderation', 'message:sending', async context => {
+ if (++calls === 1) {
+ entered.resolve();
+ await finish.promise;
+ }
+ return { continue: true, data: context.data };
+ });
+ const pending = send();
+ await entered.promise;
+ jest.setSystemTime(new Date('2026-06-02T00:00:01Z'));
+ await messages.save({
+ sessionId: 's1',
+ chatId: '[email protected]',
+ from: 'a',
+ to: 'b',
+ type: 'text',
+ direction: MessageDirection.OUTGOING,
+ });
+ try {
+ await expectLimited();
+ } finally {
+ finish.resolve();
+ await pending;
+ }
+ expect(await messages.count()).toBe(2);
+ });
+
+ it('keeps the current-day admission when an older preparation is refunded', async () => {
+ pacingConfig.warmupSchedule = [2];
+ const older = await pacing.assertSendAllowed('s1', '[email protected]', { whilePreparing: true });
+ jest.setSystemTime(new Date('2026-06-02T00:00:01Z'));
+ const current = await pacing.assertSendAllowed('s1', '[email protected]', { whilePreparing: true });
+
+ older?.();
+ pacingConfig.warmupSchedule = [1];
+ await expectLimited();
+ current?.();
+
+ await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
+ });
+
+ it('refunds a retired preparation before its sending hook completes', async () => {
+ const entered = deferred();
+ const finish = deferred();
+ hooks.register('moderation', 'message:sending', async context => {
+ entered.resolve();
+ await finish.promise;
+ return { continue: true, data: context.data };
+ });
+ const old = send().catch((error: unknown) => error);
+ await entered.promise;
+ await replaceSession();
+ hooks.unregisterPlugin('moderation');
+ expect(await messages.count()).toBe(0);
+
+ try {
+ await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
+ } finally {
+ finish.resolve();
+ await old;
+ }
+ expect(await old).toMatchObject({ status: 404 });
+ expect(await messages.count()).toBe(1);
+ await expectLimited();
+ });
+
+ it('refunds an admission whose lifetime retires during the pacing lookup', async () => {
+ const entered = deferred();
+ const finish = deferred();
+ const count = messages.count.bind(messages);
+ jest.spyOn(messages, 'count').mockImplementationOnce(async options => {
+ entered.resolve();
+ await finish.promise;
+ return count(options);
+ });
+ const hook = jest.fn((context: HookContext) => Promise.resolve({ continue: true, data: context.data }));
+ hooks.register('moderation', 'message:sending', hook);
+ const old = send().catch((error: unknown) => error);
+ await entered.promise;
+ await replaceSession();
+
+ finish.resolve();
+ expect(await old).toMatchObject({ status: 404 });
+ expect(hook).not.toHaveBeenCalled();
+ expect(await messages.count()).toBe(0);
+ await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
+ });
+
+ it('cannot dispatch or settle successfully after its pending write lifetime retires', async () => {
+ const entered = deferred();
+ const finish = deferred();
+ const save = sender.saveOutgoingMessage.bind(sender);
+ jest.spyOn(sender, 'saveOutgoingMessage').mockImplementationOnce(async (sessionId, data, lifetime) => {
+ const message = await save(sessionId, data, lifetime);
+ entered.resolve();
+ await finish.promise;
+ return message;
+ });
+ const old = send().catch((error: unknown) => error);
+ await entered.promise;
+ expect(await messages.count()).toBe(1);
+ await replaceSession();
+
+ try {
+ await expect(send()).resolves.toMatchObject({ messageId: 'sent-1' });
+ } finally {
+ finish.resolve();
+ await old;
+ }
+ expect(await old).toMatchObject({ status: 404 });
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
+ expect(await messages.count()).toBe(1);
+ });
+});
diff --git a/src/modules/message/message-send.service.spec.ts b/src/modules/message/message-send.service.spec.ts
index e5eff2727..1afc77f72 100644
--- a/src/modules/message/message-send.service.spec.ts
+++ b/src/modules/message/message-send.service.spec.ts
@@ -289,15 +289,15 @@ describe('MessageSendService', () => {
status: MessageStatus.PENDING,
}),
);
- // save called twice: once for initial pending, once for status update to sent
- expect(repository.save).toHaveBeenCalledTimes(2);
+ expect(repository.save).toHaveBeenCalledTimes(1);
+ expect(repository.update).toHaveBeenCalledWith(
+ { id: 'msg-uuid-1', sessionId: 'sess-1' },
+ expect.objectContaining({ status: MessageStatus.SENT }),
+ );
});
it('returns success (not FAILED) when persisting the SENT state fails after a successful send', async () => {
- // 1st save (PENDING) ok; 2nd save (SENT-state, after WhatsApp already accepted the message) throws.
- (repository.save as jest.Mock)
- .mockImplementationOnce((msg: unknown) => Promise.resolve(msg))
- .mockRejectedValueOnce(new Error('transient db fault'));
+ (repository.update as jest.Mock).mockRejectedValueOnce(new Error('transient db fault'));
const result = await service.sendText('sess-1', { chatId: '[email protected]', text: 'Hello' });
@@ -413,18 +413,16 @@ describe('MessageSendService', () => {
waMessageId: 'wa-msg-1',
status: MessageStatus.SENT,
} as Message;
- (repository.save as jest.Mock)
- .mockImplementationOnce((msg: unknown) => Promise.resolve(msg)) // PENDING save
- .mockRejectedValueOnce(
- Object.assign(new Error('UNIQUE constraint failed'), { code: 'SQLITE_CONSTRAINT_UNIQUE' }),
- ); // SENT save collides with the echo row
+ (repository.update as jest.Mock).mockRejectedValueOnce(
+ Object.assign(new Error('UNIQUE constraint failed'), { code: 'SQLITE_CONSTRAINT_UNIQUE' }),
+ );
(repository.findOne as jest.Mock).mockResolvedValueOnce(echoRow);
await service.sendText('sess-1', { chatId: '[email protected]', text: 'hi' });
// Timestamp merged onto the echo row; the redundant PENDING row dropped. `status` is NOT
// written: the echo row is already SENT and an ack may have advanced it further.
- const [, mergePatch] = (repository.update as jest.Mock).mock.calls[0] as [unknown, object];
+ const [, mergePatch] = (repository.update as jest.Mock).mock.calls[1] as [unknown, object];
expect(mergePatch).not.toHaveProperty('status');
expect(repository.delete).toHaveBeenCalledWith({ id: 'msg-uuid-1' });
const persisted = (hookManager.execute as jest.Mock).mock.calls.filter(
@@ -1365,7 +1363,10 @@ describe('MessageSendService', () => {
service.clickButton('sess-1', { chatId: '[email protected]', messageId: 'PROMPT-1', buttonId: 'yes' }),
).rejects.toBeInstanceOf(BadRequestException);
- expect(repository.save).toHaveBeenCalledWith(expect.objectContaining({ status: MessageStatus.FAILED }));
+ expect(repository.update).toHaveBeenCalledWith(
+ { id: 'msg-uuid-1', sessionId: 'sess-1' },
+ expect.objectContaining({ status: MessageStatus.FAILED }),
+ );
expect(hookManager.execute).toHaveBeenCalledWith(
'message:failed',
expect.objectContaining({ sessionId: 'sess-1', type: 'click-button' }),
@@ -1412,7 +1413,7 @@ describe('MessageSendService', () => {
messageId: 'wa-msg-to-fwd',
});
- expect(assertSendAllowed).toHaveBeenCalledWith('sess-1', '[email protected]');
+ expect(assertSendAllowed).toHaveBeenCalledWith('sess-1', '[email protected]', { whilePreparing: true });
});
});
@@ -1449,12 +1450,13 @@ describe('MessageSendService', () => {
expect(repository.save).not.toHaveBeenCalled();
});
- it('keeps it when the engine fails after the row was written', async () => {
+ it('hands it to the durable row before an engine failure', async () => {
mockEngine.sendTextMessage.mockRejectedValueOnce(new BadRequestException('refused'));
await expect(service.sendText('sess-1', { chatId: '[email protected]', text: 'hi' })).rejects.toThrow('refused');
- expect(release).not.toHaveBeenCalled();
+ expect(release).toHaveBeenCalledTimes(1);
+ expect(release).toHaveBeenCalledWith(true);
});
});
@@ -1639,9 +1641,9 @@ describe('MessageSendService', () => {
describe('persistSentState vs the own-send echo (dedup race)', () => {
it('retains the sent media row when merging onto the echo fails', async () => {
- (repository.save as jest.Mock)
- .mockImplementationOnce(msg => Promise.resolve(msg))
- .mockRejectedValueOnce(new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'));
+ (repository.update as jest.Mock).mockRejectedValueOnce(
+ new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'),
+ );
(repository.findOne as jest.Mock).mockResolvedValue({ id: 'echo-row', metadata: {} });
(repository.update as jest.Mock).mockRejectedValueOnce(new Error('SQLITE_BUSY'));
@@ -1656,13 +1658,13 @@ describe('MessageSendService', () => {
);
});
it('merges state onto the echo row, then drops the redundant PENDING row', async () => {
- // The engine's message_create echo (onMessageCreate) won the insert race, so the SENT-state save
+ // The engine's message_create echo won the insert race, so the SENT-state update
// collides on UNIQUE(sessionId, waMessageId). The echo row carries only what the engine reported
// β€” for a Baileys API send, a media-less marker β€” so the merge must land status/timestamp/metadata
// on it BEFORE the placeholder is deleted, or the payload is lost. The send still succeeds.
- (repository.save as jest.Mock)
- .mockImplementationOnce(msg => Promise.resolve(msg)) // saveOutgoingMessage (PENDING)
- .mockRejectedValueOnce(new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'));
+ (repository.update as jest.Mock).mockRejectedValueOnce(
+ new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'),
+ );
const result = await service.sendText('sess-1', { chatId: '[email protected]', text: 'hi' });
@@ -1679,41 +1681,39 @@ describe('MessageSendService', () => {
* when a `delivered` ack won the race, writing SENT here dragged the row back and the
* dashboard showed one tick for a message the recipient already had.
*/
- const [, sentPatch] = (repository.update as jest.Mock).mock.calls[0] as [unknown, object];
+ const [, sentPatch] = (repository.update as jest.Mock).mock.calls[1] as [unknown, object];
expect(sentPatch).not.toHaveProperty('status');
expect(repository.delete).toHaveBeenCalledWith({ id: 'msg-uuid-1' });
});
it('merges the media payload onto the echo row for a media send (no data loss after reload)', async () => {
- (repository.save as jest.Mock)
- .mockImplementationOnce(msg => Promise.resolve(msg))
- .mockRejectedValueOnce(new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'));
+ (repository.update as jest.Mock).mockRejectedValueOnce(
+ new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'),
+ );
(repository.findOne as jest.Mock).mockResolvedValue({ id: 'echo-row', metadata: {} });
await service.sendImage('sess-1', { chatId: '[email protected]', base64: 'QUJD', mimetype: 'image/png' });
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
- const patch = (repository.update as jest.Mock).mock.calls[0]?.[1] as Record<string, unknown> | undefined;
+ const patch = (repository.update as jest.Mock).mock.calls[1]?.[1] as Record<string, unknown> | undefined;
expect((patch?.metadata as { media?: { data?: string } } | undefined)?.media?.data).toBe('QUJD');
expect(repository.delete).toHaveBeenCalledWith({ id: 'msg-uuid-1' });
});
it('keeps the echo row’s downloaded bytes rather than merging a URL pointer over them', async () => {
- (repository.save as jest.Mock)
- .mockImplementationOnce(msg => Promise.resolve(msg))
- .mockRejectedValueOnce(new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'));
+ (repository.update as jest.Mock).mockRejectedValueOnce(
+ new Error('UNIQUE constraint failed: messages.sessionId, messages.waMessageId'),
+ );
await service.sendImage('sess-1', { chatId: '[email protected]', url: 'https://example.com/cat.png' });
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
- const patch = (repository.update as jest.Mock).mock.calls[0]?.[1] as Record<string, unknown> | undefined;
+ const patch = (repository.update as jest.Mock).mock.calls[1]?.[1] as Record<string, unknown> | undefined;
expect(patch).not.toHaveProperty('metadata');
});
it('does NOT delete anything on a transient (non-unique) persist error', async () => {
- (repository.save as jest.Mock)
- .mockImplementationOnce(msg => Promise.resolve(msg))
- .mockRejectedValueOnce(new Error('SQLITE_BUSY: database is locked'));
+ (repository.update as jest.Mock).mockRejectedValueOnce(new Error('SQLITE_BUSY: database is locked'));
const result = await service.sendText('sess-1', { chatId: '[email protected]', text: 'hi' });
diff --git a/src/modules/message/message-send.service.ts b/src/modules/message/message-send.service.ts
index 50b2753b4..18a8794c4 100644
--- a/src/modules/message/message-send.service.ts
+++ b/src/modules/message/message-send.service.ts
@@ -13,7 +13,7 @@ import { assertBase64WithinMediaCap, stripBase64DataUri } from './media-cap.util
import { MediaInput, IWhatsAppEngine, MessageResult } from '../../engine/interfaces/whatsapp-engine.interface';
import { Message, MessageDirection, MessageStatus } from './entities/message.entity';
import { HookManager, applySendingGate } from '../../core/hooks';
-import { SendPacingService, countsTowardSendBreaker } from './send-pacing.service';
+import { SendPacingService, SettleAdmission, countsTowardSendBreaker } from './send-pacing.service';
import { TemplateService } from '../template/template.service';
import { renderTemplate } from '../../common/utils/template-render';
import { createLogger } from '../../common/services/logger.service';
@@ -24,6 +24,7 @@ import { ChatMediaArchiveService } from '../chat-media/chat-media-archive.servic
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { resolveJidCandidates } from '../../engine/identity/jid-candidates';
import { isMediaUrl, MEDIA_URL_MESSAGE } from '../../common/media/media-url';
+import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
/** Default cap on a rendered template's final text; overridable via TEMPLATE_RENDER_MAX_CHARS. */
export const DEFAULT_TEMPLATE_RENDER_MAX_CHARS = 64 * 1024;
@@ -110,15 +111,12 @@ export class MessageSendService {
if (dto.linkPreview === false && dto.customLinkPreview) {
throw new BadRequestException('linkPreview: false cannot be combined with customLinkPreview');
}
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'text', dto);
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
+ const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'text', dto, finalDto => ({
chatId: finalDto.chatId,
body: finalDto.text,
type: 'text',
quotedMessageId: finalDto.quotedMessageId,
- });
+ }));
// Humanising "typing…" pause before the actual send (anti-automation signal). On by default;
// SIMULATE_TYPING=false disables it.
@@ -157,8 +155,8 @@ export class MessageSendService {
/**
* Run the pre-send `message:sending` plugin gate for one outbound message and return the
- * (possibly plugin-modified) input with the session's engine and what `prepare` built from that
- * input, or throw BadRequestException if a plugin blocked the send.
+ * (possibly plugin-modified) input with the session's engine, prepared data and durable PENDING
+ * row, or throw BadRequestException if a plugin blocked the send.
* Centralised so EVERY public sender in this class β€” text, media, extended (location/contact/
* poll/sticker/reply/forward) β€” passes through the same moderation chokepoint, instead of only
* `sendText`. The edit path is gated by the twin method in MessageService (the query side of
@@ -169,8 +167,9 @@ export class MessageSendService {
sessionId: string,
type: string,
input: T,
+ buildPending: (finalDto: T, prepared: P) => SaveOutgoingMessageData | Promise<SaveOutgoingMessageData>,
prepare?: (finalDto: T) => P,
- ): Promise<{ finalDto: T; engine: IWhatsAppEngine; prepared: P }> {
+ ): Promise<{ finalDto: T; engine: IWhatsAppEngine; prepared: P; message: Message }> {
// Pacing runs BEFORE the plugin gate, so a send that policy forbids never reaches a plugin at
// all β€” plugins should not be asked to moderate, or given the chance to rewrite, traffic that is
// not going to be sent. The consequence is deliberate and documented in the hook contract: a
@@ -181,17 +180,32 @@ export class MessageSendService {
// its persisted row still drained the cold budget. Edit carries a chatId too; the edited
// message's own row already makes that chat warm, so the gate is a no-op there.
const target = input as { chatId?: string; toChatId?: string };
- const release = await this.pacing.assertSendAllowed(sessionId, target.chatId ?? target.toChatId);
+ const lifetime = captureSessionWrites(
+ this.messageRepository.manager?.connection ?? this.messageRepository,
+ sessionId,
+ );
+ let release: SettleAdmission | undefined;
// Everything a sender does before its PENDING row is written runs in here (the plugin gate, the
- // engine lookup, `prepare`), so a send that fails on the way hands its pacing admission back: with no
+ // engine lookup, preparation and initial persistence), so a failure hands its pacing admission back: with no
// row it never counts, and holding it would refuse the caller's next send near the cap.
+ let persisted = false;
try {
+ release = await this.pacing.assertSendAllowed(sessionId, target.chatId ?? target.toChatId, {
+ whilePreparing: true,
+ });
+ if (release) lifetime.onRetire(release);
+ lifetime.assertCurrent();
const finalDto = await applySendingGate(this.hookManager, sessionId, type, input, 'MessageService');
+ lifetime.assertCurrent();
const engine = this.getEngine(sessionId);
- return { finalDto, engine, prepared: prepare?.(finalDto) as P };
- } catch (error) {
- release?.();
- throw error;
+ const prepared = prepare?.(finalDto) as P;
+ const message = await this.saveOutgoingMessage(sessionId, await buildPending(finalDto, prepared), lifetime);
+ lifetime.assertCurrent();
+ persisted = true;
+ return { finalDto, engine, prepared, message };
+ } finally {
+ release?.(persisted);
+ lifetime.close();
}
}
@@ -295,21 +309,25 @@ export class MessageSendService {
async sendImage(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
const {
+ message,
finalDto,
engine,
prepared: media,
- } = await this.applySendingGate(sessionId, 'image', dto, d => this.buildMediaInput(d));
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- body: finalDto.caption || '',
- type: 'image',
- quotedMessageId: finalDto.quotedMessageId,
- metadata: {
- media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
- },
- });
+ } = await this.applySendingGate(
+ sessionId,
+ 'image',
+ dto,
+ (finalDto, media) => ({
+ chatId: finalDto.chatId,
+ body: finalDto.caption || '',
+ type: 'image',
+ quotedMessageId: finalDto.quotedMessageId,
+ metadata: {
+ media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
+ },
+ }),
+ (d: SendMediaMessageDto) => this.buildMediaInput(d),
+ );
let result: MessageResult;
try {
@@ -322,21 +340,25 @@ export class MessageSendService {
async sendVideo(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
const {
+ message,
finalDto,
engine,
prepared: media,
- } = await this.applySendingGate(sessionId, 'video', dto, d => this.buildMediaInput(d));
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- body: finalDto.caption || '',
- type: 'video',
- quotedMessageId: finalDto.quotedMessageId,
- metadata: {
- media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
- },
- });
+ } = await this.applySendingGate(
+ sessionId,
+ 'video',
+ dto,
+ (finalDto, media) => ({
+ chatId: finalDto.chatId,
+ body: finalDto.caption || '',
+ type: 'video',
+ quotedMessageId: finalDto.quotedMessageId,
+ metadata: {
+ media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
+ },
+ }),
+ (d: SendMediaMessageDto) => this.buildMediaInput(d),
+ );
let result: MessageResult;
try {
@@ -352,29 +374,32 @@ export class MessageSendService {
// persisted row all carry the same type for one outbound voice note β€” failSend and the saved row
// already use `finalDto.ptt ? 'voice' : 'audio'`.
const {
+ message,
finalDto,
engine,
- prepared: { audioDto, media },
- } = await this.applySendingGate(sessionId, dto.ptt ? 'voice' : 'audio', dto, gated => {
- // Voice notes need a real audio codec; default to ogg/opus when the caller omits a mimetype so the
- // wire message and the persisted record agree. Resolved BEFORE buildMediaInput so its base64
- // mimetype guard sees the effective type. buildMediaInput itself stays generic (shared by all media).
- const audioDto = gated.ptt && !gated.mimetype ? { ...gated, mimetype: 'audio/ogg; codecs=opus' } : gated;
- const media = this.buildMediaInput(audioDto);
- media.ptt = gated.ptt;
- return { audioDto, media };
- });
-
- // Save message as pending BEFORE sending. A PTT send is a 'voice' note (matches inbound
- // classification, the outbound webhook echo, stats, and the dashboard), not a plain 'audio' file.
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- type: finalDto.ptt ? 'voice' : 'audio',
- metadata: {
- media: { mimetype: audioDto.mimetype, filename: finalDto.filename, data: media.data },
+ prepared: { media },
+ } = await this.applySendingGate(
+ sessionId,
+ dto.ptt ? 'voice' : 'audio',
+ dto,
+ (finalDto, { audioDto, media }) => ({
+ chatId: finalDto.chatId,
+ type: finalDto.ptt ? 'voice' : 'audio',
+ metadata: {
+ media: { mimetype: audioDto.mimetype, filename: finalDto.filename, data: media.data },
+ },
+ quotedMessageId: finalDto.quotedMessageId,
+ }),
+ (gated: SendAudioMessageDto) => {
+ // Voice notes need a real audio codec; default to ogg/opus when the caller omits a mimetype so the
+ // wire message and the persisted record agree. Resolved BEFORE buildMediaInput so its base64
+ // mimetype guard sees the effective type. buildMediaInput itself stays generic (shared by all media).
+ const audioDto = gated.ptt && !gated.mimetype ? { ...gated, mimetype: 'audio/ogg; codecs=opus' } : gated;
+ const media = this.buildMediaInput(audioDto);
+ media.ptt = gated.ptt;
+ return { audioDto, media };
},
- quotedMessageId: finalDto.quotedMessageId,
- });
+ );
let result: MessageResult;
try {
@@ -387,21 +412,25 @@ export class MessageSendService {
async sendDocument(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
const {
+ message,
finalDto,
engine,
prepared: media,
- } = await this.applySendingGate(sessionId, 'document', dto, d => this.buildMediaInput(d));
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- body: finalDto.caption || finalDto.filename || '',
- type: 'document',
- quotedMessageId: finalDto.quotedMessageId,
- metadata: {
- media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
- },
- });
+ } = await this.applySendingGate(
+ sessionId,
+ 'document',
+ dto,
+ (finalDto, media) => ({
+ chatId: finalDto.chatId,
+ body: finalDto.caption || finalDto.filename || '',
+ type: 'document',
+ quotedMessageId: finalDto.quotedMessageId,
+ metadata: {
+ media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
+ },
+ }),
+ (d: SendMediaMessageDto) => this.buildMediaInput(d),
+ );
let result: MessageResult;
try {
@@ -423,15 +452,12 @@ export class MessageSendService {
quotedMessageId?: string;
},
): Promise<MessageResponseDto> {
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'location', dto);
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
+ const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'location', dto, finalDto => ({
chatId: finalDto.chatId,
body: `πŸ“ ${finalDto.description || 'Location'}`,
type: 'location',
quotedMessageId: finalDto.quotedMessageId,
- });
+ }));
let result: MessageResult;
try {
@@ -452,15 +478,12 @@ export class MessageSendService {
sessionId: string,
dto: { chatId: string; contactName: string; contactNumber: string; quotedMessageId?: string },
): Promise<MessageResponseDto> {
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'contact', dto);
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
+ const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'contact', dto, finalDto => ({
chatId: finalDto.chatId,
body: `πŸ“‡ ${finalDto.contactName}`,
type: 'contact',
quotedMessageId: finalDto.quotedMessageId,
- });
+ }));
let result: MessageResult;
try {
@@ -479,11 +502,7 @@ export class MessageSendService {
sessionId: string,
dto: { chatId: string; name: string; options: string[]; allowMultipleAnswers?: boolean; quotedMessageId?: string },
): Promise<MessageResponseDto> {
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'poll', dto);
-
- // Save message as pending BEFORE sending. A poll has no plain-text body, so store the
- // question β€” that keeps the message history readable.
- const message = await this.saveOutgoingMessage(sessionId, {
+ const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'poll', dto, finalDto => ({
chatId: finalDto.chatId,
body: `πŸ“Š ${finalDto.name}`,
type: 'poll',
@@ -495,7 +514,7 @@ export class MessageSendService {
},
},
quotedMessageId: finalDto.quotedMessageId,
- });
+ }));
let result: MessageResult;
try {
@@ -513,20 +532,24 @@ export class MessageSendService {
async sendSticker(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
const {
+ message,
finalDto,
engine,
prepared: media,
- } = await this.applySendingGate(sessionId, 'sticker', dto, d => this.buildMediaInput(d));
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- type: 'sticker',
- quotedMessageId: finalDto.quotedMessageId,
- metadata: {
- media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
- },
- });
+ } = await this.applySendingGate(
+ sessionId,
+ 'sticker',
+ dto,
+ (finalDto, media) => ({
+ chatId: finalDto.chatId,
+ type: 'sticker',
+ quotedMessageId: finalDto.quotedMessageId,
+ metadata: {
+ media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
+ },
+ }),
+ (d: SendMediaMessageDto) => this.buildMediaInput(d),
+ );
let result: MessageResult;
try {
@@ -541,19 +564,16 @@ export class MessageSendService {
sessionId: string,
dto: { chatId: string; quotedMessageId: string; text: string; mentions?: string[] },
): Promise<MessageResponseDto> {
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'reply', dto);
-
- // Resolve the quoted message body (best-effort) so the dashboard can render the reply preview.
- const quotedBody = await this.resolveQuotedBody(sessionId, finalDto.quotedMessageId, finalDto.chatId);
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- body: finalDto.text,
- type: 'text',
- metadata: {
- quotedMessage: { id: finalDto.quotedMessageId, body: quotedBody },
- },
+ const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'reply', dto, async finalDto => {
+ const quotedBody = await this.resolveQuotedBody(sessionId, finalDto.quotedMessageId, finalDto.chatId);
+ return {
+ chatId: finalDto.chatId,
+ body: finalDto.text,
+ type: 'text',
+ metadata: {
+ quotedMessage: { id: finalDto.quotedMessageId, body: quotedBody },
+ },
+ };
});
let result: MessageResult;
@@ -573,22 +593,23 @@ export class MessageSendService {
sessionId: string,
dto: { chatId: string; messageId: string; buttonId: string; text?: string },
): Promise<MessageResponseDto> {
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'click-button', dto);
-
- // A click IS a reply to the prompt, so resolve the prompt's body the way reply() does: the
- // dashboard renders the quote box from this field, and a hardcoded empty string left every
- // answered prompt showing an empty quote above the choice the user tapped.
- const promptBody = await this.resolveQuotedBody(sessionId, finalDto.messageId, finalDto.chatId);
-
- const message = await this.saveOutgoingMessage(sessionId, {
- chatId: finalDto.chatId,
- body: finalDto.text || finalDto.buttonId,
- type: 'text',
- metadata: {
- quotedMessage: { id: finalDto.messageId, body: promptBody },
- button: { id: finalDto.buttonId, text: finalDto.text },
+ const { message, finalDto, engine } = await this.applySendingGate(
+ sessionId,
+ 'click-button',
+ dto,
+ async finalDto => {
+ const promptBody = await this.resolveQuotedBody(sessionId, finalDto.messageId, finalDto.chatId);
+ return {
+ chatId: finalDto.chatId,
+ body: finalDto.text || finalDto.buttonId,
+ type: 'text',
+ metadata: {
+ quotedMessage: { id: finalDto.messageId, body: promptBody },
+ button: { id: finalDto.buttonId, text: finalDto.text },
+ },
+ };
},
- });
+ );
let result: MessageResult;
try {
@@ -612,14 +633,11 @@ export class MessageSendService {
sessionId: string,
dto: { fromChatId: string; toChatId: string; messageId: string },
): Promise<MessageResponseDto> {
- const { finalDto, engine } = await this.applySendingGate(sessionId, 'forward', dto);
-
- // Save message as pending BEFORE sending
- const message = await this.saveOutgoingMessage(sessionId, {
+ const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'forward', dto, finalDto => ({
chatId: finalDto.toChatId,
body: '[Forwarded]',
type: 'forward',
- });
+ }));
let result: MessageResult;
try {
@@ -686,73 +704,87 @@ export class MessageSendService {
* failing, mirroring `persistSentState`: the echo carries only what the engine reported (for a
* Baileys API send, a media-less marker), so dropping this write would lose the media payload.
*/
- async saveOutgoingMessage(sessionId: string, data: SaveOutgoingMessageData): Promise<Message> {
- const session = await this.sessionService.findOne(sessionId);
- // Resolved here rather than in each sender: reply and click-button build their own
- // `metadata.quotedMessage` and never reach this branch, so every OTHER quoting sender (media,
- // location, contact, poll, quoted text) used to persist an id with an empty body and the
- // dashboard drew a blank quote box above the message.
- const quotedMessage = data.quotedMessageId
- ? { id: data.quotedMessageId, body: await this.resolveQuotedBody(sessionId, data.quotedMessageId) }
- : undefined;
- const message = this.messageRepository.create({
- sessionId,
- // An engine that sent a message but could not read its id back reports an empty id (see the
- // whatsapp-web.js adapter's `toMessageResult`). Store NULL rather than '': the
- // (sessionId, waMessageId) unique index is not partial, so a second id-less send in the same
- // session collides on '' while NULLs stay exempt β€” and in the bulk path that violation is
- // swallowed into a warning, losing the row silently. Normalizing at this one chokepoint covers
- // every caller instead of relying on each to remember.
- waMessageId: data.waMessageId || undefined,
- chatId: data.chatId,
- from: session?.phone || 'me',
- to: data.chatId,
- body: data.body,
- type: data.type,
- direction: MessageDirection.OUTGOING,
- timestamp: data.timestamp,
- status: data.status ?? MessageStatus.PENDING,
- metadata: quotedMessage ? { ...data.metadata, quotedMessage } : data.metadata,
- });
- // No transaction of its own: the unique violation handled below is routine (the own-send echo wins the
- // race), and on SQLite's single shared connection its rollback would discard what other callers wrote
- // while it was open, after they were told it was stored.
- const saved = await this.messageRepository.save(message, { transaction: false }).catch(async (err: unknown) => {
- const waMessageId = message.waMessageId;
- if (!waMessageId || !isUniqueViolation(err)) throw err;
- // No `status` here on purpose. The row this collides with is the own-send echo's, inserted
- // SENT, and the ack path advances it forward-only (ackStatusTransitionFrom). This write only
- // ever carries PENDING or SENT, so it can never be an upgrade: it is a no-op, or it drags a
- // DELIVERED/READ row back to SENT when an ack won the race. Leave the delivery state to the
- // one writer that owns it.
- const patch: QueryDeepPartialEntity<Message> = {
- timestamp: message.timestamp,
- };
- // Only when this write actually carries metadata worth merging: a text item must not blank
- // the echo's, and a URL pointer must not replace bytes the engine already downloaded.
- const metadata = message.metadata;
- if (metadata && !isUrlPointerMetadata(metadata)) {
- try {
- await updateMessageMetadata(this.messageRepository, { sessionId, waMessageId }, current =>
- mergeSentMetadata(current, metadata),
- );
- } catch (error) {
- if (message.status !== MessageStatus.SENT) throw error;
- this.logger.warn(`Merging sent metadata onto the echo row failed (id=${waMessageId})`, {
- error: error instanceof Error ? error.message : String(error),
- });
- // The bulk engine has already sent this item. Keep its media in an id-less SENT row
- // when the echo cannot accept it, instead of losing the only payload-bearing copy.
- return this.messageRepository.save(this.messageRepository.create({ ...message, waMessageId: undefined }));
- }
- }
- if (message.timestamp !== undefined) await this.messageRepository.update({ sessionId, waMessageId }, patch);
- const surviving = await this.messageRepository.findOne({ where: { sessionId, waMessageId } });
- if (!surviving) throw err;
- return surviving;
- });
- this.emitPersisted(sessionId, saved);
- return saved;
+ async saveOutgoingMessage(
+ sessionId: string,
+ data: SaveOutgoingMessageData,
+ lifetime?: SessionWriteScope,
+ ): Promise<Message> {
+ const scope =
+ lifetime ?? captureSessionWrites(this.messageRepository.manager?.connection ?? this.messageRepository, sessionId);
+ try {
+ const session = await this.sessionService.findOne(sessionId);
+ // Resolved here rather than in each sender: reply and click-button build their own
+ // `metadata.quotedMessage` and never reach this branch, so every OTHER quoting sender (media,
+ // location, contact, poll, quoted text) used to persist an id with an empty body and the
+ // dashboard drew a blank quote box above the message.
+ const quotedMessage = data.quotedMessageId
+ ? { id: data.quotedMessageId, body: await this.resolveQuotedBody(sessionId, data.quotedMessageId) }
+ : undefined;
+ const message = this.messageRepository.create({
+ sessionId,
+ // An engine that sent a message but could not read its id back reports an empty id (see the
+ // whatsapp-web.js adapter's `toMessageResult`). Store NULL rather than '': the
+ // (sessionId, waMessageId) unique index is not partial, so a second id-less send in the same
+ // session collides on '' while NULLs stay exempt β€” and in the bulk path that violation is
+ // swallowed into a warning, losing the row silently. Normalizing at this one chokepoint covers
+ // every caller instead of relying on each to remember.
+ waMessageId: data.waMessageId || undefined,
+ chatId: data.chatId,
+ from: session?.phone || 'me',
+ to: data.chatId,
+ body: data.body,
+ type: data.type,
+ direction: MessageDirection.OUTGOING,
+ timestamp: data.timestamp,
+ status: data.status ?? MessageStatus.PENDING,
+ metadata: quotedMessage ? { ...data.metadata, quotedMessage } : data.metadata,
+ });
+ // No transaction of its own: the unique violation handled below is routine (the own-send echo wins the
+ // race), and on SQLite's single shared connection its rollback would discard what other callers wrote
+ // while it was open, after they were told it was stored.
+ const saved = await scope
+ .write(() => this.messageRepository.save(message, { transaction: false }))
+ .catch(async (err: unknown) => {
+ const waMessageId = message.waMessageId;
+ if (!waMessageId || !isUniqueViolation(err)) throw err;
+ // No `status` here on purpose. The row this collides with is the own-send echo's, inserted
+ // SENT, and the ack path advances it forward-only (ackStatusTransitionFrom). This write only
+ // ever carries PENDING or SENT, so it can never be an upgrade: it is a no-op, or it drags a
+ // DELIVERED/READ row back to SENT when an ack won the race. Leave the delivery state to the
+ // one writer that owns it.
+ const patch: QueryDeepPartialEntity<Message> = {
+ timestamp: message.timestamp,
+ };
+ // Only when this write actually carries metadata worth merging: a text item must not blank
+ // the echo's, and a URL pointer must not replace bytes the engine already downloaded.
+ const metadata = message.metadata;
+ if (metadata && !isUrlPointerMetadata(metadata)) {
+ try {
+ await updateMessageMetadata(this.messageRepository, { sessionId, waMessageId }, current =>
+ mergeSentMetadata(current, metadata),
+ );
+ } catch (error) {
+ if (message.status !== MessageStatus.SENT) throw error;
+ this.logger.warn(`Merging sent metadata onto the echo row failed (id=${waMessageId})`, {
+ error: error instanceof Error ? error.message : String(error),
+ });
+ // The bulk engine has already sent this item. Keep its media in an id-less SENT row
+ // when the echo cannot accept it, instead of losing the only payload-bearing copy.
+ return scope.write(() =>
+ this.messageRepository.save(this.messageRepository.create({ ...message, waMessageId: undefined })),
+ );
+ }
+ }
+ if (message.timestamp !== undefined) await this.messageRepository.update({ sessionId, waMessageId }, patch);
+ const surviving = await this.messageRepository.findOne({ where: { sessionId, waMessageId } });
+ if (!surviving) throw err;
+ return surviving;
+ });
+ this.emitPersisted(sessionId, saved);
+ return saved;
+ } finally {
+ if (!lifetime) scope.close();
+ }
}
// Fire-and-forget: a plugin handler must never break the send path. The built-in FTS search provider
@@ -794,7 +826,14 @@ export class MessageSendService {
delete media.data;
}
message.status = MessageStatus.FAILED;
- await this.messageRepository.save(message);
+ const result = await this.messageRepository.update(
+ { id: message.id, sessionId: message.sessionId },
+ {
+ status: MessageStatus.FAILED,
+ metadata: message.metadata as QueryDeepPartialEntity<Record<string, unknown>>,
+ },
+ );
+ if (!result.affected) return;
// Reconcile the earlier PENDING emission (#906): a provider must see the terminal FAILED state.
this.emitPersisted(message.sessionId, message);
}
@@ -817,7 +856,16 @@ export class MessageSendService {
message.timestamp = result.timestamp;
try {
// No transaction of its own, for the reason given at the first save of this message.
- await this.messageRepository.save(message, { transaction: false });
+ const updated = await this.messageRepository.update(
+ { id: message.id, sessionId: message.sessionId },
+ {
+ waMessageId: message.waMessageId,
+ status: message.status,
+ timestamp: message.timestamp,
+ metadata: message.metadata as QueryDeepPartialEntity<Record<string, unknown>>,
+ },
+ );
+ if (!updated.affected) return { messageId: result.id, timestamp: result.timestamp };
// Reconcile the earlier PENDING emission with the finalized row (#906).
this.emitPersisted(message.sessionId, message);
} catch (persistError) {
diff --git a/src/modules/message/message.service.ts b/src/modules/message/message.service.ts
index d2bd3c67e..3762bb81c 100644
--- a/src/modules/message/message.service.ts
+++ b/src/modules/message/message.service.ts
@@ -15,6 +15,7 @@ import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.
import { ChatMediaArchiveService } from '../chat-media/chat-media-archive.service';
import { StorageService, isMissingObjectError } from '../../common/storage/storage.service';
import { MessageSendService, SaveOutgoingMessageData } from './message-send.service';
+import { SessionWriteScope } from '../../common/utils/session-write-scope';
// Type-only: the module binds this class to PLUGIN_MESSAGE_PORT with a `useExisting` alias, which
// TypeScript does not check, so `implements` is what keeps the two in step.
import type { PluginMessagePort } from '../../core/plugins/plugin-host-ports';
@@ -288,8 +289,12 @@ export class MessageService implements PluginMessagePort {
}
/** Persist an outbound row; exposed for the bulk path, which reuses the send-persistence rules. */
- saveOutgoingMessage(sessionId: string, data: SaveOutgoingMessageData): Promise<Message> {
- return this.sender.saveOutgoingMessage(sessionId, data);
+ saveOutgoingMessage(
+ sessionId: string,
+ data: SaveOutgoingMessageData,
+ lifetime?: SessionWriteScope,
+ ): Promise<Message> {
+ return this.sender.saveOutgoingMessage(sessionId, data, lifetime);
}
/**
diff --git a/src/modules/message/send-pacing.service.spec.ts b/src/modules/message/send-pacing.service.spec.ts
index a41af8a88..c951158e4 100644
--- a/src/modules/message/send-pacing.service.spec.ts
+++ b/src/modules/message/send-pacing.service.spec.ts
@@ -1,3 +1,4 @@
+import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
import {
BadRequestException,
HttpException,
@@ -85,6 +86,15 @@ const expectPacingRefusal = async (promise: Promise<unknown>): Promise<Record<st
describe('SendPacingService', () => {
beforeEach(() => resetSendPacingRefusals());
+ it('settles an admission only once', async () => {
+ const { service } = build({ warmupSchedule: [1] });
+ const settle = await service.assertSendAllowed('s1', '[email protected]', { whilePreparing: true });
+ settle?.(true);
+ settle?.();
+
+ await expectPacingRefusal(service.assertSendAllowed('s1', '[email protected]'));
+ });
+
describe('when disabled', () => {
// The disabled path must cost nothing and change nothing β€” a deployment that has not opted in
// has to behave exactly as it did before this feature existed, including doing no DB work.
@@ -328,7 +338,7 @@ describe('send paths consult the governor', () => {
// The recipient must reach the governor too: without it the cold-reachout rule has nothing to
// classify and silently degrades to the overall cap.
- expect(pacing.assertSendAllowed).toHaveBeenCalledWith('s1', '[email protected]');
+ expect(pacing.assertSendAllowed).toHaveBeenCalledWith('s1', '[email protected]', { whilePreparing: true });
// The ordering decision, pinned: a paced-out send is never offered to plugins, so no
// `message:sending` fires and nothing is persisted or sent.
expect(hookManager.execute).not.toHaveBeenCalled();
@@ -421,7 +431,15 @@ describe('send paths consult the governor', () => {
pacing as never,
);
- await (service as unknown as { processBatch: (id: string) => Promise<void> }).processBatch('b1');
+ await (
+ service as unknown as {
+ processBatch: (id: string, reserved: boolean, lifetime: SessionWriteScope) => Promise<void>;
+ }
+ ).processBatch(
+ 'b1',
+ false,
+ captureSessionWrites((service as unknown as { batchRepository: object }).batchRepository, 's1'),
+ );
expect(pacing.assertSendAllowed).toHaveBeenCalledWith('s1', '[email protected]', { untilSettled: true });
expect(hookManager.execute).not.toHaveBeenCalledWith('message:sending', expect.anything(), expect.anything());
diff --git a/src/modules/message/send-pacing.service.ts b/src/modules/message/send-pacing.service.ts
index dfd72662c..a6a447b2f 100644
--- a/src/modules/message/send-pacing.service.ts
+++ b/src/modules/message/send-pacing.service.ts
@@ -108,12 +108,13 @@ interface Admission {
until: number;
/** Epoch ms it stops being held, so only its row counts from then on; refreshed by heldAdmissions. */
heldUntil: number;
- sentToday: number;
+ /** Reset at UTC rollover, then filled from the first current-day count. */
+ sentToday: number | null;
/**
* Set for a cold send; the key is folded the way the cold count folds dialects. Cleared by heldAdmissions
* once no cold admission's own term is running, so from then on only its row counts against the cold cap.
*/
- cold: { key: string; coldToday: number } | null;
+ cold: { key: string; coldToday: number | null } | null;
}
/** The admissions a session holds, in the order they were admitted, for one UTC day. */
@@ -141,8 +142,8 @@ const UNSETTLED_ADMISSION_MAX_MS = 5 * 60_000;
/**
* Settles the admission assertSendAllowed held. Called with nothing, for a send that provably never went
- * out, it hands the admission back at once. Called with `true`, once the engine returned or failed with an
- * unknown outcome, it holds the admission for ADMISSION_WINDOW_MS from now, while the row or the own-send
+ * out, it hands the admission back at once. Called with `true`, once PENDING is written or the engine returned
+ * or failed with an unknown outcome, it holds the admission for ADMISSION_WINDOW_MS while the row or own-send
* echo lands, or for as long as a send admitted after it is held, if that is longer.
*/
export type SettleAdmission = (mayHaveSent?: boolean) => void;
@@ -242,6 +243,8 @@ export class SendPacingService {
* after the engine call (a bulk item, a product send): the window starts when the caller settles it
* with `true`, bounded by UNSETTLED_ADMISSION_MAX_MS if it never does. Without it the window starts
* now, for a caller that writes its PENDING row before asking the engine.
+ * `whilePreparing` has no safety expiry: its caller must settle in a finally block once the
+ * PENDING write finishes or preparation fails, even when hooks take arbitrarily long.
*
* Returns the settle for the admission it held, or undefined when it held none. A caller whose send
* fails before writing a row, and before WhatsApp may have taken it, calls it with nothing so that
@@ -250,7 +253,7 @@ export class SendPacingService {
async assertSendAllowed(
sessionId: string,
chatId?: string,
- opts: { hold?: boolean; untilSettled?: boolean } = {},
+ opts: { hold?: boolean; untilSettled?: boolean; whilePreparing?: boolean } = {},
): Promise<SettleAdmission | undefined> {
const config = resolveSendPacingConfig(this.configService);
if (!config.enabled) return;
@@ -283,7 +286,9 @@ export class SendPacingService {
this.assertUnderColdCap(sessionId, dayStart, ageDays, cold);
}
if (opts.hold !== false) {
- const until = Date.now() + (opts.untilSettled ? UNSETTLED_ADMISSION_MAX_MS : ADMISSION_WINDOW_MS);
+ const until = opts.whilePreparing
+ ? Infinity
+ : Date.now() + (opts.untilSettled ? UNSETTLED_ADMISSION_MAX_MS : ADMISSION_WINDOW_MS);
const admission: Admission = {
until,
heldUntil: until,
@@ -293,7 +298,10 @@ export class SendPacingService {
const hold = this.holds.get(sessionId);
if (hold?.dayStartMs === dayStart.getTime()) hold.admissions.push(admission);
else this.holds.set(sessionId, { dayStartMs: dayStart.getTime(), admissions: [admission] });
+ let settled = false;
return (mayHaveSent = false) => {
+ if (settled) return;
+ settled = true;
if (mayHaveSent) {
admission.until = Date.now() + ADMISSION_WINDOW_MS;
return;
@@ -302,7 +310,10 @@ export class SendPacingService {
admission.until = admission.heldUntil = 0;
const admissions = this.holds.get(sessionId)?.admissions;
const index = admissions?.indexOf(admission) ?? -1;
- if (admissions && index !== -1) admissions.splice(index, 1);
+ if (admissions && index !== -1) {
+ admissions.splice(index, 1);
+ if (admissions.length === 0) this.holds.delete(sessionId);
+ }
};
}
}
@@ -316,16 +327,27 @@ export class SendPacingService {
for (let i = held.length - 1; i >= 0; i--) {
const cold = held[i].cold;
if (!cold) continue;
+ cold.coldToday ??= persisted;
chats.add(cold.key);
count = Math.max(count, cold.coldToday + chats.size);
}
return count;
}
- /** This session's held admissions today, oldest first; empty once none of them is held or the day rolled. */
+ /** This session's held admissions today, oldest first, including preparations carried across midnight. */
private heldAdmissions(sessionId: string, dayStart: Date): Admission[] {
const hold = this.holds.get(sessionId);
if (!hold) return [];
+ if (hold.dayStartMs !== dayStart.getTime()) {
+ // Preparing sends still have no row to count today. Keep their settlement identity and rebase
+ // their snapshots on the new day's first count; yesterday's finite holds have expired.
+ hold.admissions = hold.admissions.filter(a => a.until === Infinity);
+ hold.dayStartMs = dayStart.getTime();
+ for (const admission of hold.admissions) {
+ admission.sentToday = null;
+ if (admission.cold) admission.cold.coldToday = null;
+ }
+ }
const now = Date.now();
// The cold terms lapse as a whole, once no cold admission's own term is running: a warm admission read no
// cold count, so it cannot have missed a cold row, and letting it hold them would keep a cold send that
@@ -550,7 +572,10 @@ export class SendPacingService {
persisted: number,
): void {
const held = this.heldAdmissions(sessionId, dayStart);
- const sentToday = held.reduce((max, a, i) => Math.max(max, a.sentToday + held.length - i), persisted);
+ const sentToday = held.reduce((max, a, i) => {
+ a.sentToday ??= persisted;
+ return Math.max(max, a.sentToday + held.length - i);
+ }, persisted);
if (sentToday < allowance) return;
const retryAfter =
diff --git a/src/modules/session/session-content-lifetime.spec.ts b/src/modules/session/session-content-lifetime.spec.ts
new file mode 100644
index 000000000..24e81732e
--- /dev/null
+++ b/src/modules/session/session-content-lifetime.spec.ts
@@ -0,0 +1,306 @@
+import { ConfigService } from '@nestjs/config';
+import { randomUUID } from 'crypto';
+import { DataSource } from 'typeorm';
+import { Session } from './entities/session.entity';
+import { Message } from '../message/entities/message.entity';
+import { MessageBatch } from '../message/entities/message-batch.entity';
+import { SendIdempotencyKey } from '../message/entities/send-idempotency-key.entity';
+import { Webhook } from '../webhook/entities/webhook.entity';
+import { WebhookOutboxEvent } from '../webhook/entities/webhook-outbox-event.entity';
+import { WebhookDeliveryFailure } from '../webhook/entities/webhook-delivery-failure.entity';
+import { IntegrationDeliveryFailure } from '../integration/entities/integration-delivery-failure.entity';
+import { Template } from '../template/entities/template.entity';
+import { BaileysStoredMessage } from '../../engine/adapters/baileys-stored-message.entity';
+import { ChatState } from '../../engine/adapters/baileys-chat-state.entity';
+import { StatusUpdate } from '../status-store/entities/status-update.entity';
+import { EngineRegistry } from '../../engine/engine-registry.service';
+import { IWhatsAppEngine, MessageResult } from '../../engine/interfaces/whatsapp-engine.interface';
+import { HookManager } from '../../core/hooks';
+import { SessionEngineControls, StopMarks } from './session-engine-controls';
+import { SessionLifecycleFences } from './session-lifecycle-fences';
+import { SessionEngineLeafEvents } from './session-engine-leaf-events';
+import { MessageSendService } from '../message/message-send.service';
+import { SessionService } from './session.service';
+import { TemplateService } from '../template/template.service';
+import { SendPacingService } from '../message/send-pacing.service';
+import { StatusStoreService } from '../status-store/status-store.service';
+import { StorageService } from '../../common/storage/storage.service';
+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
+
+function deferred<T = void>() {
+ let resolve!: (value: T | PromiseLike<T>) => void;
+ let reject!: (reason: unknown) => void;
+ const promise = new Promise<T>((yes, no) => {
+ resolve = yes;
+ reject = no;
+ });
+ return { promise, resolve, reject };
+}
+
+const entities = [
+ Session,
+ Message,
+ MessageBatch,
+ SendIdempotencyKey,
+ Webhook,
+ WebhookOutboxEvent,
+ WebhookDeliveryFailure,
+ IntegrationDeliveryFailure,
+ Template,
+ BaileysStoredMessage,
+ ChatState,
+ StatusUpdate,
+];
+
+describe('Session content lifetime', () => {
+ let db: DataSource;
+ let controls: SessionEngineControls;
+ let engines: EngineRegistry;
+ let hooks: HookManager;
+ const config = new ConfigService({});
+ const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() };
+
+ beforeEach(async () => {
+ 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: `session_content_${randomUUID().replace(/-/g, '')}`,
+ entities,
+ synchronize: false,
+ }
+ : { type: 'better-sqlite3', database: ':memory:', entities, synchronize: true },
+ );
+ await db.initialize();
+ if (db.options.type === 'postgres') {
+ await db.query(`CREATE SCHEMA "${db.options.schema}"`);
+ await db.synchronize();
+ }
+ engines = new EngineRegistry();
+ hooks = new HookManager();
+ const state = { attachTo: <T>(value: T) => value, clear: jest.fn() };
+ const fences = new SessionLifecycleFences({
+ engines,
+ pendingTeardowns: new Map(),
+ pendingInitialStatuses: new Map(),
+ logger: logger as unknown as ConstructorParameters<typeof SessionLifecycleFences>[0]['logger'],
+ });
+ controls = new SessionEngineControls({
+ sessionRepository: db.getRepository(Session),
+ engineFactory: { purgeSessionData: () => Promise.resolve() },
+ engines,
+ sessionErrors: state,
+ sessionRestrictions: state,
+ presence: state,
+ hookManager: hooks,
+ configService: config,
+ logger,
+ dataSource: () => db,
+ fences,
+ broadcaster: state,
+ cancelReconnect() {},
+ isClosed: () => false,
+ ownsSession: () => true,
+ stoppingSessions: new StopMarks(),
+ operatorTeardowns: new Map(),
+ reconnectStates: new Map(),
+ stuckAuthRecoveryUsed: new Set(),
+ initializingSessions: new Set(),
+ } as unknown as ConstructorParameters<typeof SessionEngineControls>[0]);
+ });
+ afterEach(async () => {
+ jest.restoreAllMocks();
+ if (db.isInitialized) {
+ if (db.options.type === 'postgres') await db.query(`DROP SCHEMA "${db.options.schema}" CASCADE`);
+ await db.destroy();
+ }
+ });
+
+ async function createSession() {
+ return db.getRepository(Session).save({ name: 'test-session', config: {} });
+ }
+
+ function sender(engine: object, sessionId: string) {
+ engines.set(sessionId, engine as IWhatsAppEngine);
+ return new MessageSendService(
+ db.getRepository(Message),
+ {
+ findOne: (id: string) => db.getRepository(Session).findOneByOrFail({ id }),
+ } as unknown as SessionService,
+ engines,
+ hooks,
+ {} as TemplateService,
+ new SendPacingService(db.getRepository(Message), db.getRepository(Session), new ConfigService({})),
+ new ConfigService({ features: { simulateTyping: false } }),
+ );
+ }
+
+ it.each(['accepted', 'refused'])('keeps deleted messages absent when an %s engine call settles', async outcome => {
+ const session = await createSession();
+ const started = deferred();
+ const result = deferred<MessageResult>();
+ const service = sender(
+ {
+ sendChatState: () => Promise.resolve(),
+ forceDestroy: () => Promise.resolve(),
+ sendTextMessage: () => {
+ started.resolve();
+ return result.promise;
+ },
+ },
+ session.id,
+ );
+ const oldTyping = process.env.SIMULATE_TYPING;
+ process.env.SIMULATE_TYPING = 'false';
+ try {
+ const send = service.sendText(session.id, { chatId: '[email protected]', text: 'test body' });
+ const settled = send.then(
+ () => undefined,
+ () => undefined,
+ );
+ await started.promise;
+ await controls.delete(session.id);
+ expect(await db.getRepository(Message).count()).toBe(0);
+ if (outcome === 'accepted') result.resolve({ id: 'sent-id', timestamp: 1700000000 });
+ else result.reject(new EngineNotReadyError());
+ await settled;
+ expect(await db.getRepository(Message).count()).toBe(0);
+ } finally {
+ if (oldTyping === undefined) delete process.env.SIMULATE_TYPING;
+ else process.env.SIMULATE_TYPING = oldTyping;
+ }
+ });
+
+ it('drains an admitted initial database write before removing its parent', async () => {
+ const session = await createSession();
+ const service = sender({ forceDestroy: () => Promise.resolve() }, session.id);
+ const repo = db.getRepository(Message);
+ const save = repo.save.bind(repo);
+ const started = deferred();
+ const resume = deferred();
+ jest.spyOn(repo, 'save').mockImplementationOnce(async value => {
+ started.resolve();
+ await resume.promise;
+ return save(value);
+ });
+ const write = service.saveOutgoingMessage(session.id, { chatId: '[email protected]', type: 'text', body: 'test' });
+ const settled = write.then(
+ () => undefined,
+ () => undefined,
+ );
+ await started.promise;
+ const deletion = controls.delete(session.id);
+ await new Promise<void>(setImmediate);
+ resume.resolve();
+ await Promise.all([deletion, settled]);
+ expect(await db.getRepository(Session).count()).toBe(0);
+ expect(await repo.count()).toBe(0);
+ });
+
+ it.each(['success', 'failure'])('does not recreate a status after a late media %s', async outcome => {
+ const session = await createSession();
+ const started = deferred();
+ const media = deferred();
+ const store = new StatusStoreService(
+ db.getRepository(StatusUpdate),
+ {
+ putFile: () => {
+ started.resolve();
+ return media.promise;
+ },
+ } as unknown as StorageService,
+ config,
+ );
+ const ingest = store.ingest(session.id, {
+ waStatusId: 'story',
+ contactJid: '[email protected]',
+ type: 'image',
+ caption: 'test story',
+ postedAt: Date.now(),
+ media: { data: Buffer.from('test').toString('base64'), mimetype: 'image/png' },
+ });
+ await started.promise;
+ await controls.delete(session.id);
+ if (outcome === 'success') media.resolve();
+ else media.reject(new Error('storage unavailable'));
+ await ingest;
+ expect(await db.getRepository(StatusUpdate).count()).toBe(0);
+ expect(await store.list(session.id)).toEqual([]);
+ });
+
+ it.each([false, true])('drops a seed after a deleted parent, including same-id replacement=%s', async recreate => {
+ const session = await createSession();
+ const id = session.id;
+ const started = deferred();
+ const poster = deferred<null>();
+ const engine = {
+ forceDestroy: () => Promise.resolve(),
+ getChatHistory: () =>
+ Promise.resolve([
+ {
+ id: 'story',
+ isStatusBroadcast: true,
+ author: '[email protected]',
+ from: 'status@broadcast',
+ fromMe: false,
+ type: 'text',
+ body: 'test story',
+ timestamp: Math.floor(Date.now() / 1000),
+ },
+ ]),
+ getContactById: () => {
+ started.resolve();
+ return poster.promise;
+ },
+ };
+ engines.set(id, engine as unknown as IWhatsAppEngine);
+ const store = new StatusStoreService(db.getRepository(StatusUpdate), {} as StorageService, config);
+ const leaf = new SessionEngineLeafEvents({
+ sessionRepository: db.getRepository(Session),
+ statusStore: store,
+ configService: config,
+ logger,
+ } as unknown as ConstructorParameters<typeof SessionEngineLeafEvents>[0]);
+ const seed = leaf.seedStatuses(id, engine as unknown as IWhatsAppEngine);
+ await started.promise;
+ await controls.delete(id);
+ if (recreate) await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ poster.reject(new Error('engine closed'));
+ await seed;
+ expect(await db.getRepository(StatusUpdate).count()).toBe(0);
+ });
+ it('refuses a pre-send continuation after the session id was replaced', async () => {
+ const session = await createSession();
+ const id = session.id;
+ const started = deferred();
+ const resume = deferred();
+ hooks.register('test-plugin', 'message:sending', async context => {
+ started.resolve();
+ await resume.promise;
+ return { continue: true, data: context.data };
+ });
+ const service = sender({ forceDestroy: () => Promise.resolve() }, id);
+ const send = service.sendText(id, { chatId: '[email protected]', text: 'test body' });
+ const settled = send.then(
+ () => 'sent',
+ () => 'refused',
+ );
+ await started.promise;
+ await controls.delete(id);
+ await db.getRepository(Session).save({ id, name: 'replacement', config: {} });
+ const replacementSend = jest.fn().mockResolvedValue({ id: 'new-message', timestamp: 1700000000 });
+ engines.set(id, {
+ sendTextMessage: replacementSend,
+ sendChatState: () => Promise.resolve(),
+ } as unknown as IWhatsAppEngine);
+ resume.resolve();
+ expect(await settled).toBe('refused');
+ expect(replacementSend).not.toHaveBeenCalled();
+ expect(await db.getRepository(Message).count()).toBe(0);
+ });
+});
diff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.ts
index f16f1bd48..f485f9e67 100644
--- a/src/modules/session/session-engine-controls.ts
+++ b/src/modules/session/session-engine-controls.ts
@@ -20,6 +20,7 @@ import { Template } from '../template/entities/template.entity';
import { BaileysStoredMessage } from '../../engine';
import { ChatState } from '../../engine/adapters/baileys-chat-state.entity';
import { StatusUpdate } from '../status-store/entities/status-update.entity';
+import { closeSessionWrites } from '../../common/utils/session-write-scope';
import { EngineFactory } from '../../engine/engine.factory';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
@@ -686,6 +687,7 @@ export class SessionEngineControls {
// sessionErrors (and the recovery budget, Task 8) are cleared ONLY on a committed delete; a
// rejected 409 from fence #2 leaves them intact (the session still exists).
let parentDeleted = false;
+ const writes = closeSessionWrites(this.host.dataSource(), id);
try {
// Stop engine if running β€” time-bounded + isolated so a stuck Chromium can't wedge the delete;
@@ -724,6 +726,7 @@ export class SessionEngineControls {
throw fenceError;
}
+ await writes.drain();
// Execute hook BEFORE delete so plugins can access session data
await this.hookManager.execute(
'session:deleted',
@@ -795,6 +798,7 @@ export class SessionEngineControls {
const nameIsAnId = await this.sessionRepository.exists({ where: { id: session.name } }).catch(() => true);
await this.engineFactory.purgeSessionData(id, nameIsAnId ? undefined : session.name);
} finally {
+ writes.release();
// Always clear the teardown mark so a later recreate/start with this id isn't suppressed. This
// stop mark was set after fence #1, so clearing it on a rejected 409 only undoes what THIS
// delete added β€” it does NOT touch reconnect timer / engine / last status / error / recovery
diff --git a/src/modules/session/session-engine-leaf-events.ts b/src/modules/session/session-engine-leaf-events.ts
index fd756f3d3..0b20d079b 100644
--- a/src/modules/session/session-engine-leaf-events.ts
+++ b/src/modules/session/session-engine-leaf-events.ts
@@ -59,6 +59,7 @@ export class SessionEngineLeafEvents {
* `(sessionId, waStatusId)`, so this can never double-count a status onMessage already ingested.
*/
async seedStatuses(sessionId: string, engine: IWhatsAppEngine): Promise<void> {
+ const lifetime = this.statusStore.captureWrites(sessionId);
try {
// Read the status-broadcast chat's own recent messages rather than getContactStatuses(): on
// whatsapp-web.js the latter reads the StatusV3 collection, which loads asynchronously and is
@@ -108,7 +109,7 @@ export class SessionEngineLeafEvents {
status.contactName = poster.name;
status.contactPushName = poster.pushName;
}
- await this.statusStore.ingest(sessionId, status);
+ await this.statusStore.ingest(sessionId, status, lifetime);
} catch (itemErr) {
// One bad item must not abort the whole backfill.
this.logger.warn('Status seed item skipped', {
@@ -122,6 +123,8 @@ export class SessionEngineLeafEvents {
sessionId,
error: err instanceof Error ? err.message : String(err),
});
+ } finally {
+ lifetime.close();
}
}
diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.ts
index 23454974b..a5aa348e4 100644
--- a/src/modules/session/session.service.spec.ts
+++ b/src/modules/session/session.service.spec.ts
@@ -63,6 +63,7 @@ import { EventsGateway } from '../events/events.gateway';
import { WebhookService } from '../webhook/webhook.service';
import { HookManager } from '../../core/hooks';
import { StatusStoreService } from '../status-store/status-store.service';
+import { captureSessionWrites } from '../../common/utils/session-write-scope';
import {
IncomingMessage,
EngineEventCallbacks,
@@ -249,6 +250,7 @@ describe('SessionService', () => {
};
statusStore = {
+ captureWrites: jest.fn().mockImplementation((id: string) => captureSessionWrites(dataSource, id)),
// Default: nothing freshly inserted (callers only dispatch status.received on created=true).
ingest: jest.fn().mockResolvedValue({ row: {}, created: false }),
};
@@ -7112,6 +7114,7 @@ describe('SessionService', () => {
caption: 'hi',
postedAt: nowSec * 1000,
}),
+ expect.any(Object),
);
// st-b had no cached name, so the seed backfilled it from getContactById.
expect(statusStore.ingest).toHaveBeenNthCalledWith(
@@ -7124,6 +7127,7 @@ describe('SessionService', () => {
contactName: 'Bob',
contactPushName: 'Bobby',
}),
+ expect.any(Object),
);
// The lookup runs only for the poster that lacked a name; st-a already had one.
expect(mockEngine.getContactById).toHaveBeenCalledWith('[email protected]');
@@ -7155,6 +7159,7 @@ describe('SessionService', () => {
expect(statusStore.ingest).toHaveBeenCalledWith(
'sess-uuid-1',
expect.objectContaining({ waStatusId: 'st-c', media }),
+ expect.any(Object),
);
});
@@ -7224,6 +7229,7 @@ describe('SessionService', () => {
2,
'sess-uuid-1',
expect.objectContaining({ waStatusId: 'st-ok' }),
+ expect.any(Object),
);
});
diff --git a/src/modules/status-store/status-store.service.spec.ts b/src/modules/status-store/status-store.service.spec.ts
index a41f1fb76..ea2cd7e16 100644
--- a/src/modules/status-store/status-store.service.spec.ts
+++ b/src/modules/status-store/status-store.service.spec.ts
@@ -1,7 +1,7 @@
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
-import { DataSource, DeepPartial, Repository } from 'typeorm';
+import { DataSource, Repository } from 'typeorm';
import { ConfigService } from '@nestjs/config';
jest.mock('archiver', () => ({ default: jest.fn() }));
@@ -305,13 +305,7 @@ describe('StatusStoreService (ingest / list / getMedia)', () => {
// The in-memory row returned here is exactly what dispatchStatusReceived sends. Every other
// omission path sets omitReason, so leaving it unset made a real media loss indistinguishable
// from an unexplained omission β€” and nothing retries it.
- const saveSpy = jest.spyOn(repository, 'save');
- let calls = 0;
- saveSpy.mockImplementation((row: DeepPartial<StatusUpdate>) => {
- calls += 1;
- if (calls === 2) return Promise.reject(new Error('db blip')); // the post-write update
- return Promise.resolve(row as DeepPartial<StatusUpdate> & StatusUpdate);
- });
+ const updateSpy = jest.spyOn(repository, 'update').mockRejectedValueOnce(new Error('db blip'));
try {
const { row } = await service.ingest('sess', {
waStatusId: 'w-row-fail',
@@ -324,7 +318,7 @@ describe('StatusStoreService (ingest / list / getMedia)', () => {
expect(row.omitReason).toBe('write_failed');
expect(row.mediaPath).toBeFalsy();
} finally {
- saveSpy.mockRestore();
+ updateSpy.mockRestore();
}
});
diff --git a/src/modules/status-store/status-store.service.ts b/src/modules/status-store/status-store.service.ts
index bfca25f84..004131f3e 100644
--- a/src/modules/status-store/status-store.service.ts
+++ b/src/modules/status-store/status-store.service.ts
@@ -12,6 +12,7 @@ import { isUniqueViolation } from '../../common/utils/db-errors';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { parseWaId, userPart } from '../../engine/identity/wa-id';
import { createLogger } from '../../common/services/logger.service';
+import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';
/** A status/story lives for 24h from posting, matching WhatsApp's own expiry. Exported for the
* session service's seed, which skips backfilling statuses that have already run out their TTL. */
@@ -117,49 +118,62 @@ export class StatusStoreService implements OnModuleInit, OnModuleDestroy {
* permanent orphan file; the narrow window between the file write and the row update is the only
* remaining orphan source, and the reconciliation sweep reaps those.
*/
- async ingest(sessionId: string, s: IncomingStatus): Promise<{ row: StatusUpdate; created: boolean }> {
- const existing = await this.repository.findOne({ where: { sessionId, waStatusId: s.waStatusId } });
- if (existing) return { row: existing, created: false };
+ async ingest(
+ sessionId: string,
+ s: IncomingStatus,
+ lifetime?: SessionWriteScope,
+ ): Promise<{ row: StatusUpdate; created: boolean }> {
+ const scope = lifetime ?? this.captureWrites(sessionId);
+ try {
+ const existing = await this.repository.findOne({ where: { sessionId, waStatusId: s.waStatusId } });
+ if (existing) return { row: existing, created: false };
- const row = new StatusUpdate();
- row.sessionId = sessionId;
- row.contactJid = s.contactJid;
- row.contactName = s.contactName;
- row.contactPushName = s.contactPushName;
- row.waStatusId = s.waStatusId;
- row.type = s.type;
- row.caption = s.caption;
- row.backgroundColor = s.backgroundColor;
- row.font = s.font;
- row.postedAt = s.postedAt;
- row.expiresAt = s.postedAt + STATUS_TTL_MS;
- // Settles every media outcome that does NOT need a file write; a keepable blob stays
- // omitted-for-now until attachMedia lands the file and flips it (post-save).
- const keepMedia = this.applyMediaDecision(row, s);
+ const row = new StatusUpdate();
+ row.sessionId = sessionId;
+ row.contactJid = s.contactJid;
+ row.contactName = s.contactName;
+ row.contactPushName = s.contactPushName;
+ row.waStatusId = s.waStatusId;
+ row.type = s.type;
+ row.caption = s.caption;
+ row.backgroundColor = s.backgroundColor;
+ row.font = s.font;
+ row.postedAt = s.postedAt;
+ row.expiresAt = s.postedAt + STATUS_TTL_MS;
+ // Settles every media outcome that does NOT need a file write; a keepable blob stays
+ // omitted-for-now until attachMedia lands the file and flips it (post-save).
+ const keepMedia = this.applyMediaDecision(row, s);
- let saved: StatusUpdate;
- try {
- // Without a transaction: a single-row save() wraps itself in one, and on SQLite's single shared
- // connection the rollback of the unique violation expected below also discards the rows other callers
- // wrote while it was open, after they were reported stored.
- saved = await this.repository.save(row, { transaction: false });
- } catch (error) {
- // The unique (sessionId, waStatusId) index is the idempotency backstop for a concurrent ingest
- // of the same status racing past the findOne check above; on a unique-constraint violation the
- // loser re-reads and returns the row the winner just inserted instead of surfacing the
- // constraint error to the caller. Any OTHER save error is a genuine persistence failure and
- // must propagate β€” never be masked by a coincidentally matching row. No media file has been
- // written at this point (row-first ordering), so unlike a file-first ingest there is nothing
- // to reap here β€” the winner's own call owns its file write.
- const winner = await this.repository.findOne({ where: { sessionId, waStatusId: s.waStatusId } });
- if (winner && isUniqueViolation(error)) return { row: winner, created: false };
- throw error;
- }
+ let saved: StatusUpdate;
+ try {
+ // Without a transaction: a single-row save() wraps itself in one, and on SQLite's single shared
+ // connection the rollback of the unique violation expected below also discards the rows other callers
+ // wrote while it was open, after they were reported stored.
+ saved = await scope.write(() => this.repository.save(row, { transaction: false }));
+ } catch (error) {
+ // The unique (sessionId, waStatusId) index is the idempotency backstop for a concurrent ingest
+ // of the same status racing past the findOne check above; on a unique-constraint violation the
+ // loser re-reads and returns the row the winner just inserted instead of surfacing the
+ // constraint error to the caller. Any OTHER save error is a genuine persistence failure and
+ // must propagate β€” never be masked by a coincidentally matching row. No media file has been
+ // written at this point (row-first ordering), so unlike a file-first ingest there is nothing
+ // to reap here β€” the winner's own call owns its file write.
+ const winner = await this.repository.findOne({ where: { sessionId, waStatusId: s.waStatusId } });
+ if (winner && isUniqueViolation(error)) return { row: winner, created: false };
+ throw error;
+ }
- if (keepMedia) {
- await this.attachMedia(saved, sessionId, s);
+ if (keepMedia) {
+ await this.attachMedia(saved, sessionId, s);
+ }
+ return { row: saved, created: true };
+ } finally {
+ if (!lifetime) scope.close();
}
- return { row: saved, created: true };
+ }
+
+ captureWrites(sessionId: string): SessionWriteScope {
+ return captureSessionWrites(this.repository.manager?.connection ?? this.repository, sessionId);
}
/**
@@ -211,7 +225,7 @@ export class StatusStoreService implements OnModuleInit, OnModuleDestroy {
error instanceof Error ? error.stack : String(error),
);
row.omitReason = 'write_failed';
- await this.repository.save(row).catch(err =>
+ await this.repository.update({ id: row.id, sessionId }, { omitReason: row.omitReason }).catch(err =>
this.logger.warn(`Failed to record the write_failed omission for status ${s.waStatusId}`, {
error: String(err),
}),
@@ -223,7 +237,14 @@ export class StatusStoreService implements OnModuleInit, OnModuleDestroy {
row.mediaMimetype = media.mimetype;
row.mediaOmitted = false;
try {
- await this.repository.save(row);
+ await this.repository.update(
+ { id: row.id, sessionId },
+ {
+ mediaPath: row.mediaPath,
+ mediaMimetype: row.mediaMimetype,
+ mediaOmitted: false,
+ },
+ );
} catch (error) {
// The file exists but the row cannot reference it β€” an orphan the reconciliation sweep reaps
// after its grace window. The persisted row stays consistent (still omitted from the first