Standalone feature-completeness audit

Executive verdict

CONDITIONAL — core feature-complete if the operational assumptions below are accepted. No genuine missing core feature or demonstrated security blocker was identified in the reviewed scope. An operator can configure and run the daemon, connect supported encoded sources and listeners, update metadata, publish independently produced HLS, inspect/control live resources, enforce limits, drain, shut down, and restart.

The condition is substantive: Quikcast is a bounded Unix encoded-audio distribution daemon with a documented client/deployment contract. It does not yet carry a claim of universal HLS player compatibility, arbitrary encoded-media mappings, production capacity, or production qualification. In particular, HLS Range requests return 416 and the successful recorded FFmpeg playback explicitly disables seeking. If a required player cannot use whole-object HLS, that specific requirement must be investigated before declaring completeness for that deployment. No such required-client failure is currently established.

Quikcast distributes continuous encoded audio to continuous listeners, and separately accepts explicitly produced MPEG-TS HLS assets for HLS delivery. Neither subsystem converts into the other. Encoding, decoding, transcoding, remuxing, AutoDJ, databases/accounts, and platform orchestration remain outside its identity.

The 30-area completeness matrix (docs--standalone-completeness-matrix.html) supplies the requested Area / Status / Evidence / Limitation / Action columns, with searchable text and status filtering. Its machine-readable data (evidence--standalone-audit--completeness-matrix.json) uses only the five requested status values. The matrix is an interactive artifact instead of a large Markdown table. A portable canvas source (docs--standalone-completeness-audit.canvas.tsx.zip) contains the same data; this desktop workspace has no discoverable provisioned Cursor canvas directory, so automatic canvas hosting/type diagnostics were unavailable. The HTML matrix is the directly usable companion.

Audit basis and verification

Reviewed ownership and request paths in configuration, authentication, protocol, client identity, source ingest, mounts/generations, ring/media parsing, ICY, listener bodies, socket progress, supervisor, lifecycle, management, metrics/logging, and HLS configuration/budget/store/HTTP/TS validation. Reviewed Cargo dependencies and the milestone/protocol/management/drain documentation and recorded client reports.

Fresh current-tree checks:

• cargo test --locked: 49 unit/property/concurrency tests and 20 transport integration tests passed, zero failures; empty binary/doc-test suites add no coverage.

• cargo fmt --all --check: passed.

• cargo clippy --locked --all-targets --all-features -- -D warnings: passed.

• git diff --check: passed.

• Production sources, Cargo manifests/lockfile, example configuration and test sources were hashed before the checks and compared afterward. See audit evidence (evidence--standalone-audit--validation.json), source manifest (evidence--standalone-audit--source-manifest.json), and test log (evidence--standalone-audit--tests.log).

Test count alone does not establish completeness. The decisive evidence is coverage of wire delivery, failure isolation, resource release, publication races and lifecycle boundaries described below. No new external client, Linux, fuzz, dedicated-host capacity, or advisory-audit run was performed for this audit. Historical results retain their original build identities.

Accepted limitations and deployment assumptions

1. Unix execution and logging. The CLI logger requires Unix and nonregular stdout: pipe, socket, terminal or character device. quikcast > server.log fails startup intentionally. Provide a draining collector. Records are bounded to 4,096 bytes and can be truncated, partially written or dropped; metrics expose loss. Structured tracing fields exist, but JSON logs and durable audit storage are not promised.

2. TLS and administration are external deployment responsibilities. Administration must bind loopback. Health/metrics are unauthenticated there; /api requires its dedicated Bearer token, and HLS producer operations require separate Basic authentication. A remote private proxy must preserve this boundary. Protect source/metadata credentials with TLS or a trusted private path. Do not expose all loopback routes through an unrestricted public proxy.

3. Proxy behavior must fit continuous delivery. Disable upload/response buffering, caching and short live-stream timeouts. An HTTP proxy that rejects SOURCE needs a supported PUT encoder path or TCP pass-through. Quikcast serves HTTP/1, closes finite responses and close-delimits live audio. XFF affects inspection, not authorization. Trust only configured immediate IP/CIDR peers; the proxy must sanitize/append forwarding correctly. Address families, including mapped IPv4, need explicit matching configuration.

