Quikcast remaining-feature roadmap and review gate
Date: 2026-10-07. Original status: PROPOSED — roadmap approval required before implementation.
Execution update: the user subsequently approved starting Phase A. Its implementation and checks are recorded in the continuous relay milestone review. This document preserves the original scope/sequence decision; Feature freeze was declared on 2026-10-08; comprehensive manual validation remains pending, keeping profiling/optimization blocked.
Fallback milestone update — 2026-10-08
The user explicitly selected internal admission-time fallback mounts with bounded chaining. This is now implemented; the completion review supersedes the historical fallback/redirect and chaining recommendations below. Primary restoration affects new requests; existing listeners remain generation-bound. Source takeover, priorities, live migration/failback and HLS fallback remain deferred. The next feature recommendation is a separately reviewed takeover policy; no follow-on implementation is authorized by completion of fallback. Manual player validation and the optimization gate remain applicable.
Ogg FLAC milestone update — 2026-10-08
Ogg FLAC mapping 1.0 is implemented through the existing bounded Ogg parser/fanout. The completion review records mapping/header validation, shared STREAMINFO parsing, page preservation, late joins, same-codec chains, decoder evidence and tests. Native audio/flac remains a separate mapping. Server capabilities distinguish flac (native) from ogg-flac.
The next work is manual BUTT 1.46 validation, then the broader operator/client validation and freeze review. GUI/audio-device probing could not establish a usable BUTT test session, so direct interoperability remains an explicit gap. FFmpeg also cannot continuously decode chains that switch bit depth; supported server transport and tested player behavior are documented separately. No subsequent codec, relay, platform or optimization milestone is started. Profiling/optimization remains blocked on accepted scope and satisfactory manual validation; the deferred backlog below remains deferred.
Native FLAC milestone update — 2026-10-08
The user explicitly selected native FLAC continuous streaming after the relay milestone. Implementation, bounds, tests, encoder/decode evidence and limitations are recorded in the native FLAC completion review. Supported continuous source formats now include native audio/flac alongside MP3, AAC ADTS, Ogg Vorbis and Ogg Opus. Existing relay compatibility remains MP3/AAC/Vorbis/Opus.
The remaining sequence is operator/client validation and an updated freeze review covering native FLAC, followed by profiling/optimization only after satisfactory manual validation and explicit scope acceptance. Liquidsoap native-source validation remains an environment-dependent follow-up; Ogg FLAC, FLAC relays/HLS, fallback/takeover, reload/rotation, inbound TLS/PROXY and RadioPlatform integration remain deferred. No further implementation milestone is started by this completion.
The original proposal below is retained as historical context; its “exactly one next implementation milestone” identifies the prior relay decision, not an instruction to implement another relay milestone.
Recommendation and scope
Finish bounded continuous relays, including their metadata, reconnect policy, lifecycle, and native operator visibility, before declaring feature freeze. Keep fallback, source replacement, and automatic failover outside this freeze unless an actual workflow is selected and its semantics explicitly approved. Existing standalone capabilities plus this one cohesive feature group form the proposed freeze scope.
This report supersedes the next-milestone and optimization recommendations in the standalone completeness audit, including its recommendation to begin performance profiling. It preserves that audit's conditional core-completeness findings and deployment limitations. A complete existing core is not approval to optimize before finishing the newly selected feature scope.
This milestone produces review documentation only. It does not implement relays, change APIs/configuration, refactor the engine, run benchmarks, profile, tune, or qualify production capacity. Ratings below are engineering judgments based on the current working tree, not measured performance or engineering-hour estimates. Approval of this roadmap is a future gate, not inferred from this report.
Quikcast remains a standalone encoded-audio distribution server. Its permanent media boundary is:
No crossing between those paths. No encoder, decoder, transcoder, AutoDJ, media conversion, runtime FFmpeg/media subprocess, or platform orchestration is introduced.
Current implementation: what the roadmap builds on
Source ingest (src--ingest.rs) has raw and framed encoder adapters. Both claim an existing mount, start a source lease, publish encoded bytes, and observe generation/shutdown cancellation.
Mount ownership (src--mounts.rs) already provides
Mount::claim,SourceLease::start/publish/finish, generation-local rings and track state, bounded listener admission, and identity-checked cancellation. A duplicate source is rejected. Listeners belong to one generation; disconnecting it ends those sessions. Reconnect does not transparently migrate listeners.Source metadata normalization (src--protocol.rs) currently maps selected encoder
ice-*headers into listenericy-*headers. A relay receives listener-response headers, so it needs its own allowlisted adapter; passing the remote headers through the encoder parser unchanged would lose useful station fields.ICY (src--icy.rs) provides bounded local title serialization and source-authenticated metadata updates. It is not an upstream ICY demultiplexer. Local MP3/AAC listeners negotiate metadata at a 16,000-audio-byte interval. Titles are UTF-8, at most 1,024 bytes, with control characters and semicolons rejected. Ogg metadata remains in-band.
Configuration (src--config.rs) is static, with at most 64 configured continuous mounts, checked retained-generation/media budgets, and restart-based secrets/limits. Lifecycle (src--lifecycle.rs) has one-way drain admission. Native management already inspects and cancels sources/listeners and inspects HLS.
Cargo dependencies (Cargo.toml) currently enable Hyper server functionality, not a complete outbound HTTP/TLS relay stack. A bounded maintained HTTP client and outbound certificate-validating TLS are implementation dependencies to select later. They do not imply native inbound TLS.
HLS already serves independently produced MPEG-TS whole objects with GET/HEAD, ETags, and configured CORS. Range returns 416. The audit establishes no concrete required-player failure, but broad target-player validation remains outstanding.
The README still opens with a RadioPlatform-centered description. Updating that wording and consolidating an operator runbook are documentation work for the selected scope; they do not authorize integration or an architecture change. Existing audit results are historical evidence. No new runtime test result is claimed here.
Remaining inventory and decision table
IMPLEMENT BEFORE OPTIMIZATION means proposed mandatory freeze scope. OPTIONAL means useful but not a freeze blocker; select it explicitly before implementation. IMPLEMENT LATER means outside this freeze, subject to a concrete requirement and a separate scope decision. REJECT means excluded from the standalone runtime or current project direction; an external tool may still provide that capability.
Value is likely operational value for the described standalone scope. A HIGH value does not make an unspecified policy feature mandatory. Complexity includes implementation/integration effort. Risk is shown independently as P protocol, C concurrency, M incremental memory/resource impact, and T test burden; every dimension uses LOW / MEDIUM / HIGH. Memory/resource impact describes the difficulty of bounding new connections, tasks, buffers, or retained state, not an RSS prediction. Dependencies are approval requirements or concrete technical prerequisites, not instructions to build speculative abstractions.
Phases: A selected relay feature group; B optional tooling/documentation closure and compatibility decisions; C feature-freeze review; L later expansion after optimization and deployment evidence; — rejected. The sequence and validation gates follow the table.
Feature | Decision | Value | Dependencies | Complexity | Risk | Recommended phase |
|---|---|---|---|---|---|---|
Continuous relays: URL/auth, format, ownership, lifecycle | IMPLEMENT BEFORE OPTIMIZATION | HIGH | Static relay-to-mount mapping; outbound HTTP/HTTPS client; existing source lease; bounded egress/task budget | HIGH | P HIGH; C MEDIUM; M MEDIUM; T HIGH | A |
Relay station/track metadata | IMPLEMENT BEFORE OPTIMIZATION | HIGH | Relay response validation; bounded ICY demultiplexer; existing generation/title state | MEDIUM | P HIGH; C MEDIUM; M LOW; T HIGH | A |
Relay retry/backoff and deadlines | IMPLEMENT BEFORE OPTIMIZATION | HIGH | One supervisor per relay; cancellation; monotonic timers; drain admission | MEDIUM | P MEDIUM; C HIGH; M LOW; T HIGH | A |
Relay visibility, statistics, stop/reconnect | IMPLEMENT BEFORE OPTIMIZATION | HIGH | Relay state owner; management Bearer scope; generation-safe commands; bounded errors/counters | MEDIUM | P LOW; C HIGH; M LOW; T MEDIUM | A |
Fallback mounts | IMPLEMENT LATER | HIGH | Explicit approval of listener routing semantics; mount availability; target-player redirect behavior | MEDIUM | P MEDIUM; C MEDIUM; M LOW; T HIGH | L |
Controlled source takeover/replacement | IMPLEMENT LATER | MEDIUM | Concrete workflow; approved priority/auth/ownership policy; continuity and resume contract | HIGH | P HIGH; C HIGH; M HIGH; T HIGH | L |
Source priorities | IMPLEMENT LATER | MEDIUM | Selected takeover workflow; credential-scoped producer identity; explicit priority/state model | MEDIUM | P LOW; C HIGH; M MEDIUM; T HIGH | L, before takeover activation |
Automatic failover | IMPLEMENT LATER | MEDIUM | Approved fallback/takeover model as applicable; health trigger, hysteresis and return policy | HIGH | P MEDIUM; C HIGH; M MEDIUM; T HIGH | L, after source policy |
Mount chaining | OPTIONAL | LOW | A demonstrated multi-fallback need; approved fallback; deterministic cycle/depth validation | MEDIUM | P LOW; C MEDIUM; M LOW; T MEDIUM | L, only after fallback |
Ordinary Quikcast origin/edge distribution | IMPLEMENT LATER | MEDIUM | Working relays; explicit topology; loop prevention by configuration; deployment evidence | LOW | P LOW; C LOW; M MEDIUM; T MEDIUM | L, reuse A |
General runtime configuration reload | IMPLEMENT LATER | MEDIUM | Field-specific mutation ownership; validation/commit boundary; removal/drain semantics | HIGH | P LOW; C HIGH; M MEDIUM; T HIGH | L |
Restart-free credential rotation | IMPLEMENT LATER | MEDIUM | Separate immutable credential snapshots; per-scope overlap/revocation and active-session policy | MEDIUM | P MEDIUM; C HIGH; M LOW; T HIGH | L; no generic reload prerequisite |
Native inbound TLS | IMPLEMENT LATER | LOW | A direct-public deployment requirement; cert lifecycle/rotation; separate private admin binding | MEDIUM | P HIGH; C MEDIUM; M MEDIUM; T HIGH | L |
PROXY protocol | IMPLEMENT LATER | LOW | Concrete L4 proxy requirement; trusted peers; strict pre-HTTP subset and timeout policy | MEDIUM | P HIGH; C LOW; M LOW; T HIGH | L |
HLS Range requests | OPTIONAL | MEDIUM | Recorded required-player failure; approved byte-range subset; retention/body-accounting semantics | MEDIUM | P HIGH; C MEDIUM; M LOW; T HIGH | B decision; implement before C only if required |
HLS fMP4/CMAF assets | IMPLEMENT LATER | LOW | Concrete producer/player contract; bounded init-object and container validation; publication/reference rules | HIGH | P HIGH; C MEDIUM; M MEDIUM; T HIGH | L |
Raw AAC HLS assets | IMPLEMENT LATER | LOW | Concrete client/producer requirement; separate asset validation and playlist contract | MEDIUM | P HIGH; C LOW; M LOW; T HIGH | L |
LL-HLS | IMPLEMENT LATER | LOW | Required low-latency workflow; selected asset contract; parts, blocking reload and retention budgets | HIGH | P HIGH; C HIGH; M HIGH; T HIGH | L |
HLS encryption support | IMPLEMENT LATER | LOW | Explicit threat/producer/player contract; key delivery/auth/lifetime and logging policy | HIGH | P HIGH; C MEDIUM; M MEDIUM; T HIGH | L |
Persistent/disk-backed HLS storage | IMPLEMENT LATER | LOW | Actual restart-retention need; object/index recovery, quotas, cleanup and publication durability | HIGH | P MEDIUM; C HIGH; M HIGH; T HIGH | L |
Additional continuous codecs/mappings | IMPLEMENT LATER | LOW | Named source/player need; parser bounds; safe late join; MIME and metadata contract | HIGH | P HIGH; C MEDIUM; M MEDIUM; T HIGH | L |
Small operator CLI consuming /api | OPTIONAL | MEDIUM | Stable native API; safe token handling; generation-guarded mutation; relay endpoints if included | LOW | P LOW; C LOW; M LOW; T MEDIUM | B if explicitly selected, otherwise L |
Fresh-install/runbook and standalone wording | IMPLEMENT BEFORE OPTIMIZATION | HIGH | Final relay contract; existing source/HLS/API and deployment limitations | LOW | P LOW; C LOW; M LOW; T LOW | B |
Deployment examples/service packaging | OPTIONAL | MEDIUM | Named service manager/proxy; existing private-admin, logging and long-stream contract | LOW | P LOW; C LOW; M LOW; T MEDIUM | B if selected, otherwise L |
Persistent listener history in the core | REJECT | LOW | A future concrete need would require a new scope decision; external analytics can consume observations | HIGH | P LOW; C HIGH; M HIGH; T HIGH | — |
Persistent embedded audit storage | REJECT | LOW | A concrete audit/compliance requirement would require a new scope decision; external log collector owns retention | MEDIUM | P LOW; C MEDIUM; M HIGH; T HIGH | — |
Database-backed listeners, generations, counters/runtime state | REJECT | LOW | No established persistence requirement; reconnect/repopulation already define restart recovery | HIGH | P MEDIUM; C HIGH; M HIGH; T HIGH | — |
Public station directory/discovery | REJECT | LOW | Higher-layer discovery requirement belongs in an external application | MEDIUM | P MEDIUM; C MEDIUM; M MEDIUM; T MEDIUM | — |
Narrow encoder/player/relay compatibility fix | OPTIONAL | MEDIUM | Reproducible target failure; bounded wire contract and regression fixture | MEDIUM | P HIGH; C MEDIUM; M LOW; T HIGH | B if required for selected scope |
Broad Icecast compatibility/parity | REJECT | LOW | No demonstrated client need; only narrow evidence-driven compatibility is eligible | HIGH | P HIGH; C MEDIUM; M MEDIUM; T HIGH | — |
Clustering/distributed coordination | REJECT | LOW | No requirement beyond ordinary relay topology | HIGH | P HIGH; C HIGH; M HIGH; T HIGH | — |
RadioPlatform integration | REJECT | LOW for this milestone | Standalone completion, manual validation, optimization/hardening must precede any separately approved integration | HIGH | P MEDIUM; C HIGH; M HIGH; T HIGH | — |
Encoding/decoding/transcoding/AutoDJ or continuous ↔ HLS bridging | REJECT | Outside identity | Conflicts with permanent media boundary | HIGH | P HIGH; C HIGH; M HIGH; T HIGH | — |
Complexity/risk for rejected items describes the likely cost if brought into the runtime; it is not a proposal to design them. Optional compatibility work promoted by a required-client failure must have its scope approved before implementation. No optional row silently becomes mandatory.
Core, optional, deferred and rejected scope
Must finish before optimization: the existing standalone engine; the complete Phase A relay group; standalone identity/runbook updates; correctness checks for the chosen scope; and the feature-freeze review. Metadata, backoff, bounds, ownership, and operator stop behavior are parts of relay completeness, not later upgrades to an unreliable relay MVP.
Nice to have before optimization: the small /api CLI and deployment examples. Range or narrow compatibility changes are conditional options, not convenience requirements. If target validation demonstrates a blocker, make an explicit scope decision and close it before profiling. Unselected optional tooling does not delay freeze.
Later expansion: fallback, takeover/priorities, automatic failover, optional bounded chaining, origin/edge deployment packaging, reload, rotation, inbound TLS, PROXY protocol, new HLS asset types/modes/storage and additional codecs. Each needs named operational evidence and a separate design gate. None is reserved as unfinished mandatory work in this freeze.
Rejected from this standalone plan: embedded history/audit databases and persistence of volatile runtime state, public directories, broad Icecast parity (including XML admin parity, /status-json.xsl, directory services and Icecast configuration syntax), clustering/consensus/shared databases/service meshes, platform-specific integration, and media transformation. External analytics/audit collection remain valid deployment responsibilities. RadioPlatform integration is rejected for this milestone, not a claim that a future external consumer can never use the standalone API.
Dependency graph and implementation order
The A1–A4 entries are internal sequencing within one implementation milestone, not four independently proposed milestones. Implement tests alongside each path. Reuse existing concrete ownership mechanisms; no speculative SourceProducer trait hierarchy, new generic scheduler, or fanout rewrite is necessary to approve this plan.
Source-policy decisions deliberately kept outside Phase A
Fallback: recommend a single configured same-server HTTP redirect when the requested primary is unavailable for source/initialization reasons, resolved only on a new listener request. Target failure returns the normal unavailable response; do not redirect on authentication, listener-capacity exhaustion, or server drain. Do not migrate an already streaming listener. This is the simplest candidate model, but it requires explicit semantics approval and player testing; no status-code/configuration contract is committed here. Internal attachment would need decisions about requested versus effective mount identity, listener caps, API attribution, format compatibility and later primary recovery. A transparent configured fallback-source relationship would additionally enter source policy; it is not hidden inside relays.
Takeover and priorities: no “last source wins.” A later concrete workflow must jointly define credential-to-producer scope, numeric or named priorities, ties, current ownership, protected preemption, decoder/listener continuity across formats, metadata generation, lower-priority source retention/resume, and stale-source cleanup. Prefer an explicit state/priority model if selected. Existing source generations do not guarantee continuous playback during replacement. Keeping displaced sources connected would add bounded slots/tasks/media reservations that must be designed then.
Automatic failover: reconnecting the same upstream in Phase A is transport recovery, not source-selection failover. Multi-upstream activation, primary-return behavior and live-to-automation resume depend on approved policy plus failure thresholds/hysteresis. Scheduling, business rules and general orchestration belong outside Quikcast.
Chaining: only a demonstrated multi-fallback need justifies it. Require startup cycle detection, a fixed depth bound and deterministic availability resolution; no recursive network probing or unlimited graph traversal.
Origin/edge: ordinary relays already permit origin → edge → listeners. A future deployment milestone can validate that topology without new clustering state, discovery, consensus, a shared database, or an “edge mode” abstraction. Operators must avoid relay loops; remote origins are not guaranteed discoverable by local cycle checks.
Reload and rotation: retain restart-based configuration and rotation now. Later rotation can atomically replace one credential scope without generic reload, but must specify whether existing sessions survive, how old/new secrets overlap, and when outbound relay credentials take effect. General reload also needs transactional validation and ownership of mount removals, listener limits, proxy identity snapshots and relay tasks. No mutable global configuration bag is proposed.
TLS/PROXY: outbound HTTPS certificate validation belongs to relays. Native inbound TLS remains deferred because external termination is accepted. PROXY protocol is distinct from current trusted XFF inspection and offers no established benefit without a named L4 deployment; if selected, define a narrow trusted-peer version/subset and reject ambiguous framing.
HLS/codecs: retain MPEG-TS whole-object HLS and MP3/AAC ADTS/Ogg Vorbis/Ogg Opus. Range requires actual target-player evidence. New containers, low-latency HLS, encryption and persistence each introduce independent producer/player and lifetime obligations. They cannot be implemented by converting continuous mounts. Additional continuous formats need their own bounded parser, join and compatibility evidence.
Exactly one next implementation milestone
Bounded continuous relay sources with native lifecycle management.
It comes next because remote continuous-stream redistribution is the one clearly intended remaining server capability. It provides useful upstream ingestion and establishes the reusable origin/edge mechanism while preserving the current media boundary. Its failure, metadata and retry policies form one tightly related feature group. Fallback and takeover are not prerequisites for a dedicated relay mount.
Dependencies: approval of this roadmap and the relay contract below; existing mount leases, generation cancellation, media validation/joins, title state, drain, and authenticated management; selection of a maintained bounded HTTP/HTTPS client with documented body/framing, DNS and TLS behavior. Exact crate versions, endpoints, fields, defaults and numerical limits are implementation-review choices, not invented here.
Proposed relay contract for that approval
Static operator configuration. One explicitly configured HTTP/HTTPS remote continuous URL per dedicated local mount; optional upstream Basic credentials loaded through bounded secret-file handling. No public endpoint accepts arbitrary relay URLs, no inline URL userinfo, and no secret-bearing URLs/logs/API responses. Bound URL/configuration sizes, relay count, outbound connections/handshakes, headers, buffers, credentials, tasks, metadata and deadlines. Upstream addresses are operator-authorized egress destinations; do not build a public fetch service. No automatic redirect-following in the initial contract, so credentials cannot silently move to another origin. Operators configure the final endpoint.
Remote protocol validation. Accept the selected successful HTTP response/framing subset through a maintained client, reject conflicting/unsupported framing, unsupported media and HLS/HTML/error responses. Validate Content-Type against the existing continuous media set and apply existing media/parser/join validation; do not infer codec from URL or promise decoded-bitstream validation. HTTP transfer framing is removed before ICY parsing. Request uncompressed content and reject unsupported content encodings. A finite response/EOF is a relay disconnect, never conversion into an HLS object. Legacy
ICY 200 OKstatus syntax is a narrow compatibility candidate only if a selected upstream needs it.Dedicated ownership and shared domain. Reserve relay-configured mounts against external encoder claims; reject duplicate relay definitions and self-targets detectable locally. Do not race encoder admission or silently preempt a source. The relay directly claims/starts/publishes/finishes the same source lease and existing parser/ring/fanout used by encoder adapters. It does not connect back through the public source socket, fabricate encoder authentication, or add a second ring. Dedicated mount ownership is configuration policy, not a new priority model.
Bounded metadata adaptation. Map an allowlist of validated remote
icy-*station fields into the existing source metadata representation; omit malformed optional station fields. Keep aggregate metadata within the existing 8 KiB contract. For MP3/AAC, request ICY where supported, validate a positive boundedicy-metaint, and consume exactly that many audio bytes between length-prefixed metadata blocks. The length byte permits at most 4,080 metadata payload bytes; remote parsing must have a separate fixed cap and incremental state. It must not assume Quikcast's own smaller title block or 16,000-byte interval is the remote contract.Track normalization and corruption handling. Parse a narrow unambiguous
StreamTitlerepresentation, validate UTF-8 and the existing 1,024-byte/control-character/semicolon rules, and update only the owned current generation through existing title serialization. Ignore unknown fields and invalid/ambiguous titles; a zero-length ICY block means unchanged metadata, while an explicit valid empty title clears it. Strip upstream ICY blocks before audio publication, then let local listeners negotiate the local interval independently. Never forward raw remote blocks. If a bounded block has invalid text but sound framing, skip the metadata and continue exact audio delivery. If truncation or invalid interval makes framing unknowable, close only that relay attempt and retry; guessing an audio boundary would corrupt delivery. New generations start with fresh track state. Ogg comments remain in-band without extraction, rewriting or synthetic ICY.One supervised state machine per relay. Explicit
stopped,connecting,connected, andbackoffstates, with a separate bounded stop/retry reason and attempt identity. Connected means the validated source lease has started; media readiness remains separately visible through existing source/codec state. Exactly one active upstream attempt and one retry timer per relay. Finite initial/max delays, capped exponential growth, bounded jitter, and a configured stable-connection interval before resetting backoff. Avoid arithmetic overflow. DNS/connect/TLS/header deadlines and media-read inactivity deadlines are finite and cancellation-aware; no total-duration deadline terminates a healthy live stream. Metadata chatter without audio must not defeat media inactivity detection. DNS timeout must not accumulate detached resolver jobs; the chosen client's resolver/concurrency contract needs evidence.Recoverable versus stopped behavior. Upstream EOF, reset, timeout, DNS/TLS/HTTP/media failures release attempt resources and enter bounded backoff with a sanitized reason. Invalid static configuration fails startup. Persistent remote auth/format/certificate failures stay visible and retry only at the bounded rate; no certificate verification bypass. Administrative stop releases the current attempt and suppresses automatic retries until explicit reconnect/start or process restart. Stop/reconnect commands are serialized by the relay owner, generation/attempt guarded, and cannot leave overlapping attempts. Existing native source-disconnect on a relay-owned source must produce administrative stop rather than an immediate retry undoing the operator's action. Listener disconnect retains existing semantics.
Generation and drain semantics. Upstream failure ends its source generation and its listeners; clients reconnect to the new generation after successful relay recovery. Seamless continuity is explicitly outside this milestone. During server drain, an already admitted connected relay may continue its existing generation, but new attempts/admissions and manual reconnects are blocked. A relay between attempts stops retrying while drained. Shutdown cancels connect/read/backoff and joins owned tasks within the existing lifecycle deadline. Stale attempt cleanup/title updates/control commands cannot affect a successor.
Native visibility and failure isolation. Authenticated
/apiinspection exposes bounded relay identity/local mount, state, enabled/stopped reason, attempt/generation, connection age, next retry, sanitized last error, byte accounting, attempts/reconnects and metadata rejection counters. Distinguish received transport bytes from published encoded audio and metadata. Stop/reconnect operations use the management scope, not remote or source credentials. Do not expose secret URLs, raw upstream bodies or TLS/debug internals. Keep metrics labels fixed/bounded and logs limited to bounded state transitions/diagnostics. Retry tasks, socket/TLS buffers and staging have explicit aggregate reservations in addition to existing media budgets. Never retry while holding mount locks or permits from the ended generation. Failures remain relay-local; correctness tests must show unrelated continuous/HLS/API/lifecycle paths still work within configured headroom, without claiming privileged admin availability under saturation.
Explicit exclusions
No fallback, takeover, priorities, multi-upstream selection, automatic source failover, chaining, seamless generation migration, config reload, restart-free rotation, directory/admin compatibility suite, clustering, inbound TLS, PROXY protocol, new codecs, HLS enhancements, media conversion, runtime subprocesses or RadioPlatform integration. No optimizer work, allocator tuning, buffer pools, lock-free rewrites, io_uring, unsafe Quikcast code, syscall tuning, custom executors or architecture-specific changes. Adding the concrete outbound transport dependency is feature implementation, not an invitation to refactor existing working transport/fanout.
Completion criteria
Approved static configuration and remote HTTP/HTTPS/auth contract work for the four currently supported continuous formats; unsupported inputs fail closed and secret material is absent from operational output.
The shared source lease/media/join/fanout path is used, with exclusive dedicated-mount ownership and existing aggregate generation/media limits retained. Every new task, socket, handshake, body/metadata buffer and resolver attempt has an enforceable bound.
Deterministic byte-level tests verify ordinary and chunked responses, arbitrary split reads, distinct remote/local ICY intervals, metadata changes/clears, malformed text, framing truncation, MIME/media rejection and Ogg initialization/late join. Byte-for-byte encoded audio preservation is verified independently of metadata output.
Controlled fault tests cover partial HTTP headers, timeout in each connection stage, EOF/reset, refused/DNS/TLS/auth failures, unsupported encoding, invalid media, persistent failure backoff, stability reset and stop/reconnect races. Timer tests verify bounded retries without performance benchmarks.
Cancellation/ownership tests cover admin source-disconnect, relay stop/reconnect, stale cleanup, resource release, drain while connecting/connected/backing off, and shutdown. Integration correctness tests demonstrate continued unrelated mount, HLS, and management operation during relay faults.
Native relay state/control/statistics and operator documentation match the implementation. Standard correctness/lint checks pass for the selected code changes, and the milestone is reviewed against these criteria.
A focused real-upstream/client smoke exercise demonstrates the relay workflow. This supports feature acceptance but does not replace the comprehensive post-freeze manual-validation gate below, or production qualification.
Proposed implementation sequence and feature freeze
Phase A — continuous relay milestone: implement the complete selected group only after roadmap approval, using A1–A4 above as internal order. Record contract decisions and failure-isolation evidence. No policy-feature or fanout preparation refactor.
Phase B — scope and operator closure: update standalone wording/runbook; identify named target encoders, upstreams, continuous players, HLS players and the proxy deployment. Review any already observed compatibility failure. Explicitly select or defer CLI/deployment examples. If a required player proves incompatible, approve the smallest compatibility change, implement and verify it before freeze; broad parity remains rejected. If a new feature family is requested, revise the freeze scope rather than quietly adding it.
Phase C — FEATURE FREEZE: declare this explicitly only when all of the following are true:
The accepted standalone baseline remains intact: continuous MP3/AAC ADTS/Ogg Vorbis/Ogg Opus, safe supported late join, ICY MP3/AAC titles, externally produced MPEG-TS HLS typed ingest/whole-object serving, bounded admission/storage, distinct credentials, native inspection/control, trusted XFF, health/metrics/logging, drain and shutdown/restart.
The entire approved relay milestone passes its completion criteria: configuration, outbound HTTP/HTTPS/auth, remote format/metadata handling, dedicated ownership, shared source publication, supervised backoff/deadlines, stop/reconnect, observability, resource accounting and fault isolation. No metadata/retry/control item is left as unfinished mandatory follow-up.
Standalone operator documentation covers sources, relays, listeners, HLS producer/repopulation, metadata, management, external TLS/private admin, nonbuffering proxies, Unix logging constraints, static restart-based configuration/rotation, volatile state and generation-scoped listener continuity.
Every optional/deferred candidate has an explicit disposition. Only specifically approved conditional compatibility additions are included, and those are finished. No planned functionality remains unimplemented inside the freeze scope.
Correctness/lifecycle/resource-bound checks pass, known correctness blockers are closed, the target manual-validation plan is recorded, and the operator accepts the supported media/client/deployment limits. An explicit review records the accepted scope and build identity.
After that declaration, permit correctness fixes, validation, profiling, optimization and hardening only, in the order below. New planned functionality requires an explicit new scope decision and a new freeze review. Freeze does not certify satisfactory manual testing, performance, or production readiness by itself.
Phase D — comprehensive manual validation: exercise named encoders and all supported codecs, metadata changes/clears, late joins, ordinary authenticated/unauthenticated upstreams, HTTPS, relay disconnect/recovery/admin stop, listener reconnection across generations, and multiple independent mounts. Rehearse native API inspection/cancellation, listener limits, real signal shutdown and restart, secret/config changes through restart, relay drain behavior, and the intended TLS/proxy/XFF/private-admin path. Test named HLS players with rolling publication, ENDLIST, expiry/grace, producer errors, deletion, restart repopulation and drain; inspect actual Range/CORS behavior. Record exact client/build/configuration identities with secrets redacted and pass/failure evidence. These are functional sessions, not profiling, capacity trials or benchmarks. An unmet mandatory client requirement reopens the scope/correctness gate and keeps optimization blocked.
Phase E — profiling/optimization: eligible only after Phase C is explicitly accepted and Phase D is satisfactory, with no required feature/correctness work outstanding. This report neither starts nor recommends a performance experiment.
Phase F — production qualification: follows feature completion, satisfactory manual validation and the optimization/hardening milestone. Broad capacity and deployment qualification remain separate later work.
Review disposition
The concrete approval proposal is: existing standalone baseline + complete bounded continuous relays + operator documentation; policy/deployment/media expansions remain outside the freeze. The next implementation milestone is exactly bounded continuous relay sources with native lifecycle management. Approval of this roadmap does not also approve fallback/takeover/failover semantics or optional backlog implementation.
This report stops at the review gate. No production implementation, profiling, benchmark, tuning, optimization, or runtime refactor was performed.
PERFORMANCE OPTIMIZATION REMAINS BLOCKED UNTIL FEATURE FREEZE.