Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

test(message): cover send idempotency keys on PostgreSQL

Yudhi Armyndharisfd16604b3df4
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 06d67a6a2..60f3e2087 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -256,7 +256,7 @@ jobs:
# differently between two statements, so an unstable order drops rows from a page walk), and
# that the data entities can build their own schema (raw SQL the ORM passes through verbatim,
# such as a partial index predicate, only case-folds on a real server), and that the UTC pin
- # holds across a backup round trip, a retention window and a local-midnight count. All six
+ # holds across a backup round trip, a retention window and a local-midnight count. All seven
# self-skip unless DATABASE_TYPE=postgres, so they are a no-op in the default test job and only
# execute here against the postgres:16 service.
#
@@ -269,7 +269,7 @@ jobs:
# spec's own two-migrator race is in-file (Promise.all) and unaffected by runInBand. The
# synchronize spec additionally CREATEs and DROPs a scratch database of its own, which is
# only safe serialized.
- run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts
+ run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts
env:
TZ: Asia/Jakarta
DATABASE_TYPE: postgres
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 31e846758..92c3141a4 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -230,7 +230,7 @@ jobs:
# database), that a paged message list has a total order, that the data entities can build
# their own schema (raw SQL the ORM passes through verbatim, such as a partial index predicate,
# only case-folds on a real server), and that the UTC pin holds across a backup round trip, a
- # retention window and a local-midnight count. All six self-skip unless DATABASE_TYPE=postgres,
+ # retention window and a local-midnight count. All seven self-skip unless DATABASE_TYPE=postgres,
# so they are a no-op in the default test job and only execute here against the postgres:16
# service. TZ is deliberately not UTC, for the reason ci.yml states.
- name: Postgres specs (FTS + migrations + ordering + schema + UTC + recovery)
@@ -240,7 +240,7 @@ jobs:
# tree CI had passed minutes earlier). The lock spec's own two-migrator race is in-file
# (Promise.all) and unaffected by runInBand. The synchronize spec additionally CREATEs and
# DROPs a scratch database of its own, which is only safe serialized.
- run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts
+ run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts
env:
TZ: Asia/Jakarta
DATABASE_TYPE: postgres
diff --git a/src/modules/message/idempotency/send-idempotency.service.pg.spec.ts b/src/modules/message/idempotency/send-idempotency.service.pg.spec.ts
new file mode 100644
index 000000000..2845d2720
--- /dev/null
+++ b/src/modules/message/idempotency/send-idempotency.service.pg.spec.ts
@@ -0,0 +1,159 @@
+/* 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']);
+ });
+});