IOutboxMessageSource
Namespace: Orleans.Durable.Messaging
public interface IOutboxMessageSourceRemarks
IOutbox stages a reference entry which carries the message ID and delivery state, but no payload or receiver, so the payload is journaled once, in the application's state. The outbox keeps every delivery semantic of an ordinary message: delivery after the sending write is durable, retries with backoff, dead-lettering after OutboxRetryTimeout, wake-ups, and metrics.
The outbox calls IOutboxMessageSource when the message is sent and before every delivery attempt. The first registered source which returns the message owns it for the activation's lifetime; for an entry recovered from the journal, the first source which returns the message or throws owns it. When the entry retires, the outbox calls the owner's IOutboxMessageSource once for that entry in the current activation, synchronously, while it stages the entry's removal. The source's journaled changes and the removal commit in the same journal write. If the activation fails before that write commits, recovery restores the pending entry and the source's prior journaled state, and retiring the recovered entry invokes IOutboxMessageSource again.
A source withdraws a pending message through IOutbox, for example after the application times it out or an administrator removes it, and releases its payload in the same journal write. The outbox removes the entry without calling IOutboxMessageSource and makes no further delivery attempt. An attempt already in flight can still deliver the message and reads the buffers which IOutboxMessageSource returned, so keep them unchanged: release them by dropping references rather than reusing them.
A source which can't provide a pending message after its send, for example because its stored payload no longer decodes, throws from IOutboxMessageSource; an invalid message is handled the same way. The outbox then dead-letters that entry alone, without delivering it, and calls IOutboxMessageSource with DeadLettered; the grain's messaging and its other messages are unaffected. A recovered entry which no registered source provides is dead-lettered the same way, without an owner to notify. Because no valid message exists, the dead letter's message carries only its Envelope, with an empty payload and a default OutboxMessage, and its reason records the failure.
All calls run on the activation scheduler. Register sources during activation setup, before journal recovery: a recovered reference entry fails the activation when no source is registered. While a source provides a message, it returns the same message, envelope and receiver alike, for every call.
Methods
OnRetired(MessageId, OutboxMessageRetirement)Notifies the source that the outbox is staging a message's retirement, so the source can release its payload.TryGetMessage(MessageId, OutboxMessage)Materializes a message for its send or a delivery attempt.
