Table of Contents

Interface ITransportReceiver

Namespace
Excalibur.Dispatch.Transport
Assembly
Excalibur.Dispatch.Transport.Abstractions.dll

Defines the minimal interface for receiving messages from a transport source. Replaces the bloated ICloudMessageConsumer (11 methods) with a focused contract (3 methods + GetService).

public interface ITransportReceiver : IAsyncDisposable
Inherited Members
Extension Methods

Remarks

Follows the Microsoft.Extensions.AI IChatClient pattern:

  • Minimal surface area — only core receive/ack/reject operations.
  • Advanced features (visibility timeout, start/stop, streaming) via GetService(Type).
  • Cross-cutting concerns (telemetry, DLQ routing) via DelegatingTransportReceiver decorators.

Properties

Source

Gets the source name (queue or subscription) this receiver is configured for.

string Source { get; }

Property Value

string

The source name.

Methods

AcknowledgeAsync(TransportReceivedMessage, CancellationToken)

Requests acknowledgement of successful processing of a message.

Task AcknowledgeAsync(TransportReceivedMessage message, CancellationToken cancellationToken)

Parameters

message TransportReceivedMessage

The message to acknowledge.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task

Task representing the acknowledgment operation.

Remarks

Returning normally means the provider completed the supported acknowledgement operation without reporting failure or refusal through its available response. Confirmation guarantees depend on the transport; completion does not guarantee durable broker acceptance or prevent redelivery. An implementation must throw on an observed failure, refusal, or unsupported operation. Callers must remain idempotent.

Exceptions

TransportSettlementException

The acknowledgement could not be completed or its outcome could not be determined. The broker may have accepted it before the failure became observable. Read RedeliveryExpectation to see whether the transport could determine redelivery, and Retryability before retrying the settlement. Clients of this interface must be idempotent.

GetService(Type)

Gets the underlying transport service (e.g., IConsumer, ServiceBusReceiver, IAmazonSQS).

object? GetService(Type serviceType)

Parameters

serviceType Type

The type of service to retrieve.

Returns

object

The service instance, or null if not available.

Remarks

Follows the IChatClient.GetService() pattern from Microsoft.Extensions.AI. Returns null if the requested service type is not available.

The default implementation answers for any service this instance itself implements, so a transport that provides one directly need not override it. A transport overrides it to hand out its native SDK handle, and a decorator overrides it to answer for itself before deferring to the transport it wraps.

Exceptions

ArgumentNullException

Thrown when serviceType is null.

ReceiveAsync(int, CancellationToken)

Receives messages from the source.

Task<IReadOnlyList<TransportReceivedMessage>> ReceiveAsync(int maxMessages, CancellationToken cancellationToken)

Parameters

maxMessages int

Maximum number of messages to receive.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<IReadOnlyList<TransportReceivedMessage>>

The received messages.

RejectAsync(TransportReceivedMessage, string?, bool, CancellationToken)

Rejects a message and optionally requeues it for retry.

Task RejectAsync(TransportReceivedMessage message, string? reason, bool requeue, CancellationToken cancellationToken)

Parameters

message TransportReceivedMessage

The message to reject.

reason string

The reason for rejection.

requeue bool

Whether to requeue the message for retry.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task

Task representing the reject operation.

Remarks

requeue states the outcome the caller requires: true asks the broker to deliver the message again, false asks it not to. Not every broker can suppress redelivery for a single message, and an implementation that cannot deliver the requested disposition must throw rather than silently substitute another operation. Normal return means the supported operation completed without an observed failure or refusal; broker confirmation and subsequent delivery depend on the transport.

Exceptions

TransportSettlementException

The rejection could not be completed or its outcome could not be determined. The broker may have accepted it before the failure became observable. Read RedeliveryExpectation to see whether the message is expected to arrive again, and Retryability before retrying the settlement. A failed requeue: false may leave a poison message queued.