ADR-0030: Durable Consumers Are Named Infrastructure, Not Ephemeral Session State

Context

BSFG already chose unary paged pull and durable named consumers for fetch progress. JetStream consumers are the mechanism that track delivery and acknowledgement state, and durable consumers persist that progress across disconnects and restarts. NATS also documents that pull consumers are intended for batching and horizontal scaling, and that streams and durable consumers can be managed administratively outside the application. :contentReference[oaicite:0]{index=0}

That leaves one architectural question: should BSFG consumer identities be treated as ephemeral runtime artifacts created freely by sessions, or as named infrastructure objects with governed lifecycle?

Options Considered

• simple local experimentation
• little up-front coordination

|

• progress identity becomes unstable
• restart semantics weaken
• consumer sprawl becomes likely

| | Application-managed durable consumers only | Let each runtime create and own durable consumers programmatically as needed. |

• high application flexibility
• less ops coordination initially

|

• naming discipline may drift
• runtime behavior can mutate infrastructure topology
• cleanup becomes inconsistent

| | Named infrastructure consumers (Selected) | Treat durable consumers as governed infrastructure objects with stable names and lifecycle. |

• stable fetch identity
• restart and failover semantics stay predictable
• consumer topology is observable and auditable
• fits administrative management model documented by NATS

|

• requires naming governance
• consumer lifecycle needs explicit ops ownership

| | Raw stream position without consumer identity | Skip consumer abstractions and track offsets entirely outside JetStream. |

• appears minimal
• avoids consumer administration

|

• gives up server-side acknowledgement tracking
• reimplements durable progress poorly
• misaligns with JetStream’s pull model

|

Decision

BSFG treats durable consumers as named infrastructure, not ephemeral session state.

consumer_name = stable logical reader identity
progress      = persisted server-side
lifecycle     = governed operationally

Practical implications:

• consumer names are well-known and deliberate
• fetch clients attach to an existing logical consumer identity
• restarts or failover reuse the same durable progress where appropriate
• ad hoc inspection may still use temporary consumers, but that is not the canonical BSFG path

Durable consumers may still be created programmatically, but they are part of infrastructure topology, not casual per-session runtime noise. NATS explicitly documents durable consumers as persistent stateful views and notes that they can be managed administratively outside the application. :contentReference[oaicite:1]{index=1}

Consequences

Benefits:

• consumer progress survives restarts in a predictable way
• replication topology is clearer to operators
• consumer sprawl is reduced
• horizontal sharing of pull consumers remains possible where intended. :contentReference[oaicite:2]{index=2}

Tradeoffs:

• consumer naming and ownership need governance
• unused durable consumers must be retired deliberately
• some experimentation paths are slightly less casual than fully ephemeral designs