4. Static configuration and volatile state. Configuration, limits and credentials change through restart. HLS, listener identities/history, counters and continuous generations are memory/process scoped. Producers repopulate HLS after restart. Operators re-read source state before destructive actions; generation numbers alone are not persistent identities.

5. Supported media subsets. MP3 frame joins cover indexed-bitrate Layer III MPEG-1/2/2.5; MP3 reservoirs can need decoder recovery. AAC joins require supported ADTS headers/channel layout. Ogg supports sequential Vorbis or mono/stereo Opus family 0, including chains, within bounded initialization. No claim of bitstream decoding/validation, arbitrary damaged-stream recovery, free-format MP3, multiplexed Ogg or multichannel Opus.

6. Metadata contract. ICY is MP3/AAC only, negotiated by icy-metadata: 1, at 16,000 audio bytes. Titles are UTF-8, at most 1,024 bytes; control characters and semicolons are rejected. Apostrophes/backslashes remain verbatim based on recorded Icecast behavior. This is not universal escaping/legacy-charset support. Ogg metadata remains in-band producer work.

7. HLS client and producer contract. An upstream producer performs segmentation/muxing and calls the typed ingest/publication API. MPEG-TS whole-object delivery, GET/HEAD, ETag revalidation and configured CORS exist; Range requests receive 416. Recorded successful FFmpeg playback uses -seekable 0 -http_seekable 0 -http_persistent 0. Broad browser/native HLS defaults, live rolling-player sessions and arbitrary producer integration are unproven. End retains final content; deletion/retention/grace and final references govern reclamation.

8. Capacity and drain semantics. Allocation accounting bounds application-owned media, not total RSS/kernel buffers. Size connection, descriptor, proxy and OS headroom. Public/admin connections share the global connection/handshake caps; loopback binding isolates routes but does not reserve operational availability under complete saturation. Pre-routing capacity exhaustion closes TCP; routed admission exhaustion returns 503. Drain is one-way and has no automatic shutdown/resume. Accepted work may finish after drain; existing continuous sessions and HLS reads remain usable. New HLS producer mutations, including end/delete, are blocked after drain admission.

These restrictions do not require a new server feature for the intended scope. They must be accepted rather than hidden behind a generic completeness claim.

Genuine core gaps and security blockers

None identified. There are no CORE_GAP matrix rows and no required implementation proposal. No smallest-fix/architecture/test bundle is applicable without an established defect or unmet core requirement.

The audit found finite bounds and failure paths at each admission/storage boundary. Source credentials are mount scoped; metadata resolves/authenticates the target mount; HLS producer credentials cannot reuse a configured source secret. Management is a separate Bearer scope and fails closed when absent. Management-token equality with source/HLS secrets is not automatically checked: use generated distinct secrets as documented. That operator responsibility is an accepted security limitation, not evidence that the public source route grants management authority.

Authentication content and length use padded constant-time comparison after bounded syntax parsing; parsing itself is not claimed constant-time. Secret types lack Debug output, API models exclude credentials, configuration errors use bounded messages, and reviewed logging does not emit authorization/configuration values. This is source-review evidence, not a penetration-test certification or dependency advisory clearance.

Request targets/headers, metadata queries, JSON/segment bodies, codec staging, registry populations, task populations and upload/mutation concurrency are bounded. Duplicate sensitive headers, conflicting framing, unsupported transfer coding, invalid paths/encoded separators/traversal, unknown configuration fields, oversized uploads and cross-scope credentials fail closed. Trusted forwarding falls back to the socket peer for malformed/untrusted input. Global caps constrain aggregate abuse; they do not guarantee fairness or privileged admin admission during saturation.

