Rename transport binding to WIP over HTTP

crates/wip-http/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "wip-http"
+version = "0.1.0"
+edition = "2024"
+description = "Framework-independent standard WIP over HTTP v1 binding"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+base64 = "0.22"
+http = "1"
+serde = "1"
+serde_json = "1"
+url = "2"
+wip-protocol = { path = "../wip-protocol" }

crates/wip-http/src/batch.rs

@@ -0,0 +1,570 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use http::header::{ACCEPT, CONTENT_TYPE};
+use http::{Method, Request, Response, StatusCode};
+use serde_json::{Map, Value as Json};
+use wip_protocol::{
+    FetchInterfaceRequest, FetchInterfaceResponse, INTERFACE_FORMAT_V1, ObserveRequest,
+    ObserveResponse, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
+};
+
+use crate::response::{self, DecodedResponse};
+use crate::{
+    BodyKind, ClientResponseError, CodecError, EncodeHttpError, Endpoint, InvalidResponseKind,
+    JSON_CONTENT_TYPE, Limits, ResourceLimitKind, Route, is_json_content_type, json,
+};
+
+/// A retrieval method accepted by the standard v1 batch endpoint.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BatchMethod {
+    /// Observe one object and its indexable descendants.
+    Observe,
+    /// Fetch one interface descriptor.
+    FetchInterface,
+}
+
+impl BatchMethod {
+    fn name(self) -> &'static str {
+        match self {
+            Self::Observe => "observe",
+            Self::FetchInterface => "fetch_interface",
+        }
+    }
+
+    fn interaction(self) -> ProtocolInteraction {
+        match self {
+            Self::Observe => ProtocolInteraction::Observe,
+            Self::FetchInterface => ProtocolInteraction::FetchInterface,
+        }
+    }
+}
+
+/// One retrieval interaction accepted by the standard v1 batch endpoint.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BatchRequestKind {
+    /// Observe one object and its indexable descendants.
+    Observe(ObserveRequest),
+    /// Fetch one interface descriptor.
+    FetchInterface(FetchInterfaceRequest),
+    /// A known method whose `arguments` are not a valid logical request.
+    Invalid {
+        /// Method that was successfully identified from the item envelope.
+        method: BatchMethod,
+        /// Item-local `invalid_request` to return without rejecting other items.
+        error: ProtocolError,
+    },
+}
+
+impl BatchRequestKind {
+    fn interaction(&self) -> ProtocolInteraction {
+        match self {
+            Self::Observe(_) => ProtocolInteraction::Observe,
+            Self::FetchInterface(_) => ProtocolInteraction::FetchInterface,
+            Self::Invalid { method, .. } => method.interaction(),
+        }
+    }
+}
+
+/// One uniquely identified batch subrequest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BatchRequestItem {
+    /// Identifier used only to correlate the corresponding subresponse.
+    pub id: String,
+    /// Retrieval interaction and arguments.
+    pub request: BatchRequestKind,
+}
+
+/// A standard v1 batch request.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BatchRequest {
+    /// Independent subrequests. Identifiers must be unique.
+    pub requests: Vec<BatchRequestItem>,
+}
+
+/// Successful result of one batch item.
+#[derive(Debug, Clone, PartialEq)]
+pub enum BatchSuccess {
+    /// Successful `observe` result.
+    Observe(ObserveResponse),
+    /// Successful `fetch_interface` result.
+    FetchInterface(FetchInterfaceResponse),
+}
+
+/// One batch subresponse, correlated by `id` rather than array position.
+#[derive(Debug, Clone, PartialEq)]
+pub struct BatchResponseItem {
+    /// Identifier copied from its subrequest.
+    pub id: String,
+    /// Direct interaction result or canonical item-local protocol failure.
+    pub outcome: Result<BatchSuccess, ProtocolError>,
+}
+
+/// A valid standard v1 batch response.
+#[derive(Debug, Clone, PartialEq)]
+pub struct BatchResponse {
+    /// Exactly one response for each requested identifier, in any order.
+    pub responses: Vec<BatchResponseItem>,
+}
+
+fn validate_ids<'a>(ids: impl Iterator<Item = &'a str>, maximum: usize) -> Result<(), CodecError> {
+    let mut seen = BTreeSet::new();
+    let mut count = 0;
+    for id in ids {
+        count += 1;
+        if !seen.insert(id) {
+            return Err(CodecError::DuplicateBatchId { id: id.into() });
+        }
+    }
+    if count > maximum {
+        return Err(CodecError::TooManyBatchItems {
+            actual: count,
+            maximum,
+        });
+    }
+    Ok(())
+}
+
+fn request_item_to_json(item: &BatchRequestItem) -> Result<Json, CodecError> {
+    let (method, arguments) = match &item.request {
+        BatchRequestKind::Observe(value) => ("observe", json::observe_request_to_json(value)),
+        BatchRequestKind::FetchInterface(value) => (
+            "fetch_interface",
+            json::fetch_interface_request_to_json(value),
+        ),
+        BatchRequestKind::Invalid { .. } => {
+            return Err(CodecError::InvalidField {
+                field: "requests".into(),
+                reason: "item-local invalid requests cannot be encoded as client requests".into(),
+            });
+        }
+    };
+    Ok(serde_json::json!({"id": item.id, "method": method, "arguments": arguments}))
+}
+
+fn request_to_json(request: &BatchRequest, limits: Limits) -> Result<Json, CodecError> {
+    validate_ids(
+        request.requests.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    for item in &request.requests {
+        match &item.request {
+            BatchRequestKind::Observe(value) => value.validate()?,
+            BatchRequestKind::FetchInterface(_) | BatchRequestKind::Invalid { .. } => {}
+        }
+    }
+    let requests = request
+        .requests
+        .iter()
+        .map(request_item_to_json)
+        .collect::<Result<Vec<_>, _>>()?;
+    Ok(serde_json::json!({"requests": requests}))
+}
+
+fn request_from_json(value: &Json, limits: Limits) -> Result<BatchRequest, CodecError> {
+    let fields = exact_object(value, "batch", &["requests"])?;
+    let values = array(required(fields, "requests")?, "requests")?;
+    if values.len() > limits.max_batch_items {
+        return Err(CodecError::TooManyBatchItems {
+            actual: values.len(),
+            maximum: limits.max_batch_items,
+        });
+    }
+    let mut requests = Vec::with_capacity(values.len());
+    for (index, value) in values.iter().enumerate() {
+        let field = format!("requests[{index}]");
+        let fields = exact_object(value, &field, &["id", "method", "arguments"])?;
+        let id = string(required(fields, "id")?, &format!("{field}.id"))?;
+        let method_name = string(required(fields, "method")?, &format!("{field}.method"))?;
+        let arguments = required(fields, "arguments")?;
+        let method = match method_name.as_str() {
+            "observe" => BatchMethod::Observe,
+            "fetch_interface" => BatchMethod::FetchInterface,
+            _ => {
+                return Err(CodecError::InvalidField {
+                    field: format!("{field}.method"),
+                    reason: "batch supports only observe and fetch_interface".into(),
+                });
+            }
+        };
+        let decoded = match method {
+            BatchMethod::Observe => {
+                json::observe_request_from_json(arguments).map(BatchRequestKind::Observe)
+            }
+            BatchMethod::FetchInterface => json::fetch_interface_request_from_json(arguments)
+                .map(BatchRequestKind::FetchInterface),
+        };
+        let request = decoded.unwrap_or_else(|error| BatchRequestKind::Invalid {
+            method,
+            error: ProtocolError {
+                code: ProtocolErrorCode::InvalidRequest,
+                message: format!("invalid {} arguments: {error}", method.name()),
+            },
+        });
+        requests.push(BatchRequestItem { id, request });
+    }
+    validate_ids(
+        requests.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    Ok(BatchRequest { requests })
+}
+
+/// Encodes a batch request using `POST v1/batch`.
+pub fn encode_batch_request(
+    endpoint: &Endpoint,
+    value: &BatchRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    let body = json::serialize(&request_to_json(value, limits)?, BodyKind::Request, limits)?;
+    Ok(Request::builder()
+        .method(Method::POST)
+        .uri(endpoint.route(Route::Batch).as_str())
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .header(ACCEPT, "application/json")
+        .body(body)?)
+}
+
+/// Decodes and validates a batch request body.
+pub fn decode_batch_request(body: &[u8], limits: Limits) -> Result<BatchRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    request_from_json(&value, limits)
+}
+
+fn success_to_json(success: &BatchSuccess) -> Json {
+    match success {
+        BatchSuccess::Observe(value) => json::observe_response_to_json(value),
+        BatchSuccess::FetchInterface(value) => json::fetch_interface_response_to_json(value),
+    }
+}
+
+fn response_to_json(
+    request: &BatchRequest,
+    response: &BatchResponse,
+    limits: Limits,
+) -> Result<Json, CodecError> {
+    correlate(request, response, limits)?;
+    Ok(serde_json::json!({
+        "responses": response.responses.iter().map(|item| {
+            let mut fields = Map::new();
+            fields.insert("id".into(), Json::String(item.id.clone()));
+            match &item.outcome {
+                Ok(success) => { fields.insert("result".into(), success_to_json(success)); }
+                Err(error) => { fields.insert("error".into(), response::item_error_to_json(error)); }
+            }
+            Json::Object(fields)
+        }).collect::<Vec<_>>()
+    }))
+}
+
+fn correlate(
+    request: &BatchRequest,
+    response: &BatchResponse,
+    limits: Limits,
+) -> Result<(), CodecError> {
+    validate_ids(
+        request.requests.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    validate_ids(
+        response.responses.iter().map(|item| item.id.as_str()),
+        limits.max_batch_items,
+    )?;
+    let requested: BTreeMap<&str, &BatchRequestKind> = request
+        .requests
+        .iter()
+        .map(|item| (item.id.as_str(), &item.request))
+        .collect();
+    for item in &response.responses {
+        let Some(kind) = requested.get(item.id.as_str()) else {
+            return Err(CodecError::UnexpectedBatchId {
+                id: item.id.clone(),
+            });
+        };
+        match (&item.outcome, *kind) {
+            (Ok(BatchSuccess::Observe(value)), BatchRequestKind::Observe(request)) => {
+                request.validate_response(value)?;
+            }
+            (
+                Ok(BatchSuccess::FetchInterface(value)),
+                BatchRequestKind::FetchInterface(request),
+            ) => {
+                value.validate_for(request)?;
+            }
+            (
+                Err(error),
+                BatchRequestKind::Invalid {
+                    error: expected, ..
+                },
+            ) if error == expected => {}
+            (Err(error), kind)
+                if !matches!(kind, BatchRequestKind::Invalid { .. })
+                    && error.code.is_allowed_for(kind.interaction()) => {}
+            _ => {
+                return Err(CodecError::BatchInteractionMismatch {
+                    id: item.id.clone(),
+                });
+            }
+        }
+    }
+    for item in &request.requests {
+        if !response.responses.iter().any(|other| other.id == item.id) {
+            return Err(CodecError::MissingBatchId {
+                id: item.id.clone(),
+            });
+        }
+    }
+    Ok(())
+}
+
+/// Encodes a valid batch response. Item failures remain inside HTTP 200.
+pub fn encode_batch_response(
+    request: &BatchRequest,
+    value: &BatchResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    let body = json::serialize(
+        &response_to_json(request, value, limits)?,
+        BodyKind::Response,
+        limits,
+    )?;
+    Ok(Response::builder()
+        .status(StatusCode::OK)
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)?)
+}
+
+/// Encodes a top-level batch-envelope failure.
+///
+/// Item-local failures belong in [`BatchResponseItem`]. Only failures that can
+/// reject the batch envelope before item execution are accepted here. A
+/// resource-limit failure defaults to the logical-limit status; use
+/// [`encode_batch_resource_limit_error_response`] when the concrete class is
+/// known.
+pub fn encode_batch_error_response(
+    error: &ProtocolError,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    if !matches!(
+        error.code,
+        ProtocolErrorCode::InvalidRequest
+            | ProtocolErrorCode::ResourceLimitExceeded
+            | ProtocolErrorCode::Internal
+    ) {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: "code is not valid for a top-level batch failure".into(),
+        }
+        .into());
+    }
+    let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
+    Ok(Response::builder()
+        .status(response::status_for_error(error.code))
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)?)
+}
+
+/// Encodes a class-specific top-level batch `resource_limit_exceeded` failure.
+pub fn encode_batch_resource_limit_error_response(
+    error: &ProtocolError,
+    kind: ResourceLimitKind,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    if error.code != ProtocolErrorCode::ResourceLimitExceeded {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: "resource-limit encoder requires resource_limit_exceeded".into(),
+        }
+        .into());
+    }
+    let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
+    Ok(Response::builder()
+        .status(response::status_for_resource_limit(kind))
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)?)
+}
+
+fn response_from_json(
+    value: &Json,
+    request: &BatchRequest,
+    limits: Limits,
+) -> Result<BatchResponse, CodecError> {
+    let fields = exact_object(value, "batch", &["responses"])?;
+    let values = array(required(fields, "responses")?, "responses")?;
+    if values.len() > limits.max_batch_items {
+        return Err(CodecError::TooManyBatchItems {
+            actual: values.len(),
+            maximum: limits.max_batch_items,
+        });
+    }
+    let requested: BTreeMap<&str, &BatchRequestKind> = request
+        .requests
+        .iter()
+        .map(|item| (item.id.as_str(), &item.request))
+        .collect();
+    let mut responses = Vec::with_capacity(values.len());
+    for (index, value) in values.iter().enumerate() {
+        let field = format!("responses[{index}]");
+        let fields = object(value, &field)?;
+        for name in fields.keys() {
+            if !["id", "result", "error"].contains(&name.as_str()) {
+                return Err(CodecError::UnknownField {
+                    field: format!("{field}.{name}"),
+                });
+            }
+        }
+        let id = string(required(fields, "id")?, &format!("{field}.id"))?;
+        let Some(kind) = requested.get(id.as_str()) else {
+            return Err(CodecError::UnexpectedBatchId { id });
+        };
+        let outcome = match (fields.get("result"), fields.get("error")) {
+            (Some(_), Some(_)) | (None, None) => {
+                return Err(CodecError::InvalidField {
+                    field,
+                    reason: "batch item must contain exactly one of result or error".into(),
+                });
+            }
+            (None, Some(error)) => {
+                let error = response::item_error_from_json(error)?;
+                match kind {
+                    BatchRequestKind::Invalid {
+                        error: expected, ..
+                    } if error == *expected => {}
+                    BatchRequestKind::Invalid { .. } => {
+                        return Err(CodecError::BatchInteractionMismatch { id });
+                    }
+                    kind if error.code.is_allowed_for(kind.interaction()) => {}
+                    _ => return Err(CodecError::BatchInteractionMismatch { id }),
+                }
+                Err(error)
+            }
+            (Some(result), None) => Ok(match kind {
+                BatchRequestKind::Observe(request) => {
+                    let value = json::observe_response_from_json(result)?;
+                    request.validate_response(&value)?;
+                    BatchSuccess::Observe(value)
+                }
+                BatchRequestKind::FetchInterface(request) => {
+                    let value = json::fetch_interface_response_from_json(result)?;
+                    value.validate_for(request)?;
+                    BatchSuccess::FetchInterface(value)
+                }
+                BatchRequestKind::Invalid { .. } => {
+                    return Err(CodecError::BatchInteractionMismatch { id });
+                }
+            }),
+        };
+        responses.push(BatchResponseItem { id, outcome });
+    }
+    let response = BatchResponse { responses };
+    correlate(request, &response, limits)?;
+    Ok(response)
+}
+
+/// Decodes a batch response, including item-local failures within HTTP 200.
+pub fn decode_batch_response<B: AsRef<[u8]>>(
+    request: &BatchRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<BatchResponse>, ClientResponseError> {
+    let valid_content_type = value
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(is_json_content_type);
+    if !valid_content_type {
+        if value.status().is_success() {
+            return Err(ClientResponseError::invalid(
+                InvalidResponseKind::InvalidBatch,
+                "missing or non-UTF-8 application/json Content-Type",
+            ));
+        }
+        return Err(response::transport_failure(value.status()));
+    }
+    let decoded = response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::Observe,
+        limits,
+        |json| response_from_json(json, request, limits),
+    )
+    .map_err(|error| match error {
+        ClientResponseError::InvalidResponse { detail, .. } => {
+            ClientResponseError::invalid(InvalidResponseKind::InvalidBatch, detail)
+        }
+        other => other,
+    })?;
+    if let DecodedResponse::ProtocolFailure { error, .. } = &decoded
+        && !matches!(
+            error.code,
+            ProtocolErrorCode::InvalidRequest
+                | ProtocolErrorCode::ResourceLimitExceeded
+                | ProtocolErrorCode::Internal
+        )
+    {
+        return Err(ClientResponseError::invalid(
+            InvalidResponseKind::InvalidBatch,
+            "protocol code is not valid for a top-level batch failure",
+        ));
+    }
+    if let DecodedResponse::Success(success) = &decoded {
+        for item in &success.responses {
+            if let Ok(BatchSuccess::FetchInterface(interface)) = &item.outcome
+                && interface.descriptor.format != INTERFACE_FORMAT_V1
+            {
+                return Err(ClientResponseError::UnsupportedDescriptorFormat {
+                    format: interface.descriptor.format.clone(),
+                });
+            }
+        }
+    }
+    Ok(decoded)
+}
+
+fn object<'a>(value: &'a Json, field: &str) -> Result<&'a Map<String, Json>, CodecError> {
+    value.as_object().ok_or_else(|| CodecError::InvalidField {
+        field: field.into(),
+        reason: "expected object".into(),
+    })
+}
+
+fn exact_object<'a>(
+    value: &'a Json,
+    field: &str,
+    allowed: &[&str],
+) -> Result<&'a Map<String, Json>, CodecError> {
+    let fields = object(value, field)?;
+    for name in fields.keys() {
+        if !allowed.contains(&name.as_str()) {
+            return Err(CodecError::UnknownField {
+                field: format!("{field}.{name}"),
+            });
+        }
+    }
+    Ok(fields)
+}
+
+fn required<'a>(fields: &'a Map<String, Json>, name: &str) -> Result<&'a Json, CodecError> {
+    fields
+        .get(name)
+        .ok_or_else(|| CodecError::MissingField { field: name.into() })
+}
+
+fn string(value: &Json, field: &str) -> Result<String, CodecError> {
+    value
+        .as_str()
+        .map(str::to_owned)
+        .ok_or_else(|| CodecError::InvalidField {
+            field: field.into(),
+            reason: "expected string".into(),
+        })
+}
+
+fn array<'a>(value: &'a Json, field: &str) -> Result<&'a [Json], CodecError> {
+    value
+        .as_array()
+        .map(Vec::as_slice)
+        .ok_or_else(|| CodecError::InvalidField {
+            field: field.into(),
+            reason: "expected array".into(),
+        })
+}

