Struct EnvelopeLayerBuilder 

pub struct EnvelopeLayerBuilder { /* private fields */ }

Configuration for an super::EnvelopeLayer. Nothing is checked until build, and the calls may come in any order.

Implementations

impl EnvelopeLayerBuilder

pub fn build(self) -> Result<EnvelopeLayer, CratestackError>

Check the configuration: CratestackError::Validation when the audience is empty (it would bind no recipient), the policy or the transport is missing, the REST route table is empty (a rest(..) given another schema’s, or an RPC schema’s, empty table would bind nothing), the body limit or the contract trials is zero, an allow-listed template does not start with /, or the envelope’s media type is not a valid header value naming application/cose or a type the envelope claims.

impl EnvelopeLayerBuilder

pub fn policy(self, policy: impl EnvelopePolicy) -> EnvelopeLayerBuilder

Which mode each op runs in: an super::EnvelopeMode for all of them, or a closure per op. Required (decision D9).

pub fn rest( self, prefix: &str, routes: &'static [RouteTransportDescriptor], ) -> EnvelopeLayerBuilder

A REST router mounted at prefix ("" at the root), over the generated cratestack_schema::axum::ROUTE_TRANSPORTS, which must not be empty.

pub fn rpc(self, prefix: &str) -> EnvelopeLayerBuilder

A transport rpc router mounted at prefix ("" at the root).

pub fn binding_resolver( self, resolver: impl BindingResolver, ) -> EnvelopeLayerBuilder

A custom BindingResolver, instead of rest or rpc.

pub fn mount_prefix(self, prefix: &str) -> EnvelopeLayerBuilder

Where the router is mounted ("/api" for Router::nest("/api", router)). It wins over the prefix given to rest or rpc, whichever order the calls come in: the generated envelope_layer passes the root to those, so this is how its layer is told about a mount. Also what allow_unresolved templates are relative to.

pub fn allow_unresolved<I, T>(self, templates: I) -> EnvelopeLayerBuilder

where I: IntoIterator<Item = T>, T: Into<String>,

Route templates (as given to Router::route, relative to the mount prefix, e.g. "/health") that the router may match without the resolver knowing them: hand-written routes merged into the generated router before the layer. Plain traffic to them passes through unsigned. Any other matched route the resolver cannot bind fails closed with a 500 when the policy’s unresolved_mode is Required (decision S2), which is what a wrong or missing mount prefix looks like. A COSE body to an allow-listed route is still refused (415).

pub fn unresolved_mode(self, mode: EnvelopeMode) -> EnvelopeLayerBuilder

Replace the policy’s unresolved_mode with mode, whatever the policy answers (second-review nit). An explicit opt-in, mostly for a closure policy, whose unresolved_mode is always Required: with Optional or Off here, a matched route the resolver cannot bind passes through plain (warned about once per process) instead of failing closed with the 500, and so does every route when the mount prefix is wrong. It also lets through a method the schema does not generate on a generated path (normally the layer’s own 405), so a hand-written handler for that method runs unsigned. Prefer listing hand-written routes with allow_unresolved, which keeps a misconfiguration loud. The ops’ own modes are unchanged; a /rpc/batch whose frames cannot be read uses this mode too.

pub fn principal_mapper( self, mapper: impl PrincipalMapper, ) -> EnvelopeLayerBuilder

Replace super::ThumbprintPrincipal (cose:<hex thumbprint>; ThumbprintPrincipal::with_prefix(..) keeps the thumbprint and changes the prefix).

pub fn response_seal_policy( self, policy: impl ResponseSealPolicy, ) -> EnvelopeLayerBuilder

Replace super::AcceptNamesEnvelope (decision D10).

pub fn max_contract_trials(self, trials: usize) -> EnvelopeLayerBuilder

How many accepted digests the layer tries for a request that names none (no Cratestack-Contract header: a hand-built client), newest first. Default super::DEFAULT_MAX_CONTRACT_TRIALS; at least 1. A request that does name one is verified under it alone, so an up-to-date generated client costs one verification however long an op’s accepted list grows, and a forged request without the header costs one parse, one key resolution and at most this many signature verifications (the COSE envelope’s open_request_any; a custom ServerEnvelope that keeps the default pays the parse and the resolution per trial). A failed trial records no nonce.

pub fn max_body_bytes(self, limit: usize) -> EnvelopeLayerBuilder

The largest request body the layer buffers. Default super::DEFAULT_MAX_BODY_BYTES; keep it a little above the router’s own body limit, which applies to the payload after opening.

impl EnvelopeLayerBuilder

pub fn payload_media_types<I, J>( self, request: I, response: J, ) -> EnvelopeLayerBuilder

where I: IntoIterator, <I as IntoIterator>::Item: Into<String>, J: IntoIterator, <J as IntoIterator>::Item: Into<String>,

The payload media types the layer allows inside the seal: request for what a client seals, response for what the layer seals back. Default: application/cbor for both, so a layer that never calls this changes nothing for anyone: a request that names no type is bound and opened with the bytes 0.15.3 used (AAD and body), and answered by a response whose AAD and body are 0.15.3’s too. The one difference a 0.15.3 client can see is a new response header, Cratestack-Payload-Type, which it ignores.

A client names the type of its request in the unbound Cratestack-Payload-Type header and the response types it reads, in order, in Cratestack-Payload-Accept (the same selector pattern as Cratestack-Contract: they select among what is allowed and never widen it). Both are authenticated by the binding, not by the headers: a request binding names the request payload’s type, a response binding names the response payload’s own type, and a response repeats it in Cratestack-Payload-Type. A header that lies about the request fails the signature with the coarse 401. Binding version 2 and the COSE wire are unchanged.

What an op allows is this set intersected with the route’s declared types (ResolvedRoute::with_payload_types, filled from the schema’s capabilities by RestBindingResolver and RpcBindingResolver). /rpc/batch stays CBOR both ways. An empty route list (the generated reads and deletes, which take no payload) constrains nothing, and a GET, HEAD or DELETE is not checked for the type its empty payload names (bound as sent, never refused): a payload that is not empty is held to this set and the route’s once opened, and refused as a sealed 415.

A retry under the same Idempotency-Key must repeat its Cratestack-Payload-Accept: the idempotency layer fingerprints the request’s content type and body, not the types it reads, so a response stored for the first attempt in a type the retry did not negotiate is never sealed for it (a sealed 500, fail closed).

Refusals are unsigned and made before any key is looked up or nonce spent: a selector header sent twice or malformed is a 400, a request type outside the op’s set a 415 (payload_type_unsupported), and a Cratestack-Payload-Accept with no type the op can answer in a 406 (payload_type_not_acceptable). A handler’s success in a type the request did not negotiate is a sealed 500; its error in one is re-encoded in the transport’s error shape, in the client’s first choice of CBOR or JSON, and sealed.

build refuses a type outside the grammar of cratestack_core::parse_payload_type, one that may never be sealed (application/cose*, application/cbor-seq, text/event-stream, multipart/*), an empty request set, and a response set without application/cbor or application/json, which the layer’s own errors are sealed in.

use cratestack_axum::envelope_layer::EnvelopeLayer;
// vpay's shape: forms in, JSON out, and CBOR for the generated clients.
let builder = EnvelopeLayer::builder(envelope, "payments", &[]).payload_media_types(
    ["application/cbor", "application/x-www-form-urlencoded"],
    ["application/cbor", "application/json"],
);