Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
index 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.ts
index 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.ts
index 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));
+ await reachout('s1', ['[email protected]', '[email protected]', '[email protected]']);
+ 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));
+ await reachout('s1', ['[email protected]', '[email protected]', '[email protected]']);
+ 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.ts
index 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 });
}