Delivery

A delivery carries its payload and its headers; each header is one SQS message attribute, String or Binary, at most ten.

A header the service takes as text travels as a String attribute, and any other value as a Binary one. A handler reads the same bytes either way, and never sees which type carried them. No envelope wraps the message, so any other SQS producer or consumer reads it as it is.

SQS takes at most ten attributes on one message. An attribute name is 1 to 256 letters, digits, _, - and ., and a value is never empty. A message SQS refuses fails the publish with SqsError::Publish, and the in-process account refuses it the same way. A message is at most 1 MiB, body and attributes together.

A handler reads the headers as a typed contract with Headers<T>, or one by one through cx.headers(). Two headers have meanings of their own: RECEIVE_COUNT_HEADER carries the queue's receive count, and PARTITION_KEY_HEADER the FIFO message group. A payload SQS would not take as text travels base64-encoded with one more attribute, as the body page describes. The crate adds no per-delivery context field, so a handler takes no Ctx<K> parameter here; what a delivery carries beyond its payload is in its headers.

Example

An order carries its tenant and a trace id as two message attributes, and the handler reads them as one contract.

Macros
Manual

examples/sqs_delivery_headers.rs
/// The headers an order carries: two message attributes on the queue.
#[derive(Debug, PartialEq, Deserialize, Serialize)]
struct OrderMeta {
    tenant: String,
    trace: Option<String>,
}

#[subscriber(SqsQueue::new("orders"))]
async fn bill(order: &Order, Headers(meta): Headers<OrderMeta>) -> HandlerOutcome {
    tracing::info!(order.id, meta.tenant, trace = ?meta.trace, "order billed");
    HandlerOutcome::ack()
}

examples/manual/sqs_delivery_headers.rs
/// The headers an order carries: two message attributes on the queue.
#[derive(Debug, PartialEq, Deserialize, Serialize, JsonSchema)]
#[schemars(crate = "ruststream::schemars")]
struct OrderMeta {
    tenant: String,
    trace: Option<String>,
}

struct Bill;

impl Handle<Message<OrderMeta, Order>> for Bill {
    fn handle(
        &self,
        msg: &Message<OrderMeta, Order>,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<(), HandlerOutcome>> {
        let (order, meta) = (&msg.body, &msg.headers);
        tracing::info!(order.id, meta.tenant, trace = ?meta.trace, "order billed");
        ready(Ok(()))
    }
}

Example​

Example