crates/wip-http/src/codec.rs

@@ -0,0 +1,604 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+use http::header::{ACCEPT, CONTENT_TYPE};
+use http::{HeaderMap, Method, Request, Response, StatusCode};
+use wip_protocol::{
+    CallOperationRequest, CallOperationResponse, FetchInterfaceRequest, FetchInterfaceResponse,
+    INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, ObserveRequest, ObserveResponse,
+    ProtocolError, ProtocolInteraction, Target,
+};
+
+use crate::response::{self, DecodedResponse};
+use crate::{
+    BodyKind, ClientResponseError, CodecError, Endpoint, InvalidResponseKind, JSON_CONTENT_TYPE,
+    Limits, ResourceLimitKind, Route, json,
+};
+
+fn request(
+    endpoint: &Endpoint,
+    route: Route,
+    body: Vec<u8>,
+) -> Result<Request<Vec<u8>>, http::Error> {
+    Request::builder()
+        .method(Method::POST)
+        .uri(endpoint.route(route).as_str())
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .header(ACCEPT, "application/json")
+        .body(body)
+}
+
+fn response(status: StatusCode, body: Vec<u8>) -> Result<Response<Vec<u8>>, http::Error> {
+    Response::builder()
+        .status(status)
+        .header(CONTENT_TYPE, JSON_CONTENT_TYPE)
+        .body(body)
+}
+
+fn require_response_content_type<B>(response: &Response<B>) -> Result<(), ClientResponseError> {
+    let valid = response
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(is_json_content_type);
+    if valid {
+        Ok(())
+    } else if response.status().is_success() {
+        Err(ClientResponseError::invalid(
+            InvalidResponseKind::InvalidSuccessBody,
+            "missing or non-UTF-8 application/json Content-Type",
+        ))
+    } else {
+        Err(response::transport_failure(response.status()))
+    }
+}
+
+fn is_utf8_charset(value: &str) -> bool {
+    let value = value.trim();
+    value.eq_ignore_ascii_case("utf-8")
+        || value
+            .strip_prefix('"')
+            .and_then(|value| value.strip_suffix('"'))
+            .is_some_and(|value| value.eq_ignore_ascii_case("utf-8"))
+}
+
+/// Returns whether a Content-Type value denotes UTF-8 `application/json`.
+///
+/// The charset parameter is optional because JSON exchanged by this binding is
+/// always UTF-8; when present, its value must be `utf-8`. Other parameters are
+/// rejected so intermediaries cannot silently select another representation.
+#[must_use]
+pub fn is_json_content_type(value: &str) -> bool {
+    let mut parts = value.split(';');
+    if !parts
+        .next()
+        .is_some_and(|media| media.trim().eq_ignore_ascii_case("application/json"))
+    {
+        return false;
+    }
+    let mut saw_charset = false;
+    for parameter in parts {
+        let Some((name, value)) = parameter.trim().split_once('=') else {
+            return false;
+        };
+        if !name.trim().eq_ignore_ascii_case("charset") || !is_utf8_charset(value) || saw_charset {
+            return false;
+        }
+        saw_charset = true;
+    }
+    true
+}
+
+fn accepts_json(headers: &HeaderMap) -> bool {
+    let mut present = false;
+    let mut best_match: Option<((u8, u8), f32)> = None;
+    for value in headers.get_all(ACCEPT) {
+        present = true;
+        let Ok(value) = value.to_str() else {
+            continue;
+        };
+        for range in value.split(',') {
+            let mut parts = range.split(';');
+            let media_range = parts.next().unwrap_or_default().trim();
+            let mut quality = 1.0_f32;
+            let mut saw_quality = false;
+            let mut saw_charset = false;
+            let mut media_parameter_count = 0;
+            let mut valid = true;
+            for parameter in parts {
+                let parameter = parameter.trim();
+                let (name, value) = parameter
+                    .split_once('=')
+                    .map_or((parameter, None), |(name, value)| {
+                        (name.trim(), Some(value))
+                    });
+                if name.is_empty() {
+                    valid = false;
+                    break;
+                }
+                if saw_quality {
+                    // Parameters after q are Accept extensions and do not
+                    // constrain the selected representation.
+                    continue;
+                }
+                if name.eq_ignore_ascii_case("q") {
+                    let Some(value) = value else {
+                        valid = false;
+                        break;
+                    };
+                    saw_quality = true;
+                    match value.trim().parse::<f32>() {
+                        Ok(value) if (0.0..=1.0).contains(&value) => quality = value,
+                        _ => {
+                            valid = false;
+                            break;
+                        }
+                    }
+                } else {
+                    let Some(value) = value else {
+                        valid = false;
+                        break;
+                    };
+                    if !name.eq_ignore_ascii_case("charset")
+                        || !is_utf8_charset(value)
+                        || saw_charset
+                    {
+                        valid = false;
+                        break;
+                    }
+                    saw_charset = true;
+                    media_parameter_count += 1;
+                }
+            }
+            let media_specificity = if media_range.eq_ignore_ascii_case("application/json") {
+                Some(2)
+            } else if media_range.eq_ignore_ascii_case("application/*") {
+                Some(1)
+            } else if media_range == "*/*" {
+                Some(0)
+            } else {
+                None
+            };
+            if valid && let Some(media_specificity) = media_specificity {
+                let specificity = (media_specificity, media_parameter_count);
+                match best_match {
+                    Some((best_specificity, _)) if best_specificity > specificity => {}
+                    Some((best_specificity, best_quality)) if best_specificity == specificity => {
+                        best_match = Some((specificity, best_quality.max(quality)));
+                    }
+                    _ => best_match = Some((specificity, quality)),
+                }
+            }
+        }
+    }
+    if present {
+        best_match.is_some_and(|(_, quality)| quality > 0.0)
+    } else {
+        true
+    }
+}
+
+/// A failure while validating inbound HTTP request metadata.
+#[derive(Debug)]
+pub enum RequestMetadataError {
+    /// The method or route does not match the selected WIP interaction.
+    InvalidRequest(CodecError),
+    /// The request body does not use UTF-8 `application/json`.
+    UnsupportedMediaType,
+    /// The request's `Accept` metadata excludes `application/json`.
+    NotAcceptable,
+}
+
+impl RequestMetadataError {
+    /// Returns the HTTP status for this metadata failure.
+    #[must_use]
+    pub const fn status(&self) -> StatusCode {
+        match self {
+            Self::InvalidRequest(_) => StatusCode::BAD_REQUEST,
+            Self::UnsupportedMediaType => StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            Self::NotAcceptable => StatusCode::NOT_ACCEPTABLE,
+        }
+    }
+}
+
+impl Display for RequestMetadataError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidRequest(error) => error.fmt(formatter),
+            Self::UnsupportedMediaType => {
+                formatter.write_str("expected UTF-8 application/json Content-Type")
+            }
+            Self::NotAcceptable => formatter.write_str("request does not accept application/json"),
+        }
+    }
+}
+
+impl Error for RequestMetadataError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidRequest(error) => Some(error),
+            Self::UnsupportedMediaType | Self::NotAcceptable => None,
+        }
+    }
+}
+
+/// Validates mandatory HTTP metadata for an inbound WIP request.
+///
+/// Both absolute-form and origin-form request URIs are accepted, but the path
+/// must exactly equal the selected endpoint route and a query is forbidden.
+/// Unsupported content negotiation is reported as a Transport Binding metadata
+/// failure rather than a Core `invalid_request`.
+pub fn validate_http_request<B>(
+    endpoint: &Endpoint,
+    route: Route,
+    value: &Request<B>,
+) -> Result<(), RequestMetadataError> {
+    if value.method() != Method::POST {
+        return Err(RequestMetadataError::InvalidRequest(
+            CodecError::InvalidField {
+                field: "method".into(),
+                reason: "standard WIP routes require POST".into(),
+            },
+        ));
+    }
+    let expected = endpoint.route(route);
+    if value.uri().path() != expected.path() || value.uri().query().is_some() {
+        return Err(RequestMetadataError::InvalidRequest(
+            CodecError::InvalidField {
+                field: "route".into(),
+                reason: "request URI does not match the selected standard route".into(),
+            },
+        ));
+    }
+    let valid_content_type = value
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(is_json_content_type);
+    if !valid_content_type {
+        return Err(RequestMetadataError::UnsupportedMediaType);
+    }
+    if !accepts_json(value.headers()) {
+        return Err(RequestMetadataError::NotAcceptable);
+    }
+    Ok(())
+}
+
+/// Encodes an `observe` HTTP request.
+pub fn encode_observe_request(
+    endpoint: &Endpoint,
+    value: &ObserveRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    value.validate().map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::observe_request_to_json(value),
+        BodyKind::Request,
+        limits,
+    )?;
+    Ok(request(endpoint, Route::Observe, body)?)
+}
+
+/// Decodes an `observe` request body.
+pub fn decode_observe_request(body: &[u8], limits: Limits) -> Result<ObserveRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::observe_request_from_json(&value)
+}
+
+/// Encodes a `fetch_interface` HTTP request.
+pub fn encode_fetch_interface_request(
+    endpoint: &Endpoint,
+    value: &FetchInterfaceRequest,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    let body = json::serialize(
+        &json::fetch_interface_request_to_json(value),
+        BodyKind::Request,
+        limits,
+    )?;
+    Ok(request(endpoint, Route::FetchInterface, body)?)
+}
+
+/// Decodes a `fetch_interface` request body.
+pub fn decode_fetch_interface_request(
+    body: &[u8],
+    limits: Limits,
+) -> Result<FetchInterfaceRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::fetch_interface_request_from_json(&value)
+}
+
+/// Descriptor-independent fields needed to resolve a `call_operation` request.
+///
+/// A Host decodes this metadata first, fixes the current interface descriptor,
+/// then passes the same body and descriptor to [`decode_call_operation_request`].
+/// This preserves canonical path/interface/operation lookup and error precedence
+/// without treating unvalidated argument JSON as a logical [`wip_protocol::Value`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CallOperationMetadata {
+    /// Path and optional object-state precondition.
+    pub target: Target,
+    /// Interface reference and optional interface precondition.
+    pub interface: InterfaceTarget,
+    /// Operation name used to select a declaration.
+    pub operation: String,
+}
+
+impl CallOperationMetadata {
+    /// Decodes the descriptor-bound request and verifies that routing metadata
+    /// still matches the values used to resolve `descriptor`.
+    pub fn decode_request(
+        &self,
+        body: &[u8],
+        descriptor: &InterfaceDescriptor,
+        limits: Limits,
+    ) -> Result<CallOperationRequest, CodecError> {
+        let request = decode_call_operation_request(body, descriptor, limits)?;
+        if request.target != self.target
+            || request.interface != self.interface
+            || request.operation != self.operation
+        {
+            return Err(CodecError::InvalidField {
+                field: "request".into(),
+                reason: "call metadata changed after descriptor resolution".into(),
+            });
+        }
+        Ok(request)
+    }
+}
+
+/// Decodes descriptor-independent `call_operation` routing metadata.
+pub fn decode_call_operation_metadata(
+    body: &[u8],
+    limits: Limits,
+) -> Result<CallOperationMetadata, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    let (target, interface, operation) = json::call_request_metadata_from_json(&value)?;
+    Ok(CallOperationMetadata {
+        target,
+        interface,
+        operation,
+    })
+}
+
+/// Encodes a descriptor-bound `call_operation` HTTP request.
+pub fn encode_call_operation_request(
+    endpoint: &Endpoint,
+    value: &CallOperationRequest,
+    descriptor: &InterfaceDescriptor,
+    limits: Limits,
+) -> Result<Request<Vec<u8>>, EncodeHttpError> {
+    let value = json::call_request_to_json(value, descriptor)?;
+    let body = json::serialize(&value, BodyKind::Request, limits)?;
+    Ok(request(endpoint, Route::CallOperation, body)?)
+}
+
+/// Decodes a descriptor-bound `call_operation` request body.
+pub fn decode_call_operation_request(
+    body: &[u8],
+    descriptor: &InterfaceDescriptor,
+    limits: Limits,
+) -> Result<CallOperationRequest, CodecError> {
+    let value = json::parse(body, BodyKind::Request, limits)?;
+    json::call_request_from_json(&value, descriptor)
+}
+
+/// Encodes a successful `observe` response as a direct body with HTTP 200.
+pub fn encode_observe_response(
+    request_value: &ObserveRequest,
+    value: &ObserveResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    request_value
+        .validate_response(value)
+        .map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::observe_response_to_json(value),
+        BodyKind::Response,
+        limits,
+    )?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies an `observe` client response.
+pub fn decode_observe_response<B: AsRef<[u8]>>(
+    request_value: &ObserveRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<ObserveResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::Observe,
+        limits,
+        |json| {
+            let observation = json::observe_response_from_json(json)?;
+            request_value.validate_response(&observation)?;
+            Ok(observation)
+        },
+    )
+}
+
+/// Encodes a successful `fetch_interface` response as a direct body with HTTP 200.
+pub fn encode_fetch_interface_response(
+    request_value: &FetchInterfaceRequest,
+    value: &FetchInterfaceResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    value
+        .validate_for(request_value)
+        .map_err(CodecError::from)?;
+    let body = json::serialize(
+        &json::fetch_interface_response_to_json(value),
+        BodyKind::Response,
+        limits,
+    )?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies a `fetch_interface` client response.
+pub fn decode_fetch_interface_response<B: AsRef<[u8]>>(
+    request_value: &FetchInterfaceRequest,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<FetchInterfaceResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    let decoded = response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::FetchInterface,
+        limits,
+        |json| {
+            let interface = json::fetch_interface_response_from_json(json)?;
+            interface.validate_for(request_value)?;
+            Ok(interface)
+        },
+    )?;
+    if let DecodedResponse::Success(success) = &decoded
+        && success.descriptor.format != INTERFACE_FORMAT_V1
+    {
+        return Err(ClientResponseError::UnsupportedDescriptorFormat {
+            format: success.descriptor.format.clone(),
+        });
+    }
+    Ok(decoded)
+}
+
+/// Encodes a successful `call_operation` response as a direct body with HTTP 200.
+pub fn encode_call_operation_response(
+    request_value: &CallOperationRequest,
+    descriptor: &InterfaceDescriptor,
+    value: &CallOperationResponse,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    let json = json::call_response_to_json(value, descriptor, &request_value.operation)?;
+    let body = json::serialize(&json, BodyKind::Response, limits)?;
+    Ok(response(StatusCode::OK, body)?)
+}
+
+/// Decodes and classifies a descriptor-bound `call_operation` client response.
+pub fn decode_call_operation_response<B: AsRef<[u8]>>(
+    request_value: &CallOperationRequest,
+    descriptor: &InterfaceDescriptor,
+    value: &Response<B>,
+    limits: Limits,
+) -> Result<DecodedResponse<CallOperationResponse>, ClientResponseError> {
+    require_response_content_type(value)?;
+    response::decode(
+        value.status(),
+        value.body().as_ref(),
+        ProtocolInteraction::CallOperation,
+        limits,
+        |json| json::call_response_from_json(json, descriptor, &request_value.operation),
+    )
+}
+
+fn validate_protocol_error(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+) -> Result<(), CodecError> {
+    if !error.code.is_allowed_for(interaction) {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: format!(
+                "code `{}` is not allowed for {interaction:?}",
+                response::error_code_name(error.code)
+            ),
+        });
+    }
+    Ok(())
+}
+
+fn encode_protocol_error_with_status(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+    status: StatusCode,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    validate_protocol_error(interaction, error)?;
+    let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
+    Ok(response(status, body)?)
+}
+
+/// Encodes a canonical Host error envelope using its standard HTTP status.
+///
+/// The code must be allowed for `interaction`. This API accepts only
+/// [`ProtocolError`], so client-local `InvalidResponse` and
+/// `UnsupportedDescriptorFormat` classifications cannot be emitted as Host
+/// error envelopes. Resource-limit errors use the logical-limit status; callers
+/// that know the concrete limit class should use
+/// [`encode_resource_limit_error_response`].
+pub fn encode_protocol_error_response(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    encode_protocol_error_with_status(
+        interaction,
+        error,
+        response::status_for_error(error.code),
+        limits,
+    )
+}
+
+/// Encodes a `resource_limit_exceeded` envelope with its class-specific status.
+pub fn encode_resource_limit_error_response(
+    interaction: ProtocolInteraction,
+    error: &ProtocolError,
+    kind: ResourceLimitKind,
+    limits: Limits,
+) -> Result<Response<Vec<u8>>, EncodeHttpError> {
+    if error.code != wip_protocol::ProtocolErrorCode::ResourceLimitExceeded {
+        return Err(CodecError::InvalidField {
+            field: "error.code".into(),
+            reason: "resource-limit encoder requires resource_limit_exceeded".into(),
+        }
+        .into());
+    }
+    encode_protocol_error_with_status(
+        interaction,
+        error,
+        response::status_for_resource_limit(kind),
+        limits,
+    )
+}
+
+/// Failure while building an outbound framework-neutral HTTP message.
+#[derive(Debug)]
+pub enum EncodeHttpError {
+    /// JSON or protocol encoding failed.
+    Codec(CodecError),
+    /// The framework-neutral HTTP message builder rejected the URI or headers.
+    Http(http::Error),
+}
+
+impl std::fmt::Display for EncodeHttpError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Codec(error) => error.fmt(formatter),
+            Self::Http(error) => error.fmt(formatter),
+        }
+    }
+}
+
+impl std::error::Error for EncodeHttpError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Codec(error) => Some(error),
+            Self::Http(error) => Some(error),
+        }
+    }
+}
+
+impl From<CodecError> for EncodeHttpError {
+    fn from(value: CodecError) -> Self {
+        Self::Codec(value)
+    }
+}
+
+impl From<http::Error> for EncodeHttpError {
+    fn from(value: http::Error) -> Self {
+        Self::Http(value)
+    }
+}

