Skip to content

feat: deferred delivery with handler defaults and publish-time override - #94

Merged
dillonstreator merged 5 commits into
mainfrom
feat/deferred-delivery
Nov 5, 2026
Merged

dillonstreator merged 5 commits into
mainfrom
feat/deferred-delivery

Conversation

@dillonstreator

Copy link
Copy Markdown
Member

Summary

Adds deferred delivery: a handler declares a default defer and a publisher can override it per event. The publish-time defer is resolved to a timestamp at publish and stored on the event as defer_until; a handler's defer is resolved at fan-out. Either way the result lands in run_after on each new delivery.

// handler default: static or a function of the event
followUp: {
  defer: { delayMs: 3_600_000 },
  handle: async ({ event }) => { /* ... */ },
},
reminder: {
  defer: (event) => ({ until: event.data.remindAt }),
  handle: async ({ event }) => { /* ... */ },
},

// publish-time override, wins over every handler's default for this event
await outbox.publish(tx, "order.created", data, { defer: { delayMs: 0 } });
  • TxOBDefer = { delayMs: number } | { until: Date }. delayMs counts from event.created_at, so fan-out retries resolve to the same time.
  • event.defer_until: Date | null is persisted and visible to handler defer functions and handlers.
  • Invalid defer config fails at startup (static), at publish (publish-time), or leaves the event unfanned with a logged error (handler function), same path as invalid priority.
  • After fan-out, the processor schedules a poll at the earliest due time. scheduleTick now ignores timers longer than pollingIntervalMs, which also keeps clear of the setTimeout 24.8 day overflow previously reachable via backoffUntil.

Stores

Store Change
Postgres defer_until TIMESTAMPTZ on txob_events; completeFanout inserts run_after
memory, MongoDB, DynamoDB defer_until on event record; run_after on new deliveries
Redis defer_until hash field (ms); fan-out script places future deliveries in the delayed zset
Drizzle / Kysely schema helper and row types updated

Postgres fan-out passes run_after as text[] and casts in SQL: postgres.js (under Drizzle) has no encoder for timestamptz[] parameters.

Breaking

  • Postgres: new column. Existing installs run ALTER TABLE txob_events ADD COLUMN IF NOT EXISTS defer_until TIMESTAMPTZ; (see MIGRATING.md).
  • Custom stores: TxOBNewDelivery.run_after: Date | null is required; insertEvent must persist event.defer_until and return it from claims.

Tests

  • src/defer.test.ts: normalize / resolve units.
  • test/units.test.ts: compile validation, precedence (publish > handler fn > static), invalid defer leaves event unfanned, due-time poll ahead of a 60 s interval.
  • test/contract.ts: store-level future run_after held until due; processor-level defer with publish override. Runs against all five stores and seven ORM adapters.

All backends green. Postgres plus ORM adapters pass in isolation (304 tests). In one fully parallel 20 minute run, two kysely tests timed out from load, one of them pre-existing; neither reproduces alone.

Add `defer` to handler config (static `{ delayMs } | { until }` or a function
of the event) and a `defer` publish option that overrides it for every handler
of that event. The processor resolves the deferral at fan-out into
`run_after` on each new delivery; `delayMs` counts from `event.created_at` so
fan-out retries are deterministic.

- `TxOBEvent.defer` persisted; new `defer JSONB` column on `txob_events`
- `TxOBNewDelivery.run_after: Date | null` (breaking for custom stores)
- all stores honor `run_after` on fan-out; redis routes to the delayed zset
- processor schedules a poll at the earliest due time; `scheduleTick` skips
  timers longer than `pollingIntervalMs` (also avoids setTimeout overflow)
- pg fan-out passes `run_after` as `text[]`: postgres.js under Drizzle cannot
  encode `timestamptz[]` parameters
- docs, example, migration notes, changeset
Resolve the publish `defer` option at publish time into `event.defer_until`
instead of persisting the config object. The column is a plain TIMESTAMPTZ,
validation happens once in `publish`, and stores carry a Date like
`created_at` rather than a JSON blob. Handler defers still resolve at fan-out.
mongod 8.0.21-8.0.36 and 8.3.0-8.3.15 exit at startup on the GitHub runners'
Ubuntu kernels: their kernel 6.19+ guard does not recognise Ubuntu's version
numbering as already carrying the rseq fix (SERVER-131779). The exemption
ships in 8.3.16 / 8.0.37, which Docker Hub has not published yet; 9.0.4 has
it. Also drops the ubuntu-24.04 pin: that image's kernel is affected too.
@codecov

codecov Bot commented Nov 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.04%. Comparing base (b88589e) to head (8581d28).

Additional details and impacted files
@@            Coverage Diff             @@
##             main      #94      +/-   ##
==========================================
+ Coverage   95.88%   96.04%   +0.16%     
==========================================
  Files          32       33       +1     
  Lines        2163     2253      +90     
  Branches      416      455      +39     
==========================================
+ Hits         2074     2164      +90     
  Misses         72       72              
  Partials       17       17              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dillonstreator
dillonstreator merged commit 12415b7 into main Nov 5, 2026
4 checks passed
@dillonstreator
dillonstreator deleted the feat/deferred-delivery branch November 5, 2026 01:51
@github-actions github-actions Bot mentioned this pull request Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant