Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(baileys): keep a stored lid mapping when the cache misses
Yudhi Armyndharisf702f90f4c7c
diff --git a/src/common/errors/lid-not-mapped.error.ts b/src/common/errors/lid-not-mapped.error.tsnew file mode 100644index 000000000..c1e176a62--- /dev/null+++ b/src/common/errors/lid-not-mapped.error.ts@@ -0,0 +1,11 @@+/**+ * Thrown by an engine's `resolveContactPhone` when it cannot map a lid to a phone right now: no+ * cache, table or key store knows the pair. It is not a "no phone" answer, and unlike a transient+ * engine failure it will not clear on the next attempt, so callers may hold off before asking again.+ */+export class LidNotMappedError extends Error {+ constructor(lid: string) {+ super(`lid ${lid} is not mapped in this session`);+ this.name = 'LidNotMappedError';+ }+}diff --git a/src/engine/adapters/baileys-contacts.ts b/src/engine/adapters/baileys-contacts.tsindex 2e1d9c5f2..4da5ac4e0 100644--- a/src/engine/adapters/baileys-contacts.ts+++ b/src/engine/adapters/baileys-contacts.ts@@ -5,6 +5,8 @@ import { type createLogger } from '../../common/services/logger.service';import { BAILEYS_QUERY_BUDGET_MS, withQueryDeadline } from './baileys-query-deadline';import { EngineTransportError } from '../../common/errors/engine-transport.error';import { RecipientUnreachableError } from '../../common/errors/recipient-unreachable.error';+import { LidNotMappedError } from '../../common/errors/lid-not-mapped.error';+import { parseWaId, userPart } from '../identity/wa-id';/*** Contacts/profile/chats-domain operations extracted from BaileysAdapter. The adapter keeps the@@ -22,6 +24,10 @@ export interface BaileysContactsHost {listContacts(): Contact[];findContact(contactId: string): Contact | null;resolvePhone(contactId: string): string | null;+ /** The phone the persisted lid->phone table holds for a lid, or null; read when the caches miss. */+ findPersistedLidPhone(lid: string): Promise<string | null>;+ /** Learn a lid->phone pair (written through to the persisted table). */+ recordLidMapping(lid: string, pn: string): void;listChats(): ChatSummary[];/*** The chat's last known message (the handle chatModify needs), or null when none.@@ -322,10 +328,27 @@ export class BaileysContacts {this.blocklistGeneration += 1;}- // eslint-disable-next-line @typescript-eslint/require-await+ /**+ * `resolvePhone` reads caches only, so for a lid its null means "not cached", not "no phone": the+ * mapping may have been evicted, or sit past the preload cap after a restart. Answering null there+ * told the sender resolver the lid had no phone, and it stored that null over the real mapping. So a+ * lid miss reads the persisted table, then Baileys' own signal-key mapping, and rejects when neither+ * knows it; a rejection is a transient unknown the resolver neither caches nor persists.+ */async resolveContactPhone(contactId: string): Promise<string | null> {this.host.ensureReady();- return this.host.resolvePhone(contactId);+ const cached = this.host.resolvePhone(contactId);+ if (cached || parseWaId(contactId).kind !== 'lid') return cached;+ const persisted = await this.host.findPersistedLidPhone(contactId);+ if (persisted) return persisted;+ const pn = await this.sock()+ .signalRepository?.lidMapping?.getPNForLID(contactId)+ .catch(() => null);+ if (pn) {+ this.host.recordLidMapping(contactId, pn);+ return userPart(pn);+ }+ throw new LidNotMappedError(contactId);}// eslint-disable-next-line @typescript-eslint/require-awaitdiff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.tsindex c4a531da4..9f83d37f9 100644--- a/src/engine/adapters/baileys.adapter.spec.ts+++ b/src/engine/adapters/baileys.adapter.spec.ts@@ -174,6 +174,7 @@ import { ChannelNotFoundError } from '../../common/errors/channel-not-found.erroimport { ChatLabelsUnsupportedError } from '../../common/errors/chat-labels-unsupported.error';import { Boom } from '@hapi/boom';import { EngineTransportError } from '../../common/errors/engine-transport.error';+import { LidNotMappedError } from '../../common/errors/lid-not-mapped.error';import { loadRemoteMediaBuffer } from '../../common/media/load-remote-media';import * as safeLinkPreview from './safe-link-preview';@@ -6150,6 +6151,68 @@ describe('BaileysAdapter contact + chat reads', () => {});});+ describe('resolveContactPhone for a lid this session does not hold in memory', () => {+ const makeLidStore = () => ({+ getCached: jest.fn((): string | null | undefined => undefined),+ resolveLid: jest.fn(() => null),+ lidsForPhone: jest.fn((): string[] => []),+ remember: jest.fn(() => Promise.resolve()),+ findPhoneForLid: jest.fn((): Promise<string | null> => Promise.resolve(null)),+ });+ const readyWith = async (lidMappingStore: ReturnType<typeof makeLidStore>): Promise<BaileysAdapter> => {+ const adapter = new BaileysAdapter({+ sessionId: 'sess-1',+ dbSessionId: 'db-uuid-1',+ authDir: './data/baileys',+ messageStore: fakeStore,+ lidMappingStore,+ });+ await adapter.initialize({});+ fakeSock.fire('connection.update', { connection: 'open' });+ return adapter;+ };+ afterEach(() => {+ fakeSock.signalRepository = undefined;+ });++ it('answers from the persisted table when the cache no longer holds the mapping', async () => {+ const lidStore = makeLidStore();+ lidStore.findPhoneForLid.mockResolvedValue('628111');+ const adapter = await readyWith(lidStore);+ expect(await adapter.resolveContactPhone('111@lid')).toBe('628111');+ expect(lidStore.findPhoneForLid).toHaveBeenCalledWith('111@lid');+ expect(lidStore.remember).not.toHaveBeenCalled();+ });++ it("asks Baileys' own mapping when the table has none, and records what it learns", async () => {+ const lidStore = makeLidStore();+ const getPNForLID = jest.fn().mockResolvedValue('[email protected]');+ fakeSock.signalRepository = { lidMapping: { getLIDForPN: jest.fn(), getPNForLID } };+ const adapter = await readyWith(lidStore);+ expect(await adapter.resolveContactPhone('111@lid')).toBe('628222');+ expect(getPNForLID).toHaveBeenCalledWith('111@lid');+ expect(lidStore.remember).toHaveBeenCalledWith('111', '628222', 'sess-1');+ });++ it('rejects instead of answering null when nothing maps the lid, so no null is stored', async () => {+ const lidStore = makeLidStore();+ fakeSock.signalRepository = {+ lidMapping: { getLIDForPN: jest.fn(), getPNForLID: jest.fn().mockRejectedValue(new Error('no key')) },+ };+ const adapter = await readyWith(lidStore);+ await expect(adapter.resolveContactPhone('111@lid')).rejects.toThrow(LidNotMappedError);+ expect(lidStore.remember).not.toHaveBeenCalled();+ });++ it('answers a phone JID, and null for a group, without a lookup', async () => {+ const lidStore = makeLidStore();+ const adapter = await readyWith(lidStore);+ expect(await adapter.resolveContactPhone('[email protected]')).toBe('628333');+ expect(await adapter.resolveContactPhone('[email protected]')).toBeNull();+ expect(lidStore.findPhoneForLid).not.toHaveBeenCalled();+ });+ });+describe('address book on a first link', () => {// During a first link's initial sync Baileys folds the app-state contacts.upsert (the saved name)// into the messaging-history.set record it already holds for that id, so the saved name arrivesdiff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.tsindex 053fbf000..511006339 100644--- a/src/engine/adapters/baileys.adapter.ts+++ b/src/engine/adapters/baileys.adapter.ts@@ -164,6 +164,7 @@ export class BaileysAdapter implements IWhatsAppEngine {contactCount: () => this.sessionStore.listContacts().length,findContact: contactId => this.sessionStore.findContact(contactId),resolvePhone: contactId => this.sessionStore.resolvePhone(contactId),+ findPersistedLidPhone: lid => this.config.lidMappingStore?.findPhoneForLid?.(lid) ?? Promise.resolve(null),listChats: () => this.sessionStore.listChats(),lastMessage: chatId => this.sessionStore.lastMessage(chatId),lastInboundMessage: chatId => this.sessionStore.lastInboundMessage(chatId),diff --git a/src/engine/interfaces/whatsapp-engine.interface.ts b/src/engine/interfaces/whatsapp-engine.interface.tsindex 128549f55..af93776f8 100644--- a/src/engine/interfaces/whatsapp-engine.interface.ts+++ b/src/engine/interfaces/whatsapp-engine.interface.ts@@ -1133,9 +1133,11 @@ export interface ContactCapability {getNumberId(number: string): Promise<string | null>;/**- * Best-effort resolution of a contact id to a phone number (MSISDN digits), or `null` when the- * engine cannot map it (e.g. a privacy `@lid` the account has never seen). The contact id is the- * engine's native scheme; the adapter decides how to resolve it.+ * Best-effort resolution of a contact id to a phone number (MSISDN digits). `null` is a definitive+ * "no phone for this id"; a lookup that could not decide (a failed page read, or a lid no cache,+ * table or key store maps) rejects instead, so a caller that stores the answer never overwrites a+ * known mapping with a null. The contact id is the engine's native scheme; the adapter decides how+ * to resolve it.*/resolveContactPhone(contactId: string): Promise<string | null>;diff --git a/src/modules/session/session-lid-resolver.service.spec.ts b/src/modules/session/session-lid-resolver.service.spec.tsindex 8c18c320f..16415641e 100644--- a/src/modules/session/session-lid-resolver.service.spec.ts+++ b/src/modules/session/session-lid-resolver.service.spec.ts@@ -2,6 +2,7 @@ import { SessionLidResolver } from './session-lid-resolver.service';import { EngineRegistry } from '../../engine/engine-registry.service';import type { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';import type { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';+import { LidNotMappedError } from '../../common/errors/lid-not-mapped.error';describe('SessionLidResolver', () => {let engines: EngineRegistry;@@ -53,12 +54,40 @@ describe('SessionLidResolver', () => {await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBeNull();});- it('does not cache a transient failure, so the sender resolves once the engine answers', async () => {- resolveContactPhone.mockRejectedValueOnce(new Error('Evaluation failed')).mockResolvedValueOnce('628111');+ describe('a rejected lookup', () => {+ let now: jest.SpyInstance<number, []>;+ beforeEach(() => {+ now = jest.spyOn(Date, 'now').mockReturnValue(1_000_000);+ });+ afterEach(() => now.mockRestore());- await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBeNull();- await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBe('628111');- expect(resolveContactPhone).toHaveBeenCalledTimes(2);+ it('does not cache a transient failure, so the sender resolves once the engine answers', async () => {+ resolveContactPhone.mockRejectedValueOnce(new Error('Evaluation failed')).mockResolvedValueOnce('628111');++ await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBeNull();+ await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBe('628111');+ expect(resolveContactPhone).toHaveBeenCalledTimes(2);+ });++ it('retries an unmapped lid once the hold expires', async () => {+ resolveContactPhone.mockRejectedValueOnce(new LidNotMappedError('111@lid')).mockResolvedValueOnce('628111');++ await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBeNull();+ now.mockReturnValue(1_000_000 + 60_001);+ await expect(resolver.resolveSenderPhone('s1', '111@lid')).resolves.toBe('628111');+ expect(resolveContactPhone).toHaveBeenCalledTimes(2);+ });++ it('does not retry an unmapped lid on every message from the same sender, and writes nothing', async () => {+ resolveContactPhone.mockRejectedValue(new LidNotMappedError('404@lid'));++ await expect(resolver.resolveSenderPhone('s1', '404@lid')).resolves.toBeNull();+ now.mockReturnValue(1_000_000 + 59_000);+ await expect(resolver.resolveSenderPhone('s1', '404@lid')).resolves.toBeNull();++ expect(resolveContactPhone).toHaveBeenCalledTimes(1);+ expect(remember).not.toHaveBeenCalled();+ });});it('returns null when the session has no live engine', async () => {diff --git a/src/modules/session/session-lid-resolver.service.ts b/src/modules/session/session-lid-resolver.service.tsindex 6c1d480a9..08687ba6a 100644--- a/src/modules/session/session-lid-resolver.service.ts+++ b/src/modules/session/session-lid-resolver.service.ts@@ -2,6 +2,7 @@ import { Injectable, Optional } from '@nestjs/common';import { EngineRegistry } from '../../engine/engine-registry.service';import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';import { userPart } from '../../engine/identity/wa-id';+import { LidNotMappedError } from '../../common/errors/lid-not-mapped.error';/*** Resolves a privacy-id sender (`@lid`) to a phone number for inline attachment on incoming@@ -21,6 +22,13 @@ export class SessionLidResolver {*/private readonly cache = new Map<string, string | null>();private static readonly CACHE_MAX = 5000;+ /**+ * When an unmapped-lid lookup may be retried, per key. A rejection is not cached above (it is not+ * an answer), but a sender whose lid no store maps rejects on every message, and each retry costs+ * the engine a table query and a key-store read. Kept in memory only and never persisted.+ */+ private readonly retryAfter = new Map<string, number>();+ private static readonly RETRY_AFTER_MS = 60_000;constructor(private readonly engines: EngineRegistry,@@ -40,9 +48,14 @@ export class SessionLidResolver {if (cached !== undefined) {return cached;}+ if ((this.retryAfter.get(key) ?? 0) > Date.now()) {+ return null;+ }let phone: string | null;// `resolved` marks a definitive engine answer: a rejection or a missing engine is a transient// unknown, NOT "this contact has no phone", and must never overwrite a stored mapping (#1058).+ // Engines reject rather than answer null when they cannot decide (a Baileys lid no cache, table+ // or key store maps), so only a real "no phone" reaches the null write below.let resolved = false;try {const engine = this.engines.get(sessionId);@@ -52,11 +65,21 @@ export class SessionLidResolver {} else {phone = null;}- } catch {+ } catch (err) {phone = null;+ // Only an unmapped lid waits: any other rejection (a dead page, a rate limit) is retried on the+ // sender's next message, since the engine may answer as soon as it recovers.+ if (err instanceof LidNotMappedError) {+ this.retryAfter.delete(key); // re-inserted at the newest end, so the FIFO bound drops the oldest+ if (this.retryAfter.size >= SessionLidResolver.CACHE_MAX) {+ this.retryAfter.delete(this.retryAfter.keys().next().value!);+ }+ this.retryAfter.set(key, Date.now() + SessionLidResolver.RETRY_AFTER_MS);+ }}// Only a definitive answer is cached: a transient null would otherwise stick for the process life.if (resolved) {+ this.retryAfter.delete(key);// Bounded FIFO eviction: Map preserves insertion order, so the first key is the oldest.if (this.cache.size >= SessionLidResolver.CACHE_MAX) {for (const oldest of this.cache.keys()) {