Headers

A header contract becomes the headers schema of its message, from a Headers<T> parameter or from #[outgoing(headers = ..)].

The contract struct derives JsonSchema, as a payload does. The schema describes the logical contract; on the wire each header value is a string (see Headers). On the receive side the contract is a Headers<T> parameter, or the header half of a Message<H, P> input. On the publish side it is the type's #[outgoing(headers = Meta)] declaration. A message component carries one contract. Two handlers that read one type with different contracts keep the first, and generation logs a warning. Without the macros a Message<H, P> input reports its contract. The example runs with cargo test --example asyncapi_reports --features macros,memory,asyncapi.

Example

Macros

examples/asyncapi_reports.rs

/// What travels in the headers of a shipment.
#[derive(Debug, Deserialize, JsonSchema)]
struct ShipmentMeta {
    /// The trace the shipment belongs to.
    trace_id: String,
    /// The carrier's attempt number.
    attempt: u32,
}

/// A parcel handed to the carrier.
#[derive(Debug, Deserialize, JsonSchema)]
struct Shipment {
    id: u64,
}

#[subscriber("shipments")]
async fn ship(shipment: &Shipment, Headers(meta): Headers<ShipmentMeta>) -> HandlerOutcome {
    tracing::info!(shipment.id, trace_id = %meta.trace_id, meta.attempt, "shipped");
    HandlerOutcome::ack()
}

Manual

examples/manual/asyncapi_reports.rs

/// What travels in the headers of a shipment.
#[derive(Debug, Deserialize, JsonSchema)]
struct ShipmentMeta {
    /// The trace the shipment belongs to.
    trace_id: String,
    /// The carrier's attempt number.
    attempt: u32,
}

/// A parcel handed to the carrier.
#[derive(Debug, Deserialize, JsonSchema)]
struct Shipment {
    id: u64,
}

/// The pair input carries the header contract, so the registration reports its schema.
struct Ship;

impl Handle<Message<ShipmentMeta, Shipment>> for Ship {
    fn handle(
        &self,
        shipment: &Message<ShipmentMeta, Shipment>,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<(), HandlerOutcome>> {
        let meta = &shipment.headers;
        tracing::info!(shipment.body.id, trace_id = %meta.trace_id, meta.attempt, "shipped");
        ready(Ok(()))
    }
}