Struct Publisher 

pub struct Publisher { /* private fields */ }

Publishes outgoing Dispatches to the RabbitMQ cluster.

Distinguishes single publishing (try_publish and publish) from batch publishing (try_publish_many and publish_many).

Also, distinguishes fail-fast publishing (try_publish and try_publish_many) from error-less publishing (publish and publish_many).

Connection

This publisher delegates establishing connection and creation of Channels to Connector, which must be started before creating a publisher.

No more than one Channel is being kept by this publisher, and it is re-fetched whenever a connection issue is suspected.

Configuration

All publishing configuration is off-loaded to Egress.

One important part of the egress configuration is ConfirmationLevel. This level has significant consequences for the publishing process, as described in its documentation.

Publishing

Publishing a Dispatch to RabbitMQ is a two-step process:

1. Transmit the dispatch payload over network to the broker.
2. Confirm with the broker the successful reception of the message.

The transmission step plays out the same way regardless of the configuration. This publisher always transmits one dispatch at a time (there should be no benefit in transmitting dispatches in parallel in a single channel).

The confirmation step depends a lot on the confirmation level selected on the egress.

Batch benefits

The publishing of a Dispatch may be a one-step or a two-step process depending on the confirmation level of this publisher’s Egress.

The first step (transmission of the message to the broker) does not benefit from batching since the messages are transmitted one at a time. However, the second step (confirmation with the broker), if executed, can benefit from the batch approach.

Publishing API

The following four publishing methods are exposed.

All publishing methods return all Dispatches that were passed into them (both in the happy path and in the case of an error). It is up to the caller to then either drop the dispatches or use them for a different purpose (e.g., also publish them via a different Publisher).

try_publish: single Dispatch, fail-fast

Attempts once to publish a single dispatch and returns an error as soon as something goes wrong.

publish: single Dispatch, error-less

Repeatedly attempts to publish a single dispatch and returns only once the message is confirmed.

try_publish_many: batch of Dispatches, fail-fast

Attempts once to publish a batch of dispatches and returns an error as soon as something goes wrong.

publish_many: batch of Dispatches, error-less

Repeatedly attempts to publish a batch of dispatches and returns only once all the messages are confirmed.

Implementations

impl Publisher

pub fn new(gateway: Gateway, egress: Egress) -> Self

Creates and returns a new Publisher.

pub fn start(handle: impl AsRef<Handle>, egress: Egress) -> Self

Starts a new Connector with the given Handle and uses it to create and return a new Publisher for the given Egress.

impl Publisher

pub fn name(&self) -> &str

Reports the name of this Publisher.

impl Publisher

pub async fn try_publish( &self, dispatch: impl Into<Dispatch>, ) -> PublishingResult

Attempts once to publish a single Dispatch and returns an error as soon as something goes wrong.

The provided dispatch is returned back to the caller, both in the happy path and in the case of an error.

This is a fail-fast version of the single-dispatch publishing. For the error-less approach, use publish.

pub async fn publish(&self, dispatch: impl Into<Dispatch>) -> Dispatch

Repeatedly attempts to publish a single Dispatch and returns only once the message is confirmed.

The provided dispatch is returned back to the caller.

Note that the ConfirmationLevel on this publisher’s Egress will significantly affect the publishing semantics.

This is an error-less version of the single-dispatch publishing. For the fail-fast approach, use try_publish.

pub async fn try_publish_many<I>(&self, dispatches: I) -> BatchPublishingResult

where I: IntoIterator, I::Item: Into<Dispatch>,

Attempts once to publish a batch of Dispatches and returns an error as soon as something goes wrong.

The provided dispatches are all returned back to the caller, both in the happy path and in the case of an error.

This is a fail-fast version of the batch publishing. For the error-less approach, use publish_many.

pub async fn publish_many<I>(&self, dispatches: I) -> Vec<Dispatch>

where I: IntoIterator, I::Item: Into<Dispatch>,

Repeatedly attempts to publish a batch of Dispatches and returns only once all the messages are confirmed.

The provided dispatches are all returned back to the caller.

Note that the ConfirmationLevel on this publisher’s Egress will significantly affect the publishing semantics.

This is an error-less version of the batch publishing. For the fail-fast approach, use try_publish_many.