Skip to content

Instantly share code, notes, and snippets.

@englishm
Created October 12, 2026 23:12
Show Gist options
  • Select an option

  • Save englishm/8a08ca17d09edefcd6720bc08262bced to your computer and use it in GitHub Desktop.

Select an option

Save englishm/8a08ca17d09edefcd6720bc08262bced to your computer and use it in GitHub Desktop.

Work pack: MOQT nested-namespace routing (longest match vs. all matches)

Assembled 2026-10-12 from chicane's notes, measurements and the moq-rs source, for Mike to work from on another machine.

Goals for today:

  1. Interop tests for relay routing when PUBLISH_NAMESPACE prefixes nest. The natural home is moq-rs moq-test-client.
  2. A WG issue asking the draft to say what relays should do.

Everything needed is in this one file: the spec text to check, the history, what was measured, the relay code, the client-side subtleties, a proposed test matrix, and a draft issue.


1. The question in one paragraph

Publisher G announces (a). Publisher S announces (a, b). A subscriber sends SUBSCRIBE for track t in namespace (a, b, c).

  • Under the draft's prefix-matching rules, both announcements match.
  • The relay text says to send SUBSCRIBE to all matching publishers, so both G and S would get it.
  • Every implementation we measured sends it only to S, the longest match. They don't fall back to G if S refuses.
  • chicane depends on that longest-match behaviour. The draft doesn't say it.

2. Spec text to check (draft-ietf-moq-transport-22; same in -18)

⚠ Quoted from notes taken 2026-10-05. Re-read the current draft and fix section numbers before filing.

  • §2.4.2 Namespace Prefix Matching:
    • A prefix matches a namespace if its fields equal the namespace's leading fields, compared field by field and not byte by byte.
    • -18's own example: a SUBSCRIBE for (foo, bar)/x matches publishers that announced (foo) or (foo, bar).
  • Relay section: "Relays MUST send SUBSCRIBE messages to all matching publishers."
  • Read together: nested announcements both receive the SUBSCRIBE. Nothing in the text says the longest match wins.
  • SUBSCRIBE_NAMESPACE (§10.18/§10.19 in -18): it no longer carries Subscribe Options, and serves namespace announcements only. moq-rs 8ea887b/26b9681 implement this, and the interop relay runs it since 2026-10-07. That's unrelated to the routing question, but it changed the wire format, so test clients must be current.

3. History (2026-10-05; issue and PR summaries only, not every comment or the list)

Ref When What
#252 / PR #394 Feb 2024 Exact-match routing. "Longest prefix match" was listed as an option but not discussed
#1100 / PR #1116 Jul–Aug 2025 Clarified field-by-field prefix matching; nothing on which of several nested matches wins
#1701 / PR #1923 Jun 2026 (#1923 open then) "Send to all publishers" is motivated by make-before-break: several publishers of the same namespace

No explicit decision either way on nested announcements was found. Before filing, check the mailing list and recent interims for "longest", "nested" or "prefix".

4. What implementations do (measured 2026-10-05)

Relay Nested announcements Specific publisher refuses Duplicate (identical) namespace
Cloudflare draft-18 interop relay (draft-18-interop.cloudflare.mediaoverquic.com) Longest match in both announce orders: only the (…, t, stx) publisher got SUBSCRIBE for (…, t, stx, usb, 7074000) No fallback to the general publisher not measured
moq-rs moq-relay-ietf, draft-18-dev Longest match by field prefix (code below) No fallback: routing returns a single best source Refused (second announce of the same namespace)

The moq-rs relay code (at 17e8e58; the same logic was at 52b8a90)

moq-relay-ietf/src/local.rs, Locals::route_namespace:

