Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
new file mode 100644
index 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.ts
index 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-await
diff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.ts
index 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.erro
import { 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 arrives
diff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.ts
index 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.ts
index 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.ts
index 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.ts
index 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()) {