Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(pacing): reserve cold group reachouts before the engine call
Yudhi Armyndharis3ffdfffeaf10
diff --git a/src/modules/group/group.service.spec.ts b/src/modules/group/group.service.spec.tsindex 676524d6f..2cc64320c 100644--- a/src/modules/group/group.service.spec.ts+++ b/src/modules/group/group.service.spec.ts@@ -9,8 +9,8 @@ import { SendPacingService } from '../message/send-pacing.service';/** Pacing is off by default; its own spec covers the governor, so here it must simply not refuse. */const inertPacing = (): SendPacingService =>({- assertReachoutAllowed: jest.fn().mockResolvedValue(0),- chargeGroupReachouts: jest.fn(),+ assertReachoutAllowed: jest.fn().mockResolvedValue({ coldCount: 0, dayStartMs: 0 }),+ refundGroupReachouts: jest.fn(),}) as unknown as SendPacingService;describe('GroupService', () => {@@ -117,43 +117,45 @@ describe('GroupService', () => {await expect(svc.getGroupInfo('s1', 'g1')).resolves.toEqual({ id: 'g1', name: 'G' });});- it('charges the cold-reachout budget only after the engine call resolves', async () => {+ it('keeps the reserved cold-reachout budget when the engine call resolves', async () => {const addParticipants = jest.fn().mockResolvedValue(undefined);const { svc, pacing } = makeServiceWithPacing({ addParticipants },{- assertReachoutAllowed: jest.fn().mockResolvedValue(3),- chargeGroupReachouts: jest.fn(),+ assertReachoutAllowed: jest.fn().mockResolvedValue({ coldCount: 3, dayStartMs: 1 }),+ refundGroupReachouts: jest.fn(),},);await svc.addParticipants('s1', 'g1', ['[email protected]']);- expect(pacing.chargeGroupReachouts).toHaveBeenCalledWith('s1', 3);+ expect(pacing.refundGroupReachouts).not.toHaveBeenCalled();});- it('does not charge the budget when the engine refuses the add (the participants were never contacted)', async () => {+ it('refunds the reservation when the engine refuses the add (the participants were never contacted)', async () => {const addParticipants = jest.fn().mockRejectedValue(new Error('no admin rights'));+ const reservation = { coldCount: 3, dayStartMs: 1 };const { svc, pacing } = makeServiceWithPacing({ addParticipants },{- assertReachoutAllowed: jest.fn().mockResolvedValue(3),- chargeGroupReachouts: jest.fn(),+ assertReachoutAllowed: jest.fn().mockResolvedValue(reservation),+ refundGroupReachouts: jest.fn(),},);await expect(svc.addParticipants('s1', 'g1', ['[email protected]'])).rejects.toThrow('no admin rights');- expect(pacing.chargeGroupReachouts).not.toHaveBeenCalled();+ expect(pacing.refundGroupReachouts).toHaveBeenCalledWith('s1', reservation);});- it('does not charge the budget when createGroup fails (whatsapp-web.js always 501s)', async () => {+ it('refunds the reservation when createGroup fails (whatsapp-web.js always 501s)', async () => {const createGroup = jest.fn().mockRejectedValue(new Error('EngineNotSupportedError'));+ const reservation = { coldCount: 2, dayStartMs: 1 };const { svc, pacing } = makeServiceWithPacing({ createGroup },{- assertReachoutAllowed: jest.fn().mockResolvedValue(2),- chargeGroupReachouts: jest.fn(),+ assertReachoutAllowed: jest.fn().mockResolvedValue(reservation),+ refundGroupReachouts: jest.fn(),},);await expect(svc.createGroup('s1', 'G', ['[email protected]', '[email protected]'])).rejects.toThrow();- expect(pacing.chargeGroupReachouts).not.toHaveBeenCalled();+ expect(pacing.refundGroupReachouts).toHaveBeenCalledWith('s1', reservation);});it('passes participant lists straight through to the engine', async () => {diff --git a/src/modules/group/group.service.ts b/src/modules/group/group.service.tsindex 9c8fac00e..2423ee370 100644--- a/src/modules/group/group.service.ts+++ b/src/modules/group/group.service.ts@@ -67,10 +67,14 @@ export class GroupService {*/async createGroup(sessionId: string, name: string, participants: string[]) {this.assertAddressableParticipants(participants);- const coldCount = await this.pacing.assertReachoutAllowed(sessionId, participants);- const group = await this.getEngine(sessionId).createGroup(name, participants);- this.pacing.chargeGroupReachouts(sessionId, coldCount);- return group;+ const reservation = await this.pacing.assertReachoutAllowed(sessionId, participants);+ try {+ return await this.getEngine(sessionId).createGroup(name, participants);+ } catch (error) {+ // Nobody was invited, so the reserved budget goes back (whatsapp-web.js always 501s here).+ this.pacing.refundGroupReachouts(sessionId, reservation);+ throw error;+ }}/**@@ -80,10 +84,15 @@ export class GroupService {*/async addParticipants(sessionId: string, groupId: string, participants: string[]) {this.assertAddressableParticipants(participants);- const coldCount = await this.pacing.assertReachoutAllowed(sessionId, participants);- const result = await this.getEngine(sessionId).addParticipants(groupId, participants);- this.pacing.chargeGroupReachouts(sessionId, coldCount);- return result;+ const reservation = await this.pacing.assertReachoutAllowed(sessionId, participants);+ try {+ return await this.getEngine(sessionId).addParticipants(groupId, participants);+ } catch (error) {+ // A refused add contacted nobody. Per-participant failures an engine reports without throwing+ // stay charged: the batch was attempted.+ this.pacing.refundGroupReachouts(sessionId, reservation);+ throw error;+ }}removeParticipants(sessionId: string, groupId: string, participants: string[]) {diff --git a/src/modules/message/send-pacing-cold-query.spec.ts b/src/modules/message/send-pacing-cold-query.spec.tsindex 05f893710..ef386dcf5 100644--- a/src/modules/message/send-pacing-cold-query.spec.ts+++ b/src/modules/message/send-pacing-cold-query.spec.ts@@ -1,9 +1,12 @@import { DataSource } from 'typeorm';-import { SendPacingService } from './send-pacing.service';+import { SEND_PACING_LIMITED, SendPacingService } from './send-pacing.service';import { Message, MessageDirection } from './entities/message.entity';import { Session } from '../session/entities/session.entity';import { computeSendPacingConfig } from './send-pacing.config';import type { ConfigService } from '@nestjs/config';+import { GroupService } from '../group/group.service';+import { EngineRegistry } from '../../engine/engine-registry.service';+import type { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';/*** The cold-reachout count is the one piece of this feature that cannot be proven with a mocked@@ -221,10 +224,9 @@ describe('group reachouts against a real database', () => {await ds.destroy();});- // The group callers charge only after the engine call resolves; mirror that flow so the tally- // semantics below (accumulation, day reset, shared budget) are tested through the real seam.+ // An allowed batch is reserved by the check itself; the group callers only refund on failure.const reachout = async (sessionId: string, ids: string[]): Promise<void> => {- service.chargeGroupReachouts(sessionId, await service.assertReachoutAllowed(sessionId, ids));+ await service.assertReachoutAllowed(sessionId, ids);};it("allows a batch that fits inside the day's remaining allowance", async () => {@@ -307,6 +309,102 @@ describe('group reachouts against a real database', () => {await addMessage('[email protected]', TODAY);await addMessage('[email protected]', TODAY);- await expect(service.assertReachoutAllowed('s1', [])).resolves.toBe(0);+ await expect(service.assertReachoutAllowed('s1', [])).resolves.toMatchObject({ coldCount: 0 });+ });++ // The check and the charge are one synchronous step: two requests in flight at once must not both+ // pass against the same unspent budget.+ it('refuses the second of two concurrent batches that together exceed the allowance', async () => {+ const results = await Promise.allSettled([+ service.assertReachoutAllowed('s1', ['[email protected]', '[email protected]']),+ service.assertReachoutAllowed('s1', ['[email protected]', '[email protected]']),+ ]);++ expect(results.filter(r => r.status === 'fulfilled')).toHaveLength(1);+ expect(results.find(r => r.status === 'rejected')).toMatchObject({ reason: { status: 429 } });+ });++ it('hands a refunded reservation back to the same day', async () => {+ const reservation = await service.assertReachoutAllowed('s1', ['[email protected]', '[email protected]', '[email protected]']);+ await expect(reachout('s1', ['[email protected]'])).rejects.toMatchObject({ status: 429 });++ service.refundGroupReachouts('s1', reservation);+ await expect(reachout('s1', ['[email protected]', '[email protected]', '[email protected]'])).resolves.toBeUndefined();+ });++ it("leaves the new day's tally alone when a reservation is refunded after UTC midnight", async () => {+ const yesterdays = await service.assertReachoutAllowed('s1', ['[email protected]', '[email protected]']);++ jest.setSystemTime(new Date(NOW.getTime() + DAY_MS));+ service.refundGroupReachouts('s1', yesterdays);++ // Today's three are still spent; the refund belonged to a day that is over.+ await expect(reachout('s1', ['[email protected]'])).rejects.toMatchObject({ status: 429 });+ });++ it("does not let a check that straddled UTC midnight overwrite the new day's tally", async () => {+ const internals = service as unknown as { countColdReachoutsToday: () => Promise<number> };+ const realCount = internals.countColdReachoutsToday.bind(service);+ // While the first check is suspended on its count query, the clock rolls over and another+ // request spends the whole new day's allowance.+ jest.spyOn(internals, 'countColdReachoutsToday').mockImplementationOnce(async () => {+ jest.setSystemTime(new Date(NOW.getTime() + DAY_MS));+ return 0;+ });+ jest.spyOn(internals, 'countColdReachoutsToday').mockImplementation(realCount);++ await reachout('s1', ['[email protected]']);+ await expect(reachout('s1', ['[email protected]'])).rejects.toMatchObject({ status: 429 });+ });++ describe('through GroupService', () => {+ const tenStrangers = (prefix: string): string[] =>+ Array.from({ length: 10 }, (_, i) => `62${prefix}${String(i).padStart(4, '0')}@c.us`);++ const groupService = (engine: Partial<IWhatsAppEngine>): GroupService => {+ const engines = new EngineRegistry();+ engines.set('s1', engine as IWhatsAppEngine);+ return new GroupService(engines, service);+ };++ beforeEach(() => {+ service = new SendPacingService(ds.getRepository(Message), ds.getRepository(Session), {+ get: (key: string) =>+ key === 'sendPacing'+ ? { ...computeSendPacingConfig({}), enabled: true, warmupSchedule: [10_000], coldSchedule: [10] }+ : undefined,+ } as unknown as ConfigService);+ });++ it('adds at most one of two concurrent batches that together exceed the allowance', async () => {+ // The engine takes a while, as a real per-participant add does: the window the race lived in.+ // Real timers, so the engine's setImmediate can fire.+ const addParticipants = jest.fn(+ () => new Promise(resolve => setImmediate(() => resolve([]))),+ ) as unknown as IWhatsAppEngine['addParticipants'];+ jest.useRealTimers();+ const svc = groupService({ addParticipants });++ const results = await Promise.allSettled([+ svc.addParticipants('s1', '[email protected]', tenStrangers('811')),+ svc.addParticipants('s1', '[email protected]', tenStrangers('822')),+ ]);++ expect(results.map(r => r.status).sort()).toEqual(['fulfilled', 'rejected']);+ expect(addParticipants).toHaveBeenCalledTimes(1);+ expect(results.find(r => r.status === 'rejected')).toMatchObject({+ reason: { status: 429, response: { code: SEND_PACING_LIMITED } },+ });+ });++ it('refunds the batch when the engine refuses the add, so the next batch still fits', async () => {+ const addParticipants = jest.fn().mockRejectedValueOnce(new Error('not an admin')).mockResolvedValueOnce([]);+ const svc = groupService({ addParticipants });++ await expect(svc.addParticipants('s1', '[email protected]', tenStrangers('811'))).rejects.toThrow('not an admin');+ await expect(svc.addParticipants('s1', '[email protected]', tenStrangers('822'))).resolves.toEqual([]);+ });});});diff --git a/src/modules/message/send-pacing.service.ts b/src/modules/message/send-pacing.service.tsindex 0e54b4329..0e106fcf8 100644--- a/src/modules/message/send-pacing.service.ts+++ b/src/modules/message/send-pacing.service.ts@@ -52,6 +52,18 @@ export function countsTowardSendBreaker(error: unknown): boolean {return true;}+/**+ * Cold reachouts `assertReachoutAllowed` set aside on the group tally for one request, and the UTC+ * day they were taken from. Hand it back to `refundGroupReachouts` if the engine call fails.+ */+export interface GroupReachoutReservation {+ coldCount: number;+ dayStartMs: number;+}++/** Nothing reserved: the feature is off, no cold schedule, or no stranger in the batch. */+const NO_RESERVATION: GroupReachoutReservation = { coldCount: 0, dayStartMs: 0 };+/** Per-session breaker state. Deliberately in memory — see the class doc. */interface BreakerState {consecutiveFailures: number;@@ -165,13 +177,17 @@ export class SendPacingService {* reporting success would leave the caller unable to tell who actually got added, and the engines* report per-participant outcomes for real failures already — a pacing refusal must not be* mistaken for one of those.+ *+ * An allowed batch is reserved on the group tally before this returns, in the same synchronous+ * step as the comparison, so concurrent requests cannot all pass against the same unspent budget.+ * The caller refunds the reservation if the engine call then throws.*/- async assertReachoutAllowed(sessionId: string, contactIds: string[]): Promise<number> {+ async assertReachoutAllowed(sessionId: string, contactIds: string[]): Promise<GroupReachoutReservation> {const config = resolveSendPacingConfig(this.configService);- if (!config.enabled) return 0;+ if (!config.enabled) return NO_RESERVATION;this.assertBreakerClosed(sessionId, config);- if (config.coldSchedule.length === 0 || contactIds.length === 0) return 0;+ if (config.coldSchedule.length === 0 || contactIds.length === 0) return NO_RESERVATION;// The same id twice in one request is one contact, and must cost one. Each contact is probed// under both user-id dialects (see dialectVariants) — a contact known under the other spelling@@ -186,10 +202,10 @@ export class SendPacingService {.getRawMany<{ chatId: string }>();const knownIds = new Set(knownRows.map(row => row.chatId));const coldCount = unique.filter(id => !variantsByContact.get(id)!.some(v => knownIds.has(v))).length;- if (coldCount === 0) return 0;+ if (coldCount === 0) return NO_RESERVATION;const session = await this.sessionRepository.findOne({ where: { id: sessionId } });- if (!session) return 0;+ if (!session) return NO_RESERVATION;const dayStart = startOfUtcDay(new Date());const ageDays = Math.floor((dayStart.getTime() - startOfUtcDay(session.createdAt).getTime()) / DAY_MS);@@ -200,10 +216,12 @@ export class SendPacingService {const usedToday =(await this.countColdReachoutsToday(sessionId, dayStart)) + this.groupReachoutsToday(sessionId, dayStart);if (usedToday + coldCount <= allowance) {- // Caller charges this AFTER the engine call resolves (chargeGroupReachouts): a createGroup- // that 501s on whatsapp-web.js (always) or an add the engine refuses must not burn the- // day's cold allowance for participants never contacted.- return coldCount;+ // Reserved now, with no await between the check and the charge: a concurrent request must+ // see this batch as spent. The caller refunds it (refundGroupReachouts) if the engine call+ // throws, so a createGroup that 501s on whatsapp-web.js or an add the engine refuses does not+ // burn the day's cold allowance for participants never contacted.+ this.addGroupReachouts(sessionId, dayStart, coldCount);+ return { coldCount, dayStartMs: dayStart.getTime() };}this.refuse('cold_daily_cap', sessionId, secondsUntilNextUtcDay(), {@@ -217,12 +235,15 @@ export class SendPacingService {}/**- * Charge `coldCount` cold reachouts against the in-memory group tally. Split out of- * assertReachoutAllowed so the group callers charge only after the engine call resolves.+ * Give back a reservation from assertReachoutAllowed after the engine call failed. Only the day it+ * was taken from is credited: once the tally has rolled over to a new UTC day, the old day's+ * reservation no longer counts against anything and the new day's tally is left alone.*/- chargeGroupReachouts(sessionId: string, coldCount: number): void {- if (coldCount <= 0) return;- this.addGroupReachouts(sessionId, startOfUtcDay(new Date()), coldCount);+ refundGroupReachouts(sessionId: string, reservation: GroupReachoutReservation): void {+ if (reservation.coldCount <= 0) return;+ const tally = this.groupReachoutTally.get(sessionId);+ if (!tally || tally.dayStartMs !== reservation.dayStartMs) return;+ tally.count = Math.max(0, tally.count - reservation.coldCount);}/** Cold group-add reachouts charged to this session today (0 once the stored day rolls over). */@@ -235,6 +256,9 @@ export class SendPacingService {private addGroupReachouts(sessionId: string, dayStart: Date, n: number): void {const dayStartMs = dayStart.getTime();const tally = this.groupReachoutTally.get(sessionId);+ // A check that straddled midnight must not replace a tally another request already started+ // for the new day.+ if (tally && tally.dayStartMs > dayStartMs) return;if (tally && tally.dayStartMs === dayStartMs) tally.count += n;else this.groupReachoutTally.set(sessionId, { dayStartMs, count: n });}