Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(infra): keep legacy failure backups restorable

Yudhi Armyndharisba084909ddba
diff --git a/src/modules/infra/export-tables.ts b/src/modules/infra/export-tables.ts
index e861a54bf..ef387b1b6 100644
--- a/src/modules/infra/export-tables.ts
+++ b/src/modules/infra/export-tables.ts
@@ -177,6 +177,8 @@ export interface ExportTable<K extends keyof MigrationTables = keyof MigrationTa
* export, because a backup that silently omits them is worse than no backup.
*/
optional?: boolean;
+ /** Columns read from SQL, excluding transient payloads before they can be materialized. */
+ columns?: readonly string[];
/**
* Rows carry an FK `sessionId` to sessions. The reads share no snapshot, so a session created after
* `sessions` was read can leave child rows here that would fail the restore's FK check and roll the
@@ -302,6 +304,19 @@ export const EXPORT_TABLES: AnyExportTable[] = [
key: 'webhookDeliveryFailures',
table: 'webhook_delivery_failures',
optional: true,
+ columns: [
+ 'id',
+ 'webhookId',
+ 'sessionId',
+ 'event',
+ 'url',
+ 'idempotencyKey',
+ 'deliveryId',
+ 'attempts',
+ 'lastStatusCode',
+ 'lastError',
+ 'createdAt',
+ ],
afterRead: stripWebhookFailurePayload,
}),
defineExportTable({ key: 'webhookOutboxEvents', table: 'webhook_outbox_events', optional: true }),
diff --git a/src/modules/infra/infra-data.controller.spec.ts b/src/modules/infra/infra-data.controller.spec.ts
index 6da286f12..1e375f640 100644
--- a/src/modules/infra/infra-data.controller.spec.ts
+++ b/src/modules/infra/infra-data.controller.spec.ts
@@ -1564,6 +1564,99 @@ describe('InfraDataController.import/export preserves every data-DB table', () =
expect((await outboxRepo.findOneByOrFail({ idempotencyKey: 'key-1' })).state).toBe('pending');
});
+ it('restores legacy terminal failures using a deterministic keeper without losing independent records', async () => {
+ await seedSession('s1');
+ const dump = await controller.exportData();
+ const base = {
+ webhookId: 'wh-1',
+ sessionId: 's1',
+ event: 'message.received',
+ url: 'https://receiver.example',
+ idempotencyKey: 'key-1',
+ deliveryId: null,
+ attempts: 3,
+ lastStatusCode: 503,
+ lastError: 'HTTP 503',
+ createdAt: '2026-10-05T00:00:00.000Z',
+ };
+ dump.tables.webhookDeliveryFailures = [
+ { ...base, id: 'a', attempts: 8 },
+ { ...base, id: 'b', payload: '{"body":"retained"}' },
+ { ...base, id: 'c', attempts: 0 },
+ { ...base, id: 'd', idempotencyKey: null },
+ { ...base, id: 'e', idempotencyKey: null },
+ { ...base, id: 'f', idempotencyKey: 'key-2', attempts: 5 },
+ { ...base, id: 'g', idempotencyKey: 'key-2', attempts: 5 },
+ ];
+ const result = await controller.importData({ tables: dump.tables });
+ expect(result.imported).toBe(true);
+ expect(result.warnings).toEqual([]);
+ const repository = ds.getRepository(WebhookDeliveryFailure);
+ expect((await repository.find({ order: { id: 'ASC' } })).map(row => row.id)).toEqual(['b', 'c', 'd', 'e', 'g']);
+ expect(result.counts.webhookDeliveryFailures).toBe(5);
+ expect(await repository.createQueryBuilder('failure').addSelect('failure.payload').getMany()).toEqual(
+ expect.arrayContaining([expect.objectContaining({ id: 'b', payload: null })]),
+ );
+ });
+
+ it.each(['primary-key', 'missing-url'] as const)(
+ 'preserves restore rollback for a %s error in terminal failures',
+ async problem => {
+ await seedSession('s1');
+ const dump = await controller.exportData();
+ const base = {
+ id: 'same-id',
+ webhookId: 'wh-1',
+ sessionId: 's1',
+ event: 'message.received',
+ url: 'https://receiver.example',
+ deliveryId: null,
+ attempts: 3,
+ lastStatusCode: 503,
+ lastError: 'HTTP 503',
+ createdAt: '2026-10-05T00:00:00.000Z',
+ };
+ dump.tables.webhookDeliveryFailures =
+ problem === 'primary-key'
+ ? [
+ { ...base, idempotencyKey: 'key-1' },
+ { ...base, idempotencyKey: 'key-2' },
+ ]
+ : [
+ { ...base, id: 'a', idempotencyKey: 'key-1', attempts: 1, url: null as unknown as string },
+ { ...base, id: 'b', idempotencyKey: 'key-1' },
+ ];
+ const result = await controller.importData({ tables: dump.tables });
+ expect(result.imported).toBe(false);
+ expect(result.warnings.join(' ')).toMatch(/UNIQUE constraint failed|NOT NULL constraint failed/);
+ expect(await ds.getRepository(Session).count()).toBe(1);
+ },
+ );
+
+ it('projects failure audit columns before reading retained payloads and supports the pre-payload schema', async () => {
+ await seedSession('s1');
+ const repository = ds.getRepository(WebhookDeliveryFailure);
+ await repository.save({
+ webhookId: 'wh-1',
+ sessionId: 's1',
+ event: 'message.received',
+ url: 'https://receiver.example',
+ idempotencyKey: 'key-1',
+ attempts: 3,
+ lastError: 'HTTP 503',
+ payload: { body: 'x'.repeat(2 * 1024 * 1024) },
+ });
+ const query = jest.spyOn(ds, 'query');
+ const dump = await controller.exportData();
+ expect(dump.tables.webhookDeliveryFailures).toHaveLength(1);
+ expect(dump.tables.webhookDeliveryFailures[0]).not.toHaveProperty('payload');
+ const reads = query.mock.calls.filter(([sql]) => /^SELECT .*FROM webhook_delivery_failures$/i.test(sql));
+ expect(reads).toHaveLength(1);
+ expect(reads[0][0]).not.toMatch(/\*|payload/);
+ await ds.query('ALTER TABLE webhook_delivery_failures DROP COLUMN payload');
+ expect((await controller.exportData()).tables.webhookDeliveryFailures).toEqual(dump.tables.webhookDeliveryFailures);
+ });
+
// A PostgreSQL export serializes CreateDateColumn/UpdateDateColumn values as ISO `...T...Z`, while
// TypeORM writes and compares them on SQLite as `YYYY-MM-DD HH:MM:SS.SSS`. Stored verbatim, a
// restored pending row never matched `createdAt < cutoff` on its own calendar day, so the replay
diff --git a/src/modules/infra/infra-data.service.ts b/src/modules/infra/infra-data.service.ts
index 3c75d7e86..15289bb68 100644
--- a/src/modules/infra/infra-data.service.ts
+++ b/src/modules/infra/infra-data.service.ts
@@ -20,7 +20,7 @@ import { In } from 'typeorm';
import { DateUtils } from 'typeorm/util/DateUtils';
import type { MigrationTables, TableCounts } from './migration-tables.types';
import { EXPORT_TABLES, EXPORT_TABLE_EXCLUSIONS, type AnyExportTable } from './export-tables';
-import { TABLE_IMPORTERS } from './table-importers';
+import { TABLE_IMPORTERS, deduplicateArchivedWebhookFailures } from './table-importers';
/**
* The ownership quartet SessionOwnershipService maintains: which process holds a session's engine and
@@ -417,7 +417,10 @@ export class InfraDataService {
const droppedBefore = inlineMediaBudget.droppedPayloads();
const rows: unknown[] = entry.inlineMedia
? await this.readInlineMediaTable(entry, entry.inlineMedia, sql => readTable(entry, sql), inlineMediaBudget)
- : await readTable(entry, `SELECT * FROM ${entry.table}`);
+ : await readTable(
+ entry,
+ `SELECT ${entry.columns?.map(column => `"${column}"`).join(', ') ?? '*'} FROM ${entry.table}`,
+ );
// `rows` was read for exactly this entry's table, so it holds the row type the entry's hooks
// declare. That correlation is what the erased entry type cannot carry, and this loop is the
// one place it is known — so the casts live here rather than at each hook.
@@ -846,7 +849,10 @@ export class InfraDataService {
// PostgreSQL-made backup compares and sorts like rows the app wrote itself.
const datetimeColumns = isPostgres ? undefined : sqliteDatetimeColumns(this.dataDataSource);
restore: for (const importer of TABLE_IMPORTERS) {
- const rows = data.tables[importer.key];
+ const rows =
+ importer.key === 'webhookDeliveryFailures'
+ ? deduplicateArchivedWebhookFailures(data.tables.webhookDeliveryFailures ?? [])
+ : data.tables[importer.key];
if (!rows?.length) continue;
const dateColumns = datetimeColumns?.get(importer.key) ?? [];
for (const archivedRow of rows) {
diff --git a/src/modules/infra/migration-tables.types.ts b/src/modules/infra/migration-tables.types.ts
index 99f9a9feb..61656c532 100644
--- a/src/modules/infra/migration-tables.types.ts
+++ b/src/modules/infra/migration-tables.types.ts
@@ -184,7 +184,7 @@ export interface WebhookDeliveryFailureRow {
attempts: number;
lastStatusCode: number | null;
lastError: string;
- /** Replay copy of the event; read by `SELECT *` but dropped from the export (see export-tables). */
+ /** Legacy archives may carry replay data; current exports omit it at the SQL projection. */
payload?: string | null;
createdAt: string;
}
diff --git a/src/modules/infra/table-importers.ts b/src/modules/infra/table-importers.ts
index 02596be02..a3cc3974b 100644
--- a/src/modules/infra/table-importers.ts
+++ b/src/modules/infra/table-importers.ts
@@ -79,6 +79,40 @@ function nulFree(value: unknown): unknown {
return NulFreeTransformer.to(value);
}
+/** Apply the terminal index's keeper order to archives created before that index existed. */
+export function deduplicateArchivedWebhookFailures(rows: WebhookDeliveryFailureRow[]): WebhookDeliveryFailureRow[] {
+ const owners = new Map<string, WebhookDeliveryFailureRow>();
+ const identity = (row: WebhookDeliveryFailureRow): string => JSON.stringify([row.webhookId, row.idempotencyKey]);
+ // SQLite's zone-less datetime strings represent UTC, just like PostgreSQL's explicit UTC exports.
+ const timestamp = (value: string): number =>
+ new Date(
+ /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(\.\d+)?$/.test(value) ? `${value.replace(' ', 'T')}Z` : value,
+ ).getTime();
+ // Malformed archive rows must still reach the normal all-or-nothing restore checks.
+ const eligible = (row: WebhookDeliveryFailureRow): boolean =>
+ row.attempts > 0 &&
+ row.idempotencyKey != null &&
+ [row.id, row.webhookId, row.sessionId, row.event, row.url, row.lastError, row.createdAt].every(
+ value => value != null,
+ );
+ for (const row of rows) {
+ if (!eligible(row)) continue;
+ const key = identity(row);
+ const previous = owners.get(key);
+ if (!previous) {
+ owners.set(key, row);
+ continue;
+ }
+ const rank =
+ Number(row.payload == null) - Number(previous.payload == null) ||
+ previous.attempts - row.attempts ||
+ timestamp(previous.createdAt) - timestamp(row.createdAt) ||
+ (row.id === previous.id ? 0 : row.id > previous.id ? -1 : 1);
+ if (rank < 0) owners.set(key, row);
+ }
+ return rows.filter(row => !eligible(row) || owners.get(identity(row)) === row);
+}
+
// (sessionId, NUL-free name) -> id of the first archived template holding it, built once per table.
const templateNameOwners = new WeakMap<TemplateRow[], Map<string, string>>();