dispergo

PRIVATE ALPHA

Runtime server module

Configure the operational listener, control API, health endpoints and shutdown lifecycle.

server

output.http.listener serves media and viewer routes. The runtime listener is configured under server.operational and is usually on the same host with a different port.

FieldDefaultPurpose
server.operational.hostmedia listener hostBind address for API, health and metrics.
server.operational.port9091Must not overlap output.http.listener.
server.shutdownTimeout10sBudget for root component shutdown and selected cleanup phases; not a process-wide termination limit.

Shutdown proceeds through ordered phases. Pull, push, transcode, registry and webhook cleanup have independent deadlines; selected other phases receive a fresh configured budget. Total process termination can take longer than server.shutdownTimeout. Allow for the complete enabled cleanup path when setting the deployment's termination grace period.

The operational listener has no application authentication. Keep it on a trusted network. Enabled routes can start pulls, start pushes and stop streams.

API and health

Method and pathPurpose
GET /livezShallow process liveness.
GET /readyzConfigured components started and shutdown has not begun; this is not per-stream media health.
GET /metricsLow-cardinality Prometheus metrics.
GET /api/v1/featuresRedacted effective capabilities and bounded configuration.
GET /api/v1/streamsActive stream list.
GET /api/v1/streams/{streamId}Identity, tracks, health and module state.
DELETE /api/v1/streams/{streamId}Stop an eligible active stream.
GET /api/v1/capacityAdvisory resource and worker snapshot.
GET /api/v1/pullsManaged source-pull list.
GET, PUT, DELETE /api/v1/pulls/{streamId}One managed source-pull lifecycle.
GET /api/v1/pushesOutbound SRT push list.
GET, PUT, DELETE /api/v1/pushes/{pushId}One outbound push lifecycle.
GET /api/v1/pull-control/capabilitiesProcess incarnation, writer watermark and operation capacity.
PUT /api/v1/pull-control/writerCompare-and-swap the process-wide writer fence.
PUT, GET /api/v1/pull-operations/{operationId}Submit or recover an exact fenced start/stop operation.
GET /api/v1/moqtAggregate enabled MOQT lifecycle, admission and authorization state.
GET /api/v1/moqt/presentationsBounded publisher/relay presentation readiness and delivery counts.

Path identifiers are URL-encoded. Sensitive request data is never added to metric labels. Legacy pull routes remain available, while schedulers recovering lost acknowledgements should use the fenced operation contract. Stream detail can also include independent llHlsState, thumbnailState and latestThumbnail snapshots.

Wall-clock provenance

In GET /api/v1/streams/{streamId}, the stream-detail wallClockProvenance field reports the time source of the node-local active mapping as source, cascade, or server, and is omitted rather than null until the current epoch has a mapping.

source means an explicit UTC-to-media correlation accepted directly from an external source. PCR, PTS, or DTS alone does not establish source. cascade means a usable anchor received from an upstream dispergo node, whether that upstream node used source or its own server fallback. server means the current node's local clock fallback.

The same contract applies to local push, managed source pull, and cascade input, including nodes with no local output or only cascade output. A later accepted usable upstream anchor can change server to cascade in the same epoch. Reset, reconnect, or generation replacement withdraws the old value; the field remains omitted until the new mapping exists. Reading this field never creates a mapping or samples the clock. Clients that accepted legacy origin, source, and edge values must migrate: this is a contract change, not a string rename.

Configuration reference

The configuration document rules apply to every runtime module. The complete field reference covers every accepted option; the maximal composition shows how modules fit together.

Runtime overviewTranscode