feat: add bounded filesystem projection server

crates/wip-fs-server/src/interfaces.rs

@@ -0,0 +1,43 @@
+//! Filesystem capability interfaces published by the projection.
+
+use wip_interface as wip;
+
+/// Bounded reads from a regular file.
+#[wip::interface]
+pub trait FileRead {
+    /// Reads bytes from the current regular file.
+    ///
+    /// # Returns
+    /// At most the configured read limit, beginning at `offset`.
+    fn read(
+        &self,
+        /// Byte offset; omitted means zero.
+        offset: Option<u64>,
+        /// Requested byte count; omitted means the rest of the file.
+        length: Option<u64>,
+    ) -> wip::OperationResult<wip::Bytes>;
+}
+
+/// Inspection operations for a symbolic link itself.
+#[wip::interface]
+pub trait SymlinkInspect {
+    /// Reads the link payload without following it.
+    ///
+    /// # Returns
+    /// The platform path bytes stored in the symbolic link.
+    fn read_link(&self) -> wip::OperationResult<wip::Bytes>;
+}
+
+/// Explicitly enabled mutation of a regular file.
+#[wip::interface]
+pub trait FileWrite {
+    /// Replaces the current regular file contents through its pinned handle.
+    ///
+    /// # Returns
+    /// Unit after the new bytes have been written and synchronized.
+    fn replace(
+        &self,
+        /// Complete replacement contents.
+        contents: wip::Bytes,
+    ) -> wip::OperationResult<()>;
+}

crates/wip-fs-server/src/lib.rs

