Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(identity): say which report makes a session the lid row's owner

Yudhi Armyndharis3f46cf14cac5
diff --git a/src/engine/identity/lid-mapping-store.service.ts b/src/engine/identity/lid-mapping-store.service.ts
index 3278d9c18..b591a4759 100644
--- a/src/engine/identity/lid-mapping-store.service.ts
+++ b/src/engine/identity/lid-mapping-store.service.ts
@@ -50,9 +50,10 @@ export interface LidMappingStore {
/** The lids the table maps to these phone digits, read from the database. */
findLidsForPhone?(phone: string): Promise<string[]>;
/**
- * Write-through: update the cache + persist. A phone is last-write-wins, and the same phone from another
- * session makes that session the row's owner. A `null` phone records a negative result, and replaces a
- * stored phone only when its owner (or none, or one since deleted) gives it.
+ * Write-through: update the cache + persist. A phone is last-write-wins. A session reporting the phone
+ * this node already holds takes the row, unless this node already counted a report of it from that
+ * session: after s1, s2, s1 report one phone the owner is s2. A `null` phone records a negative result,
+ * and replaces a stored phone only when its owner (or none, or one since deleted) gives it.
*/
remember(lid: string, phone: string | null, sessionId?: string): Promise<void>;
}
@@ -110,10 +111,12 @@ export class LidMappingStoreService implements LidMappingStore, OnModuleInit {
*/
private readonly racedLookups = new Set<string>();
/**
- * Sessions that wrote or reported the phone a lid holds in {@link lidToPhone}. One not in it that
- * reports the same phone takes the row, in one write, so the row names the latest session to see
- * that phone and the negative of a session that saw it earlier leaves it; one already in it reports
- * again for free. Dropped with the cached entry.
+ * Sessions counted as having written or reported the phone a lid holds in {@link lidToPhone} (a loaded
+ * row counts its owner). One not counted that reports the same phone takes the row, in one write, and is
+ * counted; one already counted writes nothing. So the row names the latest uncounted session to report
+ * the phone, not the latest to report it: after s1, s2, s1 report one phone it names s2, and s2's
+ * negative clears a phone s1 still sees. Started anew when the phone changes, dropped with the cached
+ * entry, on an applied negative and on any release, and a session whose write failed leaves it.
*/
private readonly seenBy = new Map<string, Set<string>>();
// 0 = unbounded (legacy behaviour). Every other long-lived map in the engine surface is bounded, so
diff --git a/src/engine/identity/lid-mapping.entity.ts b/src/engine/identity/lid-mapping.entity.ts
index 25fb6d3ae..a0d612d62 100644
--- a/src/engine/identity/lid-mapping.entity.ts
+++ b/src/engine/identity/lid-mapping.entity.ts
@@ -9,8 +9,11 @@ import { Column, Entity, Index, PrimaryColumn, UpdateDateColumn } from 'typeorm'
* so it's a cache WhatsApp can correct. `phone` is nullable to record a negative result (a lid we looked
* up and could not resolve) so active lookups stay one-network-call-per-unknown-lid. A negative replaces a
* phone only when the session that wrote it (or none, or one since deleted) answers it, since another
- * account may not see the number. `sessionId` is the session that last wrote the row or reported its phone -
- * intentionally NOT a foreign key, since the row outlives any one session.
+ * account may not see the number. `sessionId` is the row's owner, the session that last wrote it: a
+ * negative, or a report of a phone, though a session this node already counted for that phone writes
+ * nothing when it reports it again (LidMappingStoreService.seenBy), so after s1, s2, s1 report one phone
+ * the owner is s2. A deleted session owns nothing. Intentionally NOT a foreign key, since the row outlives
+ * any one session.
*/
@Entity('lid_mappings')
@Index(['phone']) // reverse lookup: phone -> lids, for the message from-filter
@@ -23,7 +26,7 @@ export class LidMapping {
@Column({ type: 'varchar', nullable: true })
phone!: string | null;
- /** The row's owner: the session that last wrote it or reported its phone (see above). Not a foreign key. */
+ /** The row's owner: the session that last wrote it (see above). Not a foreign key. */
@Column({ type: 'varchar', nullable: true })
sessionId!: string | null;