Struct Envelope 

#[non_exhaustive]
pub struct Envelope<T> {
    pub id: MessageId,
    pub message_type: MessageType,
    pub body: T,
    pub metadata: Metadata,
    /* private fields */
}

An envelope: a typed or serialized body plus the metadata Reliar understands and the custom headers it does not. Envelope != OutboxRecord != InboxRecord — nothing here carries delivery state (attempts, leases, dead-letter bookkeeping).

use reliar_core::Envelope;

#[derive(serde::Serialize, serde::Deserialize)]
struct Ping;
impl reliar_core::Message for Ping {
    const TYPE: &'static str = "ping";
    const VERSION: u16 = 1;
}

let envelope = Envelope::builder(Ping).build();
assert_eq!(envelope.message_type.to_string(), "ping.v1");

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: MessageId

The envelope’s own identity.

message_type: MessageType

The message’s stable contract identity — T::TYPE/T::VERSION, never chosen ad hoc.

body: T

The message body: typed on the application side, bytes::Bytes once serialized.

metadata: Metadata

Canonical, typed framework metadata — the single source of truth (ADR 0004).

Implementations

impl<T> Envelope<T>

pub fn headers(&self) -> Option<&Headers>

The envelope’s custom headers, if any were set.

use reliar_core::Envelope;
let envelope = Envelope::builder(Ping).build();
assert!(envelope.headers().is_none());

pub fn headers_mut(&mut self) -> &mut Headers

Mutably accesses the envelope’s custom headers, lazily allocating an empty Headers the first time this is called.

use reliar_core::Envelope;
let mut envelope = Envelope::builder(Ping).build();
envelope.headers_mut().insert("x-a", "1")?;
assert_eq!(envelope.headers().unwrap().get("x-a"), Some("1"));

pub fn set_headers(&mut self, headers: Option<Headers>)

Replaces the whole header map. The rehydration path for providers and transport mappers, which read back an already-validated map rather than inserting key by key.

use reliar_core::{Envelope, Headers};
let mut envelope = Envelope::builder(Ping).build();
let mut headers = Headers::default();
headers.insert("x-a", "1")?;
envelope.set_headers(Some(headers));
assert_eq!(envelope.headers().unwrap().get("x-a"), Some("1"));

pub fn map_body<U>(self, f: impl FnOnce(T) -> U) -> Envelope<U>

Converts the body, keeping every other field. The only conversion between typed and serialized envelopes — no field is ever re-declared, so none can be dropped in the process (ADR 0003).

use bytes::Bytes;
use reliar_core::Envelope;
let envelope = Envelope::builder(Ping).build();
let serialized: Envelope<Bytes> = envelope.map_body(|_| Bytes::from_static(b"{}"));
assert_eq!(serialized.body.as_ref(), b"{}");

pub fn try_map_body<U, E>( self, f: impl FnOnce(T) -> Result<U, E>, ) -> Result<Envelope<U>, E>

Fallible variant of Self::map_body, for SerializedEnvelope -> Envelope<T> via a Serializer.

Errors

Returns whatever error f returns, unchanged.

use bytes::Bytes;
use reliar_core::Envelope;
let wire = Envelope::builder(Ping)
    .build()
    .map_body(|_| Bytes::from_static(b"{}"));

let typed: Envelope<Ping> = wire.try_map_body(|_body| Ok::<_, std::convert::Infallible>(Ping))?;
assert_eq!(typed.message_type.to_string(), "ping.v1");

impl<T: Message> Envelope<T>

pub fn builder(body: T) -> EnvelopeBuilder<T>

Starts building an envelope for body. message_type is derived from T::TYPE/ T::VERSION and cannot be passed in (ADR 0010).

use reliar_core::Envelope;

#[derive(serde::Serialize, serde::Deserialize)]
struct OrderCreated { order_id: u64 }

impl reliar_core::Message for OrderCreated {
    const TYPE: &'static str = "orders.created";
    const VERSION: u16 = 1;
}

let envelope = Envelope::builder(OrderCreated { order_id: 42 })
    .tenant("acme")
    .header("x-import-batch", "2026-09-04")?
    .build();

assert_eq!(envelope.message_type.to_string(), "orders.created.v1");
assert_eq!(envelope.metadata.tenant_id.as_deref(), Some("acme"));

impl Envelope<Bytes>

pub fn from_parts( id: MessageId, message_type: MessageType, body: Bytes, metadata: Metadata, headers: Option<Headers>, ) -> Self

Rehydration entry point for providers and transport mappers, which have a MessageType read from storage or the wire rather than from a Rust type (ADR 0011).

use bytes::Bytes;
use reliar_core::{Metadata, MessageId, MessageType, SerializedEnvelope};

let envelope = SerializedEnvelope::from_parts(
    MessageId::new(),
    MessageType::from_parts("orders.created".to_string(), 1),
    Bytes::from_static(b"{}"),
    Metadata::default(),
    None,
);
assert_eq!(envelope.message_type.name(), "orders.created");

Trait Implementations

impl<T: Clone> Clone for Envelope<T>

Clone only where T: Clone — nothing in Reliar requires it, since a dispatcher moves owned records into publish tasks rather than cloning them; the impl exists for tests and host code.

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Envelope<T>

Elides the body unconditionally: a typed body may be arbitrary application data and a serialized one is raw payload bytes, and neither belongs in a log line (ADR 0003).

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: PartialEq> PartialEq for Envelope<T>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.