Skip to main content

Module hooks

Module hooks 

Source
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§

ConfigError
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.
HookConfig
One configured destination.
HookMeters
Delivery counters and current saturation for one hook.
HookSnapshot
One hook’s operational numbers at an instant.
Hooks
The enqueue side, held by whatever observes application events.
HooksConfig
Process-wide hook settings.
IgnoreHookEvents
Discards everything, for a caller that wants no reporting.
InvalidSigningSecret
RenderError
Renderer
Builds envelopes for one node.
SigningSecret

Enums§

Loss
Why an event never reached its endpoint.

Constants§

CONTENT_TYPE
Structured-mode CloudEvents, as the specification names it.

Traits§

HookObserver
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.