Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
perf(session): read the chat and contact lists once per paged walk
Yudhi Armyndharisa43e352551c0
diff --git a/src/common/utils/listing-memo.spec.ts b/src/common/utils/listing-memo.spec.tsnew file mode 100644index 000000000..b4afb9008--- /dev/null+++ b/src/common/utils/listing-memo.spec.ts@@ -0,0 +1,97 @@+import { ListingMemo, LISTING_MEMO_TTL_MS } from './listing-memo';++describe('ListingMemo', () => {+ const list = (...ids: string[]) => jest.fn().mockImplementation(() => Promise.resolve(ids.map(id => ({ id }))));++ afterEach(() => jest.restoreAllMocks());++ it('reads afresh for a first page and reuses the list for the later pages', async () => {+ const memo = new ListingMemo<{ id: string }>();+ const load = list('a', 'b');+ await memo.read('s1', 0, load);+ await memo.read('s1', undefined, load);+ expect(load).toHaveBeenCalledTimes(2);+ await expect(memo.read('s1', 1000, load)).resolves.toEqual([{ id: 'a' }, { id: 'b' }]);+ await memo.read('s1', 2000, load);+ expect(load).toHaveBeenCalledTimes(2);+ });++ it.each([Number.NaN, -1])('treats offset %s as a first page', async offset => {+ const memo = new ListingMemo<{ id: string }>();+ const load = list('a');+ await memo.read('s1', 0, load);+ await memo.read('s1', offset, load);+ expect(load).toHaveBeenCalledTimes(2);+ });++ it('keeps one list per session', async () => {+ const memo = new ListingMemo<{ id: string }>();+ await memo.read('s1', 0, list('a'));+ const other = list('b');+ await expect(memo.read('s2', 1000, other)).resolves.toEqual([{ id: 'b' }]);+ expect(other).toHaveBeenCalledTimes(1);+ });++ it('reads afresh once the list is older than its time to live', async () => {+ const now = Date.now();+ const clock = jest.spyOn(Date, 'now').mockReturnValue(now);+ const memo = new ListingMemo<{ id: string }>();+ const load = list('a');+ await memo.read('s1', 0, load);+ clock.mockReturnValue(now + LISTING_MEMO_TTL_MS - 1);+ await memo.read('s1', 1000, load);+ expect(load).toHaveBeenCalledTimes(1);+ clock.mockReturnValue(now + LISTING_MEMO_TTL_MS);+ await memo.read('s1', 1000, load);+ expect(load).toHaveBeenCalledTimes(2);+ });++ it('shares a read in flight with a later page', async () => {+ const memo = new ListingMemo<{ id: string }>();+ let finish: (items: { id: string }[]) => void = () => undefined;+ const load = jest.fn(() => new Promise<{ id: string }[]>(resolve => (finish = resolve)));+ const first = memo.read('s1', 0, load);+ const later = memo.read('s1', 1000, load);+ finish([{ id: 'a' }]);+ await expect(Promise.all([first, later])).resolves.toEqual([[{ id: 'a' }], [{ id: 'a' }]]);+ expect(load).toHaveBeenCalledTimes(1);+ });++ it('does not keep a failed read, and an older failure leaves a newer list in place', async () => {+ const memo = new ListingMemo<{ id: string }>();+ await expect(memo.read('s1', 0, () => Promise.reject(new Error('page died')))).rejects.toThrow('page died');+ const load = list('a');+ await memo.read('s1', 1000, load);+ expect(load).toHaveBeenCalledTimes(1);++ let fail: (error: Error) => void = () => undefined;+ const slow = memo.read('s1', 0, () => new Promise((_, reject) => (fail = reject)));+ await memo.read('s1', 0, load);+ fail(new Error('page died'));+ await expect(slow).rejects.toThrow('page died');+ await memo.read('s1', 1000, load);+ expect(load).toHaveBeenCalledTimes(2);+ });++ it('reads afresh after a drop, including a drop while the read was in flight', async () => {+ const memo = new ListingMemo<{ id: string }>();+ const load = list('a');+ await memo.read('s1', 0, load);+ memo.drop('s1');+ await memo.read('s1', 1000, load);+ expect(load).toHaveBeenCalledTimes(2);++ const pending = memo.read('s1', 0, load);+ memo.drop('s1');+ await pending;+ await memo.read('s1', 1000, load);+ expect(load).toHaveBeenCalledTimes(4);+ });++ it('hands every caller its own copy of the list', async () => {+ const memo = new ListingMemo<{ id: string }>();+ const first = await memo.read('s1', 0, list('a', 'b'));+ first.reverse().pop();+ await expect(memo.read('s1', 1000, list())).resolves.toEqual([{ id: 'a' }, { id: 'b' }]);+ });+});diff --git a/src/common/utils/listing-memo.ts b/src/common/utils/listing-memo.tsnew file mode 100644index 000000000..4ad4360e2--- /dev/null+++ b/src/common/utils/listing-memo.ts@@ -0,0 +1,42 @@+/** How long a session's full listing stays reusable for the later pages of the walk that read it. */+export const LISTING_MEMO_TTL_MS = 5_000;++/**+ * A session's last full engine listing (every chat, or every contact), kept a few seconds so the pages+ * of one walk (offset 0, 1000, 2000 ...) share one engine read instead of each re-reading the whole+ * list, which on whatsapp-web.js is a page evaluation over the entire account.+ *+ * Only a later page reuses it. A read at offset 0 starts a walk and always goes to the engine, so a+ * reload after a live event never starts from an old list. It holds the raw list of one session and+ * nothing else: every request applies its own chat-scope filter and window after reading it. Reads in+ * flight are shared, a failed read is not kept, and the owner drops a session's entry when a write may+ * have changed the list or the session's engine stops being the live one.+ */+export class ListingMemo<T> {+ private readonly entries = new Map<string, { items: Promise<T[]>; expiresAt: number }>();++ constructor(private readonly ttlMs = LISTING_MEMO_TTL_MS) {}++ async read(sessionId: string, offset: number | undefined, load: () => Promise<T[]>): Promise<T[]> {+ let entry = this.entries.get(sessionId);+ if (!(entry && (offset ?? 0) > 0 && entry.expiresAt > Date.now())) {+ const fresh = { items: load(), expiresAt: Infinity };+ this.entries.set(sessionId, fresh);+ fresh.items.then(+ () => {+ fresh.expiresAt = Date.now() + this.ttlMs;+ },+ () => {+ if (this.entries.get(sessionId) === fresh) this.entries.delete(sessionId);+ },+ );+ entry = fresh;+ }+ // A copy, so no caller can reorder or trim the list the next page reads.+ return [...(await entry.items)];+ }++ drop(sessionId: string): void {+ this.entries.delete(sessionId);+ }+}diff --git a/src/core/agent-tools/tool-chat-scope.spec.ts b/src/core/agent-tools/tool-chat-scope.spec.tsindex c609db299..a8b3adf90 100644--- a/src/core/agent-tools/tool-chat-scope.spec.ts+++ b/src/core/agent-tools/tool-chat-scope.spec.ts@@ -142,7 +142,7 @@ describe('chat-restricted tool calls', () => {t => t.name === 'SessionGetChats',)!;await expect(call(descriptor, { sessionId: 's1', limit: 1 })).resolves.toEqual([{ id: CHAT }]);- expect(listChats).toHaveBeenCalledWith('s1');+ expect(listChats).toHaveBeenCalledWith('s1', undefined);expect(getChats).not.toHaveBeenCalled();});@@ -163,7 +163,8 @@ describe('chat-restricted tool calls', () => {{ sessionId: 's1', limit: 1, offset: 1 },),).resolves.toEqual([allowed[1]]);- expect(list).toHaveBeenCalledWith('s1');+ // The contact listing takes the offset too, so the later pages of a walk share one engine read.+ expect(list).toHaveBeenCalledWith(...(name === 'ContactFindAll' ? ['s1', 1] : ['s1']));expect(paged).not.toHaveBeenCalled();},);diff --git a/src/core/agent-tools/tools/contact.tools.ts b/src/core/agent-tools/tools/contact.tools.tsindex 813750ed8..71b94c19c 100644--- a/src/core/agent-tools/tools/contact.tools.ts+++ b/src/core/agent-tools/tools/contact.tools.ts@@ -23,7 +23,11 @@ export function contactTools(contact: ContactService): AnyToolDescriptor[] {if (!chatScope?.isRestricted(apiKey)) {return contact.getContacts(input.sessionId, { limit: input.limit, offset: input.offset });}- const visible = await chatScope.filter(apiKey, await contact.listContacts(input.sessionId), item => item.id);+ const visible = await chatScope.filter(+ apiKey,+ await contact.listContacts(input.sessionId, input.offset),+ item => item.id,+ );return paginate(visible, input.limit, input.offset);},}),diff --git a/src/core/agent-tools/tools/session.tools.ts b/src/core/agent-tools/tools/session.tools.tsindex 58da04b6c..ec1b6059b 100644--- a/src/core/agent-tools/tools/session.tools.ts+++ b/src/core/agent-tools/tools/session.tools.ts@@ -55,7 +55,11 @@ export function sessionTools(session: SessionService): AnyToolDescriptor[] {if (!chatScope?.isRestricted(apiKey)) {return session.getChats(input.sessionId, { limit: input.limit, offset: input.offset });}- const visible = await chatScope.filter(apiKey, await session.listChats(input.sessionId), chat => chat.id);+ const visible = await chatScope.filter(+ apiKey,+ await session.listChats(input.sessionId, input.offset),+ chat => chat.id,+ );return paginate(visible, input.limit, input.offset);},}),diff --git a/src/modules/contact/contact.controller.spec.ts b/src/modules/contact/contact.controller.spec.tsindex 2d276714d..ef0b38869 100644--- a/src/modules/contact/contact.controller.spec.ts+++ b/src/modules/contact/contact.controller.spec.ts@@ -26,7 +26,7 @@ describe('ContactController', () => {it('findAll applies limit/offset query strings', async () => {service.listContacts.mockResolvedValue(contacts(50));const page = (await controller.findAll('s1', '5', '10')) as { id: string }[];- expect(service.listContacts).toHaveBeenCalledWith('s1');+ expect(service.listContacts).toHaveBeenCalledWith('s1', 10);expect(page.map(c => c.id)).toEqual(['[email protected]', '[email protected]', '[email protected]', '[email protected]', '[email protected]']);});diff --git a/src/modules/contact/contact.controller.ts b/src/modules/contact/contact.controller.tsindex 68d14bb34..019384199 100644--- a/src/modules/contact/contact.controller.ts+++ b/src/modules/contact/contact.controller.ts@@ -50,8 +50,13 @@ export class ContactController {@CurrentApiKey() apiKey?: ApiKey,) {// Filtered before paging so a chat-restricted key sees only its contacts, in full windows.- const visible = await this.chatScope.filter(apiKey, await this.contactService.listContacts(sessionId), c => c.id);- return paginate(visible, limit ? parseInt(limit, 10) : undefined, offset ? parseInt(offset, 10) : undefined);+ const skip = offset ? parseInt(offset, 10) : undefined;+ const visible = await this.chatScope.filter(+ apiKey,+ await this.contactService.listContacts(sessionId, skip),+ c => c.id,+ );+ return paginate(visible, limit ? parseInt(limit, 10) : undefined, skip);}@Get('profile-pictures')diff --git a/src/modules/contact/contact.service.spec.ts b/src/modules/contact/contact.service.spec.tsindex c9073735f..f90f9dd77 100644--- a/src/modules/contact/contact.service.spec.ts+++ b/src/modules/contact/contact.service.spec.ts@@ -294,12 +294,84 @@ describe('ContactService', () => {['the engine dialect', '[email protected]'],['a bare number', '628123456789'],])('still accepts %s', async (_label, id) => {- const upsertContact = jest.fn();+ const upsertContact = jest.fn().mockResolvedValue(undefined);await makeService({ upsertContact }).upsertContact('s1', id, 'Ada');expect(upsertContact).toHaveBeenCalled();});});+ describe('one engine read per walk', () => {+ const contactsOf = (prefix: string, count: number) =>+ Array.from({ length: count }, (_, i) => ({ id: `${prefix}${i}@c.us` }));+ const walk = async (svc: ContactService, sessionId = 's1') => {+ const ids: string[] = [];+ for (let offset = 0; ; offset += 1000) {+ const page = (await svc.getContacts(sessionId, { limit: 1000, offset })) as { id: string }[];+ ids.push(...page.map(c => c.id));+ if (page.length < 1000) return ids;+ }+ };++ it('reads the engine once for every page of one walk, and afresh for the next walk', async () => {+ const getContacts = jest.fn().mockResolvedValue(contactsOf('62', 5000));+ const svc = makeService({ getContacts });+ expect(new Set(await walk(svc)).size).toBe(5000);+ expect(getContacts).toHaveBeenCalledTimes(1);+ await walk(svc);+ expect(getContacts).toHaveBeenCalledTimes(2);+ });++ it("never serves one session's listing to another session", async () => {+ const engines = new EngineRegistry();+ const first = { getContacts: jest.fn().mockResolvedValue(contactsOf('62', 5000)) };+ const second = { getContacts: jest.fn().mockResolvedValue(contactsOf('63', 1500)) };+ engines.set('s1', first as unknown as IWhatsAppEngine);+ engines.set('s2', second as unknown as IWhatsAppEngine);+ const svc = new ContactService(engines);+ await svc.getContacts('s1', { offset: 0 });+ const page = (await svc.getContacts('s2', { offset: 1000 })) as { id: string }[];+ expect(second.getContacts).toHaveBeenCalledTimes(1);+ expect(page).toHaveLength(500);+ expect(page.every(c => c.id.startsWith('63'))).toBe(true);+ });++ it('reads afresh once the engine it came from was retired, and answers 400 while none runs', async () => {+ const engines = new EngineRegistry();+ const getContacts = jest.fn().mockResolvedValue(contactsOf('62', 1500));+ const engine = { getContacts } as unknown as IWhatsAppEngine;+ engines.set('s1', engine);+ const svc = new ContactService(engines);+ await svc.getContacts('s1', { offset: 0 });+ engines.delete('s1');+ expect(() => svc.getContacts('s1', { offset: 1000 })).toThrow(BadRequestException);+ // The same engine object registered again: only the retire notification can drop the listing.+ engines.set('s1', engine);+ await svc.getContacts('s1', { offset: 1000 });+ expect(getContacts).toHaveBeenCalledTimes(2);+ });++ it.each([+ ['upsertContact', (svc: ContactService) => svc.upsertContact('s1', '[email protected]', 'Ada')],+ ['deleteContact', (svc: ContactService) => svc.deleteContact('s1', '[email protected]')],+ ['blockContact', (svc: ContactService) => svc.blockContact('s1', '[email protected]')],+ ['unblockContact', (svc: ContactService) => svc.unblockContact('s1', '[email protected]')],+ ])('a %s call makes the next page read afresh, even when it fails', async (method, write) => {+ const getContacts = jest.fn().mockResolvedValue(contactsOf('62', 5000));+ const engine: Partial<Record<string, jest.Mock>> = { getContacts, [method]: jest.fn().mockResolvedValue(true) };+ const svc = makeService(engine as Partial<IWhatsAppEngine>);+ await svc.getContacts('s1', { offset: 0 });+ await write(svc);+ await svc.getContacts('s1', { offset: 1000 });+ expect(getContacts).toHaveBeenCalledTimes(2);++ // A timed-out write may still have been applied, so a failure drops the listing too.+ engine[method] = jest.fn().mockRejectedValue(new Error('timed out'));+ await expect(write(svc)).rejects.toThrow('timed out');+ await svc.getContacts('s1', { offset: 2000 });+ expect(getContacts).toHaveBeenCalledTimes(3);+ });+ });+describe('resolveContactPhone error contract', () => {it('propagates the 400 when the session is not started (getEngine is outside the swallow)', async () => {const svc = makeService(undefined);diff --git a/src/modules/contact/contact.service.ts b/src/modules/contact/contact.service.tsindex 73549a289..d839b82a0 100644--- a/src/modules/contact/contact.service.ts+++ b/src/modules/contact/contact.service.ts@@ -1,8 +1,9 @@import { HttpException, BadRequestException, Injectable, NotFoundException } from '@nestjs/common';import { EngineRegistry } from '../../engine/engine-registry.service';import { createLogger } from '../../common/services/logger.service';-import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';+import { Contact, IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';import { paginate, ListOptions } from '../../common/utils/paginate';+import { ListingMemo } from '../../common/utils/listing-memo';import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';import { isIndividualWid, parseWaId, toNeutralJid } from '../../engine/identity/wa-id';@@ -13,23 +14,31 @@ import { isIndividualWid, parseWaId, toNeutralJid } from '../../engine/identity/@Injectable()export class ContactService {private readonly logger = createLogger('ContactService');+ /** The contact listing the pages of one walk share. Every addressbook or block write drops it. */+ private readonly listings = new ListingMemo<Contact>();- constructor(private readonly engines: EngineRegistry) {}+ constructor(private readonly engines: EngineRegistry) {+ engines.onRetire(id => this.listings.drop(id));+ }private getEngine(sessionId: string): IWhatsAppEngine {// EngineRegistry.require()'s default is this exact 400 "Session is not started".return this.engines.require(sessionId);}- /** Every contact WITHOUT the response window, for callers that filter before paging. */- listContacts(sessionId: string) {+ /**+ * Every contact WITHOUT the response window, for callers that filter before paging. `offset` is the+ * window the caller is about to take: a later page reuses the list its walk's first page read.+ */+ listContacts(sessionId: string, offset?: number) {// getEngine throws synchronously (keeps the "session not started" guard a sync 400).- return this.getEngine(sessionId).getContacts();+ const engine = this.getEngine(sessionId);+ return this.listings.read(sessionId, offset, () => engine.getContacts());}getContacts(sessionId: string, opts: ListOptions = {}) {// The engine returns the full set and we bound the HTTP response window via paginate().- return this.listContacts(sessionId).then(contacts => paginate(contacts, opts.limit, opts.offset));+ return this.listContacts(sessionId, opts.offset).then(contacts => paginate(contacts, opts.limit, opts.offset));}async getContactById(sessionId: string, contactId: string) {@@ -139,7 +148,9 @@ export class ContactService {*/blockContact(sessionId: string, contactId: string) {this.assertBlockable(contactId);- return this.getEngine(sessionId).blockContact(this.toAddressableId(contactId));+ return this.getEngine(sessionId)+ .blockContact(this.toAddressableId(contactId))+ .finally(() => this.listings.drop(sessionId));}/**@@ -219,16 +230,22 @@ export class ContactService {upsertContact(sessionId: string, contactId: string, firstName: string, lastName?: string) {this.assertAddressable(contactId);- return this.getEngine(sessionId).upsertContact(this.toAddressableId(contactId), firstName, lastName);+ return this.getEngine(sessionId)+ .upsertContact(this.toAddressableId(contactId), firstName, lastName)+ .finally(() => this.listings.drop(sessionId));}deleteContact(sessionId: string, contactId: string) {this.assertAddressable(contactId);- return this.getEngine(sessionId).deleteContact(this.toAddressableId(contactId));+ return this.getEngine(sessionId)+ .deleteContact(this.toAddressableId(contactId))+ .finally(() => this.listings.drop(sessionId));}unblockContact(sessionId: string, contactId: string) {this.assertBlockable(contactId);- return this.getEngine(sessionId).unblockContact(this.toAddressableId(contactId));+ return this.getEngine(sessionId)+ .unblockContact(this.toAddressableId(contactId))+ .finally(() => this.listings.drop(sessionId));}}diff --git a/src/modules/session/session-config.concurrency.spec.ts b/src/modules/session/session-config.concurrency.spec.tsindex 9c8df58ca..624382885 100644--- a/src/modules/session/session-config.concurrency.spec.ts+++ b/src/modules/session/session-config.concurrency.spec.ts@@ -2,6 +2,7 @@ import { ConflictException } from '@nestjs/common';import { DataSource } from 'typeorm';import { Session } from './entities/session.entity';import { SessionService } from './session.service';+import { EngineRegistry } from '../../engine/engine-registry.service';/*** PATCH /config merges into the stored blob. Two overlapping requests that each read the same blob@@ -21,7 +22,7 @@ describe('SessionService.updateConfig under concurrent requests', () => {ds.getRepository(Session),unused, // messagesds,- unused, // engine registry+ new EngineRegistry(),unused, // watchdogattach, // session errorsattach, // session restrictionsdiff --git a/src/modules/session/session.controller.ts b/src/modules/session/session.controller.tsindex 17147cb23..e763dd2cc 100644--- a/src/modules/session/session.controller.ts+++ b/src/modules/session/session.controller.ts@@ -589,8 +589,9 @@ export class SessionController {// This route is admitted to a chat-restricted key because it FILTERS to the key's chats rather// than naming one in the path. Filter BEFORE paginating: filtering the page instead would give a// restricted key a short or empty window while an allowed chat sat just past it.- const visible = await this.chatScope.filter(apiKey, await this.sessionService.listChats(id), chat => chat.id);- return paginate(visible, limit ? parseInt(limit, 10) : undefined, offset ? parseInt(offset, 10) : undefined);+ const skip = offset ? parseInt(offset, 10) : undefined;+ const visible = await this.chatScope.filter(apiKey, await this.sessionService.listChats(id, skip), chat => chat.id);+ return paginate(visible, limit ? parseInt(limit, 10) : undefined, skip);}@ChatScoped('fenced')diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.tsindex 60d494d94..e4b1f1797 100644--- a/src/modules/session/session.service.spec.ts+++ b/src/modules/session/session.service.spec.ts@@ -83,6 +83,9 @@ import {getSessionReconnectLoopAlertsTotal,} from '../../common/metrics/session-reconnect-metrics';import { AuditService } from '../audit/audit.service';+import { SessionController } from './session.controller';+import { ChatScopeService } from '../auth/chat-scope.service';+import type { ApiKey } from '../auth/entities/api-key.entity';/** The (action, context) pair of one audit call, typed so assertions do not fall back to `any`. */const auditCall = (mock: jest.Mock, index = 0): [string, { sessionId?: string; metadata?: Record<string, unknown> }] =>@@ -8131,6 +8134,127 @@ describe('SessionService', () => {await expect(service.getChats('sess-uuid-1')).rejects.toThrow(BadRequestException);});++ describe('one engine read per walk', () => {+ const chatsOf = (prefix: string, count: number) =>+ Array.from({ length: count }, (_, i) => ({+ id: `${prefix}${i}@c.us`,+ name: `c${i}`,+ isGroup: false,+ unreadCount: 0,+ timestamp: i,+ }));+ const walk = async (sessionId = 'sess-uuid-1') => {+ const ids: string[] = [];+ for (let offset = 0; ; offset += 1000) {+ const page = await service.getChats(sessionId, { limit: 1000, offset });+ ids.push(...page.map(c => c.id));+ if (page.length < 1000) return ids;+ }+ };++ beforeEach(async () => {+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });+ await service.start('sess-uuid-1');+ mockEngine.getChats.mockResolvedValue(chatsOf('62', 5000));+ });++ it('reads the engine once for every page of one walk', async () => {+ expect(new Set(await walk()).size).toBe(5000);+ expect(mockEngine.getChats).toHaveBeenCalledTimes(1);+ });++ it('reads afresh for the first page of every walk', async () => {+ await walk();+ await walk();+ expect(mockEngine.getChats).toHaveBeenCalledTimes(2);+ });++ it('reads afresh for a later page once the listing has outlived its few seconds', async () => {+ const now = Date.now();+ const clock = jest.spyOn(Date, 'now').mockReturnValue(now);+ try {+ await service.getChats('sess-uuid-1', { offset: 0 });+ clock.mockReturnValue(now + 60_000);+ await service.getChats('sess-uuid-1', { offset: 1000 });+ } finally {+ clock.mockRestore();+ }+ expect(mockEngine.getChats).toHaveBeenCalledTimes(2);+ });++ it("never serves one session's listing to another session", async () => {+ const other = { getChats: jest.fn().mockResolvedValue(chatsOf('63', 1500)) };+ registry.set('sess-uuid-2', other as never);+ await service.getChats('sess-uuid-1', { offset: 0 });+ const page = await service.getChats('sess-uuid-2', { offset: 1000 });+ expect(other.getChats).toHaveBeenCalledTimes(1);+ expect(page).toHaveLength(500);+ expect(page.every(c => c.id.startsWith('63'))).toBe(true);+ });++ it('reads afresh from an engine that replaced the one the listing came from', async () => {+ await service.getChats('sess-uuid-1', { offset: 0 });+ // The same engine object registered again stands in for any replacement: identity alone+ // would not tell it apart, so only the retire notification can drop the listing.+ registry.delete('sess-uuid-1');+ registry.set('sess-uuid-1', mockEngine as never);+ await service.getChats('sess-uuid-1', { offset: 1000 });+ expect(mockEngine.getChats).toHaveBeenCalledTimes(2);+ });++ it('answers 400 for a stopped session instead of its last listing', async () => {+ await service.getChats('sess-uuid-1', { offset: 0 });+ registry.delete('sess-uuid-1');+ await expect(service.getChats('sess-uuid-1', { offset: 1000 })).rejects.toThrow(BadRequestException);+ });++ it.each([+ ['sendSeen', (s: SessionService) => s.sendSeen('sess-uuid-1', '[email protected]')],+ ['markUnread', (s: SessionService) => s.markUnread('sess-uuid-1', '[email protected]')],+ ['clearChatMessages', (s: SessionService) => s.clearChatMessages('sess-uuid-1', '[email protected]')],+ ['archiveChat', (s: SessionService) => s.archiveChat('sess-uuid-1', '[email protected]', true)],+ ['muteChat', (s: SessionService) => s.muteChat('sess-uuid-1', '[email protected]', null)],+ ['pinChat', (s: SessionService) => s.pinChat('sess-uuid-1', '[email protected]', true)],+ ['deleteChat', (s: SessionService) => s.deleteChat('sess-uuid-1', '[email protected]')],+ ])('a %s call makes the next page read afresh, even when it fails', async (method, write) => {+ mockEngine.archiveChat = jest.fn().mockResolvedValue(true);+ mockEngine.muteChat = jest.fn().mockResolvedValue(undefined);+ mockEngine.pinChat = jest.fn().mockResolvedValue(true);+ await service.getChats('sess-uuid-1', { offset: 0 });+ await write(service);+ await service.getChats('sess-uuid-1', { offset: 1000 });+ expect(mockEngine.getChats).toHaveBeenCalledTimes(2);++ // A timed-out write may still have been applied, so a failure drops the listing too.+ mockEngine[method] = jest.fn().mockRejectedValue(new Error('timed out'));+ await expect(write(service)).rejects.toThrow('timed out');+ await service.getChats('sess-uuid-1', { offset: 2000 });+ expect(mockEngine.getChats).toHaveBeenCalledTimes(3);+ });++ it('filters every page for a chat-restricted key after an unrestricted walk read the listing', async () => {+ const controller = new SessionController(+ service,+ { logInfo: jest.fn() } as unknown as AuditService,+ new ChatScopeService(),+ );+ const restricted = { allowedChats: allowed } as ApiKey;+ expect(await controller.getChats('sess-uuid-1', { allowedChats: null } as ApiKey, '1000', '0')).toHaveLength(+ 1000,+ );+ const seen: string[] = [];+ for (let offset = 0; offset < 4; offset++) {+ const page = await controller.getChats('sess-uuid-1', restricted, '1', String(offset));+ expect(page.every(c => allowed.includes(c.id))).toBe(true);+ seen.push(...page.map(c => c.id));+ }+ expect(seen.sort()).toEqual([...allowed].sort());+ expect(mockEngine.getChats).toHaveBeenCalledTimes(2);+ });+ });});describe('start() concurrent stop/delete guard', () => {diff --git a/src/modules/session/session.service.ts b/src/modules/session/session.service.tsindex c7190ae45..8d8baf5bb 100644--- a/src/modules/session/session.service.ts+++ b/src/modules/session/session.service.ts@@ -50,6 +50,7 @@ import {} from './session-engine-lifecycle.service';import { SessionOwnershipService } from './session-ownership.service';import { paginate, ListOptions, resolveListWindow } from '../../common/utils/paginate';+import { ListingMemo } from '../../common/utils/listing-memo';import { isTransientDbError, isUniqueViolation } from '../../common/utils/db-errors';import { resolveFeatureFlags } from '../../config/feature-flags';import { IWhatsAppEngine, ChatSummary, ChatState } from '../../engine/interfaces/whatsapp-engine.interface';@@ -154,6 +155,8 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatprivate readonly startReservations = new Map<string, number>();/** Ids whose claim a failed start left to another start in flight; the last start out hands it back. */private readonly releaseOwed = new Set<string>();+ /** The sorted chat listing the pages of one walk share. Every chat write below drops it. */+ private readonly chatListings = new ListingMemo<ChatSummary>();constructor(@InjectRepository(Session, 'data')@@ -181,7 +184,9 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicat// source the reconnect scheduler and the takeover sweep consult.@Optional()private readonly shutdownService?: ShutdownService,- ) {}+ ) {+ this.engineRegistry.onRetire(id => this.chatListings.drop(id));+ }/*** True from the start of the shutdown drain. An engine launched during the drain would be torn@@ -1109,18 +1114,22 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicat* Every chat for a session, most-recent first, WITHOUT the response window. Callers that must* filter before paging (a chat-restricted API key) use this, then paginate themselves: filtering* after paginate() would hand back short or empty pages for an allowed chat past the window.+ * `offset` is the window the caller is about to take: a later page reuses the list its walk's+ * first page read a few seconds ago (see ListingMemo).*/- async listChats(id: string): Promise<ChatSummary[]> {+ async listChats(id: string, offset?: number): Promise<ChatSummary[]> {await this.findOne(id); // Verify session existsconst engine = this.requireEngine(id);// Most-recent first. Sorting before the cap means a capped response is the N newest chats (what// clients show first) rather than an arbitrary slice.- return [...(await engine.getChats())].sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0));+ return this.chatListings.read(id, offset, async () =>+ [...(await engine.getChats())].sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0)),+ );}async getChats(id: string, opts: ListOptions = {}): Promise<ChatSummary[]> {- return paginate(await this.listChats(id), opts.limit, opts.offset);+ return paginate(await this.listChats(id, opts.offset), opts.limit, opts.offset);}/**@@ -1169,7 +1178,8 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatawait this.findOne(id); // Verify session existsconst engine = this.requireEngine(id);- return engine.sendSeen(chatId, messageIds, await this.groupAuthors(id, chatId, messageIds));+ const authors = await this.groupAuthors(id, chatId, messageIds);+ return engine.sendSeen(chatId, messageIds, authors).finally(() => this.chatListings.drop(id));}/**@@ -1203,7 +1213,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatawait this.findOne(id); // Verify session existsconst engine = this.requireEngine(id);- return engine.markUnread(chatId);+ return engine.markUnread(chatId).finally(() => this.chatListings.drop(id));}/**@@ -1216,7 +1226,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatconst engine = this.requireEngine(id);const cutoff = new Date();- const ok = await engine.clearChatMessages(chatId);+ const ok = await engine.clearChatMessages(chatId).finally(() => this.chatListings.drop(id));if (ok) await this.purgeStoredChat(id, chatId, cutoff);return ok;}@@ -1230,7 +1240,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatawait this.findOne(id); // Verify session existsconst engine = this.requireEngine(id);- return engine.archiveChat(chatId, archive);+ return engine.archiveChat(chatId, archive).finally(() => this.chatListings.drop(id));}/**@@ -1242,7 +1252,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatawait this.findOne(id); // Verify session existsconst engine = this.requireEngine(id);- return engine.muteChat(chatId, muteUntil);+ return engine.muteChat(chatId, muteUntil).finally(() => this.chatListings.drop(id));}/**@@ -1253,7 +1263,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatawait this.findOne(id); // Verify session existsconst engine = this.requireEngine(id);- return engine.pinChat(chatId, pin);+ return engine.pinChat(chatId, pin).finally(() => this.chatListings.drop(id));}/** Delete a chat. On success the gateway's stored copies of its messages are removed too. */@@ -1262,7 +1272,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicatconst engine = this.requireEngine(id);const cutoff = new Date();- const ok = await engine.deleteChat(chatId);+ const ok = await engine.deleteChat(chatId).finally(() => this.chatListings.drop(id));if (ok) await this.purgeStoredChat(id, chatId, cutoff);return ok;}diff --git a/test/mcp-auth.e2e-spec.ts b/test/mcp-auth.e2e-spec.tsindex da5ff3a74..2e3c4c8a0 100644--- a/test/mcp-auth.e2e-spec.ts+++ b/test/mcp-auth.e2e-spec.ts@@ -206,7 +206,7 @@ describe('MCP server (e2e)', () => {const result = parseMcpResponse(res).result as { isError?: boolean; content: Array<{ text: string }> };expect(result.isError).not.toBe(true);expect(JSON.parse(result.content[0].text)).toEqual([{ id: '[email protected]' }]);- expect(list).toHaveBeenCalledWith(scopedSession);+ expect(list).toHaveBeenCalledWith(scopedSession, undefined);} finally {list.mockRestore();}