This is the central bus for all events in the application. It sets up a channel and routes
received EventMessages to the Subscriptions of EventConsumers with matching topic patterns. Every subscription
has its own bounded inbox and worker, which calls the consumer’s handle_event method,
retries failed deliveries according to the subscription’s RetryPolicy and hands messages it gives up on to a
DeadLetterSink. When an inbox is full, the subscription’s Overflow policy decides whether routing waits or the
message is dead-lettered. Messages whose topic doesn’t match any subscription are dropped silently, and messages
carrying a TransportHandle are settled once all of their deliveries finished.
Messages are submitted to the channel using a [Sender], produced by the get_sender method.
While the sender can be used for submissions “as is”, the submit_event from the EventEmitter trait provides a safe default
implementation using channel permits, conveniently supporting both single and batched EventSubmissions.
A type representing an events context. EventTopics are generated from strings and used as either subscription patterns
or routing keys for event messages. Periods are used to create TopicSegments within a topic string to allow further categorisation
and structural representation. A topic intended as a routing key only permits strings of alphanumeric characters and
the characters .-_, ensuring it consists only of literal segments which can be used to match subscription pattern topics.
Setting up the topic as a subscription pattern allows topics to consist of alphanumeric characters as well as ., -, _, [, ], ,, *
enabling literal, wildcard (*) and selection ([val1,val2,valN]) segments. This will also enable tail matching if a wildcard segment is found at the end of the topic.
If many wildcard segments are found at the end of the pattern, one will be kept and the rest discarded, as it won’t affect matching. A topic
consisting of a single wildcard segment matches any other topic.
The error returned by EventConsumer::handle_event. Any
error converts into a transient HandlerError with ?, which is retried according to the
subscription’s RetryPolicy. Errors retrying won’t fix should be returned as
permanent, which dead-letters the message right away. Like
anyhow::Error, HandlerError doesn’t implement std::error::Error itself, as that would rule
out the conversion.
Decides how often a failed delivery is retried and how long its subscription waits between
attempts. A delivery keeps its subscription’s concurrency
slot while it waits, so a subscription handling one message at a time retries it before moving
on to the next. Delays that would overflow saturate at Duration::MAX, use
with_max_delay to cap them.
Configures one subscription of an EventConsumer: the topic pattern it matches and how messages
are delivered to it. Every subscription receives messages through its own bounded inbox, handles
up to concurrency of them at once, retries failed deliveries
according to its RetryPolicy and hands the messages it gives up on to its DeadLetterSink.
Settings left unset fall back to the broker’s.
Identifies the subscriptions of an EventConsumer registered with an EventBroker. Returned by
add_topic_consumer and consumed by
remove_topic_consumer to unsubscribe the consumer again.
The handle holds Weak references, so keeping it around does not keep the
consumer alive.
The subscriptions of an EventConsumer, each identified by a value of the consumer’s
Topic. Consumers with a single subscription can convert a pattern or a
Subscription into Subscriptions<()>.
A type representing a single topic segment. Topic segments are used to match against other topic segments. Literal segments
matched against other literal segments must be equal. Selection segments are matched against literal segments by checking if the literal segment
value is contained within the selection segment. Wildcard segments match against any segment. Selection segments are defined by square brackets and comma separated values.
When parsing selection segments, and inside the selection a wildcard segment is found, the entire selection will be parsed as wildcard. If a selection segment contains only a single
value, the segment will be parsed as literal. Multiple values will be sorted and deduplicated, so selection segment lookups should be fairly quick.
Wildcard segments are defined by a single asterisk. Literal segments are any other string. Selection values must be non-empty and may not
contain brackets or embedded wildcards; segments that could never match a routing key (like [a,] or a[b]) are rejected when parsed.
Receives the messages subscriptions give up on: after the handler failed permanently or used up
all retries of its RetryPolicy, or when the subscription’s inbox
overflowed. A sink can be set for all subscriptions with
EventBroker::with_dead_letter_sink and for a single
one with Subscription::with_dead_letter_sink.
Without a sink, these messages are logged and dropped.
Implementors are registered with an EventBroker and receive EventMessages on one or more
Subscriptions. Every subscription pairs a topic pattern with a value of the consumer’s
Topic, which is handed to handle_event
along with each Delivery it receives, so messages can be handled per subscription. A message
matching several subscriptions of a consumer is delivered once on each of them.
Enables implementors to submit one or more EventMessages to a channel connected
to an EventBroker. When overriding the submit_event default implementation,
implementors should ensure that cancel safety is maintained by using the channels reserve
method. Under normal circumstances, the EventBroker will handle any outstanding permits
when being shut down.
Carries the transport specific part of a message received from another messaging system, like
a JetStream message, a Kafka offset alongside its consumer or an AMQP acker. Attach it with
with_transport before submitting the message to an
EventBroker, and access it again through
Delivery::transport or EventMessage::transport.