crates/wip-http/src/endpoint.rs

@@ -0,0 +1,147 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+use url::Url;
+
+/// The media type emitted for every WIP request and every response with a body.
+pub const JSON_CONTENT_TYPE: &str = "application/json; charset=utf-8";
+
+/// A fixed standard WIP over HTTP v1 route.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Route {
+    /// Observe one object and its indexable descendants.
+    Observe,
+    /// Fetch an interface descriptor.
+    FetchInterface,
+    /// Call one operation.
+    CallOperation,
+    /// Package independent retrieval interactions.
+    Batch,
+}
+
+impl Route {
+    /// Returns the RFC 3986 relative reference used below an endpoint prefix.
+    #[must_use]
+    pub const fn relative_reference(self) -> &'static str {
+        match self {
+            Self::Observe => "v1/observe",
+            Self::FetchInterface => "v1/fetch_interface",
+            Self::CallOperation => "v1/call_operation",
+            Self::Batch => "v1/batch",
+        }
+    }
+}
+
+/// A canonical absolute hierarchical base URL whose path always ends in `/`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Endpoint(Url);
+
+impl Endpoint {
+    /// Parses and canonicalizes an endpoint.
+    ///
+    /// The input must be an absolute hierarchical URL with a host and without a
+    /// query or fragment. Its path is an endpoint prefix, not a Worldspace path.
+    /// A trailing slash is appended when absent so RFC 3986 relative-reference
+    /// resolution preserves the final prefix segment. The supplied scheme is
+    /// preserved; scheme and transport security are deployment concerns.
+    pub fn parse(input: &str) -> Result<Self, EndpointError> {
+        let mut url = Url::parse(input).map_err(EndpointError::InvalidUrl)?;
+        if url.cannot_be_a_base() || url.host_str().is_none() {
+            return Err(EndpointError::NotAbsoluteBase);
+        }
+        if url.query().is_some() {
+            return Err(EndpointError::HasQuery);
+        }
+        if url.fragment().is_some() {
+            return Err(EndpointError::HasFragment);
+        }
+        if !url.path().ends_with('/') {
+            let path = format!("{}/", url.path());
+            url.set_path(&path);
+        }
+        Ok(Self(url))
+    }
+
+    /// Returns the canonical base URL.
+    #[must_use]
+    pub fn as_url(&self) -> &Url {
+        &self.0
+    }
+
+    /// Resolves one fixed v1 route below this endpoint prefix.
+    #[must_use]
+    pub fn route(&self, route: Route) -> Url {
+        self.0
+            .join(route.relative_reference())
+            .expect("fixed relative WIP routes are valid URL references")
+    }
+
+    /// Recognizes an exact standard route below this endpoint.
+    ///
+    /// Query strings, fragments, additional path segments, and Worldspace paths
+    /// are not route components and therefore never match.
+    #[must_use]
+    pub fn recognize(&self, candidate: &Url) -> Option<Route> {
+        const ROUTES: [Route; 4] = [
+            Route::Observe,
+            Route::FetchInterface,
+            Route::CallOperation,
+            Route::Batch,
+        ];
+        if candidate.query().is_some() || candidate.fragment().is_some() {
+            return None;
+        }
+        ROUTES
+            .into_iter()
+            .find(|route| self.route(*route) == *candidate)
+    }
+}
+
+impl Display for Endpoint {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        self.0.fmt(formatter)
+    }
+}
+
+impl TryFrom<&str> for Endpoint {
+    type Error = EndpointError;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::parse(value)
+    }
+}
+
+/// Why an endpoint is not a valid standard WIP over HTTP base.
+#[derive(Debug)]
+pub enum EndpointError {
+    /// URL parsing failed.
+    InvalidUrl(url::ParseError),
+    /// The URL is not a hierarchical absolute URL with an authority.
+    NotAbsoluteBase,
+    /// A query component was supplied.
+    HasQuery,
+    /// A fragment component was supplied.
+    HasFragment,
+}
+
+impl Display for EndpointError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidUrl(error) => write!(formatter, "invalid endpoint URL: {error}"),
+            Self::NotAbsoluteBase => {
+                formatter.write_str("WIP endpoint must be an absolute base URL")
+            }
+            Self::HasQuery => formatter.write_str("WIP endpoint must not contain a query"),
+            Self::HasFragment => formatter.write_str("WIP endpoint must not contain a fragment"),
+        }
+    }
+}
+
+impl Error for EndpointError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidUrl(error) => Some(error),
+            _ => None,
+        }
+    }
+}

