Crate boatramp_server 

boatramp HTTP server + publishing API.

The server is backend-agnostic: it is handed a DeployStore (blobs in any boatramp_core::Storage, metadata in any boatramp_core::kv::KvStore) and exposes:

• a publishing API used by boatramp sync — negotiate a manifest, upload missing blobs (streamed), then atomically activate;
• public serving of the currently-active deployment for each site.

Every byte path streams: uploads flow request→backend, downloads flow backend→response, and only small manifests are ever held in memory.

Modules

envelope

Secrets-at-rest envelope backends.

signer

External token signer backends: KMS / HSM / Vault-hosted control-plane root keys behind the boatramp_core::cose::Signer seam. External Signer backends for the control-plane token issuer.

sql_shim

The compute sql-shim (PLAN-compute-bindings, Phase 0).

Structs

Auth

Control-plane auth configuration: the token trust anchor (root public key) plus the KV that holds the RBAC policy (authz/policy) and revocation markers (authz/revoked/<id>). None ⇒ auth disabled (development).

CapabilityFeature

Capability-surface types (boatramp capabilities / /api/capabilities). Ungated — a build without handlers still names the vocabulary, it just implements nothing. A capability feature this host implements, paired with its stability. The name is the token a guest names in its manifest requires; admission checks the name, and boatramp capabilities shows the name + lifecycle so operators can see what’s settled vs. provisional.

DaemonRuntime

FastServe

The serve fast path (hot-path bypass): the dependencies the axum router’s Extension layers hold, cloned so RouterHandler can call [serve_by_host_inner] directly for a plain site GET/HEAD — skipping the axum Router + middleware future-composition tax (~15–20% of per-core CPU, profiled) — while every security check still runs inside serve_by_host_inner. Non-eligible requests fall through to the full router unchanged.

HandlerRuntime

The WebAssembly handler runtime: the shared engine plus the per-site binding backends. Cheap to clone (it is an Arc inside). Without the handlers feature it is an empty placeholder, so the serving signatures stay uniform — pass HandlerRuntime::disabled.

MeshMember

One node’s Raft membership, reported by GET /api/cluster/members.

ReloadableTls

A rustls ServerConfig the accept loop reads afresh per connection, so a background task (ACME renewal) can hot-swap the served certificate without a restart — the same capability axum_server’s RustlsConfig gave us. Reads are a single lock-free atomic load (ArcSwap).

RequestId

A per-request correlation id assigned by the access-log layer and readable downstream via the request extensions — the handler dispatch tags captured guest logs with it, so a guest line correlates with its boatramp::access line. Public so an embedder (or a test) can seed its own id into the request extensions.

ServeInput

A Router plus the optional hot-path handle, flowed through the serve loops as one unit. A bare Router converts in with no fast path (From<Router>), so auxiliary listeners (the :80 HTTP→HTTPS redirect, ACME challenge) are unchanged; the main site listeners pass (router, fast) (via From<(Router, FastServe)>) to enable the bypass. Cheap to clone (an Arc-y Router clone + an Option).

ServerLimits

Server-tier upload limits. All None = unlimited (the default; preserves the unbounded streaming behavior for operators who front boatramp with their own limits).

ServerMetrics

Always-on HTTP + lifecycle counters. Request cells are keyed by (status_class, cache_result); the rest are scalar totals.

ServerOptions

Server runtime knobs that aren’t part of the core (deploy, auth, handlers) triple: operational request limits and an optional custom domain-ownership DomainProbe (defaults to the live network probe).

UploadGuard

Runtime guard built from ServerLimits, shared across requests as an axum extension. Holds the concurrency semaphore (if any) and the per-upload caps.

Enums

JoinOutcome

The result of a join admission (MeshControl::admit).

Lifecycle

Capability-surface types (boatramp capabilities / /api/capabilities). Ungated — a build without handlers still names the vocabulary, it just implements nothing. The stability of a capability feature — an honest, present-tense signal to operators and guest authors, and the seam the future deprecation clock extends (a deprecated capability is just this with a removal target). Experimental = new or off-by-default surface whose shape or behaviour may still change; Stable = safe to build on. Not a quality judgement — a stable capability isn’t “better”, it’s settled.

ServeError

A failure starting or running the HTTP server.

Traits

MeshControl

The cluster mesh control operations exposed to the control-plane API, implemented by the cluster runtime over ClusterNode; None on a non-cluster node (the routes then return 501).

Functions

alpn_h1_h2

