Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture Overview

boatramp is a Rust workspace of feature-gated crates that compose into one binary:

CrateResponsibility
boatramp-coreDomain types, the streaming Storage trait, the pluggable KvStore, content-addressed deploys, routing, config, access/WAF, messaging. No runtime/engine.
boatramp-storageBackends: FsStorage, S3, SlateDB KV, Cloudflare KV, libsql SQL.
boatramp-serverThe axum HTTP server: serving pipeline, control-plane API, auth, limits.
boatramp-handlersThe wasmtime engine + host bindings for Wasm components.
boatramp-acmeACME (incl. DNS-01) + the DnsProvider abstraction.
boatramp-clusteropenraft integration: RaftKv, RaftMessaging, persistence, membership.
boatramp-firecrackerThe microVM compute backend: an embedded rust-vmm VMM and an external-Firecracker driver, with snapshot/restore.
boatramp-containerThe container compute backend: a jailed worker with namespaces, cgroups, and a seccomp filter.
boatramp-dockerThe remote-Docker compute backend.
boatramp-cloudflareThe Cloudflare Containers compute backend + edge-Worker generator.
boatrampThe CLI (serve, sync, domain, …) and deploy generators.

The ComputeBackend trait, scheduler, and reconcile loop live in boatramp-core::compute; each backend above is a separate, capability-detected crate. See Compute: handlers vs containers vs microVMs.

Two kinds of data

boatramp keeps two very different things apart, so nothing is ever buffered whole in memory:

  • Blobs — file contents — stream through a Storage backend (fs / S3 / R2), content-addressed by SHA-256.
  • Metadata — small, read on every request — lives in a KvStore (deploy manifests, the per-site current pointer, site config, tokens, certs).

See Storage & KV and the KV Keyspace.

The request pipeline

One ordered pipeline, each stage driven by config:

  1. Host → site (virtualhost), with an optional default site.
  2. TLS / transport — HTTPS redirect + HSTS (proxy-aware via X-Forwarded-Proto).
  3. Access control — WAF → IP rules → rate limit → basic auth.
  4. Path normalization — clean URLs, trailing-slash policy, dot-segment collapsing (traversal-safe).
  5. Redirects, then handlers, then rewrites / SPA / reverse-proxy.
  6. Resolve to a manifest entry (directory index, custom error documents).
  7. HTTP correctness — conditional 304, Range/206, ETag, headers, Cache-Control, compression negotiation.

The routing logic (steps 4–7) is pure and lives in boatramp_core::route, so it is unit-tested in isolation — and reused by the Cloudflare edge Worker, so the edge and the origin route identically.

Deployment modes, one UX

The same commands and config run on a single node, a self-hosted Raft cluster, or Cloudflare Containers. Environment differences hide behind the Storage / KvStore / Messaging trait seams, not in the UX. See Deployment topologies.