@@ -0,0 +1,197 @@
+//! Request-time filesystem projection served through the standard WIP HTTPS binding.
+//!
+//! This crate deliberately keeps the boundaries visible:
+//!
+//! - [`wip_protocol`] owns logical requests and responses;
+//! - [`wip_host`] owns object publication, validators, and typed dispatch;
+//! - [`wip_https`] owns routes, JSON, envelopes, batching, and status mapping;
+//! - this crate owns the filesystem capability boundary and the real HTTP listener.
+//!
+//! TLS is terminated by an explicitly configured reverse proxy. The built-in
+//! listener accepts cleartext only on loopback, either behind that proxy or when
+//! [`TransportSecurity::DevelopmentHttp`] is deliberately selected.
+
+#![deny(missing_docs)]
+
+mod interfaces;
+mod projection;
+mod server;
+
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+pub use interfaces::{FileRead, FileWrite, SymlinkInspect};
+pub use server::{BoundServer, ServerBuildError, WipFsServer};
+
+/// Filesystem capabilities published by regular files.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AccessMode {
+    /// Publish bounded reads only.
+    ReadOnly,
+    /// Also publish validator-protected whole-file replacement.
+    ReadWrite,
+}
+
+/// How HTTPS is provided for the endpoint.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TransportSecurity {
+    /// A trusted reverse proxy terminates TLS and forwards to the loopback listener.
+    ReverseProxyTls,
+    /// Cleartext HTTP is deliberately enabled for local development only.
+    DevelopmentHttp,
+}
+
+/// Bounded resource policy applied by the HTTP adapter and filesystem provider.
+#[derive(Debug, Clone, Copy)]
+pub struct ResourceLimits {
+    /// Standard JSON, body-size, nesting, and batch limits.
+    pub wire: wip_https::Limits,
+    /// Maximum bytes returned by one file read.
+    pub max_file_read_bytes: usize,
+    /// Maximum bytes accepted by one file replacement.
+    pub max_file_write_bytes: usize,
+    /// Maximum accepted `fetch_tree` depth.
+    pub max_tree_depth: u32,
+    /// Maximum accepted `fetch_tree` node count, including its root.
+    pub max_tree_nodes: u32,
+    /// Maximum simultaneously pinned projected filesystem handles.
+    pub max_open_handles: usize,
+    /// Maximum requests executing concurrently.
+    pub max_concurrent_requests: usize,
+    /// Deadline applied to request dispatch and cooperative filesystem work.
+    pub request_timeout: Duration,
+}
+
+impl Default for ResourceLimits {
+    fn default() -> Self {
+        Self {
+            wire: wip_https::Limits::new(256 * 1024, 2 * 1024 * 1024, 64, 64)
+                .expect("default wire limits are nonzero"),
+            max_file_read_bytes: 1024 * 1024,
+            max_file_write_bytes: 1024 * 1024,
+            max_tree_depth: 32,
+            max_tree_nodes: 1024,
+            max_open_handles: 2048,
+            max_concurrent_requests: 32,
+            request_timeout: Duration::from_secs(30),
+        }
+    }
+}
+
+/// Complete listener and projection configuration.
+#[derive(Debug, Clone)]
+pub struct ServerConfig {
+    /// Filesystem directory projected as Worldspace `/`.
+    pub root: PathBuf,
+    /// Loopback socket used by the built-in cleartext listener.
+    pub listen: SocketAddr,
+    /// URL path prefix below which standard `v1/*` routes are mounted.
+    pub endpoint_base_path: String,
+    /// Read-only or explicit read-write publication mode.
+    pub access: AccessMode,
+    /// TLS termination or explicit development HTTP policy.
+    pub transport_security: TransportSecurity,
+    /// Request, operation, traversal, and concurrency bounds.
+    pub limits: ResourceLimits,
+}
+
+impl ServerConfig {
+    /// Builds a secure-by-default configuration for `root`.
+    ///
+    /// The listener defaults to an ephemeral loopback port, read-only access,
+    /// and TLS termination delegated to a reverse proxy.
+    #[must_use]
+    pub fn for_root(root: impl Into<PathBuf>) -> Self {
+        Self {
+            root: root.into(),
+            listen: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
+            endpoint_base_path: "/wip".into(),
+            access: AccessMode::ReadOnly,
+            transport_security: TransportSecurity::ReverseProxyTls,
+            limits: ResourceLimits::default(),
+        }
+    }
+
+    pub(crate) fn validate(&self) -> Result<(), ConfigError> {
+        if !self.listen.ip().is_loopback() {
+            return Err(ConfigError::NonLoopbackCleartext);
+        }
+        if !valid_base_path(&self.endpoint_base_path) {
+            return Err(ConfigError::InvalidBasePath);
+        }
+        if self.limits.max_file_read_bytes == 0
+            || self.limits.max_file_write_bytes == 0
+            || self.limits.max_tree_nodes == 0
+            || self.limits.max_open_handles == 0
+            || self.limits.max_concurrent_requests == 0
+            || self.limits.request_timeout.is_zero()
+        {
+            return Err(ConfigError::ZeroLimit);
+        }
+        if self.limits.max_open_handles < self.limits.max_tree_nodes as usize {
+            return Err(ConfigError::InsufficientHandles);
+        }
+        if self.limits.wire.max_response_bytes() < 512 {
+            return Err(ConfigError::ResponseLimitTooSmall);
+        }
+        Ok(())
+    }
+
+    pub(crate) fn effective_root(&self) -> Result<PathBuf, std::io::Error> {
+        std::fs::canonicalize(&self.root)
+    }
+
+    pub(crate) fn endpoint(&self) -> Result<wip_https::Endpoint, ConfigError> {
+        let endpoint = format!("https://localhost{}", self.endpoint_base_path);
+        wip_https::Endpoint::parse(&endpoint).map_err(|_| ConfigError::InvalidBasePath)
+    }
+}
+
+/// Invalid server configuration.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConfigError {
+    /// The cleartext built-in listener was exposed beyond loopback.
+    NonLoopbackCleartext,
+    /// The endpoint prefix is not an absolute canonical URL path.
+    InvalidBasePath,
+    /// A resource limit is zero.
+    ZeroLimit,
+    /// Tree nodes could exhaust the configured handle ceiling by construction.
+    InsufficientHandles,
+    /// The response limit cannot reliably carry a bounded protocol error envelope.
+    ResponseLimitTooSmall,
+}
+
+impl std::fmt::Display for ConfigError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(match self {
+            Self::NonLoopbackCleartext => "the built-in cleartext listener must bind to loopback",
+            Self::InvalidBasePath => {
+                "endpoint base path must be absolute, canonical, and query-free"
+            }
+            Self::ZeroLimit => "all resource limits and the request timeout must be nonzero",
+            Self::InsufficientHandles => "max_open_handles must cover max_tree_nodes",
+            Self::ResponseLimitTooSmall => "max_response_bytes must be at least 512",
+        })
+    }
+}
+
+impl std::error::Error for ConfigError {}
+
+fn valid_base_path(path: &str) -> bool {
+    path.starts_with('/')
+        && !path.contains('?')
+        && !path.contains('#')
+        && !path.contains("//")
+        && !path
+            .split('/')
+            .any(|segment| segment == "." || segment == "..")
+        && (path == "/" || !path.ends_with('/'))
+}
+
+/// Returns whether `root` is an existing directory suitable for projection.
+#[must_use]
+pub fn is_projectable_root(root: &Path) -> bool {
+    root.is_dir()
+}

