durable

Overview ¶

Package durable is Harbor's StateStore-backed MessageBus driver. It persists every published BusEnvelope through the runtime's state.StateStore and projects it onto the local events.EventBus (the same projection contract the loopback driver uses), so bus traffic is replayable after a restart. A background poller scans the shared store for envelopes published by OTHER instances (or left by a crash, or whose local projection failed) and projects them onto the local event bus — at-least-once cross-instance fan-out.

Backend. StateStore-backed: each envelope is one record keyed by a time-ordered ULID under a common prefix; the poller enumerates them with a maintenance-scoped prefix scan. On a shared Postgres store this is Postgres-as-queue across instances; on SQLite it is single-instance restart-replay. NATS / Redis Streams remain future drivers in the same set. The StateStore exposes no change-notification primitive, so delivery is poll-based; a Postgres LISTEN/NOTIFY fast-path is a future optimization behind this same driver.

Scope. Opt-in via distributed.bus_driver: durable; the loopback driver stays the default. The driver fails loud at construction when no StateStore is wired (an operator who selected durable must get durability). Delivery is at-least-once: a restart re-projects persisted envelopes and a crash mid-publish may re-deliver, so consumers MUST be idempotent on (TaskID, Edge, EventID) — the MessageBus contract.