crates/wip-http/src/error.rs

@@ -0,0 +1,255 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+/// Caller-selected hard limits applied before or while decoding JSON.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Limits {
+    /// Largest accepted request body in bytes.
+    pub(crate) max_request_bytes: usize,
+    /// Largest accepted response body in bytes.
+    pub(crate) max_response_bytes: usize,
+    /// Largest accepted JSON container nesting depth.
+    pub(crate) max_nesting: usize,
+    /// Largest accepted number of batch items.
+    pub(crate) max_batch_items: usize,
+}
+
+impl Limits {
+    /// Creates a nonzero limit set.
+    pub fn new(
+        max_request_bytes: usize,
+        max_response_bytes: usize,
+        max_nesting: usize,
+        max_batch_items: usize,
+    ) -> Result<Self, LimitConfigurationError> {
+        if max_request_bytes == 0 {
+            return Err(LimitConfigurationError::ZeroRequestBytes);
+        }
+        if max_response_bytes == 0 {
+            return Err(LimitConfigurationError::ZeroResponseBytes);
+        }
+        if max_nesting == 0 {
+            return Err(LimitConfigurationError::ZeroNesting);
+        }
+        if max_batch_items == 0 {
+            return Err(LimitConfigurationError::ZeroBatchItems);
+        }
+        Ok(Self {
+            max_request_bytes,
+            max_response_bytes,
+            max_nesting,
+            max_batch_items,
+        })
+    }
+
+    /// Returns the request body byte limit.
+    #[must_use]
+    pub const fn max_request_bytes(self) -> usize {
+        self.max_request_bytes
+    }
+
+    /// Returns the response body byte limit.
+    #[must_use]
+    pub const fn max_response_bytes(self) -> usize {
+        self.max_response_bytes
+    }
+
+    /// Returns the JSON container nesting limit.
+    #[must_use]
+    pub const fn max_nesting(self) -> usize {
+        self.max_nesting
+    }
+
+    /// Returns the batch item count limit.
+    #[must_use]
+    pub const fn max_batch_items(self) -> usize {
+        self.max_batch_items
+    }
+}
+
+/// Why a [`Limits`] configuration is not bounded.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LimitConfigurationError {
+    /// Request-byte limit was zero.
+    ZeroRequestBytes,
+    /// Response-byte limit was zero.
+    ZeroResponseBytes,
+    /// Nesting limit was zero.
+    ZeroNesting,
+    /// Batch-item limit was zero.
+    ZeroBatchItems,
+}
+
+impl Display for LimitConfigurationError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        formatter.write_str(match self {
+            Self::ZeroRequestBytes => "request byte limit must be nonzero",
+            Self::ZeroResponseBytes => "response byte limit must be nonzero",
+            Self::ZeroNesting => "nesting limit must be nonzero",
+            Self::ZeroBatchItems => "batch item limit must be nonzero",
+        })
+    }
+}
+
+impl Error for LimitConfigurationError {}
+
+/// Whether a body is being decoded as a request or response.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BodyKind {
+    /// An inbound server request.
+    Request,
+    /// An inbound client response.
+    Response,
+}
+
+/// The class of a resource limit exceeded by a wire representation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResourceLimitKind {
+    /// A request or response representation exceeded its byte-size limit.
+    RepresentationBytes,
+    /// A logical limit such as nesting depth, batch count, or collection size was exceeded.
+    Logical,
+}
+
+/// A malformed or locally disallowed wire representation.
+#[derive(Debug)]
+pub enum CodecError {
+    /// The body exceeds its configured byte limit.
+    BodyTooLarge {
+        /// Actual body size.
+        actual: usize,
+        /// Configured maximum.
+        maximum: usize,
+    },
+    /// JSON syntax is invalid.
+    InvalidJson(serde_json::Error),
+    /// A JSON container exceeds the configured nesting depth.
+    NestingTooDeep {
+        /// Configured maximum.
+        maximum: usize,
+    },
+    /// A required field is absent.
+    MissingField {
+        /// Field name.
+        field: String,
+    },
+    /// An undeclared field is present.
+    UnknownField {
+        /// Field name.
+        field: String,
+    },
+    /// A field has an invalid JSON type or semantic representation.
+    InvalidField {
+        /// Field name or value location.
+        field: String,
+        /// Stable human-readable reason.
+        reason: String,
+    },
+    /// An optional field was represented by JSON null rather than omission.
+    NullOptionalField {
+        /// Field name.
+        field: String,
+    },
+    /// Base64 is not canonical RFC 4648 Section 4 encoding.
+    InvalidBase64 {
+        /// Field name or value location.
+        field: String,
+    },
+    /// Logical protocol validation rejected the decoded representation.
+    ProtocolValidation(wip_protocol::ValidationError),
+    /// The batch exceeds its configured item count.
+    TooManyBatchItems {
+        /// Actual item count.
+        actual: usize,
+        /// Configured maximum.
+        maximum: usize,
+    },
+    /// Batch item identifiers are not unique.
+    DuplicateBatchId {
+        /// Repeated identifier.
+        id: String,
+    },
+    /// A response contains a batch identifier that was not requested.
+    UnexpectedBatchId {
+        /// Unexpected identifier.
+        id: String,
+    },
+    /// A response omitted a requested batch identifier.
+    MissingBatchId {
+        /// Missing identifier.
+        id: String,
+    },
+    /// A batch item result does not match its requested interaction.
+    BatchInteractionMismatch {
+        /// Item identifier.
+        id: String,
+    },
+}
+
+impl CodecError {
+    /// Classifies this failure when it represents a canonical resource limit.
+    #[must_use]
+    pub const fn resource_limit_kind(&self) -> Option<ResourceLimitKind> {
+        match self {
+            Self::BodyTooLarge { .. } => Some(ResourceLimitKind::RepresentationBytes),
+            Self::NestingTooDeep { .. } | Self::TooManyBatchItems { .. } => {
+                Some(ResourceLimitKind::Logical)
+            }
+            _ => None,
+        }
+    }
+}
+
+impl Display for CodecError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::BodyTooLarge { actual, maximum } => {
+                write!(formatter, "body has {actual} bytes; maximum is {maximum}")
+            }
+            Self::InvalidJson(error) => write!(formatter, "invalid JSON: {error}"),
+            Self::NestingTooDeep { maximum } => {
+                write!(formatter, "JSON nesting exceeds maximum {maximum}")
+            }
+            Self::MissingField { field } => write!(formatter, "missing field `{field}`"),
+            Self::UnknownField { field } => write!(formatter, "unknown field `{field}`"),
+            Self::InvalidField { field, reason } => {
+                write!(formatter, "invalid field `{field}`: {reason}")
+            }
+            Self::NullOptionalField { field } => {
+                write!(
+                    formatter,
+                    "optional field `{field}` must be omitted instead of null"
+                )
+            }
+            Self::InvalidBase64 { field } => {
+                write!(formatter, "field `{field}` is not canonical base64")
+            }
+            Self::ProtocolValidation(error) => error.fmt(formatter),
+            Self::TooManyBatchItems { actual, maximum } => {
+                write!(formatter, "batch has {actual} items; maximum is {maximum}")
+            }
+            Self::DuplicateBatchId { id } => write!(formatter, "duplicate batch id `{id}`"),
+            Self::UnexpectedBatchId { id } => write!(formatter, "unexpected batch id `{id}`"),
+            Self::MissingBatchId { id } => write!(formatter, "missing batch id `{id}`"),
+            Self::BatchInteractionMismatch { id } => {
+                write!(formatter, "batch result does not match request `{id}`")
+            }
+        }
+    }
+}
+
+impl Error for CodecError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidJson(error) => Some(error),
+            Self::ProtocolValidation(error) => Some(error),
+            _ => None,
+        }
+    }
+}
+
+impl From<wip_protocol::ValidationError> for CodecError {
+    fn from(value: wip_protocol::ValidationError) -> Self {
+        Self::ProtocolValidation(value)
+    }
+}

crates/wip-http/src/lib.rs

@@ -0,0 +1,68 @@
+//! Framework-independent standard WIP over HTTP v1 binding.
+//!
+//! This crate owns endpoint and route derivation, UTF-8 JSON encoding, canonical
+//! success and error response handling, HTTP status mapping, descriptor-guided
+//! operation-value conversion, and retrieval batching. It deliberately performs
+//! no I/O and depends on no server framework, TLS implementation, filesystem
+//! projection, client cache, or presentation layer. URL schemes, TLS,
+//! certificates, authentication mechanisms, proxies, and caches are selected by
+//! the HTTP implementation and deployment rather than by WIP conformance.
+//!
+//! Logical values remain owned by [`wip_protocol`]. Validators and `Bytes` are
+//! encoded in JSON bodies using canonical RFC 4648 Section 4 base64; this crate
+//! does not infer WIP validator semantics from `ETag` or `If-Match`.
+//!
+//! ```
+//! use wip_http::{Endpoint, Limits, encode_observe_request};
+//! use wip_protocol::ObserveRequest;
+//!
+//! let endpoint = Endpoint::parse("http://example.test/api/wip")?;
+//! let limits = Limits::new(64 * 1024, 1024 * 1024, 64, 100)?;
+//! let request = encode_observe_request(
+//!     &endpoint,
+//!     &ObserveRequest { path: "/items/123".into(), depth: 0 },
+//!     limits,
+//! )?;
+//! assert_eq!(request.uri(), "http://example.test/api/wip/v1/observe");
+//! assert_eq!(request.method(), http::Method::POST);
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
+
+#![deny(missing_docs)]
+
+mod batch;
+mod codec;
+mod endpoint;
+mod error;
+mod json;
+mod response;
+
+pub use batch::{
+    BatchMethod, BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse,
+    BatchResponseItem, BatchSuccess, decode_batch_request, decode_batch_response,
+    encode_batch_error_response, encode_batch_request, encode_batch_resource_limit_error_response,
+    encode_batch_response,
+};
+pub use codec::{
+    CallOperationMetadata, EncodeHttpError, RequestMetadataError, decode_call_operation_metadata,
+    decode_call_operation_request, decode_call_operation_response, decode_fetch_interface_request,
+    decode_fetch_interface_response, decode_observe_request, decode_observe_response,
+    encode_call_operation_request, encode_call_operation_response, encode_fetch_interface_request,
+    encode_fetch_interface_response, encode_observe_request, encode_observe_response,
+    encode_protocol_error_response, encode_resource_limit_error_response, is_json_content_type,
+    validate_http_request,
+};
+pub use endpoint::{Endpoint, EndpointError, JSON_CONTENT_TYPE, Route};
+pub use error::{BodyKind, CodecError, LimitConfigurationError, Limits, ResourceLimitKind};
+pub use response::{
+    ClientResponseError, DecodedResponse, InvalidResponseKind, StatusMismatch,
+    TransportBindingFailure, TransportFailureKind, error_code_name, status_for_error,
+    status_for_resource_limit,
+};
+
+/// Framework-neutral HTTP types used by this binding's public API.
+pub use http;
+/// URL type used by [`Endpoint`].
+pub use url;
+/// Transport-independent logical protocol model used by this binding.
+pub use wip_protocol;

crates/wip-http/src/response.rs

