Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
/* istanbul ignore file: PG-gated, only runs under DATABASE_TYPE=postgres (test-postgres CI job);
skipped in the default test job, so its lines would be unread and skew the global coverage gate. */
import 'reflect-metadata';
import { randomBytes } from 'crypto';
import { DataSource, Repository } from 'typeorm';
import { SendIdempotencyKey } from '../entities/send-idempotency-key.entity';
import {
SEND_IDEMPOTENCY_STALE_PENDING_MS,
SEND_IDEMPOTENCY_TTL_MS,
SendIdempotencyService,
} from './send-idempotency.service';
import { AddSendIdempotencyKeys1787100000000 } from '../../../database/migrations/1787100000000-AddSendIdempotencyKeys';
import { postgresUtcExtra } from '../../../database/postgres-utc';
/**
* The exactly-once claim behind `Idempotency-Key` is a plain INSERT against UNIQUE(sessionId,
* idempotencyKey), and it is documented for several nodes sharing one PostgreSQL database. Three things
* about it are only true on the real server: the unique violation is recognised by its driver code, the
* row id is generated by the table's own DEFAULT (the migration, not synchronize, builds the table), and
* the timestamp columns mean one instant under the UTC pin (bind, parse and session) with the process
* deliberately OFF UTC. A SQLite-only suite cannot fail on any of them.
*
* Built in a schema of its own, like the other PostgreSQL suites that share the CI database, so it
* neither drops nor depends on the tables they create.
*/
const POSTGRES_ENABLED = process.env.DATABASE_TYPE === 'postgres';
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
const DAY = 24 * 60 * 60 * 1000;
/** The instant behind a naive timestamp read as text: the pinned server writes UTC wall time. */
const utcInstant = (wallText: string): number => new Date(`${wallText.replace(' ', 'T')}Z`).getTime();
(POSTGRES_ENABLED ? describe : describe.skip)('SendIdempotencyService (postgres)', () => {
const schema = `send_idem_${process.pid}_${randomBytes(4).toString('hex')}`;
const input = { sessionId: 's1', key: 'k-1', route: 'sendText', requestHash: 'h1' };
let admin: DataSource;
let nodeA: DataSource;
let nodeB: DataSource;
let keys: Repository<SendIdempotencyKey>;
let serviceA: SendIdempotencyService;
let serviceB: SendIdempotencyService;
beforeAll(async () => {
const connection = {
type: 'postgres' as const,
host: process.env.DATABASE_HOST || 'localhost',
port: Number(process.env.DATABASE_PORT || 5432),
username: process.env.DATABASE_USERNAME || 'openwa',
password: process.env.DATABASE_PASSWORD || 'openwa',
database: process.env.DATABASE_NAME || 'openwa',
};
admin = await new DataSource(connection).initialize();
await admin.query(`CREATE SCHEMA "${schema}"`);
const scoped = {
...connection,
schema,
entities: [SendIdempotencyKey],
extra: { ...postgresUtcExtra(), options: `-c search_path=${schema},public` },
};
// Two connection pools stand for two nodes sharing the database.
nodeA = await new DataSource(scoped).initialize();
nodeB = await new DataSource(scoped).initialize();
const runner = nodeA.createQueryRunner();
try {
await new AddSendIdempotencyKeys1787100000000().up(runner);
} finally {
await runner.release();
}
keys = nodeA.getRepository(SendIdempotencyKey);
serviceA = new SendIdempotencyService(keys);
serviceB = new SendIdempotencyService(nodeB.getRepository(SendIdempotencyKey));
});
beforeEach(async () => {
await keys.clear();
});
afterAll(async () => {
if (nodeB?.isInitialized) await nodeB.destroy();
if (nodeA?.isInitialized) await nodeA.destroy();
if (admin?.isInitialized) {
await admin.query(`DROP SCHEMA "${schema}" CASCADE`);
await admin.destroy();
}
});
it('claims under the id the table generates and reads its timestamps as one instant', async () => {
// Without a non-UTC process every timestamp assertion below would hold for the wrong reason.
expect(new Date().getTimezoneOffset()).not.toBe(0);
const before = Date.now();
const claim = await serviceA.claim(input);
const after = Date.now();
if (claim.kind !== 'claimed') throw new Error('expected a claim');
expect(claim.id).toMatch(UUID);
// Bound as UTC wall time: read back as text, no driver parser involved.
const [raw] = await nodeA.query<Array<{ id: string; expires: string }>>(
'SELECT "id", "expiresAt"::text AS expires FROM "send_idempotency_keys"',
);
expect(raw.id).toBe(claim.id);
expect(utcInstant(raw.expires)).toBeGreaterThanOrEqual(before + SEND_IDEMPOTENCY_TTL_MS);
expect(utcInstant(raw.expires)).toBeLessThanOrEqual(after + SEND_IDEMPOTENCY_TTL_MS);
// Parsed as UTC through the driver: the column the service wrote and the one DEFAULT now() filled.
const stored = await keys.findOneByOrFail({ id: claim.id });
expect(stored.expiresAt.getTime()).toBeGreaterThanOrEqual(before + DAY);
expect(stored.expiresAt.getTime()).toBeLessThanOrEqual(after + DAY);
expect(Math.abs(stored.createdAt.getTime() - Date.now())).toBeLessThan(60_000);
// A claim made moments ago is still running, not abandoned: that needs the parsed expiry to be right.
expect(await serviceB.claim(input)).toEqual({ kind: 'in_progress' });
});
it('lets exactly one of many concurrent claims win, across two connections', async () => {
const claims = await Promise.all(Array.from({ length: 20 }, (_, i) => (i % 2 ? serviceB : serviceA).claim(input)));
expect(claims.filter(c => c.kind === 'claimed')).toHaveLength(1);
expect(claims.filter(c => c.kind === 'in_progress')).toHaveLength(19);
expect(await keys.count()).toBe(1);
});
it('replays a completed send, refuses a different request, and frees a released key', async () => {
const claim = await serviceA.claim(input);
if (claim.kind !== 'claimed') throw new Error('expected a claim');
const body = { messageId: 'm1', timestamp: 1, nested: { list: [1, 2] } };
await serviceA.complete(claim.id, body);
expect(await serviceB.claim(input)).toEqual({ kind: 'replay', body });
expect(await serviceB.claim({ ...input, requestHash: 'h2' })).toEqual({ kind: 'mismatch' });
const other = await serviceA.claim({ ...input, key: 'k-2' });
if (other.kind !== 'claimed') throw new Error('expected a claim');
await serviceA.release(other.id);
expect((await serviceB.claim({ ...input, key: 'k-2', requestHash: 'h2' })).kind).toBe('claimed');
});
it('keeps a failed or abandoned key taken, and reclaims and prunes an expired one', async () => {
const failed = await serviceA.claim({ ...input, key: 'k-failed' });
if (failed.kind !== 'claimed') throw new Error('expected a claim');
await serviceA.markFailed(failed.id);
expect(await serviceB.claim({ ...input, key: 'k-failed' })).toEqual({ kind: 'outcome_unknown' });
const abandoned = await serviceA.claim({ ...input, key: 'k-abandoned' });
if (abandoned.kind !== 'claimed') throw new Error('expected a claim');
const claimedLongAgo = Date.now() - SEND_IDEMPOTENCY_STALE_PENDING_MS - 1000;
await keys.update({ id: abandoned.id }, { expiresAt: new Date(claimedLongAgo + SEND_IDEMPOTENCY_TTL_MS) });
expect(await serviceB.claim({ ...input, key: 'k-abandoned' })).toEqual({ kind: 'outcome_unknown' });
const done = await serviceA.claim({ ...input, key: 'k-done' });
if (done.kind !== 'claimed') throw new Error('expected a claim');
await serviceA.complete(done.id, { messageId: 'm1' });
await keys.update({ id: done.id }, { expiresAt: new Date(Date.now() - 1000) });
expect((await serviceB.claim({ ...input, key: 'k-done', requestHash: 'h2' })).kind).toBe('claimed');
await keys.update({ id: failed.id }, { expiresAt: new Date(Date.now() - 1000) });
expect(await serviceA.pruneExpired()).toBe(1);
expect((await keys.find()).map(row => row.idempotencyKey).sort()).toEqual(['k-abandoned', 'k-done']);
});
});