If target-player testing establishes a required Range-dependent HLS workflow, record the exact request/player failure, distinguish playlist versus segment behavior, and decide its smallest compatible HTTP change in a later milestone. This audit does not preemptively label optional Range support a core gap.

Operator workflow: all fifteen steps are viable

1. Configure: bounded typed TOML, static canonical mounts, separate machine secrets/files, optional HLS/management, listener limits and explicit trusted proxies. Example config and Config::validate provide the contract.

2. Start: build/run with --config or QUIKCAST_CONFIG; validation, credential/logging setup and binding fail before serving. Use supported stdout handling.

3. Connect an encoder: authenticated raw PUT, framed PUT or narrow raw SOURCE to a configured mount; duplicate ownership rejects, not replaces.

4. Connect listeners: public GET at the mount; correct MIME/station/cache headers, safe late join and optional MP3/AAC ICY. Inactive/uninitialized media can be unavailable.

5. Update track metadata: source-authenticated /admin/metadata?mode=updinfo&mount=...&song=...; clear with empty song. Ogg producers provide comments in-band.

6. Observe source/listeners: authenticated /api/mounts, full-path source detail and per-mount paginated listener collection/detail, plus stats/metrics.

7. Inspect HLS: /api/hls and stream/rendition inspection show generation, revision, publication/window/lifecycle, retained bytes and reservations. HLS may be disabled.

8. Disconnect a listener: DELETE opaque listener resource; cancellation closes the owned transport and lease cleanup releases permits.

9. Disconnect a source: DELETE full-path source resource, optionally guarded by generation; target identity checks prevent killing a successor. Its listeners end with that generation.

10. Enforce listener limits: finite global cap and inherited/overridden per-mount caps, including locally unlimited zero under finite global limits; concurrent admission cannot oversubscribe.

11. Drain: authenticated POST /api/server/drain; stable start time/idempotent response, new continuous admissions and producer mutations reject.

12. Observe readiness removal: /health/ready returns 503, ready metric becomes zero; liveness remains 200 during drain.

13. Keep existing playback: owned continuous sessions, their metadata updates, public HLS reads and native inspection/control continue. HLS live publishers must account for mutation blocking; retained content does not guarantee an indefinitely progressing live playlist.

14. Shut down: SIGINT/SIGTERM trigger cancellation, listener descriptor closure, mount closure, supervised connection joining and timeout/abort fallback; HLS closes after owned tasks finish.

15. Restart with changes: restart restores accepting state and applies configuration; reconnect sources and explicitly republish HLS. This is the supported workflow, not an unsupported reload hack.

Automated tests establish the main resource/control semantics. A combined real-client/proxy rehearsal and actual signal-driven deployment test remain validation tasks, not missing workflow features.

Architectural-quality findings

No material architectural defect requiring a pre-optimization refactor was found. This is a focused code/ownership review, not a formal proof of every interleaving.

• Runtime composes concrete subsystems; it is not one giant shared mutable mutex. Mount admission, listener records, generation ring/title and HLS registry/stream/rendition state have distinct ownership. Dispatch handlers are substantial but delegate domain mutations to existing owners; file size alone does not justify splitting them.

• Raw/framed source adapters share admission, media publication and leases. Separate transport read loops are necessary for EOF versus Hyper framing. The bounded HTTP preface is parsed again by Hyper for ordinary requests; duplicate parsing has a purpose, avoids a second general HTTP server, and is a profiling candidate rather than a correctness defect.

• Drain has one shared one-way lifecycle component. Its two continuous admission checks and one HLS request admission check implement different documented linearization boundaries, not competing shutdown mechanisms.

• Per-connection JoinSet ownership, cancellation, RAII permits and deadline/abort joining prevent abandoned connection tasks. There are no per-chunk spawned tasks or external media subprocesses in production.

• Reviewed production lock scopes do not cross network awaits. HLS body reads occur after guard scopes end; listener polling clones bounded immutable references under synchronous locks. Nested lock ordering follows domain ownership. Management cancellation logs execute under short locks but use the nonblocking bounded sink.

