dbgflow-server 0.4.0

Live HTTP and SSE server for durable dbgflow recordings.
Documentation

dbgflow-server

Loopback-oriented live API for a native dbgflow recording. The default server package has no frontend dependency. ServerConfig::ui_dir can load an independently built UI even when the crate's ui feature is disabled. Its optional ui feature embeds the dependency-free dbgflow-ui assets on the same origin for zero-configuration local use; an explicit directory takes precedence over that bundle.

External delivery is intentionally a fixed startup contract: index.html, app.js, app.css, and globals.css must all be readable regular files. They are loaded once before binding/building the router. Only those four exact routes are exposed, so request paths cannot traverse or turn the server into a general-purpose file server. Missing or invalid assets fail startup with the offending path in the error. With neither ui_dir nor the ui feature, the server remains API-only.

Routes:

  • GET /api/v1/capabilities negotiates API, schema, storage, pagination, and live transport capabilities.
  • GET /api/v1/recording returns the manifest, the last durable cursor, and writer activity (active, interrupted, or complete). interrupted means the manifest is incomplete but no process holds the persistent writer lock, so clients stop reconnecting and can offer recovery/resume instead of polling forever. Its durable.retained_prefix identifies rolling-history truncation and the exact first retained/last removed sequence cursors.
  • GET /api/v1/events?after=<sequence>&limit=<count> reads a bounded page; after is exclusive. Both event count and estimated serialized response bytes are bounded before payloads are retained or base64-encoded. A single event larger than the configured budget returns HTTP 413.
  • GET /api/v1/events?before=<sequence>&limit=<count> efficiently reads the immediately preceding page in ascending sequence order. before is exclusive and the response's previous_cursor continues backward paging. after and before are mutually exclusive. Every page repeats retained_prefix, so deep-history clients can distinguish the durable retention boundary from the recording's natural beginning.
  • GET /api/v1/replay?cursor=<sequence>&limit=<count> returns the nearest compatible typed projection checkpoint at or before the requested cursor and a byte/count-bounded canonical delta page. Continue with boundary=<checkpoint-cursor>&after=<next_cursor> while has_more is true; this pins every page to one checkpoint even if the writer publishes a newer sidecar during the request sequence. exact is true only when the checkpoint has exact bounded known topology and active-span boundary state and every delta through the resolved durable cursor is present. It does not claim that arbitrary old application values are embedded in the checkpoint; those remain available from canonical history. Corruption, unsupported sidecars, gaps, and retention boundaries remain explicit.
  • GET /api/v1/live?after=<sequence> follows durable history over SSE. A reconnect may use either after or the standard Last-Event-ID header.

All sequence values and other 64-bit IDs are decimal strings in JSON so they remain exact in JavaScript. SSE messages use dbgflow.event and dbgflow.gap, with the durable sequence as their id. The API advertises synced_frames: one lazy tailer per router reads immutable chunks plus the writer's synced, checksummed active prefix and publishes each new envelope once into a shared count-and-byte-bounded fanout. Its stateful durable-tail reader resumes at the last decoded byte offset, so unchanged polls do not rescan chunk directories or historical frames. Clients subscribe before a bounded history catch-up, then deduplicate by sequence while switching to the shared stream. A lagged client is disconnected so browser EventSource reconnects from its real Last-Event-ID; lag is never represented as a persisted dbgflow.gap. Slow or disconnected browsers cannot block the recording writer or multiply storage polling. Periodic visibility does not create a new chunk.

When rolling retention has removed the requested prefix, SSE first sends a dbgflow.retention JSON notice containing decimal-string first_cursor and removed_through_cursor. The notice deliberately has no SSE id: it describes transport state rather than a persisted EventEnvelope, cannot be confused with a recorded gap, and does not corrupt browser Last-Event-ID reconnect progress. The first retained event then advances the normal durable cursor.

live_buffer_events and live_buffer_bytes bound the shared tail. Per-client catch-up pages are further capped at 64 events and 1 MiB, preventing both a full-window clone per slow client and one disk scan per historical event. A single larger event may use up to the configured live_buffer_bytes so a permitted event cannot permanently stall reconnect progress. LiveDiagnostics exposes tailer starts, storage polls, catch-up reads, publication count, active subscribers, directory scans, reinitializations and decoded tail frames without changing the HTTP wire API.

On the checked-in 10,000-chunk benchmark, the underlying stateful empty poll measured about 17.1 µs versus 22.27 ms for the previous stateless read_after loop, after a one-time reader-open cost of about 194.6 ms. Results are local baselines; the important contract is one initialization scan followed by O(new chunks + new events) work.

use dbgflow_server::{Server, ServerConfig};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let server = Server::bind(ServerConfig::default(), "run.dbgflow").await?;
println!("listening on http://{}", server.local_addr());
let handle = server.spawn();
// Application shutdown path:
handle.shutdown().await?;
# Ok(())
# }

An independently shipped UI can be selected without enabling embedded assets:

use std::path::PathBuf;
use dbgflow_server::{Server, ServerConfig};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let server = Server::bind(
    ServerConfig {
        ui_dir: Some(PathBuf::from("dist/dbgflow-ui")),
        ..ServerConfig::default()
    },
    "run.dbgflow",
).await?;
# Ok(())
# }

The default address is 127.0.0.1:0. Non-loopback bind addresses are rejected; remote exposure should be an explicit responsibility of a reverse proxy or a future authenticated transport.

Requests must carry exactly one Host naming localhost, 127.0.0.1, or [::1] with the listener's actual port. Other authorities are rejected to prevent DNS-rebinding access to the local API. API and UI responses include a Content Security Policy plus nosniff, frame, referrer, permissions, and cross-origin policy headers. The CSP retains inline script/style support needed by the current embedded UI while restricting network access to the same origin.

ServerHandle::shutdown broadcasts graceful shutdown and awaits the listener. Dropping a handle also signals shutdown and aborts its listener task, so an accidentally forgotten handle cannot leave a detached local server running.