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
15 changes: 8 additions & 7 deletions .github/workflows/interop.yml
Original file line number Diff line number Diff line change
Expand Up @@ -124,9 +124,9 @@ jobs:
# A release PR fails, rather than skips, a browser the lite-07 cut waits on to prove its route key.
CI_STRICT: ${{ github.event_name == 'pull_request' && '1' || '' }}

# The same matrix with every client pinned to one moq-transport draft per pass. A release
# PR runs the oldest and newest even draft between Rust and native JS; nightly and manual
# runs cover every even draft and every client.
# The same matrix with every client pinned to one moq-transport draft per pass. A backport
# PR into release runs the oldest and newest even draft between Rust and native JS; the cut
# PR (head `main`), nightly, and manual runs cover every even draft and every client.
- name: Interop (moq-transport)
id: interop-ietf
if: ${{ !cancelled() && steps.setup.outcome == 'success' }}
Expand All @@ -135,15 +135,16 @@ jobs:
nix develop --command just test interop "${args[@]}"
shell: bash -leo pipefail {0}
env:
INTEROP_ARGS: ${{ github.event_name == 'pull_request' && '--publishers rust --subscribers rust,js-native-node,js-native-bun --versions moq-transport-18,moq-transport-22' || '--all --versions ietf' }}
INTEROP_ARGS: ${{ github.event_name == 'pull_request' && github.head_ref != 'main' && '--publishers rust --subscribers rust,js-native-node,js-native-bun --versions moq-transport-18,moq-transport-22' || '--all --versions ietf' }}
HARNESS_RUNS: ${{ runner.temp }}/moq-test-runs
HARNESS_RESULTS: ${{ runner.temp }}/moq-test-runs/results.jsonl