• Collections have explicit bounds: static mounts, global/local admitted listeners, ring byte/entry caps, headers/query fields, Ogg page/init buffers, HLS streams/renditions/segments/retired identities, in-flight uploads and descriptions. HLS retired sequence identities participate in the segment-count bound and are pruned as publication advances.

• No production TODO/FIXME, .unwrap(), .expect(), unsafe block, unnecessary media abstraction/factory or runtime encoder/decoder dependency was found in the scan. unsafe_code = forbid and strict Clippy guard additional regressions. Bounded parser/index arithmetic and arbitrary-byte properties support panic resistance; a clean scan is not proof of panic impossibility.

• Cloning is mainly Arc/Bytes ownership/snapshots, with bounded header/model/index clones. Listener ID generation and snapshot serialization allocate bounded objects. No demonstrated harmful cloning warrants speculative rewrites.

Proposal documents still mention historical platform responsibilities and later ICY/HLS milestones. Those are documentation drift, not evidence of accidental runtime conversion or an unmet feature.

Performance-architecture readiness

Structurally sound: generation-local bounded rings and listener cursors; source append independent of listeners; immutable shared Bytes fanout; one pending body-frame flush gate; bounded rechunking that does not hide arbitrarily large retained backing; independent immutable HLS publications/segments; allocation charges held until final reference; finite connection tasks and nonblocking lossy logs. Media never travels through the management model or a conversion pipeline.

Should fix before optimization: no code/architecture blocker identified. Establish a named baseline and carry compatibility/correctness gates forward. Do not use historical captures or test counts as current performance measurements.

Can wait for profiling: per-generation ring contention and cursor lookup, per-byte MP3/ADTS boundary detection and Ogg CRC, metadata lock/read frequency, 50 ms per-connection monitor ticks, per-listener random ID/allocation overhead, HTTP preface/replay and header parsing, vectored socket response path, bounded HLS registry cloning/sweep/retention work, management snapshot contention and mixed HLS/continuous workloads. Finite HLS responses close connections; the cost deserves measurement against the accepted client contract. None is demonstrated as a bottleneck here.

Do not infer zero-copy from Bytes sharing: ingress/rechunking, parser staging, HTTP processing and kernel transport still copy. Do not introduce custom allocators, unsafe code, io_uring, pools, lock-free rewrites or syscall tuning without profiles. Existing Linux load/resource observations are historical baselines, not a current production listener rating. The reviewed milestones also distinguish payload accounting from allocator/OS RSS and retain failed harness captures instead of treating them as server capacity proof.

Test and evidence map

Manual validation gaps

Before changing behavior based on profiles, capture a repeatable baseline with the chosen build and target versions. Before production qualification, complete the wider deployment sessions below. These are evidence gaps rather than missing product features:

• Repeat sustained BUTT, Liquidsoap and FFmpeg source sessions, metadata change/clear, stop/reconnect and a concurrent healthy listener; record versions, wire results, build/fixture hashes and cleanup. Rerun existing proof harnesses on the selected current build.

• Exercise real target MP3/AAC/Vorbis/Opus players for startup, late join, source loss/reconnect, Ogg chaining and metadata. Add HE-AAC/multichannel or alternate mapping evidence only if actually required.

• Test intended native/browser HLS players against rolling MPEG-TS publication, final ENDLIST, grace/expiry, deletion and drain. Specifically inspect their Range requests/defaults, CORS behavior and recovery. Record any concrete required-client failure.

• Deploy through the intended TLS/proxy path: continuous uploads without buffering, listener delivery without caching, long-lived timeouts, SOURCE/PUT handling, trusted XFF sanitization, private management exposure and health routing.

• Run real playback during drain, confirm new admissions/readiness rejection, existing metadata/control access and HLS producer mutation rejection. Demonstrate that a draining live HLS publisher stops progressing by design, while already retained assets stay playable.

• Use administrative source/listener disconnect against real traffic, verify unrelated clients/mounts survive, accounting/permits clear and reconnect works after cleanup.

