Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# [S] js/net: remaining capability gaps vs rs/moq-net (SETUP role, finish_at and final sequence, range controls, typed errors)
# [M] js/net: remaining capability gaps vs rs/moq-net (SETUP role, finish_at and final sequence, range controls, typed errors)

## Goal

Expand All @@ -8,8 +8,10 @@ within the issue's stated scope and boundaries.
## Plan

Rescoped during the 2026-08 grooming: SETUP role, frame naming, typed errors,
and start/end cursors landed on dev. The one surviving gap: track end
semantics (finishAt / finished(), still collapsed into close(abort?)).
and start/end cursors landed on dev. Two gaps survive: track end semantics
(finishAt / finished(), still collapsed into close(abort?)), and the
producer-side `announce(prefix)` a Rust publisher has and a browser one does
not.

### Issue context

Expand All @@ -20,6 +22,7 @@ Where js/net is a strict subset of the Rust model. The subscription-options mode
- \[ ] **Range/cursor controls**: `start_at`, `end_at`, `get_group` (wait for a live sequence), sync cache peek, and `latest()` have no JS equivalents. Some are relay-only and fine to omit, but `startAt`/`endAt` pair with the missing subscription range fields and a JS player implementing catch-up/DVR hits this wall.
- \[ ] **Typed errors**: Rust has a `#[non_exhaustive]` enum with stable wire codes; JS throws bare `Error` with prose (only `CacheFull` is a class), so consumers string-match to distinguish `NotFound` from `Unauthorized`, and wire reset codes are not surfaced. At minimum add a stable `code` property before locking the API.
- \[ ] **Delete the dead `SubscribeOptions` export** (`js/net/src/track.ts`): introduced by #2167, superseded by `Subscription` in #2170, identical field-for-field, referenced nowhere. Two exported names for one concept invites drift.
- \[ ] **Producer-side `announce(prefix)`**: Rust publishers advertise a prefix route and serve whatever is requested beneath it; JS only consumes prefix routes, so a browser publisher still announces exact paths and cannot advertise a catalog it would materialize on demand.
- \[ ] **Frame field naming**: JS uses `payload` for `Datagram` but `data` for both Frame types, and `@moq/hang`'s container Frame is shaped differently from both `@moq/net`'s and Rust's. Pick `payload` consistently (JS `keyframe`/`duration` are genuine WebCodecs needs and fine as additive fields).

Related: #2155, #2216, #2073.
Expand Down

This file was deleted.

This file was deleted.