@@ -0,0 +1,365 @@
+use std::error::Error;
+use std::fmt::{self, Display, Formatter};
+
+use http::StatusCode;
+use serde_json::{Map, Value as Json};
+use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
+
+use crate::{BodyKind, CodecError, Limits, ResourceLimitKind, json};
+
+/// A successfully classified client response.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DecodedResponse<T> {
+    /// A successful direct response body.
+    Success(T),
+    /// A canonical Host protocol failure.
+    ProtocolFailure {
+        /// The authoritative protocol error decoded from the envelope.
+        error: ProtocolError,
+        /// A diagnostic when the HTTP status differs from the canonical mapping.
+        status_mismatch: Option<StatusMismatch>,
+    },
+}
+
+/// Diagnostic evidence that HTTP metadata disagrees with a valid error envelope.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct StatusMismatch {
+    /// Status received from the peer.
+    pub actual: StatusCode,
+    /// Canonical status for the envelope's protocol code.
+    pub expected: StatusCode,
+}
+
+/// Class of non-protocol HTTP failure returned without a valid WIP envelope.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TransportFailureKind {
+    /// HTTP 401, commonly emitted by authentication infrastructure.
+    AuthenticationRequired,
+    /// HTTP 403, commonly emitted by endpoint policy or infrastructure.
+    EndpointForbidden,
+    /// Another non-success HTTP response without a WIP error envelope.
+    HttpStatus,
+}
+
+/// A non-success HTTP response that is not a valid WIP protocol failure.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TransportBindingFailure {
+    /// HTTP status returned by the peer or intermediary.
+    pub status: StatusCode,
+    /// Coarse classification which does not invent a protocol error code.
+    pub kind: TransportFailureKind,
+}
+
+/// Why a response violates the WIP v1 response contract.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum InvalidResponseKind {
+    /// A 2xx response contained an error envelope.
+    ErrorEnvelopeOnSuccessStatus,
+    /// A non-2xx response contained a valid success body.
+    SuccessBodyOnErrorStatus,
+    /// A valid error envelope used a code forbidden for the interaction.
+    DisallowedProtocolCode,
+    /// A valid success body used a 2xx status other than canonical HTTP 200.
+    NonCanonicalSuccessStatus,
+    /// A 2xx body was malformed or semantically invalid.
+    InvalidSuccessBody,
+    /// A batch response did not correlate exactly with its request.
+    InvalidBatch,
+}
+
+/// A local failure while classifying or validating a peer response.
+#[derive(Debug)]
+pub enum ClientResponseError {
+    /// The HTTP exchange failed outside the protocol envelope.
+    TransportBinding(TransportBindingFailure),
+    /// The peer supplied a contradictory or invalid WIP response.
+    InvalidResponse {
+        /// Stable response-failure category.
+        kind: InvalidResponseKind,
+        /// Bounded diagnostic from local decoding.
+        detail: String,
+    },
+    /// The descriptor is structurally valid but uses an unsupported format.
+    UnsupportedDescriptorFormat {
+        /// Format identifier received from the Host.
+        format: String,
+    },
+}
+
+impl ClientResponseError {
+    pub(crate) fn invalid(kind: InvalidResponseKind, detail: impl Into<String>) -> Self {
+        Self::InvalidResponse {
+            kind,
+            detail: detail.into(),
+        }
+    }
+}
+
+impl Display for ClientResponseError {
+    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::TransportBinding(failure) => write!(
+                formatter,
+                "transport binding failure ({:?}, HTTP {})",
+                failure.kind, failure.status
+            ),
+            Self::InvalidResponse { kind, detail } => {
+                write!(formatter, "invalid WIP response ({kind:?}): {detail}")
+            }
+            Self::UnsupportedDescriptorFormat { format } => {
+                write!(
+                    formatter,
+                    "unsupported interface descriptor format `{format}`"
+                )
+            }
+        }
+    }
+}
+
+impl Error for ClientResponseError {}
+
+/// Returns the canonical HTTP status for a wire-level protocol error.
+///
+/// [`ProtocolErrorCode::ResourceLimitExceeded`] defaults to the logical-limit
+/// status. Use [`status_for_resource_limit`] when the concrete limit class is
+/// known.
+#[must_use]
+pub const fn status_for_error(code: ProtocolErrorCode) -> StatusCode {
+    match code {
+        ProtocolErrorCode::InvalidRequest => StatusCode::BAD_REQUEST,
+        ProtocolErrorCode::NotFound | ProtocolErrorCode::InterfaceNotFound => StatusCode::NOT_FOUND,
+        ProtocolErrorCode::InterfaceMismatch => StatusCode::CONFLICT,
+        ProtocolErrorCode::OperationNotFound => StatusCode::NOT_FOUND,
+        ProtocolErrorCode::InvalidArguments => StatusCode::UNPROCESSABLE_ENTITY,
+        ProtocolErrorCode::ValidatorRequired | ProtocolErrorCode::InterfaceValidatorRequired => {
+            StatusCode::PRECONDITION_REQUIRED
+        }
+        ProtocolErrorCode::ValidatorMismatch | ProtocolErrorCode::InterfaceValidatorMismatch => {
+            StatusCode::PRECONDITION_FAILED
+        }
+        ProtocolErrorCode::PermissionDenied => StatusCode::FORBIDDEN,
+        ProtocolErrorCode::ResourceLimitExceeded => StatusCode::UNPROCESSABLE_ENTITY,
+        ProtocolErrorCode::Internal | ProtocolErrorCode::OperationOutcomeUnknown => {
+            StatusCode::INTERNAL_SERVER_ERROR
+        }
+    }
+}
+
+/// Returns the canonical HTTP status for a concrete resource-limit class.
+#[must_use]
+pub const fn status_for_resource_limit(kind: ResourceLimitKind) -> StatusCode {
+    match kind {
+        ResourceLimitKind::RepresentationBytes => StatusCode::PAYLOAD_TOO_LARGE,
+        ResourceLimitKind::Logical => StatusCode::UNPROCESSABLE_ENTITY,
+    }
+}
+
+fn status_matches_error(status: StatusCode, code: ProtocolErrorCode) -> bool {
+    match code {
+        ProtocolErrorCode::ResourceLimitExceeded => {
+            status == StatusCode::PAYLOAD_TOO_LARGE || status == StatusCode::UNPROCESSABLE_ENTITY
+        }
+        _ => status == status_for_error(code),
+    }
+}
+
+/// Returns the stable snake-case wire spelling of a protocol code.
+#[must_use]
+pub const fn error_code_name(code: ProtocolErrorCode) -> &'static str {
+    match code {
+        ProtocolErrorCode::InvalidRequest => "invalid_request",
+        ProtocolErrorCode::NotFound => "not_found",
+        ProtocolErrorCode::InterfaceNotFound => "interface_not_found",
+        ProtocolErrorCode::InterfaceMismatch => "interface_mismatch",
+        ProtocolErrorCode::OperationNotFound => "operation_not_found",
+        ProtocolErrorCode::InvalidArguments => "invalid_arguments",
+        ProtocolErrorCode::ValidatorRequired => "validator_required",
+        ProtocolErrorCode::ValidatorMismatch => "validator_mismatch",
+        ProtocolErrorCode::InterfaceValidatorRequired => "interface_validator_required",
+        ProtocolErrorCode::InterfaceValidatorMismatch => "interface_validator_mismatch",
+        ProtocolErrorCode::PermissionDenied => "permission_denied",
+        ProtocolErrorCode::ResourceLimitExceeded => "resource_limit_exceeded",
+        ProtocolErrorCode::Internal => "internal",
+        ProtocolErrorCode::OperationOutcomeUnknown => "operation_outcome_unknown",
+    }
+}
+
+fn error_code_from_name(name: &str) -> Option<ProtocolErrorCode> {
+    Some(match name {
+        "invalid_request" => ProtocolErrorCode::InvalidRequest,
+        "not_found" => ProtocolErrorCode::NotFound,
+        "interface_not_found" => ProtocolErrorCode::InterfaceNotFound,
+        "interface_mismatch" => ProtocolErrorCode::InterfaceMismatch,
+        "operation_not_found" => ProtocolErrorCode::OperationNotFound,
+        "invalid_arguments" => ProtocolErrorCode::InvalidArguments,
+        "validator_required" => ProtocolErrorCode::ValidatorRequired,
+        "validator_mismatch" => ProtocolErrorCode::ValidatorMismatch,
+        "interface_validator_required" => ProtocolErrorCode::InterfaceValidatorRequired,
+        "interface_validator_mismatch" => ProtocolErrorCode::InterfaceValidatorMismatch,
+        "permission_denied" => ProtocolErrorCode::PermissionDenied,
+        "resource_limit_exceeded" => ProtocolErrorCode::ResourceLimitExceeded,
+        "internal" => ProtocolErrorCode::Internal,
+        "operation_outcome_unknown" => ProtocolErrorCode::OperationOutcomeUnknown,
+        _ => return None,
+    })
+}
+
+pub(crate) fn error_to_json(error: &ProtocolError) -> Json {
+    serde_json::json!({
+        "error": {
+            "code": error_code_name(error.code),
+            "message": error.message,
+        }
+    })
+}
+
+pub(crate) fn item_error_to_json(error: &ProtocolError) -> Json {
+    serde_json::json!({
+        "code": error_code_name(error.code),
+        "message": error.message,
+    })
+}
+
+pub(crate) fn item_error_from_json(value: &Json) -> Result<ProtocolError, CodecError> {
+    let fields = value
+        .as_object()
+        .ok_or_else(|| invalid_field("error", "expected object"))?;
+    exact(fields, &["code", "message"], "error")?;
+    let code_name = required_string(fields, "code")?;
+    let code = error_code_from_name(code_name)
+        .ok_or_else(|| invalid_field("error.code", "unknown protocol error code"))?;
+    let message = required_string(fields, "message")?.to_owned();
+    Ok(ProtocolError { code, message })
+}
+
+fn envelope_error_from_json(value: &Json) -> Result<Option<ProtocolError>, CodecError> {
+    let Some(fields) = value.as_object() else {
+        return Ok(None);
+    };
+    if fields.len() != 1 || !fields.contains_key("error") {
+        return Ok(None);
+    }
+    item_error_from_json(&fields["error"]).map(Some)
+}
+
+fn exact(fields: &Map<String, Json>, allowed: &[&str], parent: &str) -> Result<(), CodecError> {
+    for name in fields.keys() {
+        if !allowed.contains(&name.as_str()) {
+            return Err(CodecError::UnknownField {
+                field: format!("{parent}.{name}"),
+            });
+        }
+    }
+    for name in allowed {
+        if !fields.contains_key(*name) {
+            return Err(CodecError::MissingField {
+                field: format!("{parent}.{name}"),
+            });
+        }
+    }
+    Ok(())
+}
+
+fn required_string<'a>(fields: &'a Map<String, Json>, name: &str) -> Result<&'a str, CodecError> {
+    fields
+        .get(name)
+        .and_then(Json::as_str)
+        .ok_or_else(|| invalid_field(&format!("error.{name}"), "expected string"))
+}
+
+fn invalid_field(field: &str, reason: &str) -> CodecError {
+    CodecError::InvalidField {
+        field: field.into(),
+        reason: reason.into(),
+    }
+}
+
+pub(crate) fn decode<T>(
+    status: StatusCode,
+    body: &[u8],
+    interaction: ProtocolInteraction,
+    limits: Limits,
+    success: impl FnOnce(&Json) -> Result<T, CodecError>,
+) -> Result<DecodedResponse<T>, ClientResponseError> {
+    let value = match json::parse(body, BodyKind::Response, limits) {
+        Ok(value) => value,
+        Err(_) if !status.is_success() => {
+            return Err(transport_failure(status));
+        }
+        Err(error) => {
+            return Err(ClientResponseError::invalid(
+                InvalidResponseKind::InvalidSuccessBody,
+                error.to_string(),
+            ));
+        }
+    };
+
+    match envelope_error_from_json(&value) {
+        Ok(Some(error)) => {
+            if status.is_success() {
+                return Err(ClientResponseError::invalid(
+                    InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
+                    "protocol error envelope carried by a success status",
+                ));
+            }
+            if !error.code.is_allowed_for(interaction) {
+                return Err(ClientResponseError::invalid(
+                    InvalidResponseKind::DisallowedProtocolCode,
+                    format!(
+                        "code `{}` is not allowed for {interaction:?}",
+                        error_code_name(error.code)
+                    ),
+                ));
+            }
+            let expected = status_for_error(error.code);
+            let status_mismatch =
+                (!status_matches_error(status, error.code)).then_some(StatusMismatch {
+                    actual: status,
+                    expected,
+                });
+            Ok(DecodedResponse::ProtocolFailure {
+                error,
+                status_mismatch,
+            })
+        }
+        Err(_) if !status.is_success() => Err(transport_failure(status)),
+        Err(error) => Err(ClientResponseError::invalid(
+            InvalidResponseKind::InvalidSuccessBody,
+            error.to_string(),
+        )),
+        Ok(None) if status == StatusCode::OK => success(&value)
+            .map(DecodedResponse::Success)
+            .map_err(|error| {
+                ClientResponseError::invalid(
+                    InvalidResponseKind::InvalidSuccessBody,
+                    error.to_string(),
+                )
+            }),
+        Ok(None) if status.is_success() => match success(&value) {
+            Ok(_) => Err(ClientResponseError::invalid(
+                InvalidResponseKind::NonCanonicalSuccessStatus,
+                format!("success body carried by non-canonical HTTP {status}"),
+            )),
+            Err(error) => Err(ClientResponseError::invalid(
+                InvalidResponseKind::InvalidSuccessBody,
+                error.to_string(),
+            )),
+        },
+        Ok(None) => match success(&value) {
+            Ok(_) => Err(ClientResponseError::invalid(
+                InvalidResponseKind::SuccessBodyOnErrorStatus,
+                "valid success body carried by a non-success status",
+            )),
+            Err(_) => Err(transport_failure(status)),
+        },
+    }
+}
+
+pub(crate) fn transport_failure(status: StatusCode) -> ClientResponseError {
+    let kind = match status {
+        StatusCode::UNAUTHORIZED => TransportFailureKind::AuthenticationRequired,
+        StatusCode::FORBIDDEN => TransportFailureKind::EndpointForbidden,
+        _ => TransportFailureKind::HttpStatus,
+    };
+    ClientResponseError::TransportBinding(TransportBindingFailure { status, kind })
+}

crates/wip-http/tests/batch.rs

