Documentation

Primary key of a keiro_outbox row. Stable across publish retries.

Lifecycle state of an outbox row.

• OutboxPending — never attempted.
• OutboxPublishing — currently held by a publisher worker (between claim and the call to mark sentfaileddead). Rows left in this state after a worker crash are reclaimed by outboxMaintenancePass after publishingTimeout.
• OutboxSent — Kafka acknowledged the publish; terminal.
• OutboxFailed — last attempt failed; will be retried after next_attempt_at.
• OutboxDead — terminal failure after maxAttempts consecutive failures. Stays in the table for operator inspection.

Ordering policy enforced by the publisher worker's claim query.

• PerKeyHeadOfLine (default) — within a source, a non-terminal row with key k blocks every later row with the same key. Rows with Nothing key bypass the block (Kafka does not promise cross-key order for null-keyed records). One stuck aggregate cannot stall traffic on other aggregates. Ordering is based on created_at, which PostgreSQL sets to transaction-start time; callers that concurrently enqueue the same key through escape hatches must serialize those enqueues themselves if commit order matters.
• PerSourceStream — within a source, any non-terminal row blocks every later row. Use when ordering matters across keys (rare). This has the same created_at concurrency caveat as PerKeyHeadOfLine.
• StopTheLine — any failure halts the worker until operator intervention. Use when correctness requires manual review on every failure.
• BestEffort — failed rows do not block; explicit opt-in only. Safe only when published events have no per-key/causal relationship.

Backoff curve used to compute next_attempt_at after a failure.

• ConstantBackoff — fixed delay between retries.
• ExponentialBackoff — exponential growth capped at maxDelay.

Knobs for ExponentialBackoff. delay = min maxDelay (initial * multiplier ^ (attempt - 1)).

A request to enqueue one integration event into the outbox. Callers generate outboxId (use a random UUID for ad-hoc enqueues, a deterministic UUID for idempotent retries from a saga/process manager).

A row read back from keiro_outbox. Worker code consumes these to publish to Kafka; tests use them to assert state transitions.

Knobs that govern one invocation of publishClaimedOutbox.

The optional tracer field opts the publisher into OpenTelemetry instrumentation: when present, the publisher opens a Producer-kind span around each publish call, attributing the first row's destination (topic), messageId, and Kafka key per the messaging semantic conventions. When tracer is Nothing (the default) the publisher emits no spans.

Aggregate result of one publisher pass.

published + retried + dead equals the number of rows claimed. retried includes rows that were skipped because an earlier row in the same ordered publish group failed; those rows are returned to failed without consuming an attempt. haltedOn is populated only by StopTheLine policy and names the failed pivot row, which is already counted in retried or dead.

Knobs for outboxMaintenancePass.

Schedule maintenance less frequently than publish passes; it owns crash reclamation and backlog gauge sampling.

Result of one outbox maintenance pass.

Sensible defaults: batch of 32, ten retry attempts, two-second constant backoff, per-key head-of-line ordering.

Maintenance defaults match the publisher's retry ceiling and stale-row timeout.

Validate outbox publisher options before starting a worker.

Wire representation of OutboxStatus used in the status column.

Inverse of statusText. Unknown database values are decode failures.

Compute the retry delay for an attempt number (1-based: 1 = first failure, 2 = second failure, …). Used by markOutboxFailedTx to derive next_attempt_at.