The ALPN protocols our HTTPS listeners advertise, in server-preference order: HTTP/2 first, then HTTP/1.1. (serve_connection also sniffs the h2 preface, so a client that negotiates neither still gets the right codec — ALPN is the fast path, the sniff is the backstop.)

config_baseline

The daemon-config file baseline derived from ServerOptions (the resolved boatramp.cfg). serve uses this to build a DaemonRuntime it can wake on SIGHUP/changelog; the posture’s upload cap is the ceiling a dynamic override may not exceed.

http_redirect_router

A standalone router for a plain :80 listener that permanently redirects every request to its HTTPS equivalent. Bound alongside the HTTPS listener so plain-HTTP visitors are upgraded even when boatramp terminates TLS itself.

require_auth

Axum middleware enforcing control-plane auth on the routes it wraps.

router

Build the application router around a DeployStore, Auth config, and the WebAssembly handler runtime (HandlerRuntime::disabled for none), with default ServerOptions (unlimited, live probe).

router_with

router with explicit ServerOptions — lets a caller set request limits or inject a custom domain-ownership probe. Returns just the axum Router; the serve loop uses router_with_fast to also obtain the hot-path handle.

router_with_fast

Like router_with but also returns the FastServe hot-path handle, so the serve loop can dispatch eligible requests directly to serve_by_host and bypass the axum router/middleware composition tax. The handle is opaque; a caller only passes it (with the router) into a serve loop (serve_tls / serve_plaintext / the splice loop) via ServeInput.

serve

Bind addr and serve until a shutdown signal (Ctrl-C / SIGTERM), then drain in-flight requests under [DRAIN_DEADLINE]. Default ServerOptions.

serve_plaintext

Serve plaintext HTTP on addr through the unified dispatcher (h1, or h2c via the preface sniff), bridged into router. Used by the :80 HTTP→HTTPS redirect listener. Returns once shutdown resolves, after a bounded drain.

serve_plaintext_listener

serve_plaintext on an already-bound TcpListener (see serve_tls_listener).

serve_router_conn

Serve one accepted connection (plaintext or already-TLS-terminated) by driving it through the unified boatramp_http::serve_connection dispatcher, bridged into router. A clean close is silent; an unexpected IO error is logged at debug. Generic over the IO so a raw TcpStream, a rewound stream, or a TlsStream all serve identically.

serve_tls

Serve HTTPS on addr: accept TCP, terminate TLS with the (reloadable) rustls config, and drive the negotiated protocol through serve_router_conn. An ACME acme-tls/1 challenge handshake completes and is dropped (it carries no request). Returns once shutdown resolves, after a bounded drain of in-flight connections. The config SHOULD advertise ALPN h2/http/1.1 (alpn_h1_h2); an ACME config additionally carries acme-tls/1.

serve_tls_listener

serve_tls on an already-bound TcpListener — for callers that must learn the bound port first (an ephemeral :0 bind) or that inherit the socket (systemd activation, tests).

serve_with

serve with explicit ServerOptions (e.g. operational request limits).

server_metrics

The process-wide ServerMetrics. Cheap to call (no allocation).

shutdown_signal

Resolve when the process receives Ctrl-C or SIGTERM, so in-flight requests can drain before exit.

spawn_compute_reconcile

Spawn the leader-gated compute reconcile loop: every tick, while is_leader(), run one [reconcile_once] pass over the backend registry + node inventory to converge each workload’s replicas. A no-op while not leader or with an empty registry. Detached for the server’s lifetime; the same leader-gating pattern as cron/cert issuance.

spawn_domain_verify_reconcile

Spawn the domain-verification auto-complete reconcile loop: every tick, on the leader, re-check all pending challenges and attach any that now pass — so a challenge whose HTTP/DNS token is published (e.g. by domain add --provider) but never finished with domain verify self-heals with no operator action, and no persistent background daemon is needed beyond this tick. Mirrors crate::spawn_compute_reconcile; the leader gate makes it a single-writer in a cluster.

verification_pending_page

The “verification pending” holding page — an HTTP 421 Misdirected Request served for a non-local Host that isn’t a verified, attached virtualhost (DV-2’s mandatory-verification gate). It looks up any pending challenge for the host to show the exact token / record + path; otherwise it shows generic guidance. Self-contained HTML (no JS, no external assets) — safe on an unverified host.

Type Aliases

CronLeaderGate

Predicate gating cron firing to the cluster leader (see [HandlerRuntime::set_cron_leader_gate]).