boardwalk

A hypermedia server framework for federated services. Boardwalk models addressable things as Resources, drives executable Actors inside a Node, exposes their ResourceSnapshots as discoverable Siren resources over HTTP, multiplexes telemetry over WebSockets, and tunnels HTTP requests back through outbound peer connections so services behind a NAT stay reachable from anywhere else on your fleet.

Boardwalk started as a Rust port of Zetta and is evolving independently from there.

Install

[dependencies]
boardwalk = "0.2"
tokio = { version = "1", features = ["full"] }

Quick start

From this workspace, the LED example is a small resource/actor fixture. It registers an actor, queries it through the runtime handle, invokes a transition, and prints the explicitly published state event.

cargo run -p hello-led

What's in the box

• Resource / Actor runtime — read-only Resources, executable Actors, per-node directories, lifecycle hooks, bounded transition execution, and TransitionOutcome results.
• Resource HTTP routes — /resources, /resources/{id}, and /resources/{id}/transitions/{transition} render Siren around ResourceSnapshot; peer-scoped routes mirror that vocabulary under /servers/{name}/resources.
• Multiplex WebSocket events at /events — subscribe to topics with * / ** / regex patterns, optional ?ql=<caql> filters, explicit actor publishes, and bounded slow-consumer policies.
• CaQL — small query DSL for selecting and projecting resources.
• Job-runner example — runnable Boardwalk HTTP server showing JobQueue / Job resources, async transition acceptance, explicit progress/log/lifecycle streams, replay, and SlowConsumerPolicy::Coalesce.
• Peer tunnel — hub dials cloud via an outbound WebSocket; both sides upgrade to HTTP/2 with reversed roles. The cloud then proxies HTTP and forwards event subscriptions back through the same socket.
• TLS — peer dials use rustls + the OS trust store via rustls-platform-verifier.

Run the example

cargo run --bin hello-led

There's also a tunnel proof-of-concept that drives role-reversed HTTP/2 over an arbitrary duplex stream:

cargo run --bin tunnel-poc

Module layout

The whole library lives in the single boardwalk crate. The Resource/Actor model lives behind a small crate-root facade, with curated runtime, query, caql, and events modules for focused subdomains. The crate root exports the authoring facade: Boardwalk, Resource, Actor, NodeBuilder, ResourceSnapshot, transition metadata, and stream specs. Curated submodules cover focused domains:

Use Boardwalk::new().use_actor(...).listen(...) when you want the supplied HTTP, WebSocket, and peer routes. That builder creates the same actor-backed Node runtime that NodeBuilder exposes for in-process use.

The #[actor] and #[transition] proc macros ship in the separate boardwalk-macros crate (a Rust requirement — proc-macro crates can't live alongside non-macro code) and are re-exported by boardwalk.

Docs

• Getting started — run the Resource/Actor LED example and drive it through /resources.
• Resources and actors — Resource, Actor, Node, ResourceSnapshot, transitions, streams, and the job-runner example.
• Events — multiplex WebSocket and NDJSON event wire protocol.
• Peers — reverse-tunnel hub ↔ cloud setup.
• CaQL — query DSL reference.

License

Apache-2.0. See LICENSE.