# Registry installs and the release matrix run only on main, nightly or
# on demand: a break only needs catching before the next release.
# Registry installs and the release matrix run on main (nightly or on demand)
# and on the cut PR, whose head is `main`: the last chance to catch a break
# against the published versions before it ships. Backports skip it.
- name: Released wire compatibility
id: wire-compat
if: ${{ !cancelled() && steps.setup.outcome == 'success' && github.ref == 'refs/heads/main' && github.event_name != 'pull_request' }}
if: ${{ !cancelled() && steps.setup.outcome == 'success' && ((github.ref == 'refs/heads/main' && github.event_name != 'pull_request') || (github.event_name == 'pull_request' && github.head_ref == 'main')) }}
run: nix develop --command just test wire-compat
shell: bash -leo pipefail {0}
env:
Expand Down
6 changes: 4 additions & 2 deletions js/json/src/snapshot/producer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -197,8 +197,10 @@ export class Producer<T> {
*/
mutate(fn: (value: T) => void, at: Time.Timestamp): void {
// Start from the last-published value, falling back to the configured initial value. We
// don't invent an empty object: mutating with nothing to start from is a usage error.
const base = this.#encoder.value ?? this.#initial;
// don't invent an empty object: mutating with nothing to start from is a usage error. A
// published JSON null is a value, so only `undefined` means nothing was published.
const published = this.#encoder.value;
const base = published !== undefined ? published : this.#initial;
if (base === undefined) {
throw new Error("mutate() requires a prior update() or `initial` in the config");
}
Expand Down
21 changes: 21 additions & 0 deletions js/json/src/snapshot/snapshot.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,27 @@ test("mutate starts from the configured initial value", async () => {
expect((await consumer.next())?.value).toEqual({ a: 1 });
});

// JSON null is a published value: mutate must hand it over rather than the stale `initial`, and
// must not refuse it as if nothing had been published.
test("mutate starts from a published null", async () => {
for (const initial of [undefined, { a: 1 }]) {
const track = new Track.Producer("test");
const producer = new Producer<Value | null>({ track, initial });
producer.update(null, key());

let seen: Value | null | undefined;
producer.mutate((v) => {
seen = v;
}, key());
expect(seen).toBeNull();
producer.finish();
const consumer = new Consumer<Value | null>({ track });
const states: (Value | null)[] = [];
for (let state = await consumer.latest(); state; state = await consumer.latest()) states.push(state.value);
expect(states).toEqual([null]);
}
});

// A rejected edit never reached the wire, so the next owner starts from the last value that did.
// Carrying the rejected edit forward would fail every later publish the same way. (Mirrors the Rust
// `a_rejected_edit_leaves_modify_at_the_last_written_value`.)
Expand Down
23 changes: 18 additions & 5 deletions quest/m2/auth-attach-downstream.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,23 @@ Until moq.pro reads `token`, it must not meet a relay with this change:
marked temporary migration in `rs/moq-auth/src/serve.rs`), but moq.pro has no
such reader for the new shape.

Rechecked 2026-11-20 by the main → release audit at moq.pro `828766e510`:
still unfixed. `rs/edge/src/auth/mod.rs` reads only `query_jwt(request.query)`
(`:1064`, `:1316` on `End`, `:1339` on `Attach` and `Revalidate`) and never
`request.token`, and no moq.pro quest owns the change. The planning PR lists
it as a follow-up for moq.pro's own `/quest-plan`, required by moq.pro's
[cut pin adoption](https://github.com/moq-dev/moq.pro/blob/main/quest/m0/adopt-cut-pin.md),
so moq.pro never runs a relay with this change before it reads `token`. Its
test presents distinct credentials through attach, revalidate, and end
against both the last released relay and the candidate.

## Waiting

- Maintainer: check the moq.pro and Kixel auth handlers read `attach` from
`token`, and fix one that does not before it meets a relay with this change.
An agent cannot read those private repositories from here. Done when both
handlers' tests present an attach whose `query` holds an expired `jwt` and
whose `token` holds a valid one.
- moq-dev/moq.pro: the edge auth handler reads an attached credential from
`token` on `attach`, `revalidate`, and `end`. Check with
`grep -n "request.token" rs/edge/src/auth/mod.rs` on moq.pro `main`, and a
test whose attach carries an expired `jwt` in `query` and a valid `token`.
- kixel-ai/kixel.ai: `Mesh.admit` (`src/mesh.ts:557`, rechecked 2026-11-20)
reads a `credential` query parameter on every event, `attach` included, and
its client attaches nothing yet. Before a Kixel client attaches, it reads
`token` there too; check the same way.
47 changes: 47 additions & 0 deletions quest/m2/time-addressing/range-table.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# [M] Rust and JS deliver the same groups from one range table

## Goal

One shared table of range cases pins which groups a subscription delivers, and both Rust and
`@moq/net` pass it. Each case gives a track's groups at the origin, what a copy holds
(complete, sparse, or partly evicted), a lite-07 range (a time start, a Position, or no anchor
with a Min Age, and a time end or none), and the exact group IDs delivered, plus whether the copy
must ask upstream. Every case runs direct from the origin, through a relay copy cold and warm, as
a late join, and across a route switch mid-read. The copy's answer always equals the origin's,
so the cut publishes lite-07 knowing the two implementations agree.

## Plan

Decided 2026-11-20 (maintainer, /quest-plan of the main → release audit): ✅ m2, so the cut
waits on it (rejected: m4 after the cut, since a divergence found then is a lite-07 behavior fix
after publication; dropping it for the per-language tests no relative anchors adds, which never
compare Rust with JS).

The audit reproduced why per-language tests weren't enough: with latest group 9, the same
`relative: 2` through `time: 8` subscription returned `[7, 8]` from a complete JS copy and `[1, 2]`
from one holding `[1, 2, 9]`. [No relative anchors](/quest/m2/time-addressing/no-relative-anchors.md)
removes that anchor, but a live join by Min Age and a time start resolve against holdings the
same way, and nothing compares the two languages' answers.

Recommended:

- One JSON fixture read by a Rust test and a `bun:test` file, as
`rs/moq-json/tests/window-vectors.json` and `js/json/src/window/vectors.test.ts` already
share one. Expected outputs are group IDs, never timings.
- Seed it with the audit's sparse-copy case restated without the relative anchor, and the cases
no relative anchors names: a Min Age reaching past what a copy holds, an oldest reader and a
live reader on one relay, a time start between held groups linked by Previous Start (which a
copy may answer from cache) and one that isn't (which must ask).
- The relayed run uses the real copy path in each language, so a JS copy under a Rust origin
is covered the way `just test relay-fill` already covers fills.
- Drive time with the manual clocks both test suites already use.

Public API: none. Wire: none; a divergence this finds is fixed under lite-07-wip before the cut.

## Required

- [No relative anchors](/quest/m2/time-addressing/no-relative-anchors.md) - the range shapes this table pins

## Related

- [A relay fetches a group's missing head](/quest/m1/missing-head-asks-upstream.md) - a partial group a copy holds is another case for the table
20 changes: 20 additions & 0 deletions quest/m3/release/cut.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,26 @@ observe withdrawal. All four paths passed on lite-06 with 0.17.17 and audited ma
Re-run the existing cut checks on the resolved merge and version bump. After publication,
check that Release remeasure opened or updated its pin PR, as RELEASE.md describes.

From the 2026-11-20 main → release audit (main `9828a20cab` against release `381b802d9b`: 4,241
main-only and 307 release-only commits, 330 paths conflicted in a trial merge), for the
candidate:
- Keep the behavior of release-only fixes while resolving conflicts, not just their text, and
run a test of each on the candidate: stopped-stream receive credit (`b834502dfa`, qmux 0.5.4
and `@moq/qmux` 0.3.5), a far-ahead group sequence costing a relay nothing extra
(`0c9ffdd7a7`, backport of [moq-dev/moq#9044](https://github.com/moq-dev/moq/pull/9044)), a
relay restarting under its old hop ID stranding nothing (`4a9005c3c5`), a 64-bit Hop ID read
as unknown in Rust and JS (`f48b7a066e`, `a480bba27c`), and a restarted publisher winning over
its lingering session (`5511441a02`). List the rest with
`git log --no-merges origin/main..origin/release`.
- Widen the two-relay smoke above: keep a reader attached through each roll, in both directions
(last published relay to candidate and back), and check it keeps receiving the same frames
after the roll and after a withdrawal and return.
- The cut PR (head `main`) now runs the full moq-transport matrix and Released wire
compatibility in its Release gate, which a backport PR still skips (planned by the audit's
PR). Read both results on the cut PR rather than repeating them by hand.
- Attach each result to the candidate SHA in the cut PR body, so a later push visibly
invalidates it.

## Required

- [Breaking release readiness](/quest/m2/README.md) - code, protocol and package proofs
Expand Down
13 changes: 13 additions & 0 deletions quest/m3/release/migrate-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,19 @@ m1 quest on 2026-10-22.
- moq-gst: the request pad's `encoder` property, shipped in
`moq-gst-v0.4.24`, was removed with no entry, so a `gst-launch` line
setting it now fails at runtime.
- moq-archive (added 2026-11-20, from the main → release audit):
`rs/moq-archive/MIGRATE.md`'s "Recording format version 4 drops the
datagram form" and "Recording format version 3 replaces version 1" are
wrong since [moq-dev/moq#8932](https://github.com/moq-dev/moq/pull/8932):
`VERSION` is 2, the only version written or read, and `Error::Form` is
gone. Replace both with #8932's Impact text: format version 2 replaces
version 1; start a new recording prefix; main builds' versions 2 to 4 are
unsupported; `Info::version` and `Error::Form` are removed and `Info` no
longer implements `Serialize`/`Deserialize` (use `Info::encode` and
`Info::decode`); keep a release build's reader for retained version 1
archives. Keep the `i8` priority and optional timescale notes, and check
the "Objects are keyed by timeline segment" entry's `Key::Segments`,
`Store::get_segments`, and `Error::Span`, none of which exist on `main`.

## Required

Expand Down
44 changes: 44 additions & 0 deletions quest/m4/route-forward-states.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# [L] A route's forwarding and advertising decide reachability in one place

## Goal

A lite-07 node decides once whether a broadcast is ready to forward, waiting for something
named, or unavailable, and both what it advertises and where it forwards a request follow that
one decision. A request that has to wait names what it waits for, and that event wakes it, so
no reader is refused for a broadcast the node still advertises, or left waiting for something
that will never arrive. The failover model covers a claim missing for a while and a live route
coming back, and an already attached reader resumes delivery in both.

## Plan

Decided 2026-11-20 (maintainer, /quest-plan of the main → release audit): ✅ m4, after the cut
(rejected: m2, which puts an L routing refactor right before the cut; dropping it and fixing
races one replay at a time). [moq-dev/moq#9231](https://github.com/moq-dev/moq/pull/9231)
fixed the race the audit found, and
[mesh replay violations](/quest/m0/nightly/mesh-replay-violations.md) owns the replay's open
strands. If that quest traces one to forwarding, move this quest up.

The shape today: `Node::forward` (`rs/moq-net/src/route/node.rs`) returns
`Option<Option<Via>>`, where the outer `None` waits and `Some(None)` refuses, and announce
discovery judges reachability from other facts. #9231's stranded reader came from that gap: a
route to the claimant existed before the next hop held its claim, `forward` refused for good,
and the reader had no reason to retry once the claim landed.

Recommended:

- One enum, such as `Ready(Via)`, `Waiting(Reason)`, and `Unavailable(Reason)`, computed by one
function that both the advertised availability and `poll_forward` read. A `Waiting` reason
names the event that wakes it, so `Unavailable` is terminal only when nothing advertised can
change it.
- Extend `rs/moq-net/verify/failover/FailoverChain.tla` with a claim that disappears and comes
back while its route stays up, and a route that leaves and returns live. Check that an attached
reader resumes in both (`/verify-failover`).
- Keep [route wakes](/quest/m4/route-wakes.md)'s write-once and targeted-wake goals in view: the
waiting reason is what lets a change wake only the requests it affects.

Public API: none expected. Wire: none.

## Related

- [Route wakes](/quest/m4/route-wakes.md) - which fronts a route change wakes
- [A lite-07 claim is shown no broader than its grants](/quest/m2/lite07-claim-reach-routes.md) - an advertised claim a request is then refused on
1 change: 1 addition & 0 deletions swift/Sources/Moq/Durations.swift
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ func checkSubscription(_ subscription: Subscription?) throws {

func checkTrackInfo(_ info: TrackInfo?) throws {
try checkDuration(info?.maxAge, "maxAge")
try checkDuration(info?.refresh.interval, "refresh.interval")
}

func checkFetch(_ options: FetchGroupOptions?) throws {
Expand Down
3 changes: 3 additions & 0 deletions swift/Tests/MoqTests/SmokeTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,9 @@ final class SmokeTests: XCTestCase {
var info = try broadcast.publishTrack(name: "info").consume().info()
info.maxAge = bad
assertConfig({ _ = try broadcast.publishTrack(name: "bad", info: info) }, "max age \(bad)")
info.maxAge = 0
info.refresh = TrackRefresh(interval: bad)
assertConfig({ _ = try broadcast.publishTrack(name: "bad", info: info) }, "refresh interval \(bad)")

var subscription = Subscription.default
subscription.delay.max = bad
Expand Down