feat(spf): multi cdn failover

[cjpillsbury]

Base branch: targets feat/spf-multi-cdn (the sticky-CDN-pick PR), not
main — will repoint to main once that lands. The Files changed tab is
already scoped to just this PR's content.

TL;DR

Multi-CDN failover for HLS sources that publish the same content on more than
one host (Mux Video's ?redundant_streams=true). The redundant variants
already parse as ordinary per-CDN candidate tracks, so this is modeled as
selecting a CDN and keeping the whole presentation on it inside the
track-switching rule model — a scope rule (sticky pick) + a constraint
(failover) — rather than URL rewriting at fetch time. Validated by engine
integration tests and a gated live round-trip against a real Mux source.
Internal SPF (alpha); engine config + state additions are additive.

For reviewers — how to read this PR

The single biggest churn is the design-doc rewrite (multi-cdn-failover.md,
+186/−143, docs-only). The runtime change is two new behaviors
(setup-failover-monitor, plus the deriveCdnPriority rename) and fetch-site
decorators threaded into existing behaviors/engines.

Runtime (focus here)

Read fully: setup-failover-monitor.ts (new) — owns failedCdns;
per-source cooldown timers that expire a tripped CDN; clears the set + timers
on src unload (no cross-source leak); trips on a single terminal failure
(retry/back-off is a future layer below the trip, not here)

Targeted careful read:

• track-switching.ts (+134/−37) — preferActiveCdn scope (active CDN =
  highest-priority cdnPriority entry with surviving tracks; falls through
  when a CDN is empty) + excludeFailedCdns constraint, shared by the video +
  audio chains via one CdnRuleConfig; cross-type coherence (both chains read
  the same definition → agree on the CDN); applyConstraints pre-pass runs
  before the rule chain and should be order-independent; SwitchableTrack
  gains url
• resolve-track.ts (+76/−10) — failoverFetch decorates the media-playlist
  fetch; one catch covers both a thrown fetch and a non-OK status
  (fetchResolvableText rejects on non-OK); the failing CDN is keyed off the
  track URL via the configured getCdnId
• setup-buffer-actors.ts (+43/−5) — failoverFetchBytes trips on a
  segment-fetch failure the same way; the decorator wraps
  trackedFetch/fetchStream without touching buffer-actor lifecycle
• cdn.ts (+28/−10) — addFailedCdn is pure + idempotent (returns the same
  array reference when the CDN is already present — the monitor's
  set-membership watch relies on this to not reschedule); getCdnId origin
  default + unparseable-URL fallback

Skim structure only: engine.ts (+38/−6) / engine-audio-only.ts
(+28/−5) — compose deriveCdnPriority + setupFailoverMonitor after
resolvePresentation, add failover?/getCdnId? config + cdnPriority?/
failedCdns? state; audio-only mirrors main. derive-cdn-priority.ts
(+10/−7) — the resolveCdnPriority → deriveCdnPriority rename +
getCdnId threading, no behavior change. network/fetch.ts (new) — FetchText

• fetchResolvableText (fetch → reject on non-OK → text), the text analog of
  FetchBytes

Skim file: Tests (6 files, +411) — engine.test.ts integration
(manifest-order cdnPriority + pick on primary; reorder re-narrows;
auto-failover when a media-playlist fetch fails; custom getCdnId honored
end-to-end); setup-failover-monitor.test.ts (cooldown expiry, per-CDN
independence, per-source clear); track-switching.test.ts (scope/constraint +
failover-via-constraint); cdn.test.ts / derive-cdn-priority.test.ts /
resolve-track.test.ts. failover-smoke.test.ts is the gated live round-trip
(see Smoke test)

Design doc (skim)

Skim file: internal/design/spf/features/multi-cdn-failover.md (+186/−143)
— the feature spec, now definition: implemented. Carries the "constraint +
scope, not URL rewriting" rationale and the site-adds / behavior-expires
failover split; the Follow-up candidates section enumerates the deliberately
deferred gaps.

Smoke test

Sticky CDN pick is observable through the SPF segment-loading harness against a
real Mux redundant source. preload=auto is required — the harness defaults to
preload=none, which never activates the manifest fetch.

Sandbox: /spf-segment-loading/?preload=auto&muted=true&autoplay=true&src=https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8?redundant_streams=true

• Video plays (time advances, buffer grows) — the CDN pick doesn't break
  playback.
• The rendition picker lists each rendition as "N rendition(s) across CDNs" —
  confirms the source really is multi-CDN (redundant variants parse as per-CDN
  tracks).
• Console: window.state().cdnPriority → two hosts in manifest order
  (…edgemv.mux.com, then …fastly.mux.com).
• The selected video and audio tracks resolve from the same host (the
  primary, edgemv) — the whole presentation sticks to one CDN (cross-type
  coherence), not a per-type host split.

Failover / recovery has no built-in harness control (it needs a CDN to actually
fail). That round-trip — trip → failover to backup → recovery to primary —
is the gated live test:

VITE_FAILOVER_SMOKE=1 pnpm -F @videojs/spf test \
  src/playback/engines/hls/tests/failover-smoke.test.ts

What changed — by surface

Sticky CDN pick (scope). deriveCdnPriority publishes a per-presentation
ordered cdnPriority list (the manifest's distinct CDN hosts, most-preferred
first — mirroring HLS content steering's PATHWAY-PRIORITY), and clears it on
src unload. A shared preferActiveCdn scope rule narrows every track type's
candidates to the highest-priority CDN that still has tracks, so video / audio
/ text all resolve from one host. The active CDN is derived (first-with-
survivors), never stored.

Failover (constraint + trip/expiry). Site-adds, behavior-expires. Fetch
sites add the failing CDN's origin to a failedCdns set on a terminal fetch
failure — failoverFetch for media playlists in resolve-track,
failoverFetchBytes for segments in setup-buffer-actors. A shared
excludeFailedCdns constraint (in setupTrackSwitching's new applyConstraints
pre-pass) prunes that CDN's tracks, so the scope's first-with-survivors falls
to the next CDN automatically. setupFailoverMonitor removes the CDN once a
cooldown lapses, and the scope snaps back — no reactive "active CDN" rewrite at
any point.

Configurable CDN identity. getCdnId (origin-based default) is overridable
via engine config — e.g. to key on Mux's cdn= query param — and is threaded
to all four CDN-id sites so the keys used to build cdnPriority, trip
failedCdns, and evaluate the scope/constraint stay comparable.

Notable design decisions

• Constraint + scope in the track-switching model, not active-URI rotation
  in resolveTrack. Redundant variants already parse as per-CDN tracks, so
  CDN choice is a track-selection problem. Alternative considered: rewrite the
  selected track's URL at fetch time, or store a reactive activeCdn value.
  Rejected because the ordered-list shape (cdnPriority, active =
  first-with-survivors) makes failover a pure constraint — pruning moves the
  pick, un-pruning returns it — and composes with content-steering later as a
  plain list reorder, with no active-value rewrite to keep in sync.
• Self-contained cooldown, not a network-resilience circuit-breaker.
  setupFailoverMonitor is a per-source cooldown timer. Alternative
  considered: depend on the (unbuilt) network-resilience cluster for
  retry/backoff/error-classification. Rejected because failover shouldn't block
  on that cluster; retries would sit below the trip (so it sees only
  post-retry terminal failures) as a future refinement, not a prerequisite.
• Trip on the first terminal failure. A network error or non-OK
  media-playlist status trips immediately; cooldown is the only back-off.
  Alternative considered: an N-failures threshold or a windowed/decaying health
  metric. Rejected as over-built for the first cut. Reviewers: is
  trip-on-first too aggressive for flaky-but-not-dead CDNs? (flapping is called
  out below.)

Reviewer callouts — known limitations

• [Deferred] All-CDNs-down has no terminal state. When every CDN is pruned
  the candidate set is empty and the prior pick is silently left in place; a
  distinct "nothing playable" state is unmodeled (shared with the
  constraints-pre-pass work).
• [Deferred] Flapping / no cooldown extension on re-failure. A flaky CDN
  can oscillate — trip → cooldown lapses → re-preferred (it's cdnPriority[0])
  → fails again. No hysteresis or growing back-off on repeated trips; re-failing
  mid-cooldown doesn't push the deadline out.
• [Deferred] Coarse HTTP-status classification. The trip fires on a thrown
  fetch or a non-OK media-playlist status; finer classification (5xx-with-body
  vs 4xx, segment-side codes) is deferred to network-resilience. A 200 with
  an unparseable body deliberately does not trip (content issue, not CDN
  unavailability).
• [Author] switchAudioTrack config tidiness (cosmetic). Audio spreads
  ...config, so video-only ABR fields ride into the shared ranker harmlessly
  (audio has no bandwidthState). A cross-cutting-only shared config type would
  keep them out.

Breaking changes

The resolveCdnPriority → deriveCdnPriority rename is internal SPF only — not
a public export, no external consumers. New engine config (failover?,
getCdnId?) and state (cdnPriority?, failedCdns?) are additive.

Test plan

• Gated live failover smoke test — VITE_FAILOVER_SMOKE=1 pnpm -F @videojs/spf test src/playback/engines/hls/tests/failover-smoke.test.ts —
  passes: trip → failover to backup → recovery to primary against a real
  Mux ?redundant_streams=true source.
• E2E through the html player + real MSE — deferred: apps/e2e pages are
  generated from media.ts, so a redundant source would sweep into every
  generic + visual spec. The gated engine smoke test covers the round-trip,
  including recovery (which isn't observable at the player DOM).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v10-sandbox	Ready	Preview, Comment	Jun 10, 2026 7:02pm