crates/wip-fs-server/src/main.rs

@@ -0,0 +1,83 @@
+use std::error::Error;
+use std::net::SocketAddr;
+use std::path::PathBuf;
+
+use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut root: Option<PathBuf> = None;
+    let mut listen: SocketAddr = "127.0.0.1:8443".parse()?;
+    let mut base_path = "/wip".to_owned();
+    let mut access = AccessMode::ReadOnly;
+    let mut security = None;
+    let mut arguments = std::env::args().skip(1);
+    while let Some(argument) = arguments.next() {
+        match argument.as_str() {
+            "--root" => root = Some(PathBuf::from(required_value(&mut arguments, "--root")?)),
+            "--listen" => listen = required_value(&mut arguments, "--listen")?.parse()?,
+            "--base-path" => base_path = required_value(&mut arguments, "--base-path")?,
+            "--read-write" => access = AccessMode::ReadWrite,
+            "--development-http" => {
+                set_security(&mut security, TransportSecurity::DevelopmentHttp)?
+            }
+            "--behind-tls-proxy" => {
+                set_security(&mut security, TransportSecurity::ReverseProxyTls)?
+            }
+            "--help" | "-h" => {
+                print_help();
+                return Ok(());
+            }
+            unknown => return Err(format!("unknown argument `{unknown}`; use --help").into()),
+        }
+    }
+
+    let root = root.ok_or("--root is required")?;
+    let transport_security =
+        security.ok_or("select exactly one of --behind-tls-proxy or --development-http")?;
+    let mut config = ServerConfig::for_root(root);
+    config.listen = listen;
+    config.endpoint_base_path = base_path;
+    config.access = access;
+    config.transport_security = transport_security;
+
+    let server = WipFsServer::new(config)?;
+    let effective_root = server.effective_root().to_owned();
+    let endpoint = server.endpoint().clone();
+    let bound = server.bind()?;
+    eprintln!(
+        "wip-fs-server root={} access={access:?} transport={transport_security:?} endpoint={} listen={}",
+        effective_root.display(),
+        endpoint,
+        bound.local_addr()
+    );
+    bound.serve()?;
+    Ok(())
+}
+
+fn required_value(
+    arguments: &mut impl Iterator<Item = String>,
+    option: &str,
+) -> Result<String, Box<dyn Error>> {
+    arguments
+        .next()
+        .ok_or_else(|| format!("{option} requires a value").into())
+}
+
+fn set_security(
+    security: &mut Option<TransportSecurity>,
+    value: TransportSecurity,
+) -> Result<(), Box<dyn Error>> {
+    if security.replace(value).is_some() {
+        Err("select only one transport-security mode".into())
+    } else {
+        Ok(())
+    }
+}
+
+fn print_help() {
+    println!(
+        "Usage: wip-fs-server --root PATH [--listen 127.0.0.1:8443] \\\n         [--base-path /wip] [--read-write] \\\n         (--behind-tls-proxy | --development-http)\n\n\
+         The built-in listener is cleartext and loopback-only. In production, \
+         select --behind-tls-proxy and terminate HTTPS at a trusted reverse proxy."
+    );
+}

