Expand description
Telling other systems what happened, without ever slowing this one down.
§What is promised
Best-effort, at-least-once while the process lives. Every event carries a
stable id that retries reuse, so a consumer deduplicates on source + id.
Events for one subject arrive in the order they occurred, though a prefix
may be missing; nothing is promised across subjects.
Events are lost by exceptional ingress saturation, queue overflow, permanent rejection, exhausted retries, or the drain deadline at shutdown, each counted separately because they mean different things. Nothing survives a crash.
Hooks are not a substitute for reading state. Anything correctness- critical has to reconcile. If that ever stops being acceptable the answer is a durable outbox, not more retry settings.
§Why it cannot stall the caller
Hooks::deliver renders once, performs only bounded try_send operations,
and returns — no waiting, no queue scans, no network. Callers invoke it from
whatever task produced the event, often a media session’s own, so anything
slower would pause that work for whatever a remote endpoint felt like taking.
§What an application supplies
This crate owns the transport: CloudEvents rendering, per-subject ordering, drop-oldest overflow, retry with backoff, and a bounded drain at shutdown. It deliberately owns none of the vocabulary.
An application implements Occurrence for its own event type, naming the
Subject that ordering follows and the Kind that subscriptions
filter on. Two applications therefore share the machinery while promising
their consumers entirely different facts.
Structs§
- Config
Error - A destination that cannot deliver must fail before any dispatcher starts.
- Dispatchers
- Everything needed to run the configured hooks.
- Envelope
- One rendered event, immutable from here on.
- Hook
Config - One configured destination.
- Hook
Meters - Delivery counters and current saturation for one hook.
- Hook
Snapshot - One hook’s operational numbers at an instant.
- Hooks
- The enqueue side, held by whatever observes application events.
- Hooks
Config - Process-wide hook settings.
- Ignore
Hook Events - Discards everything, for a caller that wants no reporting.
- Invalid
Signing Secret - Render
Error - Renderer
- Builds envelopes for one node.
- Signing
Secret
Enums§
- Loss
- Why an event never reached its endpoint.
Constants§
- CONTENT_
TYPE - Structured-mode CloudEvents, as the specification names it.
Traits§
- Hook
Observer - Where this crate reports its own failures.
- Kind
- Which fact an event reports, and what a subscription list is written in.
- Occurrence
- One thing an application promises to report.
- Subject
- What delivery orders by: one subject’s events keep their relative order.
Functions§
- build
- Builds the enqueue side and the dispatchers that drain it.