let mut best_match: Option<NamespaceSource> = None;
let mut best_len = 0;
for (registered_ns, entry) in bucket.iter() {
    let Some(source) = entry.local.as_ref() else { continue };
    if namespace.fields.len() >= registered_ns.fields.len() {
        let is_prefix = registered_ns.fields.iter()
            .zip(namespace.fields.iter()).all(|(a, b)| a == b);
        if is_prefix && registered_ns.fields.len() > best_len {
            best_match = Some(source.clone());
            best_len = registered_ns.fields.len();
        }
    }
}
best_match
  • Unit test: get_or_request_track_uses_longest_namespace_prefix (local.rs ~L2039).
  • producer.rs ~L157 documents it too: "Locals routes a track to the longest registered namespace that prefixes it." namespace_covers is used for rendezvous wake-ups.
  • Consequence: a single best source, so there's no fan-out to all matches and no fallback on refusal.

Client/publisher side: where the SUBSCRIBE arrives (matters when writing tests)

moq-transport/src/session/publisher.rs, Publisher::recv_subscribe (~L1190):

// Route to an active PUBLISH_NAMESPACE if present.
if let Some(ns) = self.publish_namespaces.lock()?.get_mut(&namespace) {
    return ns.recv_subscribe(subscribed).map_err(Into::into);
}
// Otherwise, surface it to the application via the unknown queue.
self.unknown_subscribed.push(subscribed) ...
  • A SUBSCRIBE whose namespace exactly equals an announced namespace goes to that announcement's handler, e.g. the TracksReader passed to publish_namespace().
  • A SUBSCRIBE for a deeper namespace goes to publisher.subscribed(), the "unknown" queue.
  • So a test publisher that announces (a) and wants to see a SUBSCRIBE for (a, b, c) must poll subscribed(). Watching only its Tracks reader would make the test pass or fail for the wrong reason.
  • chicane hit this in production (lesson 45): a per-station service announced exactly the name it was subscribed to, its subscriber was never counted, and its job was stopped as idle every ~22 s. It's worth a sentence in moq-rs docs, or a unified API.

5. What exists already

chicane's ad-hoc script (scripts/prefix-routing-test.sh)

  • Two chicane-ft8 --serve publishers on <root>/svc/<t> (general) and <root>/svc/<t>/stx (specific), started in both orders, 4 s apart.
  • chan-probe subscribes to <root>/svc/<t>/stx/usb/7074000 track ft8.
  • Each publisher logs every SUBSCRIBE it receives; the script counts them per publisher.
  • It's chicane-specific (it needs chicane binaries) and judged by eye. That's fine for a first measurement, but not an interop test.

