Fix InvalidCastException starting a NATS listener with a dead-letter subject (GH-3739)

[jeremydmiller]

Closes #3739.

Reported against 6.16.0 and 6.23.1, and still present on main. Configuring any NATS JetStream listener with a dead-letter subject:

opts.ListenToNatsSubject(subject)
    .UseJetStream(streamName, consumerName)
    .ConfigureDeadLetterQueue(maxDeliveryAttempts, deadLetterSubject);

fails the whole host during WolverineRuntime.StartAsync:

System.InvalidCastException: Unable to cast object of type
'Wolverine.Transports.Sending.BufferedSendingAgent' to type
'Wolverine.Transports.Sending.ISender'.
   at Wolverine.Nats.Internal.NatsEndpoint.BuildListenerAsync
   at Wolverine.Transports.ListeningAgent.StartAsync()

Root cause

NatsEndpoint.BuildListenerAsync resolved the dead-letter sender by casting the result of IEndpointCollection.GetOrBuildSendingAgent(...) straight to ISender. That method returns an ISendingAgent — a BufferedSendingAgent, DurableSendingAgent or InlineSendingAgent — and none of those implement ISender, so the cast threw for every sending mode, not just some. The listener never started, and the only workaround was to drop the dead-letter subject entirely and let poison messages be acknowledged and discarded.

What changed

Reach through to the ISender the agent wraps rather than casting the agent, the same way EndpointCollection already does when it resolves connection state (both SendingAgent and InlineSendingAgent expose Sender).

This is the reporter's Option B, and the underlying sender is deliberately the right choice here rather than routing through the agent: NatsListener.MoveToErrorsAsync publishes the poison message and only then terminates JetStream delivery — the comment there is explicit that the forward happens first so a terminate failure can't lose the message. Enqueuing on a buffered agent would return before the message was on the wire, so a crash in between would drop the copy and terminate the original.

An unrecognized agent type now throws a named InvalidOperationException identifying the listener, dead-letter subject and actual agent type instead of a bare cast failure.

Tests

The NATS suite had no dead-letter coverage at all, which is how this survived two releases. NatsDeadLetterSubjectTests adds:

• listener_with_a_dead_letter_subject_starts_up — the startup regression, plus a pin that the resolved sender is the transport-level NatsSender and that the agent is genuinely not an ISender (so the test can't silently pass again if the cast is reintroduced).
• poison_message_is_forwarded_to_the_configured_dead_letter_subject — end to end: a handler throws, and a raw NATS subscriber on the dead-letter subject observes the forwarded copy carrying the original body and the x-dlq-original-subject failure metadata.

Verified as a real red baseline — both tests fail with exactly the reported InvalidCastException when the fix is reverted. Full NATS suite green locally (152 tests).

🤖 Generated with Claude Code