@@ -0,0 +1,345 @@
+use wip_http::http::StatusCode;
+use wip_http::wip_protocol::{
+    FetchInterfaceRequest, FetchInterfaceResponse, INTERFACE_FORMAT_V1, InterfaceDescriptor,
+    Object, ObjectObservation, ObserveRequest, ProtocolError, ProtocolErrorCode,
+};
+use wip_http::{
+    BatchMethod, BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse,
+    BatchResponseItem, BatchSuccess, ClientResponseError, DecodedResponse, Endpoint,
+    InvalidResponseKind, Limits, ResourceLimitKind, decode_batch_request, decode_batch_response,
+    encode_batch_error_response, encode_batch_request, encode_batch_resource_limit_error_response,
+    encode_batch_response,
+};
+
+fn limits() -> Limits {
+    Limits::new(100_000, 100_000, 64, 4).unwrap()
+}
+
+fn observed_item(validator: Option<Vec<u8>>) -> ObjectObservation {
+    ObjectObservation {
+        object: Object {
+            name: "item".into(),
+            description: None,
+            interfaces: vec![],
+            r#ref: None,
+            validator,
+        },
+        children: None,
+    }
+}
+
+fn request() -> BatchRequest {
+    BatchRequest {
+        requests: vec![
+            BatchRequestItem {
+                id: "object".into(),
+                request: BatchRequestKind::Observe(ObserveRequest {
+                    path: "/item".into(),
+                    depth: 0,
+                }),
+            },
+            BatchRequestItem {
+                id: "interface".into(),
+                request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
+                    interface: "interface-v1".into(),
+                }),
+            },
+        ],
+    }
+}
+
+#[test]
+fn batch_round_trips_by_unique_id_with_item_failures_and_validators() {
+    let request = request();
+    let endpoint = Endpoint::parse("https://example.test/wip").unwrap();
+    let encoded_request = encode_batch_request(&endpoint, &request, limits()).unwrap();
+    assert_eq!(encoded_request.uri().path(), "/wip/v1/batch");
+    assert_eq!(encoded_request.headers()["accept"], "application/json");
+    assert_eq!(
+        decode_batch_request(encoded_request.body(), limits()).unwrap(),
+        request
+    );
+
+    let response = BatchResponse {
+        responses: vec![
+            BatchResponseItem {
+                id: "interface".into(),
+                outcome: Err(ProtocolError {
+                    code: ProtocolErrorCode::InterfaceNotFound,
+                    message: "gone".into(),
+                }),
+            },
+            BatchResponseItem {
+                id: "object".into(),
+                outcome: Ok(BatchSuccess::Observe(observed_item(Some(vec![
+                    0, 1, 2, 255,
+                ])))),
+            },
+        ],
+    };
+    let encoded = encode_batch_response(&request, &response, limits()).unwrap();
+    assert_eq!(encoded.status(), StatusCode::OK);
+    assert!(
+        std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("AAEC/w==")
+    );
+    assert_eq!(
+        decode_batch_response(&request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(response)
+    );
+}
+
+#[test]
+fn batch_interface_validator_round_trips_in_item_body() {
+    let request = BatchRequest {
+        requests: vec![BatchRequestItem {
+            id: "interface".into(),
+            request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
+                interface: "interface-v1".into(),
+            }),
+        }],
+    };
+    let response = BatchResponse {
+        responses: vec![BatchResponseItem {
+            id: "interface".into(),
+            outcome: Ok(BatchSuccess::FetchInterface(FetchInterfaceResponse {
+                interface: "interface-v1".into(),
+                descriptor: InterfaceDescriptor {
+                    format: INTERFACE_FORMAT_V1.into(),
+                    documentation: None,
+                    types: vec![],
+                    operations: vec![],
+                },
+                validator: Some(vec![255, 254, 253]),
+            })),
+        }],
+    };
+    let encoded = encode_batch_response(&request, &response, limits()).unwrap();
+    assert!(
+        std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("//79")
+    );
+    assert_eq!(
+        decode_batch_response(&request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(response)
+    );
+}
+
+#[test]
+fn malformed_known_method_arguments_are_item_local() {
+    let body = br#"{
+        "requests": [
+            {"id":"valid","method":"observe","arguments":{"path":"/item","depth":0}},
+            {"id":"invalid","method":"observe","arguments":{"path":"/","depth":"deep"}}
+        ]
+    }"#;
+    let decoded = decode_batch_request(body, limits()).unwrap();
+    assert!(matches!(
+        decoded.requests[0].request,
+        BatchRequestKind::Observe(_)
+    ));
+    let invalid = match &decoded.requests[1].request {
+        BatchRequestKind::Invalid { method, error } => {
+            assert_eq!(*method, BatchMethod::Observe);
+            assert_eq!(error.code, ProtocolErrorCode::InvalidRequest);
+            error.clone()
+        }
+        other => panic!("expected item-local invalid request, got {other:?}"),
+    };
+
+    let response = BatchResponse {
+        responses: vec![
+            BatchResponseItem {
+                id: "valid".into(),
+                outcome: Ok(BatchSuccess::Observe(observed_item(None))),
+            },
+            BatchResponseItem {
+                id: "invalid".into(),
+                outcome: Err(invalid),
+            },
+        ],
+    };
+    let encoded = encode_batch_response(&decoded, &response, limits()).unwrap();
+    assert_eq!(encoded.status(), StatusCode::OK);
+    assert_eq!(
+        decode_batch_response(&decoded, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(response)
+    );
+}
+
+#[test]
+fn invalid_batch_envelopes_are_rejected_at_top_level() {
+    assert!(decode_batch_request(br#"{}"#, limits()).is_err());
+
+    let malformed_item = br#"{
+        "requests": [
+            {"id":"item","method":"observe","arguments":{"path":"/","depth":0},"extra":true}
+        ]
+    }"#;
+    assert!(decode_batch_request(malformed_item, limits()).is_err());
+
+    let duplicate = br#"{
+        "requests": [
+            {"id":"same","method":"observe","arguments":{"path":"/a","depth":0}},
+            {"id":"same","method":"observe","arguments":{"path":"/b","depth":0}}
+        ]
+    }"#;
+    assert!(decode_batch_request(duplicate, limits()).is_err());
+
+    let operation = br#"{
+        "requests": [
+            {"id":"call","method":"call_operation","arguments":{}}
+        ]
+    }"#;
+    assert!(decode_batch_request(operation, limits()).is_err());
+
+    let too_many = Limits::new(100_000, 100_000, 64, 1).unwrap();
+    assert!(decode_batch_request(duplicate, too_many).is_err());
+}
+
+#[test]
+fn batch_resource_limits_use_413_or_422_and_never_429() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::ResourceLimitExceeded,
+        message: "bounded".into(),
+    };
+    for (kind, status) in [
+        (
+            ResourceLimitKind::RepresentationBytes,
+            StatusCode::PAYLOAD_TOO_LARGE,
+        ),
+        (ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
+    ] {
+        let encoded = encode_batch_resource_limit_error_response(&error, kind, limits()).unwrap();
+        assert_eq!(encoded.status(), status);
+        assert_ne!(encoded.status(), StatusCode::TOO_MANY_REQUESTS);
+        assert_eq!(
+            decode_batch_response(&request(), &encoded, limits()).unwrap(),
+            DecodedResponse::ProtocolFailure {
+                error: error.clone(),
+                status_mismatch: None,
+            }
+        );
+    }
+}
+
+#[test]
+fn batch_success_body_requires_exactly_http_200() {
+    let request = request();
+    let response = BatchResponse {
+        responses: vec![
+            BatchResponseItem {
+                id: "object".into(),
+                outcome: Ok(BatchSuccess::Observe(observed_item(None))),
+            },
+            BatchResponseItem {
+                id: "interface".into(),
+                outcome: Err(ProtocolError {
+                    code: ProtocolErrorCode::InterfaceNotFound,
+                    message: "gone".into(),
+                }),
+            },
+        ],
+    };
+    let encoded = encode_batch_response(&request, &response, limits()).unwrap();
+    for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
+        let mut noncanonical = encoded.clone();
+        *noncanonical.status_mut() = status;
+        assert!(matches!(
+            decode_batch_response(&request, &noncanonical, limits()).unwrap_err(),
+            ClientResponseError::InvalidResponse { .. }
+        ));
+    }
+}
+
+#[test]
+fn top_level_batch_errors_use_the_batch_allowed_code_set() {
+    let invalid = ProtocolError {
+        code: ProtocolErrorCode::InvalidRequest,
+        message: "bad envelope".into(),
+    };
+    let encoded = encode_batch_error_response(&invalid, limits()).unwrap();
+    assert_eq!(
+        decode_batch_response(&request(), &encoded, limits()).unwrap(),
+        DecodedResponse::ProtocolFailure {
+            error: invalid,
+            status_mismatch: None,
+        }
+    );
+
+    let not_found = wip_http::http::Response::builder()
+        .status(StatusCode::NOT_FOUND)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(br#"{"error":{"code":"not_found","message":"not a batch failure"}}"#.to_vec())
+        .unwrap();
+    assert!(matches!(
+        decode_batch_response(&request(), &not_found, limits()).unwrap_err(),
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidBatch,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn unsupported_batch_descriptor_waits_for_envelope_correlation() {
+    let duplicate = wip_http::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(
+            br#"{"responses":[{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future":true}}},{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"}}}]}"#
+                .to_vec(),
+        )
+        .unwrap();
+    assert!(matches!(
+        decode_batch_response(&request(), &duplicate, limits()).unwrap_err(),
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidBatch,
+            ..
+        }
+    ));
+
+    let missing = wip_http::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(
+            br#"{"responses":[{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"}}}]}"#
+                .to_vec(),
+        )
+        .unwrap();
+    assert!(matches!(
+        decode_batch_response(&request(), &missing, limits()).unwrap_err(),
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidBatch,
+            ..
+        }
+    ));
+
+    let request = BatchRequest {
+        requests: vec![BatchRequestItem {
+            id: "interface".into(),
+            request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
+                interface: "interface-v1".into(),
+            }),
+        }],
+    };
+    assert!(matches!(
+        decode_batch_response(&request, &missing, limits()).unwrap_err(),
+        ClientResponseError::UnsupportedDescriptorFormat { format }
+            if format == "wip-interface/2"
+    ));
+}
+
+#[test]
+fn batch_response_must_have_exactly_the_requested_ids() {
+    let request = request();
+    let missing = BatchResponse {
+        responses: vec![BatchResponseItem {
+            id: "object".into(),
+            outcome: Ok(BatchSuccess::Observe(observed_item(None))),
+        }],
+    };
+    assert!(encode_batch_response(&request, &missing, limits()).is_err());
+}

crates/wip-http/tests/codecs.rs