• Exercise SIGTERM/SIGINT and restart through the intended service manager/container, including an incomplete upload/stalled peer, stdout collector congestion, changed secrets/configuration and HLS repopulation.

• Qualify descriptor/socket/RSS/CPU headroom, shared admin capacity under saturation, sustained mixed HLS/continuous load and intended machine capacity. A dependency advisory scan is also outstanding from the historical validation package.

The narrow compatibility smoke baseline can accompany profiling setup. Long-duration sessions, security/deployment hardening and dedicated-host ratings belong to production qualification; they need not delay the first observational profile.

Documentation audit and small completion tasks

Required concepts are covered, but distributed: build/start/listener URLs and example TOML in README; ingest methods/metadata behavior in protocol and milestones 2/4; supported codecs/joins in milestone 5; typed producer/public URLs/cache/lifecycle in milestone 6; native endpoints/auth/proxy/limits in management guide; health/drain/shutdown in management/drain/architecture notes.

Coverage is sufficient to perform the workflow without an unsupported feature workaround. It needs operator-facing consolidation:

1. Replace README's RadioPlatform-centered opening with the standalone identity and link this decision. This audit leaves existing documentation wording intact except for its new artifacts.

2. Mark architecture/engineering/protocol/milestone text as proposal or historical evidence wherever it says implemented ICY/HLS/metadata are future work; resolve the proposal's finite keep-alive language against current close-after-response behavior.

3. Create one concise fresh-install/operator runbook linking source/format/metadata/listener/HLS producer/native management examples, limits and all accepted assumptions. Explicitly document the Unix/nonregular stdout requirement, external TLS/private admin/proxy settings, restart state loss and no reserved admin capacity.

4. Publish a current validation/evidence index that separates sealed captures, manual BUTT observations, current automated tests and outstanding production checks. Clarify readiness is process admission rather than source/playback availability and HLS drain blocks future publication.

These are documentation completion tasks and can accompany baseline profiling preparation. They do not warrant another server implementation milestone. No documentation consolidation was silently performed during this audit.

Optional backlog, separate from core completion

Explicit deferred-feature disposition

Continuous relays; fallback mounts; source takeover/replacement; source priorities; automatic failover; mount chaining; master/slave or edge/origin distribution; configuration reload; restart-free token rotation; native TLS; PROXY protocol; operator CLI; additional codecs; additional HLS containers; LL-HLS; persistent listener history; persistent audit storage; and RadioPlatform integration should all remain deferred. No concrete standalone requirement in this audit promotes any of them to core. Additional HLS encryption and full Icecast parity are likewise optional, not hidden prerequisites.

Media conversion, encoding/decoding/transcoding, AutoDJ and platform account/database logic are excluded responsibilities, rather than future core-completion work.

Optimization decision and review gate

Is Quikcast ready to enter performance profiling and optimization? YES, within the explicit supported scope. No missing core implementation or architecture repair blocks measurement. Start with reproducible current-build baseline profiling, source/listener and mixed HLS workloads, lock/allocation/task/socket observations, resource headroom and existing correctness regressions. Refresh target-client smoke evidence and consolidate operator documentation alongside baseline setup. Apply optimizations only when measurements identify a problem; production qualification remains a separate later gate.

Recommended next milestone: performance baseline and profiling, followed by narrowly justified improvements with before/after evidence. Do not implement relays/fallback/takeover or platform integration merely to extend a roadmap. If review rejects one of the accepted assumptions, scope that concrete unmet requirement first.

This milestone stops at the review gate. No optimization or next milestone has begun.

Quikcast standalone core is CONDITIONALLY FEATURE-COMPLETE subject to: Unix execution with a draining nonregular stdout collector; external TLS/private administration and correctly configured live-stream proxies; static restart-based configuration and volatile HLS/state; the documented MP3/AAC/Ogg mappings and ICY restrictions; whole-object MPEG-TS HLS clients that do not require Range; and configured capacity/connection headroom without a production-capacity or universal-client guarantee.