Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

5.3 KB
Raw Blame
import { Column, CreateDateColumn, Entity, Index, PrimaryColumn } from 'typeorm';
import { dateColumnType, jsonColumnType } from '../../../common/utils/column-types';
import { DateTransformer } from '../../../common/transformers/date.transformer';

// The enqueue-outcome lifecycle of a persisted event, recorded AFTER the fast ack (persist-before-ack
// means the row always exists before dispatch is attempted):
//  - 'pending'    — written by recordOrSkip; dispatch not (yet) confirmed. The reconciler sweeps these.
//  - 'dispatched' — the event reached the dispatch tier (handed to BullMQ or delivered inline). A
//                   failure INSIDE the tier (BullMQ attempts exhausted) dead-letters separately, so a
//                   'dispatched' row is never the reconciler's concern.
//  - 'failed'     — terminal: the reconciler exhausted its replay budget or found the queue job failed,
//                   or the row aged past INGRESS_DEDUP_RETENTION_DAYS undispatched; recovery continues
//                   via the integration_delivery_failures row + RedriveService (none is written when the
//                   instance or session was deleted).
// NULL marks rows that predate these columns on synchronize-bootstrapped DBs (no backfill ran there);
// NULL reads as "not watched" — the reconciler never sweeps it, so an upgrade can never mass-replay
// the historical dedup log.
export type IngressDispatchState = 'pending' | 'dispatched' | 'failed';

// Persist-before-ack durable row + inbound dedup oracle. UNIQUE(pluginId, instanceId, providerDeliveryId):
// instanceId is only unique within a plugin, so pluginId must be part of the key or two plugins sharing an
// instanceId string would drop each other's deliveries as false duplicates.
//
// Storage shape: the FULL payload is carried only while the row is the sole durability handle — from
// recordOrSkip until the dispatch outcome is recorded ('dispatched') or the reconciler dead-letters it
// ('failed'). At that point the dispatch tier owns the payload (the BullMQ job, or the DLQ row on
// failure) and the row's payload is retired to NULL, leaving a slim dedup marker (~hundreds of bytes
// instead of up to 2× maxBodyBytes). payloadHash is kept permanently as the content fingerprint.
@Entity('ingress_events')
@Index('UQ_ingress_events_instance_delivery', ['pluginId', 'instanceId', 'providerDeliveryId'], { unique: true })
@Index('IDX_ingress_events_createdAt', ['createdAt'])
@Index('IDX_ingress_events_dispatchState', ['dispatchState', 'createdAt'])
export class IngressEvent {
  // Host-minted uuid (crypto.randomUUID()), NOT DB-generated — the id and the jobId (= deliveryId)
  // are decoupled on purpose. @PrimaryColumn, not @PrimaryGeneratedColumn.
  @PrimaryColumn()
  id!: string;

  @Column()
  instanceId!: string;

  @Column()
  pluginId!: string;

  @Column()
  providerDeliveryId!: string;

  @Column()
  route!: string;

  // NULL once the dispatch outcome is recorded (see the storage-shape comment above). The reconciler
  // only replays 'pending' rows, which always still carry the payload. NULL on a 'pending' row is
  // unreadable history (e.g. imported without one); the reconciler's sweep query excludes it silently,
  // and it stays pending until INGRESS_DEDUP_RETENTION_DAYS prunes it.
  // `method` is the request's HTTP method, so a replay reaches the handler as the live attempt did. Rows
  // written before it was persisted lack it, and dispatch falls back to 'POST' for them.
  // `admission.verified` is what the host decided when it accepted the request (false on a route that
  // authenticates nothing); a replay or retry hands the handler that verdict, not the route's current scheme.
  // Rows written before it was persisted lack it, and dispatch reads the route as it stands.
  @Column({ type: jsonColumnType(), nullable: true })
  payload!: {
    headers: Record<string, string>;
    query: Record<string, string>;
    body: string;
    rawBody: string;
    method?: string;
    admission?: { verified: boolean };
  } | null;

  // sha256 hex of the rawBody, written at recordOrSkip. Survives payload retirement so operators can
  // still correlate a dedup row with a provider delivery without storing the payload. NULL on rows
  // that predate the column (no backfill — their payloads are retired anyway).
  @Column({ type: 'varchar', nullable: true })
  payloadHash!: string | null;

  @Column({ type: 'varchar', nullable: true })
  sessionId!: string | null;

  // Nullable by design (see the IngressDispatchState comment above): NO DB default, because the
  // default 'pending' would also stamp pre-upgrade rows on the synchronize path and the reconciler
  // would replay the whole dedup log on deploy. New rows are 'pending' via recordOrSkip explicitly;
  // migration-managed DBs backfill existing rows to 'dispatched' instead.
  @Column({ type: 'varchar', nullable: true })
  dispatchState!: IngressDispatchState | null;

  // Dispatch-attempt counter the reconciler caps its replay budget against; the live path bumps it
  // on a swallowed inline-dispatch failure so those retries count too.
  @Column({ type: 'int', default: 0 })
  dispatchAttempts!: number;

  @Column({ type: dateColumnType(), nullable: true, transformer: DateTransformer })
  lastDispatchAt!: Date | null;

  @CreateDateColumn()
  createdAt!: Date;
}