crates/wip-fs-server/src/server.rs

@@ -0,0 +1,523 @@
+use std::io::Read;
+use std::net::SocketAddr;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::thread;
+use std::time::{Duration, Instant};
+
+use http::{Request, Response, StatusCode};
+use wip_host::{ExecutionContext, ObjectProvider};
+use wip_https::{
+    BatchRequestKind, BatchResponse, BatchResponseItem, BatchSuccess, CodecError, EncodeHttpError,
+    Endpoint, RequestMetadataError, ResourceLimitKind, Route, decode_batch_request,
+    decode_call_operation_metadata, decode_fetch_interface_request, decode_fetch_request,
+    decode_fetch_tree_request, encode_batch_error_response,
+    encode_batch_resource_limit_error_response, encode_batch_response,
+    encode_call_operation_response, encode_fetch_interface_response, encode_fetch_response,
+    encode_fetch_tree_response, encode_protocol_error_response,
+    encode_resource_limit_error_response, validate_http_request,
+};
+use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
+
+use crate::projection::Projection;
+use crate::{ConfigError, ServerConfig};
+
+/// Filesystem projection and framework-neutral standard WIP request adapter.
+pub struct WipFsServer {
+    config: ServerConfig,
+    endpoint: Endpoint,
+    effective_root: std::path::PathBuf,
+    projection: Arc<Projection>,
+}
+
+impl WipFsServer {
+    /// Validates configuration and opens the configured directory capability.
+    pub fn new(config: ServerConfig) -> Result<Self, ServerBuildError> {
+        config.validate()?;
+        let effective_root = config.effective_root()?;
+        let endpoint = config.endpoint()?;
+        let projection = Projection::open(&effective_root, config.access, config.limits)?;
+        Ok(Self {
+            config,
+            endpoint,
+            effective_root,
+            projection: Arc::new(projection),
+        })
+    }
+
+    /// Returns the canonical effective filesystem root opened by the server.
+    #[must_use]
+    pub fn effective_root(&self) -> &std::path::Path {
+        &self.effective_root
+    }
+
+    /// Returns the configured transport endpoint prefix.
+    #[must_use]
+    pub fn endpoint(&self) -> &Endpoint {
+        &self.endpoint
+    }
+
+    /// Handles one already-buffered HTTP request with the standard `wip-https` codecs.
+    ///
+    /// Listener integrations must enforce the same body limit while collecting bytes.
+    #[must_use]
+    pub fn handle_http(&self, request: Request<Vec<u8>>) -> Response<Vec<u8>> {
+        let Some(route) = self.route(request.uri().path()) else {
+            return empty_response(StatusCode::NOT_FOUND);
+        };
+        if let Err(error) = validate_http_request(&self.endpoint, route, &request) {
+            return self.metadata_error(route, error);
+        }
+        let context = ExecutionContext::new()
+            .with_deadline(Instant::now() + self.config.limits.request_timeout)
+            .with_resource_budget(u64::from(self.config.limits.max_tree_nodes));
+        match route {
+            Route::Fetch => self.fetch(request.body(), &context),
+            Route::FetchTree => self.fetch_tree(request.body(), &context),
+            Route::FetchInterface => self.fetch_interface(request.body()),
+            Route::CallOperation => self.call_operation(request.body(), &context),
+            Route::Batch => self.batch(request.body(), &context),
+        }
+    }
+
+    /// Binds the built-in bounded loopback HTTP listener.
+    ///
+    /// The listener is cleartext by design. Configuration must explicitly state
+    /// whether TLS is terminated by a reverse proxy or development HTTP is in use.
+    pub fn bind(self) -> Result<BoundServer, ServerBuildError> {
+        let server = tiny_http::Server::http(self.config.listen)
+            .map_err(|error| ServerBuildError::Listener(error.to_string()))?;
+        let local_addr = server
+            .server_addr()
+            .to_ip()
+            .ok_or_else(|| ServerBuildError::Listener("expected an IP listener".into()))?;
+        Ok(BoundServer {
+            local_addr,
+            service: Arc::new(self),
+            listener: Arc::new(server),
+        })
+    }
+
+    fn route(&self, path: &str) -> Option<Route> {
+        [
+            Route::Fetch,
+            Route::FetchTree,
+            Route::FetchInterface,
+            Route::CallOperation,
+            Route::Batch,
+        ]
+        .into_iter()
+        .find(|route| self.endpoint.route(*route).path() == path)
+    }
+
+    fn fetch(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
+        let request = match decode_fetch_request(body, self.config.limits.wire) {
+            Ok(request) => request,
+            Err(error) => return self.codec_error(ProtocolInteraction::Fetch, error),
+        };
+        match self
+            .projection
+            .fetch_with_context(context, &request.path)
+            .map_err(|error| error.protocol_error())
+        {
+            Ok(object) => encode_fetch_response(&request, &object, self.config.limits.wire)
+                .unwrap_or_else(|error| self.read_encode_error(ProtocolInteraction::Fetch, error)),
+            Err(error) => self.protocol_error(ProtocolInteraction::Fetch, &error, None),
+        }
+    }
+
+    fn fetch_tree(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
+        let request = match decode_fetch_tree_request(body, self.config.limits.wire) {
+            Ok(request) => request,
+            Err(error) => return self.codec_error(ProtocolInteraction::FetchTree, error),
+        };
+        match self.projection.fetch_tree(context, &request) {
+            Ok(tree) => encode_fetch_tree_response(&request, &tree, self.config.limits.wire)
+                .unwrap_or_else(|error| {
+                    self.read_encode_error(ProtocolInteraction::FetchTree, error)
+                }),
+            Err(error) => self.protocol_error(ProtocolInteraction::FetchTree, &error, None),
+        }
+    }
+
+    fn fetch_interface(&self, body: &[u8]) -> Response<Vec<u8>> {
+        let request = match decode_fetch_interface_request(body, self.config.limits.wire) {
+            Ok(request) => request,
+            Err(error) => return self.codec_error(ProtocolInteraction::FetchInterface, error),
+        };
+        match self.projection.fetch_interface(&request) {
+            Ok(interface) => {
+                encode_fetch_interface_response(&request, &interface, self.config.limits.wire)
+                    .unwrap_or_else(|error| {
+                        self.read_encode_error(ProtocolInteraction::FetchInterface, error)
+                    })
+            }
+            Err(error) => self.protocol_error(ProtocolInteraction::FetchInterface, &error, None),
+        }
+    }
+
+    fn call_operation(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
+        let metadata = match decode_call_operation_metadata(body, self.config.limits.wire) {
+            Ok(metadata) => metadata,
+            Err(error) => return self.codec_error(ProtocolInteraction::CallOperation, error),
+        };
+        let decoded = std::sync::Mutex::new(None);
+        let execution = self.projection.call_operation_with_context_and_decoder(
+            context,
+            metadata.target.clone(),
+            metadata.interface.clone(),
+            metadata.operation.clone(),
+            |descriptor| {
+                let request = metadata.decode_request(body, descriptor, self.config.limits.wire)?;
+                let arguments = request.arguments.clone();
+                *decoded.lock().unwrap_or_else(|error| error.into_inner()) =
+                    Some((request, descriptor.clone()));
+                Ok::<_, CodecError>(arguments)
+            },
+        );
+        match execution.map_err(|error| error.protocol_error()) {
+            Ok(result) => {
+                let Some((request, descriptor)) = decoded
+                    .into_inner()
+                    .unwrap_or_else(|error| error.into_inner())
+                else {
+                    return self.protocol_error(
+                        ProtocolInteraction::CallOperation,
+                        &ProtocolError {
+                            code: ProtocolErrorCode::OperationOutcomeUnknown,
+                            message: "operation completed without response metadata".into(),
+                        },
+                        None,
+                    );
+                };
+                encode_call_operation_response(
+                    &request,
+                    &descriptor,
+                    &result,
+                    self.config.limits.wire,
+                )
+                .unwrap_or_else(|_| {
+                    // Dispatch succeeded. A transport/result encoding failure cannot
+                    // prove that a write did not commit.
+                    let error = ProtocolError {
+                        code: ProtocolErrorCode::OperationOutcomeUnknown,
+                        message: "operation completed but its response could not be encoded".into(),
+                    };
+                    self.protocol_error(ProtocolInteraction::CallOperation, &error, None)
+                })
+            }
+            Err(error) => self.protocol_error(ProtocolInteraction::CallOperation, &error, None),
+        }
+    }
+
+    fn batch(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
+        let request = match decode_batch_request(body, self.config.limits.wire) {
+            Ok(request) => request,
+            Err(error) => return self.batch_codec_error(error),
+        };
+        let responses = request
+            .requests
+            .iter()
+            .map(|item| {
+                let outcome = match &item.request {
+                    BatchRequestKind::Fetch(request) => self
+                        .projection
+                        .fetch_with_context(context, &request.path)
+                        .map(BatchSuccess::Fetch)
+                        .map_err(|error| error.protocol_error()),
+                    BatchRequestKind::FetchTree(request) => self
+                        .projection
+                        .fetch_tree(context, request)
+                        .map(BatchSuccess::FetchTree),
+                    BatchRequestKind::FetchInterface(request) => self
+                        .projection
+                        .fetch_interface(request)
+                        .map(BatchSuccess::FetchInterface),
+                    BatchRequestKind::Invalid { error, .. } => Err(error.clone()),
+                };
+                BatchResponseItem {
+                    id: item.id.clone(),
+                    outcome,
+                }
+            })
+            .collect();
+        let response = BatchResponse { responses };
+        encode_batch_response(&request, &response, self.config.limits.wire).unwrap_or_else(
+            |error| match error {
+                EncodeHttpError::Codec(codec) => self.batch_codec_error(codec),
+                EncodeHttpError::Http(_) => self.batch_top_error(&internal_error(), None),
+            },
+        )
+    }
+
+    fn metadata_error(&self, route: Route, error: RequestMetadataError) -> Response<Vec<u8>> {
+        match error {
+            RequestMetadataError::InvalidRequest(_) => self.protocol_error(
+                interaction(route),
+                &ProtocolError {
+                    code: ProtocolErrorCode::InvalidRequest,
+                    message: "invalid HTTP request metadata".into(),
+                },
+                None,
+            ),
+            RequestMetadataError::UnsupportedMediaType => {
+                empty_response(StatusCode::UNSUPPORTED_MEDIA_TYPE)
+            }
+            RequestMetadataError::NotAcceptable => empty_response(StatusCode::NOT_ACCEPTABLE),
+        }
+    }
+
+    fn codec_error(
+        &self,
+        interaction: ProtocolInteraction,
+        error: CodecError,
+    ) -> Response<Vec<u8>> {
+        if let Some(kind) = error.resource_limit_kind() {
+            self.protocol_error(interaction, &resource_error(), Some(kind))
+        } else {
+            self.protocol_error(
+                interaction,
+                &ProtocolError {
+                    code: ProtocolErrorCode::InvalidRequest,
+                    message: "malformed WIP request".into(),
+                },
+                None,
+            )
+        }
+    }
+
+    fn batch_codec_error(&self, error: CodecError) -> Response<Vec<u8>> {
+        if let Some(kind) = error.resource_limit_kind() {
+            self.batch_top_error(&resource_error(), Some(kind))
+        } else {
+            self.batch_top_error(
+                &ProtocolError {
+                    code: ProtocolErrorCode::InvalidRequest,
+                    message: "malformed WIP batch request".into(),
+                },
+                None,
+            )
+        }
+    }
+
+    fn read_encode_error(
+        &self,
+        interaction: ProtocolInteraction,
+        error: EncodeHttpError,
+    ) -> Response<Vec<u8>> {
+        match error {
+            EncodeHttpError::Codec(codec) if codec.resource_limit_kind().is_some() => {
+                self.protocol_error(interaction, &resource_error(), codec.resource_limit_kind())
+            }
+            _ => self.protocol_error(interaction, &internal_error(), None),
+        }
+    }
+
+    fn protocol_error(
+        &self,
+        interaction: ProtocolInteraction,
+        error: &ProtocolError,
+        resource_kind: Option<ResourceLimitKind>,
+    ) -> Response<Vec<u8>> {
+        let encoded = match resource_kind {
+            Some(kind) => encode_resource_limit_error_response(
+                interaction,
+                error,
+                kind,
+                self.config.limits.wire,
+            ),
+            None => encode_protocol_error_response(interaction, error, self.config.limits.wire),
+        };
+        encoded.unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
+    }
+
+    fn batch_top_error(
+        &self,
+        error: &ProtocolError,
+        resource_kind: Option<ResourceLimitKind>,
+    ) -> Response<Vec<u8>> {
+        let encoded = match resource_kind {
+            Some(kind) => {
+                encode_batch_resource_limit_error_response(error, kind, self.config.limits.wire)
+            }
+            None => encode_batch_error_response(error, self.config.limits.wire),
+        };
+        encoded.unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
+    }
+}
+
+/// Bound real HTTP listener for a [`WipFsServer`].
+pub struct BoundServer {
+    local_addr: SocketAddr,
+    service: Arc<WipFsServer>,
+    listener: Arc<tiny_http::Server>,
+}
+
+impl BoundServer {
+    /// Returns the actual bound loopback address, including an assigned port.
+    #[must_use]
+    pub fn local_addr(&self) -> SocketAddr {
+        self.local_addr
+    }
+
+    /// Serves requests with a fixed worker count until `shutdown` becomes true.
+    pub fn serve_until(&self, shutdown: Arc<AtomicBool>) -> Result<(), std::io::Error> {
+        let mut workers = Vec::with_capacity(self.service.config.limits.max_concurrent_requests);
+        for _ in 0..self.service.config.limits.max_concurrent_requests {
+            let listener = Arc::clone(&self.listener);
+            let service = Arc::clone(&self.service);
+            let shutdown = Arc::clone(&shutdown);
+            workers.push(thread::spawn(move || {
+                while !shutdown.load(Ordering::Acquire) {
+                    match listener.recv_timeout(Duration::from_millis(25)) {
+                        Ok(Some(request)) => serve_request(&service, request),
+                        Ok(None) => {}
+                        Err(error) => return Err(error),
+                    }
+                }
+                Ok(())
+            }));
+        }
+        for worker in workers {
+            worker
+                .join()
+                .map_err(|_| std::io::Error::other("HTTP worker panicked"))??;
+        }
+        Ok(())
+    }
+
+    /// Serves until the process is terminated.
+    pub fn serve(&self) -> Result<(), std::io::Error> {
+        self.serve_until(Arc::new(AtomicBool::new(false)))
+    }
+}
+
+fn serve_request(service: &WipFsServer, mut request: tiny_http::Request) {
+    let maximum = service.config.limits.wire.max_request_bytes();
+    let mut body = Vec::new();
+    let read_result = request
+        .as_reader()
+        .take(maximum.saturating_add(1) as u64)
+        .read_to_end(&mut body);
+    let route = service.route(request.url().split('?').next().unwrap_or_default());
+    let response = if read_result.is_err() {
+        empty_response(StatusCode::BAD_REQUEST)
+    } else if body.len() > maximum {
+        route.map_or_else(
+            || empty_response(StatusCode::PAYLOAD_TOO_LARGE),
+            |route| {
+                if route == Route::Batch {
+                    service.batch_top_error(
+                        &resource_error(),
+                        Some(ResourceLimitKind::RepresentationBytes),
+                    )
+                } else {
+                    service.protocol_error(
+                        interaction(route),
+                        &resource_error(),
+                        Some(ResourceLimitKind::RepresentationBytes),
+                    )
+                }
+            },
+        )
+    } else {
+        let mut builder = Request::builder()
+            .method(request.method().as_str())
+            .uri(request.url());
+        for header in request.headers() {
+            if let (Ok(name), Ok(value)) = (
+                http::header::HeaderName::from_bytes(header.field.as_str().as_bytes()),
+                http::HeaderValue::from_bytes(header.value.as_bytes()),
+            ) {
+                builder = builder.header(name, value);
+            }
+        }
+        match builder.body(body) {
+            Ok(request) => service.handle_http(request),
+            Err(_) => empty_response(StatusCode::BAD_REQUEST),
+        }
+    };
+    let status = tiny_http::StatusCode(response.status().as_u16());
+    let mut outgoing =
+        tiny_http::Response::from_data(response.body().clone()).with_status_code(status);
+    for (name, value) in response.headers() {
+        if let Ok(header) = tiny_http::Header::from_bytes(name.as_str(), value.as_bytes()) {
+            outgoing.add_header(header);
+        }
+    }
+    let _ = request.respond(outgoing);
+}
+
+fn interaction(route: Route) -> ProtocolInteraction {
+    match route {
+        Route::Fetch => ProtocolInteraction::Fetch,
+        Route::FetchTree => ProtocolInteraction::FetchTree,
+        Route::FetchInterface => ProtocolInteraction::FetchInterface,
+        Route::CallOperation => ProtocolInteraction::CallOperation,
+        Route::Batch => ProtocolInteraction::Fetch,
+    }
+}
+
+fn resource_error() -> ProtocolError {
+    ProtocolError {
+        code: ProtocolErrorCode::ResourceLimitExceeded,
+        message: "configured resource limit exceeded".into(),
+    }
+}
+
+fn internal_error() -> ProtocolError {
+    ProtocolError {
+        code: ProtocolErrorCode::Internal,
+        message: "filesystem server failed".into(),
+    }
+}
+
+fn empty_response(status: StatusCode) -> Response<Vec<u8>> {
+    Response::builder()
+        .status(status)
+        .body(Vec::new())
+        .expect("static status builds an HTTP response")
+}
+
+/// Failure while validating, opening, or binding the server.
+#[derive(Debug)]
+pub enum ServerBuildError {
+    /// Configuration is unsafe or unbounded.
+    Config(ConfigError),
+    /// The root capability could not be opened.
+    Io(std::io::Error),
+    /// The listener could not be bound.
+    Listener(String),
+}
+
+impl std::fmt::Display for ServerBuildError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Config(error) => write!(formatter, "invalid server configuration: {error}"),
+            Self::Io(error) => write!(formatter, "filesystem root could not be opened: {error}"),
+            Self::Listener(error) => write!(formatter, "HTTP listener could not be bound: {error}"),
+        }
+    }
+}
+
+impl std::error::Error for ServerBuildError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Config(error) => Some(error),
+            Self::Io(error) => Some(error),
+            Self::Listener(_) => None,
+        }
+    }
+}
+
+impl From<ConfigError> for ServerBuildError {
+    fn from(value: ConfigError) -> Self {
+        Self::Config(value)
+    }
+}
+
+impl From<std::io::Error> for ServerBuildError {
+    fn from(value: std::io::Error) -> Self {
+        Self::Io(value)
+    }
+}