feat(nats): expose JetStream DeliverPolicy on transport + listener

[jeremydmiller]

Closes the gap in the user question on Wolverine NATS — there was no way to make an auto-provisioned JetStream consumer use DeliverPolicy.New (or anything other than the NATS-server default of All) without pre-creating the consumer outside Wolverine. This adds the knob at both the transport-wide and per-listener level.

Why

JetStreamSubscriber.StartAsync builds the consumer config with AckPolicy.Explicit / MaxDeliver / AckWait hardcoded and DeliverPolicy left unset — so every auto-provisioned consumer falls through to NATS's DeliverPolicy.All and replays every message currently in the stream on first connect. That's rarely what a host wants when standing up a new listener against a long-running stream.

What changed

A nullable ConsumerConfigDeliverPolicy? at two levels:

• Transport-wide — JetStreamDefaults.DeliverPolicy. Configure once via UseJetStream(d => d.DeliverPolicy = …) and every auto-provisioned consumer inherits it.
• Per-listener — NatsListenerConfiguration.DeliverFrom(...). Wins over the transport-wide default for a single endpoint.

Resolution lives on NatsEndpoint.EffectiveDeliverPolicy (endpoint > transport > null), computed at access time so configuration ordering is irrelevant. JetStreamSubscriber.StartAsync reads it and only writes to ConsumerConfig.DeliverPolicy when non-null — hosts that don't opt in see no behaviour change and the NATS-server default is preserved.

// Transport-wide default
opts.UseNats("nats://localhost:4222")
    .UseJetStream(js =>
    {
        js.DeliverPolicy = ConsumerConfigDeliverPolicy.New; // every consumer
                                                            // starts at "now"
    });

// Per-listener override (wins over the transport default)
opts.ListenToNatsSubject("orders.received")
    .UseJetStream("ORDERS")
    .DeliverFrom(ConsumerConfigDeliverPolicy.New);

The override applies only to consumers Wolverine itself auto-provisions. Pre-created consumers referenced by name through UseJetStream(streamName, consumerName) keep their existing config — that path already does GetConsumerAsync first and only falls through to CreateOrUpdateConsumerAsync on miss, so there's no behaviour change there either.

The endpoint's DeliverPolicy is also propagated when the endpoint clones itself for tenanted setups in CreateSender, so per-listener overrides flow through to per-tenant endpoints.

Test plan

• NatsDeliverPolicyTests 11/11 on net9.0 — covers default-null, EffectiveDeliverPolicy resolution at every precedence point, listener-configuration round-trip, and parameterized cases for All / Last / New / LastPerSubject.
• Existing NATS unit tests still pass (NatsEndpointUriTests, broker_role_tests).
• No behaviour change when neither knob is set — ConsumerConfig.DeliverPolicy is left untouched and the NATS server default applies, exactly as before.
• CI to confirm full integration suite (NatsTransportComplianceTests, BasicTests, etc.) — those need a NATS container which I don't have locally.

Docs

New Consumer Deliver Policy subsection under JetStream Configuration in docs/guide/messaging/transports/nats.md, with a code sample for both knobs and a table of the relevant ConsumerConfigDeliverPolicy values (including the OptStartSeq / OptStartTime caveat for ByStartSequence / ByStartTime, which require pre-creating the consumer since those supplemental properties have no listener-configuration surface here). vitepress build clean (17.29s).

🤖 Generated with Claude Code