Native management milestone review gate

Architecture changes

management.rs contains explicit JSON models, authentication/error translation, validation, dispatch, and focused resource handlers. Mounts own generation resolution, identity-checked source cancellation, listener registry snapshots, bounded pagination, and listener cancellation. Source/body/socket ownership stays with the existing supervised tasks and leases. Administration never removes a live record or releases source admission early.

Each listener has a random opaque identity, cancellation token, immutable connection metadata, and shared transport-byte counter. A per-mount ordered registry retains records only through lease lifetime. Listing uses an exclusive range cursor, not an unlimited collection clone. Detail/control search at most the 64 configured mount registries. Existing global and local semaphore permits remain the admission authority, with per-mount overrides and explicit locally unlimited semantics.

Both raw and framed source loops now observe generation cancellation. Source actions capture an owned generation target and compare its identity under admission before closing it. Old cleanup and delayed cancellation cannot mutate a successor. An administrative reason overrides other termination observations in lease accounting. Generation metadata, title, byte counters, and known codec state stay generation-local.

HLS adds read-only typed snapshots, publication/ingest timestamps, and maintained retained-segment-byte accounting. Inspection distinguishes payload retention from reserved allocations and includes grace-period deleted objects. Existing immutable publication/storage and producer controls remain authoritative. No segment data is copied into management responses.

Connection and handshake gauges have scoped RAII cleanup. Statistics read typed atomics and bounded HLS state independently of Prometheus rendering. Structured mutation logs use fixed reason labels, mount, opaque listener ID/source generation, and cancellation result. No new dynamic metric labels are added. Public response identity is Quikcast; the existing streaming framing/cache headers remain intact.

Endpoint and model review

The complete endpoint contracts, query validation, curl examples, success models, errors, side effects, and races are in management-api.md.

There are 13 method/path operations: server/stats/mount list/detail, source GET/DELETE, listener list/detail/DELETE, and four HLS GETs. There is no new API version prefix. Separate source resources support arbitrarily nested configured mount paths without action-name collisions. Listener collection filtering uses an encoded canonical mount query. Existing versioned internal HLS producer routes predate this work and are unchanged.

Models are ServerInfo, AdmissionLimits, Stats, MountInfo, SourceInfo, StationMetadata, TrackInfo, ConnectionInfo, ListenerInfo, ListenerPage, HLS OperationalSummary, StreamInfo, RenditionInfo, and the stable native error envelope. Station declarations, track metadata, and runtime state remain separate. Unknown values are null; no additional media parser was introduced. Ogg codec visibility reuses the existing parser.

Authentication, limits, and proxy behavior

Management uses an optional startup token/token-file configuration. Omission fails closed. Token contents/length compare through fixed padded constant-time comparisons; parsing and file reads are bounded. Documented generation uses 256 random bits encoded as hex. No sessions, users, database, cookies, OAuth, or permission system exists. Health/metrics keep their existing loopback boundary. Remote access requires a private proxy.

Per-mount listener_limit inherits limits.listeners_per_mount when omitted. Zero means unlimited locally; the finite global max_listeners and max_connections still apply. Global/default/local limits validate before binding. Atomic local/global semaphore acquisition prevents concurrent over-admission and needs no global admission mutex. Rejection is deterministic HTTP 503 and increments admission rejection metrics. Mount responses show null for unlimited. Conservative startup audio reservations include the additional operational records.

Trusted proxies are an explicit bounded IP/CIDR list. Only bounded X-Forwarded-For chains from trusted socket peers are considered. Resolution walks trusted hops from right to left; malformed or duplicated chains fall back to the socket address. The exact contract and proxy obligations are documented in the API guide. This affects source/listener inspection only.

Validation added

• Bearer validity, missing/invalid/malformed/oversized values, bounded lengths, duplicate fields, and no secret in server output.

• Mount list/detail, unknown mounts, nested paths, connected/disconnected sources, configured limits, method/query validation, and native error codes.

• Bounded listener pages, exclusive deterministic cursors, invalid page sizes/cursors/duplicate parameters, active detail, unknown/completed detail, disconnects, and duplicate operations.

• Deterministic stale generation regression: capture N, drop N, start N+1, resume N's admin operation, prove N+1 and its listeners survive. Current cancellation then terminates the correct generation.

• Barrier-controlled listener admission near capacity, concurrent duplicate listener cancellation, cancellation racing natural lease drop, ID uniqueness across 500 live records and subsequent replacement, cleanup accounting, and unlimited local semantics.

• HLS stream/rendition list/detail, unknown resources, active/ended states, retained bytes, media sequence, publication revision, and timestamps.

• Direct/trusted/untrusted peers, spoofed leftmost hops, malformed/duplicate headers, multihop resolution, and CIDR validation.

• Real-socket management authentication, per-mount 503 rejection/accounting, forwarding/user-agent/ICY visibility, actual served-byte counters, listener close and permit reuse, source close, generation-safe reconnect control, and framed-source-body cancellation.

• Existing MP3, ADTS, Ogg Vorbis/Opus, ICY, source framing, HLS lifecycle/publication, hostile input, slow consumer, isolation, shutdown, property, and memory-ceiling tests remain in the suite.

Final result: 61 tests passed (44 unit/property/concurrency tests and 17 transport integration tests), with zero failures. Strict Clippy, formatting, and git diff --check passed. The suite contains 12 new tests, plus expanded HLS integration/proxy assertions.

Validation commands: cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test (localhost binding requires an execution environment allowing local sockets). Existing manual BUTT/player sessions were not repeated; compatibility regression evidence here is the existing real media fixtures and transport suite.

Known limitations

• No configuration reload or runtime limit/token mutation. Restart applies static configuration; externally preserve tokens securely.

• Listener pagination is a live view, not a historical or transactionally frozen list. Random IDs are ordered lexically, not by connection time; IDs are probabilistically unique from 128 random bits. Active collisions fail closed.

• Source generations reset across process restarts. External clients should not reuse pre-restart source inspection state for destructive actions.

• Accepted cancellation is asynchronous. Records may briefly show disconnecting before lease cleanup; subsequent duplicate requests return deterministic not-found/no-source.

• Statistics across independent resources are observational rather than atomically consistent. HLS snapshots have bounded registry cost; retained counters avoid per-segment scans.

• Audio properties from headers are producer declarations; MP3/AAC codec follows admitted content type. No new bitrate/sample analysis exists.

• User agents are truncated to 256 characters. Trusted forwarding is IP-only; mapped address families must be configured explicitly.

• Transport errors rejected before routing preserve the existing HTTP error format. API errors after routing use the native JSON envelope.

• Health/metrics remain unauthenticated on a required loopback binding. A proxy that exposes them must establish its own access boundary.

• There is no listener history, persistent audit store, public mount directory, effective configuration endpoint, build revision provenance, or token rotation API.

Remaining standalone feature gaps

Next milestone recommendation

Choose a focused operator workflow review and remaining-feature decision. Exercise native API inspection/cancellation with real encoders, players, and the intended proxy setup; review restart/reload, the implemented drain workflow, TLS boundary, formats, and future relay requirements. Select the next concrete server feature only after that review. Do not automatically enter optimization, relay/fallback/takeover implementation, integration, or production qualification.