@@ -0,0 +1,526 @@
+use std::collections::BTreeMap;
+
+use wip_http::http::StatusCode;
+use wip_http::wip_protocol::{
+    CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
+    FetchInterfaceResponse, FieldDeclaration, INTERFACE_FORMAT_V1, InterfaceDescriptor,
+    InterfaceTarget, MAX_SAFE_INTEGER, Object, ObjectObservation, ObserveRequest,
+    OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target, TypeDeclaration,
+    TypeExpr, UnionCase, Value,
+};
+use wip_http::{
+    ClientResponseError, CodecError, DecodedResponse, Endpoint, InvalidResponseKind, Limits,
+    ResourceLimitKind, decode_call_operation_metadata, decode_call_operation_request,
+    decode_call_operation_response, decode_fetch_interface_request,
+    decode_fetch_interface_response, decode_observe_request, decode_observe_response,
+    encode_call_operation_request, encode_call_operation_response, encode_fetch_interface_request,
+    encode_fetch_interface_response, encode_observe_request, encode_observe_response,
+};
+
+fn limits() -> Limits {
+    Limits::new(1_000_000, 1_000_000, 100, 100).unwrap()
+}
+
+fn endpoint() -> Endpoint {
+    Endpoint::parse("https://example.test/wip").unwrap()
+}
+
+fn object(name: &str, validator: &[u8]) -> Object {
+    Object {
+        name: name.into(),
+        description: Some("description".into()),
+        interfaces: vec!["interface-v1".into()],
+        r#ref: Some(format!("object:{name}")),
+        validator: Some(validator.to_vec()),
+    }
+}
+
+fn descriptor() -> InterfaceDescriptor {
+    InterfaceDescriptor {
+        format: INTERFACE_FORMAT_V1.into(),
+        documentation: Some(Documentation {
+            summary: "Codec fixture".into(),
+            details: None,
+        }),
+        types: vec![TypeDeclaration {
+            name: "Pair".into(),
+            documentation: None,
+            definition: TypeExpr::Record {
+                fields: vec![
+                    FieldDeclaration {
+                        name: "required".into(),
+                        required: true,
+                        documentation: None,
+                        r#type: TypeExpr::String,
+                    },
+                    FieldDeclaration {
+                        name: "optional".into(),
+                        required: false,
+                        documentation: None,
+                        r#type: TypeExpr::String,
+                    },
+                    FieldDeclaration {
+                        name: "optional_json".into(),
+                        required: false,
+                        documentation: None,
+                        r#type: TypeExpr::Json,
+                    },
+                ],
+            },
+        }],
+        operations: vec![OperationDeclaration {
+            name: "everything".into(),
+            documentation: None,
+            parameters: vec![
+                parameter("unit", TypeExpr::Unit),
+                parameter("boolean", TypeExpr::Boolean),
+                parameter("integer", TypeExpr::Integer),
+                parameter("number", TypeExpr::Number),
+                parameter("string", TypeExpr::String),
+                parameter("bytes", TypeExpr::Bytes),
+                parameter("entry", TypeExpr::Entry),
+                parameter(
+                    "list",
+                    TypeExpr::List {
+                        items: Box::new(TypeExpr::Integer),
+                    },
+                ),
+                parameter(
+                    "record",
+                    TypeExpr::Named {
+                        name: "Pair".into(),
+                    },
+                ),
+                parameter(
+                    "enum",
+                    TypeExpr::Enum {
+                        cases: vec![EnumCase {
+                            name: "ready".into(),
+                            documentation: None,
+                        }],
+                    },
+                ),
+                parameter(
+                    "union",
+                    TypeExpr::Union {
+                        cases: vec![
+                            UnionCase {
+                                name: "empty".into(),
+                                documentation: None,
+                                payload: None,
+                            },
+                            UnionCase {
+                                name: "found".into(),
+                                documentation: None,
+                                payload: Some(TypeExpr::Entry),
+                            },
+                        ],
+                    },
+                ),
+                parameter("json", TypeExpr::Json),
+            ],
+            returns: ReturnDeclaration {
+                documentation: None,
+                r#type: TypeExpr::Bytes,
+            },
+        }],
+    }
+}
+
+fn parameter(name: &str, r#type: TypeExpr) -> ParameterDeclaration {
+    ParameterDeclaration {
+        name: name.into(),
+        required: true,
+        documentation: None,
+        r#type,
+    }
+}
+
+fn record(fields: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
+    Value::Record(
+        fields
+            .into_iter()
+            .map(|(name, value)| (name.into(), value))
+            .collect(),
+    )
+}
+
+fn call_request() -> CallOperationRequest {
+    CallOperationRequest {
+        target: Target {
+            path: "/items/123".into(),
+            validator: Some(vec![0, 1, 2, 255]),
+        },
+        interface: InterfaceTarget {
+            reference: "interface-v1".into(),
+            validator: Some(vec![9, 8, 7]),
+        },
+        operation: "everything".into(),
+        arguments: BTreeMap::from([
+            ("unit".into(), Value::Unit),
+            ("boolean".into(), Value::Boolean(true)),
+            ("integer".into(), Value::Integer(MAX_SAFE_INTEGER)),
+            ("number".into(), Value::Number(1.5)),
+            ("string".into(), Value::String("text".into())),
+            ("bytes".into(), Value::Bytes(vec![0, 1, 2, 255])),
+            ("entry".into(), Value::String("/items/123".into())),
+            (
+                "list".into(),
+                Value::List(vec![Value::Integer(1), Value::Integer(2)]),
+            ),
+            (
+                "record".into(),
+                record([("required", Value::String("present".into()))]),
+            ),
+            ("enum".into(), Value::String("ready".into())),
+            (
+                "union".into(),
+                record([
+                    ("$case", Value::String("found".into())),
+                    ("value", Value::String("/items/123".into())),
+                ]),
+            ),
+            (
+                "json".into(),
+                record([
+                    ("null", Value::Unit),
+                    ("number", Value::Integer(2)),
+                    ("path_like", Value::String("/not-an-entry".into())),
+                ]),
+            ),
+        ]),
+    }
+}
+
+#[test]
+fn every_single_interaction_request_accepts_json() {
+    let observe = encode_observe_request(
+        &endpoint(),
+        &ObserveRequest {
+            path: "/".into(),
+            depth: 0,
+        },
+        limits(),
+    )
+    .unwrap();
+    let fetch_interface = encode_fetch_interface_request(
+        &endpoint(),
+        &FetchInterfaceRequest {
+            interface: "interface-v1".into(),
+        },
+        limits(),
+    )
+    .unwrap();
+    let call = encode_call_operation_request(&endpoint(), &call_request(), &descriptor(), limits())
+        .unwrap();
+
+    for request in [observe, fetch_interface, call] {
+        assert_eq!(request.headers()["accept"], "application/json");
+    }
+}
+
+#[test]
+fn depth_zero_observe_round_trips_direct_body_and_validator() {
+    let request = ObserveRequest {
+        path: "/items/123".into(),
+        depth: 0,
+    };
+    let encoded_request = encode_observe_request(&endpoint(), &request, limits()).unwrap();
+    assert_eq!(encoded_request.uri().path(), "/wip/v1/observe");
+    assert_eq!(
+        decode_observe_request(encoded_request.body(), limits()).unwrap(),
+        request
+    );
+
+    let expected = ObjectObservation {
+        object: object("123", &[0, 1, 2, 255]),
+        children: None,
+    };
+    let encoded = encode_observe_response(&request, &expected, limits()).unwrap();
+    assert_eq!(encoded.status(), StatusCode::OK);
+    assert!(
+        !std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("children")
+    );
+    assert_eq!(
+        decode_observe_response(&request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(expected)
+    );
+    assert!(encoded.headers().get("etag").is_none());
+}
+
+#[test]
+fn observe_and_interface_round_trip_nested_logical_models() {
+    let observe_request = ObserveRequest {
+        path: "/items".into(),
+        depth: 1,
+    };
+    let encoded_request = encode_observe_request(&endpoint(), &observe_request, limits()).unwrap();
+    assert_eq!(
+        decode_observe_request(encoded_request.body(), limits()).unwrap(),
+        observe_request
+    );
+    let observation = ObjectObservation {
+        object: object("items", b"root-validator"),
+        children: Some(vec![ObjectObservation {
+            object: object("123", b"child-validator"),
+            children: None,
+        }]),
+    };
+    let encoded = encode_observe_response(&observe_request, &observation, limits()).unwrap();
+    assert_eq!(
+        decode_observe_response(&observe_request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(observation)
+    );
+
+    let empty = ObjectObservation {
+        object: object("items", b"root-validator"),
+        children: Some(vec![]),
+    };
+    let encoded_empty = encode_observe_response(&observe_request, &empty, limits()).unwrap();
+    assert!(
+        std::str::from_utf8(encoded_empty.body())
+            .unwrap()
+            .contains("\"children\":[]")
+    );
+
+    let interface_request = FetchInterfaceRequest {
+        interface: "interface-v1".into(),
+    };
+    let encoded_request =
+        encode_fetch_interface_request(&endpoint(), &interface_request, limits()).unwrap();
+    assert_eq!(
+        decode_fetch_interface_request(encoded_request.body(), limits()).unwrap(),
+        interface_request
+    );
+    let interface = FetchInterfaceResponse {
+        interface: interface_request.interface.clone(),
+        descriptor: descriptor(),
+        validator: Some(vec![4, 5, 6, 255]),
+    };
+    let encoded =
+        encode_fetch_interface_response(&interface_request, &interface, limits()).unwrap();
+    assert_eq!(
+        decode_fetch_interface_response(&interface_request, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(interface)
+    );
+}
+
+#[test]
+fn descriptor_guided_values_and_validators_round_trip_both_directions() {
+    let descriptor = descriptor();
+    let request = call_request();
+    let encoded =
+        encode_call_operation_request(&endpoint(), &request, &descriptor, limits()).unwrap();
+    let body = std::str::from_utf8(encoded.body()).unwrap();
+    assert!(body.contains("AAEC/w=="));
+    let metadata = decode_call_operation_metadata(encoded.body(), limits()).unwrap();
+    assert_eq!(metadata.target, request.target);
+    assert_eq!(metadata.interface, request.interface);
+    assert_eq!(metadata.operation, request.operation);
+    assert_eq!(
+        metadata
+            .decode_request(encoded.body(), &descriptor, limits())
+            .unwrap(),
+        request
+    );
+    let mut changed_route = request.clone();
+    changed_route.target.path = "/items/other".into();
+    let changed =
+        encode_call_operation_request(&endpoint(), &changed_route, &descriptor, limits()).unwrap();
+    assert!(
+        metadata
+            .decode_request(changed.body(), &descriptor, limits())
+            .is_err()
+    );
+
+    let mut null_json_request = request.clone();
+    null_json_request
+        .arguments
+        .insert("json".into(), Value::Unit);
+    null_json_request.arguments.insert(
+        "record".into(),
+        record([
+            ("required", Value::String("present".into())),
+            ("optional_json", Value::Unit),
+        ]),
+    );
+    let null_json =
+        encode_call_operation_request(&endpoint(), &null_json_request, &descriptor, limits())
+            .unwrap();
+    assert_eq!(
+        decode_call_operation_request(null_json.body(), &descriptor, limits()).unwrap(),
+        null_json_request
+    );
+
+    let expected = CallOperationResponse {
+        result: Value::Bytes(vec![255, 0, 1]),
+        validator: Some(vec![3, 2, 1, 0]),
+    };
+    let encoded =
+        encode_call_operation_response(&request, &descriptor, &expected, limits()).unwrap();
+    assert!(
+        std::str::from_utf8(encoded.body())
+            .unwrap()
+            .contains("/wAB")
+    );
+    assert_eq!(
+        decode_call_operation_response(&request, &descriptor, &encoded, limits()).unwrap(),
+        DecodedResponse::Success(expected)
+    );
+}
+
+#[test]
+fn malformed_unknown_null_and_noncanonical_base64_are_rejected() {
+    let limits = limits();
+    assert!(decode_observe_request(br#"{"path":"/","depth":0,"extra":true}"#, limits).is_err());
+    assert!(
+        decode_observe_request(br#"{"path":"relative","path":"/","depth":0}"#, limits).is_err()
+    );
+
+    let request = call_request();
+    let descriptor = descriptor();
+    let body = serde_json::to_vec(&serde_json::json!({
+        "target": {"path": "/items/123", "validator": null},
+        "interface": {"reference": "interface-v1"},
+        "operation": "everything",
+        "arguments": {}
+    }))
+    .unwrap();
+    assert!(decode_call_operation_request(&body, &descriptor, limits).is_err());
+
+    let mut json: serde_json::Value = serde_json::from_slice(
+        encode_call_operation_request(&endpoint(), &request, &descriptor, limits)
+            .unwrap()
+            .body(),
+    )
+    .unwrap();
+    json["arguments"]["bytes"] = serde_json::Value::String("AAEC_w==".into());
+    assert!(
+        decode_call_operation_request(&serde_json::to_vec(&json).unwrap(), &descriptor, limits)
+            .is_err()
+    );
+}
+
+#[test]
+fn caller_limits_bound_bytes_and_nesting() {
+    let tiny = Limits::new(8, 8, 2, 1).unwrap();
+    let too_large = decode_observe_request(br#"{"path":"/long","depth":0}"#, tiny).unwrap_err();
+    assert!(matches!(&too_large, CodecError::BodyTooLarge { .. }));
+    assert_eq!(
+        too_large.resource_limit_kind(),
+        Some(ResourceLimitKind::RepresentationBytes)
+    );
+
+    let nested = br#"{"path":[[["/"]]],"depth":0}"#;
+    let nesting_limited = Limits::new(1024, 1024, 2, 1).unwrap();
+    let too_deep = decode_observe_request(nested, nesting_limited).unwrap_err();
+    assert!(matches!(&too_deep, CodecError::NestingTooDeep { .. }));
+    assert_eq!(
+        too_deep.resource_limit_kind(),
+        Some(ResourceLimitKind::Logical)
+    );
+
+    let outbound_limited = Limits::new(1_000_000, 1_000_000, 1, 10).unwrap();
+    assert!(
+        encode_call_operation_request(
+            &endpoint(),
+            &call_request(),
+            &descriptor(),
+            outbound_limited,
+        )
+        .is_err()
+    );
+    assert!(
+        encode_observe_response(
+            &ObserveRequest {
+                path: "/item".into(),
+                depth: 0,
+            },
+            &ObjectObservation {
+                object: object("item", b"validator"),
+                children: None,
+            },
+            outbound_limited,
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn unsupported_descriptor_format_is_client_local() {
+    let request = FetchInterfaceRequest {
+        interface: "interface-v1".into(),
+    };
+    let mut interface = FetchInterfaceResponse {
+        interface: request.interface.clone(),
+        descriptor: descriptor(),
+        validator: None,
+    };
+    interface.descriptor.format = "future-format".into();
+    let response = encode_fetch_interface_response(&request, &interface, limits()).unwrap();
+    let error = decode_fetch_interface_response(&request, &response, limits()).unwrap_err();
+    assert!(matches!(
+        error,
+        ClientResponseError::UnsupportedDescriptorFormat { .. }
+    ));
+
+    let future_shape = wip_http::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(
+            br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future_shape":true}}"#
+                .to_vec(),
+        )
+        .unwrap();
+    assert!(matches!(
+        decode_fetch_interface_response(&request, &future_shape, limits()).unwrap_err(),
+        ClientResponseError::UnsupportedDescriptorFormat { format }
+            if format == "wip-interface/2"
+    ));
+
+    for malformed in [
+        br#"{"interface":"wrong","descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
+        br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"},"validator":null}"#
+            .as_slice(),
+    ] {
+        let response = wip_http::http::Response::builder()
+            .status(StatusCode::OK)
+            .header("content-type", "application/json; charset=utf-8")
+            .body(malformed.to_vec())
+            .unwrap();
+        assert!(matches!(
+            decode_fetch_interface_response(&request, &response, limits()).unwrap_err(),
+            ClientResponseError::InvalidResponse {
+                kind: InvalidResponseKind::InvalidSuccessBody,
+                ..
+            }
+        ));
+    }
+}
+
+#[test]
+fn invalid_success_is_classified_as_invalid_response() {
+    let response = wip_http::http::Response::builder()
+        .status(StatusCode::OK)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(br#"{"object":{"name":"wrong","interfaces":[]}}"#.to_vec())
+        .unwrap();
+    let error = decode_observe_response(
+        &ObserveRequest {
+            path: "/expected".into(),
+            depth: 0,
+        },
+        &response,
+        limits(),
+    )
+    .unwrap_err();
+    assert!(matches!(
+        error,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::InvalidSuccessBody,
+            ..
+        }
+    ));
+}

crates/wip-http/tests/responses.rs

@@ -0,0 +1,310 @@
+use wip_http::http::{Response, StatusCode};
+use wip_http::wip_protocol::{
+    ObserveRequest, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
+};
+use wip_http::{
+    ClientResponseError, DecodedResponse, InvalidResponseKind, Limits, ResourceLimitKind,
+    TransportFailureKind, decode_observe_response, encode_protocol_error_response,
+    encode_resource_limit_error_response, error_code_name, is_json_content_type, status_for_error,
+    status_for_resource_limit,
+};
+
+fn limits() -> Limits {
+    Limits::new(64 * 1024, 64 * 1024, 32, 16).unwrap()
+}
+
+fn request() -> ObserveRequest {
+    ObserveRequest {
+        path: "/".into(),
+        depth: 0,
+    }
+}
+
+fn response(status: StatusCode, body: impl Into<Vec<u8>>) -> Response<Vec<u8>> {
+    Response::builder()
+        .status(status)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(body.into())
+        .unwrap()
+}
+
+#[test]
+fn content_type_accepts_only_utf8_json_syntax() {
+    assert!(is_json_content_type("application/json"));
+    assert!(is_json_content_type("Application/JSON; Charset=\"UTF-8\""));
+    assert!(!is_json_content_type("application/json; charset=utf-16"));
+    assert!(!is_json_content_type("application/json; charset=\"utf-8"));
+    assert!(!is_json_content_type("application/json; charset=utf-8\""));
+    assert!(!is_json_content_type("application/json; profile=other"));
+}
+
+#[test]
+fn every_protocol_code_has_stable_name_and_status() {
+    let expected = [
+        (
+            ProtocolErrorCode::InvalidRequest,
+            "invalid_request",
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            ProtocolErrorCode::NotFound,
+            "not_found",
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            ProtocolErrorCode::InterfaceNotFound,
+            "interface_not_found",
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            ProtocolErrorCode::InterfaceMismatch,
+            "interface_mismatch",
+            StatusCode::CONFLICT,
+        ),
+        (
+            ProtocolErrorCode::OperationNotFound,
+            "operation_not_found",
+            StatusCode::NOT_FOUND,
+        ),
+        (
+            ProtocolErrorCode::InvalidArguments,
+            "invalid_arguments",
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+        (
+            ProtocolErrorCode::ValidatorRequired,
+            "validator_required",
+            StatusCode::PRECONDITION_REQUIRED,
+        ),
+        (
+            ProtocolErrorCode::ValidatorMismatch,
+            "validator_mismatch",
+            StatusCode::PRECONDITION_FAILED,
+        ),
+        (
+            ProtocolErrorCode::InterfaceValidatorRequired,
+            "interface_validator_required",
+            StatusCode::PRECONDITION_REQUIRED,
+        ),
+        (
+            ProtocolErrorCode::InterfaceValidatorMismatch,
+            "interface_validator_mismatch",
+            StatusCode::PRECONDITION_FAILED,
+        ),
+        (
+            ProtocolErrorCode::PermissionDenied,
+            "permission_denied",
+            StatusCode::FORBIDDEN,
+        ),
+        (
+            ProtocolErrorCode::ResourceLimitExceeded,
+            "resource_limit_exceeded",
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+        (
+            ProtocolErrorCode::Internal,
+            "internal",
+            StatusCode::INTERNAL_SERVER_ERROR,
+        ),
+        (
+            ProtocolErrorCode::OperationOutcomeUnknown,
+            "operation_outcome_unknown",
+            StatusCode::INTERNAL_SERVER_ERROR,
+        ),
+    ];
+    assert_eq!(expected.len(), ProtocolErrorCode::ALL.len());
+    for (code, name, status) in expected {
+        assert_eq!(error_code_name(code), name);
+        assert_eq!(status_for_error(code), status);
+    }
+}
+
+#[test]
+fn resource_limit_statuses_encode_and_decode_by_concrete_limit_class() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::ResourceLimitExceeded,
+        message: "bounded".into(),
+    };
+    let cases = [
+        (
+            ResourceLimitKind::RepresentationBytes,
+            StatusCode::PAYLOAD_TOO_LARGE,
+        ),
+        (ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
+    ];
+    for (kind, status) in cases {
+        assert_eq!(status_for_resource_limit(kind), status);
+        let encoded = encode_resource_limit_error_response(
+            ProtocolInteraction::Observe,
+            &error,
+            kind,
+            limits(),
+        )
+        .unwrap();
+        assert_eq!(encoded.status(), status);
+        assert_eq!(
+            decode_observe_response(&request(), &encoded, limits()).unwrap(),
+            DecodedResponse::ProtocolFailure {
+                error: error.clone(),
+                status_mismatch: None,
+            }
+        );
+    }
+
+    let default =
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).unwrap();
+    assert_eq!(default.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    assert_ne!(default.status(), StatusCode::TOO_MANY_REQUESTS);
+}
+
+#[test]
+fn rate_limit_status_without_protocol_envelope_stays_transport_failure() {
+    let response = Response::builder()
+        .status(StatusCode::TOO_MANY_REQUESTS)
+        .body(b"rate limited".to_vec())
+        .unwrap();
+    assert!(matches!(
+        decode_observe_response(&request(), &response, limits()).unwrap_err(),
+        ClientResponseError::TransportBinding(failure)
+            if failure.status == StatusCode::TOO_MANY_REQUESTS
+                && failure.kind == TransportFailureKind::HttpStatus
+    ));
+}
+
+#[test]
+fn valid_success_body_requires_exactly_http_200() {
+    let success_body = br#"{"object":{"name":"","interfaces":[]}}"#;
+    for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
+        assert!(matches!(
+            decode_observe_response(&request(), &response(status, success_body), limits())
+                .unwrap_err(),
+            ClientResponseError::InvalidResponse {
+                kind: InvalidResponseKind::NonCanonicalSuccessStatus,
+                ..
+            }
+        ));
+    }
+}
+
+#[test]
+fn server_encoder_rejects_codes_disallowed_for_the_interaction() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::InterfaceNotFound,
+        message: "not valid for observe".into(),
+    };
+    assert!(
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).is_err()
+    );
+}
+
+#[test]
+fn valid_envelope_code_is_authoritative_when_status_mismatches() {
+    let error = ProtocolError {
+        code: ProtocolErrorCode::NotFound,
+        message: "missing".into(),
+    };
+    let mut encoded =
+        encode_protocol_error_response(ProtocolInteraction::Observe, &error, limits()).unwrap();
+    *encoded.status_mut() = StatusCode::IM_A_TEAPOT;
+
+    assert_eq!(
+        decode_observe_response(&request(), &encoded, limits()).unwrap(),
+        DecodedResponse::ProtocolFailure {
+            error,
+            status_mismatch: Some(wip_http::StatusMismatch {
+                actual: StatusCode::IM_A_TEAPOT,
+                expected: StatusCode::NOT_FOUND,
+            }),
+        }
+    );
+}
+
+#[test]
+fn envelope_and_status_contradictions_are_invalid_responses() {
+    let error_body = br#"{"error":{"code":"not_found","message":"missing"}}"#;
+    let on_success =
+        decode_observe_response(&request(), &response(StatusCode::OK, error_body), limits())
+            .unwrap_err();
+    assert!(matches!(
+        on_success,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
+            ..
+        }
+    ));
+
+    let success_body = br#"{"object":{"name":"","interfaces":[]}}"#;
+    let on_error = decode_observe_response(
+        &request(),
+        &response(StatusCode::BAD_GATEWAY, success_body),
+        limits(),
+    )
+    .unwrap_err();
+    assert!(matches!(
+        on_error,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::SuccessBodyOnErrorStatus,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn disallowed_protocol_code_is_invalid_instead_of_reclassified() {
+    let body = br#"{"error":{"code":"interface_not_found","message":"wrong interaction"}}"#;
+    let error =
+        decode_observe_response(&request(), &response(StatusCode::NOT_FOUND, body), limits())
+            .unwrap_err();
+    assert!(matches!(
+        error,
+        ClientResponseError::InvalidResponse {
+            kind: InvalidResponseKind::DisallowedProtocolCode,
+            ..
+        }
+    ));
+}
+
+#[test]
+fn proxy_authentication_and_endpoint_failures_stay_transport_failures() {
+    let cases = [
+        (
+            StatusCode::BAD_GATEWAY,
+            TransportFailureKind::HttpStatus,
+            b"proxy failure".as_slice(),
+        ),
+        (
+            StatusCode::UNAUTHORIZED,
+            TransportFailureKind::AuthenticationRequired,
+            b"login required".as_slice(),
+        ),
+        (
+            StatusCode::FORBIDDEN,
+            TransportFailureKind::EndpointForbidden,
+            b"denied".as_slice(),
+        ),
+    ];
+    for (status, expected_kind, body) in cases {
+        let response = Response::builder()
+            .status(status)
+            .body(body.to_vec())
+            .unwrap();
+        let error = decode_observe_response(&request(), &response, limits()).unwrap_err();
+        assert!(matches!(
+            error,
+            ClientResponseError::TransportBinding(failure)
+                if failure.status == status && failure.kind == expected_kind
+        ));
+    }
+}
+
+#[test]
+fn malformed_non_success_envelope_is_transport_binding_failure() {
+    let malformed = response(
+        StatusCode::BAD_GATEWAY,
+        br#"{"error":{"code":"not_found","message":null}}"#,
+    );
+    assert!(matches!(
+        decode_observe_response(&request(), &malformed, limits()).unwrap_err(),
+        ClientResponseError::TransportBinding(_)
+    ));
+}

crates/wip-http/tests/routes.rs

@@ -0,0 +1,142 @@
+use wip_http::http::{Method, Request, StatusCode};
+use wip_http::{Endpoint, RequestMetadataError, Route, validate_http_request};
+
+#[test]
+fn endpoint_preserves_http_and_https_when_resolving_canonical_routes() {
+    for scheme in ["http", "https"] {
+        let endpoint = Endpoint::parse(&format!("{scheme}://example.test/root/prefix")).unwrap();
+        assert_eq!(
+            endpoint.to_string(),
+            format!("{scheme}://example.test/root/prefix/")
+        );
+
+        let expected = [
+            (Route::Observe, "v1/observe"),
+            (Route::FetchInterface, "v1/fetch_interface"),
+            (Route::CallOperation, "v1/call_operation"),
+            (Route::Batch, "v1/batch"),
+        ];
+        for (route, suffix) in expected {
+            let url = format!("{scheme}://example.test/root/prefix/{suffix}");
+            assert_eq!(endpoint.route(route).as_str(), url);
+            assert_eq!(
+                endpoint.recognize(&wip_http::url::Url::parse(&url).unwrap()),
+                Some(route)
+            );
+        }
+        assert_eq!(
+            endpoint.recognize(
+                &wip_http::url::Url::parse(&format!(
+                    "{scheme}://example.test/root/prefix/v1/observe?path=/items"
+                ))
+                .unwrap()
+            ),
+            None
+        );
+    }
+}
+
+#[test]
+fn routes_never_mix_worldspace_paths_into_endpoint_prefixes() {
+    let endpoint = Endpoint::parse("https://example.test/wip/%E4%B8%96%E7%95%8C/").unwrap();
+    let route = endpoint.route(Route::Observe);
+    assert_eq!(route.path(), "/wip/%E4%B8%96%E7%95%8C/v1/observe");
+    assert!(!route.as_str().contains("items"));
+}
+
+#[test]
+fn inbound_http_metadata_enforces_post_route_and_json() {
+    let endpoint = Endpoint::parse("https://example.test/wip").unwrap();
+    let valid = Request::builder()
+        .method(Method::POST)
+        .uri("/wip/v1/observe")
+        .header("content-type", "application/json; charset=utf-8")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    assert!(validate_http_request(&endpoint, Route::Observe, &valid).is_ok());
+
+    let wrong_method = Request::builder()
+        .method(Method::GET)
+        .uri("/wip/v1/observe")
+        .header("content-type", "application/json")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    assert!(validate_http_request(&endpoint, Route::Observe, &wrong_method).is_err());
+
+    let wrong_route = Request::builder()
+        .method(Method::POST)
+        .uri("/wip/v1/fetch_interface")
+        .header("content-type", "application/json")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    assert!(validate_http_request(&endpoint, Route::Observe, &wrong_route).is_err());
+
+    for accept in [
+        "text/plain, */*;q=1, application/json;q=0",
+        "application/json; charset=utf-16",
+        "application/json; profile=future",
+    ] {
+        let incompatible_accept = Request::builder()
+            .method(Method::POST)
+            .uri("/wip/v1/observe")
+            .header("content-type", "application/json")
+            .header("accept", accept)
+            .body(Vec::<u8>::new())
+            .unwrap();
+        let error =
+            validate_http_request(&endpoint, Route::Observe, &incompatible_accept).unwrap_err();
+        assert!(matches!(&error, RequestMetadataError::NotAcceptable));
+        assert_eq!(error.status(), StatusCode::NOT_ACCEPTABLE);
+    }
+
+    for accept in [
+        "application/json; charset=UTF-8",
+        "application/json; q=1; profile=accept-extension",
+    ] {
+        let compatible_accept = Request::builder()
+            .method(Method::POST)
+            .uri("/wip/v1/observe")
+            .header("content-type", "application/json")
+            .header("accept", accept)
+            .body(Vec::<u8>::new())
+            .unwrap();
+        assert!(validate_http_request(&endpoint, Route::Observe, &compatible_accept).is_ok());
+    }
+
+    let unsupported_media_type = Request::builder()
+        .method(Method::POST)
+        .uri("/wip/v1/observe")
+        .header("content-type", "text/plain")
+        .header("accept", "application/json")
+        .body(Vec::<u8>::new())
+        .unwrap();
+    let error =
+        validate_http_request(&endpoint, Route::Observe, &unsupported_media_type).unwrap_err();
+    assert!(matches!(&error, RequestMetadataError::UnsupportedMediaType));
+    assert_eq!(error.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
+}
+
+#[test]
+fn invalid_endpoint_components_and_non_routes_are_rejected() {
+    assert!(Endpoint::parse("/relative").is_err());
+    assert!(Endpoint::parse("file:///wip").is_err());
+    assert!(Endpoint::parse("https://example.test/wip?q=1").is_err());
+    assert!(Endpoint::parse("https://example.test/wip#fragment").is_err());
+
+    let deployment_endpoint = Endpoint::parse("http://user:secret@example.test/wip").unwrap();
+    assert_eq!(deployment_endpoint.as_url().scheme(), "http");
+    assert_eq!(deployment_endpoint.as_url().username(), "user");
+
+    let endpoint = Endpoint::parse("http://example.test/wip").unwrap();
+    for outside in [
+        "http://example.test/wip/v1/unknown",
+        "http://example.test/wip/v1/observe/extra",
+        "https://example.test/wip/v1/observe",
+        "http://other.test/wip/v1/observe",
+    ] {
+        assert_eq!(
+            endpoint.recognize(&wip_http::url::Url::parse(outside).unwrap()),
+            None
+        );
+    }
+}