Skip to content

@moq/net: a late draft-18 JS subscriber never receives a catalog written once #7088

Closed

Description

@michaelstuurman

Problem

Before draft 22, the JS IETF subscriber never sends a joining FETCH, and on draft 18
it subscribes with Absolute Start {0, 0} (joinFilter in
js/net/src/ietf/subscribe.ts: "this client does not send joining FETCH"). A relay
that follows draft 18 §5.1.2/§5.1.3 delivers only objects after Largest, and serves
earlier objects only through FETCH (§10.12.2). Behind such a relay, a browser that
joins late:

  • never receives a group written once before it subscribed, such as the hang
    catalog.json or a JSON snapshot track, so @moq/watch stays on "loading";
  • drops its first media group as headless ("dropping a group with no head") and
    waits for the next keyframe.

We see this through OpenMOQ's moqx relay on draft 18. The Rust subscriber joins at
the current group: it subscribes with Largest Object, sends a Relative Joining FETCH
for the group's head, and stitches the head and the live tail into one group (a
refused FETCH costs only that head, #6407). #6945 made the JS publisher answer that
FETCH, and notes that "JS subscribers send unfiltered before draft 22 and are
unaffected". This is the subscriber half: quest/m1/interop-coverage/late-join.md
expects the join "for Rust and JS publishers and subscribers".

The trade-off for media

For a catalog or snapshot track, the head is the point: without it the track may not
arrive for a long time. For live media there are two reasonable joins:

  • Current group: the first frame shows at once, but it is up to one group (one
    GOP) behind live. The player then stays behind, or skips forward to catch up.
  • Next group: playback starts at the live edge, after up to one GOP of black.

For low-latency live we'd default media to the next group, but this is your call.

Proposal

  1. Add join?: "current" | "next" to Track.Subscription, default "current". Any
    "current" subscriber makes the aggregate "current". It is fixed at subscribe
    time, like the group order.
  2. "current" on draft 18: SUBSCRIBE with Largest Object. After a SUBSCRIBE_OK with
    Largest {G, k}, send a Relative Joining FETCH (offset 0) on its own request. It is
    not counted in PUBLISH_DONE's Stream Count. With no Largest, don't send one.
  3. If the joining FETCH is refused or fails before any object, send one standalone
    FETCH for {G, 0} up to {G, k + 1} into the same head. Some deployed relays cannot
    resolve the join for a lone subscriber but serve the range.
  4. The fetch stream creates group G and writes objects 0..=k as they arrive, so
    readers see them at once. The live stream from k + 1 takes over that same group
    producer. A tail that arrives first waits for the head. If both FETCHes fail, or
    the head is empty or timed out, only G's head is lost and the next group plays. A
    whole group from object 0 wins the sequence if it arrives first, and is refused if
    it arrives after the head, as in Rust.
  5. "next": SUBSCRIBE with Next Group Start, no FETCH. A group in progress that the
    publisher sends anyway is skipped.
  6. @moq/watch subscribes media (video, audio, text) with "next". The catalog and
    other tracks keep the default.

Interop

Against the JS publisher from #6945, in a test: a late JS subscriber fetches a catalog
written once, and joins media at the next group. The JS publisher ignores Next Group
Start on draft 18 and sends the group in progress whole; the subscriber skips it.

With a moq CLI publisher (ffmpeg testsrc2, 4 s GOP) on draft 18:

  • moqx main (v0.3.6-55), a single relay: a late JS viewer gets the catalog and a
    complete current group through the joining FETCH, both from the native JS client
    and from @moq/watch in Chrome, alone or next to a second viewer. Without the
    change, the same relay drops the catalog group as headless and the viewer waits on
    "loading".
  • A deployed moqx instance answers the joining FETCH when the track already has a
    subscriber there. For a lone subscriber it refuses with DOES_NOT_EXIST "Session has
    no active subscribe", for the Rust subscriber as much as for this one, but answers a
    standalone FETCH for the same range. With the fallback, a lone first viewer there
    gets the catalog within 0.2 s.
  • The same instance, media with "next": the first frame shows at the next group
    boundary, 0.1 to 2.4 s after subscribing, from object 0. It sometimes still sends the
    tail of the group in progress despite Next Group Start; that tail is skipped.

Draft 22 is out of scope here, but it has the same gap: "current" sends relative(1)
without FILL_PARAMETERS. The same stitching would serve a draft-22 fill.

Open questions:

  • Which default do you want for media in @moq/watch: "next" (live edge) or
    "current" (instant first frame)? And should @moq/net itself keep "current"?
  • moq-lite serves the current group whole whatever join says. Should lite honor
    "next" too?
  • Is the standalone fallback welcome here, and should the Rust subscriber take it
    too? Without it, a lone viewer behind such a relay loses the catalog.
  • Keep Rust's strictness when a whole group arrives after the head, or skip the
    duplicate prefix?
  • Should the subscriber put a deadline on FETCH_OK (as on SUBSCRIBE_OK), or leave
    that to the fill-timeout quest?

A PR implementing this follows.

Activity

  1. coderabbitai commented on Oct 28, 2026

    @coderabbitai
    Contributor
    🔗 Related PRs

    #6798 - quest: audit the tree and record the 2026-10-25 decisions [merged]


    📝 Issue Planner

    Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.

    • Create Plan

    🧪 Issue enrichment is currently in open beta.

    You can configure auto-planning by selecting labels in the issue_enrichment configuration.

    To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

    issue_enrichment:
      auto_enrich:
        enabled: false

    💬 Have feedback or questions? Drop into our discord!

  2. added
    questBeing tracked/planned in a quest. See `quest/`
    on Oct 28, 2026
  3. kixelated commented on Oct 28, 2026

    @kixelated
    Collaborator

    Thanks. Planned in #7124 as quest/m1/ietf-js-join.md:

    • Mirror Rust. The JS subscriber joins at the current group: Largest Object plus a Relative Joining FETCH, stitched into one group, on draft 18; and the matching fill on draft 22, which has the same gap.
    • No join knob, and no "next" for @moq/watch media. An earlier plan rejected joining at the next group (a GOP of startup), and lite and Rust have no such anchor. Watch's maxDelay already decides how far behind live to play.
    • No standalone-FETCH fallback. A relay that refuses the joining FETCH for a lone subscriber has a bug of its own (worth reporting to moqx), and a refusal costs only that group's head.
    • No FETCH_OK deadline, matching Rust. Keep Rust's strictness on a whole group arriving after the head.

    We'd like to land this through #7089. We'll trim it on its branch (maintainer edits are on), keeping your authorship: drop the knob, the watch change, the fallback and the deadline, and add the draft-22 fill.

    (Written by Claude Opus 5.5)

  4. kixelated commented on Oct 28, 2026

    @kixelated
    Collaborator

    The plan from #7124 is in the merge queue. In short: the JS subscriber joins the way Rust does. On draft 18 that is Largest Object plus a Relative Joining FETCH, and on draft 22 a fill. There is no join knob, no standalone fallback and no FETCH_OK deadline. We'll trim #7089 to that scope on its branch rather than open a new PR.

    quest/m1/ietf-js-join.md tracks it. To donate tokens, run /quest-start quest/m1/ietf-js-join.

    (Written by Claude Opus 5.5)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questBeing tracked/planned in a quest. See `quest/`

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions