Crate boatramp_core 

Core domain types for boatramp.

• Storage — the streaming-first blob backend trait (filesystem, S3, …). No method buffers a whole object in memory.
• kv — a tiny pluggable kv::KvStore for small deploy metadata, with an LRU kv::CachedKv wrapper.
• deploy — content-addressed, atomically-activated deployments built on top of a Storage (blobs) plus a kv::KvStore (manifests + pointers).
• config — deploy-scoped configuration (the routing section of project.cfg), folded into the manifest; matcher — the shared path-pattern engine it relies on.

Re-exports

pub use error::DeployError;

pub use error::KvError;

pub use error::StorageError;

pub use mode::DeploymentMode;

Modules

access

Visitor access control: HTTP Basic auth, IP allow/deny (CIDR), and rate limiting. These are site-scoped policies — they live in [SiteConfig] (the mutable KV tier) and are evaluated by the server before serving any content.

authz

Control-plane authorization vocabulary and RBAC policy.

blob_notify

Ledger + operator tiers for cloud blob-change notification auto-provisioning (PLAN-faas FA-5b2). The Storage::watch seam (FA-5b1) works zero-config on the filesystem via inotify/FSEvents; cloud object stores need a native notification pipeline (S3→SQS, GCS→Pub/Sub, Azure→Event Grid). Rather than make the operator hand-wire it, boatramp provisions it — “auto-DNS, but for object-store events” — recording what it created in this ledger so it can be retracted on trigger/site removal (mirrors the ManagedDns pattern). This module is the wasm-clean serde surface; the provisioning IO lives behind boatramp_core::blob_provision::WatchProvider.

blob_provision

Cloud blob-change notification provisioning (PLAN-faas FA-5b2) — the IO side of blob_notify. A WatchProvider provisions, verifies, retracts, or describes (dry-run) the native notification pipeline for one cloud object store (S3→SQS, GCS→Pub/Sub, Azure→Event Grid). The ensure_watch orchestrator threads the four operator tiers and records what it created in the managed-notification ledger so it can be retracted later — the same reconcile/retract discipline as auto-DNS.

cache_coherence

Shared-mode cache coherence: a changelog in the shared KV store that lets independent processes invalidate just the keys a peer changed, instead of flushing the world (which thunders the store) or living on TTL desync.

cert

Cluster-managed TLS certificates.

compat

Migration shim: parse Netlify/Cloudflare-Pages-style _redirects and _headers files into boatramp’s Redirect/Rewrite/HeaderRule types, so a site moving to boatramp doesn’t have to hand-rewrite its routing config in project.cfg.

compute

Compute: the wasm-clean workload model (re-exported from boatramp_types::compute) plus the native control-plane layer — the pluggable ComputeBackend trait, the backend-aware scheduler, the selection/isolation policy, and the pure reconcile planner.

config

Deploy-scoped configuration (the routing section of project.cfg).

cron

A standard 5-field cron schedule: parse + does it fire at this time. Used to validate crons config (offline) and to drive the background cron scheduler. Fields are minute hour day-of-month month day-of-week, each a comma list of *, a, a-b, or */n / a-b/n (day-of-week 0 and 7 are both Sunday). Standard “Vixie” day semantics: when both day-of-month and day-of-week are restricted, a tick fires if either matches.

daemon_config

Dynamic daemon configuration — the operational subset of boatramp.cfg promoted into the control-plane KV tier, Raft-replicated, and changeable at runtime without a restart. See PLAN-dynamic-config.

deploy

Content-addressed deployments with atomic activation.

dns_managed

Ledger of DNS records boatramp created on the operator’s behalf, so they can be retracted when a custom domain is detached (domain rm) or its site deleted. Persisted in the control-plane KV under project/<proj>/dnsmanaged/<site>/<host> (project-scoped, 0.2.0).

domain_verify

Domain ownership verification: prove control of a custom hostname before it is attached to a site and becomes eligible for ACME issuance.

email_config

Per-project SMTP email-profile store (sealed password) backing the email guest capability — credentials host-held, config admin-reconfigurable. Project-scoped SMTP email-profile store.

envelope

Envelope encryption for secrets at rest.

error

Error types shared across storage backends, the KV layer, and deploys.

function

The FaaS function model — PLAN-faas FA-1.

gateway

Gateway: publishing a private/internal HTTP service through the edge. The operator declares the backends boatramp may reach (upstreams) and the routes that forward to them; a declared upstream is the trust boundary that authorizes reaching a private address (the SSRF guard stays public-only for everything else).

geo

FA-8 geo-edge: region tagging + nearest-replica selection. The genuinely new mechanism of the geo stage — region-aware placement + routing that extends the gateway’s health/LB replica picker (G5/G6). boatramp does not enumerate regions; a region is an operator-defined tag (us-east, eu-west) that this module only compares. Nearest = same-region-first by default, refined by an optional operator-supplied region-distance table. Pure, backend-free logic, so it is fully unit-testable without live multi-region infrastructure.

host

The Host type: one home for the routing-host normalizations that were scattered across three crates (canon_host in core, canon_domain_entry in the server, normalize_host here) with subtly different — and deliberately distinct — wildcard/case rules that all feed KV keys and DNS record names.