3 changes: 0 additions & 3 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,6 @@ with the current dev tree before starting.
- [#2985](/quest/m1/2985-js-net-path-keyed-publisher-state-goes-stale-when-a.md) - js/net: path-keyed publisher state goes stale when a broadcast is replaced
- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - net: coalesce dynamic tracks and preserve sequences across replacements
- [#2708](/quest/m1/2708-origin-open-the-announce-interest-lazily-on-first-consumer.md) - origin: open the announce interest lazily, on first consumer
- [#2756](/quest/m1/2756-origin-announce-only-entries-advertise-on-demand-content.md) - origin: announce-only entries, advertise on-demand content without instantiating broadcasts
- [Plan: generations](/quest/m1/plan-generations.md) - re-plan historical broadcast enumeration against the dev announce model via /plan-quest
- [#2873](/quest/m1/2873-moq-net-enumerate-and-resolve-historical-broadcast.md) - moq-net: enumerate and resolve historical broadcast generations by path and epoch
- [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; gates the dev merge
- [Playable](/quest/m1/hls-playable.md) - a 24/7 broadcast never becomes permanently unplayable over HLS
- [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - Follow the bandwidth grant in moq-audio instead of holding a fixed reservation
Expand Down
11 changes: 0 additions & 11 deletions quest/m1/plan-generations.md

This file was deleted.

4 changes: 2 additions & 2 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ dashboards, fleet rollout) stay downstream.

## Quests

- [Broadcast epoch](/quest/m2/broadcast-epoch.md) - every broadcast carries a publisher-minted generation epoch, so restarts never splice
- [Generation](/quest/m2/hls-generation.md) - media URLs carry the resolved epoch so segment caching can be re-enabled
- [Plan: HLS identity](/quest/m2/plan-hls-identity.md) - settle where a cacheable generation ID comes from via /plan-quest
- [Generation](/quest/m2/hls-generation.md) - media URLs carry a generation ID so segment caching can be re-enabled
- [Wildcard](/quest/m2/wildcard/README.md) - a service advertises a path pattern it could serve instead of enumerating broadcasts
- [Path patterns](/quest/m2/path-patterns/README.md) - one versioned matcher for every predicate over broadcast paths: tokens, origins, interest
- [Plan: keyframe request](/quest/m2/plan-keyframe-request.md) - settle the keyframe request wire design via /plan-quest
Expand Down
47 changes: 0 additions & 47 deletions quest/m2/broadcast-epoch.md

This file was deleted.

56 changes: 29 additions & 27 deletions quest/m2/hls-generation.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,35 +16,37 @@ restarts at a new resolution decodes new segments against the old parameter
sets; the segment window's `push` (`rs/moq-hls/src/export/segments.rs`) detects
that restart already and resets only the playlist.

The identity itself is [Broadcast epoch](/quest/m2/broadcast-epoch.md)'s job, and it arrives from the
TRANSPORT rather than from the media: `TRACK_INFO` returns the resolved epoch.
Never substitute wall-clock or a relay-local counter, since a CDN needs one URL to
mean the same bytes on every edge.
The missing ingredient is the identity itself: nothing in the stack mints a
generation today. Where it comes from is
[Plan: HLS identity](/quest/m2/plan-hls-identity.md)'s job. Whatever it turns
out to be, it must be minted by the publisher and travel with the content;
never a wall-clock or a relay-local counter, since a CDN needs one URL to mean
the same bytes on every edge.

So this quest is the consumption: the moq-hls playlist and MPD renderers EMIT
epoch-versioned `init.mp4` and segment URLs, and the cached init is invalidated
when the epoch changes. Both are CONDITIONAL on a non-zero resolved epoch: a
publisher that mints none resolves to 0, which cannot version anything, so
those broadcasts keep unversioned URLs rather than being cached against an
identity that does not exist. The cache-header half is moq.pro (downstream)
work: its edge parses the versioned paths and restores the long `max-age`
(where `immutable` is finally true) once the renderers emit them; versioning
the accepted paths without versioning the emitted ones changes nothing.

**Open: the broadcast epoch does not cover a mid-broadcast rendition
reconfigure.** Only one of the two collision sources is a new generation: an
epoch is minted per path when the broadcast is announced, so a live publisher
that reconfigures a rendition (a resolution change, say) reuses the same
`init.mp4` URL and segment numbers for different bytes without the epoch moving.
Re-enabling caching on the epoch alone would let a CDN keep serving the previous
configuration. Resolve before caching is re-enabled, either by adding a
rendition-generation component to the URL or by requiring (and testing) an epoch
bump on every reconfigure.

Acceptance: a publisher restart mid-playback exercised end to end, a zero-epoch
publisher still served with unversioned URLs, and a mid-broadcast reconfigure
that cannot be decoded against the previous configuration.
generation-versioned `init.mp4` and segment URLs, and the cached init is
invalidated when the generation changes. Both are CONDITIONAL on the identity
being present: a publisher that declares none cannot version anything, so those
broadcasts keep unversioned URLs rather than being cached against an identity
that does not exist. The cache-header half is moq.pro (downstream) work: its
edge parses the versioned paths and restores the long `max-age` (where
`immutable` is finally true) once the renderers emit them; versioning the
accepted paths without versioning the emitted ones changes nothing.

There are two collision sources, and a per-broadcast identity only covers one
of them. A live publisher that reconfigures a rendition (a resolution change,
say) reuses the same `init.mp4` URL and segment numbers for different bytes
without restarting the broadcast, so caching on a restart-scoped generation
alone would let a CDN keep serving the previous configuration. Either the URL
gains a rendition-generation component or the identity is required (and tested)
to move on every reconfigure. Settle it in
[Plan: HLS identity](/quest/m2/plan-hls-identity.md); it is the reason that
plan exists rather than a detail of this one.

Acceptance: a publisher restart mid-playback exercised end to end, a publisher
declaring no identity still served with unversioned URLs, and a mid-broadcast
reconfigure that cannot be decoded against the previous configuration.

## Required

- [Broadcast epoch](/quest/m2/broadcast-epoch.md) - a generation ID has to exist before a URL can carry it
- [Plan: HLS identity](/quest/m2/plan-hls-identity.md) - a generation ID has to exist before a URL can carry it
Loading
Loading