moq-rs moq-test-client (PR #234): the place for real tests

  • TAP 14 output, one async fn test_* per scenario in src/scenarios.rs, registered in the TestCase enum in src/main.rs.
  • The existing scenarios include publish-namespace-subscribe, subscribe-before-publish-namespace, publish-namespace-done and rendezvous-timeout.
  • test_publish_namespace_subscribe is the template: two sessions, publish_namespace(pub_reader) vs subscribe(sub_track) in a select!, and a 3 s sleep.
  • Gap: it treats both Ok and Err from subscribe as success ("subscription was processed"). The routing tests below need a real assertion: which publisher saw the SUBSCRIBE, and what the subscriber got back.

6. Proposed test matrix

Actors:

  • G: announces (T, g).
  • S: announces (T, g, s).
  • Sub: subscribes as listed below.
  • T is a unique per-run root, e.g. moq-test/<run-id>.
  • Each publisher records SUBSCRIBEs from both subscribed() and its namespace handler (see §4).

Columns: "L" is the result expected under longest match (today's practice); "A" is the result expected under all matches (the literal text).

# Scenario L expects A expects
R1 G then S announce; Sub → (T,g,s,x)/t S only G and S
R2 S then G (reverse order) S only G and S
R3 Sub → (T,g,y)/t (only G matches) G only G only
R4 Field boundary: announce (T,"gs") and Sub → (T,"g","s")/t; also announce (T,"g") and Sub → (T,"gs")/t no match / not routed same
R5 S refuses (REQUEST_ERROR) for R1 Sub gets an error; G never asked (measured: no fallback) depends; record it
R6 S withdraws (PUBLISH_NAMESPACE_DONE) after R1's subscription is live existing subscription ends? new SUBSCRIBE → G? record
R7 Sub active via G (only G announced), then S announces existing subscription stays on G? next new SUBSCRIBE → S? record
R8 Two publishers announce the identical (T,g) (make-before-break) record: both / newest / second refused (moq-rs refuses) both (per #1701 intent)
R9 Sub → exactly (T,g,s)/t (namespace equals S's announcement) S, via its announce handler (§4) G and S
R10 SUBSCRIBE_NAMESPACE (T) while G and S are announced sees both announcements same

Notes:

  • R1/R2 are the core interop cases.
  • R5–R7 are the ones the spec should probably decide explicitly: fallback, and re-routing on withdraw or new announce.
  • R4 guards against byte-prefix matching.
  • R9 exercises the exact-match path on the publisher side.
  • Pass/fail:
    • Assert per-publisher SUBSCRIBE counts and the subscriber's outcome (REQUEST_OK, or REQUEST_ERROR with its code).
    • For "record" rows, emit TAP # SKIP / # TODO with the observed behaviour in YAML diagnostics. That way implementations can differ without the test asserting an unsettled spec.
  • Targets to run against: moq-rs moq-relay-ietf locally; Cloudflare's draft-18 interop relay; any other draft-18 relays in the interop matrix.

7. Draft WG issue

Title: Relay routing with nested PUBLISH_NAMESPACE prefixes: longest match, or all matches?

§2.4.2 defines Namespace Prefix Matching such that a SUBSCRIBE for (foo, bar)/x matches publishers that announced (foo) and (foo, bar). The relay section then says "Relays MUST send SUBSCRIBE messages to all matching publishers." Read together, a relay must forward the SUBSCRIBE to both the less specific and the more specific publisher.

My understanding of the intent, and current practice, is longest match. "All matching publishers" exists for several publishers of the same namespace (make-before-break, #1701/#1923). Implementations behave that way:

  • moq-rs moq-relay-ietf: routes to the longest field prefix (Locals::route_namespace).
  • Cloudflare's draft-18 relay: only the (…, t, stx) publisher received a SUBSCRIBE for (…, t, stx, usb, 7074000), in both announce orders. It didn't fall back to the (…, t) publisher when the specific one refused.

Longest match is a useful feature. It lets a general publisher cover a broad prefix while a more specific publisher takes over part of it, with no relay coordination. One example is a service running next to one station's high-bandwidth inputs, taking that station's part of a namespace from a general cloud service.

  1. Is longest-prefix match intended when announcements nest? If so, can §2.4.2 and the relay section say so, and scope "all matching publishers" to equally specific matches?
  2. If all nested matches are intended, that should be explicit, since implementations don't do it.
  3. Either way:
    • when the most specific publisher refuses, should a relay fall back to a less specific one?
    • when a more specific announcement arrives or is withdrawn, should existing subscriptions move?

Interop tests covering these cases: <link to moq-test-client PR>.

8. Why chicane cares (context for the issue, if useful)

  • Local-first design: a decoder next to a station announces svc/<decoder>/<station> to take over that station's part of svc/<decoder> from a cloud decoder.
  • What it avoids: under "all matches", both would start jobs, and the cloud one would pull the station's raw IQ (6 Mb/s) across a home uplink that can't carry it.
  • Until the spec is settled, chicane relies on longest match for that takeover only, and documents the dependency.

9. Checklist for today

  • Re-read §2.4.2 and the relay section in the current draft; fix quotes and section numbers in §2 and §7.
  • Skim the list and interim minutes for prior discussion of nested prefixes.
  • Add R1–R4 (asserting) and R5–R10 (record and diagnose) to moq-test-client.
    • Make test publishers watch subscribed() as well as their announce handler.
    • Tighten publish-namespace-subscribe's pass condition while there.
  • Run against local moq-relay-ietf and the Cloudflare draft-18 interop relay; paste the TAP results into the issue.
  • File the issue, and link the test PR.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment