Struct EnvelopeBuilder 

pub struct EnvelopeBuilder<T> { /* private fields */ }

Builds an Envelope<T>. Obtained from Envelope::builder.

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")
    .build();
assert_eq!(envelope.metadata.tenant_id.as_deref(), Some("acme"));

Implementations

impl<T: Message> EnvelopeBuilder<T>

pub fn id(self, id: MessageId) -> Self

Overrides the generated id. Defaults to a fresh UUIDv7.

use reliar_core::{Envelope, MessageId};
let id = MessageId::new();
let envelope = Envelope::builder(Ping).id(id).build();
assert_eq!(envelope.id, id);

pub fn metadata(self, metadata: Metadata) -> Self

Replaces the whole metadata struct, including its correlation metadata. Conversation rooting is decided by value, not by call order: if the replacement’s conversation_id is still crate::ConversationId::UNSET, Self::build roots it at the envelope’s own id regardless of an earlier Self::conversation call; a non-UNSET value (including one copied from a causing message) is kept.

use reliar_core::{Envelope, Metadata};
let mut metadata = Metadata::default();
metadata.tenant_id = Some("acme".to_string());
let envelope = Envelope::builder(Ping).metadata(metadata).build();
assert_eq!(envelope.metadata.tenant_id.as_deref(), Some("acme"));

pub fn correlation(self, correlation: CorrelationMetadata) -> Self

Replaces the correlation metadata (correlation id, conversation id, causation, request id) as a group. Same value-decides-rooting rule as Self::metadata.

use reliar_core::{CorrelationMetadata, Envelope};
let mut correlation = CorrelationMetadata::default();
correlation.causation_id = Some(reliar_core::MessageId::new());
let envelope = Envelope::builder(Ping).correlation(correlation).build();
assert!(envelope.metadata.correlation.causation_id.is_some());

pub fn correlation_id(self, id: CorrelationId) -> Self

Sets the business correlation id.

use reliar_core::{CorrelationId, Envelope};
let envelope = Envelope::builder(Ping)
    .correlation_id(CorrelationId::parse("checkout-42")?)
    .build();
assert_eq!(envelope.metadata.correlation.correlation_id.unwrap().as_str(), "checkout-42");

pub fn conversation(self, id: ConversationId) -> Self

Joins an existing conversation — typically the causing message’s own conversation_id. Self::build keeps this value as long as nothing later replaces it with Self::metadata or Self::correlation (setter order matters only in that sense: the last write to conversation_id wins, same as any other field).

use reliar_core::{ConversationId, Envelope};
use uuid::Uuid;
let parent_conversation = ConversationId::from_uuid(Uuid::now_v7());
let envelope = Envelope::builder(Ping).conversation(parent_conversation).build();
assert_eq!(envelope.metadata.correlation.conversation_id, parent_conversation);

pub fn causation(self, parent: MessageId) -> Self

Records the message that caused this one.

use reliar_core::{Envelope, MessageId};
let parent = MessageId::new();
let envelope = Envelope::builder(Ping).causation(parent).build();
assert_eq!(envelope.metadata.correlation.causation_id, Some(parent));

pub fn tenant(self, tenant_id: impl Into<String>) -> Self

Sets the owning tenant.

use reliar_core::Envelope;
let envelope = Envelope::builder(Ping).tenant("acme").build();
assert_eq!(envelope.metadata.tenant_id.as_deref(), Some("acme"));

pub fn expires_at(self, at: OffsetDateTime) -> Self

Sets the time after which the message must not be published.

use reliar_core::Envelope;
let one_day = time::Duration::days(1);
let envelope = Envelope::builder(Ping)
    .expires_at(time::OffsetDateTime::now_utc() + one_day)
    .build();
assert!(envelope.metadata.delivery.expires_at.is_some());

pub fn trace( self, traceparent: impl Into<String>, tracestate: Option<String>, ) -> Self

Sets the W3C Trace Context to carry verbatim. Reliar never invents or re-derives it (ADR 0004, ADR 0020).

use reliar_core::Envelope;
let envelope = Envelope::builder(Ping)
    .trace("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01", None)
    .build();
assert!(envelope.metadata.trace.traceparent.is_some());

pub fn header( self, k: impl Into<String>, v: impl Into<String>, ) -> Result<Self, HeaderError>

Sets one custom header. Returns Err if k uses the reserved reliar- prefix or breaches a cap (see Headers::insert).

Errors

Returns HeaderError under the same conditions as Headers::insert.

use reliar_core::Envelope;
let envelope = Envelope::builder(Ping).header("x-import-batch", "2026-09-04")?.build();
assert_eq!(envelope.headers().unwrap().get("x-import-batch"), Some("2026-09-04"));

pub fn build(self) -> Envelope<T>

Builds the envelope. message_type is MessageType::of::<T>(). conversation_id: iff it is still crate::ConversationId::UNSET, it becomes this envelope’s own id (an un-correlated message roots its own conversation); any other value — set via Self::conversation, Self::correlation, or Self::metadata — is kept verbatim. Rooting is decided by the value alone, never by which setter was called or in what order (ADR 0011).

use reliar_core::Envelope;
let envelope = Envelope::builder(Ping).build();
// An un-correlated message roots its own conversation.
assert_eq!(envelope.metadata.correlation.conversation_id.as_uuid(), envelope.id.as_uuid());

Trait Implementations

impl<T> Debug for EnvelopeBuilder<T>

Elides the body: an in-progress envelope’s body is arbitrary application data.

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

Formats the value using the given formatter.