ipam

Per-node guest-IP pool shared by the VMM (tap) + container (veth) backends. IP address management for compute guest interfaces.

kv

A small, pluggable key/value store for deploy metadata.

logs

Wire DTOs for the captured-guest-logs endpoint: one bounded ring of recent stdout/stderr lines plus the per-site rate-cap drop count. The server captures and serializes these; the operator endpoint and the console tail read them back.

matcher

Path-pattern matching for redirects, rewrites, headers, and cache rules.

messaging

boatramp’s internal messaging substrate: durable topics with at-least-once consumer delivery, built on the existing Storage + [kv::KvStore] backends — no external broker.

migrate

Online, resumable migration of a pre-0.2.0 store to the project-scoped layout. The control-plane store migration mechanism: a versioned, ordered registry of forward-only migrations the engine walks to bring a store up to the layout this binary requires.

mode

Deployment mode — the single knob that selects the per-mode coordinator while the guest-facing behavior contract stays identical.

orm

A typed query AST + injection-safe ?N SQL compiler backing the orm handler binding. A typed query AST and an injection-safe SQL compiler — the backing for the orm handler binding (boatramp:handlers/orm).

predicate

A tiny, bounded predicate language for conditional routing — the when clause on a crate::config::Redirect / crate::config::Rewrite.

project

Project scoping for the store: the wire Project types (re-exported from boatramp_types::project) plus ProjectRef, a borrowing newtype threaded as the first argument of every per-name DeployStore method. Using a distinct type (not a bare &str) makes the store-wide scoping change compiler-enforced — you cannot pass a site name where a project is meant — and lets the compiler enumerate every call site during the re-key.

route

Request routing: turn a request path + DeployConfig + the manifest’s file set into an Outcome. Pure and synchronous so it is easy to unit-test; the server turns the outcome into an HTTP response (conditional/range/headers).

secret_store

Project-scoped internal secret store.

security

Operator-scoped security posture (the unifying mechanism for the security hardening). A single resolved set of trust knobs that the server, gateway, handler runtime, and compute scheduler all consult, so the trust model is decided once by the operator rather than scattered across defaults.

session

The duplex/resumable session delivery-semantics model (Stage 1 of PLAN-session-primitive). Session delivery-semantics model — Stage 1 of the duplex/resumable session primitive (PLAN-session-primitive.md). Pure, I/O-free logic so the delivery guarantees are proven in isolation: a monotonic per-session cursor, at-least-once ordered outbound frames retained until the client acks their cursor (resume-from-cursor on reconnect), idempotent inbound dedup over a bounded window, bounded buffers + frame size, and idle-TTL expiry.

site

The SiteName newtype: a site (tenant) identifier, distinct from other string ids — especially a crate::host::Host — so the transposable (site, host) argument pairs that thread through the deploy store become a compile error rather than a silent swap.

sql

A small, engine-agnostic SQL backend contract for the handler sql binding.

target_sql

Host-side parse-and-rewrite confinement of a guest’s raw-SQL target read (R4/D8): the AST-level analog of the orm path’s PerTableTarget per-table confinement, injecting tenant = B AND <public subset> onto EVERY table reference so a target read of another tenant B can reach only B’s declared public rows — the guest cannot reposition or OR-escape it. Host-side parse-and-rewrite confinement of a guest’s raw-SQL target read (R4/D8).

tenancy

In-site tenancy configuration — the declared side of the tenant-isolation model.

time

The one canonical wall-clock read for native crates (now_unix/now_unix_ms). The one canonical wall-clock read.

waf

A small, fully-configurable web-application firewall for the visitor access-control stage. Two independent features, each with its own enable flag and tunables so an operator turns on exactly what they want:

workflow

FA-6 declarative workflow orchestration — a small DAG of function-invocation steps with durable state, retries, fan-in/fan-out barriers, and on-failure compensation. Deliberately not a general workflow/BPMN engine (the PLAN-faas scope guard): a step is one function invocation, edges are depends_on, and the executor advances the DAG on the same KV-durable + scheduler-drain substrate the async invocation queue uses (Raft-replicated in cluster mode).

Structs

BlobChange

A single change event under a watched prefix — a backend-native notification (Storage::watch), never boatramp’s own write path (so the semantics are the same whoever wrote it).

GetObject

The result of a streaming read: object metadata plus its byte stream.

ObjectMeta

Metadata describing a stored object.

PutMeta

Metadata supplied when writing an object.

Enums

BlobChangeKind

How an object under a watched prefix changed (FA-5 blob-change triggers).

ConfigError

Errors from parsing or compiling deploy configuration (crate::config).

Constants

SCHEMA_VERSION

Schema version stamped on every persisted boatramp document (manifests, deploy/site configs, and KV records).

Traits

Storage

A pluggable, streaming object-storage backend.

Functions

schema_version

serde default for the version field on schema types, so documents written before the field existed (or by hand) still read as v1.

Type Aliases

ByteStream

A streaming, owned sequence of byte chunks.

ChangeStream

A stream of change events under a watched prefix, live until dropped.