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/capabilitiesnegotiates API, schema, storage, pagination, and live transport capabilities.GET /api/v1/recordingreturns the manifest, the last durable cursor, and writeractivity(active,interrupted, orcomplete).interruptedmeans 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. Itsdurable.retained_prefixidentifies rolling-history truncation and the exact first retained/last removed sequence cursors.GET /api/v1/events?after=<sequence>&limit=<count>reads a bounded page;afteris 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.beforeis exclusive and the response'sprevious_cursorcontinues backward paging.afterandbeforeare mutually exclusive. Every page repeatsretained_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 withboundary=<checkpoint-cursor>&after=<next_cursor>whilehas_moreis true; this pins every page to one checkpoint even if the writer publishes a newer sidecar during the request sequence.exactis 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 eitherafteror the standardLast-Event-IDheader.
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 ;
# async
An independently shipped UI can be selected without enabling embedded assets:
use PathBuf;
use ;
# async
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.