Crate reliar_core

Expand description

reliar-core is the pure envelope/message model every Reliar crate builds on: identity newtypes, the Message contract, a validated Headers map, typed Metadata, and the Envelope/SerializedEnvelope pair that carries them (SRS §9–§17).

§Guarantees

Pure. No storage or transport dependency: no sqlx, no broker client, no routing concept (a Kafka partition key, a RabbitMQ exchange, a NATS subject). Every other Reliar crate depends on this one; this one depends on nothing Reliar-specific (ADR 0002).
One source of truth for framework metadata. Envelope::metadata is canonical for every concept Reliar understands. A value here is never duplicated into Envelope::headers, and Reliar never reads a framework value back out of headers (ADR 0004). Headers reserves the entire reliar- prefix, case-insensitively, so a custom header can never collide with — or be mistaken for — a framework one.
Message identity never depends on std::any::type_name::<T>() or a module path. A Message’s MessageType comes from its own TYPE/VERSION constants, so renaming or moving the Rust type is safe and two distinct types sharing them render identically (ADR 0010).
One envelope type for both sides of a serialization boundary. Envelope<T> and SerializedEnvelope (= Envelope<bytes::Bytes>) are the same generic type; converting between them (Envelope::map_body) can never drop or duplicate a field (ADR 0003).
Owns vocabulary every capability shares, nothing storage/transport-specific. An item belongs here when it names no storage engine, broker or transport routing concept and more than one Reliar capability needs it to talk to another — never merely because it is small (ADR 0032).

Every public error is a hand-rolled, #[non_exhaustive] enum with a wired std::error::Error::source — no thiserror, no anyhow. Debug on payload-bearing types elides the bytes; no Display here ever prints a payload, a header value, or a credential.

Structs§

ContentType: A validated MIME type. Owned by the Serializer that produced a payload — never chosen at the call site (ADR 0010).
ConversationId: Groups every message in one business conversation. Defaults to the id of the message that starts it (see crate::EnvelopeBuilder::build), so an un-correlated message is the root of its own conversation.
CorrelationId: Application/business workflow correlation id — distinct from ConversationId (Reliar’s own conversation root) and a causation_id (the direct parent message). Capped at Self::MAX_LEN bytes: it lands in a text column read on every claim (§11).
CorrelationMetadata: Correlation and conversation identity for one envelope.
DeliveryMetadata: Serialization and delivery hints for one envelope.
EndpointAddress: An opaque, transport-interpreted address string (a queue name, a subject, a service name — Reliar does not care which). Capped at Self::MAX_LEN bytes.
Envelope: An envelope: a typed or serialized body plus the metadata Reliar understands and the custom headers it does not (§9). Envelope != OutboxRecord != InboxRecord (§17) — nothing here carries delivery state (attempts, leases, dead-letter bookkeeping).
EnvelopeBuilder: Builds an Envelope<T>. Obtained from Envelope::builder.
Headers: Application-defined metadata Reliar does not understand: a validating newtype, never a HashMap alias and never exposed through Deref (ADR 0011). Reserves the entire reliar- prefix (case-insensitive) so framework metadata is never duplicated here — see Metadata for the one canonical source of truth (ADR 0004, §14).
JsonSerializer: The default Serializer: JSON via serde_json. Ships behind the default json feature; disable it to supply a different wire format (ADR 0010).
MessageId: Uniquely identifies one envelope end-to-end: enqueue, storage row, wire message, and, if it fails permanently, the dead entry.
MessageType: A message’s name and version, carried separately so a query can filter a name across every version (§24). Renders as "{name}.v{version}" via its Display impl.
Metadata: Canonical, typed framework metadata: the single source of truth. No value here is ever duplicated into Headers (ADR 0004).
RequestId: Correlates an envelope back to the inbound request (HTTP call, RPC, CLI invocation) that caused it, so an outbound message can be traced to its trigger.
RoutingMetadata: Transport-independent routing only. Kafka partition keys, RabbitMQ exchanges and NATS subject options are transport concepts and SHALL NOT appear here (§12).
TraceContext: W3C Trace Context, carried verbatim. Reliar never invents or re-derives it (ADR 0004, ADR 0020): a transport mapper writes these from an active span and reads them back on decode.

Enums§

ContentTypeError: ContentType::parse failures.
FailureKind: Whether a failure is worth retrying.
HeaderError: Headers::insert failures.
IdError: Validation failures shared by every capped string identity newtype in reliar-core.
JsonError: JsonSerializer failures. Display names the operation, the error class (serde_json::error::Category), and the line/column — never serde_json::Error’s own message, which for a data error embeds a fragment of the value it rejected (e.g. invalid type: string "sk-live-…", expected u64). The full underlying error, message included, is still reachable via std::error::Error::source for a caller that deliberately wants it — that caller’s own logging is then responsible for §33.
SettingsError: Why a *Settings::from_env call failed. OutboxSettings::from_env (reliar-outbox) was the first caller; every provider’s own from_env returns this same type (contract §7 I3).

Traits§

Classify: Implemented by every crate::Publisher::Error and OutboxStore::Error (reliar-outbox) so a dispatcher can decide retry vs. dead without a downcast. Carried by the error type, not by the publisher: the error value is what crosses a JoinSet boundary into the dispatcher, so it must carry its own verdict (ADR 0008).
EnvelopeMapper: Converts a SerializedEnvelope to and from one transport’s native message type M.
Message: A type that can be built into an Envelope and persisted or published.
Publisher: The wire side of the outbox. One provider implements this per transport.
Serializer: Converts a typed Message body to and from bytes. Lives in reliar-core: it touches neither storage nor transport (ADR 0010).

Type Aliases§

SerializedEnvelope: The persistence/transport form: an envelope whose body has already been serialized to bytes.