# 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.
```rust,no_run
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:
```rust,no_run
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.