diff --git a/.github/workflows/alert.yml b/.github/workflows/alert.yml index a256f39dfe3..58b91ea6dbe 100644 --- a/.github/workflows/alert.yml +++ b/.github/workflows/alert.yml @@ -22,6 +22,7 @@ on: # on every push to every PR. `just gh check` enforces both halves of that. workflows: - apt-repo + - Cache - Cachix - Docker - libmoq diff --git a/.github/workflows/cache.yml b/.github/workflows/cache.yml new file mode 100644 index 00000000000..36477c5f018 --- /dev/null +++ b/.github/workflows/cache.yml @@ -0,0 +1,110 @@ +name: Cache + +# Populates the Rust build cache that check.yml restores, and the dev shell +# closure that every nix job substitutes. +# +# Actions scopes cache reads to the current branch plus the default branch, so +# only a cache written here on `main` is reachable from a pull request. `main` +# is therefore the single writer and pull requests are readers (`save-if` in +# check.yml): one cache everyone can reach, rather than per-PR entries that fill +# the repository's 10 GB budget while remaining private to the PR that wrote +# them. +# +# This runs the unscoped suite rather than the diff-scoped one: the point is to +# leave artifacts for whatever a future PR happens to touch, not to check `main` +# (the PR that became `main` was already checked). It blocks nobody. + +permissions: + contents: read + +on: + push: + branches: [main] + # A docs-only merge can't change the build graph, so don't spend a runner. + paths: + - "rs/**" + - "Cargo.toml" + - "Cargo.lock" + - "rust-toolchain.toml" + - "flake.nix" + - "flake.lock" + - ".github/workflows/cache.yml" + # Priming a cold cache by hand, e.g. after a toolchain bump evicts everything. + workflow_dispatch: + +# Newest `main` wins; an older warm is worth less than the runner it holds. +concurrency: + group: cache-${{ github.ref }} + cancel-in-progress: true + +jobs: + warm: + name: Warm + runs-on: ubuntu-24.04-arm + timeout-minutes: 60 + + steps: + - name: Free disk space + uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # main + with: + tool-cache: false + + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main + with: + determinate: false + # Trust the flake's cachix substituter. `nixConfig` in flake.nix is + # untrusted by default, so nix logs "ignoring untrusted flake + # configuration setting 'extra-substituters'" and rebuilds from + # source anything missing from the public nixpkgs cache. That was + # costing 678s per job for uniffi-bindgen-go alone, in every job that + # enters the dev shell. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= + + # cachix.yml only fires on release tags and only pushes the tagged + # package, so the dev shell itself was never cached. Anything in it that + # nixpkgs doesn't serve prebuilt (uniffi-bindgen-go, a + # buildRustPackage from a git tag) was therefore compiled from source by + # every job that entered the shell. Push it once here so pull requests + # substitute it instead. + - uses: cachix/cachix-action@5f2d7c5294214f71b873db4b969586b980625e71 # v17 + with: + name: kixelated + authToken: ${{ secrets.CACHIX_AUTH_TOKEN }} + + - name: Cache the dev shell + run: | + # `--profile` realises the shell's full build closure, which is what + # the runners actually need; `nix build .#devShells...` alone leaves + # out the build-time inputs. + nix develop --profile /tmp/devshell --command true + cachix push kixelated /tmp/devshell + + # `shared-key` replaces the automatic per-job key, which is what lets + # check.yml's differently-named jobs restore what this one saves. + - name: Rust Cache + uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2 + with: + shared-key: rust + cache-on-failure: true + + # Both halves, so the saved cache carries the lint artifacts (clippy rmeta) + # and the test artifacts (codegen + linked test binaries). They share + # little, and a PR usually needs both. + - name: Check + run: nix develop --command just check-all + env: + MOQ_STRICT: 1 + + - name: Test + if: ${{ !cancelled() }} + run: nix develop --command just test all + env: + MOQ_STRICT: 1 + NEXTEST_PROFILE: ci diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index dc2a29976ef..18ae5d3ec23 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -17,14 +17,18 @@ concurrency: cancel-in-progress: true jobs: + # `check` and `test` are separate jobs because they share almost no build + # artifacts: clippy emits rmeta without codegen, while nextest codegens and + # links every test binary. Running them in sequence meant paying both in + # series for no reuse, so they run concurrently and the job takes the slower + # of the two rather than their sum. check: name: Check # Skip the actual work on close/merge: this run exists only to cancel the # superseded in-flight build via the concurrency group above. if: github.event.action != 'closed' runs-on: ubuntu-24.04-arm - # Backstop a hang (e.g. a wedged test) instead of holding the runner for the - # 6-hour default. Generous enough for a cold first build. + # Backstop a hang instead of holding the runner for the 6-hour default. timeout-minutes: 60 steps: @@ -43,17 +47,28 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter. `nixConfig` in flake.nix is + # untrusted by default, so nix logs "ignoring untrusted flake + # configuration setting 'extra-substituters'" and rebuilds from + # source anything missing from the public nixpkgs cache. That was + # costing 678s per job for uniffi-bindgen-go alone, in every job that + # enters the dev shell. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - uses: DeterminateSystems/flake-checker-action@de924abd783455e8429c858962b9e43062d19da1 # main - # Cache Rust dependencies and build artifacts via the Actions cache. + # Restore only. cache.yml is the single writer, on `main`; see the comment + # there for why. `shared-key` has to match the one it saves under. - name: Rust Cache uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2 with: - cache-on-failure: true + shared-key: rust + save-if: false - # The same two recipes a developer runs locally. Both diff against - # origin/$GITHUB_BASE_REF and touch only the packages this PR changed plus - # their dependents, so a one-crate PR compiles one crate. + # The same recipe a developer runs locally. It diffs against + # origin/$GITHUB_BASE_REF and touches only the packages this PR changed + # plus their dependents, so a one-crate PR compiles one crate. # # MOQ_STRICT turns every "tool missing, skipping" guard into an error. # Locally an absent formatter means less gets checked; here it would mean @@ -64,6 +79,44 @@ jobs: env: MOQ_STRICT: 1 + test: + name: Test + if: github.event.action != 'closed' + runs-on: ubuntu-24.04-arm + timeout-minutes: 60 + + steps: + - name: Free disk space + uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # main + with: + tool-cache: false + + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Full history so `just test` can diff against origin/$GITHUB_BASE_REF. + fetch-depth: 0 + + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main + with: + determinate: false + # Trust the flake's cachix substituter. `nixConfig` in flake.nix is + # untrusted by default, so nix logs "ignoring untrusted flake + # configuration setting 'extra-substituters'" and rebuilds from + # source anything missing from the public nixpkgs cache. That was + # costing 678s per job for uniffi-bindgen-go alone, in every job that + # enters the dev shell. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= + + - name: Rust Cache + uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2 + with: + shared-key: rust + save-if: false + # NEXTEST_PROFILE picks up the longer hang timeout in .config/nextest.toml; # without it a runner under load could trip the local one. - name: Test diff --git a/CLAUDE.md b/CLAUDE.md index ae7e1fbe172..1082226e7b4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,11 +24,13 @@ Use the Nix dev shell for project commands so local runs match CI tooling. If Ni To force a base, `just check origin/dev` and `just fix origin/dev` take it positionally. `just test` can't: it's a module, so `just test origin/dev` looks for a *recipe* named `origin/dev`. Name the recipe to get past that: `just test default origin/dev`. -**CI runs exactly these recipes: `just check` then `just test`, with `MOQ_STRICT=1`.** There is no separate `just ci`, so there is no second definition of "checked" to drift from this one. The split is by cost, not by environment: `check` lints and compiles (plus `tsc -b` and the Python docs, which catch what `--noEmit` and autodoc can't), while `test` links and runs the test binaries, which is the expensive half. +**CI runs exactly these recipes: `just check` and `just test`, with `MOQ_STRICT=1`.** There is no separate `just ci`, so there is no second definition of "checked" to drift from this one. The split is by cost, not by environment: `check` lints and compiles (plus `tsc -b` and the Python docs, which catch what `--noEmit` and autodoc can't), while `test` links and runs the test binaries, which is the expensive half. They run as concurrent jobs in `check.yml`, because clippy emits rmeta without codegen while nextest codegens and links, so there is nearly nothing for one to reuse from the other. + +The Rust build cache is written by `main` and read by pull requests, never the other way around (`.github/workflows/cache.yml`). Actions scopes cache reads to the current branch plus the default branch, so a PR-only workflow can never leave anything a *later* PR can restore. Both jobs in `check.yml` therefore restore under `shared-key: rust` with `save-if: false`. Don't add a save to a PR job: each one is gigabytes, the repository budget is 10 GB, and PR-scoped entries evict each other while remaining unreadable to everyone else. `MOQ_STRICT` is the one thing CI does differently. Every tool the checks use is guarded with `command -v` so an incomplete local toolchain checks less instead of failing; in CI that would be a green run that silently checked nothing, so the variable turns the required set into an up-front precondition (`_tools` in the root justfile). Required is per scope, mirroring what the diff actually dispatches, so a docs-only PR doesn't have to have gradle. -Two tools stay unrequired: `swift` exists only on macOS (swift.yml is its gate), and **`go`/`uniffi-bindgen-go` are not in the dev shell**, so `just go check` skips itself in CI exactly as it always has. `uniffi-bindgen-go` isn't in nixpkgs (it installs from a NordSecurity git tag), so closing that hole means packaging it in the flake. +One tool stays unrequired: `swift` exists only on macOS, so swift.yml is its gate rather than the PR path. Two gates live outside the PR path, in `.github/workflows/nightly.yml`: `just rs audit` (cargo-deny) because an advisory lands without this repo changing, and `just rs features` (the `--all-features` and `--no-default-features` compiles) because each is a full extra workspace compile that shares almost nothing with the default one. A break there lands on `main` rather than being caught in review, which is the accepted trade; anything that must block a merge belongs in `check`. diff --git a/Cargo.lock b/Cargo.lock index 203b66e7355..bf04d04d267 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -143,7 +143,7 @@ dependencies = [ "ndk-context", "ndk-sys", "num_enum", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -356,7 +356,7 @@ dependencies = [ "nom 7.1.3", "num-traits", "rusticata-macros", - "thiserror 2.0.19", + "thiserror 2.0.20", "time", ] @@ -441,9 +441,9 @@ dependencies = [ [[package]] name = "async-trait" -version = "0.1.91" +version = "0.1.92" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec" +checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667" dependencies = [ "proc-macro2", "quote", @@ -524,9 +524,9 @@ checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" [[package]] name = "aws-lc-rs" -version = "1.17.3" +version = "1.18.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "00bdb5da18dac48ca2cc7cd4a98e533e8635a58e2361d13a1a4ee3888e0d72f1" +checksum = "ce2b2dcc879c3bae0d371e77c99f2238400ef24ec001394befa67b6e543add9e" dependencies = [ "aws-lc-sys", "untrusted 0.7.1", @@ -535,9 +535,9 @@ dependencies = [ [[package]] name = "aws-lc-sys" -version = "0.43.0" +version = "0.44.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "43103168cc76fe62678a375e722fc9cb3a0146159ac5828bc4f0dfd755c2224c" +checksum = "f09fae7be8bb3174e05c6afdb34199e6dc0c7c04ba9fa237b1967adfbde27483" dependencies = [ "cc", "cmake", @@ -935,13 +935,13 @@ dependencies = [ [[package]] name = "bytemuck_derive" -version = "1.11.0" +version = "1.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f65693059b6b9c588b9f62fed1cedbf0a8b805631457ea162d68f0de186f3de5" +checksum = "fc0e56a716f1e132ff6bf4bdac1c944a3fcdc1cae65f70a4a2a1ac3b401d2d1f" dependencies = [ "proc-macro2", "quote", - "syn 2.0.119", + "syn 3.0.3", ] [[package]] @@ -1041,7 +1041,7 @@ dependencies = [ "semver", "serde", "serde_json", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -1071,9 +1071,9 @@ dependencies = [ [[package]] name = "cc" -version = "1.4.0" +version = "1.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9" +checksum = "5d262e149917187838d5b42777c8253bcb64500067342904e7d429499a6f277e" dependencies = [ "find-msvc-tools", "jobserver", @@ -1233,9 +1233,9 @@ dependencies = [ [[package]] name = "clap" -version = "4.6.5" +version = "4.6.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "301b56658598e48f3648647ac6fc887be7e7108eddfa4e9b63fcf3ec58c0cadf" +checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca" dependencies = [ "clap_builder", "clap_derive", @@ -1243,9 +1243,9 @@ dependencies = [ [[package]] name = "clap_builder" -version = "4.6.5" +version = "4.6.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "94a65403d1a1bd28f7dc68eb8506e8874808ee5eecb59298de588e2e1407a078" +checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889" dependencies = [ "anstream", "anstyle", @@ -1292,7 +1292,7 @@ version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0fa961b519f0b462e3a3b4a34b64d119eeaca1d59af726fe450bbba07a9fc0a1" dependencies = [ - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -1709,9 +1709,9 @@ dependencies = [ [[package]] name = "cudarc" -version = "0.19.8" +version = "0.19.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "42310153e06cf4cd532901f7096beb27504d681736a29ee90728ae4e2d93b2a8" +checksum = "804764d10e844da09765a7b2ca9641a0851523d1702efb0d7299d73e31b86e80" dependencies = [ "libloading 0.9.0", ] @@ -1903,6 +1903,37 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9377eb110cece2e9431deb8d7d2ec8c116510b896741f9f2bf02b352147aa2a6" +[[package]] +name = "defmt" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e2953bfe4f93bbd20cc71198842756f77d161884c99ebbabc41d80231ded88d1" +dependencies = [ + "bitflags 1.3.2", + "defmt-macros", +] + +[[package]] +name = "defmt-macros" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bad9c72e7ca2137e0dc3813245a0d282fd6daad32fd800af018306a9169b5fe8" +dependencies = [ + "defmt-parser", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "defmt-parser" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10d60334b3b2e7c9d91ef8150abfb6fa4c1c39ebbcf4a81c2e346aad939fee3e" +dependencies = [ + "thiserror 2.0.20", +] + [[package]] name = "der" version = "0.7.10" @@ -2132,6 +2163,18 @@ dependencies = [ "winapi", ] +[[package]] +name = "dns-lookup" +version = "3.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e39034cee21a2f5bbb66ba0e3689819c4bb5d00382a282006e802a7ffa6c41d" +dependencies = [ + "cfg-if", + "libc", + "socket2 0.6.5", + "windows-sys 0.60.2", +] + [[package]] name = "document-features" version = "0.2.12" @@ -2289,13 +2332,13 @@ checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099" [[package]] name = "enum-assoc" -version = "1.3.0" +version = "1.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3ed8956bd5c1f0415200516e78ff07ec9e16415ade83c056c230d7b7ea0d55b7" +checksum = "872ece5a3d5aa63541e400219676c38e8f5474cf3366834c3f2d1fe23d29bc55" dependencies = [ "proc-macro2", "quote", - "syn 2.0.119", + "syn 3.0.3", ] [[package]] @@ -2396,7 +2439,7 @@ dependencies = [ "cfg-if", "document-features", "num-traits", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -2438,9 +2481,9 @@ checksum = "64cd1e32ddd350061ae6edb1b082d7c54915b5c672c389143b9a63403a109f24" [[package]] name = "find-msvc-tools" -version = "0.1.9" +version = "0.1.10" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" +checksum = "26b73573e6edcd2af0cdf47bd6cb58f0b3839491263c314eaad1ccf24430e1de" [[package]] name = "fixed-resample" @@ -2640,9 +2683,9 @@ dependencies = [ [[package]] name = "futures" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218" +checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3" dependencies = [ "futures-channel", "futures-core", @@ -2668,9 +2711,9 @@ dependencies = [ [[package]] name = "futures-channel" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae" +checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4" dependencies = [ "futures-core", "futures-sink", @@ -2678,15 +2721,15 @@ dependencies = [ [[package]] name = "futures-core" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" [[package]] name = "futures-executor" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458" +checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432" dependencies = [ "futures-core", "futures-task", @@ -2695,9 +2738,9 @@ dependencies = [ [[package]] name = "futures-io" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a" +checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" [[package]] name = "futures-lite" @@ -2714,26 +2757,26 @@ dependencies = [ [[package]] name = "futures-macro" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" dependencies = [ "proc-macro2", "quote", - "syn 2.0.119", + "syn 3.0.3", ] [[package]] name = "futures-sink" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" [[package]] name = "futures-task" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" [[package]] name = "futures-timer" @@ -2743,9 +2786,9 @@ checksum = "af43fadb8a98512d547e37b4e92e0ced13e205c061b87b4623eff01d918d6968" [[package]] name = "futures-util" -version = "0.3.33" +version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" dependencies = [ "futures-channel", "futures-core", @@ -3023,7 +3066,7 @@ dependencies = [ "hashbrown 0.16.1", "log", "presser", - "thiserror 2.0.19", + "thiserror 2.0.20", "windows", ] @@ -3070,7 +3113,7 @@ dependencies = [ "paste", "pin-project-lite", "smallvec", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -3151,7 +3194,7 @@ dependencies = [ "serde", "serde_json", "serde_with", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -3236,7 +3279,7 @@ dependencies = [ "jni 0.22.4", "rand 0.10.2", "rustls", - "thiserror 2.0.19", + "thiserror 2.0.20", "tinyvec", "tokio", "tokio-rustls", @@ -3258,7 +3301,7 @@ dependencies = [ "prefix-trie", "rand 0.10.2", "ring", - "thiserror 2.0.19", + "thiserror 2.0.20", "tinyvec", "tracing", "url", @@ -3286,7 +3329,7 @@ dependencies = [ "rustls", "smallvec", "system-configuration", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-rustls", "tracing", @@ -3352,9 +3395,9 @@ dependencies = [ [[package]] name = "http-body-util" -version = "0.1.4" +version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" dependencies = [ "bytes", "futures-core", @@ -4018,6 +4061,59 @@ version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +[[package]] +name = "jiff" +version = "0.2.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "668b7183bd07af9a4885f5c35b0cc5c83c4607a913c16b7e17291832910d2dcc" +dependencies = [ + "defmt", + "jiff-core", + "jiff-static", + "jiff-tzdb-platform", + "log", + "portable-atomic", + "portable-atomic-util", + "serde_core", + "windows-link", +] + +[[package]] +name = "jiff-core" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7feca88439efe53da3754500c1851dedf3cb36c524dd5cf8225cc0794de95d09" +dependencies = [ + "defmt", +] + +[[package]] +name = "jiff-static" +version = "0.2.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a69dcb3a21cfb32ce1cd056169337ca284af0766dd766e7878819b251a49204" +dependencies = [ + "jiff-core", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "jiff-tzdb" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "142bd39932ad231f10513df9ab62661fead8719872150b7ad02a2df79f4e141e" + +[[package]] +name = "jiff-tzdb-platform" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "875a5a69ac2bab1a891711cf5eccbec1ce0341ea805560dcd90b7a2e925132e8" +dependencies = [ + "jiff-tzdb", +] + [[package]] name = "jni" version = "0.21.1" @@ -4046,7 +4142,7 @@ dependencies = [ "jni-sys 0.4.1", "log", "simd_cesu8", - "thiserror 2.0.19", + "thiserror 2.0.20", "walkdir", "windows-link", ] @@ -4123,7 +4219,7 @@ dependencies = [ "jsonptr", "serde", "serde_json", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -4269,7 +4365,7 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981" [[package]] name = "libmoq" -version = "0.5.6" +version = "0.5.7" dependencies = [ "anyhow", "bytes", @@ -4277,13 +4373,14 @@ dependencies = [ "hang", "moq-audio", "moq-json", + "moq-loc", "moq-mux", "moq-native", "moq-net", "moq-video", "pollster", "serde_json", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -4298,7 +4395,7 @@ dependencies = [ "bitflags 2.13.1", "libc", "plain", - "redox_syscall 0.9.1", + "redox_syscall 0.9.2", ] [[package]] @@ -4535,9 +4632,9 @@ dependencies = [ [[package]] name = "moka" -version = "0.12.15" +version = "0.12.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "957228ad12042ee839f93c8f257b62b4c0ab5eaae1d4fa60de53b27c9d7c5046" +checksum = "4293f18e7567a1caf3c584855554377025c65e0aa445344d04171f5ad63d19b9" dependencies = [ "async-lock", "crossbeam-channel", @@ -4574,7 +4671,7 @@ dependencies = [ "rand 0.10.2", "rubato", "sonora", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "unsafe-libopus", @@ -4601,7 +4698,7 @@ dependencies = [ [[package]] name = "moq-boy" -version = "0.4.6" +version = "0.4.7" dependencies = [ "anyhow", "boytacean", @@ -4621,7 +4718,7 @@ dependencies = [ [[package]] name = "moq-cli" -version = "0.9.9" +version = "0.9.10" dependencies = [ "anyhow", "axum", @@ -4653,7 +4750,7 @@ dependencies = [ [[package]] name = "moq-ffi" -version = "0.3.9" +version = "0.3.10" dependencies = [ "bytes", "hang", @@ -4665,7 +4762,7 @@ dependencies = [ "moq-video", "pollster", "serde_json", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "uniffi", @@ -4678,7 +4775,7 @@ version = "0.1.1" dependencies = [ "bytes", "flate2", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -4701,7 +4798,7 @@ dependencies = [ [[package]] name = "moq-hls" -version = "0.4.6" +version = "0.4.7" dependencies = [ "anyhow", "axum", @@ -4715,7 +4812,7 @@ dependencies = [ "percent-encoding", "rand 0.10.2", "reqwest", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tower", "tracing", @@ -4735,7 +4832,7 @@ dependencies = [ "serde", "serde_json", "serde_path_to_error", - "thiserror 2.0.19", + "thiserror 2.0.20", "tracing", ] @@ -4745,7 +4842,7 @@ version = "0.2.1" dependencies = [ "bytes", "moq-net", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -4759,7 +4856,7 @@ dependencies = [ [[package]] name = "moq-mux" -version = "0.9.5" +version = "0.9.6" dependencies = [ "anyhow", "base64 0.23.1", @@ -4781,7 +4878,7 @@ dependencies = [ "serde", "serde_json", "serde_with", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -4790,12 +4887,13 @@ dependencies = [ [[package]] name = "moq-native" -version = "0.19.9" +version = "0.19.10" dependencies = [ "anyhow", "bytes", "chrono", "clap", + "dns-lookup", "flume", "futures", "hex", @@ -4824,7 +4922,7 @@ dependencies = [ "socket2 0.6.5", "subtle", "tempfile", - "thiserror 2.0.19", + "thiserror 2.0.20", "tikv-jemalloc-ctl", "tikv-jemallocator", "time", @@ -4847,7 +4945,7 @@ dependencies = [ [[package]] name = "moq-net" -version = "0.2.10" +version = "0.2.11" dependencies = [ "bytes", "criterion", @@ -4859,7 +4957,7 @@ dependencies = [ "rand 0.10.2", "serde", "serde_json", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "wasm-bindgen-test", @@ -4878,7 +4976,7 @@ dependencies = [ [[package]] name = "moq-relay" -version = "0.14.9" +version = "0.14.10" dependencies = [ "anyhow", "axum", @@ -4907,7 +5005,7 @@ dependencies = [ "serde_with", "sysinfo", "tempfile", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-rustls", "toml 1.1.4+spec-1.1.0", @@ -4932,7 +5030,7 @@ dependencies = [ "moq-net", "reqwest", "str0m", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -4957,7 +5055,7 @@ dependencies = [ "rustls", "sha2", "socket2 0.6.5", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-rustls", "tracing", @@ -4973,7 +5071,7 @@ dependencies = [ "moq-mux", "moq-net", "srt-tokio", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", ] @@ -4987,7 +5085,7 @@ dependencies = [ "moq-net", "serde", "serde_json", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "web-async", @@ -5008,7 +5106,7 @@ dependencies = [ "serde", "serde_json", "serde_with", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", ] @@ -5024,7 +5122,7 @@ dependencies = [ [[package]] name = "moq-transcode" -version = "0.0.9" +version = "0.0.10" dependencies = [ "anyhow", "bytes", @@ -5034,7 +5132,7 @@ dependencies = [ "moq-native", "moq-net", "moq-video", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -5057,7 +5155,7 @@ dependencies = [ [[package]] name = "moq-video" -version = "0.0.15" +version = "0.0.16" dependencies = [ "anyhow", "ashpd", @@ -5089,7 +5187,7 @@ dependencies = [ "openh264-sys2", "pipewire", "pollster", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "v4l", @@ -5109,7 +5207,7 @@ dependencies = [ "getrandom 0.4.3", "js-sys", "moq-net", - "thiserror 2.0.19", + "thiserror 2.0.20", "tracing-wasm", "url", "wasm-bindgen", @@ -5146,9 +5244,9 @@ dependencies = [ [[package]] name = "mpeg2ts" -version = "0.6.0" +version = "0.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7541fc1a42604cbd10e8607a4e6d4b231db982888fe8065ccb191b751d6368d6" +checksum = "83c1d679004305ea6e44eb53526da5816934a05b4b5b3b9a470e708a41d70a18" [[package]] name = "mpeg4-audio-const" @@ -5250,7 +5348,7 @@ dependencies = [ "once_cell", "rustc-hash 1.1.0", "spirv", - "thiserror 2.0.19", + "thiserror 2.0.20", "unicode-ident", ] @@ -5263,7 +5361,7 @@ dependencies = [ "hashbrown 0.17.1", "indexmap 2.14.0", "rustc-hash 1.1.0", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -5394,7 +5492,7 @@ dependencies = [ "log", "netlink-packet-core", "netlink-sys", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -5500,7 +5598,7 @@ dependencies = [ "rustc-hash 2.1.3", "rustls", "socket2 0.6.5", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-stream", "tracing", @@ -5532,7 +5630,7 @@ dependencies = [ "rustls-platform-verifier", "slab", "sorted-index-buffer", - "thiserror 2.0.19", + "thiserror 2.0.20", "tinyvec", "tracing", "web-time", @@ -5664,9 +5762,9 @@ dependencies = [ [[package]] name = "num-integer" -version = "0.1.46" +version = "0.1.47" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" dependencies = [ "num-traits", ] @@ -6376,7 +6474,7 @@ dependencies = [ "futures-sink", "js-sys", "pin-project-lite", - "thiserror 2.0.19", + "thiserror 2.0.20", "tracing", ] @@ -6409,7 +6507,7 @@ dependencies = [ "opentelemetry", "percent-encoding", "rand 0.9.5", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -6793,9 +6891,9 @@ dependencies = [ [[package]] name = "portable-atomic" -version = "1.14.0" +version = "1.15.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3" +checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85" dependencies = [ "serde", ] @@ -6999,7 +7097,7 @@ dependencies = [ "memchr", "parking_lot", "procfs", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -7112,7 +7210,7 @@ dependencies = [ "bytes", "futures", "rustls", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-rustls", "tokio-tungstenite", @@ -7185,7 +7283,7 @@ dependencies = [ "rustc-hash 2.1.3", "rustls", "socket2 0.6.5", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "web-time", @@ -7211,7 +7309,7 @@ dependencies = [ "rustls-pki-types", "rustls-platform-verifier", "slab", - "thiserror 2.0.19", + "thiserror 2.0.20", "tinyvec", "tracing", "web-time", @@ -7401,9 +7499,9 @@ dependencies = [ [[package]] name = "rcgen" -version = "0.14.8" +version = "0.14.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "57f6d249aad744e274e682777a50283a225a32705394ee6d5fcc01efa25e4055" +checksum = "091e7a8e7d86e6feb87a27ce8e2cba29d49eff9507afeebefab7eeb2ca667fb4" dependencies = [ "aws-lc-rs", "pem", @@ -7434,9 +7532,9 @@ dependencies = [ [[package]] name = "redox_syscall" -version = "0.9.1" +version = "0.9.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "07507be7b4a5f9f26eeb41eeaebb1f5a7ff29dfb29739facc21d35bf8b11c21e" +checksum = "f1c93da5bb2c5d4e6c0ef7abeead62c89169a0a4882bfb83ac892f2423aea2fe" dependencies = [ "bitflags 2.13.1", ] @@ -7544,7 +7642,7 @@ dependencies = [ "async-trait", "http", "reqwest", - "thiserror 2.0.19", + "thiserror 2.0.20", "tower-service", ] @@ -7772,9 +7870,9 @@ checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f" [[package]] name = "rustls-webpki" -version = "0.103.13" +version = "0.103.14" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e" +checksum = "0527518605e68109d875e248ea259b6758801cf165e4b2c2733ae3b51f12535a" dependencies = [ "aws-lc-rs", "ring", @@ -7892,9 +7990,9 @@ dependencies = [ [[package]] name = "sctp-proto" -version = "0.10.2" +version = "0.10.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "801033d212d17c3ad6b523c3fb3a41de323707b10b75cb437d05d5eff3b15204" +checksum = "f895c3c33ae20283f9129bd09db2ca69138798b372ef2b98bd2946d23ea4819b" dependencies = [ "bytes", "crc", @@ -7902,7 +8000,7 @@ dependencies = [ "rand 0.9.5", "rustc-hash 2.1.3", "slab", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -8152,9 +8250,9 @@ dependencies = [ [[package]] name = "serde_with" -version = "3.21.0" +version = "3.22.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "76a5c54c7310e7b8b9577c286d7e399ddd876c3e12b3ed917a8aabc4b96e9e8c" +checksum = "ee78f1fbe43ac4a0e47aadb3dbd357b69eb0d3793e948624cd03dd2750ab1c0a" dependencies = [ "base64 0.22.1", "bs58", @@ -8162,6 +8260,7 @@ dependencies = [ "hex", "indexmap 1.9.3", "indexmap 2.14.0", + "jiff", "schemars 0.9.0", "schemars 1.2.2", "serde_core", @@ -8172,9 +8271,9 @@ dependencies = [ [[package]] name = "serde_with_macros" -version = "3.21.0" +version = "3.22.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "84d57bc0c8b9a17920c178daa6bb924850d54a9c97ab45194bb8c17ad66bb660" +checksum = "8705578779c2b6bd90d84d66eb2e206b708b1a4d7b9f17641b293545bf1c7e46" dependencies = [ "darling 0.23.0", "proc-macro2", @@ -8344,7 +8443,7 @@ checksum = "0d585997b0ac10be3c5ee635f1bab02d512760d14b7c468801ac8a01d9ae5f1d" dependencies = [ "num-bigint", "num-traits", - "thiserror 2.0.19", + "thiserror 2.0.20", "time", ] @@ -9002,11 +9101,11 @@ dependencies = [ [[package]] name = "thiserror" -version = "2.0.19" +version = "2.0.20" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9" +checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f" dependencies = [ - "thiserror-impl 2.0.19", + "thiserror-impl 2.0.20", ] [[package]] @@ -9022,9 +9121,9 @@ dependencies = [ [[package]] name = "thiserror-impl" -version = "2.0.19" +version = "2.0.20" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd" +checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af" dependencies = [ "proc-macro2", "quote", @@ -9229,7 +9328,7 @@ dependencies = [ "slog-stdlog", "smallvec", "task-killswitch", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-stream", "tokio-util", @@ -9687,7 +9786,7 @@ dependencies = [ "rustls", "rustls-pki-types", "sha1", - "thiserror 2.0.19", + "thiserror 2.0.20", ] [[package]] @@ -10276,7 +10375,7 @@ version = "0.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "48465a648c14f53f6d8319b95bc336a44627f6aa6bd94270463777af8ed65deb" dependencies = [ - "thiserror 2.0.19", + "thiserror 2.0.20", "wasm-bindgen", "wasm-bindgen-futures", "web-sys", @@ -10334,7 +10433,7 @@ dependencies = [ "noq", "rustls", "rustls-native-certs", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -10351,7 +10450,7 @@ dependencies = [ "bytes", "http", "sfv", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "url", ] @@ -10369,7 +10468,7 @@ dependencies = [ "http", "kio 0.5.4 (registry+https://github.com/rust-lang/crates.io-index)", "rustls-pki-types", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tokio-quiche", "tracing", @@ -10391,7 +10490,7 @@ dependencies = [ "quinn", "rustls", "rustls-native-certs", - "thiserror 2.0.19", + "thiserror 2.0.20", "tokio", "tracing", "url", @@ -10416,7 +10515,7 @@ checksum = "e34a61f3c0bdb11d0fe4bb9813f4cdae82c1a19171afa5fa19e0c628b60f999b" dependencies = [ "bytes", "js-sys", - "thiserror 2.0.19", + "thiserror 2.0.20", "url", "wasm-bindgen", "wasm-bindgen-futures", @@ -10515,7 +10614,7 @@ dependencies = [ "raw-window-handle", "rustc-hash 1.1.0", "smallvec", - "thiserror 2.0.19", + "thiserror 2.0.20", "wgpu-core-deps-apple", "wgpu-core-deps-emscripten", "wgpu-core-deps-windows-linux-android", @@ -10596,7 +10695,7 @@ dependencies = [ "renderdoc-sys", "smallvec", "static_assertions", - "thiserror 2.0.19", + "thiserror 2.0.20", "wasm-bindgen", "wayland-sys", "web-sys", @@ -10647,9 +10746,9 @@ dependencies = [ [[package]] name = "wide" -version = "1.5.0" +version = "1.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dfdfe6a32973f2d1b268b8895845a8a96cac2f0191e72c27cc929036060dbf89" +checksum = "de2aaf408e58689c2096682331b1f42bb2d9f2ed6b11560407d023cd0a6c634e" dependencies = [ "bytemuck", "safe_arch", @@ -11162,7 +11261,7 @@ dependencies = [ "futures", "log", "serde", - "thiserror 2.0.19", + "thiserror 2.0.20", "windows", "windows-core", ] @@ -11197,7 +11296,7 @@ dependencies = [ "pharos", "rustc_version", "send_wrapper", - "thiserror 2.0.19", + "thiserror 2.0.20", "wasm-bindgen", "wasm-bindgen-futures", "web-sys", @@ -11261,7 +11360,7 @@ dependencies = [ "oid-registry", "ring", "rusticata-macros", - "thiserror 2.0.19", + "thiserror 2.0.20", "time", ] @@ -11292,9 +11391,9 @@ checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56" [[package]] name = "xml-rs" -version = "0.8.28" +version = "0.8.29" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3ae8337f8a065cfc972643663ea4279e04e7256de865aa66fe25cec5fb912d3f" +checksum = "e450f9b2ed1dff33c94c12589a87338689467b9c4f5d8a5710bd09a847d2c8a7" [[package]] name = "xmltree" @@ -11361,18 +11460,18 @@ dependencies = [ [[package]] name = "yuv" -version = "0.8.16" +version = "0.8.17" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5d85a782d94ee43f078bcfd6fa82d4e6a5b2d1cfbbad168e4df5a9f7b39ef48c" +checksum = "220655e1c245693beb13b377d3174b9efcb1645018d1d4ec53903fc211b135ae" dependencies = [ "num-traits", ] [[package]] name = "zbus" -version = "5.18.0" +version = "5.19.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fe18fb60dc696039e738717b76eaea21e7a4489bbb1885020b43c94236d7e98a" +checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907" dependencies = [ "async-broadcast", "async-recursion", @@ -11400,14 +11499,14 @@ dependencies = [ [[package]] name = "zbus_macros" -version = "5.18.0" +version = "5.19.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fe96480bed92df2b442a1a30df364e12d08eed03aeb061f2b8dc6afb2be91119" +checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40" dependencies = [ "proc-macro-crate", "proc-macro2", "quote", - "syn 2.0.119", + "syn 3.0.3", "zbus_names", "zvariant", "zvariant_utils", @@ -11424,20 +11523,29 @@ dependencies = [ "zvariant", ] +[[package]] +name = "zcheapstr" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1afec51604565183aeb5c54c20aeab286120d4e4460f7f76e3e8bb8c0d99473" +dependencies = [ + "serde", +] + [[package]] name = "zerocopy" -version = "0.8.55" +version = "0.8.56" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb" +checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb" dependencies = [ "zerocopy-derive", ] [[package]] name = "zerocopy-derive" -version = "0.8.55" +version = "0.8.56" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb" +checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1" dependencies = [ "proc-macro2", "quote", @@ -11554,9 +11662,9 @@ dependencies = [ [[package]] name = "zune-core" -version = "0.5.1" +version = "0.5.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9" +checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b" [[package]] name = "zune-jpeg" @@ -11569,40 +11677,41 @@ dependencies = [ [[package]] name = "zvariant" -version = "5.13.1" +version = "5.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bee2a0bcd2a907786a456fff45aaaaf54c9ba5f50b71ae9ec1a4edd200c94911" +checksum = "b5e28c25bd8bb8da5a1f3e7065d0c156b9ee9a7973adf78b0e35eaefdf3b1b5c" dependencies = [ "endi", "enumflags2", "serde", "winnow 1.0.4", + "zcheapstr", "zvariant_derive", "zvariant_utils", ] [[package]] name = "zvariant_derive" -version = "5.13.1" +version = "5.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "38a708216a18780796770bfe3f4739c7c83a3e8f789b755534bbbc06e4e23e12" +checksum = "d496a145685283b67e232bd9e47377f6b60ad9d51e3601b23867f77c42477f96" dependencies = [ "proc-macro-crate", "proc-macro2", "quote", - "syn 2.0.119", + "syn 3.0.3", "zvariant_utils", ] [[package]] name = "zvariant_utils" -version = "3.5.0" +version = "4.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "90cb9383f9b45290407a1258b202d3f8f01db719eb60b4e4055c6375af4fc7c7" +checksum = "629d80ece222cad20fe0e8741be493c4ab166acf3b85341bdc2cdbcfd8f3c2d6" dependencies = [ "proc-macro2", "quote", "serde", - "syn 2.0.119", + "syn 3.0.3", "winnow 1.0.4", ] diff --git a/Cargo.toml b/Cargo.toml index 3249b0e01f9..4f1a9ed176b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -86,7 +86,7 @@ loom = { version = "0.7.2", features = ["futures"] } mdns-sd = { version = "0.20", features = ["async"] } moq-audio = { version = "0.0.17", path = "rs/moq-audio" } moq-flate = { version = "0.1.1", path = "rs/moq-flate" } -moq-hls = { version = "0.4.6", path = "rs/moq-hls", default-features = false } +moq-hls = { version = "0.4.7", path = "rs/moq-hls", default-features = false } moq-json = { version = "0.3.3", path = "rs/moq-json" } moq-loc = { version = "0.2", path = "rs/moq-loc" } moq-msf = { version = "0.4", path = "rs/moq-msf" } @@ -108,7 +108,7 @@ moq-token-cli = { version = "0.5", path = "rs/moq-token-cli" } # can leave them off to drop the CUDA dependencies. Both crates still default # them on when depended on directly. VAAPI is opt-in everywhere, since that # backend has never been validated on real hardware. -moq-transcode = { version = "0.0.9", path = "rs/moq-transcode", default-features = false } +moq-transcode = { version = "0.0.10", path = "rs/moq-transcode", default-features = false } # Standalone crate (moq-dev/vaapi); vendored from cros-libva + cros-codecs. # dlopen's libva at runtime (no libva-dev at build, no NEEDED libva in the binary). moq-vaapi = "0.0.3" @@ -117,7 +117,7 @@ moq-vaapi = "0.0.3" # builds, which want the codecs and not the device stack. Adding # `features = ["capture"]` to a consumer that ships in those bindings pulls the # whole device graph into every one of them. -moq-video = { version = "0.0.15", path = "rs/moq-video", default-features = false } +moq-video = { version = "0.0.16", path = "rs/moq-video", default-features = false } percent-encoding = "2" qmux = { version = "0.5.0", default-features = false } serde = { version = "1", features = ["derive"] } @@ -138,6 +138,14 @@ web-transport-trait = "0.4" [profile.dev] panic = "abort" +# Full DWARF is what makes a debug build enormous: the debug `libmoq_ffi.a` +# measured 619 MiB against a 100 MiB ceiling for the published one, and a +# workspace of those fills a laptop (and a CI runner) fast. Line tables keep +# what we actually read -- file and line in every backtrace and panic -- and +# drop the variable and type records only an interactive debugger uses. Reach +# for `debug = true` in a temporary edit if you need to step through something +# in lldb. `profile.test` inherits this. +debug = "line-tables-only" # Optimize the bignum crates even in dev/test builds. RSA keygen is bignum # arithmetic in a loop, and unoptimized it is orders of magnitude slower: the diff --git a/bun.lock b/bun.lock index 4276ac4f695..12b245612ff 100644 --- a/bun.lock +++ b/bun.lock @@ -98,7 +98,7 @@ }, "js/hang": { "name": "@moq/hang", - "version": "0.3.4", + "version": "0.3.5", "dependencies": { "@kixelated/libavjs-webcodecs-polyfill": "^0.5.5", "@libav.js/variant-opus-af": "^6.9.8", @@ -202,7 +202,7 @@ }, "js/publish": { "name": "@moq/publish", - "version": "0.4.3", + "version": "0.4.4", "dependencies": { "@moq/hang": "workspace:^", "@moq/net": "workspace:^", @@ -221,7 +221,7 @@ }, "js/signals": { "name": "@moq/signals", - "version": "0.2.1", + "version": "0.2.2", "devDependencies": { "@types/bun": "^1.3.11", "@types/react": "^19.2.18", @@ -1294,10 +1294,10 @@ "mdast-util-to-string": ["mdast-util-to-string@4.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0" } }, "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg=="], - "mediabunny": ["mediabunny@1.51.0", "", { "dependencies": { "@types/dom-mediacapture-transform": "^0.1.11", "@types/dom-webcodecs": "0.1.13" } }, "sha512-u327374xU8Ho0gCaMII7fUK8t0PnqkabCox1k8uUwvgvGb9o6YQGZEG2Qr4DTe7nTMpzfL7ukgnHDvDROySZ+Q=="], - "media-captions": ["media-captions@0.0.18", "", {}, "sha512-JW18P6FuHdyLSGwC4TQ0kF3WdNj/+wMw2cKOb8BnmY6vSJGtnwJ+vkYj+IjHOV34j3XMc70HDeB/QYKR7E7fuQ=="], + "mediabunny": ["mediabunny@1.53.1", "", { "dependencies": { "@types/dom-mediacapture-transform": "^0.1.11", "@types/dom-webcodecs": "0.1.13" } }, "sha512-w25gA6mQuHSLzdpWswqwndbKtHFcJ0IRowJaIHgY7rlJaVTHhomfx5mLq4IHqonrsGCGDE/LIrtXz8mxiDzavA=="], + "merge-anything": ["merge-anything@5.1.7", "", { "dependencies": { "is-what": "^4.1.8" } }, "sha512-eRtbOb1N5iyH0tkQDAoQ4Ipsp/5qSR79Dzrz8hEPxRX10RWWR/iQXdoKmBSRCThY1Fh5EhISDtpSc93fpxUniQ=="], "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="], diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 5ef7f55056f..1daf27e7d59 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -5,7 +5,7 @@ description: Command-line tools for MoQ media # FFmpeg / moq-cli -`moq-cli` is a media router: it wires one endpoint onto a shared MoQ Origin. It +`moq-cli` is a media router: it wires endpoints onto a shared MoQ Origin. It moves media into MoQ from a source, out of MoQ to a sink, or plays a broadcast locally, bridging stdin/stdout (via FFmpeg), HLS, RTMP, SRT, and WebRTC. @@ -74,6 +74,7 @@ Each signal writes a numbered `/tmp/moq.heap.*.heap` profile for analysis with ``` moq [endpoint options] +moq [-- ]... moq play [playback options] ``` @@ -88,18 +89,24 @@ moq play [playback options] - `--cluster-lan` meshes with every other participating process on the LAN via mDNS, no relay or internet needed. See [LAN Cluster](#lan-cluster-mdns). - Any combination may be given at once (e.g. dial a relay *and* accept incoming - sessions). `--origin ` pins the process's origin id (default: fresh and - random per run); see [Redundant Publishers](#redundant-publishers-11). +Any combination may be given at once (e.g. dial a relay *and* accept incoming +sessions). `--origin ` pins the process's origin id (default: fresh and +random per run); see [Redundant Publishers](#redundant-publishers-11). + - **`import`** routes media INTO MoQ (a source fills the Origin); **`export`** routes it OUT (a sink drains the Origin). The verb fixes the data direction. + - **`play`** subscribes to a broadcast and plays its audio and video locally. + - **endpoint** is one subcommand: a container format (`avc3`, `fmp4`, `ts`, `flv` read from stdin on import; `fmp4`, `mkv`, `ts`, `flv` written to stdout on export), or a gateway (`hls`, `rtmp`, `srt`, `rtc`). For the bidirectional gateways, `--connect` dials out and `--listen` binds a socket; the parent verb decides whether that pushes or pulls. +- **`--`** starts another stage, where a stage is one `import` or `export` with + its endpoint. See [Multiple Stages](#multiple-stages). + Run `moq import --help` / `moq export --help` to see the endpoints, and `moq import rtmp --help` for a specific one. @@ -245,6 +252,51 @@ Because the proofs are HMACs over a public nonce, a weak key can be brute-forced offline by anyone watching the network. Generate 32 random bytes as above rather than choosing something memorable. +### Multiple Stages + +One `moq` process bridges one broadcast by default. Separate stages with `--` to +bridge several over a single connection, each naming its own `--broadcast`: + +```bash +moq --connect https://relay.example.com/anon \ + import --broadcast cam1.hang rtmp --listen 0.0.0.0:1935 \ + -- import --broadcast cam2.hang rtmp --listen 0.0.0.0:1936 +``` + +Stages may run in opposite directions, so one process can ingest and re-publish +without a second connection or a second copy of the media: + +```bash +moq --connect https://relay.example.com/anon \ + import --broadcast event.hang srt --listen 0.0.0.0:9000 \ + -- export --broadcast event.hang hls --listen 0.0.0.0:8080 +``` + +Every stage shares one connection, one origin id, and one Origin, and each keeps +its own `--help` (`moq import rtmp --help`). A stage without `--broadcast` falls +back to the process-wide one, so a single-stage command can keep naming the +broadcast before the verb. + +Rules worth knowing: + +- The first stage to finish (stdin EOF, Ctrl-C, or an error) ends the process, + taking the others with it. +- stdin and stdout are one resource each, so at most one stage may read a + container from stdin, and at most one may write one to stdout. +- The MoQ side belongs to the invocation, not a stage: `--connect` and + friends go before the first stage and are rejected after a `--`. +- `moq` reads every `--` as a stage separator, so it can't double as the usual + end-of-options marker. The one place that matters is a local playlist path + starting with `-`; write it as `./-playlist.m3u8`. +- `play`, `transcode`, `token`, and `devices` own the process and can't be + staged; run those on their own. +- `import capture` encodes to fit the connection's bandwidth estimate over + `--connect`, and rate control assumes it's the only publisher on that + connection, so it can't share a process with another `import`. Run those as + separate processes, or publish over `--listen`, which has no estimate. + (An audio-only `--no-video` capture never reads the estimate, so it doesn't + count.) + ### Redundant Publishers (1+1) Relays key a broadcast's content identity on the publisher's origin id (the @@ -282,8 +334,11 @@ may publish where. The `capture` subcommand captures and encodes from local devices directly, no external FFmpeg process required. It publishes the camera as an H.264 video -track and the microphone as an Opus audio track on the same broadcast. It is -gated behind the `capture` feature: +track and the microphone as an Opus audio track on the same broadcast. Video is +encoded strictly on demand: the camera is opened once at startup to read the +mode it negotiates, which is what lets the catalog describe the track exactly +before anything is encoded, and is then released until someone watches (no CPU, +LED off in between). It is gated behind the `capture` feature: Build (or run) with the feature enabled: diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 84b88014e2d..f640b91daca 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -243,12 +243,23 @@ goaway.handover = "10s" # fails outright), and the first connection to complete wins. "0s" dials every # address at once. Defaults to 250ms, RFC 8305's Connection Attempt Delay. # race = "250ms" + +# Delay before dialing an IPv4 address while the full DNS answer is outstanding. +# A dial runs the usual all-families lookup alongside an IPv4-only one that +# answers without waiting for the AAAA record, and starts on the first answer, so +# a slow or dropped AAAA query no longer delays it. The full answer is +# authoritative, including which family to try first, so this is how long the +# IPv4-only one waits for it before going ahead alone. "0s" dials as soon as any +# address resolves. Defaults to 50ms, RFC 8305's Resolution Delay. +# resolution_delay = "50ms" ``` The connect timeout is also available as `--connect-timeout` or -`MOQ_CONNECT_TIMEOUT`, and the address race as `--connect-race` or -`MOQ_CONNECT_RACE`. The two compose: the race staggers the attempts within one -dial, and the timeout bounds that dial as a whole. +`MOQ_CONNECT_TIMEOUT`, the address race as `--connect-race` or +`MOQ_CONNECT_RACE`, and the resolution delay as `--connect-resolution-delay` or +`MOQ_CONNECT_RESOLUTION_DELAY`. They compose: the resolution delay picks which +family goes first, the race staggers the attempts within one dial, and the +timeout bounds that dial as a whole. Pinning the source port (a non-zero port in `--connect-bind`) disables address racing on the `quiche` backend, which binds a fresh socket per attempt and so diff --git a/doc/concept/standard/interop.md b/doc/concept/standard/interop.md index 20bea697ef2..bd2dc41041f 100644 --- a/doc/concept/standard/interop.md +++ b/doc/concept/standard/interop.md @@ -40,10 +40,32 @@ If it plays, you interop. That's the whole test. ## Notes -- **`SUBSCRIBE_NAMESPACE` is required.** The subscriber discovers broadcasts by - sending `SUBSCRIBE_NAMESPACE` and waiting for a matching announce, so your - relay must support it. The publisher announces with `PUBLISH_NAMESPACE`, and - only in response to a `SUBSCRIBE_NAMESPACE` covering the namespace. +- **We announce without being asked, and we ask.** Every namespace we can offer + goes out as an unsolicited `PUBLISH_NAMESPACE`, and we send + `SUBSCRIBE_NAMESPACE` for every prefix we're allowed to discover. Nothing in + moq-transport says which one a peer expects, and the peers that never ask are + the ones expecting to be told, so we do both by default. +- **Tell us to stop and we will.** The [MoQ Solicit + extension](/draft/moq-solicit) is a `SETUP` option set to `1` to declare that + advertisements to you must be asked for, because you'll send + `SUBSCRIBE_NAMESPACE` for what you want. Declaring it gets you the relay + behavior the IETF draft describes. Unknown options are ignored, so an + implementation that doesn't know it loses nothing. +- **We always declare it ourselves.** We ask for every prefix we're allowed to + discover, so an unsolicited `PUBLISH_NAMESPACE` can't tell us anything we + won't have asked for. Honor it and you'll never send us one. +- **If you implement it, we hold you to it.** Sending the option at all, + including `0`, says you read ours. An unsolicited `PUBLISH_NAMESPACE` after + that is a protocol violation and we close the session, because the alternative + is a bug neither of us ever sees. Omit the option and you get the tolerant + path instead: announce away, we'll take it. Draft-14/15 are exempt, since a + `PUBLISH_NAMESPACE` is also how you answer a `SUBSCRIBE_NAMESPACE` there. +- **We ask everyone.** There's no way to tell us not to bother: answering a + `SUBSCRIBE_NAMESPACE` with an empty set costs one stream, while waiting on + your `SETUP` to find out costs a round trip on every connection. +- **One namespace, one message.** We never advertise the same namespace as both + `PUBLISH_NAMESPACE` and `NAMESPACE` on one session; your declaration picks + which. Rejecting a `PUBLISH_NAMESPACE` is fine and keeps the session up. - **`PUBLISH` is declined.** Content is routed per namespace and tracks are resolved on demand via `SUBSCRIBE`, so a single-track `PUBLISH` offer is answered with a request error. Announce with `PUBLISH_NAMESPACE` and serve diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 8f188a98aa6..0d1c40aa2b8 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -135,7 +135,7 @@ The setters fall into a few groups: - **Protocol**: `moq_client_set_versions` restricts what's offered during the handshake. Names are spelled the way the CLI spells them (`moq-lite-05`, `moq-transport-19`); `moq_versions` lists what this build offers so a menu can't drift from what the setter accepts. An empty list restores the default of offering everything. - **TLS**: `moq_client_set_tls_fingerprints` (pin a SHA-256 hex fingerprint, the native equivalent of the browser's `serverCertificateHashes`), `moq_client_set_tls_roots`, `moq_client_set_tls_system_roots`, `moq_client_set_tls_host_name` (SNI override), `moq_client_set_tls_cert` / `moq_client_set_tls_key` (mTLS), and `moq_client_set_tls_disable_verify` (development only: it accepts any certificate, so prefer a fingerprint). -- **Transport**: `moq_client_set_backend`, `moq_client_set_bind`, `moq_client_set_connect_timeout`, `moq_client_set_failover_delay`, and `moq_client_set_websocket_enabled` / `moq_client_set_websocket_delay` for the fallback that gets you through a UDP-blocked network. The QUIC backends are compile-time optional, so use `moq_backends` for the names this build actually accepts rather than assuming all three. +- **Transport**: `moq_client_set_backend`, `moq_client_set_bind`, `moq_client_set_connect_timeout`, `moq_client_set_failover_delay` / `moq_client_set_resolution_delay` (the two Happy Eyeballs delays: how long before the next address is also dialed, and how long the first one waits for the AAAA answer), and `moq_client_set_websocket_enabled` / `moq_client_set_websocket_delay` for the fallback that gets you through a UDP-blocked network. The QUIC backends are compile-time optional, so use `moq_backends` for the names this build actually accepts rather than assuming all three. - **Tuning**: `moq_client_set_backoff_initial` / `_multiplier` / `_max` / `_timeout` for reconnect pacing, and `moq_client_set_quic_max_streams` / `_idle_timeout` / `_keep_alive` / `_gso` / `_mtu_discovery` / `_congestion_control` / `_qlog` for the transport. The QUIC ones are ignored by the WebSocket fallback. Every knob is its own setter, and a knob you never set stays at its default. That is deliberate rather than incidental: the C ABI is stable, so a new knob has to be a new function. Bundling several into one `struct` you pass by pointer would freeze their layout, and adding a field later would break every caller compiled against the old size. The optional strings (`congestion_control`, `qlog`, the TLS paths) are set-or-clear, where NULL or empty puts the knob back to automatic, so a setting can be undone without rebuilding the handle. @@ -258,7 +258,7 @@ moq_publish_video_raw_frame(video, &frame); Every zero in the output config means "pick a default": `bitrate` derives one from the resolution and framerate, `gop` uses roughly two seconds. `data` is borrowed only for the call, and must be exactly one picture at the configured resolution: the frame carries no dimensions of its own, so a wrong-sized buffer is rejected rather than reinterpreted. (The decode side's `moq_video_frame` does carry dimensions, since there they are whatever the stream turned out to be.) A hardware encoder pipelines, so a call that puts nothing on the wire is normal rather than an error. -The track is named after the codec (`.avc3` / `.hev1`), and its catalog rendition appears once the first keyframe has been encoded, which is where the resolution and codec string come from. So a subscriber discovers the track through the catalog rather than a name you chose. +The track is named after the codec (`.avc3` / `.hev1`), and its catalog rendition is published immediately, read out of the encoder itself (which is opened once up front for exactly that), so a subscriber discovers the track through the catalog rather than a name you chose, and can find it before the first frame exists. Two knobs run the live encoder. `moq_publish_video_raw_bitrate` retunes it without forcing a keyframe, which is cheap enough to drive from a congestion controller; a negative return means this backend can't retune while running, so stop adapting rather than stop publishing. `moq_publish_video_raw_cut` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group, so a subscriber can always join without it. Reach for it only when you want to place the boundaries yourself, aligning groups with something the encoder can't see such as a scene change or a source switch. Call `moq_publish_video_raw_finish` to flush the codec and end the track. diff --git a/doc/lib/go/moq.md b/doc/lib/go/moq.md index 3c38f9a2ee0..87d1c4836a8 100644 --- a/doc/lib/go/moq.md +++ b/doc/lib/go/moq.md @@ -279,7 +279,7 @@ video.Finish() `AutoEncoder()` prefers a hardware encoder and falls back to software; `SoftwareEncoder()`, `HardwareEncoder()`, and `NamedEncoder("videotoolbox")` pin the choice. The bindings compile VideoToolbox (macOS), Media Foundation (Windows), and openh264 (software, everywhere); the Linux hardware codecs are a libmoq-only build option. `SetBitrate` retunes the live encoder without forcing a keyframe, cheap enough to drive from a congestion controller. -The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition appears once the first keyframe is encoded, so subscribers discover it through the catalog rather than a name you pick. `Cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `Gop` frames on its own, and each of those cuts a group. +The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition is published immediately, read out of the encoder itself, so subscribers discover it through the catalog rather than a name you pick, and can find it before the first frame exists. `Cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `Gop` frames on its own, and each of those cuts a group. ## Raw Track Controls @@ -369,6 +369,30 @@ for request, err := range dynamic.Requests(ctx) { } ``` +## Fetching media groups + +`FetchGroup` hands back raw payloads. `FetchMediaGroup` decodes the same group through the rendition's container, so you get timestamped frames without opening a live subscription: + +```go +catalog, err := consumer.Catalog(ctx) +if err != nil { + log.Fatal(err) +} + +group, err := consumer.FetchMediaGroup("audio0", 42, catalog.Audio["audio0"].Container, nil) +if err != nil { + log.Fatal(err) +} +for frame, err := range group.Frames(ctx) { + if err != nil { + log.Fatal(err) + } + fmt.Printf("%d: %d bytes\n", frame.TimestampUs, len(frame.Payload)) +} +``` + +A fetched media group is finite: it ends after the group's last decoded frame, unlike the live `SubscribeMedia` stream. Latency-based group skipping does not apply, so you always get every frame in the group. + ## Raw track timestamps Raw tracks carry arbitrary byte payloads. `WriteFrame` takes a `Frame`, whose diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 7af70044cf5..61c53a6417f 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -26,7 +26,7 @@ The raw UniFFI bindings (`uniffi.moq.*`) plus the native binaries (JNI on Androi ```kotlin // build.gradle.kts dependencies { - implementation("dev.moq:moq:0.4.2") + implementation("dev.moq:moq:0.4.3") implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0") } ``` diff --git a/doc/lib/kt/moq.md b/doc/lib/kt/moq.md index 97e256edc70..f9d01334d02 100644 --- a/doc/lib/kt/moq.md +++ b/doc/lib/kt/moq.md @@ -16,7 +16,7 @@ Full API reference: [javadoc.io/doc/dev.moq/moq](https://javadoc.io/doc/dev.moq/ ```kotlin // build.gradle.kts dependencies { - implementation("dev.moq:moq:0.4.2") + implementation("dev.moq:moq:0.4.3") implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0") } ``` @@ -173,7 +173,7 @@ video.finish() `autoEncoder` prefers a hardware encoder and falls back to software; `softwareEncoder`, `hardwareEncoder`, and `namedEncoder("videotoolbox")` pin the choice. The bindings compile VideoToolbox (macOS), Media Foundation (Windows), and openh264 (software, everywhere); the Linux hardware codecs are a libmoq-only build option. `setBitrate` retunes the live encoder without forcing a keyframe, cheap enough to drive from a congestion controller. -The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition appears once the first keyframe is encoded, so subscribers discover it through the catalog rather than a name you pick. `cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group. +The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition is published immediately, read out of the encoder itself, so subscribers discover it through the catalog rather than a name you pick, and can find it before the first frame exists. `cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group. ## Serve @@ -239,6 +239,27 @@ dynamic.requestedGroups().collect { request -> Call `request.abort(code)` when the requested group cannot be produced. Fetch is currently a single-group operation and is supported by the moq-lite 05+ FETCH wire path. +### Fetching media groups + +`fetchGroup` hands back raw payloads. `fetchMediaGroup` decodes the same group through the rendition's advertised container, so you get timestamped frames without opening a live subscription: + +```kotlin +val (name, audio) = consumer.catalog().audio.entries.first() + +consumer.fetchMediaGroup( + name, + 42uL, + audio.container, + FetchGroupOptions(priority = 10u), +).use { group -> + group.frames().collect { frame -> + println("${frame.timestampUs}: ${frame.payload.size} bytes") + } +} +``` + +`frames()` is a cancellation-aware `Flow`. A fetched media group is finite: it completes after the group's last decoded frame, unlike the live `subscribeMedia` stream. Latency-based group skipping does not apply, so you always get every frame in the group. + ### On-demand raw tracks Use a dynamic broadcast when subscribers should be able to request raw tracks that are not published yet: diff --git a/doc/lib/py/moq-rs.md b/doc/lib/py/moq-rs.md index 753895ec892..6946092a455 100644 --- a/doc/lib/py/moq-rs.md +++ b/doc/lib/py/moq-rs.md @@ -123,7 +123,7 @@ video.finish() `VideoEncoderKind.AUTO()` prefers a hardware encoder and falls back to software; `SOFTWARE()`, `HARDWARE()`, and `NAMED("videotoolbox")` pin the choice (each variant is a class, so call it). The bindings compile VideoToolbox (macOS), Media Foundation (Windows), and openh264 (software, everywhere); the Linux hardware codecs are a libmoq-only build option. `set_bitrate` retunes the live encoder without forcing a keyframe, cheap enough to drive from a congestion controller. -The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition appears once the first keyframe is encoded, so subscribers discover it through the catalog rather than a name you pick. `cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group. +The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition is published immediately, read out of the encoder itself, so subscribers discover it through the catalog rather than a name you pick, and can find it before the first frame exists. `cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group. `publish_media` fills the catalog by parsing the codec bitstream. For a video format you can pass a `VideoHint` to supply fields the stream can't reveal (such as `bitrate`), or to publish the catalog before the first keyframe: @@ -234,6 +234,21 @@ async for request in dynamic: Call `request.abort(code)` when the requested group cannot be produced. Fetch is currently a single-group operation and is supported by the moq-lite 05+ FETCH wire path. +### Fetching media groups + +`fetch_group` hands back raw payloads. `fetch_media_group` decodes the same group through the rendition's container, so you get timestamped frames without opening a live subscription: + +```python +catalog = await broadcast_consumer.catalog() +name, audio = next(iter(catalog.audio.items())) + +group = await broadcast_consumer.fetch_media_group(name, sequence=42, track=audio) +async for frame in group: + print(frame.timestamp_us, len(frame.payload)) +``` + +A fetched media group is finite: it ends after the group's last decoded frame, unlike the live `subscribe_media` stream. Latency-based group skipping does not apply, so you always get every frame in the group. + ### Raw datagrams Raw tracks can also send best-effort datagrams: diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index f121dd9e944..1f0446eb605 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -39,7 +39,7 @@ Add the `Moq` wrapper; SPM resolves `MoqFFI` (and its XCFramework) transitively: ```swift dependencies: [ - .package(url: "https://github.com/moq-dev/moq-swift", from: "0.4.3"), + .package(url: "https://github.com/moq-dev/moq-swift", from: "0.4.4"), ], targets: [ .target( diff --git a/doc/lib/swift/moq.md b/doc/lib/swift/moq.md index a7f3d5ec1dd..b5cad92c06e 100644 --- a/doc/lib/swift/moq.md +++ b/doc/lib/swift/moq.md @@ -14,7 +14,7 @@ Full API reference: [Swift Package Index](https://swiftpackageindex.com/moq-dev/ ## Install ```swift -.package(url: "https://github.com/moq-dev/moq-swift", from: "0.4.3"), +.package(url: "https://github.com/moq-dev/moq-swift", from: "0.4.4"), ``` Add `Moq` to your target's dependencies: @@ -189,6 +189,26 @@ for try await request in dynamic { Call `request.abort(errorCode:)` when the requested group cannot be produced. Fetch is currently a single-group operation and is supported by the moq-lite 05+ FETCH wire path. +### Fetching media groups + +`fetchGroup` hands back raw payloads. `fetchMediaGroup` decodes the same group through the rendition's advertised container, so you get timestamped frames without opening a live subscription: + +```swift +let catalog = try await consumer.subscribeCatalog().next()! +let (name, audio) = catalog.audio.first! + +let group = try await consumer.fetchMediaGroup( + name: name, + sequence: 42, + container: audio.container +) +for try await frame in group { + print(frame.timestampUs, frame.payload.count) +} +``` + +`MediaGroupConsumer` is an `AsyncSequence`, and cancels the native read when iteration ends. A fetched media group is finite: it completes after the group's last decoded frame, unlike the live `subscribeMedia` stream. Latency-based group skipping does not apply, so you always get every frame in the group. + ### On-demand raw tracks Use a dynamic broadcast when subscribers should be able to request raw tracks that are not published yet: @@ -295,7 +315,7 @@ try video.finish() `kind: .auto` prefers a hardware encoder and falls back to software; `.software`, `.hardware`, and `.named(name: "videotoolbox")` pin the choice. The bindings compile VideoToolbox (macOS), Media Foundation (Windows), and openh264 (software, everywhere); the Linux hardware codecs are a libmoq-only build option. `setBitrate(_:)` retunes the live encoder without forcing a keyframe, cheap enough to drive from a congestion controller. -The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition appears once the first keyframe is encoded, so subscribers discover it through the catalog rather than a name you pick. `cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group. +The track is named after the codec (`.avc3` / `.hev1`) and its catalog rendition is published immediately, read out of the encoder itself, so subscribers discover it through the catalog rather than a name you pick, and can find it before the first frame exists. `cut()` starts a new group at the next frame, which is optional: the encoder keyframes every `gop` frames on its own, and each of those cuts a group. ## Cancellation diff --git a/drafts/draft-lcurley-moq-solicit.md b/drafts/draft-lcurley-moq-solicit.md new file mode 100644 index 00000000000..2276e1f346a --- /dev/null +++ b/drafts/draft-lcurley-moq-solicit.md @@ -0,0 +1,159 @@ +--- +title: "MoQ Solicit Extension" +abbrev: "moq-solicit" +category: info + +docname: draft-lcurley-moq-solicit-latest +submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" +number: +date: +v: 3 +area: wit +workgroup: moq + +author: + - + fullname: Luke Curley + email: kixelated@gmail.com + +normative: + moqt: I-D.ietf-moq-transport + +informative: + +--- abstract + +This document defines an extension for MoQ Transport {{moqt}} that lets an endpoint declare that advertisements to it must be solicited first. +An endpoint that declares nothing receives unsolicited PUBLISH_NAMESPACE, which is what a peer unaware of this extension implicitly asks for. +An endpoint that will instead ask for what it wants says so once during setup, and is spared the advertisements it would otherwise have to ignore. +Because sending the option at all identifies an endpoint that implements this extension, the requirement is enforceable between two such endpoints rather than merely advisory. + +--- middle + +# Conventions and Definitions +{::boilerplate bcp14-tagged} + +An endpoint **advertises** a namespace by sending PUBLISH_NAMESPACE, or NAMESPACE in response to a SUBSCRIBE_NAMESPACE. +An advertisement is **solicited** when it is carried by a SUBSCRIBE_NAMESPACE the receiver sent, and **unsolicited** otherwise. + +On a version of {{moqt}} that has NAMESPACE, the mechanism decides this and nothing else does: PUBLISH_NAMESPACE opens a request of its own and is always unsolicited, however the namespace relates to a prefix the receiver subscribed to. +That distinction is what makes the requirement observable from a single message, and so enforceable ({{enforcement}}). +Earlier versions have no NAMESPACE, so an endpoint answers a SUBSCRIBE_NAMESPACE with PUBLISH_NAMESPACE requests and the two are indistinguishable. + + +# Introduction +{{moqt}} has two ways to learn that a namespace exists. +A publisher advertises one with PUBLISH_NAMESPACE, and a subscriber asks for the set under a prefix with SUBSCRIBE_NAMESPACE, which is answered with NAMESPACE. +Both are optional, and nothing on the wire says which the peer expects. + +The result is that an endpoint has to guess, and both guesses are wrong somewhere: + +- Withhold PUBLISH_NAMESPACE until asked, and a publisher connected to a relay that never asks stays silent forever. The session looks healthy and no content is ever offered. +- Send it unasked, and an endpoint that only publishes is told about every namespace its peer knows, which is a set it has no use for and, on a relay, a set as large as the network. + +Implementations resolve this out of band today, by configuring each endpoint with what the peer will do. +That works only as long as the configuration matches reality, and it makes the same software behave differently depending on a deployment flag rather than on anything in the protocol. + +This extension replaces the guess with a declaration. +An endpoint states in its SETUP that it requires advertisements to be solicited, and the peer honors it. +The default, declaring nothing, is to advertise unasked, so an endpoint that has never heard of this extension keeps working exactly as it does today. + +This is deliberately not a role: it says what an endpoint expects delivered to it, not what it is. +An endpoint that sends SUBSCRIBE_NAMESPACE for everything it cares about declares it on every session, whether it publishes, subscribes, or relays. + + +# Setup Negotiation + +An endpoint declares whether it requires solicitation with the following Setup Option ({{moqt}} Section 10.3): + +~~~ +SOLICIT Setup Option { + Option Key (vi64) = 0x40B5A + Option Value (vi64) = 0 or 1 +} +~~~ + +A value of 1 means advertisements to the sender MUST be solicited: it sends SUBSCRIBE_NAMESPACE for what it wants. +A value of 0 means it has no requirement, so an advertisement may be sent freely. + +The option is OPTIONAL, and omitting it asks for the same treatment as a value of 0. +The two are not equivalent, because sending either value also identifies the sender as implementing this extension ({{enforcement}}), while omitting it says nothing at all. +An endpoint that implements this extension and has no requirement SHOULD therefore send 0 rather than omit the option. + +A receiver MUST treat any non-zero value as 1. +The two directions are independent: each endpoint declares its own, and the two need not match. + +Unlike an extension that changes an encoding, this one needs no negotiation handshake: a declaration only ever asks the peer to send *less*, so a peer that ignores it is merely as talkative as one that never saw it. + + +# Requiring Solicitation {#announce} + +An endpoint that declared 1 will solicit the namespaces it wants with SUBSCRIBE_NAMESPACE, or wants none at all. + +A peer that receives this declaration and implements this extension MUST NOT send an unsolicited PUBLISH_NAMESPACE for the remainder of the session; one that does not implement it cannot be bound by it and is covered by {{enforcement}}. +It continues to answer SUBSCRIBE_NAMESPACE with NAMESPACE as usual; only the unsolicited half is withheld. + +This is a MUST NOT rather than a SHOULD NOT because the receiver enforces it. A SHOULD NOT that a receiver may close the session over is not a permission an endpoint can actually exercise. + +A relay is the expected user of this declaration, as is any endpoint that asks for what it wants. +So is an endpoint that only publishes, which cannot subscribe to anything and therefore has no use for an advertisement of any kind. + +An endpoint SHOULD NOT advertise the same namespace both ways on one session. +Whichever arrives second replaces the source the first attached, which at best wastes a stream and at worst leaves the receiver holding two independent advertisements it must reconcile. +Because this declaration decides which of the two an endpoint uses, honoring it also settles that question for the whole session. + + +# Enforcement {#enforcement} + +An endpoint that declared 1 and then receives an unsolicited PUBLISH_NAMESPACE MUST close the session as a protocol violation if the sender declared either value, and MUST tolerate the message otherwise. + +An endpoint that sent the option implements this extension, so it read the receiver's declaration and ignored it. +It also cannot have advertised before reading that declaration: the receiver's SETUP is what says whether advertising unasked is permitted at all, so an endpoint MUST have processed it before sending its first advertisement. +Neither a race nor a partial implementation explains the message, which leaves a bug, and one that both sides would otherwise never see. + +An endpoint that omitted the option gets the opposite treatment for the same reason: it never saw the declaration, so announcing is exactly what it should do, and closing the session over it would turn this extension into a new way for conforming implementations to fail to interoperate. + +Versions of {{moqt}} without NAMESPACE are exempt, because a PUBLISH_NAMESPACE there is also how an endpoint answers a SUBSCRIBE_NAMESPACE and the message alone does not say which it is. +Everywhere else the mechanism is the whole test: a receiver MUST NOT treat an advertisement as solicited merely because the namespace falls under a prefix it subscribed to, or an endpoint that subscribes to every prefix it can reach would find the requirement unenforceable against anyone. + +There is no counterpart for SUBSCRIBE_NAMESPACE, enforceable or otherwise. +An endpoint with nothing to advertise answers one with an empty set, which costs a single stream, while waiting on the peer's SETUP to learn whether the question is worth asking costs a round trip on every session. +Asking unconditionally is therefore the cheaper behavior, and it is what an endpoint SHOULD do. + + +# Security Considerations + +A declaration only ever reduces what its sender receives, so an attacker who forges one can silence advertisements to the endpoint it impersonates, or add an option to an endpoint that never sent one so its own advertisements are treated as a violation and its session closed. +Both are already available to anyone who can interfere with SETUP, which {{moqt}} assumes is protected by the underlying transport. + +A declaration says nothing about authorization. +An endpoint that declares no requirements is not thereby entitled to any advertisement, and a peer MUST apply the same authorization to what it advertises as it would without this extension. +In particular, a relay MUST NOT treat an absent SOLICIT option as permission to advertise namespaces the peer is not authorized to learn about. + +The declaration reveals a little about an endpoint's intent, roughly whether it intends to ask for what it wants. +An endpoint that considers this sensitive can simply declare nothing, which costs it only the messages it would have avoided. + + +# IANA Considerations + +This document requests the following registration. +A high, distinctive value is requested to avoid the low ranges reserved by {{moqt}} and to minimize collisions with provisional registrations by other extensions. + +## MOQT Setup Options + +This document requests one registration in the "MOQT Setup Options" registry ({{moqt}} Section 15.4), whose policy is Specification Required. + +| Value | Name | Reference | +|:--------|:--------|:--------------| +| 0x40B5A | SOLICIT | This Document | + +The Key-Value-Pair parity is load-bearing: SOLICIT is even, so its value is a bare varint. +This document defines only the values 0 and 1; a later extension that needs to say something else registers its own option rather than overloading this one. + + +--- back + +# Acknowledgments +{:numbered="false"} + +This document was drafted with the assistance of Claude, an AI assistant by Anthropic. diff --git a/flake.nix b/flake.nix index f28bc135c0f..ea3a8c3c0cc 100644 --- a/flake.nix +++ b/flake.nix @@ -250,6 +250,48 @@ gradle_8 ]; + # uniffi-bindgen-go renders rs/moq-ffi into the generated half of + # go/ffi. Not in nixpkgs, so build it from NordSecurity's fork; without + # it `just go check` skips itself, which reads as a pass in CI. + # + # The tag pairs the generator's own version with the uniffi release it + # targets (v0.7.1+v0.31.0 -> uniffi 0.31), and it only understands + # metadata emitted by that uniffi, so it moves with the `uniffi` + # dependency in rs/moq-ffi/Cargo.toml. Three other places name the same + # tag and must be bumped together: UNIFFI_BINDGEN_GO_TAG in + # release-go-ffi.yml, and the `cargo install` line in go/ffi/README.md + # and go/scripts/check.sh. + uniffi-bindgen-go = pkgs.rustPlatform.buildRustPackage rec { + pname = "uniffi-bindgen-go"; + version = "0.7.1+v0.31.0"; + + src = pkgs.fetchFromGitHub { + owner = "NordSecurity"; + repo = "uniffi-bindgen-go"; + rev = "v${version}"; + hash = "sha256-ZoGxEWJKriGhe/nMpSbJF6pyyZQZLzdVervUrBzUM5k="; + }; + + cargoHash = "sha256-ctDBz0oE8+mkn7SJn2KGSb6P4LF8S5UC3XcjVHWApg4="; + + # The tag is a virtual workspace whose other members are uniffi test + # fixtures. Building from the root would compile all of them, and CI + # has no Nix binary cache, so it would pay for that on every run. + buildAndTestSubdir = "bindgen"; + + # The upstream test suite generates fixtures and compiles them with a + # Go toolchain, which is a lot of build for a binary we only invoke. + doCheck = false; + }; + + # Go toolchain (go/) so `just go check` regenerates the bindings and + # runs `go test -race` on the wrapper instead of skipping. Cross-platform: + # the check builds moq-ffi for the host and runs on Linux and macOS. + goDeps = [ + pkgs.go + uniffi-bindgen-go + ]; + # Dependencies for building the OBS plugin (`just obs build`). # Linux-only: nixpkgs marks obs-studio broken on Darwin, so macOS # and Windows fetch libobs/Qt6 via the OBS buildspec instead (see @@ -323,6 +365,7 @@ ++ lintDeps ++ obsDeps ++ ktDeps + ++ goDeps ++ devTools; # jemalloc's configure uses -O0 test builds, which conflict with diff --git a/go/ffi/README.md b/go/ffi/README.md index 05109257158..e473906b4d0 100644 --- a/go/ffi/README.md +++ b/go/ffi/README.md @@ -22,7 +22,7 @@ The published module ships prebuilt `libmoq_ffi.a` for `linux/amd64`, `linux/arm `go/scripts/check.sh` builds `moq-ffi` for the host, runs `uniffi-bindgen-go` to regenerate `moq.go`, stages this module plus the wrapper into `dist/`, and runs `go build`/`go vet`/`go test`. Run via `just go check`. Skips cleanly without `cargo`, `go`, or `uniffi-bindgen-go`. -Install `uniffi-bindgen-go` once: +The dev shell provides both `go` and `uniffi-bindgen-go`, so `nix develop --command just go check` needs no setup. Without Nix, install `uniffi-bindgen-go` once: ```bash cargo install uniffi-bindgen-go \ @@ -30,6 +30,8 @@ cargo install uniffi-bindgen-go \ --tag v0.7.1+v0.31.0 ``` +The tag pins the generator to the `uniffi` version `rs/moq-ffi` depends on; `flake.nix` pins the same one. + ## Layout ```text diff --git a/go/scripts/check.sh b/go/scripts/check.sh index 178d4a031a3..14a152e3769 100755 --- a/go/scripts/check.sh +++ b/go/scripts/check.sh @@ -32,8 +32,21 @@ if ! command -v uniffi-bindgen-go >/dev/null 2>&1; then fi HOST_TARGET=$(rustc -vV | awk '/^host:/ {print $2}') +# Debug by default. This is a compile-and-test gate, not a benchmark, and a +# release build of moq-ffi shares no artifacts with the debug ones `just check` +# and `just test` already produce, so it was a third full compile of the +# dependency tree (~5 min of CI on its own, plus a whole target/release tree on +# a runner that was already tight on disk). Set MOQ_FFI_PROFILE=release for an +# optimized cdylib; the shipped artifacts are built by rs/moq-ffi/build.sh, +# which is release regardless. +PROFILE="${MOQ_FFI_PROFILE:-debug}" +# Expanded as ${CARGO_PROFILE[@]+...} at the use sites: macOS ships bash 3.2, +# where expanding an empty array under `set -u` is an "unbound variable" error. +CARGO_PROFILE=() +[[ "$PROFILE" == "release" ]] && CARGO_PROFILE=(--release) + echo "go check: building moq-ffi for $HOST_TARGET..." -cargo build --release --package moq-ffi \ +cargo build ${CARGO_PROFILE[@]+"${CARGO_PROFILE[@]}"} --package moq-ffi \ --manifest-path "$WORKSPACE_DIR/Cargo.toml" TARGET_BASE=$(cargo metadata --format-version 1 --manifest-path "$WORKSPACE_DIR/Cargo.toml" --no-deps | @@ -41,16 +54,16 @@ TARGET_BASE=$(cargo metadata --format-version 1 --manifest-path "$WORKSPACE_DIR/ case "$HOST_TARGET" in *-apple-*) - CDYLIB="$TARGET_BASE/release/libmoq_ffi.dylib" - STATICLIB="$TARGET_BASE/release/libmoq_ffi.a" + CDYLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.dylib" + STATICLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.a" ;; *-windows-*) - CDYLIB="$TARGET_BASE/release/moq_ffi.dll" - STATICLIB="$TARGET_BASE/release/moq_ffi.lib" + CDYLIB="$TARGET_BASE/$PROFILE/moq_ffi.dll" + STATICLIB="$TARGET_BASE/$PROFILE/moq_ffi.lib" ;; *) - CDYLIB="$TARGET_BASE/release/libmoq_ffi.so" - STATICLIB="$TARGET_BASE/release/libmoq_ffi.a" + CDYLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.so" + STATICLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.a" ;; esac @@ -95,13 +108,20 @@ if [[ -d "$STAGE_BINDINGS/uniffi/moq" && ! -d "$STAGE_BINDINGS/moq" ]]; then fi echo "go check: assembling ffi module..." +# --skip-size-check because the lib above is a plain host build, unrelated to +# what the mirror publishes. It is a debug build by default now, so it carries +# full line-table debug info and measured 619 MiB against a 100 MiB limit; even +# at MOQ_FFI_PROFILE=release it skips the thin LTO that rs/moq-ffi/build.sh +# applies on the publish path. Enforcing the limit here fails on a lib nobody +# publishes. bash "$GO_DIR/scripts/package-ffi.sh" \ --version "0.0.0-dev" \ --source-dir "$GO_DIR/ffi" \ --lib-dir "$STAGE_PARENT/go-libs" \ --bindings-dir "$STAGE_BINDINGS" \ --output "$STAGE_FFI" \ - --no-archive + --no-archive \ + --skip-size-check FFI_PKG="$STAGE_FFI/moq-ffi-0.0.0-dev-go" echo "go check: staging wrapper module..." diff --git a/go/scripts/package-ffi.sh b/go/scripts/package-ffi.sh index 97b016fb883..7fbfc149444 100755 --- a/go/scripts/package-ffi.sh +++ b/go/scripts/package-ffi.sh @@ -14,6 +14,8 @@ set -euo pipefail # # Optional: # --source-dir DIR in-tree ffi module skeleton (default: go/ffi) +# --skip-size-check don't enforce GitHub's 100 MiB per-file push limit, for +# callers staging libs that are never pushed to the mirror # # Expected $LIB_DIR layout (per cargo target): # $LIB_DIR/x86_64-unknown-linux-gnu/libmoq_ffi.a @@ -31,6 +33,7 @@ BINDINGS_DIR="" OUTPUT_DIR="" SOURCE_DIR="" ARCHIVE=true +SIZE_CHECK=true while [[ $# -gt 0 ]]; do case $1 in @@ -58,6 +61,10 @@ while [[ $# -gt 0 ]]; do ARCHIVE=false shift ;; + --skip-size-check) + SIZE_CHECK=false + shift + ;; -h | --help) grep '^#' "$0" | sed 's/^# \{0,1\}//' exit 0 @@ -144,6 +151,11 @@ GO_LIBS=( # these libs into git, so an oversized lib fails the publish push (GH001). # Catch it here, where the error names the file and points at the fix, rather # than after a multi-target build burns an hour to die at `git push`. +# +# Only meaningful for artifacts actually destined for the mirror. `go check` +# reuses this script to stage a throwaway module against a debug staticlib, +# which carries enough debug info to blow the limit and is never pushed, so it +# passes --skip-size-check. GITHUB_FILE_LIMIT=$((100 * 1024 * 1024)) STAGED_ANY=false OVERSIZED=() @@ -171,7 +183,7 @@ if [[ "$STAGED_ANY" != true ]]; then exit 1 fi -if [[ "${#OVERSIZED[@]}" -gt 0 ]]; then +if [[ "$SIZE_CHECK" == true && "${#OVERSIZED[@]}" -gt 0 ]]; then echo "Error: staged libs exceed GitHub's 100 MiB push limit:" >&2 printf ' %s\n' "${OVERSIZED[@]}" >&2 echo "The mirror push would be rejected (GH001). Shrink the staticlib in rs/moq-ffi/build.sh (LTO)." >&2 diff --git a/go/wrapper/moq/publish.go b/go/wrapper/moq/publish.go index 7a2952054a8..7e5cfb9cf46 100644 --- a/go/wrapper/moq/publish.go +++ b/go/wrapper/moq/publish.go @@ -127,8 +127,9 @@ func (b *BroadcastProducer) PublishAudio(name string, input AudioEncoderInput, o // encoder. // // The track is named after the codec (.avc3 / .hev1) and its catalog rendition -// appears once the first keyframe has been encoded, so subscribers discover it -// through the catalog rather than a name you pick. +// is published immediately, read out of the encoder itself, so subscribers +// discover it through the catalog rather than a name you pick, and can find it +// before the first frame exists. func (b *BroadcastProducer) PublishVideo(input VideoEncoderInput, output VideoEncoderOutput) (*VideoProducer, error) { inner, err := b.inner.PublishVideo(input, output) if err != nil { diff --git a/go/wrapper/moq/subscribe.go b/go/wrapper/moq/subscribe.go index d5a6e7fb685..d19054bb827 100644 --- a/go/wrapper/moq/subscribe.go +++ b/go/wrapper/moq/subscribe.go @@ -69,6 +69,17 @@ func (b *BroadcastConsumer) FetchGroup(name string, sequence uint64, options *Fe return &GroupConsumer{inner: inner}, nil } +// FetchMediaGroup fetches one group by sequence and decodes it with the given +// container. Unlike SubscribeMedia this holds no live subscription and applies no +// latency-based group skipping, so every frame in the group is delivered. +func (b *BroadcastConsumer) FetchMediaGroup(name string, sequence uint64, container Container, options *FetchGroupOptions) (*MediaGroupConsumer, error) { + inner, err := b.inner.FetchMediaGroup(name, sequence, container, options) + if err != nil { + return nil, err + } + return &MediaGroupConsumer{inner: inner}, nil +} + // SubscribeMedia subscribes to a media track, decoded with the given container. // subscription tunes delivery priority, group ordering priority, group range, and // the latency budget; pass nil for defaults. Raise Subscription.LatencyMaxMs to @@ -129,6 +140,32 @@ func (m *MediaConsumer) Cancel() { m.inner.Cancel() } +// MediaGroupConsumer is a finite stream of decoded media frames from one fetched +// group. It ends after the group's last frame. +type MediaGroupConsumer struct { + inner *ffi.MoqMediaGroupConsumer +} + +// Sequence is this group's sequence number within the track. +func (m *MediaGroupConsumer) Sequence() uint64 { + return m.inner.Sequence() +} + +// Next returns the next decoded frame, or (nil, nil) when the group ends. +func (m *MediaGroupConsumer) Next(ctx context.Context) (*MediaFrame, error) { + return runCancellable(ctx, m.inner.Cancel, m.inner.Next) +} + +// Frames ranges over decoded frames until the group ends or the loop breaks. +func (m *MediaGroupConsumer) Frames(ctx context.Context) iter.Seq2[*MediaFrame, error] { + return streamSeq(ctx, m.Next) +} + +// Cancel stops the stream. +func (m *MediaGroupConsumer) Cancel() { + m.inner.Cancel() +} + // GroupConsumer is a stream of timestamped raw frames within a single group. type GroupConsumer struct { inner *ffi.MoqGroupConsumer diff --git a/js/hang/package.json b/js/hang/package.json index dbf3661e0b7..9d2b0ed4426 100644 --- a/js/hang/package.json +++ b/js/hang/package.json @@ -1,7 +1,7 @@ { "name": "@moq/hang", "type": "module", - "version": "0.3.4", + "version": "0.3.5", "description": "WebCodecs-based media format for MoQ", "license": "(MIT OR Apache-2.0)", "repository": "github:moq-dev/moq", diff --git a/js/net/src/connection/accept.ts b/js/net/src/connection/accept.ts index cff465e1753..33e050b9d7d 100644 --- a/js/net/src/connection/accept.ts +++ b/js/net/src/connection/accept.ts @@ -94,14 +94,15 @@ async function acceptAlpn( version: Ietf.IetfVersion, wiring: SessionProps, ): Promise { - const controlStream = await exchangeSetup(transport, version, "moq-lite-js"); + const { control, solicit } = await exchangeSetup(transport, version, "moq-lite-js"); return new Ietf.Connection({ ...wiring, client: false, url, quic: transport, - control: controlStream, + control, + solicit, // v17+ uses NativeSession which manages its own request IDs; maxRequestId is unused. maxRequestId: 0n, version, @@ -127,7 +128,7 @@ async function acceptSetup( throw new Error(`unexpected client message type: 0x${clientCompat.toString(16)}`); } - await Ietf.ClientSetup.decode(stream.reader, version); + const client = await Ietf.ClientSetup.decode(stream.reader, version); await stream.writer.u53(Lite.StreamId.ServerCompat); @@ -135,6 +136,7 @@ async function acceptSetup( const params = new Ietf.SetupOptions(); params.setVarint(Ietf.SetupOption.MaxRequestId, 42069n); params.setBytes(Ietf.SetupOption.Implementation, encoder.encode("moq-lite-js")); + Ietf.solicitIntoSetup(params); const server = new Ietf.ServerSetup({ version, parameters: params }); await server.encode(stream.writer, version); @@ -149,6 +151,7 @@ async function acceptSetup( control: stream, maxRequestId, version, + solicit: Ietf.solicitFromSetup(client.parameters), }); } @@ -191,6 +194,7 @@ async function acceptNegotiated( const params = new Ietf.SetupOptions(); params.setVarint(Ietf.SetupOption.MaxRequestId, 42069n); params.setBytes(Ietf.SetupOption.Implementation, encoder.encode("moq-lite-js")); + Ietf.solicitIntoSetup(params); const server = new Ietf.ServerSetup({ version: selectedVersion, parameters: params }); await server.encode(stream.writer, setupVersion); @@ -213,6 +217,7 @@ async function acceptNegotiated( control: stream, maxRequestId, version: selectedVersion as Ietf.IetfVersion, + solicit: Ietf.solicitFromSetup(client.parameters), }); } else { throw new Error(`unsupported version: ${selectedVersion.toString(16)}`); diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index 6c3541bfa1d..4313b5777ae 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -267,6 +267,7 @@ async function connectTransport(url: URL, session: WebTransport, wiring: Session const params = new Ietf.SetupOptions(); params.setVarint(Ietf.SetupOption.MaxRequestId, 42069n); params.setBytes(Ietf.SetupOption.Implementation, encoder.encode("moq-lite-js")); + Ietf.solicitIntoSetup(params); const client = new Ietf.ClientSetup({ versions: @@ -304,6 +305,7 @@ async function connectTransport(url: URL, session: WebTransport, wiring: Session control: stream, maxRequestId, version: server.version as Ietf.IetfVersion, + solicit: Ietf.solicitFromSetup(server.parameters), }); } else { throw new Error(`unsupported server version: ${server.version.toString()}`); @@ -320,14 +322,15 @@ async function handshakeAlpn( version: Ietf.IetfVersion, wiring: SessionProps, ): Promise { - const controlStream = await exchangeSetup(session, version, "moq-lite-js"); + const { control, solicit } = await exchangeSetup(session, version, "moq-lite-js"); return new Ietf.Connection({ ...wiring, client: true, url, quic: session, - control: controlStream, + control, + solicit, // v17+ uses NativeSession which manages its own request IDs; maxRequestId is unused. maxRequestId: 0n, version, diff --git a/js/net/src/connection/handshake.ts b/js/net/src/connection/handshake.ts index 24c5fda7a16..a967c42f54a 100644 --- a/js/net/src/connection/handshake.ts +++ b/js/net/src/connection/handshake.ts @@ -6,23 +6,32 @@ import { Reader, Stream, Writer } from "../stream.ts"; * message, and reads the peer's Setup off an incoming uni stream. The two * halves run in parallel and the protocol is symmetric, so both `connect` * (client) and `accept` (server) use this same function. + * + * Returns the control stream plus whether the peer requires solicitation, which decides + * whether we announce namespaces unprompted (see the MoQ Solicit extension). We declare it + * ourselves on every session: we send SUBSCRIBE_NAMESPACE for each prefix we want, so an + * unsolicited advertisement can tell us nothing we won't have asked for. */ export async function exchangeSetup( transport: WebTransport, version: Ietf.IetfVersion, implementation: string, -): Promise { +): Promise<{ control: Stream; solicit: boolean | undefined }> { const encoder = new TextEncoder(); const params = new Ietf.SetupOptions(); params.setBytes(Ietf.SetupOption.Implementation, encoder.encode(implementation)); + Ietf.solicitIntoSetup(params); const setupMsg = new Ietf.Setup({ parameters: params }); - const [writer, reader] = await Promise.all([ + const [writer, received] = await Promise.all([ sendSetup(transport, version, setupMsg), receiveSetup(transport, version), ]); - return new Stream({ writer, reader }); + return { + control: new Stream({ writer, reader: received.reader }), + solicit: received.solicit, + }; } async function sendSetup(transport: WebTransport, version: Ietf.IetfVersion, setupMsg: Ietf.Setup): Promise { @@ -34,7 +43,10 @@ async function sendSetup(transport: WebTransport, version: Ietf.IetfVersion, set return writer; } -async function receiveSetup(transport: WebTransport, version: Ietf.IetfVersion): Promise { +async function receiveSetup( + transport: WebTransport, + version: Ietf.IetfVersion, +): Promise<{ reader: Reader; solicit: boolean | undefined }> { const uniReader = transport.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream >; @@ -48,7 +60,7 @@ async function receiveSetup(transport: WebTransport, version: Ietf.IetfVersion): if (streamType !== Ietf.Setup.id) { throw new Error(`unexpected stream type on setup uni: 0x${streamType.toString(16)}`); } - await Ietf.Setup.decode(reader, version); + const setup = await Ietf.Setup.decode(reader, version); - return reader; + return { reader, solicit: Ietf.solicitFromSetup(setup.parameters) }; } diff --git a/js/net/src/ietf/connection.ts b/js/net/src/ietf/connection.ts index a6af076eb87..3a520c8457e 100644 --- a/js/net/src/ietf/connection.ts +++ b/js/net/src/ietf/connection.ts @@ -53,6 +53,9 @@ export class Connection implements Established { // Module for distributing tracks. #subscriber: Subscriber; + // What the peer declared about being solicited; see {@link Ietf.solicitFromSetup}. + #solicit: boolean | undefined; + // Just to avoid logging when `close()` is called. #closed = false; @@ -63,6 +66,7 @@ export class Connection implements Established { * @param control - The control/setup stream * @param maxRequestId - The initial max request ID * @param version - The negotiated protocol version + * @param solicit - What the peer's SETUP declared (undefined when it declared nothing) * * @internal */ @@ -75,6 +79,7 @@ export class Connection implements Established { client, discovery = true, publish, + solicit, }: { url: URL; quic: WebTransport; @@ -86,6 +91,11 @@ export class Connection implements Established { discovery?: boolean; /** The origin whose broadcasts are served to the peer. Omit to publish nothing. */ publish?: OriginConsumer; + /** + * What the peer declared about being solicited. `undefined` means it declared + * nothing, which is the one case where announcing at us unasked is not a bug. + */ + solicit?: boolean; }) { this.url = url; this.discovery = discovery; @@ -108,7 +118,8 @@ export class Connection implements Established { }); } - this.#publisher = new Publisher(this.#quic, this.#session, publish); + this.#publisher = new Publisher(this.#quic, this.#session, publish, solicit ?? false); + this.#solicit = solicit; this.#subscriber = new Subscriber(this.#session); void this.#run(); @@ -138,7 +149,7 @@ export class Connection implements Established { async #run(): Promise { try { - await Promise.all([this.#runBidis(), this.#runUnis()]); + await Promise.all([this.#runBidis(), this.#runUnis(), this.#publisher.runPublishNamespaces()]); } catch (err) { if (!this.#closed) { console.error("fatal error running connection", err); @@ -236,6 +247,26 @@ export class Connection implements Established { // Subscriber handles incoming notifications case PublishNamespace.id: { const msg = await PublishNamespace.decode(stream.reader, this.#session.version); + + // We always declare that advertisements to us must be solicited (MoQ + // Solicit), and writing the option at all proves the peer implements the + // extension, whichever value it chose. It also cannot have advertised + // before reading our SETUP, since our SETUP is what says whether + // advertising unasked is allowed. So this is a bug in the peer, and a + // silent one on both sides if we tolerate it. + // + // Draft-14/15 are exempt: they have no inline NAMESPACE, so a + // PUBLISH_NAMESPACE request is also how a peer answers our + // SUBSCRIBE_NAMESPACE there, and the message alone does not say which. + const legacy = this.#session.version === Version.DRAFT_14 || this.#session.version === Version.DRAFT_15; + if (this.#solicit !== undefined && !legacy) { + console.error( + `unsolicited publish_namespace from a peer that implements MoQ Solicit: broadcast=${msg.trackNamespace}`, + ); + this.close(); + break; + } + await this.#subscriber.runPublishNamespace(msg, stream); break; } diff --git a/js/net/src/ietf/index.ts b/js/net/src/ietf/index.ts index cc3657090c7..91d45c9e1e1 100644 --- a/js/net/src/ietf/index.ts +++ b/js/net/src/ietf/index.ts @@ -10,6 +10,7 @@ export * from "./publish_namespace.ts"; export * from "./publisher.ts"; export * from "./request.ts"; export * from "./setup.ts"; +export * from "./solicit.ts"; export * from "./subscribe.ts"; export * from "./subscribe_namespace.ts"; export * from "./subscriber.ts"; diff --git a/js/net/src/ietf/parameters.ts b/js/net/src/ietf/parameters.ts index 8d8c3f6a5c6..1b265e3a251 100644 --- a/js/net/src/ietf/parameters.ts +++ b/js/net/src/ietf/parameters.ts @@ -10,6 +10,8 @@ export const SetupOption = { MaxAuthTokenCacheSize: 4n, Authority: 5n, Implementation: 7n, + /// SOLICIT, from the MoQ Solicit extension. See `solicit.ts`. + Solicit: 0x40b5an, } as const; /// Setup Options — used in SETUP messages. diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts new file mode 100644 index 00000000000..78892273387 --- /dev/null +++ b/js/net/src/ietf/publisher.test.ts @@ -0,0 +1,408 @@ +import { expect, test } from "bun:test"; +import { createMockTransportPair } from "../mock.ts"; +import { Producer as OriginProducer } from "../origin.ts"; +import * as Path from "../path.ts"; +import { Stream } from "../stream.ts"; +import { NativeSession, type Session } from "./adapter.ts"; +import { PublishNamespace } from "./publish_namespace.ts"; +import { Publisher } from "./publisher.ts"; +import { RequestError, RequestOk } from "./request.ts"; +import { SubscribeNamespace } from "./subscribe_namespace.ts"; +import { ALPN, Version } from "./version.ts"; + +const VERSION = Version.DRAFT_19; + +/** How long to wait for a stream before calling it absent, which is how a regression reports. */ +const STREAM_WAIT = 1000; + +/** Long enough for the publish to reach the announce loop's signal. */ +const SETTLE = 5; + +/** + * Accept the next stream the publisher opens, or give up rather than hang forever. + * + * Reads the queue directly instead of racing {@link Stream.accept}, whose pending read + * would keep the reader locked after the race resolves and could swallow a later stream. + */ +async function nextStream(transport: WebTransport): Promise { + const reader = + transport.incomingBidirectionalStreams.getReader() as ReadableStreamDefaultReader; + + let timer: ReturnType | undefined; + try { + const next = await Promise.race([ + reader.read(), + new Promise((resolve) => { + timer = setTimeout(() => resolve(undefined), STREAM_WAIT); + }), + ]); + + if (!next || next.done) return undefined; + return new Stream({ readable: next.value.readable, writable: next.value.writable, version: VERSION }); + } finally { + clearTimeout(timer); + reader.releaseLock(); + } +} + +/** Read one PUBLISH_NAMESPACE off a stream the publisher opened. */ +async function readPublishNamespace(stream: Stream): Promise { + const typeId = await stream.reader.u53(); + expect(typeId).toBe(PublishNamespace.id); + + const msg = await PublishNamespace.decode(stream.reader, VERSION); + return msg.trackNamespace; +} + +/** Answer a PUBLISH_NAMESPACE, which is what unblocks the announce loop. */ +async function acceptPublishNamespace(stream: Stream): Promise { + await stream.writer.u53(RequestOk.id); + await new RequestOk({ requestId: undefined }).encode(stream.writer, VERSION); +} + +/** + * Decline a PUBLISH_NAMESPACE, which the peer is allowed to do without ending the + * session. The publisher resets the request as soon as it reads the type, which lands + * back here as a write error once the refusal is already on the wire. + * + * `retryInterval` is what the peer says about coming back, in milliseconds: 0 asks not to + * be offered the namespace again, and anything else is a minimum wait. + */ +async function declinePublishNamespace(stream: Stream, retryInterval = 1n): Promise { + try { + await stream.writer.u53(RequestError.id); + await new RequestError({ + requestId: undefined, + errorCode: 403, + reasonPhrase: "no", + retryInterval, + }).encode(stream.writer, VERSION); + } catch { + // The publisher reset the request out from under us. + } +} + +/** + * A publisher serving `origin`, which is what a session publishes from: the broadcasts + * are the origin's, so a test publishes and unpublishes through it rather than the + * publisher. + */ +function publisher( + transport: WebTransport, + requiresSolicitation = false, + session?: Session, +): { pub: Publisher; origin: OriginProducer } { + const origin = new OriginProducer(); + const inner = session ?? new NativeSession(transport, VERSION, true); + return { pub: new Publisher(transport, inner, origin.consume(), requiresSolicitation), origin }; +} + +/** + * Every advertisement waits a round trip for the peer's reply. A broadcast published in + * that window has to survive it: the loop is not watching the signal while it waits, so + * a listener registered afterwards would sleep through the notification and leave the + * namespace unadvertised until something unrelated changed. + */ +test("a broadcast published mid-advertisement is still announced", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + + origin.publish(Path.from("first")); + + void pub.runPublishNamespaces(); + + // Take the first advertisement but withhold the reply, parking the loop. + const one = await nextStream(pair.client); + if (!one) throw new Error("no PUBLISH_NAMESPACE for the first broadcast"); + expect(await readPublishNamespace(one)).toBe(Path.from("first")); + + // Publish while the loop is parked on that reply. + origin.publish(Path.from("second")); + await new Promise((resolve) => setTimeout(resolve, SETTLE)); + + await acceptPublishNamespace(one); + + const two = await nextStream(pair.client); + if (!two) throw new Error("the broadcast published mid-advertisement was never announced"); + expect(await readPublishNamespace(two)).toBe(Path.from("second")); + await acceptPublishNamespace(two); + + origin.close(); +}); + +/** + * A peer may decline an advertisement and stay connected. Recording it as advertised + * anyway would strand the namespace: nothing re-adds it to the diff, so it would never + * be offered again for the life of the session. + */ +test("a declined advertisement is retried on the next change", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + + origin.publish(Path.from("first")); + + void pub.runPublishNamespaces(); + + const declined = await nextStream(pair.client); + if (!declined) throw new Error("no PUBLISH_NAMESPACE for the first broadcast"); + expect(await readPublishNamespace(declined)).toBe(Path.from("first")); + await declinePublishNamespace(declined); + + // Any later change re-runs the diff, which is where the refused namespace has to + // reappear rather than being remembered as up. + origin.publish(Path.from("second")); + + const seen = new Set(); + for (let i = 0; i < 2; i++) { + const stream = await nextStream(pair.client); + if (!stream) break; + seen.add(await readPublishNamespace(stream)); + await acceptPublishNamespace(stream); + } + + expect(seen).toContain(Path.from("second")); + expect(seen).toContain(Path.from("first")); + + origin.close(); +}); + +/** + * A peer out of stream credit rejects the open. That has to cost the namespace a turn, + * not the session its discovery: the announce loop is never restarted, so unwinding it + * would lose every future publish too. + */ +test("a failed stream open does not kill the announce loop", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const inner = new NativeSession(pair.server, VERSION, true); + + let failures = 1; + const session: Session = { + version: inner.version, + acceptBi: () => inner.acceptBi(), + nextRequestId: () => inner.nextRequestId(), + close: () => inner.close(), + openBi: () => { + if (failures-- > 0) throw new Error("no stream credit"); + return inner.openBi(); + }, + }; + + const { pub, origin } = publisher(pair.server, false, session); + origin.publish(Path.from("first")); + + void pub.runPublishNamespaces(); + await new Promise((resolve) => setTimeout(resolve, SETTLE)); + + // The refused open cost "first" its turn; the next change has to bring it back along + // with the newcomer. + origin.publish(Path.from("second")); + + const seen = new Set(); + for (let i = 0; i < 2; i++) { + const stream = await nextStream(pair.client); + if (!stream) break; + seen.add(await readPublishNamespace(stream)); + await acceptPublishNamespace(stream); + } + + expect(seen).toContain(Path.from("first")); + expect(seen).toContain(Path.from("second")); + + origin.close(); +}); + +/** + * Capacity coming back raises no signal of its own: no broadcast is published, closed, or + * changed. The loop has to come back and ask again on its own, or a namespace refused + * once stays undiscoverable for the session. + */ +test("a namespace refused once is retried without anything else changing", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const inner = new NativeSession(pair.server, VERSION, true); + + let failures = 1; + const session: Session = { + version: inner.version, + acceptBi: () => inner.acceptBi(), + nextRequestId: () => inner.nextRequestId(), + close: () => inner.close(), + openBi: () => { + if (failures-- > 0) throw new Error("no stream credit"); + return inner.openBi(); + }, + }; + + const { pub, origin } = publisher(pair.server, false, session); + origin.publish(Path.from("lonely")); + + void pub.runPublishNamespaces(); + + // Nothing else happens: no second publish, no close. Only the retry can save it. + const stream = await nextStream(pair.client); + if (!stream) throw new Error("the refused namespace was never retried"); + expect(await readPublishNamespace(stream)).toBe(Path.from("lonely")); + await acceptPublishNamespace(stream); + + origin.close(); +}); + +/** + * The solicited legacy path advertises with PUBLISH_NAMESPACE requests too, so a declined + * one needs the same retry the unsolicited loop has. Without it, a namespace refused once + * stays undiscoverable for the life of the subscription, since the peer starting to + * answer raises no signal the loop is watching. + */ +test("a solicited legacy advertisement refused once is retried", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const inner = new NativeSession(pair.server, Version.DRAFT_15, true); + + let failures = 1; + const session: Session = { + version: inner.version, + acceptBi: () => inner.acceptBi(), + nextRequestId: () => inner.nextRequestId(), + close: () => inner.close(), + openBi: () => { + if (failures-- > 0) throw new Error("no stream credit"); + return inner.openBi(); + }, + }; + + // The peer declared that advertisements to it must be solicited, so this is the loop + // that answers its SUBSCRIBE_NAMESPACE. + const { pub, origin } = publisher(pair.server, true, session); + origin.publish(Path.from("lonely")); + + const subscription = await Stream.open(pair.client, { version: Version.DRAFT_15 }); + const accepted = await Stream.accept(pair.server, Version.DRAFT_15); + if (!accepted) throw new Error("the subscription stream was never accepted"); + void pub.runSubscribeNamespace(new SubscribeNamespace({ requestId: 0n, namespace: Path.empty() }), accepted); + + // Nothing else happens: no second publish, no close. Only the retry can save it. + const stream = await nextStream(pair.client); + if (!stream) throw new Error("the refused namespace was never retried"); + expect(await readPublishNamespace(stream)).toBe(Path.from("lonely")); + await acceptPublishNamespace(stream); + + subscription.close(); + origin.close(); +}); + +/** + * A peer that refuses an advertisement with a retry interval of 0 is asking not to be + * offered it again. Coming back anyway turns a permanent refusal (unauthorized, + * uninterested) into a request every few seconds for the life of the session. + */ +test("a refusal that forbids retrying is not retried", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + origin.publish(Path.from("lonely")); + + void pub.runPublishNamespaces(); + + const stream = await nextStream(pair.client); + if (!stream) throw new Error("the namespace was never advertised"); + expect(await readPublishNamespace(stream)).toBe(Path.from("lonely")); + await declinePublishNamespace(stream, 0n); + + // Well past the retry the loop would otherwise take. + expect(await nextStream(pair.client)).toBeUndefined(); + + origin.close(); +}); + +/** + * The same rule with no gap to observe: republishing a path swaps the routing front in one + * mutation, so the path never leaves the origin's map and only the front says the peer is + * being offered a different broadcast. Keying the refusal on the path alone would strand + * the replacement for the life of the session. + */ +test("republishing a path clears a refusal without unannouncing first", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + + origin.publish(Path.from("recycled")); + + void pub.runPublishNamespaces(); + + const declined = await nextStream(pair.client); + if (!declined) throw new Error("the namespace was never advertised"); + expect(await readPublishNamespace(declined)).toBe(Path.from("recycled")); + await declinePublishNamespace(declined, 0n); + await new Promise((resolve) => setTimeout(resolve, SETTLE)); + + // A new broadcast takes the path over outright: no close, no gap. + origin.publish(Path.from("recycled")); + + const retried = await nextStream(pair.client); + if (!retried) throw new Error("the replacement broadcast was never offered"); + expect(await readPublishNamespace(retried)).toBe(Path.from("recycled")); + await acceptPublishNamespace(retried); + + origin.close(); +}); + +/** + * A refusal belongs to the namespace, not the path forever. Unannouncing takes it with + * it, so a fresh broadcast at the same path is offered again; keeping it would strand + * that path for the life of the session with no timer able to recover it. Rust gets this + * by rebuilding the watched entry on re-announce. + */ +test("re-announcing a path clears a refusal that forbade retrying", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + + const first = origin.publish(Path.from("recycled")); + + void pub.runPublishNamespaces(); + + const declined = await nextStream(pair.client); + if (!declined) throw new Error("the namespace was never advertised"); + expect(await readPublishNamespace(declined)).toBe(Path.from("recycled")); + await declinePublishNamespace(declined, 0n); + + // The broadcast goes away, taking the refusal with it, and a new one takes its place. + first.close(); + await new Promise((resolve) => setTimeout(resolve, SETTLE)); + origin.publish(Path.from("recycled")); + + const retried = await nextStream(pair.client); + if (!retried) throw new Error("a re-announced path was never offered again"); + expect(await readPublishNamespace(retried)).toBe(Path.from("recycled")); + await acceptPublishNamespace(retried); + + origin.close(); +}); + +/** + * The origin outlives the session and its signal never ends, so a closed connection + * reaches this loop through nothing it watches. Left unbounded it parks on the shared + * origin forever, waking on an unrelated publish to fail against a dead transport. + */ +test("closing the session ends the unsolicited announce loop", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server); + + origin.publish(Path.from("first")); + + const loop = pub.runPublishNamespaces(); + + const one = await nextStream(pair.client); + if (!one) throw new Error("no PUBLISH_NAMESPACE for the first broadcast"); + expect(await readPublishNamespace(one)).toBe(Path.from("first")); + await acceptPublishNamespace(one); + + // The session ends. The origin is untouched: it is shared, and other sessions keep using it. + pair.server.close(); + + await Promise.race([ + loop, + new Promise((_resolve, reject) => + setTimeout(() => reject(new Error("the announce loop outlived its session")), STREAM_WAIT), + ), + ]); + + // The origin really did survive the session, so publishing into it is still valid. + origin.publish(Path.from("second")); + origin.close(); +}); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index c50584ae38d..14f43c5f6da 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -6,6 +6,7 @@ import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; import { type Stream, Writer } from "../stream.ts"; import type { Timescale } from "../time.ts"; +import { withTimeout } from "../util/timeout.ts"; import type { Session } from "./adapter.ts"; import { Frame, Group as GroupMessage } from "./object.ts"; import { fromWire } from "./priority.ts"; @@ -22,6 +23,34 @@ import { import { TrackStatus, type TrackStatusRequest } from "./track.ts"; import { Version } from "./version.ts"; +/** First wait before re-offering a namespace the peer refused or we couldn't open for. */ +const RETRY_BASE = 100; + +/** Ceiling on that wait. The loop retries for the life of the session, so it must not spin. */ +const RETRY_MAX = 5000; + +/** + * How long one advertisement may take to be answered. Matches the Rust publisher, and the + * peer accepting the stream is only half the exchange: one it never answers on holds the + * loop just as effectively as one it never grants. + */ +const ADVERTISE_TIMEOUT_MS = 5000; + +/** Sleep `delay`, jittered, so a relay's namespaces don't all retry on the same tick. */ +function retryAfter(delay: number): Promise { + return new Promise((resolve) => setTimeout(resolve, delay * (0.5 + Math.random() / 2))); +} + +/** + * What a refusal said about re-offering the namespace. + * + * A peer answers a request it declines with a retry interval, and ignoring it is how a + * permanent refusal (unauthorized, uninterested) turns into a request every few seconds + * for the life of the session. `"never"` is an interval of 0; a number is the epoch + * milliseconds before which we must not come back. + */ +type Refused = "never" | number; + /** What {@link Publisher.runGroup} needs to serve one group. */ interface RunGroup { /** The subscription's request ID, doubling as the track alias. */ @@ -46,12 +75,13 @@ interface RunGroup { export class Publisher { #quic: WebTransport; #session: Session; + #requiresSolicitation: boolean; // The published broadcasts, borrowed from the origin this session serves. The origin // outlives the session, so this is read-only here: subscribe_namespace streams watch it // for changes, and closing the session leaves the broadcasts alone. The namespaces are - // only advertised in response to a SUBSCRIBE_NAMESPACE (see {@link runSubscribeNamespace}), - // mirroring the moq-lite publisher. + // advertised with an unsolicited PUBLISH_NAMESPACE (see {@link runPublishNamespaces}), or on + // request if the peer asked for that (see {@link runSubscribeNamespace}). #broadcasts: Getter | undefined>; /** @@ -59,13 +89,20 @@ export class Publisher { * @param quic - The WebTransport session (for uni streams) * @param session - The session abstraction for bidi streams and request IDs * @param publish - The origin whose broadcasts this session serves; omit to publish nothing + * @param requiresSolicitation - Whether the peer's SETUP asked to be told on request * * @internal */ - constructor(quic: WebTransport, session: Session, publish?: OriginConsumer) { + constructor( + quic: WebTransport, + session: Session, + publish: OriginConsumer | undefined, + requiresSolicitation: boolean, + ) { this.#quic = quic; this.#session = session; this.#broadcasts = publish?.broadcasts ?? new Signal(new Map()); + this.#requiresSolicitation = requiresSolicitation; } /** @@ -237,11 +274,11 @@ export class Publisher { /** * Handles an incoming SUBSCRIBE_NAMESPACE on a bidi stream. * - * Namespaces are only advertised in response to one of these, and the state - * is local to this stream's task, mirroring the moq-lite publisher. Draft-16+ - * streams Namespace/NamespaceDone entries inline; draft-14/15 predate those - * messages, so each advertisement is a PUBLISH_NAMESPACE request of its own - * over the control stream, closed out with PUBLISH_NAMESPACE_DONE. + * This carries the advertisements only when the peer asked to be told on request + * (MoQ Solicit); otherwise {@link runPublishNamespaces} has already announced + * everything and repeating it here would leave the peer holding two sources for one + * broadcast. Draft-16+ streams Namespace entries inline; draft-14/15 predate those + * messages, so each advertisement is a PUBLISH_NAMESPACE request of its own. * * @internal */ @@ -267,65 +304,112 @@ export class Publisher { await ok.encode(stream.writer, version); } - const advertise = async (suffix: Path.Valid) => { + if (!this.#requiresSolicitation) { + // Already announced, unasked. Hold the stream open until the peer is done. + await stream.reader.closed; + stream.close(); + return; + } + + // Reports whether the peer now holds the namespace: an inline entry always + // lands, but a PUBLISH_NAMESPACE request can be declined. + const advertise = async (suffix: Path.Valid): Promise => { if (legacy) { - await this.#advertise(prefix, suffix, requests); - } else { - await stream.writer.u53(SubscribeNamespaceEntry.id); - await new SubscribeNamespaceEntry({ suffix }).encode(stream.writer, version); + return await this.#advertise(Path.join(prefix, suffix), requests, refused); } + + await stream.writer.u53(SubscribeNamespaceEntry.id); + await new SubscribeNamespaceEntry({ suffix }).encode(stream.writer, version); + return true; }; const withdraw = async (suffix: Path.Valid) => { if (legacy) { - await this.#withdraw(suffix, requests); + await this.#withdraw(Path.join(prefix, suffix), requests); } else { await stream.writer.u53(SubscribeNamespaceEntryDone.id); await new SubscribeNamespaceEntryDone({ suffix }).encode(stream.writer, version); } }; - // Advertise the currently published broadcasts under the prefix. Keyed by suffix, - // valued by the routing front, so a republish diffs as withdraw-then-advertise - // rather than nothing. + // What the peer holds: keyed by suffix, valued by the routing front, so a republish + // diffs as withdraw-then-advertise rather than nothing. let active = new Map(); - for (const [name, front] of this.#broadcasts.peek() ?? []) { - const suffix = Path.stripPrefix(prefix, name); - if (suffix === null) continue; - active.set(suffix, front); - } - for (const suffix of active.keys()) { - await advertise(suffix); - } + let retry = 0; + // What the peer refused, and whether coming back is worth anything. + const refused = new Map(); + // The front each refusal was about, so a republish at the same path clears it. + const offered = new Map(); - // Wait for updates to the broadcasts. for (;;) { + // Subscribe BEFORE reconciling, for the same reason as + // {@link runPublishNamespaces}: a publish landing while an advertisement + // waits for its reply only notifies listeners already registered. // TODO Make a better helper within Signals. let dispose!: Dispose; const changed = new Promise | undefined>((resolve) => { dispose = this.#broadcasts.changed(resolve); }); - // Wait until the map of broadcasts changes or the peer unsubscribes. - const broadcasts = await Promise.race([changed, stream.reader.closed]); - dispose(); - if (!broadcasts) break; + const broadcasts = this.#broadcasts.peek(); + if (!broadcasts) { + dispose(); + break; + } - const newActive = new Map(); + const updated = new Map(); for (const [name, front] of broadcasts) { const suffix = Path.stripPrefix(prefix, name); if (suffix === null) continue; - newActive.set(suffix, front); + updated.set(suffix, front); + } + + // A namespace that is gone, or that a republish replaced, takes its refusal with + // it: the peer refused a broadcast, not a path forever, so a different one at + // the same path is offered again. The origin swaps the front in one mutation, + // so the path never leaves `updated` and only the front says they differ. + for (const path of [...refused.keys()]) { + const suffix = Path.stripPrefix(prefix, path); + const front = suffix === null ? undefined : updated.get(suffix); + if (front === undefined || offered.get(path) !== front) { + refused.delete(path); + offered.delete(path); + } } + // Track what the peer holds rather than what we attempted: a declined + // advertisement stays out of `held`, so the next turn retries it instead of + // believing the namespace is already up. + const held = new Map(active); // Withdraw first so a republish reads as withdraw-then-advertise (a restart). for (const [removed, front] of active) { - if (newActive.get(removed) !== front) await withdraw(removed); + if (updated.get(removed) === front) continue; + await withdraw(removed); + held.delete(removed); } - for (const [added, front] of newActive) { - if (active.get(added) !== front) await advertise(added); + for (const [added, front] of updated) { + if (held.get(added) === front) continue; + if (!this.#offerable(Path.join(prefix, added), refused)) continue; + offered.set(Path.join(prefix, added), front); + if (await advertise(added)) held.set(added, front); } - active = newActive; + active = held; + + // Whatever we wanted up and could not get up, as {@link runPublishNamespaces} + // does: only a legacy request can be declined, and nothing about the peer + // starting to answer raises a signal this loop is watching. + const outstanding = [...updated].some( + ([suffix, front]) => + active.get(suffix) !== front && this.#pending(Path.join(prefix, suffix), refused), + ); + retry = outstanding ? Math.min(retry ? retry * 2 : RETRY_BASE, RETRY_MAX) : 0; + + // Wait for the next change, or for the peer to unsubscribe. + const next = await (retry + ? Promise.race([changed, stream.reader.closed, retryAfter(retry).then(() => broadcasts)]) + : Promise.race([changed, stream.reader.closed])); + dispose(); + if (!next) break; } stream.close(); @@ -334,73 +418,259 @@ export class Publisher { console.debug(`subscribe_namespace stream error: ${reason(e)}`); stream.abort(e); } finally { - // This subscription's advertisements die with it: close out every open - // draft-14/15 PUBLISH_NAMESPACE request. - for (const suffix of [...requests.keys()]) { - await this.#withdraw(suffix, requests); + // This subscription's advertisements die with it. + for (const path of [...requests.keys()]) { + await this.#withdraw(path, requests); } } } /** - * Advertise one namespace on its own PUBLISH_NAMESPACE request (draft-14/15, - * which have no NAMESPACE entry message). A declined request is logged and - * skipped rather than failing the subscription. + * Advertise every published broadcast with an unsolicited PUBLISH_NAMESPACE, until + * the publisher is closed. + * + * The peers that never send SUBSCRIBE_NAMESPACE are exactly the ones expecting a + * publisher to announce itself, so announcing is the default. A peer that would + * rather ask says so in its SETUP (MoQ Solicit) and this does nothing, leaving + * {@link runSubscribeNamespace} to carry the advertisements instead. Exactly one of + * the two is live, so the peer never hears a namespace twice. + * + * @internal */ - async #advertise( - prefix: Path.Valid, - suffix: Path.Valid, - requests: Map, - ) { - const path = Path.join(prefix, suffix); + async runPublishNamespaces() { + if (this.#requiresSolicitation) { + // The peer asked to be told on request; runSubscribeNamespace answers it. + return; + } - const requestId = await this.#session.nextRequestId(); - if (requestId === undefined) return; + // The open PUBLISH_NAMESPACE request per advertised path. + const requests = new Map(); + + // The origin outlives the session and its signal never ends, so this loop needs the + // session's own ending to stop: without it a closed connection leaves the loop parked + // on a shared origin forever, waking on someone else's publish to fail on a dead + // transport. `runSubscribeNamespace` gets this from the stream the peer asked on; an + // unsolicited loop has no stream of its own, so the session is what it watches. + const closed = this.#quic.closed.then( + () => undefined, + () => undefined, + ); - const request = await this.#session.openBi(); try { - await request.writer.u53(PublishNamespace.id); - const msg = new PublishNamespace({ requestId, trackNamespace: path }); - await msg.encode(request.writer, this.#session.version); - - // Read response (RequestOk and PublishNamespaceOk share 0x07) - const respTypeId = await request.reader.u53(); - if (respTypeId !== RequestOk.id) { - throw new Error(`PublishNamespace rejected: typeId=0x${respTypeId.toString(16)}`); + // What the peer holds: keyed by path, valued by the routing front, so a republish + // diffs as withdraw-then-advertise rather than nothing. + let active = new Map(); + let retry = 0; + // What the peer refused, and whether coming back is worth anything. + const refused = new Map(); + // The front each refusal was about, so a republish at the same path clears it. + const offered = new Map(); + + for (;;) { + // Subscribe BEFORE reconciling. Each advertisement below waits a round trip + // for the peer's reply, and a publish that lands in that window notifies + // only the listeners already registered; one created afterwards would sleep + // through it and leave the namespace unadvertised until something unrelated + // changed. + // TODO Make a better helper within Signals. + let dispose!: Dispose; + const changed = new Promise | undefined>((resolve) => { + dispose = this.#broadcasts.changed(resolve); + }); + + const broadcasts = this.#broadcasts.peek(); + if (!broadcasts) { + dispose(); + break; + } + + const updated = new Map(broadcasts); + + // A namespace that is gone, or that a republish replaced, takes its refusal with + // it: the peer refused a broadcast, not a path forever, so a different one at + // the same path is offered again. Rust gets this by rebuilding the watched entry. + for (const path of [...refused.keys()]) { + const front = updated.get(path); + if (front === undefined || offered.get(path) !== front) { + refused.delete(path); + offered.delete(path); + } + } + + // Withdraw first so a republish reads as withdraw-then-advertise (a restart) + // rather than nothing: the front changed, so the peer is holding a broadcast + // that no longer exists. + for (const [removed, front] of active) { + if (updated.get(removed) === front) continue; + await this.#withdraw(removed, requests); + } + for (const [added, front] of updated) { + if (active.get(added) === front) continue; + if (!this.#offerable(added, refused)) continue; + offered.set(added, front); + await this.#advertise(added, requests, refused); + } + + // What the peer holds, not what we attempted: a declined PUBLISH_NAMESPACE + // leaves no request behind, so it stays outstanding below. + active = new Map( + [...requests.keys()].flatMap((path) => { + const front = updated.get(path); + return front ? [[path, front] as const] : []; + }), + ); + + // Whatever we wanted up and could not get up. Stream credit freeing, a + // transient failure clearing, or the peer starting to answer raises no + // signal of its own, so the only way back is to ask again on a timer. + const outstanding = [...updated].some( + ([path, front]) => active.get(path) !== front && this.#pending(path, refused), + ); + retry = outstanding ? Math.min(retry ? retry * 2 : RETRY_BASE, RETRY_MAX) : 0; + + // Wait for the next change, which has already fired if one landed above. + const next = await (retry + ? Promise.race([changed, closed, retryAfter(retry).then(() => broadcasts)]) + : Promise.race([changed, closed])); + dispose(); + if (!next) break; } - // Draft-14 sends PublishNamespaceOk (requestId only, no parameters) - if (this.#session.version === Version.DRAFT_14) { - await PublishNamespaceOk.decode(request.reader, this.#session.version); - } else { - await RequestOk.decode(request.reader, this.#session.version); + } catch (err: unknown) { + // Nothing restarts this loop, so whatever got us here cost the session its + // discovery. Not a debug-level event. + console.warn(`publish_namespace loop failed: ${reason(error(err))}`); + } finally { + // Close out every open PUBLISH_NAMESPACE request. + for (const path of [...requests.keys()]) { + await this.#withdraw(path, requests); } + } + } - requests.set(suffix, { path, requestId, stream: request }); + /** + * Whether a namespace may be offered to the peer right now. + * + * A peer that asked never to be offered it again means it, whatever brought us back; + * one that named a minimum wait gets it, even when our own backoff comes round sooner. + */ + #offerable(path: Path.Valid, refused: Map): boolean { + const entry = refused.get(path); + if (entry === undefined) return true; + return entry !== "never" && Date.now() >= entry; + } + + /** + * Whether the loop should keep coming back to a namespace the peer does not hold. + * + * Distinct from {@link offerable}, and the difference is what arms the retry: a + * namespace waiting out a minimum is not offerable yet but is still pending, and + * gating the timer on offerable instead would disarm it for exactly the wait it is + * supposed to be counting. Only a refusal that forbids retrying ends it. + */ + #pending(path: Path.Valid, refused: Map): boolean { + return refused.get(path) !== "never"; + } + + /** + * Advertise one namespace on its own PUBLISH_NAMESPACE request. A declined request + * is logged and skipped: a peer that wants none of this rejects each one and stays + * connected. + * + * `refused` records what a refusal said about coming back, so a peer that asked not to + * be offered a namespace again is not re-offered it by the retry above. + */ + async #advertise( + path: Path.Valid, + requests: Map, + refused: Map, + ): Promise { + const requestId = await this.#session.nextRequestId(); + if (requestId === undefined) return false; + + // Opening is inside the try because it fails like any other advertisement does: + // a peer out of stream credit rejects here, and letting that escape would unwind + // the announce loop and take discovery down for the whole session, rather than + // costing this one namespace a turn. + let request: Stream | undefined; + try { + request = await this.#session.openBi(); + const stream = request; + + // Bounded, like the subscriber's own request: the loop is single-threaded over + // advertisements, so a peer that takes the stream and answers nothing strands + // every publish and withdrawal behind it. Timing out costs this namespace a + // turn and leaves it outstanding, which the retry above re-offers. + await withTimeout( + (async () => { + await stream.writer.u53(PublishNamespace.id); + const msg = new PublishNamespace({ requestId, trackNamespace: path }); + await msg.encode(stream.writer, this.#session.version); + + // Read response (RequestOk and PublishNamespaceOk share 0x07) + const respTypeId = await stream.reader.u53(); + if (respTypeId === RequestError.id) { + // The peer named how long to stay away, in milliseconds. Draft-14/15 + // carry no such field, so a 0 there says nothing and our own backoff + // stands; everywhere else 0 means it does not want this again. + const err = await RequestError.decode(stream.reader, this.#session.version); + const legacy = + this.#session.version === Version.DRAFT_14 || this.#session.version === Version.DRAFT_15; + if (!legacy) { + refused.set( + path, + err.retryInterval === 0n ? "never" : Date.now() + Number(err.retryInterval), + ); + } + throw new Error(`PublishNamespace rejected: ${err.errorCode} ${err.reasonPhrase}`); + } + if (respTypeId !== RequestOk.id) { + throw new Error(`PublishNamespace rejected: typeId=0x${respTypeId.toString(16)}`); + } + // Draft-14 sends PublishNamespaceOk (requestId only, no parameters) + if (this.#session.version === Version.DRAFT_14) { + await PublishNamespaceOk.decode(stream.reader, this.#session.version); + } else { + await RequestOk.decode(stream.reader, this.#session.version); + } + })(), + ADVERTISE_TIMEOUT_MS, + `advertisement timed out after ${ADVERTISE_TIMEOUT_MS}ms waiting for the peer's answer`, + ); + + requests.set(path, { path, requestId, stream: request }); + return true; } catch (err: unknown) { const e = error(err); console.warn(`announce failed: broadcast=${path} error=${reason(e)}`); - request.abort(e); + request?.abort(e); + return false; } } /** - * Close out a namespace's PUBLISH_NAMESPACE request with PUBLISH_NAMESPACE_DONE - * (draft-14/15). + * Close out a namespace's PUBLISH_NAMESPACE request with PUBLISH_NAMESPACE_DONE. */ async #withdraw( - suffix: Path.Valid, + path: Path.Valid, requests: Map, ) { - const request = requests.get(suffix); + const request = requests.get(path); if (!request) return; - requests.delete(suffix); + requests.delete(path); - try { - await request.stream.writer.u53(PublishNamespaceDone.id); - const done = new PublishNamespaceDone({ trackNamespace: request.path, requestId: request.requestId }); - await done.encode(request.stream.writer, this.#session.version); - } catch { - // Stream might already be closed + // Draft-17+ removed PUBLISH_NAMESPACE_DONE: the close below is the whole + // withdrawal. Sending it anyway puts the type on the wire before the body throws, + // and a receiver reading 0x09 there has no choice but to treat it as a protocol + // violation. + const version = this.#session.version; + if (version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16) { + try { + await request.stream.writer.u53(PublishNamespaceDone.id); + const done = new PublishNamespaceDone({ trackNamespace: request.path, requestId: request.requestId }); + await done.encode(request.stream.writer, version); + } catch { + // Stream might already be closed + } } request.stream.close(); } diff --git a/js/net/src/ietf/solicit.test.ts b/js/net/src/ietf/solicit.test.ts new file mode 100644 index 00000000000..be31565f46f --- /dev/null +++ b/js/net/src/ietf/solicit.test.ts @@ -0,0 +1,48 @@ +import { expect, test } from "bun:test"; +import { SetupOption, SetupOptions } from "./parameters.ts"; +import { solicitFromSetup, solicitIntoSetup } from "./solicit.ts"; + +/** + * We declare it on every session, so a peer honoring it never sends us an unsolicited + * PUBLISH_NAMESPACE. The literal 1 is the wire contract, not an implementation detail. + */ +test("we declare that advertisements must be solicited", () => { + const params = new SetupOptions(); + solicitIntoSetup(params); + + expect(params.getVarint(SetupOption.Solicit)).toBe(1n); + expect(solicitFromSetup(params)).toBe(true); +}); + +/** + * A peer that has never heard of the extension sends nothing, and must keep getting the + * unsolicited announcements it expects. Distinct from an explicit 0, which is what lets + * us tell a peer that ignored our declaration from one that never saw it. + */ +test("an absent option declares nothing", () => { + expect(solicitFromSetup(new SetupOptions())).toBeUndefined(); +}); + +/** + * An explicit 0 asks for the same treatment an absent option does, but it is not the same + * statement: writing the option proves the peer implements this. + */ +test("an explicit zero is a declaration, not an absence", () => { + const params = new SetupOptions(); + params.setVarint(SetupOption.Solicit, 0n); + + expect(solicitFromSetup(params)).toBe(false); +}); + +/** + * A value this draft doesn't define still means "ask me first", so a later revision that + * says more can't be read as saying nothing. + */ +test("any non-zero value requires solicitation", () => { + for (const value of [1n, 2n, 0x8000n]) { + const params = new SetupOptions(); + params.setVarint(SetupOption.Solicit, value); + + expect(solicitFromSetup(params)).toBe(true); + } +}); diff --git a/js/net/src/ietf/solicit.ts b/js/net/src/ietf/solicit.ts new file mode 100644 index 00000000000..a01089dd4ea --- /dev/null +++ b/js/net/src/ietf/solicit.ts @@ -0,0 +1,48 @@ +import { SetupOption, type SetupOptions } from "./parameters.ts"; + +/** + * The MoQ Solicit extension (draft-lcurley-moq-solicit-00). + * + * moq-transport says nothing about whether an endpoint expects to be told what we have or + * to ask for it, so a publisher that waits to be asked is silent against a relay that + * never asks. This extension lets an endpoint declare, in its SETUP, that advertisements + * to it must be solicited first. + * + * Declaring nothing means "no requirement, tell me unasked", which is what a peer that has + * never heard of the extension implicitly says. + * + * @module + * @internal + */ + +/** + * What the peer declared, if anything. + * + * The three states are distinct, and the difference between the last two is what makes the + * requirement enforceable: + * + * - `undefined`: no option at all. The peer has never heard of the extension, so it cannot + * have honored ours and an unsolicited advertisement from it is expected. + * - `false`: an explicit 0. No requirement of its own, but writing the option at all proves + * it implements this, so it is held to ours. + * - `true`: advertisements to it must be solicited, and likewise held to ours. + * + * @internal + */ +export function solicitFromSetup(params: SetupOptions): boolean | undefined { + const value = params.getVarint(SetupOption.Solicit); + return value === undefined ? undefined : value !== 0n; +} + +/** + * Declare that advertisements to us must be solicited. + * + * Unconditional, and true of every session: we send SUBSCRIBE_NAMESPACE for each prefix + * we want, so there is nothing an unsolicited PUBLISH_NAMESPACE could tell us that we + * will not have asked for. + * + * @internal + */ +export function solicitIntoSetup(params: SetupOptions) { + params.setVarint(SetupOption.Solicit, 1n); +} diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts new file mode 100644 index 00000000000..768713672ea --- /dev/null +++ b/js/net/src/ietf/subscriber.test.ts @@ -0,0 +1,332 @@ +import { expect, test } from "bun:test"; +import type * as announce from "../announced.ts"; +import { createMockTransportPair } from "../mock.ts"; +import * as Path from "../path.ts"; +import { Stream } from "../stream.ts"; +import { NativeSession } from "./adapter.ts"; +import { PublishNamespace } from "./publish_namespace.ts"; +import { RequestOk } from "./request.ts"; +import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDone } from "./subscribe_namespace.ts"; +import { Subscriber } from "./subscriber.ts"; +import { ALPN, Version } from "./version.ts"; + +const VERSION = Version.DRAFT_19; + +/** How long to wait for a stream before calling it absent. */ +const STREAM_WAIT = 500; + +/** + * Accept the next stream the subscriber opens, or give up rather than hang forever. + * + * Reads the queue directly instead of racing {@link Stream.accept}, whose pending read + * would keep the reader locked after the race resolves and could swallow a later stream. + */ +async function nextStream(transport: WebTransport): Promise { + const reader = + transport.incomingBidirectionalStreams.getReader() as ReadableStreamDefaultReader; + + let timer: ReturnType | undefined; + try { + const next = await Promise.race([ + reader.read(), + new Promise((resolve) => { + timer = setTimeout(() => resolve(undefined), STREAM_WAIT); + }), + ]); + + if (!next || next.done) return undefined; + return new Stream({ readable: next.value.readable, writable: next.value.writable, version: VERSION }); + } finally { + clearTimeout(timer); + reader.releaseLock(); + } +} + +/** + * Every peer is asked, whatever it declared. A peer with nothing to advertise answers + * with an empty set, which costs one stream, and a peer that only answers when asked is + * the one that would otherwise never be discovered. + */ +test("every peer is asked", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + + const subscriber = new Subscriber(session); + subscriber.announced(Path.empty()); + + expect(await nextStream(pair.client)).toBeDefined(); +}); + +/** + * The other half of discovery: a peer that tells us unasked. Asking must not make us deaf + * to a PUBLISH_NAMESPACE that arrives on its own stream instead. + */ +test("an unsolicited announcement lands", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber(session); + + const announced = subscriber.announced(Path.empty()); + + // The question we asked, which this peer never answers. + expect(await nextStream(pair.client)).toBeDefined(); + + // What the connection dispatch does when a PUBLISH_NAMESPACE arrives instead. + const stream = await Stream.open(pair.server, { version: VERSION }); + const handler = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("surprise") }), + stream, + ); + + const next = await announced.next(); + expect(next?.path).toBe(Path.from("surprise")); + expect(next?.active).toBe(true); + + // The handler holds the request open until the peer drops it, and withdraws the + // namespace on the way out. + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream to close"); + peer.close(); + await handler; + expect(await announced.next()).toMatchObject({ path: Path.from("surprise"), active: false }); +}); + +/** + * Answer the SUBSCRIBE_NAMESPACE the subscriber just opened, then hand back its stream so + * the test can feed inline NAMESPACE entries down it. + */ +async function acceptSubscribeNamespace(transport: WebTransport): Promise { + const stream = await nextStream(transport); + if (!stream) throw new Error("no SUBSCRIBE_NAMESPACE was sent"); + + // Drain the request, then answer it. + await stream.reader.u53(); + await SubscribeNamespace.decode(stream.reader, VERSION); + await stream.writer.u53(RequestOk.id); + await new RequestOk({ requestId: undefined }).encode(stream.writer, VERSION); + + return stream; +} + +/** Advertise `path` inline on a SUBSCRIBE_NAMESPACE stream. */ +async function inlineNamespace(stream: Stream, path: Path.Valid): Promise { + await stream.writer.u53(SubscribeNamespaceEntry.id); + await new SubscribeNamespaceEntry({ suffix: path }).encode(stream.writer, VERSION); +} + +/** + * Advertise a path nothing else uses and wait for it, which proves the entries written + * before it on the same stream have been read. Announcing an already-announced path is + * silent by design, so it cannot be waited on directly. + */ +async function syncInline(stream: Stream, announced: announce.Consumer): Promise { + await inlineNamespace(stream, Path.from("sentinel")); + expect(await announced.next()).toMatchObject({ path: Path.from("sentinel"), active: true }); +} + +/** + * A peer may advertise one namespace both ways on a session: an unsolicited + * PUBLISH_NAMESPACE and an inline NAMESPACE answering our own SUBSCRIBE_NAMESPACE are two + * messages about one source, and the MoQ Solicit draft requires us to tolerate it. + * + * The unsolicited request ending must not retract what the subscription still holds, or a + * watcher drops a broadcast that is still being published. + */ +test("an announcement survives the first of its two sources ending", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber(session); + + const announced = subscriber.announced(Path.empty()); + const subscription = await acceptSubscribeNamespace(pair.client); + + // Unsolicited first, then the same path inline on the subscription. + const request = await Stream.open(pair.server, { version: VERSION }); + const handler = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("both") }), + request, + ); + expect(await announced.next()).toMatchObject({ path: Path.from("both"), active: true }); + + await inlineNamespace(subscription, Path.from("both")); + await syncInline(subscription, announced); + + // The unsolicited request goes away. The subscription still advertises the path, so + // nothing has been withdrawn and there is nothing for the consumer to hear. + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream to close"); + peer.close(); + await handler; + + const next = await Promise.race([ + announced.next(), + new Promise<"nothing">((resolve) => setTimeout(() => resolve("nothing"), 250)), + ]); + expect(next).toBe("nothing"); +}); + +/** + * The mirror of the above, and the reason the count exists rather than a flag: once the + * last source goes, the path really is gone and consumers have to hear it. + */ +test("an announcement ends once its last source does", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber(session); + + const announced = subscriber.announced(Path.empty()); + const subscription = await acceptSubscribeNamespace(pair.client); + + const request = await Stream.open(pair.server, { version: VERSION }); + const handler = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("both") }), + request, + ); + expect(await announced.next()).toMatchObject({ path: Path.from("both"), active: true }); + + await inlineNamespace(subscription, Path.from("both")); + await syncInline(subscription, announced); + + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream to close"); + peer.close(); + await handler; + + // Now the subscription drops it too, which is the last reference. + await subscription.writer.u53(SubscribeNamespaceEntryDone.id); + await new SubscribeNamespaceEntryDone({ suffix: Path.from("both") }).encode(subscription.writer, VERSION); + + expect(await announced.next()).toMatchObject({ path: Path.from("both"), active: false }); +}); + +/** + * A stream owns every advertisement it carried, so losing it retracts them: closing a + * subscription withdraws nothing on the wire, since NAMESPACE_DONE is what does that. + * Whatever is still live outlived its channel, and a count left behind would pin the path + * for the rest of the session, for every other consumer too. + */ +test("a subscription that dies releases what it advertised", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber(session); + + // Two feeds, so one outlives the stream that carries the advertisement. + const doomed = subscriber.announced(Path.empty()); + const streamA = await acceptSubscribeNamespace(pair.client); + const survivor = subscriber.announced(Path.empty()); + await acceptSubscribeNamespace(pair.client); + + await inlineNamespace(streamA, Path.from("orphan")); + expect(await doomed.next()).toMatchObject({ path: Path.from("orphan"), active: true }); + expect(await survivor.next()).toMatchObject({ path: Path.from("orphan"), active: true }); + + // The stream that advertised it goes away without a NAMESPACE_DONE. + streamA.writer.close(); + + expect(await survivor.next()).toMatchObject({ path: Path.from("orphan"), active: false }); +}); + +/** + * Draft-14/15 name their namespace-scoped messages instead of numbering them, so the + * adapter can hold one request per namespace. A second would overwrite the first and the + * withdrawals would go to the wrong stream, then to none at all, killing the session. The + * case that makes a second reference legitimate needs an inline NAMESPACE, which those + * drafts do not have. + */ +test("a duplicate legacy publish_namespace is still refused", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, Version.DRAFT_15, true); + const subscriber = new Subscriber(session); + + const announced = subscriber.announced(Path.empty()); + + const first = await Stream.open(pair.server, { version: Version.DRAFT_15 }); + const handler = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("twice") }), + first, + ); + expect(await announced.next()).toMatchObject({ path: Path.from("twice"), active: true }); + + // The same namespace again, on its own request. + const second = await Stream.open(pair.server, { version: Version.DRAFT_15 }); + await subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 2n, trackNamespace: Path.from("twice") }), + second, + ); + + // Refused, so it took no reference: the first request ending still retracts the path. + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream to close"); + peer.close(); + await handler; + + expect(await announced.next()).toMatchObject({ path: Path.from("twice"), active: false }); +}); + +/** + * The read loop is not awaited when the local consumer closes first, and closing the + * stream cancels the transport without discarding what the reader already buffered. An + * entry that decodes after the teardown must not take a reference, or the path is pinned + * for the session with nobody left to release it. + */ +test("an entry buffered past a consumer close does not pin the path", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber(session); + + const announced = subscriber.announced(Path.empty()); + const subscription = await acceptSubscribeNamespace(pair.client); + + // Both entries land in one chunk, so the second is buffered while the first is being + // delivered. Closing the consumer then races the loop that would attach it. + await inlineNamespace(subscription, Path.from("first")); + await inlineNamespace(subscription, Path.from("buffered")); + + announced.close(); + + // Whatever the loop managed to attach, the stream gave back on its way out. + await new Promise((resolve) => setTimeout(resolve, 50)); + + const fresh = subscriber.announced(Path.empty()); + const seeded = await Promise.race([ + fresh.next(), + new Promise<"nothing">((resolve) => setTimeout(() => resolve("nothing"), 250)), + ]); + expect(seeded).toBe("nothing"); +}); + +/** + * The reservation has to be synchronous. The count is only taken once the OK is written, + * so two legacy requests dispatched together would both get past a check that looked only + * at what is announced, and both would take a reference for one namespace. + */ +test("concurrent legacy publish_namespace requests take one reference", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, Version.DRAFT_15, true); + const subscriber = new Subscriber(session); + + const announced = subscriber.announced(Path.empty()); + + // Dispatched together, as the connection would on two incoming streams. + const first = await Stream.open(pair.server, { version: Version.DRAFT_15 }); + const second = await Stream.open(pair.server, { version: Version.DRAFT_15 }); + const one = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("raced") }), + first, + ); + const two = subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 2n, trackNamespace: Path.from("raced") }), + second, + ); + + expect(await announced.next()).toMatchObject({ path: Path.from("raced"), active: true }); + await two; + + // Only one reference was taken, so the surviving request ending retracts the path. + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream to close"); + peer.close(); + await one; + + expect(await announced.next()).toMatchObject({ path: Path.from("raced"), active: false }); +}); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 470caf999f1..ad0e630b362 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -60,8 +60,19 @@ export class Subscriber { // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. #consumes = new BroadcastCache(); - // Any currently active announcements. - #announced = new Set(); + // Paths with a legacy PUBLISH_NAMESPACE request in flight, reserved synchronously. + // The count below is only taken once the OK is written, and two requests that both + // got past the duplicate check before either attached would both take one. + #legacyRequests = new Set(); + + // Every announced path, counted by how many live advertisements reference it. + // + // A peer may advertise one namespace twice on a session: an unsolicited + // PUBLISH_NAMESPACE and an inline NAMESPACE answering our own SUBSCRIBE_NAMESPACE are + // two messages about one source, which the MoQ Solicit draft requires us to tolerate. + // Counting them is what keeps the second from duplicating the announce and the first + // to end from retracting what the other still holds. + #announced = new Map(); // Any consumers that want each new announcement. #announcedConsumers = new Set(); @@ -78,10 +89,14 @@ export class Subscriber { /** * Gets an announced reader for the specified prefix. + * + * The peer is asked with SUBSCRIBE_NAMESPACE regardless of what it declared, and an + * unsolicited PUBLISH_NAMESPACE lands here too, so a peer that only tells and one + * that only answers are both discovered. */ announced(prefix = Path.empty()): announce.Consumer { const announced = new announce.Producer(prefix); - for (const active of this.#announced) { + for (const active of this.#announced.keys()) { const suffix = Path.stripPrefix(prefix, active); if (suffix === null) continue; announced.append({ path: suffix, active: true }); @@ -96,9 +111,66 @@ export class Subscriber { return announced.consume(); } + /** + * Record one more advertisement for a path, telling consumers only when it is the + * first. A second one is the same namespace said twice, not news. + */ + #attachAnnounce(path: Path.Valid) { + const count = this.#announced.get(path) ?? 0; + this.#announced.set(path, count + 1); + if (count > 0) return; + + console.debug(`announced: broadcast=${path} active=true`); + for (const consumer of this.#announcedConsumers) { + const suffix = Path.stripPrefix(consumer.prefix, path); + if (suffix === null) continue; + consumer.append({ path: suffix, active: true }); + } + } + + /** + * Drop one advertisement for a path, retracting it only once the last one goes. + */ + #detachAnnounce(path: Path.Valid) { + const count = this.#announced.get(path); + if (count === undefined) return; + if (count > 1) { + this.#announced.set(path, count - 1); + return; + } + + this.#announced.delete(path); + + // The path is gone, so stop sharing its broadcast: a holder outliving the publisher + // would otherwise hand the dead generation to whoever consumes the path next. + this.#consumes.evict(path); + console.debug(`announced: broadcast=${path} active=false`); + + for (const consumer of this.#announcedConsumers) { + const suffix = Path.stripPrefix(consumer.prefix, path); + if (suffix === null) continue; + try { + consumer.append({ path: suffix, active: false }); + } catch { + // Consumer already closed, will be cleaned up + } + } + } + async #runAnnounced(announced: announce.Producer, prefix: Path.Valid) { const version = this.#session.version; + // Suffixes live on this stream, so a repeat is recognized as an update to the + // advertisement rather than a second one, which would leak the count. + const live = new Set(); + + // Set once the teardown below has given back everything this stream held. The read + // loop is not awaited when the local consumer closes first, and closing the stream + // cancels the transport without discarding what the reader already buffered, so a + // fully buffered entry can still decode afterwards. Attaching one then would take a + // reference nobody is left to release, pinning the path for the session. + let released = false; + // v14/v15: SubscribeNamespace on control stream (via adapter virtual stream) // v16+: SubscribeNamespace on its own real bidi stream @@ -150,26 +222,21 @@ export class Subscriber { const msgType = await stream.reader.u53(); if (msgType === SubscribeNamespaceEntry.id) { const entry = await SubscribeNamespaceEntry.decode(stream.reader, version); + if (released) break; const path = Path.join(prefix, entry.suffix); - console.debug(`announced: broadcast=${path} active=true`); - this.#announced.add(path); - for (const consumer of this.#announcedConsumers) { - const suffix = Path.stripPrefix(consumer.prefix, path); - if (suffix === null) continue; - consumer.append({ path: suffix, active: true }); + // A repeat updates the advertisement; only the first is news. + if (!live.has(path)) { + live.add(path); + this.#attachAnnounce(path); } } else if (msgType === SubscribeNamespaceEntryDone.id) { const entry = await SubscribeNamespaceEntryDone.decode(stream.reader, version); + if (released) break; const path = Path.join(prefix, entry.suffix); - console.debug(`announced: broadcast=${path} active=false`); - - this.#announced.delete(path); - this.#consumes.evict(path); - for (const consumer of this.#announcedConsumers) { - const suffix = Path.stripPrefix(consumer.prefix, path); - if (suffix === null) continue; - consumer.append({ path: suffix, active: false }); + + if (live.delete(path)) { + this.#detachAnnounce(path); } } else if (msgType === PublishBlocked.id && version === Version.DRAFT_17) { const blocked = await PublishBlocked.decode(stream.reader, version); @@ -210,6 +277,16 @@ export class Subscriber { // it from "nothing is published under this prefix" waits forever on a broadcast // that will never be announced. Matches the lite subscriber. announced.close(e); + } finally { + // The stream owns every advertisement it carried, so release them however it + // ends: a clean close, a decode error, or the peer resetting it. Without this + // each namespace keeps its count and the source never detaches, which would + // pin the path for the session even after the other source withdrew. + released = true; + for (const path of live) { + this.#detachAnnounce(path); + } + live.clear(); } } @@ -400,30 +477,40 @@ export class Subscriber { const version = this.#session.version; const path = msg.trackNamespace; - if (this.#announced.has(path)) { + // Draft-14/15 key their namespace-scoped messages by name, not request ID, so the + // adapter can hold only one request per namespace: a second would overwrite the + // first, and the withdrawals would then close the wrong stream and fail to find + // the other. Nothing is lost by refusing it, because the case that makes a second + // reference legitimate (an inline NAMESPACE for a path a PUBLISH_NAMESPACE already + // carried) needs a message those drafts do not have. + const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15; + if (legacy && (this.#announced.has(path) || this.#legacyRequests.has(path))) { console.warn("duplicate PublishNamespace"); if (version === Version.DRAFT_14) { await stream.writer.u53(PublishNamespaceError.id); - const err = new PublishNamespaceError({ + await new PublishNamespaceError({ requestId: msg.requestId, errorCode: 409, reasonPhrase: "duplicate namespace", - }); - await err.encode(stream.writer, version); + }).encode(stream.writer, version); } else { await stream.writer.u53(RequestError.id); - const err = new RequestError({ - requestId: version === Version.DRAFT_15 || version === Version.DRAFT_16 ? msg.requestId : undefined, + await new RequestError({ + requestId: msg.requestId, errorCode: 409, reasonPhrase: "duplicate namespace", - }); - await err.encode(stream.writer, version); + }).encode(stream.writer, version); } stream.close(); return; } - this.#announced.add(path); + // Everywhere else a path this session already knows is not refused: the same + // namespace can reach us twice, and the count is what tells the second apart from + // news. This request owns exactly one of those references and gives it back when + // the stream ends. + if (legacy) this.#legacyRequests.add(path); + let attached = false; try { // Send OK first. This must complete before notifying consumers, @@ -441,34 +528,22 @@ export class Subscriber { await ok.encode(stream.writer, version); } - console.debug(`announced: broadcast=${path} active=true`); - - // Notify consumers after OK is written - for (const consumer of this.#announcedConsumers) { - const suffix = Path.stripPrefix(consumer.prefix, path); - if (suffix === null) continue; - consumer.append({ path: suffix, active: true }); - } + // Only now is the advertisement ours to announce, for the reason above: a + // consumer reacting with a SUBSCRIBE must not interleave with that OK. + attached = true; + this.#attachAnnounce(path); // Wait for stream close (= PublishNamespaceDone) console.debug(`runPublishNamespace: awaiting stream.reader.closed for ${path}`); await stream.reader.closed; console.debug(`runPublishNamespace: stream.reader.closed resolved for ${path}`); } finally { - this.#announced.delete(path); - // The path is gone, so stop sharing its broadcast: a holder outliving the publisher - // would otherwise hand the dead generation to whoever consumes the path next. - this.#consumes.evict(path); - console.debug(`announced: broadcast=${path} active=false`); - - for (const consumer of this.#announcedConsumers) { - const suffix = Path.stripPrefix(consumer.prefix, path); - if (suffix === null) continue; - try { - consumer.append({ path: suffix, active: false }); - } catch { - // Consumer already closed, will be cleaned up - } + if (legacy) this.#legacyRequests.delete(path); + + // Give back exactly what was taken: a request that never got its OK out never + // referenced the path, and retracting there would drop someone else's count. + if (attached) { + this.#detachAnnounce(path); } } } diff --git a/js/publish/package.json b/js/publish/package.json index 8182cb8d8f2..a22729637d5 100644 --- a/js/publish/package.json +++ b/js/publish/package.json @@ -1,7 +1,7 @@ { "name": "@moq/publish", "type": "module", - "version": "0.4.3", + "version": "0.4.4", "jsr": false, "description": "Publish Media over QUIC broadcasts", "license": "(MIT OR Apache-2.0)", diff --git a/js/signals/package.json b/js/signals/package.json index 7a01bbc7e77..cbb6fec7ea7 100644 --- a/js/signals/package.json +++ b/js/signals/package.json @@ -1,7 +1,7 @@ { "name": "@moq/signals", "type": "module", - "version": "0.2.1", + "version": "0.2.2", "description": "Reactive and safe signals", "license": "(MIT OR Apache-2.0)", "repository": "github:moq-dev/moq", diff --git a/justfile b/justfile index 386953ea99b..3801338dcbc 100644 --- a/justfile +++ b/justfile @@ -90,13 +90,8 @@ _changed $BASE: # to invoke it. Takes the same file list as the dispatch, or `ALL` to require # everything (`check-all`). # -# Two deliberate absences: -# - swift exists only on macOS, and `swift check` skips off-macOS by design; -# swift.yml is its real gate. -# - go and uniffi-bindgen-go are NOT in the dev shell (uniffi-bindgen-go isn't -# in nixpkgs; it installs from a NordSecurity git tag). Requiring them would -# fail every Go-scoped PR, so `just go check` still skips itself in CI, as it -# always has. Packaging them is what would close that hole. +# One deliberate absence: swift exists only on macOS, and `swift check` skips +# off-macOS by design; swift.yml is its real gate. # Fail when a tool the diff's scopes need is missing. No-op unless MOQ_STRICT. [private] @@ -112,12 +107,20 @@ _tools $FILES="": scoped '^(rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo) scoped '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/)' && tools+=(uv) scoped '^(kt/|rs/moq-ffi/)' && tools+=(gradle java) + # cargo because `go check` builds moq-ffi for the host, and skips on a + # missing cargo the same way it skips on a missing go. + scoped '^(go/|rs/moq-ffi/)' && tools+=(go uniffi-bindgen-go cargo) # The OBS lints ship only in the Linux dev shell; nixpkgs marks obs-studio # broken on Darwin. if [[ "$(uname -s)" == "Linux" ]] && scoped '^cpp/obs/'; then tools+=(clang-format gersemi) fi + # Scopes overlap (rs/moq-ffi/ is in four of them), so the same tool can land + # in the list twice and be reported missing twice. Splitting on whitespace is + # safe: every entry is a bare command name. + tools=($(printf '%s\n' "${tools[@]}" | sort -u)) + missing=() for tool in "${tools[@]}"; do command -v "$tool" >/dev/null 2>&1 || missing+=("$tool") diff --git a/kt/README.md b/kt/README.md index 97826a90df2..d8f76cf6c4a 100644 --- a/kt/README.md +++ b/kt/README.md @@ -14,7 +14,7 @@ Most apps want `dev.moq:moq`. Reach for `dev.moq:moq-ffi` directly only if you w ```kotlin // build.gradle.kts dependencies { - implementation("dev.moq:moq:0.4.2") + implementation("dev.moq:moq:0.4.3") implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0") } ``` @@ -47,6 +47,7 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **`Moq.connect(...)`**: a connection facade (`Moq.kt`), so you never hand-wire a `MoqClient`. - **Typealiases** (`Aliases.kt`): re-export the `Moq*`-prefixed FFI types under clean `dev.moq` names (`OriginProducer`, `BroadcastConsumer`, `Catalog`, `Frame`, ...), so you import `dev.moq.*` only. A couple of sealed types (`Container`, `MoqException`) are not aliased because Kotlin can't resolve their subtypes through a typealias; use `uniffi.moq.*` for those. - **Flow extensions** (`Flows.kt`): `updates()`, `groups()`, `frames()`, `announcements()`, `catalog()` turn the pull-based consumers into coroutine `Flow`s with cancellation wired through. +- **Fetched media**: `fetchMediaGroup(...).frames()` streams the decoded frames of one retained group, then completes. - **`logLevel(...)`**: configures native Rust tracing without importing the raw bindings package. - **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. diff --git a/kt/gradle.properties b/kt/gradle.properties index b9fbaa56604..cf89a5a29f3 100644 --- a/kt/gradle.properties +++ b/kt/gradle.properties @@ -14,7 +14,7 @@ moqffi.version=0.0.0-dev # Wrapper (`dev.moq:moq`) version. Source of truth, bumped by hand. Independent # of the crate: release-kt-lib.yml publishes a new version only when this # changes. Must stay >= the last published wrapper version. -moq.version=0.4.2 +moq.version=0.4.3 # Publishing is disabled by default. CI flips this when MAVEN_CENTRAL_USERNAME # and SIGNING_KEY secrets are configured. See README.md for setup details. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 5a3afee6550..8317d980ce4 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -65,6 +65,8 @@ typealias MediaProducer = uniffi.moq.MoqMediaProducer typealias MediaStreamProducer = uniffi.moq.MoqMediaStreamProducer /** The read side of a media track: yields frames with codec metadata in decode order. */ typealias MediaConsumer = uniffi.moq.MoqMediaConsumer +/** A finite fetched media group: yields container-decoded frames until the group ends. */ +typealias MediaGroupConsumer = uniffi.moq.MoqMediaGroupConsumer /** The write side of a raw-audio track; PCM written here is encoded inside the FFI boundary. */ typealias AudioProducer = uniffi.moq.MoqAudioProducer /** The read side of a raw-audio track: yields decoded PCM frames. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt index 0691266abfc..b17ac90d9c0 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt @@ -23,6 +23,7 @@ import uniffi.moq.MoqJsonSnapshotConsumer import uniffi.moq.MoqJsonStreamConsumer import uniffi.moq.MoqMediaConsumer import uniffi.moq.MoqMediaFrame +import uniffi.moq.MoqMediaGroupConsumer import uniffi.moq.MoqOriginConsumer import uniffi.moq.MoqOriginDynamic import uniffi.moq.MoqRoute @@ -70,6 +71,16 @@ fun MoqMediaConsumer.frames(): Flow = flow { if (cause is CancellationException) cancel() } +/** Stream of decoded frames from one finite, fetched media group. */ +fun MoqMediaGroupConsumer.frames(): Flow = flow { + while (true) { + currentCoroutineContext().ensureActive() + emit(next() ?: break) + } +}.onCompletion { cause -> + if (cause is CancellationException) cancel() +} + /** * Stream of decoded audio frames in the layout declared by the * `MoqAudioDecoderConfig` the consumer was created with. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 5fb124d28bb..8596eefd51b 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -1,6 +1,7 @@ package dev.moq import kotlinx.coroutines.flow.first +import kotlinx.coroutines.flow.toList import kotlinx.coroutines.test.runTest import kotlinx.serialization.Serializable import uniffi.moq.MoqException @@ -13,6 +14,21 @@ import kotlin.test.assertTrue @Serializable private data class Status(val state: String) +private fun opusHead(): ByteArray = + "OpusHead".encodeToByteArray() + byteArrayOf( + 1, + 2, + 0, + 0, + 0x80.toByte(), + 0xbb.toByte(), + 0, + 0, + 0, + 0, + 0, + ) + class SmokeTest { /** * Exercises the [Moq.connect] facade end to end without a network: a bogus @@ -99,6 +115,41 @@ class SmokeTest { } } + /** A fetched media group streams its decoded frames and then completes. */ + @Test + fun `media group helper streams fetched frames`() = runTest { + BroadcastProducer().use { broadcast -> + val media = broadcast.publishMedia( + Init(format = "opus", data = opusHead(), video = null), + ) + val consumer = broadcast.consume() + val (name, audio) = consumer.catalog().audio.entries.single() + + media.writeFrame(Frame(payload = "opus frame".encodeToByteArray(), timestampUs = 5_000_000uL)) + + // Fetch while the track is still published: finishing the media producer + // unpublishes it, and the fetch would then miss with NotFound. + val fetched: MediaGroupConsumer = consumer.fetchMediaGroup( + name, + 0uL, + audio.container, + FetchGroupOptions(priority = 3u), + ) + + // Close the group so the fetched stream terminates instead of waiting for more. + media.finish() + + fetched.use { + assertEquals(0uL, it.sequence()) + val frames = it.frames().toList() + assertEquals(1, frames.size) + val frame = frames.single() + assertEquals("opus frame", frame.payload.decodeToString()) + assertEquals(5_000_000uL, frame.timestampUs) + } + } + } + /** The typed JSON helpers round-trip a `@Serializable` value. */ @Test fun `typed json snapshot round-trips a serializable value`() = runTest { diff --git a/kt/scripts/generate.sh b/kt/scripts/generate.sh index bafcfde22d2..387dafc3204 100755 --- a/kt/scripts/generate.sh +++ b/kt/scripts/generate.sh @@ -23,8 +23,21 @@ if ! command -v rustc >/dev/null 2>&1; then fi HOST_TARGET=$(rustc -vV | awk '/^host:/ {print $2}') +# Debug by default. This is a compile-and-test gate, not a benchmark, and a +# release build of moq-ffi shares no artifacts with the debug ones `just check` +# and `just test` already produce, so it was a third full compile of the +# dependency tree (~5 min of CI on its own, plus a whole target/release tree on +# a runner that was already tight on disk). Set MOQ_FFI_PROFILE=release for an +# optimized cdylib; the shipped artifacts are built by rs/moq-ffi/build.sh, +# which is release regardless. +PROFILE="${MOQ_FFI_PROFILE:-debug}" +# Expanded as ${CARGO_PROFILE[@]+...} at the use sites: macOS ships bash 3.2, +# where expanding an empty array under `set -u` is an "unbound variable" error. +CARGO_PROFILE=() +[[ "$PROFILE" == "release" ]] && CARGO_PROFILE=(--release) + echo "kt generate: building moq-ffi for $HOST_TARGET..." -cargo build --release --package moq-ffi \ +cargo build ${CARGO_PROFILE[@]+"${CARGO_PROFILE[@]}"} --package moq-ffi \ --manifest-path "$WORKSPACE_DIR/Cargo.toml" TARGET_BASE=$(cargo metadata --format-version 1 --manifest-path "$WORKSPACE_DIR/Cargo.toml" --no-deps | @@ -32,15 +45,15 @@ TARGET_BASE=$(cargo metadata --format-version 1 --manifest-path "$WORKSPACE_DIR/ case "$HOST_TARGET" in *-apple-*) - CDYLIB="$TARGET_BASE/release/libmoq_ffi.dylib" + CDYLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.dylib" OS_TAG="darwin" ;; *-windows-*) - CDYLIB="$TARGET_BASE/release/moq_ffi.dll" + CDYLIB="$TARGET_BASE/$PROFILE/moq_ffi.dll" OS_TAG="win32" ;; *) - CDYLIB="$TARGET_BASE/release/libmoq_ffi.so" + CDYLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.so" OS_TAG="linux" ;; esac @@ -64,7 +77,7 @@ cp "$CDYLIB" "$RES_DIR/" BINDGEN_OUT=$(mktemp -d) trap 'rm -rf "$BINDGEN_OUT"' EXIT -cargo run --release --package moq-ffi --bin uniffi-bindgen \ +cargo run ${CARGO_PROFILE[@]+"${CARGO_PROFILE[@]}"} --package moq-ffi --bin uniffi-bindgen \ --manifest-path "$WORKSPACE_DIR/Cargo.toml" -- \ generate --library "$CDYLIB" --language kotlin --no-format --out-dir "$BINDGEN_OUT" diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index f36a320e0d0..4891e974e4f 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -42,6 +42,7 @@ JsonSnapshotConsumer, JsonStreamConsumer, MediaConsumer, + MediaGroupConsumer, TrackConsumer, ) from .types import ( @@ -114,6 +115,7 @@ "JsonStreamConsumer", "JsonStreamProducer", "MediaConsumer", + "MediaGroupConsumer", "MediaProducer", "MediaStreamProducer", "OriginConsumer", diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index a8117b8b923..04290e98be2 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -517,8 +517,9 @@ def publish_video( """Publish a raw-video track with an in-process H.264/H.265 encoder. The track is named after the codec (``.avc3`` / ``.hev1``) and its - catalog rendition appears once the first keyframe has been encoded, so - subscribers discover it through the catalog rather than a name you pick. + catalog rendition is published immediately, read out of the encoder + itself, so subscribers discover it through the catalog rather than a + name you pick, and can find it before the first frame exists. """ return VideoProducer(self._inner.publish_video(input, output)) diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index 947a1377ed2..c9c6be2b6b2 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -16,6 +16,7 @@ MoqJsonStreamConfig, MoqJsonStreamConsumer, MoqMediaConsumer, + MoqMediaGroupConsumer, MoqTrackConsumer, ) @@ -66,6 +67,42 @@ def cancel(self) -> None: self._inner.cancel() +class MediaGroupConsumer: + """Async iterator of decoded :class:`MediaFrame` within a single fetched group. + + Built via :meth:`BroadcastConsumer.fetch_media_group`. Finite: iteration ends + after the group's last frame. Usable as an async context manager that cancels + on exit. + """ + + def __init__(self, inner: MoqMediaGroupConsumer) -> None: + self._inner = inner + + @property + def sequence(self) -> int: + """The sequence number of this group within the track.""" + return self._inner.sequence() + + async def __aenter__(self): + return self + + async def __aexit__(self, *exc) -> None: + self.cancel() + + def __aiter__(self): + return self + + async def __anext__(self) -> MediaFrame: + frame = await self._inner.next() + if frame is None: + raise StopAsyncIteration + return frame + + def cancel(self) -> None: + """Cancel reading this group and stop delivering frames.""" + self._inner.cancel() + + class GroupConsumer: """Async iterator of timestamped frames within a single group.""" @@ -373,6 +410,23 @@ async def fetch_group( """ return GroupConsumer(await self._inner.fetch_group(name, sequence, options)) + async def fetch_media_group( + self, + name: str, + sequence: int, + track: Video | Audio | Container, + options: FetchGroupOptions | None = None, + ) -> MediaGroupConsumer: + """Fetch one group by sequence and decode it into media frames. + + Unlike :meth:`subscribe_media` this holds no live subscription and applies + no latency-based group skipping, so every frame in the group is delivered. + ``track`` is either the catalog entry for this track (e.g. + ``catalog.video[name]``) or a :class:`Container` directly. + """ + container = track if isinstance(track, Container) else track.container + return MediaGroupConsumer(await self._inner.fetch_media_group(name, sequence, container, options)) + async def subscribe_media( self, name: str, diff --git a/py/moq-rs/pyproject.toml b/py/moq-rs/pyproject.toml index 29a34c8088b..de08e30c498 100644 --- a/py/moq-rs/pyproject.toml +++ b/py/moq-rs/pyproject.toml @@ -14,7 +14,7 @@ name = "moq-rs" # isn't already there (no tag needed; the registry is the gate). # Starts at 0.3.0 to open a new line above the old lockstep 0.2.x releases that # bundled the bindings. -version = "0.4.3" +version = "0.4.4" description = "Media over QUIC: real-time pub/sub with built-in caching, fan-out, and prioritization, with a Pythonic API. Import as `moq`." readme = "README.md" license = "MIT OR Apache-2.0" diff --git a/rs/CLAUDE.md b/rs/CLAUDE.md index 41e2489d991..83f75b52f8a 100644 --- a/rs/CLAUDE.md +++ b/rs/CLAUDE.md @@ -148,6 +148,8 @@ Then `Config::load()?` (initializes tracing), build clients/servers via `.init() - **`check` runs no `cargo check` pass.** Clippy is a superset of it, and the two use different rustc wrappers, so running both compiles the workspace twice for one set of errors. +- **Go through `just` rather than bare `cargo`.** Cargo fingerprints artifacts by emit kind and by compiler wrapper, so the same crate can sit in `target/` several times over. The expensive split is metadata versus codegen: `cargo check` and `clippy` emit metadata, while `cargo test` and `just test` codegen and link, and *dependencies* duplicate across that line. Within one emit kind it is cheaper than it sounds, since `just test` uses `RUSTC_WORKSPACE_WRAPPER`, which wraps only workspace crates, so dependencies stay shared with a plain `cargo test` and just our ~28 crates duplicate. It still adds up: each full tree is gigabytes, every agent worktree keeps its own, and ten worktrees were holding 59 GB on a 461 GB disk that had filled to 100%. If you run rust-analyzer, point it at clippy (`rust-analyzer.check.command = "clippy"`) so it shares with `just check` instead of opening another set. + - **Run tests through nextest, not `cargo test`.** `.config/nextest.toml` sets a `slow-timeout` with `terminate-after`, so a wedged test is reported as a TIMEOUT and killed; under `cargo test`'s harness the same test hangs forever, diff --git a/rs/justfile b/rs/justfile index fcd1a151696..3ed8ae75ff2 100644 --- a/rs/justfile +++ b/rs/justfile @@ -253,10 +253,32 @@ features: # # Takes cargo arguments, so `just rs test -p moq-net` works. `test-changed` is # the diff-scoped variant that `just test` dispatches to. +# +# clippy-driver as the compiler wrapper is rustc plus the lint passes, so this +# one compilation both builds the test binaries and reports clippy findings. +# `cargo clippy` can't be reused here: it asks cargo for metadata only, and a +# metadata build and a codegen build have different fingerprints, so running +# both compiles the dependency tree twice. Linting here is free, which makes +# `just test` a single-compile substitute for `check` + `test` on a laptop. +# +# RUSTC_WORKSPACE_WRAPPER, not RUSTC_WRAPPER, for two reasons. Cargo folds it +# into the fingerprint, so a crate already built by a plain `cargo test` is +# rebuilt through clippy rather than silently reported as fresh with no +# findings. And it applies to workspace crates only, so dependencies keep the +# artifacts they share with plain cargo instead of duplicating the whole tree. +# It is also what `cargo clippy` sets internally. +# +# Findings stay warnings rather than errors. `check` is the gate (it runs +# `clippy -D warnings`), and a hard failure here would block running the tests +# over an unused import while you are mid-edit. +# +# No RUSTFLAGS: it is part of cargo's fingerprint too, so setting it here would +# split the artifact cache against every other cargo invocation, including CI's +# warm cache. Skips the wrapper entirely when clippy-driver is absent. -# Run the test suite. +# Run the test suite, reporting clippy findings from the same compile. test *args: - cargo nextest run --all-targets {{ args }} + RUSTC_WORKSPACE_WRAPPER="$(command -v clippy-driver || true)" cargo nextest run --all-targets {{ args }} # Same selection as `check-changed`: compiling a crate's test binaries is the # expensive half of a test run, so scoping matters more here than anywhere else. diff --git a/rs/libmoq/CHANGELOG.md b/rs/libmoq/CHANGELOG.md index 3232c48b017..56a3d58c4cb 100644 --- a/rs/libmoq/CHANGELOG.md +++ b/rs/libmoq/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.7](https://github.com/moq-dev/moq/compare/libmoq-v0.5.6...libmoq-v0.5.7) - 2026-08-13 + +### Added + +- *(native)* start dialing before the AAAA answer lands ([#2749](https://github.com/moq-dev/moq/pull/2749)) +- *(moq-video)* advertise the catalog rendition before the first keyframe ([#2768](https://github.com/moq-dev/moq/pull/2768)) + ## [0.5.6](https://github.com/moq-dev/moq/compare/libmoq-v0.5.5...libmoq-v0.5.6) - 2026-08-07 ### Added diff --git a/rs/libmoq/Cargo.toml b/rs/libmoq/Cargo.toml index 5cf8cc22292..f20482ea97d 100644 --- a/rs/libmoq/Cargo.toml +++ b/rs/libmoq/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley ", "Brian Medley " repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.5.6" +version = "0.5.7" edition = "2024" rust-version.workspace = true @@ -38,3 +38,6 @@ url = "2" [build-dependencies] cbindgen = "0.29" + +[dev-dependencies] +moq-loc = { workspace = true } diff --git a/rs/libmoq/build.rs b/rs/libmoq/build.rs index b4d6f96dc08..20cd38288cd 100644 --- a/rs/libmoq/build.rs +++ b/rs/libmoq/build.rs @@ -6,6 +6,7 @@ const LIB_NAME: &str = "moq"; /// Enums the header must declare even though no signature mentions them. const ENUMS: &[&str] = &[ + "moq_container_kind", "moq_audio_format", "moq_video_pixel_format", "moq_video_codec", diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 2825459199d..0c89beca1b8 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -6,6 +6,101 @@ use std::str::FromStr; use tracing::Level; +/// How a media track's frames are wrapped, independent of the codec. +/// +/// The ABI carries this as a `uint32_t`, so an unknown discriminant from C is an +/// error rather than UB. +#[repr(C)] +#[allow(non_camel_case_types)] +#[derive(Clone, Copy, Debug)] +pub enum moq_container_kind { + /// A QUIC VarInt timestamp prefix followed by the raw codec payload. + /// Timestamps are in microseconds. + MOQ_CONTAINER_KIND_LEGACY = 0, + /// Fragmented MP4: each frame is a complete moof+mdat fragment, described by + /// the init segment in `moq_container::init`. + MOQ_CONTAINER_KIND_CMAF = 1, + /// Low Overhead Container (draft-ietf-moq-loc): a small property block + /// followed by the codec payload. + MOQ_CONTAINER_KIND_LOC = 2, + /// A container this build does not recognize, so the rendition must be + /// ignored. Only ever read out of a catalog: publishing it is an error. + MOQ_CONTAINER_KIND_UNKNOWN = 3, +} + +/// The container of a video or audio rendition, plus whatever that container +/// needs to describe itself. +/// +/// Zeroing this struct means `MOQ_CONTAINER_KIND_LEGACY` with no init segment, +/// which is what a rendition written by [moq_publish_media] carries. +#[repr(C)] +#[allow(non_camel_case_types)] +#[derive(Clone, Copy)] +pub struct moq_container { + /// `moq_container_kind` discriminant. + pub kind: u32, + + /// The CMAF init segment (ftyp+moov), or NULL. + /// Read only when `kind` is `MOQ_CONTAINER_KIND_CMAF`, where it is required. + pub init: *const u8, + pub init_len: usize, +} + +impl Default for moq_container { + fn default() -> Self { + Self { + kind: moq_container_kind::MOQ_CONTAINER_KIND_LEGACY as u32, + init: std::ptr::null(), + init_len: 0, + } + } +} + +/// # Safety +/// - `container->init` must point to `container->init_len` bytes when +/// `container->kind` is `MOQ_CONTAINER_KIND_CMAF`. +pub(crate) unsafe fn parse_container(container: &moq_container) -> Result { + use hang::catalog::Container; + + Ok(match container.kind { + v if v == moq_container_kind::MOQ_CONTAINER_KIND_LEGACY as u32 => Container::Legacy, + v if v == moq_container_kind::MOQ_CONTAINER_KIND_CMAF as u32 => { + let init = unsafe { ffi::parse_slice(container.init, container.init_len)? }; + // A CMAF rendition is undecodable without its init segment, so an empty one + // fails here rather than at every subscriber. + if init.is_empty() { + return Err(Error::InvalidPointer); + } + + Container::Cmaf { + init: bytes::Bytes::copy_from_slice(init), + } + } + v if v == moq_container_kind::MOQ_CONTAINER_KIND_LOC as u32 => Container::Loc, + // UNKNOWN included: we kept none of the original JSON, so there is nothing to republish. + _ => return Err(Error::InvalidCode), + }) +} + +/// Describe a catalog container for C, borrowing the CMAF init segment rather +/// than copying it, so the result lives only as long as the catalog snapshot. +pub(crate) fn borrow_container(container: &hang::catalog::Container) -> moq_container { + use hang::catalog::Container; + + let (kind, init) = match container { + Container::Legacy => (moq_container_kind::MOQ_CONTAINER_KIND_LEGACY, None), + Container::Cmaf { init } => (moq_container_kind::MOQ_CONTAINER_KIND_CMAF, Some(init)), + Container::Loc => (moq_container_kind::MOQ_CONTAINER_KIND_LOC, None), + Container::Unknown(_) => (moq_container_kind::MOQ_CONTAINER_KIND_UNKNOWN, None), + }; + + moq_container { + kind: kind as u32, + init: init.map_or(std::ptr::null(), |init| init.as_ptr()), + init_len: init.map_or(0, |init| init.len()), + } +} + /// Information about a video rendition in the catalog. #[repr(C)] #[allow(non_camel_case_types)] @@ -28,6 +123,9 @@ pub struct moq_video_config { /// The encoded width/height of the media, or NULL if not available pub coded_width: *const u32, pub coded_height: *const u32, + + /// How the track's frames are wrapped. + pub container: moq_container, } /// Catalog properties shared by every video rendition. @@ -80,6 +178,9 @@ pub struct moq_audio_config { /// The number of channels in the track pub channel_count: u32, + + /// How the track's frames are wrapped. + pub container: moq_container, } /// Options for a JSON snapshot track (lossy latest-value mode). @@ -633,6 +734,26 @@ pub extern "C" fn moq_client_set_failover_delay(client: u32, delay_ms: u64) -> i }) } +/// Delay before dialing an IPv4 address while the full DNS answer is outstanding, in +/// milliseconds. +/// +/// A dial runs the usual all-families lookup alongside an IPv4-only one that answers +/// without waiting for the AAAA record, and starts on the first answer. The full answer +/// is authoritative, including which family to try first, so this is how long the +/// IPv4-only one waits for it before going ahead alone. Defaults to 50ms; zero dials as +/// soon as any address resolves. +/// +/// Returns zero on success, or a negative code if the handle is unknown. +#[unsafe(no_mangle)] +pub extern "C" fn moq_client_set_resolution_delay(client: u32, delay_ms: u64) -> i32 { + ffi::enter(move || { + let client = ffi::parse_id(client)?; + State::lock().client.get_mut(client)?.connect.resolution_delay = + Some(std::time::Duration::from_millis(delay_ms)); + Ok(()) + }) +} + /// Delay before racing a WebSocket fallback against the QUIC dial, in milliseconds. /// /// Defaults to 200ms, and drops to zero for a server WebSocket already won against. @@ -1022,6 +1143,29 @@ pub unsafe extern "C" fn moq_client_get_failover_delay(client: u32, out: *mut u6 }) } +/// Read the Resolution Delay, in milliseconds. See [moq_client_set_resolution_delay] +/// and [moq_client_get_connect_timeout] for what an unset knob reports. +/// +/// Returns zero on success, or a negative code if the handle is unknown or `out` is NULL. +/// +/// # Safety +/// - The caller must ensure that `out` points to a writable `uint64_t`. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_client_get_resolution_delay(client: u32, out: *mut u64) -> i32 { + ffi::enter(move || { + let out = unsafe { out.as_mut() }.ok_or(Error::InvalidPointer)?; + let client = ffi::parse_id(client)?; + *out = millis( + State::lock() + .client + .get_mut(client)? + .connect + .resolved_resolution_delay(), + ); + Ok(()) + }) +} + /// Read the first reconnect delay, in milliseconds. See [moq_client_set_backoff_initial]. /// /// Returns zero on success, or a negative code if the handle is unknown or `out` is NULL. @@ -1732,6 +1876,10 @@ pub unsafe extern "C" fn moq_publish_video_properties(broadcast: u32, properties /// - `name` / `codec` are required (NOT NULL terminated) string slices. /// - `description` may be NULL to omit it. /// - `coded_width` / `coded_height` may be NULL to omit them. +/// - `container` describes how the frames written to the track are wrapped. A +/// zeroed one declares the legacy container, which is what [moq_publish_media] +/// writes; declare CMAF or LOC for a [moq_publish_track] whose frames you +/// already encode that way. /// /// Returns a zero on success, or a negative code on failure. /// @@ -1755,6 +1903,7 @@ pub unsafe extern "C" fn moq_publish_video_config(broadcast: u32, config: *const } video.coded_width = unsafe { config.coded_width.as_ref() }.copied(); video.coded_height = unsafe { config.coded_height.as_ref() }.copied(); + video.container = unsafe { parse_container(&config.container)? }; State::lock().publish.video_config(broadcast, name, video) }) @@ -1770,6 +1919,8 @@ pub unsafe extern "C" fn moq_publish_video_config(broadcast: u32, config: *const /// - `name` / `codec` are required (NOT NULL terminated) string slices. /// - `sample_rate` / `channel_count` are required. /// - `description` may be NULL to omit it. +/// - `container` describes how the frames written to the track are wrapped, the +/// same as for [moq_publish_video_config]. /// /// Returns a zero on success, or a negative code on failure. /// @@ -1787,6 +1938,7 @@ pub unsafe extern "C" fn moq_publish_audio_config(broadcast: u32, config: *const let codec = hang::catalog::AudioCodec::from_str(codec).map_err(Error::Hang)?; let mut audio = hang::catalog::AudioConfig::new(codec, config.sample_rate, config.channel_count); + audio.container = unsafe { parse_container(&config.container)? }; if !config.description.is_null() { let description = unsafe { ffi::parse_slice(config.description, config.description_len)? }; audio.description = Some(bytes::Bytes::copy_from_slice(description)); @@ -2242,7 +2394,9 @@ pub extern "C" fn moq_consume_catalog_free(catalog: u32) -> i32 { /// Query information about a video track in a catalog. /// -/// The destination is filled with the video track information. +/// The destination is filled with the video track information. `dst->container` +/// says how the track's frames are wrapped; skip a rendition whose kind is +/// `MOQ_CONTAINER_KIND_UNKNOWN`, since this build cannot parse it. /// /// Returns a zero on success, or a negative code on failure. /// @@ -2279,7 +2433,9 @@ pub unsafe extern "C" fn moq_consume_video_properties(catalog: u32, dst: *mut mo /// Query information about an audio track in a catalog. /// -/// The destination is filled with the audio track information. +/// The destination is filled with the audio track information. `dst->container` +/// says how the track's frames are wrapped; skip a rendition whose kind is +/// `MOQ_CONTAINER_KIND_UNKNOWN`, since this build cannot parse it. /// /// Returns a zero on success, or a negative code on failure. /// diff --git a/rs/libmoq/src/consume.rs b/rs/libmoq/src/consume.rs index b4b47a69c3f..d247ac88510 100644 --- a/rs/libmoq/src/consume.rs +++ b/rs/libmoq/src/consume.rs @@ -213,6 +213,7 @@ impl Consume { .as_ref() .map(|height| height as *const u32) .unwrap_or(std::ptr::null()), + container: crate::api::borrow_container(&config.container), }; Ok(()) @@ -261,6 +262,7 @@ impl Consume { description_len: config.description.as_ref().map(|desc| desc.len()).unwrap_or(0), sample_rate: config.sample_rate, channel_count: config.channel_count, + container: crate::api::borrow_container(&config.container), }; Ok(()) diff --git a/rs/libmoq/src/test.rs b/rs/libmoq/src/test.rs index 62c3bd41da8..f2ca14dec99 100644 --- a/rs/libmoq/src/test.rs +++ b/rs/libmoq/src/test.rs @@ -216,6 +216,7 @@ fn publish_catalog_config_invalid_broadcast() { description_len: 0, coded_width: std::ptr::null(), coded_height: std::ptr::null(), + container: moq_container::default(), }; assert!(unsafe { moq_publish_video_config(0, &video) } < 0); assert!(unsafe { moq_publish_video_properties(0, &moq_video_properties::default()) } < 0); @@ -230,6 +231,7 @@ fn publish_catalog_config_invalid_broadcast() { description_len: 0, sample_rate: 48000, channel_count: 2, + container: moq_container::default(), }; assert!(unsafe { moq_publish_audio_config(0, &audio) } < 0); @@ -280,6 +282,7 @@ fn publish_catalog_roundtrip() { description_len: description.len(), coded_width: &width, coded_height: &height, + container: moq_container::default(), }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let properties = moq_video_properties { @@ -304,6 +307,7 @@ fn publish_catalog_roundtrip() { description_len: 0, sample_rate: 48000, channel_count: 2, + container: moq_container::default(), }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -323,6 +327,7 @@ fn publish_catalog_roundtrip() { description_len: 0, coded_width: std::ptr::null(), coded_height: std::ptr::null(), + container: moq_container::default(), }; assert_eq!(unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) }, 0); let codec = unsafe { @@ -356,6 +361,7 @@ fn publish_catalog_roundtrip() { description_len: 0, sample_rate: 0, channel_count: 0, + container: moq_container::default(), }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -382,6 +388,216 @@ fn publish_catalog_roundtrip() { assert_eq!(moq_origin_close(origin), 0); } +#[test] +fn raw_loc_video_uses_the_declared_catalog_container() { + let origin = id(moq_origin_create()); + let path = b"raw-loc-video"; + let broadcast = publish_broadcast(origin, path); + + let name = b"video"; + let track = + id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), std::ptr::null()) }); + + let codec = b"vp8"; + let video = moq_video_config { + name: name.as_ptr() as *const c_char, + name_len: name.len(), + codec: codec.as_ptr() as *const c_char, + codec_len: codec.len(), + description: std::ptr::null(), + description_len: 0, + coded_width: std::ptr::null(), + coded_height: std::ptr::null(), + container: moq_container { + kind: moq_container_kind::MOQ_CONTAINER_KIND_LOC as u32, + init: std::ptr::null(), + init_len: 0, + }, + }; + assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); + + let consume = request_broadcast(origin, path); + let catalog_cb = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog = id(catalog_cb.recv()); + + // The declaration survives the round trip, so a consumer knows to parse LOC. + let mut video_cfg = moq_video_config { + name: std::ptr::null(), + name_len: 0, + codec: std::ptr::null(), + codec_len: 0, + description: std::ptr::null(), + description_len: 0, + coded_width: std::ptr::null(), + coded_height: std::ptr::null(), + container: moq_container::default(), + }; + assert_eq!(unsafe { moq_consume_video_config(catalog, 0, &mut video_cfg) }, 0); + assert_eq!( + video_cfg.container.kind, + moq_container_kind::MOQ_CONTAINER_KIND_LOC as u32 + ); + assert!(video_cfg.container.init.is_null()); + + let frame_cb = Callback::new(); + let consumer = id(unsafe { moq_consume_video(catalog, 0, 10_000, Some(channel_callback), frame_cb.ptr) }); + + let timestamp_us = 42_000; + let payload = b"codec frame"; + let loc = moq_loc::encode(timestamp_us, payload).unwrap(); + let group = id(moq_publish_track_group(track)); + assert_eq!( + unsafe { moq_publish_group_frame(group, loc.as_ptr(), loc.len(), timestamp_us) }, + 0 + ); + assert_eq!(moq_publish_group_finish(group), 0); + + let frame_id = id(frame_cb.recv()); + let mut frame = moq_frame { + payload: std::ptr::null(), + payload_size: 0, + timestamp_us: 0, + keyframe: false, + }; + assert_eq!(unsafe { moq_consume_frame(frame_id, &mut frame) }, 0); + assert_eq!(frame.timestamp_us, timestamp_us); + assert!(frame.keyframe); + assert_eq!( + unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, + payload + ); + + assert_eq!(moq_consume_frame_free(frame_id), 0); + assert_eq!(moq_consume_video_close(consumer), 0); + assert_eq!(frame_cb.recv_terminal(), 0); + assert_eq!(moq_consume_catalog_free(catalog), 0); + assert_eq!(moq_consume_catalog_close(catalog_task), 0); + assert_eq!(catalog_cb.recv_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(moq_publish_finish(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn cmaf_catalog_container_carries_its_init_segment() { + let origin = id(moq_origin_create()); + let path = b"cmaf-container"; + let broadcast = publish_broadcast(origin, path); + + let name = "audio"; + let codec = "opus"; + let init: &[u8] = &[0x00, 0x01, 0x02, 0x03]; + let audio = moq_audio_config { + name: name.as_ptr() as *const c_char, + name_len: name.len(), + codec: codec.as_ptr() as *const c_char, + codec_len: codec.len(), + description: std::ptr::null(), + description_len: 0, + sample_rate: 48000, + channel_count: 2, + container: moq_container { + kind: moq_container_kind::MOQ_CONTAINER_KIND_CMAF as u32, + init: init.as_ptr(), + init_len: init.len(), + }, + }; + assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); + + let consume = request_broadcast(origin, path); + let catalog_cb = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog = id(catalog_cb.recv()); + + let mut audio_cfg = moq_audio_config { + name: std::ptr::null(), + name_len: 0, + codec: std::ptr::null(), + codec_len: 0, + description: std::ptr::null(), + description_len: 0, + sample_rate: 0, + channel_count: 0, + container: moq_container::default(), + }; + assert_eq!(unsafe { moq_consume_audio_config(catalog, 0, &mut audio_cfg) }, 0); + assert_eq!( + audio_cfg.container.kind, + moq_container_kind::MOQ_CONTAINER_KIND_CMAF as u32 + ); + assert_eq!( + unsafe { std::slice::from_raw_parts(audio_cfg.container.init, audio_cfg.container.init_len) }, + init + ); + + assert_eq!(moq_consume_catalog_free(catalog), 0); + assert_eq!(moq_consume_catalog_close(catalog_task), 0); + assert_eq!(catalog_cb.recv_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_finish(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn unpublishable_catalog_containers_are_rejected() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"container-reject"); + + let name = "video"; + let codec = "vp8"; + let config = |container| moq_video_config { + name: name.as_ptr() as *const c_char, + name_len: name.len(), + codec: codec.as_ptr() as *const c_char, + codec_len: codec.len(), + description: std::ptr::null(), + description_len: 0, + coded_width: std::ptr::null(), + coded_height: std::ptr::null(), + container, + }; + + // UNKNOWN only ever comes out of a catalog: we keep none of the original JSON, so + // there is nothing to write back. + let unknown = config(moq_container { + kind: moq_container_kind::MOQ_CONTAINER_KIND_UNKNOWN as u32, + init: std::ptr::null(), + init_len: 0, + }); + assert_eq!( + unsafe { moq_publish_video_config(broadcast, &unknown) }, + -15, + "unknown container should return InvalidCode (-15)" + ); + + let garbage = config(moq_container { + kind: 12345, + init: std::ptr::null(), + init_len: 0, + }); + assert_eq!( + unsafe { moq_publish_video_config(broadcast, &garbage) }, + -15, + "out of range container should return InvalidCode (-15)" + ); + + let cmaf = config(moq_container { + kind: moq_container_kind::MOQ_CONTAINER_KIND_CMAF as u32, + init: std::ptr::null(), + init_len: 0, + }); + assert_eq!( + unsafe { moq_publish_video_config(broadcast, &cmaf) }, + -6, + "cmaf without an init segment should return InvalidPointer (-6)" + ); + + assert_eq!(moq_publish_finish(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn catalog_section_roundtrip() { let origin = id(moq_origin_create()); @@ -1303,6 +1519,7 @@ fn local_publish_consume() { description_len: 0, sample_rate: 0, channel_count: 0, + container: moq_container::default(), }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -1326,6 +1543,7 @@ fn local_publish_consume() { description_len: 0, coded_width: std::ptr::null(), coded_height: std::ptr::null(), + container: moq_container::default(), }; assert!( unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) } < 0, @@ -1417,6 +1635,7 @@ fn consume_announced_local() { description_len: 0, sample_rate: 0, channel_count: 0, + container: moq_container::default(), }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -1488,6 +1707,7 @@ fn video_publish_consume() { description_len: 0, coded_width: std::ptr::null(), coded_height: std::ptr::null(), + container: moq_container::default(), }; assert_eq!( unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) }, @@ -1523,6 +1743,7 @@ fn video_publish_consume() { description_len: 0, sample_rate: 0, channel_count: 0, + container: moq_container::default(), }; assert!( unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) } < 0, @@ -2191,6 +2412,7 @@ fn catalog_update_on_new_track() { description_len: 0, sample_rate: 0, channel_count: 0, + container: moq_container::default(), }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id1, 0, &mut audio_cfg) }, 0); assert!(unsafe { moq_consume_audio_config(catalog_id1, 1, &mut audio_cfg) } < 0); @@ -2498,6 +2720,9 @@ fn a_fresh_handle_reads_back_the_defaults() { assert_eq!(unsafe { moq_client_get_failover_delay(client, &mut value) }, 0); assert_eq!(value, config.resolved_race().as_millis() as u64); + assert_eq!(unsafe { moq_client_get_resolution_delay(client, &mut value) }, 0); + assert_eq!(value, config.resolved_resolution_delay().as_millis() as u64); + assert_eq!(unsafe { moq_client_get_backoff_initial(client, &mut value) }, 0); assert_eq!(value, config.backoff.initial().as_millis() as u64); diff --git a/rs/libmoq/src/video.rs b/rs/libmoq/src/video.rs index 012a37eb5b3..07bc3959d1a 100644 --- a/rs/libmoq/src/video.rs +++ b/rs/libmoq/src/video.rs @@ -284,18 +284,19 @@ impl VideoEncoder { impl Video { /// Advertise a track for an already-opened encoder. /// - /// The encoder is opened by the caller, and before this, so a config this - /// machine can't encode fails without leaving a track advertised that will - /// never carry frames. + /// The encoder and the rendition it will emit are both resolved by the caller, + /// and before this, so a config this machine can't encode fails without leaving + /// a track advertised that will never carry frames. pub fn publish( &mut self, broadcast: &moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer, format: moq_video_pixel_format, config: &moq_video::encode::Config, + rendition: hang::catalog::VideoConfig, encoder: moq_video::encode::Sink, ) -> Result { - let producer = moq_video::encode::Producer::new(broadcast.clone(), catalog, config.codec)?; + let producer = moq_video::encode::Producer::new(broadcast.clone(), catalog, rendition)?; self.producers.insert(Shared::new(VideoEncoder { encoder, producer, @@ -463,8 +464,9 @@ unsafe fn encoder_kind(output: &moq_video_encoder_output) -> Result Result<()> { // Set up catalog and encoders. let catalog = moq_mux::catalog::Producer::new(&mut broadcast)?; - let video_encoder = video::VideoEncoder::spawn(broadcast.clone(), catalog.clone()); + let video_encoder = video::VideoEncoder::spawn(broadcast.clone(), catalog.clone()).await; let audio_encoder = audio::AudioEncoder::new(broadcast.clone(), catalog.clone(), 44100)?; @@ -307,18 +307,6 @@ fn run_emulator( let mut emu = emulator::Emulator::new(rom_path)?; let start = Instant::now(); - // Run a single tick so the encoders get initial data and publish - // codec config, even before any viewer subscribes. - emu.tick(); - let elapsed = start.elapsed(); - let rgba = Bytes::from(emu.framebuffer()); - let ts = hang::container::Timestamp::from_micros(elapsed.as_micros() as u64).context("timestamp overflow")?; - session.video_encoder.try_frame(rgba, ts); - let samples = emu.audio_samples(); - if !samples.is_empty() { - audio_encoder.push_samples(&samples, elapsed)?; - } - // Game Boy runs at exactly 59.727 Hz (4194304 Hz CPU / 70224 cycles per frame). // 1/59.727 ≈ 16742 microseconds per frame. let frame_duration = Duration::from_micros(16_742); diff --git a/rs/moq-boy/src/video.rs b/rs/moq-boy/src/video.rs index 4924748fac0..d28f539790f 100644 --- a/rs/moq-boy/src/video.rs +++ b/rs/moq-boy/src/video.rs @@ -14,6 +14,10 @@ use bytes::Bytes; use crate::emulator::{HEIGHT, WIDTH}; +/// The Game Boy's 59.727 Hz, rounded: the encoder's time base and the framerate the catalog +/// advertises. +const FRAMERATE: u32 = 60; + /// Handle to the video encoding thread. /// /// Frames are submitted via `try_frame()` (non-blocking, drops if full). @@ -38,10 +42,21 @@ enum EncoderMsg { } impl VideoEncoder { - pub fn spawn(broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer) -> Self { + /// Publish the catalog rendition, then hand the encoder to a worker thread that only runs while + /// someone is watching. The returned handle feeds it frames; the emulator never blocks on it. + pub async fn spawn(broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer) -> Self { let (tx, rx) = tokio::sync::mpsc::channel(4); - let producer = moq_video::encode::Producer::new(broadcast, catalog, moq_video::encode::Codec::H264) - .expect("failed to create avc3 producer"); + + // Game Boy is 160x144; force the openh264 software encoder since hardware + // encoders can reject such tiny resolutions. + let mut config = moq_video::encode::Config::new(WIDTH, HEIGHT, FRAMERATE); + config.kind = moq_video::encode::Kind::Software; + + // Probed from a throwaway encoder, before the emulator has run a frame, so a + // viewer can discover (and unpause) a moq-boy that has published nothing. + let rendition = config.probe().await.expect("failed to probe the H.264 encoder"); + let producer = + moq_video::encode::Producer::new(broadcast, catalog, rendition).expect("failed to create avc3 producer"); let demand = producer.demand(); let force_keyframe = Arc::new(AtomicBool::new(false)); @@ -50,7 +65,7 @@ impl VideoEncoder { let ed = encode_duration.clone(); let thread = std::thread::Builder::new() .name("video-encoder".into()) - .spawn(move || encoder_thread(rx, producer, fk, ed)) + .spawn(move || encoder_thread(rx, producer, config, fk, ed)) .expect("failed to spawn video encoder thread"); Self { @@ -97,6 +112,7 @@ impl VideoEncoder { fn encoder_thread( mut rx: tokio::sync::mpsc::Receiver, mut producer: moq_video::encode::Producer, + config: moq_video::encode::Config, force_keyframe: Arc, encode_duration: Arc, ) { @@ -116,10 +132,7 @@ fn encoder_thread( let enc = match encoder.as_mut() { Some(enc) => enc, None => { - // Game Boy is 160x144; force the openh264 software encoder since - // hardware encoders can reject such tiny resolutions. - let mut config = moq_video::encode::Config::new(WIDTH, HEIGHT, 60); - config.kind = moq_video::encode::Kind::Software; + // Opened on the first frame, so a paused emulator holds no encoder. match moq_video::encode::Encoder::new(&config) { Ok(enc) => encoder.insert(enc), Err(e) => { diff --git a/rs/moq-cli/CHANGELOG.md b/rs/moq-cli/CHANGELOG.md index 902564ae530..0cd09d3cb97 100644 --- a/rs/moq-cli/CHANGELOG.md +++ b/rs/moq-cli/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.9.10](https://github.com/moq-dev/moq/compare/moq-cli-v0.9.9...moq-cli-v0.9.10) - 2026-08-13 + +### Fixed + +- *(release)* repair native package releases ([#2731](https://github.com/moq-dev/moq/pull/2731)) + ## [0.9.9](https://github.com/moq-dev/moq/compare/moq-cli-v0.9.8...moq-cli-v0.9.9) - 2026-08-07 ### Added diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 1c8c146ad87..13fa9908bdc 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.9.9" +version = "0.9.10" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-cli/README.md b/rs/moq-cli/README.md index 2b1181192a7..582f41aa69f 100644 --- a/rs/moq-cli/README.md +++ b/rs/moq-cli/README.md @@ -19,7 +19,15 @@ Multi-arch images (`linux/amd64` and `linux/arm64`) are published to [Docker Hub ## Usage -`moq-cli` routes one endpoint onto a shared MoQ Origin: `moq `. The MoQ side (before the verb) is either `--connect ` (dial a relay) or `--listen ` (self-host). `import` moves media into MoQ, `export` moves it out. The endpoint is a container format (`fmp4`, `ts`, `flv`, ... read from stdin / written to stdout), or a gateway (`hls`, `rtmp`, `srt`, `rtc`). A build with the `play` feature can also render a broadcast locally with `moq play`. +`moq-cli` routes endpoints onto a shared MoQ Origin: `moq `. The MoQ side (before the verb) is either `--connect ` (dial a relay) or `--listen ` (self-host). `import` moves media into MoQ, `export` moves it out. The endpoint is a container format (`fmp4`, `ts`, `flv`, ... read from stdin / written to stdout), or a gateway (`hls`, `rtmp`, `srt`, `rtc`). A build with the `play` feature can also render a broadcast locally with `moq play`. + +Separate additional stages with `--` to bridge several broadcasts (or both directions) over one connection, each naming its own `--broadcast`: + +```bash +moq --connect https://relay.example.com/anon \ + import --broadcast cam1.hang rtmp --listen 0.0.0.0:1935 \ + -- import --broadcast cam2.hang rtmp --listen 0.0.0.0:1936 +``` ### Publish to a remote relay diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 69132453b02..e66e493795e 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -1,11 +1,12 @@ //! The unified moq-cli argument surface. //! -//! Grammar: `moq [endpoint opts]`, plus -//! `moq play` for native playback. +//! Grammar: `moq [-- ]...`, where a stage is +//! ` [endpoint opts]`, plus `moq play` for +//! native playback. //! //! - The MoQ side (`--connect`, `--listen`, `--cluster-lan`; all //! optional, at least one) attaches the shared Origin to the MoQ network, and -//! comes before the verb. They compose: dial a relay, accept incoming +//! comes before the first stage. They compose: dial a relay, accept incoming //! sessions, and mesh with the LAN all at once. //! - `import` routes media INTO MoQ from one source; `export` routes it OUT to //! one sink. The verb fixes the data direction (and thus, for the @@ -16,20 +17,35 @@ //! conditional on the subcommand. //! - The endpoint is one subcommand: a container format (`ts`, `fmp4`, ... read //! from stdin on import, written to stdout on export) or a gateway (`hls`, -//! `rtmp`, `srt`, `rtc`). Exactly one per invocation, so "which endpoint" is +//! `rtmp`, `srt`, `rtc`). Exactly one per stage, so "which endpoint" is //! unambiguous and there's no silently-ignored flag. +//! - `--` starts another stage on the same Origin and the same MoQ attachment, so +//! one process can bridge several broadcasts (or both directions at once). clap +//! can't express a repeated subcommand, so [`Invocation`] splits argv on `--` +//! and runs each chunk through a real parser: every stage keeps full validation +//! and its own `--help`. That claims `--` from clap, which would otherwise treat +//! it as the end-of-options marker. The only positional it could have escaped is +//! an `import hls` playlist path starting with `-`, which `./-name` covers, so +//! the separator stays unconditional rather than context-sensitive. +use std::ffi::{OsStr, OsString}; use std::time::Duration; -use clap::{ArgGroup, Args, Parser, Subcommand}; +use clap::{ArgGroup, Args, CommandFactory, Parser, Subcommand}; use hang::moq_net; use crate::publish::PublishFormat; use crate::subscribe::{CatalogFormatArg, SubscribeFormat}; -/// moq-cli: a media router that wires one endpoint onto a shared MoQ Origin. +// The globals plus the first stage; later stages are parsed as a [`Stage`]. Keep +// the doc comment to one line: clap renders the rest as `--help` body text, where +// rustdoc links read as noise. +/// moq-cli: a media router that wires endpoints onto a shared MoQ Origin. #[derive(Parser, Clone)] #[command(name = "moq", version = env!("VERSION"))] +#[command(after_help = "Separate additional import/export stages with `--`; they share one \ + connection and one Origin. Every `--` starts a stage, so it is not an \ + end-of-options marker: write a path starting with `-` as `./-name`.")] pub struct Cli { /// Logging configuration. #[command(flatten)] @@ -44,6 +60,120 @@ pub struct Cli { pub command: Command, } +// `no_binary_name` because the chunk after a `--` starts at the verb, and the +// globals are deliberately absent: `--connect` past the first stage would +// read like it scopes that stage, when there is only ever one connection. As with +// [`Cli`], the doc comment stays one line because clap shows it in `--help`. +/// A stage after the first: the verb and endpoint, without the globals. +#[derive(Parser, Clone)] +#[command(name = "moq", no_binary_name = true)] +pub struct Stage { + /// The verb and endpoint. + #[command(subcommand)] + pub command: Command, +} + +/// The whole command line: the globals plus one or more `--`-separated stages. +pub struct Invocation { + /// Logging configuration. + pub log: moq_native::Log, + + /// The MoQ attachment, shared by every stage. + pub moq: MoqSide, + + /// The stages, in the order given. Never empty. + pub stages: Vec, +} + +impl Invocation { + /// Parse the process arguments, exiting with clap's own message on error. + pub fn parse() -> Self { + match Self::try_parse_from(std::env::args_os()) { + Ok(parsed) => parsed, + Err(err) => err.exit(), + } + } + + /// Split `argv` on `--` and run each chunk through a real parser. + pub fn try_parse_from(argv: I) -> Result + where + I: IntoIterator, + T: Into, + { + let argv: Vec = argv.into_iter().map(Into::into).collect(); + let mut chunks = argv.split(|arg| arg == OsStr::new("--")); + + // `split` always yields at least one chunk, even for an empty argv; clap then + // reports the missing subcommand as usual. + let cli = Cli::try_parse_from(chunks.next().unwrap_or_default())?; + + let mut stages = vec![cli.command]; + for chunk in chunks { + // A trailing or doubled `--` leaves an empty chunk, which clap would report as a + // bare missing-subcommand usage dump. Name what's actually wrong instead. + if chunk.is_empty() { + return Err(Stage::command().error( + clap::error::ErrorKind::MissingSubcommand, + "`--` starts another stage, so it must be followed by `import` or `export`", + )); + } + + stages.push(Stage::try_parse_from(chunk)?.command); + } + + Ok(Self { + log: cli.log, + moq: cli.moq, + stages, + }) + } + + /// Reject the stage combinations a single process can't run. + /// + /// Called before anything binds a port or dials out, so a refused invocation has + /// no side effects to unwind. + pub fn validate(&self) -> anyhow::Result<()> { + // One stage is what the CLI has always run, so nothing below can bite. + if self.stages.len() == 1 { + return Ok(()); + } + + // Only `import` and `export` share an Origin. The rest own the process: `play` + // drives a window on the main thread, `transcode` builds its own Origin, and + // `token` / `devices` never touch the network at all. + if let Some(command) = self.stages.iter().find(|command| !command.is_stageable()) { + anyhow::bail!( + "`{}` must be the only verb; it can't share a process with another `--` stage", + command.name() + ); + } + + // Rate control assumes it owns the uplink: the encoder targets a fraction of the + // connection's estimate, leaving room for its own audio and transport overhead but + // not for a second publisher. Anything else importing over the same connection + // spends what that encoder already claimed, so refuse rather than congest the link + // the estimate exists to protect. Exports only receive, so they don't count, and + // only an outbound client has an estimate at all. + let imports = self + .stages + .iter() + .filter(|stage| matches!(stage, Command::Import(_))) + .count(); + let adaptive = self + .stages + .iter() + .any(|stage| matches!(stage, Command::Import(import) if import.source.uses_bandwidth())); + anyhow::ensure!( + self.moq.client.url.is_none() || !adaptive || imports == 1, + "a stage that encodes to fit the connection's bandwidth estimate assumes it's the only \ + publisher on that connection, but this runs {imports} import stages; run them as separate \ + processes, or publish over --listen, which has no estimate" + ); + + Ok(()) + } +} + /// The MoQ attachment: a relay dial, a server listener, a LAN mesh, or any /// combination. /// @@ -60,10 +190,12 @@ pub struct Cli { command(group = ArgGroup::new("moq").multiple(true).args(["connect", "listen"])) )] pub struct MoqSide { - /// The broadcast name. Optional for the point endpoints (stdin/stdout, HLS - /// import, and the `--connect` dials), which default to the root broadcast at - /// the connection path; required by the `--listen` endpoints and `hls export`, - /// which bridge one named broadcast. + /// The default broadcast name for every stage that doesn't name its own. + /// + /// Optional for the point endpoints (stdin/stdout, HLS import, and the + /// `--connect` dials), which default to the root broadcast at the connection + /// path; required by the `--listen` endpoints and `hls export`, which bridge one + /// named broadcast. #[arg(long, alias = "name", help_heading = "MoQ")] pub broadcast: Option, @@ -218,11 +350,55 @@ pub enum Command { Devices, } +impl Command { + /// The verb as typed, for error messages. + pub fn name(&self) -> &'static str { + match self { + Self::Import(_) => "import", + Self::Export(_) => "export", + #[cfg(feature = "play")] + Self::Play(_) => "play", + #[cfg(feature = "transcode")] + Self::Transcode(_) => "transcode", + Self::Token(_) => "token", + #[cfg(feature = "capture")] + Self::Devices => "devices", + } + } + + /// Whether this verb can share a process (and an Origin) with other stages. + pub fn is_stageable(&self) -> bool { + matches!(self, Self::Import(_) | Self::Export(_)) + } + + /// The broadcast this stage names, falling back to the process-wide `--broadcast`. + /// + /// Empty means the root broadcast: MoQ names each broadcast by the connection + /// path plus any explicit `--broadcast`, so an unset name is the connection path + /// itself. + pub fn broadcast(&self, moq: &MoqSide) -> String { + let stage = match self { + Self::Import(import) => import.broadcast.as_deref(), + Self::Export(export) => export.broadcast.as_deref(), + _ => None, + }; + + stage.or(moq.broadcast.as_deref()).unwrap_or_default().to_string() + } +} + // ------------------------------------------------------------------ import /// import = one source -> MoQ. #[derive(Args, Clone)] pub struct Import { + /// The broadcast this stage publishes, overriding the process-wide `--broadcast`. + /// + /// Required when a process imports more than one broadcast; a single stage can + /// keep naming it before the verb. + #[arg(long, alias = "name")] + pub broadcast: Option, + /// How long relays keep a non-latest group of the published media tracks fetchable, /// e.g. "30s" or "5s". Defaults to hang's 30s. /// @@ -277,6 +453,18 @@ impl ImportSource { _ => return None, }) } + /// Whether this source encodes to fit the connection's bandwidth estimate. + /// + /// Rate control is per-encoder while the estimate is per-connection, so each such + /// source assumes it's the only one on the uplink. Only the video encoder reads + /// the estimate, so an audio-only capture doesn't count. + pub fn uses_bandwidth(&self) -> bool { + match self { + #[cfg(feature = "capture")] + Self::Capture(capture) => !capture.no_video, + _ => false, + } + } } // ------------------------------------------------------------------ export @@ -284,6 +472,13 @@ impl ImportSource { /// export = MoQ -> one sink. #[derive(Args, Clone)] pub struct Export { + /// The broadcast this stage subscribes to, overriding the process-wide `--broadcast`. + /// + /// Required when a process exports more than one broadcast; a single stage can + /// keep naming it before the verb. + #[arg(long, alias = "name")] + pub broadcast: Option, + /// Catalog format to read for track discovery (default: detect from the broadcast suffix). #[arg(long = "catalog-format")] pub catalog_format: Option, @@ -369,7 +564,6 @@ pub struct Fragmented { #[cfg(test)] mod tests { use super::*; - use clap::CommandFactory; // Catches the conflicts clap only panics on at runtime: a duplicate long, a // dangling `conflicts_with`, a flattened arg colliding with an existing one. @@ -380,6 +574,306 @@ mod tests { Cli::command().debug_assert(); } + /// The `Stage` parser is a second entry point into the same command tree, so it + /// needs the same conflict check as [`Cli`]. + #[test] + fn valid_stage() { + Stage::command().debug_assert(); + } + + #[test] + fn single_stage() { + let cli = Invocation::try_parse_from(["moq", "--connect", "http://relay", "import", "ts"]).unwrap(); + assert_eq!(cli.stages.len(), 1); + assert_eq!(cli.stages[0].name(), "import"); + assert!(cli.validate().is_ok()); + } + + /// The grammar clap can't express: one connection, several endpoints. + #[test] + fn multiple_stages() { + let cli = Invocation::try_parse_from([ + "moq", + "--connect", + "http://localhost:4444/event", + "import", + "--broadcast", + "cam1.hang", + "rtmp", + "--listen", + "0.0.0.0:1935", + "--", + "import", + "--broadcast", + "cam2.hang", + "rtmp", + "--listen", + "0.0.0.0:1936", + "--", + "export", + "--broadcast", + "cam1.hang", + "hls", + "--listen", + "0.0.0.0:8080", + ]) + .unwrap(); + + assert!(cli.validate().is_ok()); + assert_eq!(cli.stages.len(), 3); + + // The globals are read once, from the first chunk, and shared by every stage. + assert_eq!( + cli.moq.client.url.as_ref().map(ToString::to_string).as_deref(), + Some("http://localhost:4444/event") + ); + + let names: Vec = cli.stages.iter().map(|stage| stage.broadcast(&cli.moq)).collect(); + assert_eq!(names, ["cam1.hang", "cam2.hang", "cam1.hang"]); + assert_eq!(cli.stages[2].name(), "export"); + } + + /// A stage without its own `--broadcast` falls back to the process-wide one, so + /// every single-stage invocation keeps naming the broadcast before the verb. + #[test] + fn broadcast_falls_back_to_the_global() { + let cli = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "--broadcast", + "room.hang", + "import", + "ts", + "--", + "export", + "--broadcast", + "other.hang", + "fmp4", + ]) + .unwrap(); + + assert_eq!(cli.stages[0].broadcast(&cli.moq), "room.hang"); + assert_eq!(cli.stages[1].broadcast(&cli.moq), "other.hang"); + } + + /// An unnamed broadcast is the root one at the connection path, not an error. + #[test] + fn broadcast_defaults_to_root() { + let cli = Invocation::try_parse_from(["moq", "--connect", "http://relay", "import", "ts"]).unwrap(); + assert_eq!(cli.stages[0].broadcast(&cli.moq), ""); + } + + /// Only import/export share an Origin; the rest own the process. + #[test] + fn rejects_unstageable_verbs() { + let cli = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "import", + "ts", + "--", + "token", + "generate", + "--algorithm", + "ES256", + ]) + .unwrap(); + + let err = cli.validate().unwrap_err().to_string(); + assert!(err.contains("token"), "{err}"); + } + + /// Each stage is parsed by a real clap parser, so a typo past the first `--` is + /// still a parse error rather than something swallowed as a positional. + #[test] + fn stage_errors_are_parse_errors() { + let Err(err) = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "import", + "ts", + "--", + "import", + "rtmp", + "--bogus", + ]) else { + panic!("expected a parse error") + }; + + assert_eq!(err.kind(), clap::error::ErrorKind::UnknownArgument); + } + + /// Splitting on `--` claims it from clap, so it can't also escape a positional + /// starting with `-`. `./-name` is the documented way to write one. + #[test] + fn a_dash_prefixed_path_is_written_relative() { + let cli = + Invocation::try_parse_from(["moq", "--connect", "http://relay", "import", "hls", "./-odd.m3u8"]).unwrap(); + + let Command::Import(import) = &cli.stages[0] else { + panic!("expected import") + }; + let ImportSource::Hls(hls) = &import.source else { + panic!("expected hls") + }; + assert_eq!(hls.playlist, "./-odd.m3u8"); + } + + /// A `--` with nothing after it names no verb, so it's an error rather than an + /// empty stage. Same for a doubled `--`, which leaves an empty chunk between them. + #[test] + fn rejects_an_empty_stage() { + for argv in [ + vec!["moq", "--connect", "http://relay", "import", "ts", "--"], + vec![ + "moq", + "--connect", + "http://relay", + "import", + "ts", + "--", + "--", + "export", + "fmp4", + ], + ] { + let Err(err) = Invocation::try_parse_from(argv.clone()) else { + panic!("expected a parse error for {argv:?}") + }; + + assert_eq!(err.kind(), clap::error::ErrorKind::MissingSubcommand); + assert!(err.to_string().contains("must be followed by"), "{err}"); + } + } + + /// The globals belong to the invocation, not a stage: there is only ever one + /// connection, so accepting `--client-connect` again would be a lie. + #[test] + fn stages_reject_globals() { + let Err(err) = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "import", + "ts", + "--", + "--connect", + "http://other", + "import", + "fmp4", + ]) else { + panic!("expected a parse error") + }; + + assert_eq!(err.kind(), clap::error::ErrorKind::UnknownArgument); + } + + /// Stages that never read the estimate can share a connection freely, so the guard + /// must not reject them. + #[test] + fn imports_without_rate_control_can_share_a_connection() { + let cli = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "import", + "--broadcast", + "a.hang", + "rtmp", + "--listen", + "127.0.0.1:1935", + "--", + "import", + "--broadcast", + "b.hang", + "srt", + "--listen", + "127.0.0.1:9000", + ]) + .unwrap(); + + assert!(cli.validate().is_ok()); + } + + /// An encoder that follows the estimate targets most of it, so a second publisher + /// on the same connection spends what it already claimed. Exports only receive, and + /// a `--listen` publisher has no estimate to oversubscribe. + #[cfg(feature = "capture")] + #[test] + fn an_adaptive_capture_must_be_the_only_import() { + // The canonical spellings: `validate` reads the folded fields, which the + // released `--client-*` aliases only reach through `resolved()`. + let client: &[&str] = &["--connect", "http://relay"]; + let server: &[&str] = &["--listen", "[::]:4443"]; + + let cases: [(&[&str], &[&str], bool); 3] = [ + // Two video captures follow the same estimate. + (client, &["import", "capture"], false), + // A fixed-rate import spends the same uplink from outside the budget. + (client, &["import", "rtmp", "--listen", "127.0.0.1:1935"], false), + // No outbound client, so there's no estimate to oversubscribe. + (server, &["import", "capture"], true), + ]; + + for (side, second, ok) in cases { + let argv = [&["moq"][..], side, &["import", "capture", "--"], second].concat(); + let cli = Invocation::try_parse_from(argv.clone()).unwrap(); + assert_eq!(cli.validate().is_ok(), ok, "{argv:?}"); + } + + // An audio-only capture never reads the estimate, so it may share the connection. + let cli = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "import", + "capture", + "--no-video", + "--", + "import", + "rtmp", + "--listen", + "127.0.0.1:1935", + ]) + .unwrap(); + assert!(cli.validate().is_ok()); + + // Exports only receive, so they don't compete for the uplink. + let cli = Invocation::try_parse_from([ + "moq", + "--connect", + "http://relay", + "import", + "capture", + "--", + "export", + "--broadcast", + "other.hang", + "fmp4", + ]) + .unwrap(); + assert!(cli.validate().is_ok()); + } + + /// Only the video encoder reads the connection's bandwidth estimate, so an + /// audio-only capture doesn't compete for it and isn't counted against the + /// one-adaptive-stage limit. + #[cfg(feature = "capture")] + #[test] + fn audio_only_capture_is_not_bandwidth_adaptive() { + for (args, adaptive) in [(vec!["capture"], true), (vec!["capture", "--no-video"], false)] { + let argv = [vec!["moq", "--connect", "http://relay", "import"], args].concat(); + let cli = Invocation::try_parse_from(argv).unwrap(); + let Command::Import(import) = &cli.stages[0] else { + panic!("expected import") + }; + assert_eq!(import.source.uses_bandwidth(), adaptive); + } + } + #[test] fn latency_max_is_unset_unless_asked_for() { // Unset rather than defaulted to hang's constant, so the publisher's own default is @@ -513,7 +1007,7 @@ mod tests { "--cluster-lan=false", "--cluster-lan-secret", "cluster.key", - "--client-connect", + "--connect", "https://relay.example.com", "import", "ts", @@ -574,7 +1068,7 @@ mod tests { fn play_verb() { let cli = Cli::try_parse_from([ "moq", - "--client-connect", + "--connect", "https://relay.example.com/anon", "--broadcast", "room.hang", @@ -601,7 +1095,7 @@ mod tests { for flag in [["--video-codec", "vp9"], ["--audio-codec", "aac"]] { let cli = Cli::try_parse_from([ "moq", - "--client-connect", + "--connect", "https://relay.example.com/anon", "play", flag[0], diff --git a/rs/moq-cli/src/cluster.rs b/rs/moq-cli/src/cluster.rs index a5bb3766d5a..33abecd663e 100644 --- a/rs/moq-cli/src/cluster.rs +++ b/rs/moq-cli/src/cluster.rs @@ -301,7 +301,7 @@ pub async fn serve( server: moq_native::Server, lan: Lan, origin: moq_net::origin::Producer, - direction: crate::Direction, + directions: crate::Directions, public: bool, ) -> anyhow::Result<()> { let mut server = server.listen().await.context("failed to bind listeners")?; @@ -333,10 +333,15 @@ pub async fn serve( continue; } - let request = match direction { - crate::Direction::Import => request.with_publisher(origin.consume()), - crate::Direction::Export => request.with_subscriber(origin.clone()), - }; + // Both directions attach to the same session when the process runs both kinds + // of stage, which is how a relay peers with another relay. + let mut request = request; + if directions.publish { + request = request.with_publisher(origin.consume()); + } + if directions.consume { + request = request.with_subscriber(origin.clone()); + } tasks.spawn(async move { let err = match request.ok().await { Ok(session) => session.closed().await.into(), @@ -596,7 +601,16 @@ mod tests { accept.origin = origin_b.clone(); // The mesh shares the listener with ordinary clients, so go through the // same dispatch `--cluster-lan` installs rather than calling `accept`. - tokio::spawn(serve(server, accept, origin_b.clone(), crate::Direction::Import, false)); + tokio::spawn(serve( + server, + accept, + origin_b.clone(), + crate::Directions { + publish: true, + consume: false, + }, + false, + )); let mut dialer = lan("dialer-proof"); dialer.origin = origin_a.clone(); @@ -639,7 +653,16 @@ mod tests { let (server, peer) = listener(); let mut accept = lan("the-real-proof"); accept.origin = origin_b.clone(); - tokio::spawn(serve(server, accept, origin_b.clone(), crate::Direction::Import, false)); + tokio::spawn(serve( + server, + accept, + origin_b.clone(), + crate::Directions { + publish: true, + consume: false, + }, + false, + )); // A peer that reached the port but never saw a verifiable advertisement. let mut dialer = lan("dialer-proof"); @@ -670,7 +693,16 @@ mod tests { let mut accept = lan("the-real-proof"); accept.origin = origin.clone(); // `public: false` is what `--cluster-lan` passes with no `--listen`. - tokio::spawn(serve(server, accept, origin.clone(), crate::Direction::Import, false)); + tokio::spawn(serve( + server, + accept, + origin.clone(), + crate::Directions { + publish: true, + consume: false, + }, + false, + )); // An ordinary client: no mesh marker, no proof, just the advertised port. let mut config = moq_native::connect::Config::default(); diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index b9d6be6fc45..fe1e3605222 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -1,8 +1,8 @@ -//! moq-cli: a media router that wires one endpoint onto a shared MoQ Origin. +//! moq-cli: a media router that wires endpoints onto a shared MoQ Origin. //! //! The binary is `moq`. See [`args`] for the `import`/`export`/`play` command //! grammar; this module orchestrates the shared Origin and spawns the MoQ side -//! plus the selected endpoint. +//! plus every stage's endpoint. mod args; #[cfg(feature = "cluster-lan")] @@ -22,13 +22,12 @@ mod subscribe; mod transcode; mod web; -use args::{Cli, Command, Export, ExportSink, Import, ImportSource, MoqSide}; +use args::{Command, Export, ExportSink, Import, ImportSource, Invocation, MoqSide}; use hang::moq_net; use publish::Publish; use subscribe::{Subscribe, SubscribeArgs}; use anyhow::Context; -use clap::Parser; use tokio::task::JoinSet; #[cfg(feature = "jemalloc")] @@ -67,15 +66,6 @@ impl Net { } } -/// Which way media flows, which is what an inbound session is offered. -#[derive(Clone, Copy)] -pub enum Direction { - /// `import`: clients subscribe to what this process publishes. - Import, - /// `export`: clients publish into this process's origin. - Export, -} - /// Bind the MoQ listener and spawn everything that serves on it: ordinary /// clients, the LAN mesh when `--cluster-lan` is on, and the certificate /// endpoint for an explicit `--listen`. A no-op with no listener configured. @@ -85,7 +75,7 @@ async fn spawn_server( moq: &MoqSide, origin: &moq_net::origin::Producer, net: &Net, - direction: Direction, + directions: Directions, ) -> anyhow::Result<()> { if !moq.serves() { return Ok(()); @@ -106,15 +96,15 @@ async fn spawn_server( server, lan.clone(), origin.clone(), - direction, + directions, moq.server.bind.is_some(), )); tasks.spawn(lan.run(discovery)); } - None => spawn_serve(tasks, server, origin, direction), + None => spawn_serve(tasks, server, origin, directions), } #[cfg(not(feature = "cluster-lan"))] - spawn_serve(tasks, server, origin, direction); + spawn_serve(tasks, server, origin, directions); // The certificate endpoint is for clients dialing a URL, so it follows the // explicit listener rather than the mesh's ephemeral one. @@ -130,14 +120,29 @@ fn spawn_serve( tasks: &mut JoinSet>, server: moq_native::Server, origin: &moq_net::origin::Producer, - direction: Direction, + directions: Directions, ) { let origin = origin.clone(); tasks.spawn(async move { - match direction { - Direction::Import => server.serve_publish(origin.consume()).await?, - Direction::Export => server.serve_consume(origin).await?, - } + let _: () = match directions { + Directions { + publish: true, + consume: true, + } => server.serve_both(origin.consume(), origin).await?, + Directions { + publish: true, + consume: false, + } => server.serve_publish(origin.consume()).await?, + Directions { + publish: false, + consume: true, + } => server.serve_consume(origin).await?, + // Every caller attaches a direction: each stage is an import or an export. + Directions { + publish: false, + consume: false, + } => unreachable!("a stage always needs a direction"), + }; Ok(()) }); } @@ -150,23 +155,28 @@ async fn main() -> anyhow::Result<()> { .install_default() .expect("failed to install default crypto provider"); - let cli = Cli::parse(); + let cli = Invocation::parse(); cli.log.init()?; + cli.validate()?; // The local verbs never touch the network, so answer them before binding any - // transport. Each arm returns, so the move out of `cli.command` can't reach the - // code below. - match cli.command { - Command::Token(token) => { - cli.moq.reject("token")?; - return token.run(); - } - #[cfg(feature = "capture")] - Command::Devices => { - cli.moq.reject("devices")?; - return devices::run().await; + // transport. `validate` has already refused to pair them with another stage, so + // the single stage here is the whole invocation. + let mut stages = cli.stages; + if stages.len() == 1 { + match stages.remove(0) { + Command::Token(token) => { + cli.moq.reject("token")?; + return token.run(); + } + #[cfg(feature = "capture")] + Command::Devices => { + cli.moq.reject("devices")?; + return devices::run().await; + } + // Put it back: it needs the transport bound below. + other => stages.push(other), } - _ => {} } cli.moq.validate()?; @@ -183,17 +193,19 @@ async fn main() -> anyhow::Result<()> { let jemalloc = std::future::pending::>(); let run = async move { - match cli.command { - Command::Import(import) => run_import(cli.moq, import, net).await, - Command::Export(export) => run_export(cli.moq, export, net).await, - #[cfg(feature = "play")] - Command::Play(args) => run_play(cli.moq, args, net).await, - #[cfg(feature = "transcode")] - Command::Transcode(args) => transcode::run(cli.moq, args, net).await, - Command::Token(_) => unreachable!("handled above, before the transport is bound"), - #[cfg(feature = "capture")] - Command::Devices => unreachable!("handled above, before the transport is bound"), + // The verbs that own the process were refused alongside another stage, so a + // lone one of those runs by itself; everything else is a list of stages. + if stages.len() == 1 && !stages[0].is_stageable() { + match stages.remove(0) { + #[cfg(feature = "play")] + Command::Play(args) => return run_play(cli.moq, args, net).await, + #[cfg(feature = "transcode")] + Command::Transcode(args) => return transcode::run(cli.moq, args, net).await, + _ => unreachable!("the local verbs returned before the transport was bound"), + } } + + run_stages(cli.moq, stages, net).await }; tokio::select! { @@ -202,25 +214,73 @@ async fn main() -> anyhow::Result<()> { } } -/// Attach the MoQ side so it fills the shared Origin: dial a relay, accept -/// inbound sessions, or both. Shared by every verb that consumes. -async fn spawn_moq_consume( +/// Which directions the stages need on the shared MoQ attachment. +#[derive(Clone, Copy, Default)] +pub struct Directions { + /// Any `import`: the Origin is published outward. + pub publish: bool, + /// Any `export` or `play`: the Origin is filled from the network. + pub consume: bool, +} + +impl Directions { + /// The union of what the stages need, so one attachment serves them all. + fn of(stages: &[Command]) -> Self { + Self { + publish: stages.iter().any(|stage| matches!(stage, Command::Import(_))), + consume: stages.iter().any(|stage| matches!(stage, Command::Export(_))), + } + } +} + +/// Attach the shared Origin to the MoQ network: dial a relay, accept inbound +/// sessions, mesh with the LAN, or any combination. +/// +/// An invocation that both imports and exports attaches both directions to the +/// same session rather than opening two, which is how a relay peers with another +/// relay. Loops are the network's problem, not ours: an announcement carries the +/// hops it crossed, and our own origin id is one of them, so a broadcast we +/// publish is never announced back to us. +/// +/// Returns the uplink's bandwidth estimate, for the sources that can encode to +/// fit it. Only an outbound client has one: a `--server-bind` publisher's sessions +/// are inbound and never surfaced here, so it stays `None` and those sources +/// encode at their configured rate. +async fn spawn_moq( moq: &MoqSide, net: &Net, origin: &moq_net::origin::Producer, + directions: Directions, tasks: &mut JoinSet>, -) -> anyhow::Result<()> { - if moq.client.url.is_some() - && let Some(reconnect) = net.client(moq.client.clone())?.consume(origin.clone()) - { +) -> anyhow::Result> { + let mut bandwidth = None; + + if let Some(url) = moq.client.url.clone() { + let mut client = net.client(moq.client.clone())?; + if directions.publish { + client = client.with_publisher(origin.consume()); + } + if directions.consume { + client = client.with_subscriber(origin.clone()); + } + + // Both directions ride one connection, so this dials directly rather than + // through `Client::publish` / `Client::consume`, which each attach a single + // direction and dial the same URL. + let reconnect = client.connect(url); + // Read before the handle moves into the task. This consumer is persistent: it + // survives reconnects, reading `None` while down, so it can be wired up before + // anything connects. + bandwidth = Some(reconnect.send_bandwidth()); tasks.spawn(async move { Ok(reconnect.closed().await?) }); } - spawn_server(tasks, moq, origin, net, Direction::Export).await?; + spawn_server(tasks, moq, origin, net, directions).await?; // Every configured MoQ attachment is now initialized. In particular, a // combined client + LAN process must not report ready before the listener and // mDNS announcement have succeeded. moq::notify_ready(); - Ok(()) + + Ok(bandwidth) } /// Fill the shared Origin from MoQ, then play one broadcast locally. @@ -237,21 +297,116 @@ async fn run_play(moq: MoqSide, args: play::Args, net: Net) -> anyhow::Result<() let name = moq.broadcast.clone().unwrap_or_default(); let mut tasks: JoinSet> = JoinSet::new(); - spawn_moq_consume(&moq, &net, &origin, &mut tasks).await?; + let directions = Directions { + consume: true, + ..Default::default() + }; + spawn_moq(&moq, &net, &origin, directions, &mut tasks).await?; play::run(origin.consume(), name, args, tasks) } -/// Route one source INTO the shared Origin, exposing it to the MoQ network. -async fn run_import(moq: MoqSide, import: Import, net: Net) -> anyhow::Result<()> { +/// Run every stage over one Origin and one MoQ attachment. +/// +/// Stages are independent: each names its own broadcast and owns its own endpoint, +/// and the first to finish (stdin EOF, Ctrl-C, or an error) ends the process. +async fn run_stages(moq: MoqSide, stages: Vec, net: Net) -> anyhow::Result<()> { let origin = moq.origin()?; - // The broadcast defaults to "": MoQ names each broadcast by the connection - // path plus any explicit `--broadcast`, so an unset name is the root broadcast. - let name = moq.broadcast.clone().unwrap_or_default(); let mut tasks: JoinSet> = JoinSet::new(); - // The stdin/capture pipeline runs on this task instead of the JoinSet: the - // platform capture stream is not Send, so its future cannot be spawned. - let mut local: Option = None; + // The stdin/capture pipelines run on this thread instead of the JoinSet: the + // platform capture stream is not Send, so their futures cannot be spawned. + let mut locals: Vec = Vec::new(); + + // The stage combinations were refused up front by `Invocation::validate`, before + // anything bound a port or dialed out. + let bandwidth = spawn_moq(&moq, &net, &origin, Directions::of(&stages), &mut tasks).await?; + + // stdin and stdout are one resource each, so two stages can't share them. + let mut stdin = None; + let mut stdout = None; + + for stage in stages { + let name = stage.broadcast(&moq); + match stage { + Command::Import(import) => { + if import.source.stdin_format().is_some() { + claim("stdin", &mut stdin, &name)?; + } + if let Some(publish) = spawn_import(&origin, import, name, bandwidth.clone(), &mut tasks)? { + locals.push(publish); + } + } + Command::Export(export) => { + if export.sink.stdout().is_some() { + claim("stdout", &mut stdout, &name)?; + } + spawn_export(&origin, export, name, &mut tasks)?; + } + other => unreachable!("`{}` is not a stage", other.name()), + } + } + + if locals.is_empty() { + return drive(tasks).await; + } + + let local = tokio::task::LocalSet::new(); + supervise(&local, locals.into_iter().map(Publish::run), &mut tasks); + local.run_until(drive(tasks)).await +} + +/// Run the non-Send pipelines on `local`, reporting each into `tasks`. +/// +/// The report is what makes a local pipeline end the process on the same terms as a +/// spawned stage: it returns on stdin EOF, and a panic surfaces as an error instead +/// of leaving the other stages running without it. +fn supervise( + local: &tokio::task::LocalSet, + pipelines: impl IntoIterator, + tasks: &mut JoinSet>, +) where + F: std::future::Future> + 'static, +{ + for pipeline in pipelines { + let pipeline = local.spawn_local(pipeline); + tasks.spawn(async move { pipeline.await.context("pipeline panicked")? }); + } +} + +/// Refuse a second stage on a stream there is only one of. +fn claim(stream: &str, held: &mut Option, name: &str) -> anyhow::Result<()> { + if let Some(first) = held { + anyhow::bail!( + "only one stage can use {stream}, but both `{}` and `{}` do", + display_name(first), + display_name(name), + ); + } + + *held = Some(name.to_string()); + Ok(()) +} + +/// The broadcast name for an error message; the root broadcast has none. +fn display_name(name: &str) -> &str { + if name.is_empty() { "" } else { name } +} + +/// Route one stage's source INTO the shared Origin, exposing it to the MoQ network. +/// +/// Returns the pipeline that has to run on the caller's thread, for the sources +/// that have one (the stdin containers and capture). +fn spawn_import( + origin: &moq_net::origin::Producer, + import: Import, + name: String, + bandwidth: Option, + tasks: &mut JoinSet>, +) -> anyhow::Result> { + // Capture is the only source that reads the bandwidth estimate, so without that + // feature nothing does. + #[cfg(not(feature = "capture"))] + let _ = bandwidth; if let ImportSource::Rtc(rtc) = &import.source && rtc.connect.is_some() @@ -259,34 +414,6 @@ async fn run_import(moq: MoqSide, import: Import, net: Net) -> anyhow::Result<() reject_listener_cors(&rtc.cors, "import rtc")?; } - // The uplink's bandwidth estimate, for sources that can encode to fit it. Only - // an outbound client has one: a `--listen` publisher's sessions are - // inbound and never surfaced here, so it stays `None` and those sources encode - // at their configured rate. Capture is the only such source today, so without - // that feature nothing reads this. - #[cfg(feature = "capture")] - let mut send_bandwidth = None; - - // MoQ side: publish the Origin outward. - if moq.client.url.is_some() - && let Some(reconnect) = net.client(moq.client.clone())?.publish(origin.consume()) - { - // Read before the handle moves into the task. This consumer is - // persistent: it survives reconnects, reading `None` while down, so it - // can be wired up before anything connects. - #[cfg(feature = "capture")] - { - send_bandwidth = Some(reconnect.send_bandwidth()); - } - tasks.spawn(async move { Ok(reconnect.closed().await?) }); - } - spawn_server(&mut tasks, &moq, &origin, &net, Direction::Import).await?; - // Every configured MoQ attachment is now initialized. In particular, a - // combined client + LAN process must not report ready before the listener and - // mDNS announcement have succeeded. - moq::notify_ready(); - - // Foreign side: the single source. let latency_max = import.latency_max; // The MoQ side every gateway publishes into, minted per source since each takes it // by value onto its own task. @@ -296,6 +423,8 @@ async fn run_import(moq: MoqSide, import: Import, net: Net) -> anyhow::Result<() latency_max, }; + let mut local = None; + if let Some(format) = import.source.stdin_format() { warn_if_missing_format(&name); let broadcast = origin @@ -348,44 +477,28 @@ async fn run_import(moq: MoqSide, import: Import, net: Net) -> anyhow::Result<() let broadcast = origin .create_broadcast(&name, moq_net::broadcast::Route::new().with_announce(true)) .context("failed to create broadcast")?; - local = Some(Publish::capture( - broadcast, - &capture, - send_bandwidth, - import.latency_max, - )?); + local = Some(Publish::capture(broadcast, &capture, bandwidth, import.latency_max)?); } _ => unreachable!("container formats are handled by stdin_format above"), } } - match local { - Some(publish) => tokio::select! { - res = publish.run() => res, - res = drive(tasks) => res, - }, - None => drive(tasks).await, - } + Ok(local) } -/// Route the shared Origin OUT to one sink, filling it from the MoQ network. -async fn run_export(moq: MoqSide, export: Export, net: Net) -> anyhow::Result<()> { - let origin = moq.origin()?; - // The broadcast defaults to "": MoQ names each broadcast by the connection - // path plus any explicit `--broadcast`, so an unset name is the root broadcast. - let name = moq.broadcast.clone().unwrap_or_default(); - let mut tasks: JoinSet> = JoinSet::new(); - +/// Route the shared Origin OUT to one stage's sink, filling it from the MoQ network. +fn spawn_export( + origin: &moq_net::origin::Producer, + export: Export, + name: String, + tasks: &mut JoinSet>, +) -> anyhow::Result<()> { if let ExportSink::Rtc(rtc) = &export.sink && rtc.connect.is_some() { reject_listener_cors(&rtc.cors, "export rtc")?; } - // MoQ side: fill the Origin. - spawn_moq_consume(&moq, &net, &origin, &mut tasks).await?; - - // Foreign side: the single sink. if let Some((format, latency, fragment_duration)) = export.sink.stdout() { let args = SubscribeArgs { format, @@ -440,7 +553,7 @@ async fn run_export(moq: MoqSide, export: Export, net: Net) -> anyhow::Result<() } } - drive(tasks).await + Ok(()) } /// Subscribe to `name` from the Origin and write it to stdout. @@ -506,3 +619,43 @@ fn reject_listener_cors(cors: &crate::web::Cors, endpoint: &str) -> anyhow::Resu ); Ok(()) } + +#[cfg(test)] +mod tests { + use super::*; + use std::future::Future; + use std::pin::Pin; + + type Pipeline = Pin>>>; + + /// A local pipeline that dies takes the process with it, even while another one is + /// still running. Reporting completion from inside the task instead would miss + /// this: a panic skips the report, leaving the survivor to keep the process alive + /// with one broadcast silently gone. + #[tokio::test] + async fn a_panicking_pipeline_ends_the_process() { + let local = tokio::task::LocalSet::new(); + let mut tasks = JoinSet::new(); + + let pipelines: Vec = vec![ + Box::pin(async { panic!("pipeline died") }), + Box::pin(std::future::pending()), + ]; + supervise(&local, pipelines, &mut tasks); + + let err = local.run_until(drive(tasks)).await.unwrap_err(); + assert!(err.to_string().contains("pipeline panicked"), "{err}"); + } + + /// The first to finish ends the process, which is how stdin EOF stops a run. + #[tokio::test] + async fn a_finished_pipeline_ends_the_process() { + let local = tokio::task::LocalSet::new(); + let mut tasks = JoinSet::new(); + + let pipelines: Vec = vec![Box::pin(async { Ok(()) }), Box::pin(std::future::pending())]; + supervise(&local, pipelines, &mut tasks); + + local.run_until(drive(tasks)).await.unwrap(); + } +} diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index 195239f6ba2..eaa649fc7e8 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.10](https://github.com/moq-dev/moq/compare/moq-ffi-v0.3.9...moq-ffi-v0.3.10) - 2026-08-13 + +### Added + +- *(moq-video)* advertise the catalog rendition before the first keyframe ([#2768](https://github.com/moq-dev/moq/pull/2768)) +- *(bindings)* expose incoming request path and query ([#2738](https://github.com/moq-dev/moq/pull/2738)) + +### Fixed + +- *(release)* repair native package releases ([#2731](https://github.com/moq-dev/moq/pull/2731)) +- *(moq-ffi)* support iOS simulator builds ([#2710](https://github.com/moq-dev/moq/pull/2710)) + ## [0.3.9](https://github.com/moq-dev/moq/compare/moq-ffi-v0.3.8...moq-ffi-v0.3.9) - 2026-08-07 ### Other diff --git a/rs/moq-ffi/Cargo.toml b/rs/moq-ffi/Cargo.toml index 6a37a726073..e740dbd6bba 100644 --- a/rs/moq-ffi/Cargo.toml +++ b/rs/moq-ffi/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley ", "Brian Medley " repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.3.9" +version = "0.3.10" edition = "2024" keywords = ["quic", "http3", "webtransport", "media", "live"] diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index e2729b6f1b6..cb4113c8e56 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -23,6 +23,24 @@ fn raw_frame(frame: moq_net::frame::Frame) -> Result { }) } +fn media_frame(mut frame: moq_mux::container::Frame) -> Result { + let timestamp_us = timestamp_us(frame.timestamp)?; + let payload = frame.payload.copy_to_bytes(frame.payload.remaining()).to_vec(); + + Ok(MoqMediaFrame { + payload, + timestamp_us, + keyframe: frame.keyframe, + }) +} + +fn media_container(container: MoqContainer) -> Result { + let container: hang::catalog::Container = container.into(); + (&container) + .try_into() + .map_err(|e| MoqError::Codec(format!("invalid container: {e}"))) +} + /// Subscriber-side delivery preferences, mirroring [`moq_net::track::Subscription`]. /// /// Construct with the fields you care about; the rest default to moq-net's defaults @@ -164,22 +182,7 @@ struct Media { impl Media { async fn next(&mut self) -> Result, MoqError> { - let frame = self.inner.read().await?; - - let Some(frame) = frame else { - return Ok(None); - }; - - let timestamp_us = timestamp_us(frame.timestamp)?; - - let mut buf = frame.payload; - let payload = buf.copy_to_bytes(buf.remaining()).to_vec(); - - Ok(Some(MoqMediaFrame { - payload, - timestamp_us, - keyframe: frame.keyframe, - })) + self.inner.read().await?.map(media_frame).transpose() } } @@ -248,6 +251,27 @@ impl MoqBroadcastConsumer { Ok(Arc::new(MoqGroupConsumer::new(group))) } + /// Fetch one group and decode its track container into media frames. + /// + /// Unlike [`Self::subscribe_media`], this does not create a live subscription or apply + /// latency-based group skipping. The returned consumer reads exactly the requested group + /// until [`MoqMediaGroupConsumer::next`] returns `None`. + pub async fn fetch_media_group( + &self, + name: String, + sequence: u64, + container: MoqContainer, + options: Option, + ) -> Result, MoqError> { + // Parse the container before fetching so invalid CMAF init data does not leave a + // dynamic group request waiting for a consumer that can never read it. + let media = media_container(container)?; + let options = options.map(moq_net::group::Fetch::from); + let track = self.inner.track(&name).map_err(map_fetch_error)?; + let group = track.fetch_group(sequence, options).await.map_err(map_fetch_error)?; + Ok(Arc::new(MoqMediaGroupConsumer::new(group, media))) + } + /// Subscribe to a track by name, delivering frames in decode order. /// /// `container` is the track container from the catalog. @@ -263,10 +287,7 @@ impl MoqBroadcastConsumer { ) -> Result, MoqError> { // Parse the container before subscribing so we don't leave a dangling // subscription if init parsing fails. - let container: hang::catalog::Container = container.into(); - let media: moq_mux::catalog::hang::Container = (&container) - .try_into() - .map_err(|e| MoqError::Codec(format!("invalid container: {e}")))?; + let media = media_container(container)?; let subscription = subscription.map(moq_net::track::Subscription::from).unwrap_or_default(); let latency = subscription.latency; let track = self.inner.track(&name)?.subscribe(subscription).await?; @@ -426,6 +447,52 @@ pub struct MoqGroupConsumer { task: Task, } +struct MediaGroupInner { + inner: moq_mux::container::GroupConsumer, +} + +impl MediaGroupInner { + async fn next(&mut self) -> Result, MoqError> { + self.inner.read().await?.map(media_frame).transpose() + } +} + +/// A finite, container-decoded media group returned by +/// [`MoqBroadcastConsumer::fetch_media_group`]. +#[derive(uniffi::Object)] +pub struct MoqMediaGroupConsumer { + sequence: u64, + task: Task, +} + +impl MoqMediaGroupConsumer { + fn new(group: moq_net::group::Consumer, container: moq_mux::catalog::hang::Container) -> Self { + let inner = moq_mux::container::GroupConsumer::new(group, container); + Self { + sequence: inner.sequence(), + task: Task::new(MediaGroupInner { inner }), + } + } +} + +#[uniffi::export] +impl MoqMediaGroupConsumer { + /// The sequence number of this group within the track. + pub fn sequence(&self) -> u64 { + self.sequence + } + + /// Read the next decoded media frame, or `None` when the group ends. + pub async fn next(&self) -> Result, MoqError> { + self.task.run(|mut state| async move { state.next().await }).await + } + + /// Cancel all current and future `next()` calls. + pub fn cancel(&self) { + self.task.cancel(); + } +} + impl MoqGroupConsumer { pub(crate) fn new(group: moq_net::group::Consumer) -> Self { Self { diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 66fc1f8ca4a..02fe28c2daa 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -2,6 +2,7 @@ use super::origin::*; use super::producer::*; use super::server::MoqServer; use super::session::MoqClient; +use crate::consumer::MoqBroadcastConsumer; use crate::consumer::MoqFetchGroupOptions; use crate::consumer::MoqRouteWatch; use crate::consumer::MoqSubscription; @@ -447,6 +448,137 @@ async fn fetches_cached_group_without_subscribing() { assert!(fetched.read_frame().await.unwrap().is_none()); } +#[tokio::test] +async fn fetches_cached_media_group_and_decodes_container() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("media", None).unwrap(); + let consumer = MoqBroadcastConsumer::new(broadcast.consume()); + let mut media = moq_mux::container::Producer::new(track, moq_mux::catalog::hang::Container::Legacy); + + media + .write(moq_mux::container::Frame { + timestamp: moq_net::Timestamp::from_micros(1_000_000).unwrap(), + payload: bytes::Bytes::from_static(b"keyframe"), + keyframe: true, + duration: None, + }) + .unwrap(); + media + .write(moq_mux::container::Frame { + timestamp: moq_net::Timestamp::from_micros(1_020_000).unwrap(), + payload: bytes::Bytes::from_static(b"delta"), + keyframe: false, + duration: None, + }) + .unwrap(); + media.finish().unwrap(); + + let fetched = consumer + .fetch_media_group( + "media".into(), + 0, + crate::media::MoqContainer::Legacy, + Some(MoqFetchGroupOptions { priority: 7 }), + ) + .await + .unwrap(); + + assert_eq!(fetched.sequence(), 0); + let frame = fetched.next().await.unwrap().expect("expected keyframe"); + assert_eq!(frame.payload, b"keyframe"); + assert_eq!(frame.timestamp_us, 1_000_000); + assert!(frame.keyframe); + let frame = fetched.next().await.unwrap().expect("expected delta frame"); + assert_eq!(frame.payload, b"delta"); + assert_eq!(frame.timestamp_us, 1_020_000); + assert!(!frame.keyframe); + assert!(fetched.next().await.unwrap().is_none()); +} + +#[tokio::test] +async fn fetch_media_group_rejects_invalid_container_before_fetching() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let _track = broadcast.create_track("media", None).unwrap(); + let consumer = MoqBroadcastConsumer::new(broadcast.consume()); + + let result = consumer + .fetch_media_group( + "media".into(), + 0, + crate::media::MoqContainer::Cmaf { init: Vec::new() }, + None, + ) + .await; + + assert!(matches!(result, Err(MoqError::Codec(_)))); +} + +#[tokio::test] +async fn fetch_media_group_decodes_multiple_cmaf_samples() { + let config = hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8); + let muxer = moq_mux::container::fmp4::Muxer::video(&config).unwrap(); + let init = muxer.init().unwrap().expect("VP8 init should be available"); + let catalog_container = hang::catalog::Container::Cmaf { init: init.clone() }; + let container = moq_mux::catalog::hang::Container::try_from(&catalog_container).unwrap(); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("video", None).unwrap(); + let consumer = MoqBroadcastConsumer::new(broadcast.consume()); + // Buffer both samples into one moof+mdat, which is what this decodes. + let mut media = moq_mux::container::Producer::new(track, container).with_buffer(Duration::from_secs(1)); + for (timestamp_us, payload, keyframe) in [ + (2_000_000, bytes::Bytes::from_static(b"keyframe"), true), + (2_020_000, bytes::Bytes::from_static(b"delta"), false), + ] { + media + .write(moq_mux::container::Frame { + timestamp: moq_net::Timestamp::from_micros(timestamp_us).unwrap(), + payload, + keyframe, + duration: Some(moq_net::Timestamp::from_micros(20_000).unwrap()), + }) + .unwrap(); + } + media.finish().unwrap(); + + let fetched = tokio::time::timeout( + TIMEOUT, + consumer.fetch_media_group( + "video".into(), + 0, + crate::media::MoqContainer::Cmaf { init: init.to_vec() }, + None, + ), + ) + .await + .expect("timed out fetching CMAF group") + .unwrap(); + + let first = tokio::time::timeout(TIMEOUT, fetched.next()) + .await + .expect("timed out reading first CMAF sample") + .unwrap() + .expect("expected first sample"); + assert_eq!(first.payload, b"keyframe"); + assert_eq!(first.timestamp_us, 2_000_000); + assert!(first.keyframe); + let second = tokio::time::timeout(TIMEOUT, fetched.next()) + .await + .expect("timed out reading second CMAF sample") + .unwrap() + .expect("expected second sample"); + assert_eq!(second.payload, b"delta"); + assert_eq!(second.timestamp_us, 2_020_000); + assert!(!second.keyframe); + assert!( + tokio::time::timeout(TIMEOUT, fetched.next()) + .await + .expect("timed out finishing CMAF group") + .unwrap() + .is_none() + ); +} + #[tokio::test] async fn dynamic_track_serves_fetch_miss_and_priority() { let broadcast = MoqBroadcastProducer::new().unwrap(); diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index d2008fa9ad2..1c15d95a814 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -280,9 +280,9 @@ impl MoqBroadcastProducer { /// /// The encoder opens here, so an unsupported codec, resolution, or backend /// fails now rather than on the first frame. The track is named after the - /// codec (`.avc3` / `.hev1`) and its catalog rendition appears once the first - /// keyframe has been encoded, which is where the resolution and codec string - /// come from. + /// codec (`.avc3` / `.hev1`) and its catalog rendition is published + /// immediately, read out of the encoder rather than guessed, so a subscriber + /// can find the track before a frame is written to it. pub fn publish_video( &self, input: MoqVideoEncoderInput, @@ -298,14 +298,16 @@ impl MoqBroadcastProducer { config.gop = gop; } - // Open the encoder first: a config this machine can't encode should fail - // without leaving a track advertised that will never carry frames. + // Both before the track exists: a config this machine can't encode should fail + // without leaving a track advertised that will never carry frames. The probe + // closes its encoder before this one opens, so only one codec session is live. + let rendition = block_on(config.probe())?; let encoder = block_on(moq_video::encode::Sink::open(&config))?; let producer = self.with_state(|state| { Ok(moq_video::encode::Producer::new( state.broadcast.clone(), state.catalog.clone(), - config.codec, + rendition, )?) })?; diff --git a/rs/moq-hls/CHANGELOG.md b/rs/moq-hls/CHANGELOG.md index cc2c5ec337a..d61f4db5447 100644 --- a/rs/moq-hls/CHANGELOG.md +++ b/rs/moq-hls/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.4.7](https://github.com/moq-dev/moq/compare/moq-hls-v0.4.6...moq-hls-v0.4.7) - 2026-08-13 + +### Fixed + +- *(moq-hls)* bind renditions to the broadcast their catalog came from ([#2795](https://github.com/moq-dev/moq/pull/2795)) + ## [0.4.6](https://github.com/moq-dev/moq/compare/moq-hls-v0.4.5...moq-hls-v0.4.6) - 2026-08-06 ### Added diff --git a/rs/moq-hls/Cargo.toml b/rs/moq-hls/Cargo.toml index 2591be6ed55..1d34ae25411 100644 --- a/rs/moq-hls/Cargo.toml +++ b/rs/moq-hls/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.4.6" +version = "0.4.7" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 884115334ea..54ad94a3452 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -22,6 +22,7 @@ mod master; mod mpd; mod playlist; mod rendition; +mod upstream; pub mod renditions; pub mod segments; @@ -34,6 +35,7 @@ use rand::RngExt; pub(crate) use playlist::render_media; pub use rendition::{Kind, Rendition}; +pub(crate) use upstream::Upstream; /// Backoff bounds for the initial catalog subscription. /// @@ -92,17 +94,21 @@ impl Broadcaster { /// Resolve `source`'s catalog broadcast and start tracking its renditions. pub async fn new(source: moq_mux::Source, config: Config) -> crate::Result> { let broadcast = source.broadcast().await?; + let upstream = Upstream { + source, + broadcast: broadcast.clone(), + }; let renditions = renditions::Producer::new(config.window); let timeline_watcher = Arc::new(Mutex::new(None)); let broadcaster = Arc::new(Self { - broadcast: broadcast.clone(), + broadcast, renditions: renditions.clone(), watcher: Mutex::new(None), timeline_watcher: timeline_watcher.clone(), }); // The watcher owns its own producer clone; the `Broadcaster`'s `Drop` aborts it so the // standing catalog subscription stops when nobody's serving from this broadcaster. - let watcher = tokio::spawn(watch_catalog(source, broadcast, renditions, timeline_watcher)); + let watcher = tokio::spawn(watch_catalog(upstream, renditions, timeline_watcher)); *broadcaster.watcher.lock().unwrap() = Some(watcher); Ok(broadcaster) } @@ -256,17 +262,17 @@ impl Drop for Broadcaster { } async fn watch_catalog( - source: moq_mux::Source, - broadcast: moq_net::broadcast::Consumer, + upstream: Upstream, renditions: renditions::Producer, timeline_watcher: Arc>>>, ) { - // Built from the caller's `broadcast` handle rather than re-resolving through `source`, so - // the catalog, the timeline subscription, and the closed check below all refer to the same - // resolution. A same-name replacement between the two lookups would otherwise split them. + // The already-resolved handle rather than a fresh lookup through `source`, so the catalog, + // the timeline subscription, and the closed check below all refer to the same resolution. A + // same-name replacement between two lookups would otherwise split them. + let broadcast = &upstream.broadcast; let mut delay = CATALOG_RETRY_MIN; let mut consumer = loop { - match catalog::Consumer::<()>::new(&broadcast, CatalogFormat::Hang).await { + match catalog::Consumer::<()>::new(broadcast, CatalogFormat::Hang).await { Ok(consumer) => break consumer, Err(err) => { tracing::warn!(%err, "failed to subscribe to broadcast catalog, retrying"); @@ -287,7 +293,7 @@ async fn watch_catalog( loop { match kio::wait(|waiter| consumer.poll_next(waiter)).await { Ok(Some(catalog)) => { - renditions.sync(&source, &catalog); + renditions.sync(&upstream, &catalog); // The broadcast has one timeline; subscribe once it's advertised and fan its // records out to every rendition. if !timeline_started && let Some(section) = catalog.timeline.clone() { @@ -347,9 +353,13 @@ mod tests { use super::*; fn frame(micros: u64, keyframe: bool) -> moq_mux::container::Frame { + payload_frame(micros, keyframe, &[0xDE, 0xAD, 0xBE, 0xEF]) + } + + fn payload_frame(micros: u64, keyframe: bool, payload: &'static [u8]) -> moq_mux::container::Frame { moq_mux::container::Frame { timestamp: moq_net::Timestamp::from_micros(micros).unwrap(), - payload: bytes::Bytes::from_static(&[0xDE, 0xAD, 0xBE, 0xEF]), + payload: bytes::Bytes::from_static(payload), keyframe, duration: None, } @@ -768,6 +778,127 @@ mod tests { drop((catalog, media, registration, broadcast, rendition)); } + // A same-path republish takes the origin leaf over with a brand new broadcast (an ordinary + // publisher is `Origin::UNKNOWN`, which never counts as the same publisher, so even a plain + // reconnect qualifies). Renditions derived from the old broadcast's catalog must not serve the + // replacement's media: its group numbering restarts, so those bytes would be served under the + // replaced broadcast's segment number, duration, and PROGRAM-DATE-TIME. + #[tokio::test] + async fn a_replacement_publisher_is_not_served_under_the_replaced_catalog() { + const OLD: &[u8] = b"OLDOLDOLDOLDOLDO"; + const NEW: &[u8] = b"NEWNEWNEWNEWNEWN"; + + // Publish broadcast "live": a `video0` rendition plus three keyframe groups whose frames + // carry `payload`, so the two epochs' media differs byte for byte. The returned handle + // keeps the publisher alive until it is dropped. + fn publish( + origin: &moq_net::origin::Producer, + payload: &'static [u8], + ) -> (Box, hang::catalog::VideoConfig) { + let mut broadcast = origin + .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) + .expect("publish allowed"); + let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); + + let reserved = catalog.reserve(); + let mut registration = reserved.video("video0"); + let mut config = hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8); + config.framerate = Some(30.0); + registration.set(config.clone()); + drop(reserved); + + let track = broadcast.create_track("video0", None).unwrap(); + let mut media = catalog + .media_producer(track, moq_mux::catalog::hang::Container::Legacy) + .unwrap(); + media.write(payload_frame(0, true, payload)).unwrap(); + media.write(payload_frame(2_000_000, true, payload)).unwrap(); + media.write(payload_frame(4_000_000, true, payload)).unwrap(); + + (Box::new((broadcast, catalog, registration, media)), config) + } + + fn contains(haystack: &bytes::Bytes, needle: &[u8]) -> bool { + haystack.windows(needle.len()).any(|window| window == needle) + } + + // Reconcile a catalog snapshot by hand and drive the timeline, which is what + // `watch_catalog` does with each snapshot. + fn export( + upstream: &Upstream, + config: &hang::catalog::VideoConfig, + ) -> (Arc, tokio::task::JoinHandle<()>) { + let mut catalog = moq_mux::catalog::hang::Catalog::default(); + catalog.video.renditions.insert("video0".to_string(), config.clone()); + let section = hang::catalog::Timeline::new(hang::timeline::DEFAULT_NAME); + catalog.timeline = Some(section.clone()); + + let renditions = renditions::Producer::new(Config::default().window); + renditions.sync(upstream, &catalog); + let watcher = tokio::spawn(watch_timeline(upstream.broadcast.clone(), section, renditions.fanout())); + let rendition = renditions.get(Kind::Video, "video0").expect("rendition synced"); + (rendition, watcher) + } + + let origin = moq_net::Origin::random().produce(); + let (old, config) = publish(&origin, OLD); + settle().await; + + // The export binds to the broadcast it reads the catalog from. + let source = moq_mux::Source::new(origin.consume(), "live"); + let upstream = Upstream { + broadcast: source.broadcast().await.unwrap(), + source, + }; + + // The publisher reconnects before the catalog snapshot is reconciled. That gap is wide in + // practice: `watch_catalog` retries a not-yet-written catalog track with backoff, so + // seconds can pass between resolving the broadcast and syncing its first snapshot. + drop(old); + let (new, _) = publish(&origin, NEW); + settle().await; + + let (rendition, watcher) = export(&upstream, &config); + let _ = tokio::time::timeout(Duration::from_secs(1), rendition.playable()).await; + let served = rendition.segment(0).await.unwrap(); + if let Some(served) = &served { + assert!( + !contains(served, NEW), + "the replacement publisher's media was served under the replaced broadcast's catalog" + ); + } + assert!( + served.is_none(), + "the replaced broadcast is closed, so it serves nothing" + ); + watcher.abort(); + + // Control: an export started after the takeover does serve the new publisher's media, so + // the assertion above is about which epoch a rendition is bound to, not about a broadcast + // that happens to be unreadable. + let source = moq_mux::Source::new(origin.consume(), "live"); + let fresh = Upstream { + broadcast: source.broadcast().await.unwrap(), + source, + }; + let (rendition, watcher) = export(&fresh, &config); + tokio::time::timeout(Duration::from_secs(5), rendition.playable()) + .await + .expect("the new publisher's timeline arrives"); + let served = rendition + .segment(0) + .await + .unwrap() + .expect("the new publisher is servable on its own catalog"); + assert!( + contains(&served, NEW), + "the new export serves the new publisher's media" + ); + watcher.abort(); + + drop(new); + } + // A rendition the catalog drops must end its segment cursors. The cursor holds an // `Arc`, so without an explicit close the rendition (and its timeline // subscription) would stay alive and the cursor would park at the live edge forever. @@ -778,6 +909,11 @@ mod tests { .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) .expect("publish allowed"); let source = moq_mux::Source::new(origin.consume(), "live"); + settle().await; + let upstream = Upstream { + broadcast: source.broadcast().await.unwrap(), + source, + }; // Drive the producer directly so the catalog can be reconciled synchronously. let renditions = renditions::Producer::new(Config::default().window); @@ -785,7 +921,7 @@ mod tests { let mut catalog = moq_mux::catalog::hang::Catalog::default(); catalog.video.renditions.insert("video".to_string(), media); catalog.timeline = Some(hang::catalog::Timeline::new(hang::timeline::DEFAULT_NAME)); - renditions.sync(&source, &catalog); + renditions.sync(&upstream, &catalog); let rendition = renditions.get(Kind::Video, "video").expect("rendition synced"); let mut segments = rendition.segments(); @@ -795,7 +931,7 @@ mod tests { timeline: Some(hang::catalog::Timeline::new(hang::timeline::DEFAULT_NAME)), ..Default::default() }; - renditions.sync(&source, &empty); + renditions.sync(&upstream, &empty); let ended = tokio::time::timeout(Duration::from_secs(5), segments.next()) .await .expect("a removed rendition's cursor ends instead of parking") diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index c9bc87dadd6..622301777e2 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -10,6 +10,7 @@ use moq_mux::container::fmp4::Muxer; use moq_mux::timeline::Entry; use super::playlist::{Segment, Snapshot}; +use super::upstream::Upstream; use super::{mpd, segments}; use crate::Result; @@ -84,7 +85,8 @@ pub struct Rendition { /// This rendition's window over the broadcast timeline, fed by the catalog watcher's /// fan-out. live: Arc, - /// The source and (possibly sibling) broadcast reference, resolved lazily for FETCH. + /// The source and sibling broadcast reference, for the cross-broadcast case: a rendition + /// served by the catalog's own broadcast already holds it (see [`Upstream::local`]). source: moq_mux::Source, sibling: Option, /// The init segment, built on first request. @@ -101,7 +103,7 @@ impl Rendition { } /// Build a video rendition over the broadcast's timeline `section`. - pub(crate) fn video(name: String, config: &VideoConfig, source: &moq_mux::Source, section: Timeline) -> Self { + pub(crate) fn video(name: String, config: &VideoConfig, upstream: &Upstream, section: Timeline) -> Self { Self { name, kind: Kind::Video, @@ -111,15 +113,15 @@ impl Rendition { codec: config.codec.to_string(), config: Config::Video(config.clone()), section, - live: Arc::new(segments::Producer::new()), - source: source.clone(), + live: Arc::new(segments::Producer::new(upstream.local(config.broadcast.as_ref()))), + source: upstream.source.clone(), sibling: config.broadcast.clone(), init: tokio::sync::Mutex::new(None), } } /// Build an audio rendition over the broadcast's timeline `section`. - pub(crate) fn audio(name: String, config: &AudioConfig, source: &moq_mux::Source, section: Timeline) -> Self { + pub(crate) fn audio(name: String, config: &AudioConfig, upstream: &Upstream, section: Timeline) -> Self { Self { name, kind: Kind::Audio, @@ -129,8 +131,8 @@ impl Rendition { codec: config.codec.to_string(), config: Config::Audio(config.clone()), section, - live: Arc::new(segments::Producer::new()), - source: source.clone(), + live: Arc::new(segments::Producer::new(upstream.local(config.broadcast.as_ref()))), + source: upstream.source.clone(), sibling: config.broadcast.clone(), init: tokio::sync::Mutex::new(None), } @@ -328,8 +330,12 @@ impl Rendition { }) } - /// The media track handle on its (possibly sibling) broadcast, resolved lazily on the - /// first fetch. + /// The media track handle on the broadcast serving this rendition. + /// + /// Seeded at construction unless the catalog names a sibling, so the media comes from the + /// same broadcast the catalog did. Resolving the path again would not be idempotent: a + /// same-path republish installs a new broadcast at the leaf, whose group numbering restarts, + /// and its bytes would be served under the replaced broadcast's segment numbers. async fn track(&self) -> Option { if self.live.broadcast.get().is_none() { let broadcast = self.source.resolve(self.sibling.as_ref()).await.ok()?; diff --git a/rs/moq-hls/src/export/renditions.rs b/rs/moq-hls/src/export/renditions.rs index 7ad53c85614..b6e09403b92 100644 --- a/rs/moq-hls/src/export/renditions.rs +++ b/rs/moq-hls/src/export/renditions.rs @@ -17,6 +17,7 @@ use std::time::{Duration, SystemTime}; use moq_mux::catalog::hang::Catalog; use moq_mux::timeline::Entry; +use super::Upstream; use super::rendition::{Kind, Rendition}; /// The `(kind, name)` identity of a rendition. Video and audio are separate axes, so a video @@ -280,7 +281,10 @@ impl Producer { /// Renditions are only servable when the catalog advertises the broadcast's timeline (its /// root `timeline` section): without one there is nothing to render playlists from, so the /// whole catalog is skipped with a warning. - pub fn sync(&self, source: &moq_mux::Source, catalog: &Catalog) { + /// + /// `upstream` carries the broadcast the snapshot was read from, so each rendition serves media + /// from that same broadcast rather than whatever is at the path by the time it is asked. + pub fn sync(&self, upstream: &Upstream, catalog: &Catalog) { let Some(section) = catalog.timeline.clone() else { if !catalog.video.renditions.is_empty() || !catalog.audio.renditions.is_empty() { tracing::warn!("catalog advertises no timeline; its renditions can't be served as HLS"); @@ -322,7 +326,7 @@ impl Producer { if current.contains_key(&key) { continue; } - let rendition = Arc::new(Rendition::video(name.clone(), video, source, section.clone())); + let rendition = Arc::new(Rendition::video(name.clone(), video, upstream, section.clone())); self.register(&rendition); current.insert(key, rendition); } @@ -331,7 +335,7 @@ impl Producer { if current.contains_key(&key) { continue; } - let rendition = Arc::new(Rendition::audio(name.clone(), audio, source, section.clone())); + let rendition = Arc::new(Rendition::audio(name.clone(), audio, upstream, section.clone())); self.register(&rendition); current.insert(key, rendition); } diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index 35a8a8fedd4..00949bec5cd 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -35,8 +35,9 @@ use crate::Result; /// [`kio::Producer`] so a [`Consumer`] can await changes without a separate signal. pub(crate) struct Producer { state: kio::Producer, - /// The broadcast serving the media track, resolved once (it may be a sibling broadcast - /// when the catalog rendition carries a `broadcast` reference). + /// The broadcast serving the media track. Seeded at construction for a rendition served by + /// the catalog's own broadcast, and otherwise resolved on the first fetch, when the catalog + /// rendition's `broadcast` reference names a sibling. pub broadcast: OnceLock, } @@ -120,13 +121,16 @@ impl State { } impl Producer { - pub fn new() -> Self { + /// An empty window. `broadcast` is the media broadcast when it is already known, i.e. for a + /// rendition served by the catalog's own broadcast; a sibling reference passes `None` and + /// [`Rendition::track`](super::Rendition) resolves it on the first fetch. + pub fn new(broadcast: Option) -> Self { Self { state: kio::Producer::new(State { rows: VecDeque::new(), ended: false, }), - broadcast: OnceLock::new(), + broadcast: broadcast.map(OnceLock::from).unwrap_or_default(), } } @@ -366,7 +370,7 @@ mod tests { #[test] fn every_row_is_listed() { - let live = Producer::new(); + let live = Producer::new(None); live.push(row(0, 0, 0, 2_000), Duration::from_secs(30)); live.push(row(1, 1, 2_000, 2_000), Duration::from_secs(30)); @@ -383,7 +387,7 @@ mod tests { #[test] fn window_evicts_and_advances_sequence() { - let live = Producer::new(); + let live = Producer::new(None); let window = Duration::from_secs(4); for i in 0..6u64 { live.push(row(i, i, i * 2_000, 2_000), window); @@ -400,7 +404,7 @@ mod tests { #[test] fn segment_ranges_and_gaps() { - let live = Producer::new(); + let live = Producer::new(None); let window = Duration::from_secs(30); live.push(row(0, 0, 0, 1_000), window); // Segment 1 is a gap for this rendition: no ranges. @@ -426,7 +430,7 @@ mod tests { #[test] fn backwards_jump_resets_the_window() { - let live = Producer::new(); + let live = Producer::new(None); let window = Duration::from_secs(30); live.push(row(0, 0, 10_000, 2_000), window); live.push(row(1, 1, 12_000, 2_000), window); @@ -443,7 +447,7 @@ mod tests { #[test] fn next_after_walks_segments() { - let live = Producer::new(); + let live = Producer::new(None); let window = Duration::from_secs(30); live.push(row(0, 0, 0, 2_000), window); live.push(row(1, 1, 2_000, 2_000), window); diff --git a/rs/moq-hls/src/export/upstream.rs b/rs/moq-hls/src/export/upstream.rs new file mode 100644 index 00000000000..6405a2e88fc --- /dev/null +++ b/rs/moq-hls/src/export/upstream.rs @@ -0,0 +1,30 @@ +//! The broadcast an export is bound to, held rather than looked up again by path. + +/// The one broadcast an export is bound to: the already-resolved catalog consumer, plus the +/// [`moq_mux::Source`] it came from so a rendition can still follow a cross-broadcast reference. +/// +/// The two travel together because resolving the catalog path by name is not idempotent. A +/// same-path republish is a takeover (`Origin::UNKNOWN` never counts as the same publisher, so +/// every ordinary publisher reconnect qualifies), and that installs a brand new broadcast at the +/// leaf. A rendition that looked its media up by path would then serve the replacement's groups +/// under the manifest, segment numbering, and `PROGRAM-DATE-TIME` of the broadcast it replaced. +#[derive(Clone)] +pub(crate) struct Upstream { + /// Origin plus catalog path, for resolving a rendition's sibling `broadcast` reference. + pub source: moq_mux::Source, + /// The catalog broadcast, resolved once when the export started. + pub broadcast: moq_net::broadcast::Consumer, +} + +impl Upstream { + /// The broadcast serving a rendition whose catalog `broadcast` field is `rel`, when that can + /// be answered without a round trip. + /// + /// An absent or empty reference means the catalog broadcast itself, which is already in hand. + /// A named sibling returns `None` and has to go through [`moq_mux::Source::resolve`]. + pub fn local(&self, rel: Option<&moq_net::PathRelativeOwned>) -> Option { + rel.filter(|rel| !rel.is_empty()) + .is_none() + .then(|| self.broadcast.clone()) + } +} diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index dd99acb524d..22337c0870e 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.9.6](https://github.com/moq-dev/moq/compare/moq-mux-v0.9.5...moq-mux-v0.9.6) - 2026-08-13 + +### Added + +- *(moq-video)* advertise the catalog rendition before the first keyframe ([#2768](https://github.com/moq-dev/moq/pull/2768)) + +### Fixed + +- *(moq-mux)* resync TS audio instead of aborting the broadcast ([#2751](https://github.com/moq-dev/moq/pull/2751)) + +### Other + +- *(deps)* bump cargo group and support mp4-atom 0.15 ([#2728](https://github.com/moq-dev/moq/pull/2728)) + ## [0.9.5](https://github.com/moq-dev/moq/compare/moq-mux-v0.9.4...moq-mux-v0.9.5) - 2026-08-07 ### Added diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index 73cb88e7115..9dc8386138d 100644 --- a/rs/moq-mux/Cargo.toml +++ b/rs/moq-mux/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.9.5" +version = "0.9.6" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-mux/src/codec/h264/import.rs b/rs/moq-mux/src/codec/h264/import.rs index f68b56eeaf2..2ab8685b5cb 100644 --- a/rs/moq-mux/src/codec/h264/import.rs +++ b/rs/moq-mux/src/codec/h264/import.rs @@ -86,20 +86,8 @@ impl Import { fn initialize_avc1(&mut self, avcc_bytes: &[u8]) -> Result<()> { // Only switch to avc1 mode once the avcC actually parses, so a parse failure leaves the // importer in avc3 mode where inline-SPS keyframes still self-initialize. - let avcc = super::Avcc::parse(avcc_bytes)?; + let config = config_from_avcc(avcc_bytes)?; self.avc1 = true; - - let mut config = hang::catalog::VideoConfig::new(hang::catalog::H264 { - profile: avcc.profile, - constraints: avcc.constraints, - level: avcc.level, - inline: false, - }); - config.coded_width = avcc.coded_width; - config.coded_height = avcc.coded_height; - config.description = Some(Bytes::copy_from_slice(avcc_bytes)); - config.container = hang::catalog::Container::Legacy; - self.apply_config(config); Ok(()) } @@ -190,17 +178,7 @@ impl Import { if self.last_sps.as_ref() == Some(sps_nal) { return Ok(()); } - let sps = Sps::parse(sps_nal)?; - let mut config = hang::catalog::VideoConfig::new(hang::catalog::H264 { - profile: sps.profile, - constraints: sps.constraints, - level: sps.level, - inline: true, - }); - config.coded_width = Some(sps.coded_width); - config.coded_height = Some(sps.coded_height); - config.container = hang::catalog::Container::Legacy; - + let config = config_from_sps(sps_nal)?; self.last_sps = Some(sps_nal.clone()); self.apply_config(config); Ok(()) @@ -251,6 +229,55 @@ impl Import { } } +/// The catalog config a stream's codec bytes describe, resolved without publishing anything: an +/// `AVCDecoderConfigurationRecord` (the avc1 shape) or Annex-B carrying an inline SPS (avc3). +/// +/// The video counterpart of [`opus::config`](crate::codec::opus::config), for a caller holding the +/// bytes but no track: a publisher that wants its catalog rendition to say what its encoder really +/// emits reads it out of one encoded keyframe rather than guessing. +pub fn config(buf: &[u8]) -> Result { + if crate::codec::annexb::is_config_record(buf) { + return config_from_avcc(buf); + } + let sps = find_sps(buf).ok_or(Error::NotInitialized)?; + config_from_sps(&sps) +} + +/// The config an `AVCDecoderConfigurationRecord` describes, stored verbatim as the `description` +/// (`inline: false`, the avc1 shape). +fn config_from_avcc(avcc_bytes: &[u8]) -> Result { + let avcc = super::Avcc::parse(avcc_bytes)?; + + let mut config = hang::catalog::VideoConfig::new(hang::catalog::H264 { + profile: avcc.profile, + constraints: avcc.constraints, + level: avcc.level, + inline: false, + }); + config.coded_width = avcc.coded_width; + config.coded_height = avcc.coded_height; + config.description = Some(Bytes::copy_from_slice(avcc_bytes)); + config.container = hang::catalog::Container::Legacy; + Ok(config) +} + +/// The config an inline SPS describes (`inline: true`, the avc3 shape). No `description`: the +/// parameter sets ride with every keyframe. +fn config_from_sps(sps_nal: &[u8]) -> Result { + let sps = Sps::parse(sps_nal)?; + + let mut config = hang::catalog::VideoConfig::new(hang::catalog::H264 { + profile: sps.profile, + constraints: sps.constraints, + level: sps.level, + inline: true, + }); + config.coded_width = Some(sps.coded_width); + config.coded_height = Some(sps.coded_height); + config.container = hang::catalog::Container::Legacy; + Ok(config) +} + fn is_sps(nal: &[u8]) -> bool { nal.first().is_some_and(|h| h & 0x1f == NAL_TYPE_SPS) } diff --git a/rs/moq-mux/src/codec/h265/import.rs b/rs/moq-mux/src/codec/h265/import.rs index 4a285ef4c3d..37e43a998f1 100644 --- a/rs/moq-mux/src/codec/h265/import.rs +++ b/rs/moq-mux/src/codec/h265/import.rs @@ -180,27 +180,7 @@ impl Import { if self.last_sps.as_ref() == Some(sps_nal) { return Ok(()); } - - let sps = SpsNALUnit::parse(&mut &sps_nal[..]).map_err(|_| Error::SpsParse)?; - let profile = &sps.rbsp.profile_tier_level.general_profile; - let vui_data = sps.rbsp.vui_parameters.as_ref().map(VuiData::new).unwrap_or_default(); - - let mut config = hang::catalog::VideoConfig::new(hang::catalog::H265 { - in_band: true, // An inline SPS is the hev1 shape; hvc1 configs come from `config_from_hvcc`. - profile_space: profile.profile_space, - profile_idc: profile.profile_idc, - profile_compatibility_flags: profile.profile_compatibility_flag.bits().to_be_bytes(), - tier_flag: profile.tier_flag, - level_idc: profile.level_idc.ok_or(Error::MissingLevelIdc)?, - constraint_flags: super::pack_constraint_flags(profile), - }); - config.coded_width = Some(sps.rbsp.cropped_width() as u32); - config.coded_height = Some(sps.rbsp.cropped_height() as u32); - config.framerate = vui_data.framerate; - config.display_aspect_width = vui_data.display_ratio_width; - config.display_aspect_height = vui_data.display_ratio_height; - config.container = hang::catalog::Container::Legacy; - + let config = config_from_sps(sps_nal)?; self.last_sps = Some(sps_nal.clone()); self.apply_config(config); Ok(()) @@ -249,6 +229,43 @@ impl Import { } } +/// The catalog config a stream's codec bytes describe, resolved without publishing anything: an +/// `HEVCDecoderConfigurationRecord` (the hvc1 shape) or Annex-B carrying an inline SPS (hev1). +/// +/// The H.265 counterpart of [`h264::config`](crate::codec::h264::config). +pub fn config(buf: &[u8]) -> Result { + if crate::codec::annexb::is_config_record(buf) { + return Ok(super::config_from_hvcc(buf)?); + } + let sps = find_sps(buf).ok_or(Error::NotInitialized)?; + config_from_sps(&sps) +} + +/// The config an inline SPS describes (`in_band: true`, the hev1 shape). No `description`: the +/// parameter sets ride with every keyframe. +fn config_from_sps(sps_nal: &[u8]) -> Result { + let sps = SpsNALUnit::parse(&mut &sps_nal[..]).map_err(|_| Error::SpsParse)?; + let profile = &sps.rbsp.profile_tier_level.general_profile; + let vui_data = sps.rbsp.vui_parameters.as_ref().map(VuiData::new).unwrap_or_default(); + + let mut config = hang::catalog::VideoConfig::new(hang::catalog::H265 { + in_band: true, // An inline SPS is the hev1 shape; hvc1 configs come from `config_from_hvcc`. + profile_space: profile.profile_space, + profile_idc: profile.profile_idc, + profile_compatibility_flags: profile.profile_compatibility_flag.bits().to_be_bytes(), + tier_flag: profile.tier_flag, + level_idc: profile.level_idc.ok_or(Error::MissingLevelIdc)?, + constraint_flags: super::pack_constraint_flags(profile), + }); + config.coded_width = Some(sps.rbsp.cropped_width() as u32); + config.coded_height = Some(sps.rbsp.cropped_height() as u32); + config.framerate = vui_data.framerate; + config.display_aspect_width = vui_data.display_ratio_width; + config.display_aspect_height = vui_data.display_ratio_height; + config.container = hang::catalog::Container::Legacy; + Ok(config) +} + fn is_sps(nal: &[u8]) -> bool { nal.first() .is_some_and(|h| nal_unit_type(*h) == scuffle_h265::NALUnitType::SpsNut) diff --git a/rs/moq-mux/src/container/group.rs b/rs/moq-mux/src/container/group.rs new file mode 100644 index 00000000000..24547dd3a4f --- /dev/null +++ b/rs/moq-mux/src/container/group.rs @@ -0,0 +1,153 @@ +use std::collections::VecDeque; +use std::task::{Poll, ready}; + +use super::{Container, Frame}; + +/// Decode a single [`moq_net::group::Consumer`] into a finite stream of media [`Frame`]s. +/// +/// This is the group-scoped counterpart to [`Consumer`](super::Consumer). Where that one +/// subscribes to a track and juggles group ordering, latency skipping, and rewinds, this one +/// reads exactly the group it was handed, in arrival order, and ends. That is what a caller +/// wants after a FETCH: a group already chosen by sequence, with no live subscription and no +/// latency budget that could skip the very group being asked for. +/// +/// A batch of frames decoded from one wire frame (a CMAF fragment carrying several samples) is +/// handed back one frame at a time. +pub struct GroupConsumer { + group: moq_net::group::Consumer, + format: F, + + // Frames decoded from the last wire frame but not yet returned. + pending: VecDeque, + + // How many frames we have returned, so the first one can be marked a keyframe. + index: u64, +} + +impl GroupConsumer { + /// Decode `group` with the given container format. + pub fn new(group: moq_net::group::Consumer, format: F) -> Self { + Self { + group, + format, + pending: VecDeque::new(), + index: 0, + } + } + + /// The sequence number of this group within its track. + pub fn sequence(&self) -> u64 { + self.group.sequence + } + + /// Read the next frame, or `None` once the group ends. + pub async fn read(&mut self) -> Result, F::Error> { + kio::wait(|waiter| self.poll_read(waiter)).await + } + + /// Poll for the next frame, without blocking. + pub fn poll_read(&mut self, waiter: &kio::Waiter) -> Poll, F::Error>> { + loop { + if let Some(mut frame) = self.pending.pop_front() { + // First frame of a group is always a keyframe by protocol invariant; trust + // the container's flag otherwise so CMAF mid-group keyframes survive. + frame.keyframe = frame.keyframe || self.index == 0; + self.index += 1; + return Poll::Ready(Ok(Some(frame))); + } + + // An empty batch is not end-of-group, so keep looping until the format says None. + let Some(frames) = ready!(self.format.poll_read(&mut self.group, waiter))? else { + return Poll::Ready(Ok(None)); + }; + self.pending.extend(frames); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::catalog::hang::Container as Hang; + + fn frame(timestamp_us: u64, payload: &'static [u8], keyframe: bool) -> Frame { + Frame { + timestamp: moq_net::Timestamp::from_micros(timestamp_us).unwrap(), + payload: bytes::Bytes::from_static(payload), + keyframe, + duration: None, + } + } + + /// Read one retained group end to end, without a subscription. + #[tokio::test] + async fn reads_a_group_to_completion() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("media", None).unwrap(); + let consumer = broadcast.consume(); + + let mut media = crate::container::Producer::new(track, Hang::Legacy); + media.write(frame(1_000_000, b"keyframe", true)).unwrap(); + media.write(frame(1_020_000, b"delta", false)).unwrap(); + media.finish().unwrap(); + + let group = consumer.track("media").unwrap().fetch_group(0, None).await.unwrap(); + let mut group = GroupConsumer::new(group, Hang::Legacy); + assert_eq!(group.sequence(), 0); + + let first = group.read().await.unwrap().unwrap(); + assert_eq!(first.payload, b"keyframe".as_slice()); + assert!(first.keyframe); + + let second = group.read().await.unwrap().unwrap(); + assert_eq!(second.payload, b"delta".as_slice()); + assert!(!second.keyframe); + + assert!(group.read().await.unwrap().is_none()); + } + + /// One CMAF fragment decodes to several samples, which are handed back one at a time. + #[tokio::test] + async fn hands_back_a_cmaf_batch_one_frame_at_a_time() { + let config = hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8); + let muxer = crate::container::fmp4::Muxer::video(&config).unwrap(); + let init = muxer.init().unwrap().expect("VP8 init should be available"); + let cmaf = hang::catalog::Container::Cmaf { init }; + // The format is not Clone, so decode with a second instance built from the same init. + let format = Hang::try_from(&cmaf).unwrap(); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("video", None).unwrap(); + let consumer = broadcast.consume(); + + // Buffer both samples into one moof+mdat, which is what this decodes. + let mut media = crate::container::Producer::new(track, format).with_buffer(std::time::Duration::from_secs(1)); + for (timestamp_us, payload, keyframe) in [ + (2_000_000, b"keyframe".as_slice(), true), + (2_020_000, b"delta".as_slice(), false), + ] { + media + .write(Frame { + timestamp: moq_net::Timestamp::from_micros(timestamp_us).unwrap(), + payload: bytes::Bytes::from_static(payload), + keyframe, + duration: Some(moq_net::Timestamp::from_micros(20_000).unwrap()), + }) + .unwrap(); + } + media.finish().unwrap(); + + let group = consumer.track("video").unwrap().fetch_group(0, None).await.unwrap(); + let mut group = GroupConsumer::new(group, Hang::try_from(&cmaf).unwrap()); + + let first = group.read().await.unwrap().unwrap(); + assert_eq!(first.payload, b"keyframe".as_slice()); + assert!(first.keyframe); + + let second = group.read().await.unwrap().unwrap(); + assert_eq!(second.payload, b"delta".as_slice()); + assert!(!second.keyframe); + + assert!(group.read().await.unwrap().is_none()); + } +} diff --git a/rs/moq-mux/src/container/mod.rs b/rs/moq-mux/src/container/mod.rs index 36209e0b9d3..8e880fe6c38 100644 --- a/rs/moq-mux/src/container/mod.rs +++ b/rs/moq-mux/src/container/mod.rs @@ -15,6 +15,7 @@ use std::task::Poll; use bytes::Bytes; mod consumer; +mod group; mod producer; mod source; #[cfg(test)] @@ -28,6 +29,7 @@ pub mod mkv; pub mod ts; pub use consumer::Consumer; +pub use group::GroupConsumer; pub use producer::Producer; pub(crate) use source::ExportSource; diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 09956e1c0d3..31466e55d30 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -69,12 +69,12 @@ pub struct Export { /// Standalone SI sections captured on import, keyed by PID and re-emitted verbatim /// on their own cadence. Opaque: export never parses a table it carries. si: BTreeMap, - /// When each SI PID was last emitted, so each honors its own interval. + /// When each SI PID was last emitted, so each honors its own interval ([`due`]). last_si: HashMap, /// Program tables, built once the track layout is known. psi: Option, - /// Media timestamp of the last PAT/PMT emission. + /// Media timestamp of the last PAT/PMT emission ([`due`]). last_psi: Option, /// Tune-in point: the first video keyframe's timestamp, captured when the program /// tables are built. Non-video frames before it are dropped so the keyframe leads @@ -981,13 +981,36 @@ const PES_DTS_LEN: usize = 5; /// [`author_dts`] and [`Track::dts_reserve`]. const DEFAULT_DTS_RESERVE: u64 = 16; +/// Whether `timestamp` has crossed into a later repetition slot than `last`. +/// +/// Slots are absolute on the media timeline (`floor(timestamp / interval)`) rather than +/// measured forward from the previous emission, so a table lands on the same frames no +/// matter when the exporter started. Two exporters of one broadcast then emit the tables +/// at the same points, which a redundant pair compares byte for byte. `None` (nothing +/// emitted yet) is always due, so a fresh exporter leads with the tables and a receiver +/// can tune in without waiting for the next slot. +/// +/// A *later* slot, not merely a different one: video is emitted in decode order, so a +/// reordered (B-frame) PTS steps backwards all the time, and re-emitting on every +/// oscillation across a boundary buys nothing and costs a table each way. fn due(timestamp: Timestamp, last: Option, interval: Duration) -> bool { + // "Every frame", which the slot arithmetic can't express (and would divide by zero on). + if interval.is_zero() { + return true; + } let Some(last) = last else { return true; }; - Duration::from(timestamp) - .checked_sub(Duration::from(last)) - .is_some_and(|elapsed| elapsed >= interval) + slot(timestamp, interval) > slot(last, interval) +} + +/// Index of `timestamp`'s repetition slot: how many whole `interval`s fit under it. +/// +/// Nanoseconds, so the divisor is zero only for a genuinely zero `interval`, which [`due`] +/// takes before it gets here. Coarser units would floor a sub-unit interval to zero and +/// divide by it. +fn slot(timestamp: Timestamp, interval: Duration) -> u128 { + Duration::from(timestamp).as_nanos() / interval.as_nanos() } /// External byte size of an adaptation field (manual mirror of the crate's @@ -1192,7 +1215,7 @@ mod tests { use moq_net::Timestamp; - use super::{DEFAULT_DTS_RESERVE, PSI_INTERVAL, author_dts, due, is_complete_section}; + use super::{DEFAULT_DTS_RESERVE, PSI_INTERVAL, author_dts, due, is_complete_section, slot}; fn ms(value: u64) -> Timestamp { Timestamp::from_millis(value).unwrap() @@ -1293,10 +1316,40 @@ mod tests { } #[test] - fn due_uses_elapsed_duration() { + fn author_dts_is_join_independent_at_a_peak() { + // An exporter that has been running and one that just joined author the same decode + // timeline from any frame whose PTS leads everything decoded before it. A keyframe is + // exactly that (export only ever tunes in on one), so the monotonic bump cannot fire + // there and the state carried across the join stops mattering. + for b in [1, 3, 5] { + let pts = decode_order(40, b, 3_600, 10_000_000); + let running = run_clock(&pts, DEFAULT_DTS_RESERVE); + + let mut peaks = 0; + for k in 1..pts.len() { + if pts[..k].iter().any(|&p| p >= pts[k]) { + continue; + } + peaks += 1; + let fresh = run_clock(&pts[k..], DEFAULT_DTS_RESERVE); + assert_eq!( + &running[k..], + &fresh[..], + "b={b}: joining at {k} authored a different clock" + ); + } + assert!(peaks > 10, "b={b}: fixture must have peaks to join at, got {peaks}"); + } + } + + #[test] + fn due_crosses_an_absolute_slot() { assert!(due(ms(1_000), None, PSI_INTERVAL)); assert!(!due(ms(1_250), Some(ms(1_000)), PSI_INTERVAL)); assert!(due(ms(1_500), Some(ms(1_000)), PSI_INTERVAL)); + + // A backwards timestamp is a slot already served, not a new one. Emitting there would + // fire on every B-frame that steps back across a boundary (see `due_ignores_reorder`). assert!(!due(ms(750), Some(ms(1_000)), PSI_INTERVAL)); // A per-PID SI interval is honored independently of the PSI cadence: an SDT at @@ -1306,6 +1359,75 @@ mod tests { assert!(due(ms(3_000), Some(ms(1_000)), sdt)); } + /// Drive a run of timestamps through the interval cadence, advancing the stored emission + /// only when one fires, and return how many tables it emitted. That is the whole of the SI + /// path; PSI additionally emits (and re-anchors) at every video keyframe, which is what + /// keeps two exporters of a program *with* video in step even before this. + fn run_cadence(stamps: &[Timestamp], interval: Duration) -> usize { + let mut last = None; + let mut emissions = 0; + for &ts in stamps { + if due(ts, last, interval) { + emissions += 1; + last = Some(ts); + } + } + emissions + } + + #[test] + fn due_ignores_reorder() { + // Video is emitted in decode order, so a B-frame stream steps its PTS backwards + // constantly (measured at 39% of frames on real contribution content). The cadence has + // to follow the slots the stream has *reached*, not fire on every crossing of one, or + // each oscillation across a boundary re-sends the tables both ways. + let ticks = decode_order(40, 3, 3_600, 10_000_000); + let stamps: Vec = ticks + .iter() + .map(|&t| Timestamp::from_micros(t * 1_000_000 / 90_000).unwrap()) + .collect(); + assert!(stamps.windows(2).any(|w| w[1] < w[0]), "fixture must reorder its PTS"); + + // One table per slot the stream covers, however often the reorder revisits a boundary. + let first = slot(stamps[0], PSI_INTERVAL); + let last = slot(*stamps.iter().max().unwrap(), PSI_INTERVAL); + assert_eq!(run_cadence(&stamps, PSI_INTERVAL), (last - first + 1) as usize); + } + + #[test] + fn due_zero_interval_emits_every_frame() { + // A catalog is free to ask for a table on every frame. Slot arithmetic can't express + // that (and would divide by zero), so it is handled before the division. Repeated + // timestamps are the case a slot count gets wrong: two tracks can share one. + let stamps: Vec = [0, 0, 40, 40, 80].iter().map(|&t| ms(t)).collect(); + assert_eq!(run_cadence(&stamps, Duration::ZERO), stamps.len()); + } + + #[test] + fn due_survives_a_sub_microsecond_interval() { + // Only an exactly-zero interval short-circuits, so the slot divisor has to stay + // non-zero for every other duration. Nanoseconds do; anything coarser floors a + // sub-unit interval to zero and panics on the division. + let interval = Duration::from_nanos(500); + assert!( + !interval.is_zero() && interval.as_micros() == 0, + "fixture must be sub-microsecond" + ); + assert!(due(ms(1), Some(ms(0)), interval)); + assert!(!due(ms(0), Some(ms(0)), interval)); + } + + #[test] + fn due_ignores_when_the_last_emission_landed_in_its_slot() { + // The whole point of the absolute grid: two exporters that emitted at different + // points *within* the same slot agree on every later frame, so the emission points + // belong to the broadcast rather than to whoever started when. + for last in [1_000, 1_100, 1_499] { + assert!(!due(ms(1_499), Some(ms(last)), PSI_INTERVAL), "last={last}"); + assert!(due(ms(1_500), Some(ms(last)), PSI_INTERVAL), "last={last}"); + } + } + #[test] fn section_validation() { // section_length 27 (0x1b) -> 30 bytes total. diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 8eaa5522018..6d4678ff0e8 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -1731,3 +1731,186 @@ async fn opus_export_import_roundtrip() { assert_eq!(got.as_slice(), orig.as_ref(), "Opus packet survived the round-trip"); } } + +// Two exporters of one broadcast, started at different times, must render the same packets +// from the moment they overlap. That is what a redundant (SMPTE ST 2022-7) pair compares, and +// it is what lets a leg be restarted without the merge at the far end seeing the two disagree. +// See moq-dev/moq#2779. + +/// 25 fps video. +const VIDEO_US: u64 = 40_000; +/// 48 kHz AAC, 1024 samples per frame. +const AUDIO_US: u64 = 21_333; +/// Video frames per group. Deliberately not a whole number of PSI intervals, so a table +/// cadence anchored anywhere but the media timeline drifts against the keyframes. +const GOP: u64 = 15; +/// Audio frames per group, roughly matching the video group duration. +const AUDIO_GROUP: u64 = 28; +/// Video-frame ticks to produce, and the tick the second exporter joins at. +const TICKS: u64 = 150; +const JOIN: u64 = 75; + +/// Produce one broadcast and export it twice, the second exporter joining partway in, and +/// return what each rendered. +/// +/// Both exporters are drained after every write, so neither skips a group and the two see the +/// same arrival order. That isolates the question under test (does the *rendering* depend on +/// when the process started) from the separate question of whether two legs received the same +/// groups in the same order. +async fn export_twice(with_video: bool) -> (Vec, Vec) { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast).unwrap(); + + let mut video = with_video.then(|| { + let track = broadcast + .create_track(broadcast.unique_name(".avc1"), hang::container::track_info()) + .unwrap(); + // Out-of-band parameter sets (avc1), so the export source takes the catalog + // description as-is instead of parsing them out of the bitstream. + let mut cfg = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: false, + }); + cfg.container = Container::Legacy; + cfg.description = + Some(crate::codec::h264::build_avcc(&[Bytes::from_static(SPS)], &[Bytes::from_static(PPS)]).unwrap()); + catalog.lock().video.renditions.insert(track.name().to_string(), cfg); + Producer::new(track, HangContainer::Legacy) + }); + + let mut audio = { + let track = broadcast + .create_track(broadcast.unique_name(".aac"), hang::container::track_info()) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile: 2 }, 48_000, 2); + cfg.container = Container::Legacy; + catalog.lock().audio.renditions.insert(track.name().to_string(), cfg); + Producer::new(track, HangContainer::Legacy) + }; + + let source = crate::source::announced(&consumer); + let mut a = Export::new(source.clone()).await.unwrap(); + let mut b = None; + let (mut out_a, mut out_b) = (Vec::new(), Vec::new()); + + let mut audio_index = 0; + for tick in 0..TICKS { + if let Some(video) = video.as_mut() { + let keyframe = tick % GOP == 0; + let slice = if keyframe { + vec![0x65u8; 3_000] + } else { + vec![0x41u8; 400] + }; + video + .write(Frame { + timestamp: Timestamp::from_micros(tick * VIDEO_US).unwrap(), + duration: None, + payload: length_prefixed(&[&slice]), + keyframe, + }) + .unwrap(); + } + // Every audio frame that starts before the next video tick. + while audio_index * AUDIO_US < (tick + 1) * VIDEO_US { + audio + .write(Frame { + timestamp: Timestamp::from_micros(audio_index * AUDIO_US).unwrap(), + duration: None, + payload: Bytes::from_iter((0..180u16).map(|i| (i ^ audio_index as u16) as u8)), + keyframe: audio_index % AUDIO_GROUP == 0, + }) + .unwrap(); + audio_index += 1; + } + + out_a.extend(drain_frames(&mut a).await); + if let Some(b) = b.as_mut() { + out_b.extend(drain_frames(b).await); + } + if tick + 1 == JOIN { + b = Some(Export::new(source.clone()).await.unwrap()); + } + } + + (out_a, out_b) +} + +/// Pull every frame an exporter can render right now, like `drain` but keeping the frames +/// whole (this compares them one by one, not as one byte stream). +async fn drain_frames(export: &mut Export) -> Vec { + let mut out = Vec::new(); + while let Ok(res) = tokio::time::timeout(Duration::from_secs(1), export.next()).await { + match res.expect("exporter error") { + Some(frame) => out.push(frame), + None => break, + } + } + out +} + +/// Compare the overlapping output of two exporters, starting at `from`, and assert the only +/// bytes that disagree are continuity counters. +/// +/// The counter is the known exception: it is numbered from process state, so two legs are +/// offset by a constant. Fixing that needs the emitted packet count per group to be a function +/// of the broadcast, which is a much larger change than this guards. Everything else has to +/// match exactly, so this fails if any new field starts being minted per process. +fn assert_only_continuity_differs(a: &[Frame], b: &[Frame], from: Timestamp) { + let a: Vec<&Frame> = a.iter().filter(|f| f.timestamp >= from).collect(); + let b: Vec<&Frame> = b.iter().filter(|f| f.timestamp >= from).collect(); + assert!(b.len() > 20, "not enough overlap to be worth comparing: {}", b.len()); + assert_eq!(a.len(), b.len(), "exporters rendered a different number of frames"); + + for (a, b) in a.iter().zip(b.iter()) { + assert_eq!(a.timestamp, b.timestamp, "compared frames must be the same frame"); + assert_eq!( + a.payload.len(), + b.payload.len(), + "same frame rendered to a different size" + ); + assert_packet_aligned(&a.payload); + + for (offset, (x, y)) in a.payload.iter().zip(b.payload.iter()).enumerate() { + if x == y { + continue; + } + // Byte 3 of a TS packet is `transport_scrambling_control | adaptation_field_control | + // continuity_counter`, and only the low nibble is the counter. A difference anywhere + // else is a value the exporter minted from its own state rather than from the broadcast. + assert_eq!( + (offset % 188, (x ^ y) & 0xf0), + (3, 0), + "frame at {:?} differs outside the continuity counter: offset {offset}, {x:#04x} vs {y:#04x}", + a.timestamp, + ); + } + } +} + +#[tokio::test(start_paused = true)] +async fn late_join_matches_a_running_exporter() { + let (a, b) = export_twice(true).await; + + // Skip to the joiner's second keyframe: its first group covers tune-in, where the two legs + // legitimately differ because only the joiner has to lead with the program tables. + let keyframes: Vec = b.iter().filter(|f| f.keyframe).map(|f| f.timestamp).collect(); + assert_only_continuity_differs(&a, &b, keyframes[1]); +} + +/// The same property for a program with no video track. Worth its own case because the program +/// tables are re-emitted at every video keyframe, a boundary both legs share, which hides a +/// drifting cadence. Audio-only has no such boundary, so the cadence has to come from the media +/// timeline on its own. +#[tokio::test(start_paused = true)] +async fn late_join_matches_a_running_exporter_without_video() { + let (a, b) = export_twice(false).await; + + // The joiner leads with PAT/PMT on its very first frame so a receiver can tune in; the + // running exporter has no reason to repeat them there. From the next frame on the two are + // rendering the same stream. + assert_only_continuity_differs(&a, &b, b[1].timestamp); +} diff --git a/rs/moq-native/CHANGELOG.md b/rs/moq-native/CHANGELOG.md index facab623803..0b1a32313fb 100644 --- a/rs/moq-native/CHANGELOG.md +++ b/rs/moq-native/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.19.10](https://github.com/moq-dev/moq/compare/moq-native-v0.19.9...moq-native-v0.19.10) - 2026-08-13 + +### Added + +- *(native)* start dialing before the AAAA answer lands ([#2749](https://github.com/moq-dev/moq/pull/2749)) +- *(bindings)* expose incoming request path and query ([#2738](https://github.com/moq-dev/moq/pull/2738)) + +### Fixed + +- *(net)* keep a live-edge subscriber at the live edge across a takeover ([#2785](https://github.com/moq-dev/moq/pull/2785)) +- *(native)* make a build with one transport compile again ([#2780](https://github.com/moq-dev/moq/pull/2780)) +- *(native)* generate protocol version help ([#2719](https://github.com/moq-dev/moq/pull/2719)) + ## [0.19.9](https://github.com/moq-dev/moq/compare/moq-native-v0.19.8...moq-native-v0.19.9) - 2026-08-07 ### Added diff --git a/rs/moq-native/Cargo.toml b/rs/moq-native/Cargo.toml index ec1e93b4d45..b90dcfc9953 100644 --- a/rs/moq-native/Cargo.toml +++ b/rs/moq-native/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.19.9" +version = "0.19.10" edition = "2024" rust-version.workspace = true @@ -14,9 +14,9 @@ categories = ["multimedia", "network-programming", "web-programming"] [features] default = ["quinn", "aws-lc-rs", "websocket", "tcp", "uds"] -quinn = ["dep:quinn", "dep:web-transport-quinn", "dep:rcgen", "dep:reqwest", "dep:rustls-webpki", "watch"] -noq = ["dep:web-transport-noq", "dep:rcgen", "dep:reqwest", "dep:rustls-webpki", "watch"] -quiche = ["dep:web-transport-quiche", "dep:rcgen", "dep:reqwest", "dep:rustls-webpki", "dep:rustls-native-certs"] +quinn = ["dep:quinn", "dep:web-transport-quinn", "dep:rcgen", "dep:reqwest", "dep:rustls-webpki", "watch", "dep:dns-lookup"] +noq = ["dep:web-transport-noq", "dep:rcgen", "dep:reqwest", "dep:rustls-webpki", "watch", "dep:dns-lookup"] +quiche = ["dep:web-transport-quiche", "dep:rcgen", "dep:reqwest", "dep:rustls-webpki", "dep:rustls-native-certs", "dep:dns-lookup"] # Filesystem watcher for hot-reloading on-disk TLS certs/keys; the QUIC backends imply it. watch = ["dep:notify"] # Capture qlog traces (`--*-quic-qlog `). Off by default: quinn and noq pull in @@ -34,7 +34,7 @@ mdns = ["dep:mdns-sd", "dep:hmac", "dep:sha2", "dep:subtle"] jemalloc = ["dep:tikv-jemallocator", "dep:tikv-jemalloc-ctl"] websocket = ["dep:qmux"] # Plain-TCP qmux transport (`tcp://`), no TLS. Server-side and client-side. -tcp = ["dep:qmux"] +tcp = ["dep:qmux", "dep:dns-lookup"] # Unix-domain-socket qmux transport (`unix://`), unix-only. Adds peer-credential # inspection on accept. Pulls in `tcp` (shares qmux's stream transport). uds = ["tcp", "qmux/uds"] @@ -44,6 +44,9 @@ android-logcat = ["dep:tracing-android"] [dependencies] bytes = "1" clap = { version = "4", features = ["derive", "env"] } +# Family-restricted `getaddrinfo`, so the AAAA and A queries can be issued separately +# (RFC 8305 section 3) while still going through the system resolver. +dns-lookup = { version = "3", optional = true } futures = "0.3" hex = "0.4" hmac = { workspace = true, optional = true } diff --git a/rs/moq-native/src/bind.rs b/rs/moq-native/src/bind.rs index ac851761e56..6f992826f4b 100644 --- a/rs/moq-native/src/bind.rs +++ b/rs/moq-native/src/bind.rs @@ -5,7 +5,8 @@ //! `IPV6_V6ONLY` to on, so an IPv6 socket silently drops every IPv4 packet. The //! helpers here clear that before binding, so a relay on `[::]` is reachable //! over IPv4 and a dual-stack client can dial IPv4 servers (via IPv4-mapped -//! addresses; the client's address-family matching lives in `failover::match_local`). +//! addresses; the client's address-family matching lives in +//! `resolve::Candidates::with_local`). //! See . use socket2::{Domain, Protocol, Socket, TcpKeepalive, Type}; diff --git a/rs/moq-native/src/client.rs b/rs/moq-native/src/client.rs index 33d50a7ea40..922e5ff7299 100644 --- a/rs/moq-native/src/client.rs +++ b/rs/moq-native/src/client.rs @@ -30,10 +30,12 @@ pub struct Client { pub(crate) reconnect: bool, pub(crate) backoff: Backoff, pub(crate) goaway: GoawayConfig, - /// The resolved Happy Eyeballs stagger, used by the `tcp://` dial here; the + /// The resolved Happy Eyeballs timings, used by the `tcp://` dial here; the /// QUIC backends capture their own copy from the config. #[cfg(feature = "tcp")] failover_delay: std::time::Duration, + #[cfg(feature = "tcp")] + resolution_delay: std::time::Duration, #[cfg(feature = "websocket")] websocket: crate::websocket::Config, /// Only the rustls-based dials read this. quiche builds its own TLS stack, and the @@ -122,6 +124,8 @@ impl Client { // Read before the struct literal below moves fields out of `config`. #[cfg(feature = "tcp")] let failover_delay = config.resolved_race(); + #[cfg(feature = "tcp")] + let resolution_delay = config.resolved_resolution_delay(); let timeout = config.resolved_timeout(); Ok(Self { @@ -142,6 +146,8 @@ impl Client { goaway: config.goaway, #[cfg(feature = "tcp")] failover_delay, + #[cfg(feature = "tcp")] + resolution_delay, #[cfg(feature = "websocket")] websocket: config.websocket, #[cfg(any(feature = "noq", feature = "quinn", feature = "websocket"))] @@ -350,7 +356,8 @@ impl Client { // QUIC, which can't speak it. Use only on a trusted network. #[cfg(feature = "tcp")] if url.scheme() == "tcp" { - let session = crate::tcp::connect(url, &self.versions.alpns(), self.failover_delay).await?; + let session = + crate::tcp::connect(url, &self.versions.alpns(), self.failover_delay, self.resolution_delay).await?; return Ok(moq.connect(crate::transport::Async::new(session)).await?); } @@ -812,6 +819,42 @@ mod tests { assert_eq!(config.race, Some(std::time::Duration::from_millis(50))); } + #[test] + fn test_toml_resolution_delay_survives_update_from() { + let toml = r#" + resolution_delay = "10ms" + "#; + + let config: crate::connect::Config = toml::from_str(toml).unwrap(); + assert_eq!(config.resolution_delay, Some(std::time::Duration::from_millis(10))); + + // Simulate: TOML loaded, then CLI args re-applied (no --connect-resolution-delay flag). + let mut cli = Cli { config }; + cli.update_from(["test"]); + assert_eq!(cli.config.resolution_delay, Some(std::time::Duration::from_millis(10))); + } + + #[test] + fn test_cli_resolution_delay() { + let config = Cli::config_from(["test", "--connect-resolution-delay", "0s"]); + assert_eq!(config.resolution_delay, Some(std::time::Duration::ZERO)); + assert_eq!(config.resolved_resolution_delay(), std::time::Duration::ZERO); + } + + /// The released `--client-resolution-delay` spelling still lands on the field. + #[test] + fn test_cli_resolution_delay_legacy() { + let config = Cli::config_from(["test", "--client-resolution-delay", "10ms"]).resolved(); + assert_eq!(config.resolution_delay, Some(std::time::Duration::from_millis(10))); + } + + #[test] + fn resolution_delay_defaults_to_the_rfc_value() { + let config = Cli::config_from(["test"]); + assert_eq!(config.resolution_delay, None); + assert_eq!(config.resolved_resolution_delay(), std::time::Duration::from_millis(50)); + } + #[test] fn test_toml_fingerprint_survives_update_from() { let toml = r#" @@ -1096,7 +1139,7 @@ mod tests { ))] #[test] fn iroh_only_client_does_not_require_a_tls_provider() { - ClientConfig::default().init().expect("iroh-only client"); + crate::connect::Config::default().init().expect("iroh-only client"); } #[test] diff --git a/rs/moq-native/src/connect.rs b/rs/moq-native/src/connect.rs index 30a9a0eb48c..0589875e18a 100644 --- a/rs/moq-native/src/connect.rs +++ b/rs/moq-native/src/connect.rs @@ -18,6 +18,13 @@ pub(crate) const DEFAULT_TIMEOUT: std::time::Duration = std::time::Duration::fro /// [`Config::resolved_race`] has to answer in every build. pub(crate) const DEFAULT_RACE: std::time::Duration = std::time::Duration::from_millis(250); +/// How long the first candidate waits for the full DNS answer before settling for +/// the IPv4-only one, unless overridden by `--connect-resolution-delay`. RFC 8305's +/// recommended Resolution Delay. +/// +/// Lives here for the same reason as [`DEFAULT_RACE`]. +pub(crate) const DEFAULT_RESOLUTION_DELAY: std::time::Duration = std::time::Duration::from_millis(50); + /// One or more addresses for the same peer, tried in order until one connects. /// /// Most callers have a single URL and never name this type: @@ -107,6 +114,15 @@ pub(crate) struct Legacy { )] race: Option, + #[arg( + id = "client-resolution-delay", + long = "client-resolution-delay", + env = "MOQ_CLIENT_RESOLUTION_DELAY", + value_parser = humantime::parse_duration, + hide = true, + )] + resolution_delay: Option, + #[arg( id = "client-reconnect", long = "client-reconnect", @@ -152,6 +168,9 @@ impl Legacy { if self.race.is_some() { used.push("--client-failover-delay -> --connect-race"); } + if self.resolution_delay.is_some() { + used.push("--client-resolution-delay -> --connect-resolution-delay"); + } if self.reconnect.is_some() { used.push("--client-reconnect -> --connect-once (inverted)"); } @@ -377,6 +396,22 @@ pub struct Config { )] pub race: Option, + /// Delay before dialing an IPv4 address while the full DNS answer is outstanding. + /// + /// A dial runs the usual all-families lookup alongside an IPv4-only one that + /// answers without waiting for the AAAA record, and starts on the first answer. + /// The full answer is authoritative, including which family to try first, so + /// this is how long the IPv4-only one waits for it before going ahead alone. + /// Defaults to 50ms; `0s` dials as soon as any address resolves. + #[serde(default, skip_serializing_if = "Option::is_none", with = "humantime_serde::option")] + #[arg( + id = "connect-resolution-delay", + long = "connect-resolution-delay", + env = "MOQ_CONNECT_RESOLUTION_DELAY", + value_parser = humantime::parse_duration, + )] + pub resolution_delay: Option, + /// Maximum time for one [`crate::Client::connect`], covering the dial and the MoQ /// handshake. Defaults to 30 seconds; set to 0 to wait forever. /// @@ -490,6 +525,7 @@ impl Config { resolved.backend = self.backend.clone().or(legacy.backend.clone()); resolved.timeout = self.timeout.or(legacy.timeout); resolved.race = self.race.or(legacy.race); + resolved.resolution_delay = self.resolution_delay.or(legacy.resolution_delay); // The two legacy spellings say "keep reconnecting", so they invert. resolved.once = self .once @@ -548,6 +584,13 @@ impl Config { self.race.unwrap_or(DEFAULT_RACE) } + /// The Resolution Delay a dial will actually use, resolving the default from + /// the [`resolution_delay`](Self::resolution_delay) override. Read by every + /// backend, like [`resolved_race`](Self::resolved_race). + pub fn resolved_resolution_delay(&self) -> std::time::Duration { + self.resolution_delay.unwrap_or(DEFAULT_RESOLUTION_DELAY) + } + /// The deadline one connection attempt will actually get, dial and handshake /// together, resolving the default from the [`timeout`](Self::timeout) override. pub fn resolved_timeout(&self) -> std::time::Duration { diff --git a/rs/moq-native/src/failover.rs b/rs/moq-native/src/failover.rs index 6d0a5447234..11c1266562e 100644 --- a/rs/moq-native/src/failover.rs +++ b/rs/moq-native/src/failover.rs @@ -1,4 +1,4 @@ -//! Happy Eyeballs (RFC 8305) address failover for client dials. +//! Connection-phase Happy Eyeballs (RFC 8305 section 5) for client dials. //! //! DNS often returns both IPv6 and IPv4 addresses, and either family can be //! silently broken (an unrouted AAAA, a blocked v4 path). Rather than dial one @@ -6,6 +6,11 @@ //! every resolved address, alternating families, and takes the first connection //! to complete. The stagger is [`connect::Config::race`](crate::connect::Config::race). //! +//! The addresses arrive from the DNS phase as they resolve, and in the order the +//! platform's own resolver put them in, so a lookup still waiting on its AAAA +//! record no longer holds up the first attempt. How long that first attempt +//! holds back for the full answer is [`crate::connect::Config::resolution_delay`]. +//! //! Nothing here needs calling: every client dial goes through it. The one type //! a consumer sees is [`Failure`], which the backend `Error` types carry when //! the race loses every attempt. @@ -18,8 +23,7 @@ use std::time::Duration; use futures::StreamExt; use futures::stream::FuturesUnordered; -#[cfg(any(feature = "noq", feature = "quinn", feature = "quiche"))] -pub(crate) use local::match_local; +use crate::resolve::Candidates; /// One failed connection attempt, naming the address it dialed. /// @@ -57,207 +61,11 @@ pub(crate) trait Aggregate: Sized { /// Never called with fewer than two: a lone attempt is no race, so [`race`] /// hands that error back untouched rather than burying it in an aggregate. fn aggregate(failures: Vec>) -> Self; -} - -/// Order resolved addresses for racing: keep the resolver's order within each -/// family (the OS already applies RFC 6724 destination selection), but alternate -/// families so attempt N+1 is always the other family from attempt N when one is -/// available. The first address keeps its position, so the resolver still picks -/// the preferred family. -pub(crate) fn interleave(addrs: impl IntoIterator) -> Vec { - let (mut a, mut b): (Vec, Vec) = (Vec::new(), Vec::new()); - for addr in addrs { - if a.is_empty() || a[0].is_ipv4() == addr.is_ipv4() { - a.push(addr); - } else { - b.push(addr); - } - } - let mut out = Vec::with_capacity(a.len() + b.len()); - let (mut a, mut b) = (a.into_iter(), b.into_iter()); - loop { - match (a.next(), b.next()) { - (Some(x), Some(y)) => { - out.push(x); - out.push(y); - } - (Some(x), None) => out.push(x), - (None, Some(y)) => out.push(y), - (None, None) => break, - } - } - out -} - -/// Adapting candidates to the family of an already-bound local socket. -/// -/// Only the QUIC backends need this: they send every attempt from one socket -/// bound up front, so a candidate that socket can't reach has to be converted or -/// dropped. The stream transports open a fresh socket per attempt and let the OS -/// pick the source, so nothing here applies to them. -#[cfg(any(feature = "noq", feature = "quinn", feature = "quiche"))] -mod local { - use std::collections::HashSet; - use std::net::{IpAddr, SocketAddr}; - - /// [`super::interleave`], then adapt each address to the family of the `local` socket. - /// - /// A candidate the socket can't reach is converted when the conversion is - /// lossless (IPv4 to IPv4-mapped IPv6 for a dual-stack socket, and the reverse) - /// and dropped when it isn't. `dual_stack` is [`crate::bind::udp_is_dual_stack`] - /// for that socket. When every candidate would be dropped, the normalized - /// candidates are kept so the dial surfaces the OS error instead of a confusing - /// "no DNS entries". See for the - /// Windows failure this family matching originally fixed. - pub(crate) fn match_local( - addrs: impl IntoIterator, - local: SocketAddr, - dual_stack: bool, - ) -> Vec { - // Duplicates cost a wasted dial and a repeated line in the error, and they - // don't have to arrive adjacent: interleaving separates two copies of the same - // address with the other family, and normalizing collapses `1.2.3.4` and - // `::ffff:1.2.3.4` into one value only after that. So dedup by value rather - // than with `Vec::dedup`, keeping the first occurrence's position. - let mut seen = HashSet::new(); - let candidates: Vec = super::interleave(addrs) - .into_iter() - .map(|addr| normalize_family(addr, local)) - .filter(|addr| seen.insert(*addr)) - .collect(); - - let usable: Vec = candidates - .iter() - .copied() - .filter(|addr| addressable(*addr, local, dual_stack)) - .collect(); - - if usable.is_empty() { candidates } else { usable } - } - - /// Whether a socket bound to `local` can send to `dest`. - /// - /// Mostly this is the address family, but reaching IPv4 from an IPv6 socket has - /// a wrinkle: it means sending to an IPv4-mapped destination, which the kernel - /// turns back into a real IPv4 packet, and that needs an IPv4 source address. So - /// it takes both a socket that is actually dual-stack (`IPV6_V6ONLY` cleared, - /// which [`crate::bind::udp`] only attempts) and a bind that left an IPv4 source - /// to use: `[::]` does, since the kernel picks the source, and an IPv4-mapped - /// bind already is one, but a concrete IPv6 bind is not. The mirror holds too: - /// an IPv4-mapped bind can't reach a real IPv6 destination. - fn addressable(dest: SocketAddr, local: SocketAddr, dual_stack: bool) -> bool { - let (SocketAddr::V6(dest), SocketAddr::V6(local)) = (dest, local) else { - return dest.is_ipv4() == local.is_ipv4(); - }; - - match (dest.ip().to_ipv4_mapped(), local.ip().to_ipv4_mapped()) { - (Some(_), None) => dual_stack && local.ip().is_unspecified(), - (None, Some(_)) => false, - _ => true, - } - } - - /// Convert `addr` to match the family of `local` when the conversion is - /// lossless: unwrap IPv4-mapped IPv6 to IPv4, or wrap IPv4 as IPv4-mapped IPv6. - fn normalize_family(addr: SocketAddr, local: SocketAddr) -> SocketAddr { - match (addr, local.is_ipv4()) { - (SocketAddr::V6(v6), true) => match v6.ip().to_ipv4_mapped() { - Some(v4) => SocketAddr::new(IpAddr::V4(v4), v6.port()), - None => addr, - }, - (SocketAddr::V4(v4), false) => SocketAddr::new(IpAddr::V6(v4.ip().to_ipv6_mapped()), v4.port()), - _ => addr, - } - } - - #[cfg(test)] - mod tests { - use super::*; - - fn v4(s: &str) -> SocketAddr { - s.parse().unwrap() - } - - #[test] - fn match_local_prefers_matching_family() { - let a4 = v4("127.0.0.1:443"); - let a6 = v4("[::1]:443"); - - // IPv6 listed first, but local socket is IPv4: only IPv4 is usable. - assert_eq!(match_local([a6, a4], v4("0.0.0.0:0"), false), vec![a4]); - // IPv4 wraps to IPv4-mapped for an IPv6 (dual-stack) socket. - assert_eq!( - match_local([a4, a6], v4("[::]:0"), true), - vec![v4("[::ffff:127.0.0.1]:443"), a6] - ); - } - - #[test] - fn match_local_skips_mapped_ipv4_on_a_v6_only_socket() { - let a4 = v4("192.0.2.1:443"); - let a6 = v4("[2001:db8::1]:443"); - assert_eq!(match_local([a4, a6], v4("[::]:0"), false), vec![a6]); - } - - #[test] - fn match_local_skips_ipv4_for_a_concrete_v6_bind() { - let a4 = v4("192.0.2.1:443"); - let a6 = v4("[2001:db8::1]:443"); - assert_eq!(match_local([a4, a6], v4("[2001:db8::5]:0"), true), vec![a6]); - } - - #[test] - fn match_local_keeps_normalized_fallback_when_none_are_usable() { - let a4 = v4("192.0.2.1:443"); - assert_eq!( - match_local([a4], v4("[::]:0"), false), - vec![v4("[::ffff:192.0.2.1]:443")] - ); - } - - #[test] - fn match_local_unwraps_v4_mapped_for_v4_socket() { - let mapped = v4("[::ffff:127.0.0.1]:443"); - assert_eq!(match_local([mapped], v4("0.0.0.0:0"), false), vec![v4("127.0.0.1:443")]); - } - - #[test] - fn match_local_falls_back_for_unmappable_v6() { - // IPv4 socket with only a true IPv6 entry: no conversion possible, keep it - // so the OS surfaces a clear error. - let a6 = v4("[2001:db8::1]:443"); - assert_eq!(match_local([a6], v4("0.0.0.0:0"), false), vec![a6]); - } - - #[test] - fn match_local_empty() { - assert!(match_local(std::iter::empty(), v4("0.0.0.0:0"), false).is_empty()); - } - - #[test] - fn match_local_dedups_across_the_interleave() { - // Two copies of the same IPv4 entry land either side of the IPv6 one, so - // only a value-wise dedup catches them. - let a4 = v4("1.2.3.4:443"); - let a6 = v4("[2001:db8::1]:443"); - assert_eq!(match_local([a4, a4, a6], v4("0.0.0.0:0"), false), vec![a4]); - assert_eq!( - match_local([a4, a4, a6], v4("[::]:0"), true), - vec![v4("[::ffff:1.2.3.4]:443"), a6] - ); - } - - #[test] - fn match_local_dedups_normalized_forms() { - // The same address twice, once already IPv4-mapped: different families - // going in, one candidate coming out. - let a4 = v4("1.2.3.4:443"); - let mapped = v4("[::ffff:1.2.3.4]:443"); - assert_eq!(match_local([a4, mapped], v4("[::]:0"), true), vec![mapped]); - assert_eq!(match_local([mapped, a4], v4("0.0.0.0:0"), false), vec![a4]); - } - } + /// The error for a dial that never had an address to try: the DNS failure + /// when there was one, and the backend's empty-answer error when both queries + /// simply came back with nothing. + fn resolve(error: Option) -> Self; } /// Render each failed attempt as `addr: error`, joined by `; `. @@ -269,7 +77,12 @@ pub(crate) fn describe(failures: &[Failure]) -> String { /// previous one (or immediately when it fails), and return the first success. /// The remaining attempts are dropped, which aborts them. /// -/// A `delay` of zero dials every candidate at once. +/// Candidates are pulled as they resolve, so the first attempt starts on the +/// first answer rather than on the last, and a stagger that elapses while the +/// other family is still being resolved starts its attempt the moment an address +/// lands. +/// +/// A `delay` of zero dials every candidate at once, as fast as they resolve. /// /// A single candidate is not a race, so its error comes back untouched: an IP /// literal or a host with one address still reports the backend's own error, @@ -281,17 +94,21 @@ pub(crate) fn describe(failures: &[Failure]) -> String { /// blackholed until its timeout, and either can bury a rejected certificate or a /// refused port that the caller could act on. /// -/// `candidates` must not be empty; callers map an empty DNS answer to their own -/// error before racing. -pub(crate) async fn race(candidates: Vec, delay: Duration, mut dial: F) -> Result +/// A resolution that never yields an address reports [`Aggregate::resolve`] +/// instead, since there was no attempt to report. +pub(crate) async fn race(mut candidates: Candidates, delay: Duration, mut dial: F) -> Result where F: FnMut(SocketAddr) -> Fut, Fut: Future>, E: Aggregate + fmt::Display, { - let mut remaining = candidates.into_iter(); let mut attempts = FuturesUnordered::new(); let mut failures: Vec<(usize, Failure)> = Vec::new(); + let mut exhausted = false; + + // When the next attempt may start: the first as soon as an address resolves, + // each later one a stagger after the one before it. + let mut ready = tokio::time::Instant::now(); let mut next_index = 0; let mut start = |addr: SocketAddr, attempts: &mut FuturesUnordered<_>| { @@ -302,17 +119,24 @@ where attempts.push(async move { (index, addr, attempt.await) }); }; - let first = remaining.next().expect("no candidates to dial"); - start(first, &mut attempts); - loop { + if exhausted && attempts.is_empty() { + if failures.is_empty() { + return Err(E::resolve(candidates.failure())); + } + + // Report in candidate order, not the order they finished, so the same DNS + // answer always reads the same way. + failures.sort_by_key(|(index, _)| *index); + return Err(collapse(failures.into_iter().map(|(_, failure)| failure).collect())); + } + tokio::select! { // Bias toward a finished attempt so a success that raced the timer wins // without dialing another address for nothing. biased; - res = attempts.next() => { - let (index, addr, res) = res.expect("attempts can't be empty here"); + Some((index, addr, res)) = attempts.next(), if !attempts.is_empty() => { match res { Ok(conn) => { tracing::debug!(%addr, index, "connected"); @@ -327,28 +151,35 @@ where failures.push((index, Failure { addr, error: err })); // A failure starts the next candidate immediately (RFC 8305 // section 5) rather than waiting out the stagger delay. - if let Some(addr) = remaining.next() { - start(addr, &mut attempts); - } else if attempts.is_empty() { - // Report in candidate order, not the order they finished, - // so the same DNS answer always reads the same way. - failures.sort_by_key(|(index, _)| *index); - return Err(collapse(failures.into_iter().map(|(_, failure)| failure).collect())); - } + ready = tokio::time::Instant::now(); } } } - // Recreated each iteration, so the stagger measures from the most - // recently started attempt. - _ = tokio::time::sleep(delay), if remaining.len() > 0 => { - let addr = remaining.next().expect("guarded by remaining.len()"); - start(addr, &mut attempts); + // The deadline is absolute, so cancelling this arm (which every finished + // attempt does) resumes the same stagger rather than restarting it. + addr = pull(&mut candidates, ready), if !exhausted => { + match addr { + Some(addr) => { + start(addr, &mut attempts); + ready = tokio::time::Instant::now() + delay; + } + None => exhausted = true, + } } } } } +/// The next candidate to dial, once the stagger has elapsed. +/// +/// Resolution can outlast the stagger, in which case the attempt starts as soon +/// as an address lands. +async fn pull(candidates: &mut Candidates, ready: tokio::time::Instant) -> Option { + tokio::time::sleep_until(ready).await; + candidates.next().await +} + /// Fold the failed attempts into one error, leaving a lone attempt's error /// exactly as the backend produced it. fn collapse(mut failures: Vec>) -> E { @@ -365,7 +196,7 @@ mod tests { use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; - fn v4(s: &str) -> SocketAddr { + fn addr(s: &str) -> SocketAddr { s.parse().unwrap() } @@ -390,55 +221,34 @@ mod tests { fn aggregate(failures: Vec>) -> Self { Self::All(failures) } + + fn resolve(error: Option) -> Self { + match error { + Some(_) => Self::Dial("lookup failed"), + None => Self::Dial("no addresses"), + } + } } - fn failed(addr: &str, err: &'static str) -> Failure { + fn failed(dest: &str, err: &'static str) -> Failure { Failure { - addr: v4(addr), + addr: addr(dest), error: TestError::Dial(err), } } - #[test] - fn interleave_alternates_families() { - let addrs = [ - v4("[2001:db8::1]:443"), - v4("[2001:db8::2]:443"), - v4("1.2.3.4:443"), - v4("5.6.7.8:443"), - ]; - assert_eq!( - interleave(addrs), - vec![ - v4("[2001:db8::1]:443"), - v4("1.2.3.4:443"), - v4("[2001:db8::2]:443"), - v4("5.6.7.8:443"), - ] - ); - } - - #[test] - fn interleave_keeps_the_resolver_preferred_family_first() { - // IPv4 first in the answer stays first, even though IPv6 exists. - let addrs = [v4("1.2.3.4:443"), v4("[2001:db8::1]:443")]; - assert_eq!(interleave(addrs), vec![v4("1.2.3.4:443"), v4("[2001:db8::1]:443")]); - } - - #[test] - fn interleave_single_family_passthrough() { - let addrs = [v4("1.2.3.4:443"), v4("5.6.7.8:443")]; - assert_eq!(interleave(addrs), addrs.to_vec()); - } - #[tokio::test(start_paused = true)] async fn first_success_returns_immediately() { let dials = Arc::new(AtomicUsize::new(0)); let counter = dials.clone(); - let res: Result<&str, TestError> = race(vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], DEFAULT_RACE, move |_| { - counter.fetch_add(1, Ordering::SeqCst); - async { Ok("winner") } - }) + let res: Result<&str, TestError> = race( + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), + DEFAULT_RACE, + move |_| { + counter.fetch_add(1, Ordering::SeqCst); + async { Ok("winner") } + }, + ) .await; assert_eq!(res, Ok("winner")); assert_eq!(dials.load(Ordering::SeqCst), 1, "no second dial after a fast success"); @@ -448,10 +258,10 @@ mod tests { async fn second_wins_when_first_hangs() { let start = tokio::time::Instant::now(); let res: Result<&str, TestError> = race( - vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), DEFAULT_RACE, - |addr| async move { - if addr == v4("1.1.1.1:1") { + |dest| async move { + if dest == addr("1.1.1.1:1") { std::future::pending().await } else { Ok("second") @@ -467,10 +277,10 @@ mod tests { async fn failure_starts_the_next_attempt_immediately() { let start = tokio::time::Instant::now(); let res: Result<&str, TestError> = race( - vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), DEFAULT_RACE, - |addr| async move { - if addr == v4("1.1.1.1:1") { + |dest| async move { + if dest == addr("1.1.1.1:1") { Err(TestError::Dial("boom")) } else { Ok("second") @@ -488,10 +298,10 @@ mod tests { #[tokio::test(start_paused = true)] async fn all_failures_are_reported_when_the_preferred_fails_first() { let res: Result<&str, TestError> = race( - vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), Duration::from_millis(10), - |addr| async move { - if addr == v4("1.1.1.1:1") { + |dest| async move { + if dest == addr("1.1.1.1:1") { Err(TestError::Dial("network unreachable")) } else { tokio::time::sleep(Duration::from_secs(1)).await; @@ -516,10 +326,10 @@ mod tests { #[tokio::test(start_paused = true)] async fn all_failures_are_reported_when_the_preferred_times_out_last() { let res: Result<&str, TestError> = race( - vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), Duration::from_millis(10), - |addr| async move { - if addr == v4("1.1.1.1:1") { + |dest| async move { + if dest == addr("1.1.1.1:1") { tokio::time::sleep(Duration::from_secs(30)).await; Err(TestError::Dial("timed out")) } else { @@ -541,7 +351,7 @@ mod tests { /// produced (variant, source chain and all) instead of an aggregate of one. #[tokio::test(start_paused = true)] async fn a_lone_failure_is_returned_unwrapped() { - let res: Result<&str, TestError> = race(vec![v4("1.1.1.1:1")], DEFAULT_RACE, |_| async { + let res: Result<&str, TestError> = race(Candidates::fixed([addr("1.1.1.1:1")]), DEFAULT_RACE, |_| async { Err(TestError::Dial("invalid peer certificate")) }) .await; @@ -566,19 +376,23 @@ mod tests { let dropped = Arc::new(AtomicUsize::new(0)); let count = dropped.clone(); - let res: Result<&str, TestError> = race(vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], Duration::ZERO, move |addr| { - let guard = Guard(count.clone()); - async move { - if addr == v4("1.1.1.1:1") { - let _guard = guard; - std::future::pending().await - } else { - drop(guard); - tokio::time::sleep(Duration::from_millis(1)).await; - Ok("second") + let res: Result<&str, TestError> = race( + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), + Duration::ZERO, + move |dest| { + let guard = Guard(count.clone()); + async move { + if dest == addr("1.1.1.1:1") { + let _guard = guard; + std::future::pending().await + } else { + drop(guard); + tokio::time::sleep(Duration::from_millis(1)).await; + Ok("second") + } } - } - }) + }, + ) .await; assert_eq!(res, Ok("second")); assert_eq!(dropped.load(Ordering::SeqCst), 2, "the hung attempt was not aborted"); @@ -588,10 +402,10 @@ mod tests { async fn zero_delay_dials_all_at_once() { let start = tokio::time::Instant::now(); let res: Result<&str, TestError> = race( - vec![v4("1.1.1.1:1"), v4("2.2.2.2:2")], + Candidates::fixed([addr("1.1.1.1:1"), addr("2.2.2.2:2")]), Duration::ZERO, - |addr| async move { - if addr == v4("1.1.1.1:1") { + |dest| async move { + if dest == addr("1.1.1.1:1") { std::future::pending().await } else { Ok("second") @@ -602,4 +416,64 @@ mod tests { assert_eq!(res, Ok("second")); assert_eq!(start.elapsed(), Duration::ZERO); } + + /// Nothing resolved, so there is no attempt to report and the resolution says + /// why instead. + #[tokio::test(start_paused = true)] + async fn an_empty_resolution_reports_why() { + let res: Result<&str, TestError> = race(Candidates::fixed([]), DEFAULT_RACE, |_| async { + unreachable!("dialed without an address") + }) + .await; + assert_eq!(res, Err(TestError::Dial("no addresses"))); + } + + /// The first attempt goes out on the first answer, not the last: the AAAA + /// query here is the one that never lands, which is exactly the case the + /// parallel queries exist for. + #[tokio::test(start_paused = true)] + async fn dials_the_first_address_to_resolve() { + let start = tokio::time::Instant::now(); + let res: Result<&str, TestError> = race( + Candidates::slow( + (&[], Duration::from_secs(30)), + (&[addr("1.1.1.1:1")], Duration::from_millis(100)), + ), + DEFAULT_RACE, + |_| async { Ok("winner") }, + ) + .await; + assert_eq!(res, Ok("winner")); + assert_eq!( + start.elapsed(), + Duration::from_millis(100), + "waited for the other query" + ); + } + + /// A candidate that resolves after the stagger has already elapsed starts its + /// attempt the moment it lands, rather than waiting out another stagger. + /// + /// The IPv4-only answer is here at once and hangs when dialed; the full one, + /// carrying the address that works, takes a second. + #[tokio::test(start_paused = true)] + async fn a_late_candidate_starts_as_soon_as_it_resolves() { + let start = tokio::time::Instant::now(); + let res: Result<&str, TestError> = race( + Candidates::slow( + (&[addr("[2001:db8::1]:1"), addr("1.1.1.1:1")], Duration::from_secs(1)), + (&[addr("1.1.1.1:1")], Duration::ZERO), + ), + DEFAULT_RACE, + |dest| async move { + match dest.is_ipv6() { + true => Ok("second"), + false => std::future::pending().await, + } + }, + ) + .await; + assert_eq!(res, Ok("second")); + assert_eq!(start.elapsed(), Duration::from_secs(1)); + } } diff --git a/rs/moq-native/src/lib.rs b/rs/moq-native/src/lib.rs index 4dc0ffefe92..8f6c2c89c16 100644 --- a/rs/moq-native/src/lib.rs +++ b/rs/moq-native/src/lib.rs @@ -31,6 +31,8 @@ pub mod noq; pub mod quic; #[cfg(feature = "quinn")] pub mod quinn; +#[cfg(any(feature = "quinn", feature = "noq", feature = "quiche", feature = "tcp"))] +mod resolve; mod server; #[cfg(feature = "tcp")] pub mod tcp; diff --git a/rs/moq-native/src/noq.rs b/rs/moq-native/src/noq.rs index e6bc0d7a7c2..4d832d154ba 100644 --- a/rs/moq-native/src/noq.rs +++ b/rs/moq-native/src/noq.rs @@ -222,6 +222,13 @@ impl crate::failover::Aggregate for Error { fn aggregate(failures: Vec>) -> Self { Self::Failover(failures) } + + fn resolve(error: Option) -> Self { + match error { + Some(error) => Self::DnsLookup(error), + None => Self::NoDnsEntries, + } + } } type Result = std::result::Result; @@ -238,6 +245,9 @@ pub(crate) struct NoqClient { pub host_name: Option, /// Stagger between Happy Eyeballs connection attempts (see [`crate::failover`]). pub failover_delay: Duration, + /// How long the first candidate waits for the full DNS answer, RFC 8305's + /// Resolution Delay (see [`crate::connect::Config::resolution_delay`]). + pub resolution_delay: Duration, /// Whether the bound socket really came back dual-stack, which decides /// whether an IPv4 destination is reachable at all. Captured here because the /// endpoint owns the socket from here on and `local_addr` can't tell us. @@ -268,6 +278,7 @@ impl NoqClient { http_bootstrap: config.tls.allows_http_bootstrap(), host_name: config.tls.host_name.clone(), failover_delay: config.resolved_race(), + resolution_delay: config.resolved_resolution_delay(), dual_stack, }) } @@ -281,20 +292,16 @@ impl NoqClient { let mut url = url; let mut config = tls.clone(); - let host = url.host().ok_or(Error::InvalidDnsName)?.to_string(); + let target = url.host().ok_or(Error::InvalidDnsName)?; + let host = target.to_string(); let port = url.port().unwrap_or(443); - // Resolve every DNS entry, adapted to the local socket's family; the dial - // below races them Happy Eyeballs style so one broken family can't stall - // the connect. + // Resolve, adapted to the local socket's family; the dial below races the + // answers Happy Eyeballs style as they land, so neither a broken family nor a + // lookup still waiting on its AAAA record can stall the connect. let local = self.quic.local_addr().map_err(Error::LocalAddr)?; - let addrs = tokio::net::lookup_host((host.clone(), port)) - .await - .map_err(Error::DnsLookup)?; - let candidates = crate::failover::match_local(addrs, local, self.dual_stack); - if candidates.is_empty() { - return Err(Error::NoDnsEntries); - } + let candidates = + crate::resolve::Candidates::resolve(target, port, self.resolution_delay).with_local(local, self.dual_stack); if url.scheme() == "http" { // Insecure per-connection bootstrap: only honored when no stronger @@ -342,7 +349,7 @@ impl NoqClient { let mut config = noq::ClientConfig::new(Arc::new(config)); config.transport_config(self.transport.clone()); - tracing::debug!(peer = %crate::connect::Endpoint(&url), ?candidates, "connecting"); + tracing::debug!(peer = %crate::connect::Endpoint(&url), "connecting"); // Use the configured host_name override for SNI + cert verification, else the URL host. let host_name = self.host_name.clone().unwrap_or(host); diff --git a/rs/moq-native/src/quiche.rs b/rs/moq-native/src/quiche.rs index 69399f4ba7b..c77eac7f3e6 100644 --- a/rs/moq-native/src/quiche.rs +++ b/rs/moq-native/src/quiche.rs @@ -158,6 +158,13 @@ impl crate::failover::Aggregate for Error { fn aggregate(failures: Vec>) -> Self { Self::Failover(failures) } + + fn resolve(error: Option) -> Self { + match error { + Some(error) => Self::DnsLookup(error), + None => Self::NoDnsEntries, + } + } } type Result = std::result::Result; @@ -208,6 +215,9 @@ pub(crate) struct QuicheClient { pub host_name: Option, /// Stagger between Happy Eyeballs connection attempts (see [`crate::failover`]). pub failover_delay: std::time::Duration, + /// How long the first candidate waits for the full DNS answer, RFC 8305's + /// Resolution Delay (see [`crate::connect::Config::resolution_delay`]). + pub resolution_delay: std::time::Duration, identity: Option>, } @@ -245,6 +255,7 @@ impl QuicheClient { quic, host_name: config.tls.host_name.clone(), failover_delay: config.resolved_race(), + resolution_delay: config.resolved_resolution_delay(), identity, }) } @@ -313,16 +324,12 @@ impl QuicheClient { let local = socket.local_addr()?; let dual_stack = crate::bind::udp_is_dual_stack(&socket); - // Resolve every DNS entry, adapted to the bound socket's reachability; the dial - // below races them Happy Eyeballs style so one broken family can't stall - // the connect. - let addrs = tokio::net::lookup_host((host.as_str(), port)) - .await - .map_err(Error::DnsLookup)?; - let mut candidates = crate::failover::match_local(addrs, local, dual_stack); - if candidates.is_empty() { - return Err(Error::NoDnsEntries); - } + // Resolve, adapted to the bound socket's reachability; the dial below races + // the answers Happy Eyeballs style as they land, so neither a broken family + // nor a lookup still waiting on its AAAA record can stall the connect. + let target = url.host().ok_or(Error::InvalidDnsName)?; + let mut candidates = + crate::resolve::Candidates::resolve(target, port, self.resolution_delay).with_local(local, dual_stack); // Each attempt binds its own socket, and a pinned non-zero source port only // fits one socket at a time: an overlapping attempt would fail its bind with @@ -331,10 +338,10 @@ impl QuicheClient { // other's packets), so keep the preferred candidate only, the same single // dial as before failover existed. `new` warns about this once. if self.bind.port() != 0 { - candidates.truncate(1); + candidates = candidates.with_limit(1); } - tracing::debug!(peer = %crate::connect::Endpoint(&url), ?candidates, "connecting via quiche"); + tracing::debug!(peer = %crate::connect::Endpoint(&url), "connecting via quiche"); // Race only the QUIC handshake: the winner alone performs the WebTransport // CONNECT below, so the server sees a single request no matter how many diff --git a/rs/moq-native/src/quinn.rs b/rs/moq-native/src/quinn.rs index 43091ac6cac..22bccb6e7c1 100644 --- a/rs/moq-native/src/quinn.rs +++ b/rs/moq-native/src/quinn.rs @@ -235,6 +235,13 @@ impl crate::failover::Aggregate for Error { fn aggregate(failures: Vec>) -> Self { Self::Failover(failures) } + + fn resolve(error: Option) -> Self { + match error { + Some(error) => Self::DnsLookup(error), + None => Self::NoDnsEntries, + } + } } type Result = std::result::Result; @@ -251,6 +258,9 @@ pub(crate) struct QuinnClient { pub host_name: Option, /// Stagger between Happy Eyeballs connection attempts (see [`crate::failover`]). pub failover_delay: Duration, + /// How long the first candidate waits for the full DNS answer, RFC 8305's + /// Resolution Delay (see [`crate::connect::Config::resolution_delay`]). + pub resolution_delay: Duration, /// Whether the bound socket really came back dual-stack, which decides /// whether an IPv4 destination is reachable at all. Captured here because the /// endpoint owns the socket from here on and `local_addr` can't tell us. @@ -281,6 +291,7 @@ impl QuinnClient { http_bootstrap: config.tls.allows_http_bootstrap(), host_name: config.tls.host_name.clone(), failover_delay: config.resolved_race(), + resolution_delay: config.resolved_resolution_delay(), dual_stack, }) } @@ -294,20 +305,16 @@ impl QuinnClient { let mut url = url; let mut config = tls.clone(); - let host = url.host().ok_or(Error::InvalidDnsName)?.to_string(); + let target = url.host().ok_or(Error::InvalidDnsName)?; + let host = target.to_string(); let port = url.port().unwrap_or(443); - // Resolve every DNS entry, adapted to the local socket's family; the dial - // below races them Happy Eyeballs style so one broken family can't stall - // the connect. + // Resolve, adapted to the local socket's family; the dial below races the + // answers Happy Eyeballs style as they land, so neither a broken family nor a + // lookup still waiting on its AAAA record can stall the connect. let local = self.quic.local_addr().map_err(Error::LocalAddr)?; - let addrs = tokio::net::lookup_host((host.clone(), port)) - .await - .map_err(Error::DnsLookup)?; - let candidates = crate::failover::match_local(addrs, local, self.dual_stack); - if candidates.is_empty() { - return Err(Error::NoDnsEntries); - } + let candidates = + crate::resolve::Candidates::resolve(target, port, self.resolution_delay).with_local(local, self.dual_stack); if url.scheme() == "http" { // Insecure per-connection bootstrap: only honored when no stronger @@ -355,7 +362,7 @@ impl QuinnClient { let mut config = quinn::ClientConfig::new(Arc::new(config)); config.transport_config(self.transport.clone()); - tracing::debug!(peer = %crate::connect::Endpoint(&url), ?candidates, "connecting"); + tracing::debug!(peer = %crate::connect::Endpoint(&url), "connecting"); // Use the configured host_name override for SNI + cert verification, else the URL host. let host_name = self.host_name.clone().unwrap_or(host); diff --git a/rs/moq-native/src/resolve.rs b/rs/moq-native/src/resolve.rs new file mode 100644 index 00000000000..1b3e87919cf --- /dev/null +++ b/rs/moq-native/src/resolve.rs @@ -0,0 +1,914 @@ +//! DNS-phase Happy Eyeballs (RFC 8305 section 3) for client dials. +//! +//! A dial runs two lookups at once: the full one every other program does, which +//! doesn't answer until both the A and AAAA records are in, and an IPv4-only one +//! that answers without waiting for AAAA. The full answer is authoritative and +//! normally arrives first or close enough, so the addresses and their order are +//! exactly what the platform would have handed us. When the AAAA record is slow +//! or silently dropped, which is the case Happy Eyeballs exists for, the +//! IPv4-only answer takes over after the Resolution Delay rather than the dial +//! waiting out the resolver's timeout. +//! +//! Both go through the system resolver, so `/etc/hosts`, nsswitch (mDNS and +//! friends), search domains and split-DNS resolve the way they do for everything +//! else on the host. Keeping the full lookup is what preserves the *cross-family* +//! half of that: its order is RFC 6724 destination selection, which knows things +//! this layer can't, like whether there is a usable IPv6 source address at all +//! and what `gai.conf` prefers. Each call blocks its thread, so they run on the +//! blocking pool. +//! +//! The one type callers see is [`Candidates`]: build it, hand it to the race, +//! and it yields addresses in the order to dial them. + +use std::collections::{HashSet, VecDeque}; +use std::io; +use std::net::{IpAddr, SocketAddr}; +use std::time::Duration; + +use futures::FutureExt; + +use crate::connect::DEFAULT_RESOLUTION_DELAY; + +/// Which of the two lookups a query is. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Lookup { + /// Every family, in the platform's own order. Authoritative, but it answers + /// only once both records are in. + Full, + + /// IPv4 only, which answers without waiting for the AAAA record. + Ipv4, +} + +impl Lookup { + /// The `getaddrinfo` hints for this lookup. + fn hints(self) -> dns_lookup::AddrInfoHints { + dns_lookup::AddrInfoHints { + address: match self { + // Zero is `AF_UNSPEC`: whatever the host has. + Self::Full => 0, + Self::Ipv4 => dns_lookup::AddrFamily::Inet.into(), + }, + // One entry per address rather than one per socket type: a UDP and a TCP + // entry for the same address are the same candidate to us. + socktype: dns_lookup::SockType::Stream.into(), + ..Default::default() + } + } +} + +/// Which family an address belongs to, which is what decides dial order once the +/// addresses are in hand. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Family { + V6, + V4, +} + +impl Family { + /// The family an address belongs to. + fn of(addr: SocketAddr) -> Self { + match addr.is_ipv4() { + true => Self::V4, + false => Self::V6, + } + } + + /// The other one. + fn other(self) -> Self { + match self { + Self::V6 => Self::V4, + Self::V4 => Self::V6, + } + } +} + +/// One lookup, in flight until it answers. +#[derive(Default)] +struct Query { + /// The `getaddrinfo` call, dropped once it answers. + call: Option>>>, + + /// Why it answered with nothing. + error: Option, +} + +impl Query { + /// Start a lookup on the blocking pool. + fn start(host: &str, port: u16, lookup: Lookup) -> Self { + let host = host.to_owned(); + let call = tokio::task::spawn_blocking(move || resolve(&host, port, lookup)); + + Self { + call: Some(call), + ..Default::default() + } + } + + /// Whether this lookup still owes an answer. + fn pending(&self) -> bool { + self.call.is_some() + } + + /// Wait for the answer, recording a failure as no addresses. + /// + /// Never resolves once there is no call left, so it can sit in a `select!` arm + /// without spinning. Cancelling it loses nothing: the handle stays put and the + /// answer is taken the next time it is awaited. + async fn answer(&mut self, lookup: Lookup) -> Vec { + let Some(call) = self.call.as_mut() else { + return std::future::pending().await; + }; + + let res = call.await; + self.record(lookup, res) + } + + /// The answer if it has already landed, without waiting for one. + /// + /// Polling with a no-op waker drops nothing: every caller follows up with + /// [`answer`](Self::answer), which registers a real one. + fn ready(&mut self, lookup: Lookup) -> Option> { + let res = self.call.as_mut()?.now_or_never()?; + Some(self.record(lookup, res)) + } + + /// Record what the call returned, closing it out. + fn record( + &mut self, + lookup: Lookup, + res: Result>, tokio::task::JoinError>, + ) -> Vec { + // The only `JoinError` reachable here is a panic in the lookup itself: the + // handle is never aborted while it is still in `self`. + let res = res.unwrap_or_else(|err| Err(io::Error::other(err))); + self.call = None; + + match res { + Ok(addrs) => { + tracing::debug!(?lookup, count = addrs.len(), "resolved"); + addrs + } + // Not a warning: the IPv4-only lookup coming back empty is the normal + // state of every host that has only a AAAA record. It matters only when + // nothing resolves at all, and then it is in the returned error. + Err(err) => { + tracing::debug!(?lookup, %err, "lookup failed"); + self.error = Some(err); + Vec::new() + } + } + } +} + +/// The addresses a dial should try, in the order to try them. +/// +/// The families alternate, so attempt N+1 is always the other family from attempt +/// N while both have an address left. Which family leads is the platform's call, +/// not ours. Addresses arrive as their lookup answers, so a dial can start before +/// the full one is done. +pub(crate) struct Candidates { + /// The all-families lookup. + full: Query, + + /// The IPv4-only lookup. + ipv4: Query, + + /// Addresses waiting to be dialed, split by family so attempts can alternate. + /// Order within a family is the resolver's own. + v6: VecDeque, + v4: VecDeque, + + /// The family the next candidate should come from. + next: Family, + + /// How long the first candidate waits for the full answer, and whether that + /// wait has already happened. + delay: Duration, + delayed: bool, + + /// The local socket candidates are adapted to, and whether it is dual-stack. + local: Option<(SocketAddr, bool)>, + + /// Candidates the local socket can't reach, kept as a last resort. + unreachable: VecDeque, + + /// Every address handed out, so the two lookups can't dial one twice. + seen: HashSet, + + /// Whether the local socket could reach any candidate, which decides whether + /// the `unreachable` ones are worth dialing at all. + usable: bool, + + /// How many candidates have been handed out, against `limit`. + count: usize, + limit: usize, +} + +impl Default for Candidates { + fn default() -> Self { + Self { + full: Query::default(), + ipv4: Query::default(), + v6: VecDeque::new(), + v4: VecDeque::new(), + // Only until an answer says otherwise. RFC 8305 section 4: absent a + // preference, IPv6 goes first. + next: Family::V6, + delay: DEFAULT_RESOLUTION_DELAY, + delayed: false, + local: None, + unreachable: VecDeque::new(), + seen: HashSet::new(), + usable: false, + count: 0, + limit: usize::MAX, + } + } +} + +impl Candidates { + /// Resolve `host`, running the full lookup and an IPv4-only one at once. + /// + /// Both start here rather than on the first [`next`](Self::next), so they + /// overlap whatever else the dial does first. + /// + /// `delay` is how long the first candidate holds back an IPv4 address while the + /// full answer is still outstanding. + pub(crate) fn resolve(host: url::Host<&str>, port: u16, delay: Duration) -> Self { + let domain = match host { + // A literal needs no resolver, and handing one to `getaddrinfo` just + // gets it back. + url::Host::Ipv4(ip) => return Self::fixed([SocketAddr::new(ip.into(), port)]), + url::Host::Ipv6(ip) => return Self::fixed([SocketAddr::new(ip.into(), port)]), + // A non-special scheme (`moqt://192.0.2.1`) parses its host as a domain, + // so the literal check can't be left to the URL parser. + url::Host::Domain(domain) => match domain.parse::() { + Ok(ip) => return Self::fixed([SocketAddr::new(ip, port)]), + Err(_) => domain, + }, + }; + + Self { + full: Query::start(domain, port, Lookup::Full), + ipv4: Query::start(domain, port, Lookup::Ipv4), + delay, + ..Default::default() + } + } + + /// The addresses to dial when they are already known, in the caller's order. + /// + /// The families still alternate, but the first address keeps its position, so a + /// caller that has already chosen a preferred family keeps it. + pub(crate) fn fixed(addrs: impl IntoIterator) -> Self { + let mut this = Self::default(); + + for addr in addrs { + if this.v6.is_empty() && this.v4.is_empty() { + this.next = Family::of(addr); + } + this.queue(addr); + } + + this + } + + /// Adapt each candidate to the family of the `local` socket. + /// + /// The QUIC backends send from one already-bound socket, so a candidate the + /// socket can't reach is converted when the conversion is lossless (IPv4 to + /// IPv4-mapped IPv6 for a dual-stack socket, and the reverse) and dropped when + /// it isn't. `dual_stack` is [`crate::bind::udp_is_dual_stack`] for that + /// socket. When every candidate would be dropped, the normalized candidates + /// are handed out anyway so the dial surfaces the OS error instead of a + /// confusing "no DNS entries". See + /// for the Windows failure this family matching originally fixed. + #[cfg(any(feature = "noq", feature = "quinn", feature = "quiche", test))] + pub(crate) fn with_local(mut self, local: SocketAddr, dual_stack: bool) -> Self { + self.local = Some((local, dual_stack)); + self + } + + /// Hand out at most `max` candidates. + /// + /// For a backend that can't run overlapping attempts: quiche binds a socket + /// per attempt, and a pinned source port only fits one at a time. That one + /// attempt goes to the platform's own first choice, so this must not be paired + /// with an order we invented. + #[cfg(any(feature = "quiche", test))] + pub(crate) fn with_limit(mut self, max: usize) -> Self { + self.limit = max; + self + } + + /// The next address to dial, or `None` once every answer has been handed out. + pub(crate) async fn next(&mut self) -> Option { + if self.count >= self.limit { + return None; + } + + loop { + // Fold in whatever has answered since the last candidate went out. Without + // this, a fast-lane address still sitting in the queue would be handed out + // ahead of an authoritative answer that has already landed, and the order + // the platform chose would only take effect once the fast lane ran dry. + self.poll_answers(); + + if let Some(addr) = self.take(self.next) { + return Some(addr); + } + + // The preferred family has nothing ready, so consider the other one. + if !self.queued(self.next.other()).is_empty() { + // RFC 8305 section 3: an IPv4-only answer that merely beat the full one + // doesn't get to pick the family on its own, so hold it back briefly and + // give the platform's own choice a chance to land. Only the first + // candidate waits: after that the families alternate anyway, and the + // stagger between attempts dwarfs this. + if self.count == 0 && !self.delayed && self.full.pending() { + self.delayed = true; + let _ = tokio::time::timeout(self.delay, self.answer_full()).await; + continue; + } + + if let Some(addr) = self.take(self.next.other()) { + return Some(addr); + } + continue; + } + + if !self.full.pending() && !self.ipv4.pending() { + // Nothing left to wait for. A candidate the local socket can't reach + // still beats no candidate at all, so dial those rather than report an + // empty answer we didn't get. + if !self.usable + && let Some(addr) = self.unreachable.pop_front() + { + self.count += 1; + return Some(addr); + } + + return None; + } + + self.answer_any().await; + } + } + + /// Why the dial had nothing to try, and `None` when the lookup simply answered + /// with no addresses. + /// + /// The full lookup speaks for the host: the IPv4-only one covers ground it + /// already covers, so its error only stands in when the full one had none. + /// + /// Only meaningful once [`next`](Self::next) has returned `None` without ever + /// handing out an address. Consumes the error, so it reports once. + pub(crate) fn failure(&mut self) -> Option { + self.full.error.take().or_else(|| self.ipv4.error.take()) + } + + /// Hand out the next address from `family`, skipping duplicates and setting + /// aside what the local socket can't reach. + fn take(&mut self, family: Family) -> Option { + loop { + let addr = self.queued(family).pop_front()?; + let addr = match self.local { + Some((local, _)) => normalize_family(addr, local), + None => addr, + }; + + // Duplicates cost a wasted dial and a repeated line in the error, and they + // don't arrive adjacent: the families alternate, the two lookups overlap, + // and normalizing collapses `1.2.3.4` and `::ffff:1.2.3.4` into one value + // only afterwards. So dedup by value, keeping the first occurrence's + // position. + if !self.seen.insert(addr) { + continue; + } + + if let Some((local, dual_stack)) = self.local + && !addressable(addr, local, dual_stack) + { + self.unreachable.push_back(addr); + continue; + } + + self.usable = true; + self.count += 1; + self.next = family.other(); + return Some(addr); + } + } + + /// This family's queue. + fn queued(&mut self, family: Family) -> &mut VecDeque { + match family { + Family::V6 => &mut self.v6, + Family::V4 => &mut self.v4, + } + } + + /// Queue one address behind its family. + fn queue(&mut self, addr: SocketAddr) { + self.queued(Family::of(addr)).push_back(addr); + } + + /// Fold in every answer that has already landed, without waiting for one. + fn poll_answers(&mut self) { + // Full first: accepting it closes out the IPv4-only lookup, which then has + // nothing left to fold in. + if let Some(addrs) = self.full.ready(Lookup::Full) { + self.accept(Lookup::Full, addrs); + } + + if let Some(addrs) = self.ipv4.ready(Lookup::Ipv4) { + self.accept(Lookup::Ipv4, addrs); + } + } + + /// Wait for the full lookup to answer. + async fn answer_full(&mut self) { + let addrs = self.full.answer(Lookup::Full).await; + self.accept(Lookup::Full, addrs); + } + + /// Wait for whichever lookup answers next. Hangs when neither is in flight, so + /// the caller checks first. + async fn answer_any(&mut self) { + // Split the borrow: each arm only touches its own query, and both are done + // with it before `accept` takes `self` again. + let (full, ipv4) = (&mut self.full, &mut self.ipv4); + + let (lookup, addrs) = tokio::select! { + addrs = full.answer(Lookup::Full) => (Lookup::Full, addrs), + addrs = ipv4.answer(Lookup::Ipv4) => (Lookup::Ipv4, addrs), + }; + + self.accept(lookup, addrs); + } + + /// Fold a lookup's answer into the queues. + fn accept(&mut self, lookup: Lookup, addrs: Vec) { + // An empty answer from the full lookup means it failed, so leave the + // IPv4-only one to speak for the host. + if lookup == Lookup::Ipv4 || addrs.is_empty() { + for addr in addrs { + self.queue(addr); + } + return; + } + + // The full answer supersedes the IPv4-only one: the same records, sorted by + // the platform's own destination-address selection. Anything already dialed + // is held by `seen`, so requeueing can't repeat it. The lookup still in + // flight has nothing to add, and `getaddrinfo` can't be cancelled, so its + // thread just finishes unobserved. + self.ipv4.call = None; + self.v6.clear(); + self.v4.clear(); + + // Which family leads is RFC 8305 section 4's destination-address sort, which + // the resolver has already done: a host with no usable IPv6 source address, + // or a `gai.conf` that prefers IPv4, comes back IPv4 first. Only the first + // attempt asks; after that the families alternate. + if self.count == 0 + && let Some(first) = addrs.first() + { + self.next = Family::of(*first); + } + + for addr in addrs { + self.queue(addr); + } + } +} + +/// One `getaddrinfo` call, blocking until the resolver answers. +fn resolve(host: &str, port: u16, lookup: Lookup) -> io::Result> { + // No service is passed (there is no `moq` in /etc/services); the port is + // stamped on here instead. + let answers = dns_lookup::getaddrinfo(Some(host), None, Some(lookup.hints())).map_err(io::Error::from)?; + answers.map(|answer| Ok(with_port(answer?.sockaddr, port))).collect() +} + +/// The address to dial for one answer: whatever the resolver returned, at our +/// port. +/// +/// Rebuilding it from the IP alone would drop the rest of the `sockaddr`, and an +/// IPv6 one carries a scope id that a link-local address (`fe80::1%eth0`, which +/// is what mDNS hands back on a LAN) can't be reached without. +fn with_port(mut addr: SocketAddr, port: u16) -> SocketAddr { + addr.set_port(port); + addr +} + +/// Whether a socket bound to `local` can send to `dest`. +/// +/// Mostly this is the address family, but reaching IPv4 from an IPv6 socket has +/// a wrinkle: it means sending to an IPv4-mapped destination, which the kernel +/// turns back into a real IPv4 packet, and that needs an IPv4 source address. So +/// it takes both a socket that is actually dual-stack (`IPV6_V6ONLY` cleared, +/// which [`crate::bind::udp`] only attempts) and a bind that left an IPv4 source +/// to use: `[::]` does, since the kernel picks the source, and an IPv4-mapped +/// bind already is one, but a concrete IPv6 bind is not. The mirror holds too: +/// an IPv4-mapped bind can't reach a real IPv6 destination. +fn addressable(dest: SocketAddr, local: SocketAddr, dual_stack: bool) -> bool { + let (SocketAddr::V6(dest), SocketAddr::V6(local)) = (dest, local) else { + return dest.is_ipv4() == local.is_ipv4(); + }; + + match (dest.ip().to_ipv4_mapped(), local.ip().to_ipv4_mapped()) { + (Some(_), None) => dual_stack && local.ip().is_unspecified(), + (None, Some(_)) => false, + _ => true, + } +} + +/// Convert `addr` to match the family of `local` when the conversion is +/// lossless: unwrap IPv4-mapped IPv6 to IPv4, or wrap IPv4 as IPv4-mapped IPv6. +fn normalize_family(addr: SocketAddr, local: SocketAddr) -> SocketAddr { + match (addr, local.is_ipv4()) { + (SocketAddr::V6(v6), true) => match v6.ip().to_ipv4_mapped() { + Some(v4) => SocketAddr::new(IpAddr::V4(v4), v6.port()), + None => addr, + }, + (SocketAddr::V4(v4), false) => SocketAddr::new(IpAddr::V6(v4.ip().to_ipv6_mapped()), v4.port()), + _ => addr, + } +} + +#[cfg(test)] +impl Candidates { + /// Answers that land after a delay, for tests (here and in [`crate::failover`]) + /// that need a dial to start before resolution has finished. The Resolution + /// Delay is off: these exercise the caller rather than the family preference. + pub(crate) fn slow(full: (&[SocketAddr], Duration), ipv4: (&[SocketAddr], Duration)) -> Self { + Self { + full: Query::slow(full.0, full.1), + ipv4: Query::slow(ipv4.0, ipv4.1), + delay: Duration::ZERO, + ..Default::default() + } + } +} + +#[cfg(test)] +impl Query { + /// A lookup that answers with `addrs` after `delay`. + fn slow(addrs: &[SocketAddr], delay: Duration) -> Self { + let addrs = addrs.to_vec(); + + Self { + call: Some(tokio::spawn(async move { + tokio::time::sleep(delay).await; + Ok(addrs) + })), + ..Default::default() + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn addr(s: &str) -> SocketAddr { + s.parse().unwrap() + } + + fn addrs(list: &[&str]) -> Vec { + list.iter().map(|s| addr(s)).collect() + } + + /// Every candidate, in the order they're handed out. + async fn drain(mut candidates: Candidates) -> Vec { + let mut out = Vec::new(); + while let Some(addr) = candidates.next().await { + out.push(addr); + } + out + } + + /// A dial whose full lookup has already answered, in the resolver's order. + fn answered(list: &[&str]) -> Candidates { + let mut candidates = Candidates::default(); + candidates.accept(Lookup::Full, addrs(list)); + candidates + } + + #[tokio::test] + async fn alternates_families() { + let candidates = answered(&["[2001:db8::1]:443", "[2001:db8::2]:443", "1.2.3.4:443", "5.6.7.8:443"]); + assert_eq!( + drain(candidates).await, + addrs(&["[2001:db8::1]:443", "1.2.3.4:443", "[2001:db8::2]:443", "5.6.7.8:443",]) + ); + } + + /// The resolver sorts across families (RFC 6724 destination selection), and + /// that choice is not ours to second-guess: a host with no usable IPv6 source + /// address, or a `gai.conf` preferring IPv4, answers IPv4 first and has to be + /// dialed IPv4 first. + #[tokio::test] + async fn the_resolver_picks_the_leading_family() { + let candidates = answered(&["1.2.3.4:443", "[2001:db8::1]:443"]); + assert_eq!(drain(candidates).await, addrs(&["1.2.3.4:443", "[2001:db8::1]:443"])); + + let candidates = answered(&["[2001:db8::1]:443", "1.2.3.4:443"]); + assert_eq!(drain(candidates).await, addrs(&["[2001:db8::1]:443", "1.2.3.4:443"])); + } + + /// quiche pins its source port and so gets one attempt only. It has to be the + /// address the platform put first, or an IPv4-only host loses its only shot. + #[tokio::test] + async fn a_single_attempt_follows_the_resolver() { + let candidates = answered(&["1.2.3.4:443", "[2001:db8::1]:443"]).with_limit(1); + assert_eq!(drain(candidates).await, addrs(&["1.2.3.4:443"])); + } + + #[tokio::test] + async fn single_family_passthrough() { + let list = ["1.2.3.4:443", "5.6.7.8:443"]; + assert_eq!(drain(answered(&list)).await, addrs(&list)); + } + + #[tokio::test] + async fn fixed_keeps_the_leading_family() { + // A caller that already ordered its addresses keeps the family it chose. + let list = addrs(&["1.2.3.4:443", "[2001:db8::1]:443"]); + assert_eq!(drain(Candidates::fixed(list.clone())).await, list); + } + + #[tokio::test] + async fn local_prefers_matching_family() { + // IPv6 answered first, but the local socket is IPv4: only IPv4 is usable. + let candidates = answered(&["[::1]:443", "127.0.0.1:443"]).with_local(addr("0.0.0.0:0"), false); + assert_eq!(drain(candidates).await, addrs(&["127.0.0.1:443"])); + + // IPv4 wraps to IPv4-mapped for an IPv6 (dual-stack) socket. + let candidates = answered(&["[::1]:443", "127.0.0.1:443"]).with_local(addr("[::]:0"), true); + assert_eq!(drain(candidates).await, addrs(&["[::1]:443", "[::ffff:127.0.0.1]:443"])); + } + + #[tokio::test] + async fn local_skips_mapped_ipv4_on_a_v6_only_socket() { + let candidates = answered(&["[2001:db8::1]:443", "192.0.2.1:443"]).with_local(addr("[::]:0"), false); + assert_eq!(drain(candidates).await, addrs(&["[2001:db8::1]:443"])); + } + + #[tokio::test] + async fn local_skips_ipv4_for_a_concrete_v6_bind() { + let candidates = answered(&["[2001:db8::1]:443", "192.0.2.1:443"]).with_local(addr("[2001:db8::5]:0"), true); + assert_eq!(drain(candidates).await, addrs(&["[2001:db8::1]:443"])); + } + + #[tokio::test] + async fn local_keeps_the_normalized_fallback_when_none_are_usable() { + let candidates = answered(&["192.0.2.1:443"]).with_local(addr("[::]:0"), false); + assert_eq!(drain(candidates).await, addrs(&["[::ffff:192.0.2.1]:443"])); + } + + #[tokio::test] + async fn local_unwraps_v4_mapped_for_a_v4_socket() { + let candidates = answered(&["[::ffff:127.0.0.1]:443"]).with_local(addr("0.0.0.0:0"), false); + assert_eq!(drain(candidates).await, addrs(&["127.0.0.1:443"])); + } + + #[tokio::test] + async fn local_falls_back_for_an_unmappable_v6() { + // IPv4 socket with only a true IPv6 entry: no conversion possible, keep it + // so the OS surfaces a clear error. + let candidates = answered(&["[2001:db8::1]:443"]).with_local(addr("0.0.0.0:0"), false); + assert_eq!(drain(candidates).await, addrs(&["[2001:db8::1]:443"])); + } + + #[tokio::test] + async fn empty_yields_nothing() { + assert!(drain(Candidates::fixed([])).await.is_empty()); + assert!(Candidates::fixed([]).failure().is_none()); + } + + #[tokio::test] + async fn dedups_the_answer() { + let candidates = answered(&["[2001:db8::1]:443", "1.2.3.4:443", "1.2.3.4:443"]); + assert_eq!(drain(candidates).await, addrs(&["[2001:db8::1]:443", "1.2.3.4:443"])); + } + + #[tokio::test] + async fn dedups_normalized_forms() { + // The same address twice, once already IPv4-mapped: two families going in, + // one candidate coming out. + let candidates = answered(&["[::ffff:1.2.3.4]:443", "1.2.3.4:443"]).with_local(addr("[::]:0"), true); + assert_eq!(drain(candidates).await, addrs(&["[::ffff:1.2.3.4]:443"])); + + let candidates = answered(&["[::ffff:1.2.3.4]:443", "1.2.3.4:443"]).with_local(addr("0.0.0.0:0"), false); + assert_eq!(drain(candidates).await, addrs(&["1.2.3.4:443"])); + } + + /// An IP literal is dialed as-is. `https` parses one into `Host::Ipv4`, while + /// a non-special scheme like `moqt` hands back a `Host::Domain` that happens + /// to be numeric; both have to skip the resolver. + #[tokio::test] + async fn ip_literals_skip_the_resolver() { + let cases = [ + ("https://192.0.2.1", "192.0.2.1:443"), + ("moqt://192.0.2.1", "192.0.2.1:443"), + ("https://[2001:db8::1]", "[2001:db8::1]:443"), + ("moqt://[2001:db8::1]", "[2001:db8::1]:443"), + ]; + + for (url, want) in cases { + let url = url::Url::parse(url).unwrap(); + let candidates = Candidates::resolve(url.host().unwrap(), 443, DEFAULT_RESOLUTION_DELAY); + assert_eq!(drain(candidates).await, vec![addr(want)], "{url}"); + } + } + + /// The IPv4-only answer landing first must not pick the family on its own: the + /// dial waits out the Resolution Delay to see what the platform says. + #[tokio::test(start_paused = true)] + async fn ipv4_waits_out_the_resolution_delay_for_the_full_answer() { + let mut candidates = Candidates::slow( + ( + &addrs(&["[2001:db8::1]:443", "1.2.3.4:443"]), + DEFAULT_RESOLUTION_DELAY / 2, + ), + (&addrs(&["1.2.3.4:443"]), Duration::ZERO), + ); + candidates.delay = DEFAULT_RESOLUTION_DELAY; + + let start = tokio::time::Instant::now(); + assert_eq!(candidates.next().await, Some(addr("[2001:db8::1]:443"))); + assert_eq!( + start.elapsed(), + DEFAULT_RESOLUTION_DELAY / 2, + "waited longer than the answer took" + ); + assert_eq!(candidates.next().await, Some(addr("1.2.3.4:443"))); + } + + /// The same wait, but the full answer never lands: the IPv4-only one takes + /// over once the Resolution Delay is up rather than waiting out the resolver. + #[tokio::test(start_paused = true)] + async fn ipv4_proceeds_once_the_resolution_delay_expires() { + let mut candidates = Candidates::slow( + (&[], Duration::from_secs(30)), + (&addrs(&["1.2.3.4:443"]), Duration::ZERO), + ); + candidates.delay = DEFAULT_RESOLUTION_DELAY; + + let start = tokio::time::Instant::now(); + assert_eq!(candidates.next().await, Some(addr("1.2.3.4:443"))); + assert_eq!(start.elapsed(), DEFAULT_RESOLUTION_DELAY); + } + + /// A failed full lookup is an answer: there is nothing to hold the IPv4 + /// address back for, so it goes immediately. + #[tokio::test(start_paused = true)] + async fn ipv4_does_not_wait_for_a_failed_full_lookup() { + let mut candidates = Candidates::slow((&[], Duration::ZERO), (&addrs(&["1.2.3.4:443"]), Duration::ZERO)); + candidates.delay = DEFAULT_RESOLUTION_DELAY; + candidates.full.call = Some(tokio::spawn(async { Err(io::Error::other("nope")) })); + + let start = tokio::time::Instant::now(); + assert_eq!(candidates.next().await, Some(addr("1.2.3.4:443"))); + assert_eq!(start.elapsed(), Duration::ZERO); + } + + /// Only the first candidate waits: once a dial is under way the families + /// alternate on whatever has landed. + #[tokio::test(start_paused = true)] + async fn only_the_first_candidate_waits() { + let mut candidates = Candidates::slow( + (&[], Duration::from_secs(30)), + (&addrs(&["1.2.3.4:443", "5.6.7.8:443"]), Duration::ZERO), + ); + candidates.delay = DEFAULT_RESOLUTION_DELAY; + + assert_eq!(candidates.next().await, Some(addr("1.2.3.4:443"))); + + let start = tokio::time::Instant::now(); + assert_eq!(candidates.next().await, Some(addr("5.6.7.8:443"))); + assert_eq!(start.elapsed(), Duration::ZERO); + } + + /// A full answer arriving late still contributes what the IPv4-only one + /// couldn't, without repeating what it already handed out. + /// + /// The IPv4 addresses go out before it lands rather than waiting for it: the + /// caller only asks for a candidate when it wants to dial one, so holding one + /// back to keep the families alternating would idle a dial against a resolver + /// that may never answer. + #[tokio::test(start_paused = true)] + async fn the_full_answer_supersedes_the_ipv4_one() { + let mut candidates = Candidates::slow( + ( + &addrs(&["1.2.3.4:443", "[2001:db8::1]:443", "5.6.7.8:443"]), + Duration::from_secs(1), + ), + (&addrs(&["1.2.3.4:443", "5.6.7.8:443"]), Duration::ZERO), + ); + + assert_eq!(candidates.next().await, Some(addr("1.2.3.4:443"))); + assert_eq!(candidates.next().await, Some(addr("5.6.7.8:443"))); + + let start = tokio::time::Instant::now(); + assert_eq!(candidates.next().await, Some(addr("[2001:db8::1]:443"))); + assert_eq!(start.elapsed(), Duration::from_secs(1), "waited on the full answer"); + assert_eq!(candidates.next().await, None, "an address was dialed twice"); + } + + /// The full answer supersedes fast-lane addresses that are still queued, not + /// just the ones after them. + /// + /// A queued IPv4 address must not jump ahead of the one the platform put + /// first once that answer has landed: with a broken IPv4 path, every one of + /// them would burn a stagger before the IPv6 address sitting right there got + /// its turn. + #[tokio::test(start_paused = true)] + async fn a_queued_address_yields_to_the_full_answer() { + let mut candidates = Candidates::slow( + ( + &addrs(&["[2001:db8::1]:443", "1.2.3.4:443", "5.6.7.8:443"]), + Duration::from_millis(10), + ), + (&addrs(&["1.2.3.4:443", "5.6.7.8:443"]), Duration::ZERO), + ); + + // The fast lane is all there is to go on at first. + assert_eq!(candidates.next().await, Some(addr("1.2.3.4:443"))); + + // That dial is in flight when the full answer lands, so the next candidate + // comes from the platform's order rather than the fast lane's leftovers. + tokio::time::sleep(Duration::from_millis(20)).await; + assert_eq!(candidates.next().await, Some(addr("[2001:db8::1]:443"))); + assert_eq!(candidates.next().await, Some(addr("5.6.7.8:443"))); + assert_eq!(candidates.next().await, None); + } + + /// A dial that resolves nothing reports why, and reports it once. + #[tokio::test] + async fn failure_reports_the_lookup_error() { + let mut candidates = Candidates::default(); + candidates.full.error = Some(io::Error::other("no such host")); + candidates.ipv4.error = Some(io::Error::other("no A record")); + + // The full lookup speaks for the host; the IPv4-only one only stands in when + // it had nothing to say. + let err = candidates.failure().expect("no failure reported"); + assert_eq!(err.to_string(), "no such host"); + assert_eq!( + candidates.failure().map(|err| err.to_string()).as_deref(), + Some("no A record") + ); + assert!(candidates.failure().is_none()); + } + + /// A link-local answer is only routable with the scope id the resolver + /// attached to it, so stamping our port on must not rebuild the address. + #[test] + fn the_port_is_stamped_without_losing_the_scope() { + use std::net::{Ipv6Addr, SocketAddrV6}; + + let answer = SocketAddrV6::new("fe80::1".parse::().unwrap(), 0, 7, 3); + let dialed = with_port(SocketAddr::V6(answer), 443); + + let SocketAddr::V6(dialed) = dialed else { + panic!("family changed: {dialed}"); + }; + assert_eq!(dialed.port(), 443); + assert_eq!(dialed.scope_id(), 3, "dropped the interface scope"); + assert_eq!(dialed.flowinfo(), 7); + } + + /// The end-to-end path through the real resolver: localhost is in + /// `/etc/hosts` on every platform, so this exercises `getaddrinfo` without + /// needing a network. + #[tokio::test] + async fn resolves_localhost() { + let url = url::Url::parse("https://localhost").unwrap(); + let candidates = Candidates::resolve(url.host().unwrap(), 443, DEFAULT_RESOLUTION_DELAY); + let addrs = drain(candidates).await; + + assert!(!addrs.is_empty(), "localhost resolved to nothing"); + assert!(addrs.iter().all(|addr| addr.ip().is_loopback() && addr.port() == 443)); + } + + /// A host the resolver rejects reports its error rather than an empty answer. + /// + /// The name carries a NUL so both lookups fail without touching the network: + /// an unresolvable name would do as well, but only on a resolver that answers + /// NXDOMAIN rather than hijacking it. + #[tokio::test] + async fn a_rejected_host_reports_a_failure() { + let mut candidates = Candidates { + full: Query::start("no\0such\0host", 443, Lookup::Full), + ipv4: Query::start("no\0such\0host", 443, Lookup::Ipv4), + ..Default::default() + }; + + assert_eq!(candidates.next().await, None); + assert!(candidates.failure().is_some()); + } +} diff --git a/rs/moq-native/src/server.rs b/rs/moq-native/src/server.rs index 53dc62dd2b8..585946a851d 100644 --- a/rs/moq-native/src/server.rs +++ b/rs/moq-native/src/server.rs @@ -253,8 +253,23 @@ impl Server { self.with_subscriber(origin).serve().await } - /// Shared accept loop for [`serve_publish`](Self::serve_publish) / - /// [`serve_consume`](Self::serve_consume); the origin is already attached. + /// Accept sessions until the listener stops, serving `publish` to each subscriber + /// and ingesting each publisher into `subscribe`. + /// + /// The both-directions counterpart of [`serve_publish`](Self::serve_publish) and + /// [`serve_consume`](Self::serve_consume), so an inbound session can subscribe to + /// the origin and publish into it over one connection. + pub async fn serve_both( + self, + publish: moq_net::origin::Consumer, + subscribe: moq_net::origin::Producer, + ) -> crate::Result<()> { + self.with_publisher(publish).with_subscriber(subscribe).serve().await + } + + /// Shared accept loop for the `serve_*` entry points; the origin is already + /// attached. Private so a server can't be served with no direction at all, which + /// would accept and handshake sessions that carry nothing. async fn serve(self) -> crate::Result<()> { let mut listener = self.listen().await?; if let Ok(addr) = listener.local_addr() { diff --git a/rs/moq-native/src/tcp.rs b/rs/moq-native/src/tcp.rs index fad7634b28c..55e168a2716 100644 --- a/rs/moq-native/src/tcp.rs +++ b/rs/moq-native/src/tcp.rs @@ -74,8 +74,9 @@ impl Config { #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { - /// The TCP socket failed to bind or connect. Not accept: a failed `accept(2)` is - /// the listener's own to classify and retry (see [`crate::accept`]). + /// The TCP socket failed to bind or connect, or the host failed to resolve. Not + /// accept: a failed `accept(2)` is the listener's own to classify and retry + /// (see [`crate::accept`]). #[error(transparent)] Io(#[from] std::io::Error), @@ -112,6 +113,13 @@ impl crate::failover::Aggregate for Error { fn aggregate(failures: Vec>) -> Self { Self::Failover(failures) } + + fn resolve(error: Option) -> Self { + match error { + Some(error) => Self::Io(error), + None => Self::NoAddresses, + } + } } type Result = std::result::Result; @@ -119,34 +127,32 @@ type Result = std::result::Result; /// Dial a `tcp://host:port` URL, advertising `protocols` for in-band ALPN /// negotiation. Returns a qmux session over plain TCP. /// -/// When DNS returns multiple addresses they are raced Happy Eyeballs style, -/// staggered by `failover_delay` (see [`crate::failover`]). +/// The host is resolved alongside an IPv4-only lookup that answers without +/// waiting for its AAAA record, `resolution_delay` apart, and the answers raced +/// Happy Eyeballs style, staggered by `failover_delay` (see [`crate::failover`]). /// /// The port is required; there is no default for the `tcp` scheme. pub(crate) async fn connect( url: Url, protocols: &[&str], failover_delay: std::time::Duration, + resolution_delay: std::time::Duration, ) -> Result { - let host = url.host_str().ok_or(Error::MissingHostname)?; + let host = url.host().ok_or(Error::MissingHostname)?; let port = url.port().ok_or(Error::MissingPort)?; tracing::debug!(peer = %crate::connect::Endpoint(&url), "connecting via TCP"); - let addrs = tokio::net::lookup_host((host, port)).await?; - connect_addrs(crate::failover::interleave(addrs), protocols, failover_delay).await + let candidates = crate::resolve::Candidates::resolve(host, port, resolution_delay); + connect_addrs(candidates, protocols, failover_delay).await } -/// Dial the already-resolved `candidates` in Happy Eyeballs order, performing the -/// qmux handshake on each attempt; the first session to complete wins. +/// Dial `candidates` in Happy Eyeballs order, performing the qmux handshake on +/// each attempt; the first session to complete wins. async fn connect_addrs( - candidates: Vec, + candidates: crate::resolve::Candidates, protocols: &[&str], failover_delay: std::time::Duration, ) -> Result { - if candidates.is_empty() { - return Err(Error::NoAddresses); - } - crate::failover::race(candidates, failover_delay, |addr| { let protocols: Vec = protocols.iter().map(|&p| p.to_owned()).collect(); async move { @@ -269,9 +275,10 @@ mod tests { let accept = tokio::spawn(async move { listener.accept().await.expect("listener gone").expect("accept") }); let blackhole: net::SocketAddr = "192.0.2.1:9".parse().unwrap(); + let candidates = crate::resolve::Candidates::fixed([blackhole, addr]); let session = tokio::time::timeout( Duration::from_secs(5), - connect_addrs(vec![blackhole, addr], &["moq-test"], Duration::from_millis(50)), + connect_addrs(candidates, &["moq-test"], Duration::from_millis(50)), ) .await .expect("failover timed out") @@ -283,7 +290,8 @@ mod tests { #[tokio::test] async fn connect_addrs_rejects_empty() { - let res = connect_addrs(Vec::new(), &["moq-test"], Duration::ZERO).await; + let candidates = crate::resolve::Candidates::fixed([]); + let res = connect_addrs(candidates, &["moq-test"], Duration::ZERO).await; assert!(matches!(res, Err(Error::NoAddresses))); } } diff --git a/rs/moq-native/tests/broadcast.rs b/rs/moq-native/tests/broadcast.rs index d26651c91fe..58351026cad 100644 --- a/rs/moq-native/tests/broadcast.rs +++ b/rs/moq-native/tests/broadcast.rs @@ -715,6 +715,10 @@ async fn read_payloads(sub: &mut moq_net::track::Subscriber, count: usize) -> Ve /// preferred route (shorter hop chain) serves the track; when that session dies, /// the same `track::Subscriber` keeps receiving groups from the standby session. /// No unannounce is observed and nothing is resubscribed by the application. +/// +/// The subscription is live-edge (`group_start: None`), and that means the same +/// thing on the standby as it did on the first route: tune in at the latest +/// group. The standby's older cached groups are not replayed. #[tracing_test::traced_test] #[tokio::test] async fn broadcast_route_migration() { @@ -758,6 +762,8 @@ async fn broadcast_route_migration() { ) .expect("create broadcast"); let mut track_b = broadcast_b.create_track("video", None).expect("create track"); + // A clone to keep producing from the test body once the task owns the rest. + let mut standby_track = track_b.clone(); // B carries the continuation of the same content: groups 2 and 3. for sequence in 2..4u64 { let mut group = track_b @@ -826,7 +832,8 @@ async fn broadcast_route_migration() { assert_eq!(path.as_str(), "test"); let broadcast = broadcast.expect("expected announce"); - // Subscribe once; a generous stale window so cached groups are served. + // Subscribe once, with a generous stale window so the continuation B already holds + // is served rather than aged out. let subscription = moq_net::track::Subscription::default().with_latency(moq_net::Latency::max(Duration::from_secs(10))); let mut sub = broadcast @@ -840,11 +847,25 @@ async fn broadcast_route_migration() { // at the latest group, so only A's newest group arrives. assert_eq!(read_payloads(&mut sub, 1).await, ["a1"]); - // Kill the serving session. The track migrates to B and the same subscriber - // keeps reading, resuming exactly at the first group A never delivered. + // Kill the serving session. The track migrates to B and the same subscriber keeps + // reading, resuming at the splice boundary: B holds the continuation of the same + // content, so group 2 is the next thing owed rather than something to skip. The + // catch-up is bounded by the boundary, and a consumer wanting only the live edge + // drops it on its own latency budget downstream. drop(session_a); assert_eq!(read_payloads(&mut sub, 2).await, ["b2", "b3"]); + // The migrated subscription is live: what B produces from here on flows + // through the same subscriber handle. + { + let mut group = standby_track + .create_group(moq_net::group::Info { sequence: 4 }) + .expect("create group"); + group.write_frame(Timestamp::ZERO, b"b4".as_ref()).expect("write frame"); + group.finish().expect("finish group"); + } + assert_eq!(read_payloads(&mut sub, 1).await, ["b4"]); + // The application observed no unannounce or re-announce across the swap. assert!( announcements.try_next().is_none(), diff --git a/rs/moq-net/CHANGELOG.md b/rs/moq-net/CHANGELOG.md index a9e89dfabae..fbb60450c62 100644 --- a/rs/moq-net/CHANGELOG.md +++ b/rs/moq-net/CHANGELOG.md @@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.11](https://github.com/moq-dev/moq/compare/moq-net-v0.2.10...moq-net-v0.2.11) - 2026-08-13 + +### Added + +- *(net)* announce namespaces unasked, with a SETUP opt-out ([#2748](https://github.com/moq-dev/moq/pull/2748)) + +### Fixed + +- *(net)* keep a live-edge subscriber at the live edge across a takeover ([#2785](https://github.com/moq-dev/moq/pull/2785)) +- *(net)* serve subscriptions in arrival order so reordered groups aren't dropped ([#2771](https://github.com/moq-dev/moq/pull/2771)) +- *(net)* only a new publisher re-arms the origin takeover gate ([#2746](https://github.com/moq-dev/moq/pull/2746)) +- *(native)* generate protocol version help ([#2719](https://github.com/moq-dev/moq/pull/2719)) +- *(net)* re-arm the takeover gate on every route observation ([#2742](https://github.com/moq-dev/moq/pull/2742)) +- *(net)* restore displaced broadcast publishers ([#2740](https://github.com/moq-dev/moq/pull/2740)) +- *(net)* invert stream priority to match transport send-order semantics ([#2720](https://github.com/moq-dev/moq/pull/2720)) +- *(net)* tolerate incoming streams that die before their first byte ([#2721](https://github.com/moq-dev/moq/pull/2721)) + +### Other + +- *(net)* cover multi-track failover and a partial-list standby ([#2713](https://github.com/moq-dev/moq/pull/2713)) + ## [0.2.10](https://github.com/moq-dev/moq/compare/moq-net-v0.2.9...moq-net-v0.2.10) - 2026-08-07 ### Fixed diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index 6fe6cc6f387..931bb074ec8 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.2.10" +version = "0.2.11" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 47ba5b33233..bd9ff9d3fba 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -174,7 +174,7 @@ impl Client { version: ietf::Version::Draft19, path: self.setup_path.clone(), peer_setup_stream: None, - peer_cluster: None, + peer_declared: None, })?; tracing::debug!(version = ?v, "connected"); @@ -200,7 +200,7 @@ impl Client { version: ietf::Version::Draft18, path: self.setup_path.clone(), peer_setup_stream: None, - peer_cluster: None, + peer_declared: None, })?; tracing::debug!(version = ?v, "connected"); @@ -226,7 +226,7 @@ impl Client { version: ietf::Version::Draft17, path: self.setup_path.clone(), peer_setup_stream: None, - peer_cluster: None, + peer_declared: None, })?; tracing::debug!(version = ?v, "connected"); @@ -374,6 +374,7 @@ impl Client { if let Some(path) = &self.setup_path { parameters.set_bytes(ietf::ParameterBytes::Path, path.clone().into_bytes()); } + ietf::solicit::into_setup(&mut parameters, ietf_encoding); let parameters = parameters.encode_bytes(ietf_encoding)?; let client = setup::Client { @@ -410,11 +411,16 @@ impl Client { (start.recv_bandwidth, start.driver, Some(start.connecting), start.goaway) } Version::Ietf(v) => { - // Decode the parameters to get the initial request ID. + // Decode the parameters to get the initial request ID and what the server + // requires of us. let parameters = ietf::Parameters::decode(&mut server.parameters, v)?; let request_id_max = parameters .get_varint(ietf::ParameterVarInt::MaxRequestId) .map(ietf::RequestId); + let peer_declared = ietf::peer::Peer { + solicit: ietf::solicit::from_setup(¶meters, v)?, + ..Default::default() + }; let stream = stream.with_version(v); // Draft 14-16: the path rode in the bidi SETUP above, not the uni one. @@ -430,7 +436,7 @@ impl Client { version: v, path: None, peer_setup_stream: None, - peer_cluster: None, + peer_declared: Some(peer_declared), })?; (None, protocol, None, goaway) } diff --git a/rs/moq-net/src/ietf/cluster.rs b/rs/moq-net/src/ietf/cluster.rs index 64ccc6986f6..a34a3217e78 100644 --- a/rs/moq-net/src/ietf/cluster.rs +++ b/rs/moq-net/src/ietf/cluster.rs @@ -219,46 +219,6 @@ pub fn link_cost(local: Option, peer: &Peer) -> u64 { local.or(peer.cost).unwrap_or(DEFAULT_COST) } -/// Shared slot for the peer's cluster options, filled when its SETUP is read. -/// -/// The publisher blocks on this before its first advertisement: the extension changes -/// the NAMESPACE encoding, so nothing can be sent until we know whether the peer speaks -/// it. Cheap to clone; every handle shares the same slot. -#[derive(Clone, Default)] -pub(crate) struct PeerSetup(kio::Shared>); - -impl PeerSetup { - /// Record what the peer declared. A SETUP carrying neither option records the - /// default (not negotiated), which is what unblocks a waiter. - /// - /// First write wins. The announce loops read this once and hold it for their - /// lifetime while subscription serving re-reads it, so letting a later SETUP - /// overwrite the identity would advertise under one exclusion and serve under - /// another, which is how a routing loop gets back in. - pub fn set(&self, peer: Peer) { - let mut slot = self.0.lock(); - if slot.is_none() { - *slot = Some(peer); - } - } - - /// Await the peer's SETUP. - /// - /// The peer MUST send exactly one, so this resolves once that stream is read. Waits - /// forever if it never does; the caller is a session task, cancelled when the driver - /// drops. - pub async fn get(&self) -> Peer { - let slot = self - .0 - .wait(|peer| match peer.is_some() { - true => std::task::Poll::Ready(()), - false => std::task::Poll::Pending, - }) - .await; - (*slot).expect("waited for Some") - } -} - /// Read the cluster Setup Options out of a decoded SETUP parameter block. pub fn peer_from_setup(params: &super::Parameters, version: Version) -> Result { if !supported(version) { @@ -511,26 +471,6 @@ mod tests { } } - /// The announce loops read the peer's declaration once and hold it, while - /// subscription serving re-reads it. A second SETUP overwriting the identity would - /// split those two apart, so the first write is the one that counts. - #[tokio::test] - async fn peer_setup_first_write_wins() { - let slot = PeerSetup::default(); - slot.set(Peer { - origin: Some(origin(42)), - cost: Some(3), - }); - slot.set(Peer { - origin: Some(origin(99)), - cost: Some(0), - }); - - let peer = slot.get().await; - assert_eq!(peer.origin, Some(origin(42))); - assert_eq!(peer.cost, Some(3)); - } - #[test] fn setup_without_relay_hops_is_not_negotiated() { let params = super::super::Parameters::default(); diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index f6e0b3428d2..35cef5eb95c 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -15,6 +15,7 @@ mod group; mod location; pub mod message; mod namespace; +pub mod peer; mod priority; mod properties; mod publish; @@ -22,6 +23,7 @@ mod publish_namespace; mod publisher; mod request; mod session; +pub mod solicit; mod subscribe; mod subscribe_namespace; mod subscriber; diff --git a/rs/moq-net/src/ietf/parameters.rs b/rs/moq-net/src/ietf/parameters.rs index 936933c2bd7..7b6a8040c7b 100644 --- a/rs/moq-net/src/ietf/parameters.rs +++ b/rs/moq-net/src/ietf/parameters.rs @@ -22,6 +22,8 @@ pub enum ParameterVarInt { MaxAuthTokenCacheSize = 4, /// RELAY_COST, from the MoQ Cluster extension. RelayCost = super::cluster::RELAY_COST, + /// SOLICIT, from the MoQ Solicit extension. + Solicit = super::solicit::SOLICIT, #[num_enum(catch_all)] Unknown(u64), } diff --git a/rs/moq-net/src/ietf/peer.rs b/rs/moq-net/src/ietf/peer.rs new file mode 100644 index 00000000000..5cc50a741f9 --- /dev/null +++ b/rs/moq-net/src/ietf/peer.rs @@ -0,0 +1,90 @@ +//! What the peer declared in its SETUP, and the slot the session tasks read it from. + +use super::cluster; + +/// The Setup Options the peer sent us. +/// +/// One value per session: both extensions ride the same SETUP, so they arrive together +/// and are read together. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub(crate) struct Peer { + /// The MoQ Cluster options: the peer's Hop ID and what it charges to cross. + pub cluster: cluster::Peer, + + /// MoQ Solicit: whether the peer requires advertisements to be solicited, so an + /// unsolicited PUBLISH_NAMESPACE is unwanted. `None` when it declared nothing, which + /// is the one case where sending us one anyway is not a protocol violation. + pub solicit: Option, +} + +/// Shared slot for [`Peer`], filled when the peer's SETUP is read. +/// +/// The publisher blocks on this before its first advertisement: the SETUP decides both +/// what an advertisement carries (MoQ Cluster) and whether one may be sent unasked (MoQ +/// Solicit), so nothing can go out until it arrives. Cheap to clone; every handle +/// shares the same slot. +#[derive(Clone, Default)] +pub(crate) struct PeerSetup(kio::Shared>); + +impl PeerSetup { + /// Record what the peer declared. A SETUP carrying no options records the default + /// (no extension negotiated, no requirements), which is what unblocks a waiter. + /// + /// First write wins. The announce loops read this once and hold it for their + /// lifetime while subscription serving re-reads it, so letting a later SETUP + /// overwrite the identity would advertise under one exclusion and serve under + /// another, which is how a routing loop gets back in. + pub fn set(&self, peer: Peer) { + let mut slot = self.0.lock(); + if slot.is_none() { + *slot = Some(peer); + } + } + + /// Await the peer's SETUP. + /// + /// The peer MUST send exactly one, so this resolves once that stream is read. Waits + /// forever if it never does; the caller is a session task, cancelled when the driver + /// drops. + pub async fn get(&self) -> Peer { + let slot = self + .0 + .wait(|peer| match peer.is_some() { + true => std::task::Poll::Ready(()), + false => std::task::Poll::Pending, + }) + .await; + (*slot).expect("waited for Some") + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The announce loops read the peer's declaration once and hold it, while + /// subscription serving re-reads it. A second SETUP overwriting the identity would + /// split those two apart, so the first write is the one that counts. + #[tokio::test] + async fn first_write_wins() { + let first = Peer { + cluster: cluster::Peer { + origin: Some(crate::Origin::new(42).unwrap()), + cost: Some(3), + }, + solicit: None, + }; + + let slot = PeerSetup::default(); + slot.set(first); + slot.set(Peer { + cluster: cluster::Peer { + origin: Some(crate::Origin::new(99).unwrap()), + cost: Some(0), + }, + solicit: Some(true), + }); + + assert_eq!(slot.get().await, first); + } +} diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 1405a5f4aa0..88f324f0771 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -15,7 +15,7 @@ use crate::{ util::{MaybeBoxedExt, MaybeSendBox}, }; -use super::{Message, Version, cluster}; +use super::{Message, Version, cluster, peer}; /// A broadcast whose route table is watched for changes in what we advertise: the /// namespace becoming (un)advertisable, or its path or cost moving. @@ -34,6 +34,50 @@ struct Watched { idle_at: Option, /// Set once the broadcast errors, so a dead entry stops being polled. dead: bool, + /// The peer should hold this namespace but does not: it refused the request, or we + /// could not get a stream to make it on. Nothing about that clears on its own, so the + /// loop comes back to it on a timer. + deferred: bool, + /// What the peer's refusal said about coming back, which outranks that timer. + refused: Refused, +} + +/// What a refusal said about re-offering the namespace. +/// +/// A peer answers a request it declines with a retry interval ({{moqt}} REQUEST_ERROR), +/// and ignoring it is how a permanent refusal (unauthorized, uninterested) turns into a +/// request every few seconds for the life of the session. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +enum Refused { + /// Never refused, or refused on a draft whose error carries no interval, so our own + /// backoff is the only guidance there is. + #[default] + No, + /// Refused with a minimum wait before re-offering. + Until(web_async::time::Instant), + /// Refused with an interval of 0: the peer does not want this offered again. + Never, +} + +impl Refused { + /// Whether a fresh offer may go out now. + /// + /// The single gate, consulted on every reconciliation rather than only on the retry + /// sweep: a route change re-prices an advertisement but does not excuse us from a + /// wait the peer asked for, nor make a refused namespace a different one. + fn offerable(&self, now: web_async::time::Instant) -> bool { + match self { + Self::No => true, + Self::Until(at) => now >= *at, + Self::Never => false, + } + } + + /// Whether the loop should keep coming back at all. Only a refusal that forbids + /// retrying ends it; a wait still has to arm the timer that counts it out. + fn pending(&self) -> bool { + *self != Self::Never + } } impl Watched { @@ -44,6 +88,8 @@ impl Watched { sent: Advert::None, idle_at: None, dead: false, + deferred: false, + refused: Refused::No, } } @@ -103,6 +149,82 @@ enum Watch { Idle(crate::PathOwned), } +/// How long to wait for a stream to advertise one namespace on. +/// +/// Only reached when the peer has granted no more, which on this path means it is holding +/// every advertisement we already sent. Long enough that a merely slow peer is not given +/// up on, short enough that the loop resumes and can retire something. +const ADVERTISE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5); + +/// First wait before re-offering a namespace we could not get up. +const RETRY_BASE: std::time::Duration = std::time::Duration::from_millis(100); + +/// Ceiling on that wait. The loop retries for the life of the session, so it must settle +/// into a slow poll rather than a spin. +const RETRY_MAX: std::time::Duration = std::time::Duration::from_secs(5); + +/// Spread a retry over half its window, so every namespace on a busy relay does not come +/// back at the same instant. +fn jitter(delay: std::time::Duration) -> std::time::Duration { + use rand::RngExt; + delay.mul_f64(0.5 + rand::rng().random::() / 2.0) +} + +/// Where one announce loop's advertisements go. +enum Target { + /// Inline NAMESPACE entries on the SUBSCRIBE_NAMESPACE stream that asked for them + /// (draft-16+). + Inline(Stream), + /// Each advertisement on its own PUBLISH_NAMESPACE request. Unsolicited when there + /// is no stream; draft-14/15 answer a SUBSCRIBE_NAMESPACE this way, since they + /// predate NAMESPACE, and hold onto its stream to end with the subscription. + Requests(Option>), +} + +impl Target { + /// The SUBSCRIBE_NAMESPACE stream this loop answers, if any. + fn stream(&mut self) -> Option<&mut Stream> { + match self { + Self::Inline(stream) | Self::Requests(Some(stream)) => Some(stream), + Self::Requests(None) => None, + } + } + + /// Ready when the peer ends this loop by closing the stream it asked on. + /// + /// An unsolicited loop has no stream of its own to watch and parks here: the + /// session driver polling it is what drops it when the session ends. + fn poll_closed(&mut self, cx: &mut std::task::Context<'_>) -> Poll> { + match self.stream() { + Some(stream) => stream.reader.poll_closed(cx), + None => Poll::Pending, + } + } +} + +/// One announce loop's state: where its advertisements go, and what the peer holds. +struct Namespaces { + /// What the peer declared in its SETUP, which decides what an advertisement carries. + peer: cluster::Peer, + target: Target, + /// Every announced broadcast under this loop's prefix. + watched: HashMap, + /// The open PUBLISH_NAMESPACE request carrying each advertised namespace. Empty when + /// the entries ride a SUBSCRIBE_NAMESPACE stream inline. + requests: HashMap>, +} + +impl Namespaces { + fn new(peer: cluster::Peer, target: Target) -> Self { + Self { + peer, + target, + watched: HashMap::new(), + requests: HashMap::new(), + } + } +} + /// What woke an announce-forwarding loop. enum NamespaceEvent { /// The session or stream ended, with the result to surface. @@ -116,6 +238,8 @@ enum NamespaceEvent { /// The linger sleep fired without an expired entry (it was canceled, or a later /// deadline remains): restart the turn so the next deadline arms a fresh sleep. Linger, + /// The retry sleep fired: re-offer whatever the peer should be holding and isn't. + Retry, } #[derive(Clone)] @@ -133,7 +257,7 @@ pub(super) struct Publisher { // declares its own, which wins. peer_origin: Option, // What the peer declared in its SETUP, filled when that stream is read. - peer_setup: cluster::PeerSetup, + peer_setup: peer::PeerSetup, version: Version, } @@ -143,7 +267,7 @@ impl Publisher { origin: origin::Consumer, control: Control, peer_origin: Option, - peer_setup: cluster::PeerSetup, + peer_setup: peer::PeerSetup, version: Version, ) -> Self { Self { @@ -164,11 +288,19 @@ impl Publisher { /// encoding: nothing can be advertised until we know whether the peer speaks it. async fn peer(&self) -> cluster::Peer { match cluster::supported(self.version) { - true => self.peer_setup.get().await, + true => self.peer_setup.get().await.cluster, false => cluster::Peer::default(), } } + /// Whether the peer requires advertisements to be solicited, from the same SETUP. + /// + /// Blocks on it for the same reason [`Self::peer`] does: this decides whether the + /// first advertisement is sent unasked, so it cannot be guessed and corrected later. + async fn requires_solicitation(&self) -> bool { + self.peer_setup.get().await.solicit.unwrap_or(false) + } + /// The origin to serve this peer's subscriptions from: sources whose hop chain flows /// through the peer are excluded, so a subscription is never handed data that already /// flowed through the subscriber. @@ -678,39 +810,62 @@ impl Publisher { /// Bring the peer's view of one namespace in line with the current selection. /// - /// Draft-16+ re-sends NAMESPACE on the SUBSCRIBE_NAMESPACE stream (the receiver - /// treats a repeat as a replacement) and retracts with NAMESPACE_DONE. - /// Draft-14/15 carry each advertisement on its own PUBLISH_NAMESPACE request: - /// an update re-sends PUBLISH_NAMESPACE **on the stream that already carries - /// it**, since a second stream would leave two claiming one namespace, and a - /// withdrawal closes the request with PUBLISH_NAMESPACE_DONE. + /// A loop writing inline (draft-16+ answering a SUBSCRIBE_NAMESPACE) re-sends + /// NAMESPACE on that stream, which the receiver treats as a replacement, and + /// retracts with NAMESPACE_DONE. Otherwise each advertisement rides its own + /// PUBLISH_NAMESPACE request: an update re-sends PUBLISH_NAMESPACE **on the stream + /// that already carries it**, since a second stream would leave two claiming one + /// namespace, and a withdrawal closes the request with PUBLISH_NAMESPACE_DONE. async fn sync_namespace( &self, + ns: &mut Namespaces, suffix: &crate::PathOwned, path: &crate::PathOwned, - peer: &cluster::Peer, - watched: &mut HashMap, - requests: &mut HashMap>, - stream: &mut Stream, ) -> Result<(), Error> { + let Namespaces { + peer, + target, + watched, + requests, + } = ns; + let Some(watch) = watched.get(suffix) else { return Ok(()); }; let advert = self.select(watch, peer); - if advert == watch.sent { + let refused = watch.refused; + let wanted = advert.wanted(); + let held = watch.sent.wanted(); + let unchanged = advert == watch.sent; + + if unchanged { + // Nothing to send. A namespace that is no longer advertisable is no longer + // pending either, and leaving that set would keep the retry timer armed + // forever for a wire message that can never happen. + if !wanted && let Some(watch) = watched.get_mut(suffix) { + watch.deferred = false; + } + return Ok(()); + } + + // A fresh offer waits for what the refusal asked for, whatever brought us back. + // Only withdrawing and re-announcing clears it, since that builds a fresh entry. + if wanted && !held && !refused.offerable(web_async::time::Instant::now()) { return Ok(()); } - let held = watch.sent.wanted(); let absolute = self.origin.absolute(path).to_owned(); - let sent = match self.version { - Version::Draft14 | Version::Draft15 => { + // Only a fresh PUBLISH_NAMESPACE request can be refused; everything else below + // either rides a stream the peer already accepted or says nothing at all. + let mut refused = watch.refused; + let sent = match target { + Target::Requests(_) => { match (advert.wanted(), requests.get_mut(suffix)) { (false, _) => { if held { tracing::debug!(broadcast = %absolute, "namespace_done"); } - self.withdraw_namespace(stream, requests, suffix.clone()).await?; + self.withdraw_namespace(target, requests, suffix.clone()).await?; } (true, Some(request)) => { tracing::debug!(broadcast = %absolute, "announce update"); @@ -726,8 +881,9 @@ impl Publisher { .await?; } (true, None) => { - tracing::debug!(broadcast = %absolute, "namespace"); - self.advertise_namespace(requests, path, suffix.clone(), advert.params()) + tracing::debug!(broadcast = %absolute, "publish_namespace"); + refused = self + .advertise_namespace(requests, path, suffix.clone(), advert.params()) .await?; } } @@ -739,7 +895,7 @@ impl Publisher { false => Advert::None, } } - _ => { + Target::Inline(stream) => { match (advert.wanted(), held) { (true, _) => { tracing::debug!(broadcast = %absolute, "namespace"); @@ -770,23 +926,37 @@ impl Publisher { }; if let Some(watch) = watched.get_mut(suffix) { + // A peer that asked not to be offered this again outranks the retry timer; + // anything else it should hold and does not comes back on one. + watch.refused = refused; + watch.deferred = wanted && !sent.wanted() && refused.pending(); watch.set_sent(sent); } Ok(()) } - /// Open a PUBLISH_NAMESPACE request for one namespace (draft-14/15, which have - /// no NAMESPACE message), recording it in `requests` so an update or withdrawal - /// reuses the same stream. A declined request records nothing. + /// Open a PUBLISH_NAMESPACE request for one namespace, recording it in `requests` + /// so an update or withdrawal reuses the same stream. A declined request records + /// nothing: a peer that wants none of this rejects each one and stays connected. + /// + /// Returns what the refusal, if any, said about coming back. async fn advertise_namespace( &self, requests: &mut HashMap>, path: &crate::PathOwned, suffix: crate::PathOwned, cluster: Option, - ) -> Result<(), Error> { + ) -> Result { let request_id = self.control.next_request_id().await?; - let mut request = Stream::open(&mut self.session.clone(), self.version).await?; + + // Bounded, because an advertisement holds its stream for as long as the namespace + // lives: a peer whose concurrent-stream limit we have filled makes this open block, + // and the withdrawals queued behind it are the only thing that would free a slot. + // Giving up records nothing, so the namespace is simply retried later. + let Some(mut request) = self.open_request().await? else { + tracing::debug!(broadcast = %self.origin.absolute(path), "no stream for the advertisement"); + return Ok(Refused::No); + }; request.writer.encode(&ietf::PublishNamespace::ID).await?; request @@ -798,9 +968,12 @@ impl Publisher { }) .await?; - let type_id: u64 = request.reader.decode().await?; - let size: u16 = request.reader.decode().await?; - let mut data = request.reader.read_exact(size as usize).await?; + // Bounded for the same reason the open is: a peer that takes the stream and answers + // nothing would park this loop forever, and every withdrawal queued behind it. + let Some((type_id, mut data)) = Self::read_response(&mut request).await? else { + tracing::debug!(broadcast = %self.origin.absolute(path), "no answer to the advertisement"); + return Ok(Refused::No); + }; match (self.version, type_id) { (Version::Draft14, ietf::PublishNamespaceOk::ID) => { @@ -810,7 +983,8 @@ impl Publisher { (Version::Draft14, ietf::PublishNamespaceError::ID) => { let msg = ietf::PublishNamespaceError::decode_msg(&mut data, self.version)?; tracing::warn!(message = ?msg, "publish namespace error"); - return Ok(()); + // Draft-14's error carries no retry interval, so our own backoff stands. + return Ok(Refused::No); } (_, ietf::RequestOk::ID) => { let msg = ietf::RequestOk::decode_msg(&mut data, self.version)?; @@ -819,7 +993,7 @@ impl Publisher { (_, ietf::RequestError::ID) => { let msg = ietf::RequestError::decode_msg(&mut data, self.version)?; tracing::warn!(message = ?msg, "publish namespace error"); - return Ok(()); + return Ok(self.refusal(msg.retry_interval)); } _ => return Err(Error::UnexpectedMessage), } @@ -832,36 +1006,107 @@ impl Publisher { stream: request, }, ); - Ok(()) + Ok(Refused::No) } - /// Withdraw an advertised namespace: NAMESPACE_DONE inline on draft-16+, or - /// PUBLISH_NAMESPACE_DONE closing its own request on draft-14/15. + /// How to read a refusal's retry interval, in milliseconds. + /// + /// Draft-14/15 errors carry no interval, so a decoded 0 there says nothing and our own + /// backoff stands. Everywhere else 0 is the peer asking not to be offered this again, + /// which is what keeps a permanent refusal (unauthorized, uninterested) from becoming + /// a request every few seconds for the life of the session. + fn refusal(&self, retry_interval: u64) -> Refused { + match (self.version, retry_interval) { + (Version::Draft14 | Version::Draft15, _) => Refused::No, + (_, 0) => Refused::Never, + (_, ms) => Refused::Until(web_async::time::Instant::now() + std::time::Duration::from_millis(ms)), + } + } + + /// Open a stream for one advertisement, or `None` if the peer did not give us one in + /// time. + /// + /// The announce loop is single-threaded over origin updates, so an open that parks + /// forever parks everything, including the unannounces that release the streams the + /// peer is waiting on us to retire. Failing instead keeps the loop moving. + async fn open_request(&self) -> Result>, Error> { + let mut session = self.session.clone(); + let mut open = std::pin::pin!(Stream::open(&mut session, self.version)); + let mut timeout = kio::time::Deadline::after(ADVERTISE_TIMEOUT); + + kio::wait(|waiter| { + if let Poll::Ready(res) = waiter.poll_future(open.as_mut()) { + return Poll::Ready(res.map(Some)); + } + if timeout.poll(waiter).is_ready() { + return Poll::Ready(Ok(None)); + } + Poll::Pending + }) + .await + } + + /// Read the peer's answer to one advertisement, or `None` if it did not answer in time. + /// + /// Bounded for the same reason [`Self::open_request`] is, and it is the same peer + /// behavior seen a step later: a stream the peer accepts and never answers on holds the + /// loop just as effectively as one it never grants. Giving up records nothing, so the + /// namespace stays outstanding and the retry re-offers it. + async fn read_response(request: &mut Stream) -> Result, Error> { + let mut read = std::pin::pin!(async { + let type_id: u64 = request.reader.decode().await?; + let size: u16 = request.reader.decode().await?; + let data = request.reader.read_exact(size as usize).await?; + Ok::<_, Error>((type_id, data)) + }); + let mut timeout = kio::time::Deadline::after(ADVERTISE_TIMEOUT); + + kio::wait(|waiter| { + if let Poll::Ready(res) = waiter.poll_future(read.as_mut()) { + return Poll::Ready(res.map(Some)); + } + if timeout.poll(waiter).is_ready() { + return Poll::Ready(Ok(None)); + } + Poll::Pending + }) + .await + } + + /// Withdraw an advertised namespace: NAMESPACE_DONE inline, or PUBLISH_NAMESPACE_DONE + /// closing the request that carried it. async fn withdraw_namespace( &self, - stream: &mut Stream, + target: &mut Target, requests: &mut HashMap>, suffix: crate::PathOwned, ) -> Result<(), Error> { - match self.version { - Version::Draft14 | Version::Draft15 => { + match target { + Target::Requests(_) => { if let Some(mut request) = requests.remove(&suffix) { - // Best effort: the peer may already be gone. - let _ = request - .stream - .writer - .encode_message(&ietf::PublishNamespaceDone { - track_namespace: request.path.as_path(), - request_id: request.request_id, - }) - .await; + // Draft-17+ removed PUBLISH_NAMESPACE_DONE: the FIN below is the whole + // withdrawal. Sending it anyway puts the type on the wire before the + // body fails to encode, and a receiver reading 0x09 there has no choice + // but to treat it as a protocol violation (see + // `Subscriber::terminal_publish_namespace`). + if matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { + // Best effort: the peer may already be gone. + let _ = request + .stream + .writer + .encode_message(&ietf::PublishNamespaceDone { + track_namespace: request.path.as_path(), + request_id: request.request_id, + }) + .await; + } // The withdrawal rides this request's own stream, which drops with it, so // it needs the acknowledgement before the drop-time reset can discard it. let _ = request.stream.writer.close().await; } } - _ => { + Target::Inline(stream) => { stream.writer.encode(&ietf::NamespaceDone::ID).await?; stream .writer @@ -874,25 +1119,56 @@ impl Publisher { Ok(()) } - /// Close out every open draft-14/15 PUBLISH_NAMESPACE request. A no-op on - /// later drafts, whose entries ride the SUBSCRIBE_NAMESPACE stream itself. + /// Close out every open PUBLISH_NAMESPACE request. A no-op for a loop whose entries + /// ride the SUBSCRIBE_NAMESPACE stream itself, which retracts them by ending. async fn withdraw_requests( &self, - stream: &mut Stream, + target: &mut Target, requests: &mut HashMap>, ) { let suffixes: Vec = requests.keys().cloned().collect(); for suffix in suffixes { - let _ = self.withdraw_namespace(stream, requests, suffix).await; + let _ = self.withdraw_namespace(target, requests, suffix).await; } } + /// Advertise every namespace we can, without waiting to be asked. + /// + /// moq-transport itself says nothing about which of the two discovery messages a peer + /// expects, and the peers that never send SUBSCRIBE_NAMESPACE are exactly the ones + /// expecting a publisher to announce itself, so the default has to be to announce. A + /// peer that would rather ask says so with the MoQ Solicit extension + /// ([`solicit`](super::solicit)), + /// and then this loop does nothing and + /// [`Self::run_subscribe_namespace_stream`] carries the advertisements instead. + /// Exactly one of the two is live, which is what keeps the peer from hearing a + /// namespace twice. + pub async fn run_publish_namespaces(self) -> Result<(), Error> { + if self.requires_solicitation().await { + return Ok(()); + } + + // The cluster extension changes what an advertisement carries, so nothing can be + // sent until the peer's SETUP says whether it speaks it. + let peer = self.peer().await; + + // Split horizon, as the solicited loop applies it: never advertise a route back + // to the peer it came from. + let origin = match self.exclude(&peer) { + crate::Origin::UNKNOWN => self.origin.clone(), + exclude => self.origin.clone().excluding(exclude), + }; + + let ns = Namespaces::new(peer, Target::Requests(None)); + self.run_namespaces(origin, crate::Path::empty().to_owned(), ns).await + } + /// Handle a SUBSCRIBE_NAMESPACE on its bidi stream. /// - /// Namespaces are only advertised in response to one of these, and all the - /// announce state is local to this task (mirroring `lite::Publisher`'s + /// All the announce state is local to this task (mirroring `lite::Publisher`'s /// announce handling): whatever this subscription advertised is withdrawn - /// when its stream ends. + /// when its stream ends. It only advertises anything when the peer asked to be told + /// on request; otherwise [`Self::run_publish_namespaces`] has already said it all. async fn run_subscribe_namespace_stream( self, mut stream: Stream, @@ -946,32 +1222,84 @@ impl Publisher { crate::Origin::UNKNOWN => origin, exclude => origin.excluding(exclude), }; + + // Draft-14/15 predate NAMESPACE, so they answer with their own PUBLISH_NAMESPACE + // requests and keep this stream open for the subscription's lifetime. + let target = match self.version { + Version::Draft14 | Version::Draft15 => Target::Requests(Some(stream)), + _ => Target::Inline(stream), + }; + + // Unless the peer asked to be told only on request, it has already heard all of + // this as unsolicited PUBLISH_NAMESPACE. Repeating it here would leave it holding + // two sources for one namespace, so this stream carries nothing and simply stays + // open until the peer is done with it. + let origin = match self.requires_solicitation().await { + true => origin, + false => origin.empty(), + }; + + let ns = Namespaces::new(peer, target); + self.run_namespaces(origin, prefix, ns).await + } + + /// Forward origin (un)announces to the peer until the loop ends. + /// + /// Shared by both announce paths: they differ in where the advertisements go + /// ([`Target`]) and where the origin is rooted (`prefix`, empty when nothing asked + /// for a subset). + async fn run_namespaces( + &self, + origin: origin::Consumer, + prefix: crate::PathOwned, + mut ns: Namespaces, + ) -> Result<(), Error> { let mut announced = origin.announced(); - let mut watched: HashMap = HashMap::new(); - // Draft-14/15: the open PUBLISH_NAMESPACE request carrying each advertised - // namespace. Empty on later drafts, whose entries ride `stream` inline. - let mut requests: HashMap> = HashMap::new(); let mut linger = kio::time::Deadline::new(); + // When to re-offer whatever the peer should hold and doesn't, and how long to wait + // the next time that fails. Jittered so a relay's namespaces don't all come back on + // the same tick. + let mut retry = kio::time::Deadline::new(); + let mut retry_at: Option = None; + let mut retry_delay = RETRY_BASE; + // Stream updates (origin (un)announces plus watched route and demand // changes), bailing if the peer closes its side first. let res = loop { - linger.set(Self::linger_deadline(&watched)); + linger.set(Self::linger_deadline(&ns.watched)); + + match ns.watched.values().any(|watch| watch.deferred) { + // Arm on the edge, so a turn that changes nothing else doesn't push the + // deadline out forever. + true => retry_at = retry_at.or_else(|| Some(web_async::time::Instant::now() + jitter(retry_delay))), + false => { + retry_at = None; + retry_delay = RETRY_BASE; + } + } + retry.set(retry_at); let event = { + // Split the borrow so the close watch and the route sweep can both run in + // the same turn. + let Namespaces { target, watched, .. } = &mut ns; kio::wait(|waiter| { let mut cx = std::task::Context::from_waker(waiter.waker()); - if let Poll::Ready(res) = stream.reader.poll_closed(&mut cx) { + if let Poll::Ready(res) = target.poll_closed(&mut cx) { return Poll::Ready(NamespaceEvent::Closed(res)); } if let Poll::Ready(update) = announced.poll_next(waiter) { return Poll::Ready(NamespaceEvent::Update(update)); } + if retry.poll(waiter).is_ready() { + return Poll::Ready(NamespaceEvent::Retry); + } // Stamped per poll rather than kept: the turn always ends in a // `Ready` below once it fires, so it never has to survive. let fired = linger.poll(waiter).is_ready().then(web_async::time::Instant::now); - match Self::poll_watched(&mut watched, fired, waiter) { + match Self::poll_watched(watched, fired, waiter) { Poll::Ready(Watch::Changed(path)) => return Poll::Ready(NamespaceEvent::Routes(path)), Poll::Ready(Watch::Idle(path)) => return Poll::Ready(NamespaceEvent::Idle(path)), Poll::Pending => {} @@ -987,10 +1315,32 @@ impl Publisher { match event { NamespaceEvent::Closed(res) => break res, NamespaceEvent::Linger => continue, + NamespaceEvent::Retry => { + retry_at = None; + retry_delay = (retry_delay * 2).min(RETRY_MAX); + + // A minimum wait the peer named is enforced by `sync_namespace`, which + // every path goes through, so a namespace still inside one simply + // makes no offer this turn. The next sweep is at most RETRY_MAX away. + let deferred: Vec = ns + .watched + .iter() + .filter(|(_, watch)| watch.deferred) + .map(|(suffix, _)| suffix.clone()) + .collect(); + + for suffix in deferred { + let path = prefix.join(&suffix); + self.sync_namespace(&mut ns, &suffix, &path).await?; + } + } NamespaceEvent::Update(None) => { // The origin is gone: withdraw everything, then finish the // stream and wait for delivery. - self.withdraw_requests(&mut stream, &mut requests).await; + self.withdraw_requests(&mut ns.target, &mut ns.requests).await; + let Some(stream) = ns.target.stream() else { + return Ok(()); + }; stream.writer.finish()?; return stream.writer.closed().await; } @@ -1003,35 +1353,34 @@ impl Publisher { match broadcast { Some(broadcast) => { - watched.insert(suffix.clone(), Watched::new(broadcast)); - self.sync_namespace(&suffix, &path, &peer, &mut watched, &mut requests, &mut stream) - .await?; + ns.watched.insert(suffix.clone(), Watched::new(broadcast)); + self.sync_namespace(&mut ns, &suffix, &path).await?; } None => { // Only close out namespaces the peer actually saw. - let held = watched.remove(&suffix).is_some_and(|watch| watch.sent.wanted()); + let held = ns.watched.remove(&suffix).is_some_and(|watch| watch.sent.wanted()); if held { tracing::debug!(broadcast = %self.origin.absolute(&path), "namespace_done"); - self.withdraw_namespace(&mut stream, &mut requests, suffix).await?; + self.withdraw_namespace(&mut ns.target, &mut ns.requests, suffix) + .await?; } } } } NamespaceEvent::Routes(suffix) => { let path = prefix.join(&suffix); - self.sync_namespace(&suffix, &path, &peer, &mut watched, &mut requests, &mut stream) - .await?; + self.sync_namespace(&mut ns, &suffix, &path).await?; } NamespaceEvent::Idle(suffix) => { - if let Some(watch) = watched.get_mut(&suffix) { + if let Some(watch) = ns.watched.get_mut(&suffix) { watch.idle_at = Some(web_async::time::Instant::now()); } } } }; - // This subscription's advertisements die with it. - self.withdraw_requests(&mut stream, &mut requests).await; + // This loop's advertisements die with it. + self.withdraw_requests(&mut ns.target, &mut ns.requests).await; res } @@ -1355,6 +1704,23 @@ mod tests { writes.windows(needle.len()).filter(|window| *window == needle).count() } + /// A SETUP slot already filled with what the peer declared. The announce loops block + /// on it, so a test that leaves it empty is a test that never advertises. + fn declared(solicit: Option) -> peer::PeerSetup { + let slot = peer::PeerSetup::default(); + slot.set(peer::Peer { + solicit, + ..Default::default() + }); + slot + } + + /// A peer that requires solicitation, which is what hands the advertisements to the + /// SUBSCRIBE_NAMESPACE stream. + fn requires_solicitation() -> peer::PeerSetup { + declared(Some(true)) + } + /// A broadcast whose every route flows through the peer's assigned identity /// (`Client::with_peer_origin`) is never advertised to that peer; it would only /// echo the peer's own content back at it. A broadcast with an independent @@ -1373,7 +1739,7 @@ mod tests { origin.consume(), Control::new(None, false), Some(assigned), - cluster::PeerSetup::default(), + peer::PeerSetup::default(), Version::Draft16, ); @@ -1474,7 +1840,7 @@ mod tests { origin.consume(), Control::new(None, false), Some(assigned), - cluster::PeerSetup::default(), + requires_solicitation(), Version::Draft16, ); @@ -1535,6 +1901,78 @@ mod tests { /// The peer's OK to a PUBLISH_NAMESPACE, framed exactly as the announce path /// reads it -- built with the crate's own writer so the framing can't drift /// from the encoder under test. + /// A REQUEST_ERROR declining an advertisement, with the retry interval the peer asked + /// for in milliseconds. Zero means it does not want the namespace offered again. + async fn publish_namespace_error(version: Version, retry_interval: u64) -> Vec { + let log = crate::lite::test_transport::Log::default(); + let mut writer = crate::coding::Writer::new(crate::lite::test_transport::SinkSend::new(log.clone()), version); + + writer.encode(&ietf::RequestError::ID).await.unwrap(); + writer + .encode(&ietf::RequestError { + request_id: matches!(version, Version::Draft15 | Version::Draft16).then_some(RequestId(1)), + error_code: 403, + reason_phrase: "no".into(), + retry_interval, + }) + .await + .unwrap(); + + log.writes.lock().unwrap().clone() + } + + /// A peer that refuses an advertisement with a retry interval of 0 is asking not to be + /// offered it again. Coming back anyway turns a permanent refusal (unauthorized, + /// uninterested) into a request every few seconds for the life of the session. + #[tokio::test(start_paused = true)] + async fn a_refusal_that_forbids_retrying_is_not_retried() { + const VERSION: Version = Version::Draft17; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let _cam = origin + .create_broadcast("lonely-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Every stream is answered with the same refusal, so a retry would show up as a + // second occurrence on the wire. + let refusal = publish_namespace_error(VERSION, 0).await; + let session = + crate::lite::test_transport::ScriptedSession::per_stream(vec![refusal.clone(), refusal.clone(), refusal]); + let log = session.log.clone(); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + declared(Some(false)), + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"lonely-cam") > 0 { + break; + } + settle().await; + } + assert_eq!(occurrences(&log, b"lonely-cam"), 1, "the advertisement never went out"); + + // Well past every retry the loop would otherwise take. + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + tick().await; + } + + assert_eq!( + occurrences(&log, b"lonely-cam"), + 1, + "re-offered a namespace the peer asked not to be offered again" + ); + } + async fn publish_namespace_ok(version: Version) -> Vec { let log = crate::lite::test_transport::Log::default(); let mut writer = crate::coding::Writer::new(crate::lite::test_transport::SinkSend::new(log.clone()), version); @@ -1549,7 +1987,7 @@ mod tests { .await .unwrap(); } - _ => { + Version::Draft15 | Version::Draft16 => { writer.encode(&ietf::RequestOk::ID).await.unwrap(); writer .encode(&ietf::RequestOk { @@ -1558,6 +1996,11 @@ mod tests { .await .unwrap(); } + // Draft-17+ dropped the request id: the response rides the request's stream. + _ => { + writer.encode(&ietf::RequestOk::ID).await.unwrap(); + writer.encode(&ietf::RequestOk { request_id: None }).await.unwrap(); + } } let writes = log.writes.lock().unwrap(); @@ -1577,7 +2020,7 @@ mod tests { // Announced before the peer subscribes: it must only hit the wire after. let early = origin - .create_broadcast("early-cam", crate::broadcast::Route::new().with_announce(true)) + .create_broadcast("early-cam", crate::broadcast::Route::announced()) .unwrap(); settle().await; @@ -1592,7 +2035,7 @@ mod tests { consumer, Control::new(None, false), None, - cluster::PeerSetup::default(), + requires_solicitation(), VERSION, ); @@ -1619,7 +2062,7 @@ mod tests { // A later announce reaches the same subscription. let _late = origin - .create_broadcast("late-cam", crate::broadcast::Route::new().with_announce(true)) + .create_broadcast("late-cam", crate::broadcast::Route::announced()) .unwrap(); for _ in 0..100 { assert!(futures::poll!(run.as_mut()).is_pending()); @@ -1654,6 +2097,489 @@ mod tests { assert_eq!(log.bi_opens(), 3, "no extra stream for the withdrawal"); } + /// A peer that declared nothing is told without being asked. Relays that never send + /// SUBSCRIBE_NAMESPACE hear nothing otherwise, and every third-party one behaves + /// that way: a publisher is expected to announce itself. + #[tokio::test] + async fn a_peer_that_declared_nothing_is_told_unsolicited() { + const VERSION: Version = Version::Draft17; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let _local = origin + .create_broadcast("local-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // The only stream is the PUBLISH_NAMESPACE request we open ourselves. + let session = + crate::lite::test_transport::ScriptedSession::per_stream(vec![publish_namespace_ok(VERSION).await]); + let log = session.log.clone(); + + let peer_setup = peer::PeerSetup::default(); + peer_setup.set(peer::Peer::default()); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + peer_setup, + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"local-cam") >= 1 { + break; + } + settle().await; + } + + assert_eq!( + occurrences(&log, b"local-cam"), + 1, + "PUBLISH_NAMESPACE without a SUBSCRIBE_NAMESPACE" + ); + assert_eq!(log.bi_opens(), 1, "one request stream"); + } + + /// Drive both announce loops at once against a peer that declared `solicit`, + /// returning how many times the namespace hit the wire and how many bidi streams + /// were opened. One stream means the entry rode the subscription inline; two means + /// it went out as its own PUBLISH_NAMESPACE request. + async fn advertise_both_ways(solicit: Option) -> (usize, usize) { + const VERSION: Version = Version::Draft17; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let _cam = origin + .create_broadcast("cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Stream 1 is the peer's SUBSCRIBE_NAMESPACE; stream 2, if opened at all, is our + // PUBLISH_NAMESPACE request. + let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![ + Vec::new(), + publish_namespace_ok(VERSION).await, + ]); + let log = session.log.clone(); + + let publisher = Publisher::new( + session.clone(), + origin.consume(), + Control::new(None, false), + None, + declared(solicit), + VERSION, + ); + + let stream = Stream::open(&mut session.clone(), VERSION).await.unwrap(); + let msg = ietf::SubscribeNamespace { + request_id: RequestId(1), + namespace: crate::Path::new(""), + }; + let mut solicited = std::pin::pin!(publisher.clone().run_subscribe_namespace_stream(stream, msg)); + let mut unsolicited = std::pin::pin!(publisher.run_publish_namespaces()); + + // Poll well past the first advertisement, so a second one from the other loop + // would show up rather than being missed by an early break. The unsolicited loop + // finishes immediately when the peer requires solicitation, and a completed + // future must not be polled again. + let mut quiet = false; + for _ in 0..100 { + assert!(futures::poll!(solicited.as_mut()).is_pending()); + if !quiet { + quiet = futures::poll!(unsolicited.as_mut()).is_ready(); + } + settle().await; + } + + (occurrences(&log, b"cam"), log.bi_opens()) + } + + /// The regression that made announces solicited in the first place: a namespace sent + /// as both PUBLISH_NAMESPACE and NAMESPACE leaves the peer holding two sources for + /// one broadcast, and whichever arrives second replaces the one the first attached. + /// The peer's SETUP picks which loop carries it, so the other stays quiet and the + /// namespace goes out exactly once either way. + #[tokio::test] + async fn each_namespace_is_advertised_exactly_once() { + let (unsolicited, streams) = advertise_both_ways(Some(false)).await; + assert_eq!(unsolicited, 1, "a peer that required nothing is told once"); + assert_eq!(streams, 2, "on its own PUBLISH_NAMESPACE request"); + + let (solicited, streams) = advertise_both_ways(Some(true)).await; + assert_eq!(solicited, 1, "a peer that asked to be told on request is told once"); + assert_eq!(streams, 1, "inline on the SUBSCRIBE_NAMESPACE stream it asked on"); + } + + /// A peer out of stream credit parks the open. That must not wedge the loop, because + /// the withdrawals queued behind it are the only thing that frees a slot: an open that + /// never gives up is a deadlock, not a delay. + /// + /// Draft-14 so the withdrawal names its namespace on the wire, which is what makes the + /// loop's progress visible while every open is blocked. + #[tokio::test(start_paused = true)] + async fn a_parked_open_still_lets_a_namespace_be_withdrawn() { + const VERSION: Version = Version::Draft14; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let first = origin + .create_broadcast("first-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Open: the peer still has credit for the first advertisement, and answers it. + let gate = kio::Producer::new(true); + let ok = publish_namespace_ok(VERSION).await; + let session = crate::lite::test_transport::ScriptedSession::gated_open(vec![ok.clone(), ok], gate.consume()); + let log = session.log.clone(); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + declared(Some(false)), + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"first-cam") > 0 { + break; + } + settle().await; + } + assert_eq!( + occurrences(&log, b"first-cam"), + 1, + "the first advertisement never went out" + ); + + // Credit runs out, and a second namespace wants a stream we cannot get. + set_gate(&gate, false); + let _second = origin + .create_broadcast("second-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Retiring the first frees a slot and needs no new stream, so the loop has to reach + // it despite the open above. + drop(first); + + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"first-cam") >= 2 { + break; + } + tick().await; + } + assert_eq!( + occurrences(&log, b"first-cam"), + 2, + "PUBLISH_NAMESPACE_DONE never sent: the open wedged the loop" + ); + + // Credit returns, and nothing else about the origin changes. + set_gate(&gate, true); + + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"second-cam") > 0 { + break; + } + tick().await; + } + assert_eq!( + occurrences(&log, b"second-cam"), + 1, + "never retried once credit returned" + ); + } + + /// A namespace nobody can advertise any more is not pending, whatever happened before. + /// `deferred` outliving the want would arm the retry timer forever for a wire message + /// that can never happen: not a spin, but a session that never sleeps. + #[tokio::test(start_paused = true)] + async fn a_namespace_that_stops_being_advertisable_stops_being_deferred() { + let assigned = crate::Origin::new(777).unwrap(); + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + + // Every route flows through the peer's own identity, so split horizon says this + // must never be advertised back to it: `select` wants nothing, which is what the + // peer already holds. + let mut hops = crate::OriginList::new(); + hops.push(assigned).unwrap(); + let _echoed = origin + .create_broadcast( + "from/peer", + crate::broadcast::Route::new().with_hops(hops).with_announce(true), + ) + .unwrap(); + settle().await; + + let session = crate::lite::test_transport::SinkSession::new(Default::default()); + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + Some(assigned), + declared(Some(false)), + Version::Draft17, + ); + + // The state a refused or failed offer leaves behind: the peer holds nothing, and + // the loop is coming back to it on a timer. + let suffix: crate::PathOwned = crate::Path::new("from/peer").to_owned(); + let broadcast = origin.consume().get_broadcast("from/peer").unwrap(); + let mut watch = Watched::new(broadcast); + watch.deferred = true; + + let mut ns = Namespaces::new(cluster::Peer::default(), Target::Requests(None)); + ns.watched.insert(suffix.clone(), watch); + + publisher.sync_namespace(&mut ns, &suffix, &suffix).await.unwrap(); + + assert!( + !ns.watched[&suffix].deferred, + "the retry timer stays armed for a namespace that can never be advertised" + ); + } + + /// A minimum wait binds every path back to the namespace, not just the retry sweep. + /// A route change re-prices the advertisement; it does not excuse us from the wait the + /// peer asked for. + #[tokio::test(start_paused = true)] + async fn a_route_change_still_waits_out_a_refusal() { + const VERSION: Version = Version::Draft17; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let cam = origin + .create_broadcast("solo-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Refused with a wait far longer than any backoff the loop would take on its own. + let refusal = publish_namespace_error(VERSION, 600_000).await; + let session = + crate::lite::test_transport::ScriptedSession::per_stream(vec![refusal.clone(), refusal.clone(), refusal]); + let log = session.log.clone(); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + declared(Some(false)), + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"solo-cam") > 0 { + break; + } + settle().await; + } + assert_eq!(occurrences(&log, b"solo-cam"), 1, "the advertisement never went out"); + + // A second route makes the advertisement worth re-pricing, which is a path back + // into the reconciliation that does not go through the retry timer. + let _standby = origin + .create_broadcast("solo-cam", crate::broadcast::Route::announced()) + .unwrap(); + + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + tick().await; + } + + assert_eq!( + occurrences(&log, b"solo-cam"), + 1, + "re-offered inside the wait the peer asked for" + ); + + drop(cam); + } + + /// Draft-17+ has no PUBLISH_NAMESPACE_DONE, so a withdrawal there is the FIN and + /// nothing else. Writing the message anyway puts its type on the wire before the body + /// fails to encode, which the receiver can only read as a protocol violation, so every + /// unannounce would kill an otherwise healthy session. + /// + /// Only reachable through the unsolicited loop, which is what this branch made the + /// default: the solicited path answers inline and never opens a request per namespace. + #[tokio::test] + async fn a_modern_withdrawal_is_the_fin_alone() { + const VERSION: Version = Version::Draft17; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let cam = origin + .create_broadcast("solo-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + let session = + crate::lite::test_transport::ScriptedSession::per_stream(vec![publish_namespace_ok(VERSION).await]); + let log = session.log.clone(); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + declared(None), + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"solo-cam") > 0 { + break; + } + settle().await; + } + assert_eq!(occurrences(&log, b"solo-cam"), 1, "the advertisement never went out"); + + let advertised = log.writes.lock().unwrap().len(); + + // Unannounce, which retires the request the advertisement opened. + drop(cam); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + settle().await; + } + + assert_eq!( + log.writes.lock().unwrap().len(), + advertised, + "a draft-17+ withdrawal wrote a message; the FIN alone retracts" + ); + } + + /// The peer granting a stream is only half the exchange. One it accepts and then never + /// answers on wedges the loop exactly as a parked open does, so the response is bounded + /// too: everything queued behind it is otherwise stranded for the session. + /// + /// Draft-14 so each advertisement names its namespace on the wire. + #[tokio::test(start_paused = true)] + async fn a_silent_answer_still_lets_the_next_namespace_be_advertised() { + const VERSION: Version = Version::Draft14; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let _first = origin + .create_broadcast("first-cam", crate::broadcast::Route::announced()) + .unwrap(); + let _second = origin + .create_broadcast("second-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Every stream opens and then goes silent: an exhausted script parks rather than + // reporting EOF, which is the peer that takes the request and answers nothing. + let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![Vec::new(), Vec::new()]); + let log = session.log.clone(); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + declared(Some(false)), + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + for _ in 0..200 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"first-cam") > 0 && occurrences(&log, b"second-cam") > 0 { + break; + } + tick().await; + } + + // Whichever went first is the one that stalled, so both having reached the wire is + // the proof: the loop gave up on the answer and carried on. + assert!( + occurrences(&log, b"first-cam") > 0, + "the first advertisement never went out" + ); + assert!( + occurrences(&log, b"second-cam") > 0, + "the silent answer wedged the loop: the second namespace never went out" + ); + } + + /// Credit returning raises no signal of its own: no announce, no route change, nothing + /// the loop is watching. Only a retry brings the namespace back, and without one it + /// stays undiscoverable for the life of the session. + #[tokio::test(start_paused = true)] + async fn a_namespace_refused_a_stream_is_retried_on_its_own() { + const VERSION: Version = Version::Draft14; + + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let _cam = origin + .create_broadcast("lonely-cam", crate::broadcast::Route::announced()) + .unwrap(); + settle().await; + + // Closed from the start: the peer has granted nothing. + let gate = kio::Producer::new(false); + let ok = publish_namespace_ok(VERSION).await; + let session = crate::lite::test_transport::ScriptedSession::gated_open(vec![ok], gate.consume()); + let log = session.log.clone(); + + let publisher = Publisher::new( + session, + origin.consume(), + Control::new(None, false), + None, + declared(Some(false)), + VERSION, + ); + + let mut run = std::pin::pin!(publisher.run_publish_namespaces()); + + // Well past the point where the open gives up. + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + tick().await; + } + assert_eq!(occurrences(&log, b"lonely-cam"), 0, "advertised without a stream"); + + // Credit returns. Nothing else changes: no publish, no unannounce, no route move. + set_gate(&gate, true); + + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, b"lonely-cam") > 0 { + break; + } + tick().await; + } + assert_eq!(occurrences(&log, b"lonely-cam"), 1, "never came back on its own"); + } + + /// Advance far enough that a parked open gives up and its retry comes due, without + /// making the test wait: time is paused, so this only moves the clock the loop reads. + async fn tick() { + tokio::time::advance(std::time::Duration::from_millis(200)).await; + } + + fn set_gate(gate: &kio::Producer, open: bool) { + let Ok(mut gate) = gate.write() else { + panic!("gate closed") + }; + *gate = open; + } + /// A publisher talking to a scripted peer that never answers, over one bidi stream. struct Harness { publisher: Publisher, @@ -1669,8 +2595,8 @@ mod tests { let log = session.log.clone(); // Serving a request blocks on the peer's SETUP, which no scripted peer sends here. - let peer_setup = cluster::PeerSetup::default(); - peer_setup.set(cluster::Peer::default()); + let peer_setup = peer::PeerSetup::default(); + peer_setup.set(peer::Peer::default()); let publisher = Publisher::new( session.clone(), diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index 8cb28f8c8ad..30803eb852d 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -8,7 +8,7 @@ use crate::{ }; use super::{ - Control, Message, Publisher, Subscriber, Version, adapter::ControlStreamAdapter, cluster, + Control, Message, Publisher, Subscriber, Version, adapter::ControlStreamAdapter, cluster, peer, solicit, subscriber::is_protocol_violation, }; @@ -58,7 +58,7 @@ pub struct Config { /// What that pre-read SETUP declared, so the session does not have to parse it /// twice. `None` when [`Self::peer_setup_stream`] is. - pub peer_cluster: Option, + pub peer_declared: Option, } pub fn start( @@ -76,7 +76,7 @@ pub fn start( version, path, peer_setup_stream, - peer_cluster, + peer_declared, } = config; // GOAWAY wiring: the public Session holds one half (drain trigger, received @@ -99,14 +99,17 @@ pub fn start( let publish = publish.unwrap_or_else(|| origin::Producer::empty(Origin::random()).consume()); let subscribe = subscribe.unwrap_or_else(|| origin::Producer::empty(Origin::random())); - // The peer's cluster options. Seeded now when its SETUP was already read - // (a gated server accept), and filled by the uni loop otherwise. A version that - // cannot negotiate the extension is settled immediately so nothing blocks on it. - let peer_setup = cluster::PeerSetup::default(); - let setup_read = peer_cluster.is_some(); - match peer_cluster { - Some(peer) => peer_setup.set(peer), - None if !cluster::supported(version) => peer_setup.set(cluster::Peer::default()), + // What the peer declared in its SETUP. Seeded now when that stream was already + // read (the legacy handshake, or a gated server accept), and filled by the uni + // loop otherwise. + let peer_setup = peer::PeerSetup::default(); + let setup_read = peer_declared.is_some(); + match peer_declared { + Some(declared) => peer_setup.set(declared), + // A legacy caller that passed nothing (our own tests, and the lite paths): + // settle the slot rather than leave the announce loops waiting on a value + // that is never coming. + None if !cluster::supported(version) => peer_setup.set(peer::Peer::default()), None => {} } @@ -189,6 +192,9 @@ pub fn start( subscriber.clone(), version ))); + // Unsolicited PUBLISH_NAMESPACE unless the peer requires solicitation; + // see `Publisher::run_publish_namespaces`. + let mut pub_ns_run = std::pin::pin!(err_only(publisher.clone().run_publish_namespaces())); // One SUBSCRIBE_NAMESPACE per permitted prefix, like `lite::Subscriber`: // the scope is what we may ask for, and it is not the origin's root. let mut sub_ns_run = std::pin::pin!(err_only(async { @@ -242,6 +248,9 @@ pub fn start( if let Poll::Ready(err) = waiter.poll_future(sub_ns_run.as_mut()) { return Poll::Ready(Err(err)); } + if let Poll::Ready(err) = waiter.poll_future(pub_ns_run.as_mut()) { + return Poll::Ready(Err(err)); + } Poll::Pending }) .await @@ -317,6 +326,9 @@ pub fn start( ))); let mut goaway_recv = std::pin::pin!(err_only(goaway_recv)); let mut setup = std::pin::pin!(setup); + // Unsolicited PUBLISH_NAMESPACE unless the peer requires solicitation; + // see `Publisher::run_publish_namespaces`. + let mut pub_ns_run = std::pin::pin!(err_only(publisher.clone().run_publish_namespaces())); // One SUBSCRIBE_NAMESPACE per permitted prefix; see the draft-16 arm. let mut sub_ns_run = std::pin::pin!(err_only(async { let mut prefixes = futures::stream::FuturesUnordered::new(); @@ -363,6 +375,9 @@ pub fn start( if let Poll::Ready(err) = waiter.poll_future(sub_ns_run.as_mut()) { return Poll::Ready(Err(err)); } + if let Poll::Ready(err) = waiter.poll_future(pub_ns_run.as_mut()) { + return Poll::Ready(Err(err)); + } Poll::Pending }) .await @@ -399,8 +414,8 @@ pub struct PeerSetup { /// The request path the peer advertised, for URL-less transports. pub path: Option, - /// The MoQ Cluster options it declared (see [`cluster`]). - pub cluster: cluster::Peer, + /// The Setup Options it declared (see [`cluster`] and [`solicit`]). + pub declared: peer::Peer, } /// The Hop ID this session declares and detects loops against. @@ -449,21 +464,30 @@ pub async fn accept_setup( ), None => None, }; - let cluster = cluster::peer_from_setup(¶ms, version)?; + let declared = peer_from_params(¶ms, version)?; return Ok(PeerSetup { stream: reader, path, - cluster, + declared, }); } } -/// Parse the MoQ Cluster options out of a raw SETUP parameter block. -fn decode_peer_cluster(parameters: bytes::Bytes, version: Version) -> Result { +/// Parse the Setup Options we act on out of a raw SETUP parameter block. +fn decode_peer_setup(parameters: bytes::Bytes, version: Version) -> Result { let mut bytes = parameters; let params = ietf::Parameters::decode(&mut bytes, version)?; - cluster::peer_from_setup(¶ms, version) + peer_from_params(¶ms, version) +} + +/// The Setup Options we act on, out of an already-decoded parameter block. One place, so +/// a future option reaches both the pre-read accept path and the uni loop. +fn peer_from_params(params: &ietf::Parameters, version: Version) -> Result { + Ok(peer::Peer { + cluster: cluster::peer_from_setup(params, version)?, + solicit: solicit::from_setup(params, version)?, + }) } /// Send our SETUP on a uni stream and keep it alive: on draft-17+ this stream is @@ -471,7 +495,8 @@ fn decode_peer_cluster(parameters: bytes::Bytes, version: Version) -> Result( mut session: S, version: Version, @@ -491,6 +516,7 @@ async fn run_setup( parameters.set_bytes(ietf::ParameterBytes::Path, path.into_bytes()); } cluster::peer_into_setup(&mut parameters, self_origin, cost, version); + solicit::into_setup(&mut parameters, version); let parameters = parameters.encode_bytes(version)?; writer.encode(&setup::Setup { parameters }).await?; @@ -548,7 +574,7 @@ async fn run_unis( subscriber: Subscriber, // Where to record the peer's MoQ Cluster options once its SETUP arrives. `None` // for draft-14..16, whose SETUP rides the control stream instead. - peer_setup: Option, + peer_setup: Option, // Whether the peer's SETUP was already consumed before this loop started. setup_read: bool, version: Version, @@ -619,7 +645,7 @@ async fn run_unis( }; if let Some(peer_setup) = peer_setup { - let peer = match decode_peer_cluster(msg.parameters, version) { + let peer = match decode_peer_setup(msg.parameters, version) { Ok(peer) => peer, Err(err) => { tracing::warn!(%err, "setup parameter decode error"); @@ -685,6 +711,10 @@ async fn run_dispatch( // costs a handshake round rather than blocking. let peer = subscriber.peer().await; + // From the same slot, so this costs nothing extra: it decides whether an unsolicited + // advertisement is the peer ignoring our own SETUP (MoQ Solicit). + let declared = subscriber.solicit().await; + let mut tasks = TaskSet::owned(); let mut accept = session.clone(); loop { @@ -738,7 +768,7 @@ async fn run_dispatch( } // Subscriber handles: Publish, PublishNamespace ietf::Publish::ID | ietf::PublishNamespace::ID => { - tasks.push(subscriber.handle_stream(id, data, stream, peer)?); + tasks.push(subscriber.handle_stream(id, data, stream, peer, declared)?); } _ => { tracing::warn!(id, "unexpected bidi stream type"); @@ -872,9 +902,12 @@ mod tests { peer_setup_stream: None, // A peer that declared its Hop ID negotiated the extension, which is what // makes the cluster parameters mandatory in both directions. - peer_cluster: Some(cluster::Peer { - origin: Some(crate::Origin::new(2).unwrap()), - cost: None, + peer_declared: Some(peer::Peer { + cluster: cluster::Peer { + origin: Some(crate::Origin::new(2).unwrap()), + cost: None, + }, + ..Default::default() }), }) .expect("start the session"); @@ -921,7 +954,7 @@ mod tests { version: Version::Draft18, path: None, peer_setup_stream: None, - peer_cluster: None, + peer_declared: None, }) .expect("start the session"); let _driver = tokio::spawn(driver); @@ -939,16 +972,23 @@ mod tests { assert_eq!(occurrences(&log, b"rootns"), 0, "asked the peer for our local root"); } - /// A namespace is only advertised in response to a SUBSCRIBE_NAMESPACE. A peer - /// that never subscribes hears nothing, no matter what we announce locally. - #[tokio::test] - async fn announces_wait_for_a_subscribe_namespace() { + /// How many scheduling turns an advertisement gets before the count is taken. Time is + /// paused in these tests, so each turn costs nothing and only runs the driver until it + /// parks again; a busy machine cannot turn a slow announce into a passing silence. + const ANNOUNCE_TURNS: usize = 100; + + /// Run a publish-only session against a peer that declared `peer_declared`, returning + /// how many times the namespace reached the wire. + /// + /// The scripted peer answers nothing, so an advertisement parks after writing. That is + /// enough: the question is only whether the bytes went out unasked. + async fn announce_occurrences(peer_declared: Option) -> usize { let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); let _cam = origin .create_broadcast("solo-cam", crate::broadcast::Route::new().with_announce(true)) .unwrap(); - // An open gate: an unsolicited PUBLISH_NAMESPACE would reach the wire. + // An open gate: an unsolicited PUBLISH_NAMESPACE can reach the wire. let gate = kio::Producer::new(true); let session = crate::lite::test_transport::SinkSession::gated_bi(gate.consume()); let log = session.log.clone(); @@ -965,17 +1005,58 @@ mod tests { version: Version::Draft18, path: None, peer_setup_stream: None, - peer_cluster: None, + peer_declared, }) .expect("start the session"); let _driver = tokio::spawn(driver); - // Give an unsolicited announce every chance to land before asserting silence. - tokio::time::sleep(std::time::Duration::from_millis(50)).await; + // Drive until the announce lands, rather than betting on one fixed window. + for _ in 0..ANNOUNCE_TURNS { + if occurrences(&log, b"solo-cam") > 0 { + break; + } + tokio::time::sleep(std::time::Duration::from_millis(1)).await; + } + + occurrences(&log, b"solo-cam") + } + + /// The peer's SETUP decides whether an advertisement may go out unasked, so nothing + /// can be sent before it arrives. + #[tokio::test(start_paused = true)] + async fn no_announce_before_the_peer_setup() { + assert_eq!( + announce_occurrences(None).await, + 0, + "advertised before knowing what the peer wants" + ); + } + + /// A peer that requires solicitation hears nothing until it asks, which is the + /// behavior the IETF draft describes for a relay. + #[tokio::test(start_paused = true)] + async fn a_peer_requiring_solicitation_is_not_told_unasked() { + let declared = peer::Peer { + solicit: Some(true), + ..Default::default() + }; + assert_eq!( - occurrences(&log, b"solo-cam"), + announce_occurrences(Some(declared)).await, 0, - "PUBLISH_NAMESPACE must wait for a SUBSCRIBE_NAMESPACE" + "PUBLISH_NAMESPACE despite the peer asking to be told on request" + ); + } + + /// A peer that declared nothing is told without being asked. Every relay that never + /// sends SUBSCRIBE_NAMESPACE depends on this, and the session is what wires the + /// unsolicited loop up at all. + #[tokio::test(start_paused = true)] + async fn a_peer_declaring_nothing_is_told_unasked() { + assert_eq!( + announce_occurrences(Some(peer::Peer::default())).await, + 1, + "no unsolicited PUBLISH_NAMESPACE" ); } @@ -1032,7 +1113,7 @@ mod tests { peer_setup_stream: None, // Pre-settled, so nothing waits on a SETUP the dead stream will never // carry and the dispatch loop actually runs. - peer_cluster: Some(cluster::Peer::default()), + peer_declared: Some(peer::Peer::default()), }) .expect("start the session"); diff --git a/rs/moq-net/src/ietf/solicit.rs b/rs/moq-net/src/ietf/solicit.rs new file mode 100644 index 00000000000..8ac669341b9 --- /dev/null +++ b/rs/moq-net/src/ietf/solicit.rs @@ -0,0 +1,97 @@ +//! The MoQ Solicit extension (draft-lcurley-moq-solicit-00). +//! +//! moq-transport carries no statement of what an endpoint intends to do with a session, +//! so neither side can tell whether the other will announce, ask, both, or neither. An +//! unsolicited PUBLISH_NAMESPACE is therefore a guess: either the only thing that will +//! ever tell the peer what we have, or noise it never wanted. +//! +//! This extension lets an endpoint declare, via the SOLICIT Setup Option, that +//! advertisements to it must be solicited first. Declaring nothing means "no requirement, +//! tell me unasked", which is what every peer that has never heard of this extension +//! implicitly says, so the default is the chatty, interoperable behavior. +//! +//! The option is a plain Setup Option, so it rides every draft we speak rather than +//! needing the unified SETUP the MoQ Cluster extension does. + +use crate::coding::DecodeError; + +use super::Version; + +/// SOLICIT Setup Option: whether advertisements to the sender must be solicited. Even, so +/// the value is a bare varint. +pub const SOLICIT: u64 = 0x40B5A; + +/// What the peer declared, if anything. +/// +/// The three states are distinct, and the difference between the last two is what makes +/// the requirement enforceable: +/// +/// - `None`: no option at all. The peer has never heard of the extension, so it cannot +/// have honored ours and an unsolicited advertisement from it is expected. +/// - `Some(false)`: an explicit 0. No requirement of its own, but writing the option at +/// all proves it implements this, so it is held to ours. +/// - `Some(true)`: advertisements to it must be solicited, and likewise held to ours. +pub fn from_setup(params: &super::Parameters, _version: Version) -> Result, DecodeError> { + Ok(params + .get_varint(super::ParameterVarInt::Solicit) + .map(|value| value != 0)) +} + +/// Declare that advertisements to us must be solicited. +/// +/// Unconditional, and true of every session we open or accept: we send +/// SUBSCRIBE_NAMESPACE for every prefix we are allowed to discover, so there is nothing an +/// unsolicited PUBLISH_NAMESPACE could tell us that we will not have asked for. A peer +/// that honors it stops guessing which of the two we expect, which is the whole point. +pub fn into_setup(params: &mut super::Parameters, _version: Version) { + params.set_varint(super::ParameterVarInt::Solicit, 1); +} + +#[cfg(test)] +mod tests { + use super::*; + + const VERSION: Version = Version::Draft19; + + /// What we declare is what a peer reads back, on every draft that carries Setup + /// Options: an old peer can opt out too. + #[test] + fn every_version_round_trips() { + for version in [Version::Draft14, Version::Draft15, Version::Draft16, Version::Draft19] { + let mut params = super::super::Parameters::default(); + into_setup(&mut params, version); + assert_eq!(from_setup(¶ms, version).unwrap(), Some(true)); + } + } + + /// A peer that declared nothing wants to be told unasked, which is what keeps this + /// backward compatible with every implementation that has never heard of it. + #[test] + fn absent_declares_nothing() { + let params = super::super::Parameters::default(); + assert_eq!(from_setup(¶ms, VERSION).unwrap(), None); + } + + /// An explicit 0 asks for the same treatment an absent option does, but it is not the + /// same statement: writing the option proves the peer implements this, which is what + /// lets us hold it to our own declaration. + #[test] + fn zero_is_a_declaration_not_an_absence() { + let mut params = super::super::Parameters::default(); + params.set_varint(super::super::ParameterVarInt::Solicit, 0); + + assert_eq!(from_setup(¶ms, VERSION).unwrap(), Some(false)); + } + + /// A value this draft doesn't define still means "ask me first", so a later revision + /// that says more can't be read as saying nothing. + #[test] + fn any_non_zero_requires_solicitation() { + for value in [1, 2, 0x8000] { + let mut params = super::super::Parameters::default(); + params.set_varint(super::super::ParameterVarInt::Solicit, value); + + assert_eq!(from_setup(¶ms, VERSION).unwrap(), Some(true), "value {value}"); + } + } +} diff --git a/rs/moq-net/src/ietf/subscribe.rs b/rs/moq-net/src/ietf/subscribe.rs index 538df517b58..87a3dbd13c4 100644 --- a/rs/moq-net/src/ietf/subscribe.rs +++ b/rs/moq-net/src/ietf/subscribe.rs @@ -255,9 +255,23 @@ impl Message for SubscribeOk { _ => { // GROUP_ORDER is only legal here through draft-15, but keep accepting it so a // peer that still sends it doesn't have its session torn down over a hint. - decode_params!(r, version, - 0x22 => group_order: Option, - ); + let group_order = match version { + Version::Draft15 | Version::Draft16 => { + // LARGEST_OBJECT is required here once the track has content, but + // the session model does not currently expose the location. + decode_params!(r, version, + 0x09 => _largest_location: Option, + 0x22 => group_order: Option, + ); + group_order + } + _ => { + decode_params!(r, version, + 0x22 => group_order: Option, + ); + group_order + } + }; properties = Properties::decode(r, version)?; properties.group_order = properties.group_order.or(group_order); } @@ -632,6 +646,18 @@ mod tests { assert_eq!(decoded.request_id, Some(RequestId(42))); } + #[test] + fn test_subscribe_ok_accepts_largest_object() { + // request_id=4, track_alias=4, one LARGEST_OBJECT parameter at {5, 0}. + let payload = [0x04, 0x04, 0x01, 0x09, 0x02, 0x05, 0x00]; + for version in [Version::Draft15, Version::Draft16] { + let decoded: SubscribeOk = decode_message(&payload, version).unwrap(); + + assert_eq!(decoded.request_id, Some(RequestId(4))); + assert_eq!(decoded.track_alias, 4); + } + } + #[test] fn test_subscribe_ok_v15() { let msg = SubscribeOk { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index c59367198be..dc27fee09ab 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -13,7 +13,7 @@ use crate::{ util::{MaybeBoxedExt, MaybeSendBox, TaskSet, Tasks}, }; -use super::{Message, Version, cluster}; +use super::{Message, Version, cluster, peer}; use web_async::Lock; @@ -155,7 +155,7 @@ pub(super) struct Subscriber { // looped back through us. self_origin: crate::Origin, // What the peer declared in its SETUP. - peer_setup: cluster::PeerSetup, + peer_setup: peer::PeerSetup, // Local policy for what pulling from this peer costs, overriding whatever it // declared. See `cluster::link_cost`. cost: Option, @@ -192,7 +192,7 @@ impl Subscriber { origin: origin::Producer, control: Control, peer_origin: Option, - peer_setup: cluster::PeerSetup, + peer_setup: peer::PeerSetup, self_origin: crate::Origin, cost: Option, version: Version, @@ -218,7 +218,7 @@ impl Subscriber { /// that cannot negotiate it. See [`super::Publisher::peer`]. pub(super) async fn peer(&self) -> cluster::Peer { match cluster::supported(self.version) { - true => self.peer_setup.get().await, + true => self.peer_setup.get().await.cluster, false => cluster::Peer::default(), } } @@ -315,6 +315,10 @@ impl Subscriber { /// MOUNTS locally. Those are independent, and only coincide when the peer shares /// our namespace -- a peer outside it has never heard of our root, so a rooted /// subscriber asks for its scope and mounts the replies under the root. + /// + /// Asked unconditionally, without waiting on the peer's SETUP: a peer with nothing to + /// advertise answers with an empty set, which costs one stream, while waiting to find + /// out costs a round trip on every session. pub fn subscribe_prefixes(&self) -> Vec { self.origin.allowed().map(|p| p.to_owned()).collect() } @@ -488,15 +492,17 @@ impl Subscriber { /// Handle an incoming bidi stream dispatched by the session. /// - /// `peer` is what the peer declared in its SETUP, which the dispatcher awaited once - /// before accepting streams: PUBLISH_NAMESPACE cannot be parsed without knowing - /// whether the MoQ Cluster extension is on. + /// `peer` and `declared` are what the peer declared in its SETUP, which the dispatcher + /// awaited once before accepting streams: PUBLISH_NAMESPACE cannot be parsed without + /// knowing whether the MoQ Cluster extension is on, and `declared` says whether an + /// unsolicited one is a bug (MoQ Solicit). pub fn handle_stream( &mut self, id: u64, mut data: bytes::Bytes, stream: Stream, peer: cluster::Peer, + declared: Option, ) -> Result, Error> { let mut this = self.clone(); let task = match id { @@ -522,7 +528,7 @@ impl Subscriber { } tracing::debug!(message = ?msg, "received publish_namespace"); async move { - if let Err(err) = this.run_publish_namespace_stream(stream, msg, peer).await { + if let Err(err) = this.run_publish_namespace_stream(stream, msg, peer, declared).await { // An advertisement update is decoded here rather than in the // dispatcher, so nothing else would surface a malformed one. The // cluster draft requires closing the session on those; a stream @@ -544,16 +550,49 @@ impl Subscriber { Ok(task) } + /// What the peer declared about being solicited (MoQ Solicit). + /// + /// Read once by the dispatch loop and handed to each stream rather than awaited per + /// stream: the slot is settled by the time streams are accepted, and a stream task + /// that waited on it would park forever if it never were. + pub(super) async fn solicit(&self) -> Option { + self.peer_setup.get().await.solicit + } + + /// Whether an incoming PUBLISH_NAMESPACE means the peer ignored our SETUP. + /// + /// We always declare that advertisements to us must be solicited (MoQ Solicit), and a + /// peer that wrote the option at all proves it implements the extension, whichever + /// value it chose. It also cannot have advertised before reading our SETUP, since our + /// SETUP is what says whether advertising unasked is allowed. So this is a bug in the + /// peer, and a silent one on both sides if we tolerate it. + /// + /// Draft-14/15 are exempt: they have no inline NAMESPACE, so a PUBLISH_NAMESPACE + /// request is also how a peer answers our SUBSCRIBE_NAMESPACE there, and the message + /// alone does not say which it is. + fn unsolicited_is_a_violation(&self, declared: Option) -> bool { + match self.version { + Version::Draft14 | Version::Draft15 => false, + _ => declared.is_some(), + } + } + /// Handle an incoming PUBLISH_NAMESPACE on its bidi stream. async fn run_publish_namespace_stream( &mut self, mut stream: Stream, msg: ietf::PublishNamespace<'_>, peer: cluster::Peer, + declared: Option, ) -> Result<(), Error> { let request_id = msg.request_id; let path = msg.track_namespace.to_owned(); + if self.unsolicited_is_a_violation(declared) { + tracing::warn!(%path, "unsolicited publish_namespace from a peer that implements MoQ Solicit"); + return Err(Error::ProtocolViolation); + } + // A path that already contains our own Hop ID looped back. Reject it rather // than attaching a source we would then have to route around. let Some(advert) = self.route(msg.cluster.as_ref(), &peer) else { @@ -1449,6 +1488,72 @@ mod tests { writes.windows(needle.len()).filter(|window| *window == needle).count() } + /// What an unsolicited advertisement means to a subscriber on `version` whose peer + /// declared `solicit`. + fn unsolicited_is_a_violation(solicit: Option, version: Version) -> bool { + let origin = crate::origin::Info::new(crate::Origin::new(1).unwrap()).produce(); + let session = crate::lite::test_transport::SinkSession::new(Default::default()); + let peer_setup = peer::PeerSetup::default(); + peer_setup.set(peer::Peer { + solicit, + ..Default::default() + }); + let (tasks, _task_set) = crate::util::TaskSet::new(); + + Subscriber::new( + session, + origin, + Control::new(None, false), + None, + peer_setup, + crate::Origin::new(1).unwrap(), + None, + version, + tasks, + Default::default(), + ) + .unsolicited_is_a_violation(solicit) + } + + /// We always declare that advertisements to us must be solicited, so a peer that + /// implements the extension and announces anyway has a bug. Tolerating it is what + /// keeps that bug invisible on both sides, so the session goes. + /// + /// Writing the option is the proof of support, whichever value it carries: an explicit + /// 0 says "no requirement of my own" and still says "I read yours". + #[tokio::test] + async fn an_announce_from_a_peer_that_implements_solicit_is_fatal() { + assert!( + unsolicited_is_a_violation(Some(true), Version::Draft17), + "a peer that requires solicitation itself" + ); + assert!( + unsolicited_is_a_violation(Some(false), Version::Draft17), + "an explicit 0 declares support, so ours binds it too" + ); + } + + /// A peer that declared nothing has never heard of the extension, so it cannot have + /// honored ours. Announcing at us is what it is supposed to do, and #2730 is what + /// happens when nobody does. + #[tokio::test] + async fn an_announce_from_a_peer_that_declared_nothing_is_fine() { + assert!(!unsolicited_is_a_violation(None, Version::Draft17)); + } + + /// Draft-14/15 have no inline NAMESPACE, so a PUBLISH_NAMESPACE request is also how a + /// peer answers our own SUBSCRIBE_NAMESPACE. The message cannot say which it is, so + /// nothing there is enforceable: our own publisher advertises exactly this way. + #[tokio::test] + async fn a_legacy_announce_is_never_a_violation() { + for version in [Version::Draft14, Version::Draft15] { + assert!( + !unsolicited_is_a_violation(Some(true), version), + "{version:?} answers a subscription this way" + ); + } + } + /// A rooted subscriber asks the peer for its permitted SCOPE. The root names where /// replies mount on our side, which is meaningless to a peer outside our namespace, /// so sending it asks for a prefix that matches nothing there. @@ -1469,7 +1574,7 @@ mod tests { scoped, Control::new(None, false), None, - cluster::PeerSetup::default(), + peer::PeerSetup::default(), crate::Origin::new(1).unwrap(), None, Version::Draft16, @@ -1535,8 +1640,8 @@ mod tests { let (tasks, _task_set) = crate::util::TaskSet::new(); // Draft-18 can negotiate the cluster extension, so the subscriber waits for // the peer's SETUP before resolving advertisements; settle it as extension-off. - let peer_setup = cluster::PeerSetup::default(); - peer_setup.set(cluster::Peer::default()); + let peer_setup = peer::PeerSetup::default(); + peer_setup.set(peer::Peer::default()); let mut subscriber = Subscriber::new( session.clone(), scoped, @@ -1602,7 +1707,7 @@ mod tests { origin, Control::new(None, false), Some(assigned), - cluster::PeerSetup::default(), + peer::PeerSetup::default(), crate::Origin::new(1).unwrap(), None, Version::Draft14, @@ -1668,7 +1773,7 @@ mod tests { origin, Control::new(None, false), Some(peer), - cluster::PeerSetup::default(), + peer::PeerSetup::default(), self_origin, None, Version::Draft14, @@ -1712,7 +1817,7 @@ mod tests { origin.clone(), Control::new(None, false), Some(peer), - cluster::PeerSetup::default(), + peer::PeerSetup::default(), self_origin, None, Version::Draft14, @@ -1759,7 +1864,7 @@ mod tests { origin.clone(), Control::new(None, false), None, - cluster::PeerSetup::default(), + peer::PeerSetup::default(), self_origin, None, Version::Draft19, @@ -1884,8 +1989,8 @@ mod tests { std::mem::forget(task_set); // Draft-18 can negotiate the extension, so the read loop waits for the peer's // SETUP before parsing a NAMESPACE; settle it as extension-off. - let peer_setup = cluster::PeerSetup::default(); - peer_setup.set(cluster::Peer::default()); + let peer_setup = peer::PeerSetup::default(); + peer_setup.set(peer::Peer::default()); let mut subscriber = Subscriber::new( session.clone(), origin, @@ -1961,7 +2066,7 @@ mod tests { origin, Control::new(None, false), None, - cluster::PeerSetup::default(), + peer::PeerSetup::default(), crate::Origin::new(1).unwrap(), None, VERSION, @@ -1976,7 +2081,7 @@ mod tests { cluster: None, }; subscriber - .run_publish_namespace_stream(stream, msg, cluster::Peer::default()) + .run_publish_namespace_stream(stream, msg, cluster::Peer::default(), None) .await .expect("a withdrawal is not a protocol violation"); settle().await; @@ -2015,7 +2120,7 @@ mod tests { origin, Control::new(None, false), None, - cluster::PeerSetup::default(), + peer::PeerSetup::default(), crate::Origin::new(1).unwrap(), None, VERSION, @@ -2031,7 +2136,7 @@ mod tests { cluster: None, }; subscriber - .run_publish_namespace_stream(stream, msg, cluster::Peer::default()) + .run_publish_namespace_stream(stream, msg, cluster::Peer::default(), None) .await .expect_err("an unexpected message ends the stream"); settle().await; @@ -2324,7 +2429,7 @@ mod tests { origin, Control::new(None, false), None, - cluster::PeerSetup::default(), + peer::PeerSetup::default(), self_origin, None, VERSION, @@ -2503,7 +2608,7 @@ mod tests { origin, Control::new(None, false), None, - cluster::PeerSetup::default(), + peer::PeerSetup::default(), crate::Origin::new(1).unwrap(), None, Version::Draft19, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 7eac7e59686..fa2c574fb85 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -2313,6 +2313,12 @@ impl TrackServe { /// immediately, so a late insert races the group stream (a group whose id isn't /// in the map yet is dropped, stalling the track forever). The caller /// deregisters `id` if the establish fails. + /// + /// The subscription's bounds come straight from the demand aggregate. After a + /// route change a takeover boundary caps the *previous* segment's `end_group`; + /// the segment resuming the track keeps whatever start the subscribers asked for, + /// so a live-edge subscriber gets the live edge upstream rather than a replay of + /// the outage. fn prepare_establish( &self, producer: &mut track::Producer, diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index 5e8083412ab..6511d405a76 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -459,6 +459,11 @@ pub struct ScriptedSession { /// Per-stream scripts popped by `open_bi` in order; `None` shares `script` /// across every stream. queue: Option>>>>, + /// Set by [`Self::gated_open`]: parks `poll_open_bi` until the gate opens, standing in + /// for a peer that has granted no more concurrent streams. + open_gate: Option>, + /// Keeps the gate registration alive between `poll_open_bi` calls. + park: kio::Park, } impl ScriptedSession { @@ -468,6 +473,8 @@ impl ScriptedSession { eof: false, script: Arc::new(Mutex::new(script)), queue: None, + open_gate: None, + park: kio::Park::default(), } } @@ -490,6 +497,17 @@ impl ScriptedSession { eof: false, script: Arc::new(Mutex::new(Vec::new())), queue: Some(Arc::new(Mutex::new(scripts.into_iter().collect()))), + open_gate: None, + park: kio::Park::default(), + } + } + + /// Answer each stream from `scripts`, but only once the gate opens: a peer that + /// replies normally and is simply out of stream credit until then. + pub fn gated_open(scripts: Vec>, gate: kio::Consumer) -> Self { + Self { + open_gate: Some(gate), + ..Self::per_stream(scripts) } } } @@ -507,7 +525,19 @@ impl poll::Session for ScriptedSession { Poll::Pending } - fn poll_open_bi(&mut self, _cx: &mut Context<'_>) -> Poll, Self::Error>> { + fn poll_open_bi(&mut self, cx: &mut Context<'_>) -> Poll, Self::Error>> { + if let Some(gate) = self.open_gate.clone() { + let waiter = self.park.hold(cx); + // A closed gate reads as open: the test dropped the producer, so nothing is + // holding the stream back anymore. + if gate + .poll(waiter, |open| if **open { Poll::Ready(()) } else { Poll::Pending }) + .is_pending() + { + return Poll::Pending; + } + } + self.log.bi_opens.fetch_add(1, Ordering::Relaxed); let script = match &self.queue { Some(queue) => Arc::new(Mutex::new(queue.lock().unwrap().pop_front().unwrap_or_default())), diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index a72c211a1a7..ce028dd0244 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -867,6 +867,20 @@ impl Consumer { } } + /// Park `waiter` until the group closes (finish, abort, or eviction). Spliced + /// subscribers register on parked groups so an eviction wakes them; a group + /// that already closed cleanly can never abort, so no waiter is needed. + /// + /// A spliced group reads as closed without registering anything: no single abort + /// empties it, so [`Self::is_aborted`] can never turn true and there is nothing + /// a wakeup would change. + pub(crate) fn poll_closed(&self, waiter: &kio::Waiter) -> Poll<()> { + match &self.inner { + ConsumerKind::Plain(plain) => plain.state.poll_closed(waiter), + ConsumerKind::Spliced(_) => Poll::Ready(()), + } + } + /// The parent track's timescale. pub fn timescale(&self) -> Timescale { self.track.timescale diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 16b509c58f6..06ce9e6b184 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -8,16 +8,19 @@ //! were one track: bounds are enforced on the read side (a route delivering outside //! its range is silently filtered), a segment dying stalls the subscriber instead of //! erroring (the next [`Producer::switch`] resumes it), and demand is forwarded to -//! each underlying track intersected with its segment bounds, so a session serving a -//! segment just sees an ordinary subscription that happens to start or end at a -//! boundary. +//! each underlying track capped at its segment end, so a session serving a segment +//! just sees an ordinary subscription that happens to end at a boundary. A +//! group-aligned boundary never becomes a *start*: it says which groups this segment +//! owns, not which ones anyone wants, so a subscriber asking for the live edge still +//! asks for it after a switch. //! //! Boundaries are frame-precise, so a takeover does not have to wait for the next //! group. When one lands inside a group the subscriber has already handed out, the //! group itself is spliced: [`Group`] reads each route's copy in turn and the reader //! sees one continuous frame stream. This is what lets a track whose current group //! stays open indefinitely (a JSON append log, a catalog with deltas) survive a route -//! change at all. +//! change at all. That is the one boundary a live-edge subscriber does demand, since +//! only demand carries the frame offset the continuation has to start from. use std::collections::BTreeMap; use std::task::{Poll, ready}; @@ -50,6 +53,11 @@ impl Segment { /// One past the last position this segment produced within its own range, or /// `None` if nothing in range exists yet (out-of-range groups, e.g. a fetch into /// the track below the segment's start, don't count). + /// + /// Clamped to `end`: once the track's edge races past the cap the range + /// reads as settled through it, even if a position inside it never arrived. A + /// late arrival is still served (bounds filter reads, not access); the next + /// takeover splices above the cap either way. fn produced(&self) -> Option { let produced = self.track.resume_position()?; // Nothing in range yet. An unbounded segment starts at the very first frame, so @@ -78,6 +86,14 @@ fn slice(prefs: &Subscription, start: Option, end: Option) - /// The later of two optional start bounds, treating `None` as "the live edge" for the /// preference and "no lower bound" for the segment. Either way the other one wins. +/// +/// A takeover boundary therefore becomes demand even for a live-edge subscriber, so the +/// replacement resumes exactly where the dead route stopped and the splice loses nothing. +/// The catch-up that buys is bounded by how far the boundary trails the replacement's live +/// edge, which is failover latency: a broadcast closes with its last source (there is no +/// linger), so a takeover only happens between overlapping routes. A consumer that would +/// rather skip even that much drops it downstream on its own latency budget, which is what +/// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) means. fn max_unbounded_start(prefs: Option, segment: Option) -> Option { match (prefs, segment) { (Some(a), Some(b)) => Some(a.max(b)), @@ -120,7 +136,25 @@ impl Default for ResumeState { } } +/// A point-in-time copy of the producer state, reconciled into a +/// [`Subscriber`]'s cursor set by [`Subscriber::apply`]. +struct Snapshot { + epoch: u64, + finished: bool, + abort: Option, + segments: Vec, +} + impl ResumeState { + fn snapshot(&self) -> Snapshot { + Snapshot { + epoch: self.epoch, + finished: self.finished, + abort: self.abort.clone(), + segments: self.segments.clone(), + } + } + /// One past the newest position across the segments, clamped to their bounds: where /// a replacement segment should pick the track up. /// @@ -286,10 +320,9 @@ impl Producer { return Err(Error::Closed); } // One past the newest delivered position. With nothing delivered (or no - // segments at all) the replacement outright replaces them and starts - // unbounded, exactly like a first splice: a `Position::default()` boundary - // here would turn the subscriber's live-edge demand into a full backfill - // from group 0. + // segments at all) there is nothing to splice around, so the replacement + // replaces them outright and starts unbounded, exactly like a first splice. + // `switch` rejects a `None` start once a segment exists, hence the clear. let start = state.resume_position(); if start.is_none() { state.segments.clear(); @@ -430,6 +463,7 @@ impl Consumer { epoch: 0, finished: false, abort: None, + closed: false, segments: Vec::new(), next_sequence: 0, min_sequence: 0, @@ -524,6 +558,35 @@ pub struct Fetching { inner: web_async::Lock)>>, } +impl Fetching { + /// Poll for a segment to latch the fetch onto: the newest one, strictly newer + /// than `latched` when given. `Err` when the logical track aborted; + /// `Ok(None)` when the producer is gone with no qualifying segment, so + /// nothing will ever answer. + fn poll_latch(&self, waiter: &kio::Waiter, latched: Option) -> Poll>> { + let newest = move |segments: &[Segment]| { + segments + .last() + .filter(|segment| latched.is_none_or(|latched| segment.id > latched)) + .map(|segment| (segment.id, segment.track.clone())) + }; + match self.state.poll(waiter, |s| match (&s.abort, newest(&s.segments)) { + (Some(err), _) => Poll::Ready(Err(err.clone())), + (None, Some(next)) => Poll::Ready(Ok(next)), + (None, None) => Poll::Pending, + }) { + Poll::Ready(Ok(res)) => Poll::Ready(res.map(Some)), + // The producer is gone; whatever segment it froze with is all + // there will ever be. + Poll::Ready(Err(state)) => Poll::Ready(match &state.abort { + Some(err) => Err(err.clone()), + None => Ok(newest(&state.segments)), + }), + Poll::Pending => Poll::Pending, + } + } +} + impl kio::Pollable for Fetching { type Output = Result; @@ -533,27 +596,10 @@ impl kio::Pollable for Fetching { loop { if inner.is_none() { // Wait for the first segment; the newest wins if several arrived. - let (id, track) = match self.state.poll(waiter, |s| { - if s.abort.is_some() || !s.segments.is_empty() { - Poll::Ready(match &s.abort { - Some(err) => Err(err.clone()), - None => { - let segment = s.segments.last().expect("nonempty"); - Ok((segment.id, segment.track.clone())) - } - }) - } else { - Poll::Pending - } - }) { - Poll::Ready(Ok(res)) => res?, - // The producer is gone; use whatever segment it froze with. - Poll::Ready(Err(state)) => match (&state.abort, state.segments.last()) { - (Some(err), _) => return Poll::Ready(Err(err.clone())), - (None, Some(segment)) => (segment.id, segment.track.clone()), - (None, None) => return Poll::Ready(Err(Error::NotFound)), - }, - Poll::Pending => return Poll::Pending, + let (id, track) = match ready!(self.poll_latch(waiter, None))? { + Some(next) => next, + // The producer died without a route ever serving the track. + None => return Poll::Ready(Err(Error::NotFound)), }; let fetch = track.fetch_group(self.sequence, self.options.clone()); *inner = Some((id, track, fetch)); @@ -580,23 +626,8 @@ impl kio::Pollable for Fetching { // The latched copy failed the fetch. Fail over to a segment spliced in // above it, if any; ids are monotonic, so "newer" is a plain compare. - let latched = *latched; - let next = match self.state.poll(waiter, |s| { - if s.abort.is_some() || s.segments.last().is_some_and(|segment| segment.id > latched) { - Poll::Ready(match &s.abort { - Some(err) => Err(err.clone()), - None => { - let segment = s.segments.last().expect("checked newer"); - Ok((segment.id, segment.track.clone())) - } - }) - } else { - Poll::Pending - } - }) { - Poll::Ready(Ok(res)) => res?, - // The producer froze; no replacement can arrive. - Poll::Ready(Err(_)) => return Poll::Ready(Err(err)), + let next = match self.poll_latch(waiter, Some(*latched)) { + Poll::Ready(res) => res?, // No replacement yet, and the waiter is registered for the next // switch. A dead copy's failure is the route's, not the group's: // park for the takeover, exactly like a live subscription stalls. @@ -606,8 +637,11 @@ impl kio::Pollable for Fetching { _ => return Poll::Ready(Err(err)), }, }; - - let (id, track) = next; + // The producer froze with nothing newer spliced in: the latched + // copy's answer is final. + let Some((id, track)) = next else { + return Poll::Ready(Err(err)); + }; let fetch = track.fetch_group(self.sequence, self.options.clone()); *inner = Some((id, track, fetch)); // Loop: poll the replacement fetch in this same pass. @@ -1078,6 +1112,9 @@ enum SubState { /// boundaries. A segment's session failing does not error the subscription; it /// stalls until [`Producer::switch`] provides a replacement, or ends cleanly once /// the producer [`finish`](Producer::finish)es and the final segment completes. +/// The producer itself going away without a terminal state is an error +/// ([`Error::Dropped`]) once the remaining segments drain: with nobody left to +/// splice a replacement, a stall would never end. pub struct Subscriber { state: kio::Consumer, @@ -1090,6 +1127,10 @@ pub struct Subscriber { epoch: u64, finished: bool, abort: Option, + /// The producer is gone without a terminal state: the segment list is frozen, + /// so once it drains the read paths surface [`Error::Dropped`] (no takeover + /// can ever resume the track), mirroring a plain track's dropped producer. + closed: bool, /// Cursors over the segments, in segment order. segments: Vec, @@ -1175,7 +1216,7 @@ impl Subscriber { // the poll so its state borrow ends with this statement. let (snapshot, closed) = match self.state.poll(waiter, |state| { if state.epoch != epoch { - Poll::Ready((state.epoch, state.finished, state.abort.clone(), state.segments.clone())) + Poll::Ready(state.snapshot()) } else { Poll::Pending } @@ -1184,8 +1225,7 @@ impl Subscriber { // The producer is gone; the state is frozen, so reconcile one last // time and stop watching (existing segments can still drain). Poll::Ready(Err(state)) => { - let snapshot = (state.epoch != epoch) - .then(|| (state.epoch, state.finished, state.abort.clone(), state.segments.clone())); + let snapshot = (state.epoch != epoch).then(|| state.snapshot()); (snapshot, true) } // Unchanged, and the waiter is now registered for the next switch. @@ -1196,6 +1236,7 @@ impl Subscriber { self.apply(snapshot); } if closed { + self.closed = true; return; } // Loop: re-poll so the waiter is registered for the next change. @@ -1204,8 +1245,13 @@ impl Subscriber { /// Apply a producer snapshot: move boundaries on known segments and subscribe /// to new ones. - fn apply(&mut self, snapshot: (u64, bool, Option, Vec)) { - let (epoch, finished, abort, segments) = snapshot; + fn apply(&mut self, snapshot: Snapshot) { + let Snapshot { + epoch, + finished, + abort, + segments, + } = snapshot; self.epoch = epoch; self.finished = finished; self.abort = abort; @@ -1361,7 +1407,9 @@ impl Subscriber { /// out exactly once no matter how many routes contributed to it. /// /// Returns `Poll::Ready(Ok(None))` once the producer finished and every - /// segment completed, and `Poll::Ready(Err(_))` only if the producer aborted. + /// segment completed, and `Poll::Ready(Err(_))` if the producer aborted, or + /// was dropped without finishing and every segment has drained + /// ([`Error::Dropped`], like a plain track's dropped producer). pub fn poll_recv_group(&mut self, waiter: &kio::Waiter) -> Poll>> { self.poll_sync(waiter); @@ -1370,6 +1418,20 @@ impl Subscriber { let beyond_cap = |sequence: u64| end_sequence.is_some_and(|end| sequence > end); let mut all_done = true; + + // An eviction aborts a parked group without touching any cursor this + // subscriber polls, so each entry needs a waiter or this poll would never + // rerun. `poll_closed` observes-or-registers under one lock: `Pending` parks + // the waiter while the group is open (an open group cannot be aborted), and + // `Ready` means closed, where only an abort invalidates the entry. A cleanly + // closed group can never gain an abort, so it needs no waiter. Checking + // `is_aborted` separately from the registration would leave a window where an + // abort lands between the two and wakes nobody. + let watch = |group: &group::Consumer| match group.poll_closed(waiter) { + Poll::Pending => true, + Poll::Ready(()) => !group.is_aborted(), + }; + for index in 0..self.segments.len() { // A `start_at` overtook these parked groups; drop them and read on. // Eviction/expiry (which aborts a cached group) drops its entry too, @@ -1377,7 +1439,7 @@ impl Subscriber { // every group a long-capped subscription ever observed. self.segments[index] .parked - .retain(|sequence, group| *sequence >= min_sequence && !group.is_aborted()); + .retain(|sequence, group| *sequence >= min_sequence && watch(group)); // Re-offer the lowest parked group back inside the cap once it rises. while let Some(&sequence) = self.segments[index].parked.keys().next() { @@ -1402,8 +1464,13 @@ impl Subscriber { if beyond_cap(group.sequence) { // `end_at` holds the group until the cap rises rather than // dropping it; keep draining so an in-range group that - // arrived behind it still flows. - self.segments[index].parked.insert(group.sequence, group); + // arrived behind it still flows. Watch it from the moment it + // parks: the retain pass above already ran, so an entry + // admitted here would otherwise sit unwatched for the rest + // of this poll, and an abort could wake nobody. + if watch(&group) { + self.segments[index].parked.insert(group.sequence, group); + } continue; } if group.sequence < min_sequence { @@ -1436,8 +1503,16 @@ impl Subscriber { if let Some(err) = &self.abort { return Poll::Ready(Err(err.clone())); } - if self.finished && all_done { - return Poll::Ready(Ok(None)); + if all_done { + if self.finished { + return Poll::Ready(Ok(None)); + } + // The producer is gone without finishing: no takeover can ever + // resume the drained segments, so report the drop like a plain + // track would rather than stalling forever. + if self.closed { + return Poll::Ready(Err(Error::Dropped)); + } } Poll::Pending } @@ -1506,15 +1581,17 @@ impl Subscriber { // Drive the newest segment's activation too: a subscriber polling only // datagrams must still resolve the subscription (registering demand) and // be woken when it activates. - if let Some(seg) = self.segments.last_mut() - && Self::poll_activate(seg, &self.last_prefs, self.min_sequence, waiter).is_ready() - && let SubState::Active(sub) = &mut seg.sub - { - match sub.poll_recv_datagram(waiter) { - Poll::Ready(Ok(Some(datagram))) => return Poll::Ready(Ok(Some(datagram))), - // Terminal states fall through to the logical checks below. - Poll::Ready(_) => {} - Poll::Pending => return Poll::Pending, + let mut pending_activation = false; + if let Some(seg) = self.segments.last_mut() { + if Self::poll_activate(seg, &self.last_prefs, self.min_sequence, waiter).is_pending() { + pending_activation = true; + } else if let SubState::Active(sub) = &mut seg.sub { + match sub.poll_recv_datagram(waiter) { + Poll::Ready(Ok(Some(datagram))) => return Poll::Ready(Ok(Some(datagram))), + // Terminal states fall through to the logical checks below. + Poll::Ready(_) => {} + Poll::Pending => return Poll::Pending, + } } } @@ -1524,6 +1601,11 @@ impl Subscriber { if self.finished { return Poll::Ready(Ok(None)); } + // The newest segment can't progress and the producer is gone: no + // takeover is coming, so surface the drop rather than stalling forever. + if self.closed && !pending_activation { + return Poll::Ready(Err(Error::Dropped)); + } Poll::Pending } @@ -1543,6 +1625,10 @@ impl Subscriber { return Poll::Ready(Err(err.clone())); } if !self.finished { + // A dropped producer can never finish the logical track. + if self.closed { + return Poll::Ready(Err(Error::Dropped)); + } return Poll::Pending; } @@ -1662,6 +1748,27 @@ mod test { assert!(sub.recv_group().now_or_never().is_none(), "should have blocked"); } + /// A waker that counts its wakes, for asserting a pending poll left a live + /// registration behind. + struct CountWaker(std::sync::atomic::AtomicUsize); + + impl std::task::Wake for CountWaker { + fn wake(self: Arc) { + self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + } + } + + impl CountWaker { + fn new() -> (Arc, std::task::Waker) { + let counter = Arc::new(Self(std::sync::atomic::AtomicUsize::new(0))); + (counter.clone(), std::task::Waker::from(counter)) + } + + fn count(&self) -> usize { + self.0.load(std::sync::atomic::Ordering::SeqCst) + } + } + #[tokio::test] async fn switch_splices_groups() { let (mut track_a, consumer_a) = track_pair("a"); @@ -2068,15 +2175,7 @@ mod test { #[tokio::test] async fn consecutive_updates_wake() { - use std::sync::atomic::{AtomicUsize, Ordering}; - use std::task::{Context, Wake, Waker}; - - struct CountWaker(AtomicUsize); - impl Wake for CountWaker { - fn wake(self: Arc) { - self.0.fetch_add(1, Ordering::SeqCst); - } - } + use std::task::Context; let (track_a, consumer_a) = track_pair("a"); let mut producer = Producer::new(); @@ -2084,8 +2183,7 @@ mod test { let mut sub = producer.consume().subscribe(None); let prefs = sub.prefs(); - let counter = Arc::new(CountWaker(AtomicUsize::new(0))); - let waker = Waker::from(counter.clone()); + let (counter, waker) = CountWaker::new(); let mut cx = Context::from_waker(&waker); let mut fut = std::pin::pin!(sub.recv_group()); @@ -2093,14 +2191,14 @@ mod test { // First update wakes and is applied on the next poll. *prefs.write().ok().unwrap() = Subscription::default().with_priority(1); - assert_eq!(counter.0.load(Ordering::SeqCst), 1); + assert_eq!(counter.count(), 1); assert!(fut.as_mut().poll(&mut cx).is_pending()); assert_eq!(track_a.subscription().unwrap().priority, 1); // The poll that consumed the change must have re-registered: a second // update, with no other activity in between, still wakes. *prefs.write().ok().unwrap() = Subscription::default().with_priority(2); - assert_eq!(counter.0.load(Ordering::SeqCst), 2, "second update lost its wakeup"); + assert_eq!(counter.count(), 2, "second update lost its wakeup"); assert!(fut.as_mut().poll(&mut cx).is_pending()); assert_eq!(track_a.subscription().unwrap().priority, 2); } @@ -2294,8 +2392,11 @@ mod test { producer.takeover(&consumer_b).unwrap(); recv_pending(&mut sub); - let demand = track_b.subscription().unwrap(); - assert_eq!(demand.start, Some(Position::group(1))); + + // The boundary rolls to the next group once the current one is complete, and + // the replacement is asked to resume there. + assert_eq!(producer.resume_position(), Some(Position::group(1))); + assert_eq!(track_b.subscription().unwrap().start, Some(Position::group(1))); } /// A copy dying mid-group stalls its readers instead of erroring them, the same @@ -2529,6 +2630,68 @@ mod test { assert!(matches!(result, Err(Error::NotFound))); } + #[tokio::test] + async fn takeover_after_produced_segment_resumes_at_the_boundary() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut sub = producer.consume().subscribe(None); + recv_pending(&mut sub); + assert_eq!(track_a.subscription().unwrap().start, None); + + // A produced groups before its route died; B takes over. + write_group(&mut track_a, 0, "a0"); + write_group(&mut track_a, 1, "a1"); + assert_eq!(recv(&mut sub), 0); + assert_eq!(recv(&mut sub), 1); + drop(track_a); + producer.takeover(&consumer_b).unwrap(); + recv_pending(&mut sub); + + // A live-edge subscriber resumes at the boundary rather than at B's own live + // edge, so the splice loses nothing. What that can replay is bounded by how + // far the boundary trails B, which is failover latency; a consumer that wants + // none of it skips on its own latency budget downstream. + assert_eq!(track_b.subscription().unwrap().start, Some(Position::group(2))); + + // The segment range still filters a group below the boundary, so a replacement + // that serves one anyway never delivers it twice. + write_group(&mut track_b, 1, "b1"); + recv_pending(&mut sub); + + // Groups at the live edge still arrive past the boundary. + write_group(&mut track_b, 5, "b5"); + assert_eq!(recv(&mut sub), 5); + } + + #[tokio::test] + async fn takeover_keeps_an_explicit_start() { + let (mut track_a, consumer_a) = track_pair("a"); + let (track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut sub = producer + .consume() + .subscribe(Subscription::default().with_start(Position::group(0))); + recv_pending(&mut sub); + assert_eq!(track_a.subscription().unwrap().start, Some(Position::group(0))); + + write_group(&mut track_a, 0, "a0"); + write_group(&mut track_a, 1, "a1"); + assert_eq!(recv(&mut sub), 0); + assert_eq!(recv(&mut sub), 1); + drop(track_a); + producer.takeover(&consumer_b).unwrap(); + recv_pending(&mut sub); + + // A subscriber that asked for history keeps its gapless backfill: the + // boundary raises the explicit start to the first missing group. + assert_eq!(track_b.subscription().unwrap().start, Some(Position::group(2))); + } + #[tokio::test] async fn switch_validates_boundaries() { let (mut track_a, consumer_a) = track_pair("a"); @@ -3099,4 +3262,434 @@ mod test { // The second frame still arrives from the latched copy. assert_eq!(read(&mut reading), b"f1"); } + + #[tokio::test] + async fn switch_replaces_a_run_of_empty_segments() { + let (mut track_a, consumer_a) = track_pair("a"); + let (_track_b, consumer_b) = track_pair("b"); + let (_track_c, consumer_c) = track_pair("c"); + let (mut track_d, consumer_d) = track_pair("d"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + write_group(&mut track_a, 0, "a0"); + assert_eq!(recv(&mut sub), 0); + + // B and C splice in but die before producing anything. + producer.switch(&consumer_b, Position::group(1)).unwrap(); + producer.switch(&consumer_c, Position::group(2)).unwrap(); + + // D's boundary covers both empty segments: one switch replaces the run, + // and the group they never produced is D's to serve. + producer.switch(&consumer_d, Position::group(1)).unwrap(); + write_group(&mut track_d, 1, "d1"); + assert_eq!(recv(&mut sub), 1); + assert_eq!(producer.state.read().segments.len(), 2); + } + + #[tokio::test] + async fn abort_drains_before_erroring() { + let (mut track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + + write_group(&mut track_a, 0, "a0"); + producer.abort(Error::Cancel).unwrap(); + + // Buffered groups drain first; then the abort surfaces. Waiting on the + // end sees the abort immediately (it consumes nothing). + assert!(matches!(sub.finished().now_or_never().unwrap(), Err(Error::Cancel))); + assert_eq!(recv(&mut sub), 0); + assert!(matches!(sub.recv_group().now_or_never().unwrap(), Err(Error::Cancel))); + } + + #[tokio::test] + async fn terminal_states_are_exclusive() { + let (_track_a, consumer_a) = track_pair("a"); + let (_track_b, consumer_b) = track_pair("b"); + + // A finished track accepts no further transitions: a late abort (route + // churn re-queueing a completed track) must not error draining readers. + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + producer.finish().unwrap(); + assert!(matches!(producer.abort(Error::Cancel), Err(Error::Closed))); + assert!(matches!(producer.finish(), Err(Error::Closed))); + assert!(matches!( + producer.switch(&consumer_b, Position::group(1)), + Err(Error::Closed) + )); + assert!(matches!(producer.takeover(&consumer_b), Err(Error::Closed))); + assert!(matches!(producer.release(), Err(Error::Closed))); + + // An aborted track is just as terminal. + let mut producer = Producer::new(); + producer.abort(Error::Cancel).unwrap(); + assert!(matches!(producer.finish(), Err(Error::Closed))); + assert!(matches!(producer.abort(Error::Cancel), Err(Error::Closed))); + assert!(matches!(producer.takeover(&consumer_b), Err(Error::Closed))); + } + + #[tokio::test] + async fn dropped_producer_errors_once_drained() { + let (mut track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + + write_group(&mut track_a, 0, "a0"); + assert_eq!(recv(&mut sub), 0); + + // The segment dies, then the producer goes away without finish/abort: + // no takeover can ever come, so stalling would hang forever. + track_a.abort(Error::Cancel).unwrap(); + drop(producer); + + let result = sub.recv_group().now_or_never().expect("must not stall forever"); + assert!(matches!(result, Err(Error::Dropped))); + } + + #[tokio::test] + async fn dropped_producer_keeps_a_live_segment_serving() { + let (mut track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + drop(producer); + + // The frozen state still has a live segment: groups keep flowing. + write_group(&mut track_a, 0, "a0"); + assert_eq!(recv(&mut sub), 0); + recv_pending(&mut sub); + + // Only once that segment ends, without the logical track having + // finished, does the missing producer surface. + track_a.finish().unwrap(); + let result = sub.recv_group().now_or_never().expect("must not stall forever"); + assert!(matches!(result, Err(Error::Dropped))); + } + + #[tokio::test] + async fn dropped_producer_fails_finished_waiters() { + let (_track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + recv_pending(&mut sub); + + // The producer can never finish the logical track once dropped, so an + // end-waiter must not park forever, even while a segment is still live. + drop(producer); + let result = sub.finished().now_or_never().expect("must not stall forever"); + assert!(matches!(result, Err(Error::Dropped))); + } + + #[tokio::test] + async fn dropped_producer_ends_datagrams() { + let (track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + + // The segment is terminal and the producer is gone: a datagram-only + // poller must observe the drop, not park forever. + drop(track_a); + drop(producer); + let result = kio::wait(|waiter| sub.poll_recv_datagram(waiter)) + .now_or_never() + .expect("must not stall forever"); + assert!(matches!(result, Err(Error::Dropped))); + } + + #[tokio::test] + async fn evicted_parked_group_wakes_the_clean_end() { + use std::task::Context; + + let (mut track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + + sub.end_at(0); + write_group(&mut track_a, 0, "a0"); + let straggler = track_a.create_group(group::Info { sequence: 1 }).unwrap(); + assert_eq!(recv(&mut sub), 0); + recv_pending(&mut sub); // the straggler parks beyond the cap + + track_a.finish().unwrap(); + producer.finish().unwrap(); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut fut = std::pin::pin!(sub.recv_group()); + assert!( + fut.as_mut().poll(&mut cx).is_pending(), + "the parked group holds the end open" + ); + + // Eviction aborts the parked group behind the subscriber's back: it must + // wake and observe the clean end rather than sleeping forever. + straggler.abort(Error::Old).unwrap(); + assert!(counter.count() > 0, "the eviction wakeup was lost"); + let result = fut.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None)))); + } + + /// The counterpart of [`evicted_parked_group_wakes_the_clean_end`] with the + /// terminal states already in place when the straggler is first observed: + /// the poll that parks it is the same poll that sees the segment finish, so + /// the group must be watched from the moment it parks, not from the next + /// poll (which nothing would trigger). + #[tokio::test] + async fn straggler_parked_after_finish_still_wakes() { + use std::task::Context; + + let (mut track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + + sub.end_at(0); + write_group(&mut track_a, 0, "a0"); + assert_eq!(recv(&mut sub), 0); + + let straggler = track_a.create_group(group::Info { sequence: 1 }).unwrap(); + track_a.finish().unwrap(); + producer.finish().unwrap(); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut fut = std::pin::pin!(sub.recv_group()); + assert!( + fut.as_mut().poll(&mut cx).is_pending(), + "the parked group holds the end open" + ); + + straggler.abort(Error::Old).unwrap(); + assert!(counter.count() > 0, "the abort wakeup was lost"); + assert!(matches!(fut.as_mut().poll(&mut cx), Poll::Ready(Ok(None)))); + } + + #[tokio::test] + async fn release_restarts_unbounded() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + write_group(&mut track_a, 7, "a7"); + assert!(producer.is_spliced()); + + // Nobody is reading: release the segments, keeping the track alive. + producer.release().unwrap(); + assert!(!producer.is_spliced()); + assert_eq!(producer.resume_position(), None); + + // The next takeover starts unbounded: a fresh reader gets the live edge + // even below the old numbering (the source may have restarted). + producer.takeover(&consumer_b).unwrap(); + let mut sub = producer.consume().subscribe(None); + recv_pending(&mut sub); + assert_eq!(track_b.subscription().unwrap().start, None); + write_group(&mut track_b, 2, "b2"); + assert_eq!(recv(&mut sub), 2); + } + + #[tokio::test] + async fn release_resets_the_pruned_floor() { + let mut producer = Producer::new(); + + // Enough takeovers that the front segments prune, leaving a floor. + let count = 2 * MAX_SEGMENTS as u64; + let mut tracks = Vec::new(); + for sequence in 0..count { + let (mut track, consumer) = track_pair("t"); + producer.takeover(&consumer).unwrap(); + write_group(&mut track, sequence, "g"); + tracks.push(track); + } + producer.release().unwrap(); + + // The old numbering went with the segments: a restarted source's low + // sequences must not be filtered by the stale floor. + let (mut track, consumer) = track_pair("fresh"); + producer.takeover(&consumer).unwrap(); + let mut sub = producer.consume().subscribe(None); + write_group(&mut track, 0, "g0"); + assert_eq!(recv(&mut sub), 0); + } + + #[tokio::test] + async fn fetch_fails_when_the_producer_dies_segmentless() { + let producer = Producer::new(); + let consumer = producer.consume(); + + // No segment yet: the fetch waits for a route to serve the track. + let fetch = consumer.fetch_group(0, None); + let mut fetch = std::pin::pin!(fetch); + assert!(futures::poll!(fetch.as_mut()).is_pending(), "fetch should wait"); + + // The producer dies without one ever arriving: nothing can serve it. + drop(producer); + assert!(matches!(fetch.await, Err(Error::NotFound))); + } + + #[tokio::test] + async fn info_fails_when_the_producer_dies_segmentless() { + let producer = Producer::new(); + let consumer = producer.consume(); + + let info = consumer.info(); + let mut info = std::pin::pin!(info); + assert!(futures::poll!(info.as_mut()).is_pending(), "info should wait"); + + drop(producer); + assert!(matches!(info.await, Err(Error::Dropped))); + } + + #[tokio::test] + async fn start_at_drops_parked_groups_below_the_floor() { + let (mut track_a, consumer_a) = track_pair("a"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + + sub.end_at(0); + write_group(&mut track_a, 0, "a0"); + write_group(&mut track_a, 1, "a1"); + write_group(&mut track_a, 2, "a2"); + assert_eq!(recv(&mut sub), 0); + recv_pending(&mut sub); // groups 1 and 2 park beyond the cap + + // The reader skips ahead: the parked range below the floor is dropped, + // while the parked group at the floor is still re-offered. + sub.start_at(2); + sub.end_at(None); + assert_eq!(recv(&mut sub), 2, "group 1 was overtaken by start_at"); + recv_pending(&mut sub); + } + + #[tokio::test] + async fn demand_intersects_subscriber_end_with_boundary() { + let (track_a, consumer_a) = track_pair("a"); + let (track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe( + Subscription::default() + .with_start(Position::group(0)) + .with_end(Position::after_group(3)), + ); + recv_pending(&mut sub); + assert_eq!(track_a.subscription().unwrap().end, Position::after_group(3)); + + producer.switch(&consumer_b, Position::group(2)).unwrap(); + recv_pending(&mut sub); + + // The old segment's demand caps at whichever end is tighter (here the + // boundary); the new one keeps the subscriber's own end. + assert_eq!(track_a.subscription().unwrap().end, Some(Position::group(2))); + assert_eq!(track_b.subscription().unwrap().end, Position::after_group(3)); + } + + #[tokio::test] + async fn subscribers_read_independently() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let consumer = producer.consume(); + let mut sub1 = consumer.subscribe(None); + let mut sub2 = consumer.subscribe(None); + recv_pending(&mut sub1); + recv_pending(&mut sub2); + + write_group(&mut track_a, 0, "a0"); + producer.switch(&consumer_b, Position::group(1)).unwrap(); + write_group(&mut track_b, 1, "b1"); + + // Each subscriber holds its own cursors over the shared segments. + assert_eq!(recv(&mut sub1), 0); + assert_eq!(recv(&mut sub1), 1); + assert_eq!(recv(&mut sub2), 0); + assert_eq!(recv(&mut sub2), 1); + assert!(sub1.is_clone(&sub2)); + } + + #[tokio::test] + async fn latest_clamps_to_segment_bounds() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let consumer = producer.consume(); + assert_eq!(consumer.latest(), None); + + write_group(&mut track_a, 0, "a0"); + assert_eq!(consumer.latest(), Some(0)); + + producer.switch(&consumer_b, Position::group(2)).unwrap(); + + // The old route races past its cap: the logical edge stays clamped to + // the segment's range (its owed range is settled once the track's edge + // passes the cap, even if some groups in it never arrived). + write_group(&mut track_a, 5, "a5"); + assert_eq!(consumer.latest(), Some(1)); + + // A below-boundary group on the new route (unbounded demand racing the + // splice) doesn't drag the edge backwards either. + write_group(&mut track_b, 0, "b0"); + assert_eq!(consumer.latest(), Some(1)); + + write_group(&mut track_b, 3, "b3"); + assert_eq!(consumer.latest(), Some(3)); + } + + #[tokio::test] + async fn datagrams_come_from_the_newest_segment() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + assert!( + kio::wait(|waiter| sub.poll_recv_datagram(waiter)) + .now_or_never() + .is_none(), + "no datagram yet" + ); + + producer.switch(&consumer_b, Position::group(1)).unwrap(); + + // Datagrams are a live best-effort channel: one from a replaced segment + // is stale and never surfaces, only the live route's flow does. + track_a.append_datagram(Timestamp::ZERO, b"old".as_ref()).unwrap(); + assert!( + kio::wait(|waiter| sub.poll_recv_datagram(waiter)) + .now_or_never() + .is_none(), + "stale datagram must not surface" + ); + track_b.append_datagram(Timestamp::ZERO, b"new".as_ref()).unwrap(); + let datagram = kio::wait(|waiter| sub.poll_recv_datagram(waiter)) + .now_or_never() + .expect("datagram should be ready") + .expect("should not error") + .expect("track should not be finished"); + assert_eq!(&datagram.payload[..], b"new"); + } } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index d832fd003da..0b2b4f21ccb 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2470,12 +2470,25 @@ impl PlainSubscriber { } fn poll_recv_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + // An eviction aborts a parked group without touching any cursor this + // subscriber polls, so each entry needs a waiter or this poll would never + // rerun. `poll_closed` observes-or-registers under one lock: `Pending` + // parks the waiter while the group is open (an open group cannot be + // aborted), and `Ready` means closed, where only an abort invalidates the + // entry. Checking `is_aborted` separately from the registration would leave + // a window where an abort lands between the two and wakes nobody. + let watch = |group: &group::Consumer| match group.poll_closed(waiter) { + Poll::Pending => true, + Poll::Ready(()) => !group.is_aborted(), + }; + // A raised `start_at` drops parked groups it overtook, and eviction/expiry // (which aborts a cached group) drops its parked entry. The latter is what // bounds parking: a subscription capped indefinitely holds only what the // track's cache policy still retains, not every group it ever observed. + let min_sequence = self.min_sequence; self.parked - .retain(|sequence, group| *sequence >= self.min_sequence && !group.is_aborted()); + .retain(|sequence, group| *sequence >= min_sequence && watch(group)); // Re-offer the lowest parked group back inside the cap once it rises. if let Some(&sequence) = self.parked.keys().next() @@ -2500,7 +2513,12 @@ impl PlainSubscriber { // Park a group beyond the cap instead of dropping it, and keep scanning // so an in-range group that arrived behind it still flows. if self.end_sequence.is_some_and(|end| consumer.sequence > end) { - self.parked.insert(consumer.sequence, consumer); + // Watch it from the moment it parks: the retain pass above already + // ran, so an entry admitted here would otherwise sit unwatched for + // the rest of this poll, and an abort could wake nobody. + if watch(&consumer) { + self.parked.insert(consumer.sequence, consumer); + } continue; } return Poll::Ready(Ok(Some(consumer))); @@ -4335,6 +4353,51 @@ mod test { ); } + /// Eviction aborts a parked group behind a sleeping subscriber's back. Nothing + /// else will poll it (the track already finished), so the entry has to carry a + /// waiter or the subscription sleeps forever holding its stream open. + #[tokio::test] + async fn evicted_parked_group_wakes_the_clean_end() { + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::task::{Context, Wake}; + + /// A waker that counts its wakes, for asserting a pending poll left a live + /// registration behind. + struct CountWaker(AtomicUsize); + impl Wake for CountWaker { + fn wake(self: std::sync::Arc) { + self.0.fetch_add(1, Ordering::SeqCst); + } + } + + let mut producer = track_producer("test", None); + let mut consumer = producer.subscribe(None); + + producer.create_group(group::Info { sequence: 0 }).unwrap(); + assert_eq!( + consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, + 0 + ); + + consumer.end_at(0); + let straggler = producer.create_group(group::Info { sequence: 1 }).unwrap(); + assert!(consumer.recv_group().now_or_never().is_none(), "parked at the cap"); + producer.finish().unwrap(); + + let counter = std::sync::Arc::new(CountWaker(AtomicUsize::new(0))); + let waker = std::task::Waker::from(counter.clone()); + let mut cx = Context::from_waker(&waker); + let mut fut = std::pin::pin!(consumer.recv_group()); + assert!( + fut.as_mut().poll(&mut cx).is_pending(), + "the parked group holds it open" + ); + + straggler.abort(Error::Old).unwrap(); + assert!(counter.0.load(Ordering::SeqCst) > 0, "the eviction wakeup was lost"); + assert!(matches!(fut.as_mut().poll(&mut cx), Poll::Ready(Ok(None)))); + } + #[tokio::test] async fn read_frame_returns_single_frame_per_group() { let mut producer = track_producer("test", None); diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 73816468242..240821106e1 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -199,7 +199,7 @@ impl Server { // Pull the request path and max request ID out now (IETF only) so `ok()` // doesn't re-decode the consumed parameters. moq-transport carries the path // in its SETUP just like lite-05. - let (path, request_id_max) = match version { + let (path, request_id_max, peer_declared) = match version { Version::Ietf(v) => { let params = ietf::Parameters::decode(&mut client.parameters, v)?; let path = match params.get_bytes(ietf::ParameterBytes::Path) { @@ -213,9 +213,13 @@ impl Server { let request_id_max = params .get_varint(ietf::ParameterVarInt::MaxRequestId) .map(ietf::RequestId); - (path, request_id_max) + let peer_declared = ietf::peer::Peer { + solicit: ietf::solicit::from_setup(¶ms, v)?, + ..Default::default() + }; + (path, request_id_max, peer_declared) } - Version::Lite(_) => (None, None), + Version::Lite(_) => (None, None, ietf::peer::Peer::default()), }; Ok(Request { @@ -229,6 +233,7 @@ impl Server { stream, version, request_id_max, + peer_declared, }, }), }) @@ -247,7 +252,11 @@ impl Server { role: None, // A moq-transport peer only has an identity if it negotiated the MoQ // Cluster extension and declared a non-zero Hop ID. - origin: peer_setup.cluster.origin.filter(|o| *o != crate::Origin::UNKNOWN), + origin: peer_setup + .declared + .cluster + .origin + .filter(|o| *o != crate::Origin::UNKNOWN), inner: Some(RequestInner { server: self.clone(), handshake: Handshake::IetfModern { @@ -302,6 +311,8 @@ enum Handshake { stream: Stream, version: Version, request_id_max: Option, + /// What the client's SETUP declared, for the options `ok()` acts on. + peer_declared: ietf::peer::Peer, }, /// moq-lite 05+: the client's Setup Stream has been read. `ok()` starts the /// session, seeding the SETUP back so PROBE gating resolves. @@ -382,7 +393,7 @@ impl Request { let publish = server.publish.map(|origin| origin.with_stats(server.stats.clone())); let subscribe = server.subscribe.map(|origin| origin.with_stats(server.stats.clone())); - let (session, mut stream, version, request_id_max) = match handshake { + let (session, mut stream, version, request_id_max, peer_declared) = match handshake { Handshake::IetfModern { session, version, @@ -403,7 +414,7 @@ impl Request { version, path: None, peer_setup_stream: Some(peer_setup.stream), - peer_cluster: Some(peer_setup.cluster), + peer_declared: Some(peer_setup.declared), })?; tracing::debug!(?version, "connected"); return Ok(Session::new(session, version.into(), None, protocol, goaway)); @@ -465,7 +476,8 @@ impl Request { stream, version, request_id_max, - } => (session, stream, version, request_id_max), + peer_declared, + } => (session, stream, version, request_id_max, peer_declared), }; // Encode parameters using the version-appropriate type. @@ -474,6 +486,7 @@ impl Request { let mut parameters = ietf::Parameters::default(); parameters.set_varint(ietf::ParameterVarInt::MaxRequestId, u32::MAX as u64); parameters.set_bytes(ietf::ParameterBytes::Implementation, b"moq-lite-rs".to_vec()); + ietf::solicit::into_setup(&mut parameters, v); parameters.encode_bytes(v)? } Version::Lite(v) => lite::Parameters::default().encode_bytes(v)?, @@ -516,7 +529,7 @@ impl Request { version: v, path: None, peer_setup_stream: None, - peer_cluster: None, + peer_declared: Some(peer_declared), })?; (None, protocol, goaway) } diff --git a/rs/moq-relay/CHANGELOG.md b/rs/moq-relay/CHANGELOG.md index de4f0ce58df..e26091348c7 100644 --- a/rs/moq-relay/CHANGELOG.md +++ b/rs/moq-relay/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.14.10](https://github.com/moq-dev/moq/compare/moq-relay-v0.14.9...moq-relay-v0.14.10) - 2026-08-13 + +### Added + +- *(bindings)* expose incoming request path and query ([#2738](https://github.com/moq-dev/moq/pull/2738)) + ## [0.14.9](https://github.com/moq-dev/moq/compare/moq-relay-v0.14.8...moq-relay-v0.14.9) - 2026-08-07 ### Fixed diff --git a/rs/moq-relay/Cargo.toml b/rs/moq-relay/Cargo.toml index c76275de425..bfba215771a 100644 --- a/rs/moq-relay/Cargo.toml +++ b/rs/moq-relay/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.14.9" +version = "0.14.10" edition = "2024" # sysinfo 0.39 (cache governor cgroup limits) needs 1.95, above the 1.91 # workspace floor. moq-relay is lib+bin, so this applies to its library target diff --git a/rs/moq-transcode/CHANGELOG.md b/rs/moq-transcode/CHANGELOG.md index c27ae1f5354..73a42904364 100644 --- a/rs/moq-transcode/CHANGELOG.md +++ b/rs/moq-transcode/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.10](https://github.com/moq-dev/moq/compare/moq-transcode-v0.0.9...moq-transcode-v0.0.10) - 2026-08-13 + +### Added + +- *(moq-video)* advertise the catalog rendition before the first keyframe ([#2768](https://github.com/moq-dev/moq/pull/2768)) + ## [0.0.9](https://github.com/moq-dev/moq/compare/moq-transcode-v0.0.8...moq-transcode-v0.0.9) - 2026-08-07 ### Other diff --git a/rs/moq-transcode/Cargo.toml b/rs/moq-transcode/Cargo.toml index f7fa50a9c79..76656823570 100644 --- a/rs/moq-transcode/Cargo.toml +++ b/rs/moq-transcode/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.0.9" +version = "0.0.10" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-transcode/src/catalog.rs b/rs/moq-transcode/src/catalog.rs index bf549239728..102847ca35f 100644 --- a/rs/moq-transcode/src/catalog.rs +++ b/rs/moq-transcode/src/catalog.rs @@ -1,7 +1,7 @@ //! Derivative catalog construction: pick the source rendition, size the ladder //! against it, and fill the output catalog with rung + passthrough entries. -use hang::catalog::{AV1, H264, Video, VideoCodec, VideoConfig}; +use hang::catalog::{AV1, Video, VideoCodec, VideoConfig}; use moq_net::PathRelativeOwned; use crate::{Error, Rung}; @@ -27,11 +27,24 @@ pub(crate) fn choose_source(video: &Video) -> Result<(String, VideoConfig), Erro // through this one; composing relative references is a follow-up. .filter(|(_, config)| config.broadcast.is_none()) .filter(|(_, config)| can_decode(config)) + // A publisher can advertise its codec before it knows its picture: a capture whose camera + // hasn't been opened publishes a rendition with no dimensions, and the first keyframe fills + // them in. There is no ladder to derive from that yet, so leave it for a later snapshot + // rather than choosing it and failing on geometry. + .filter(|(_, config)| dimensions(config).is_some()) .max_by_key(|(_, config)| (config.coded_height, config.coded_width, config.bitrate)) .map(|(name, config)| (name.clone(), config.clone())) .ok_or(Error::NoSource) } +/// The source geometry a ladder can be sized against, if it's known at all. +fn dimensions(config: &VideoConfig) -> Option<(u64, u64)> { + match (config.coded_width, config.coded_height) { + (Some(w), Some(h)) if w > 0 && h > 0 => Some((w as u64, h as u64)), + _ => None, + } +} + fn can_decode(config: &VideoConfig) -> bool { match &config.codec { VideoCodec::H264(_) | VideoCodec::H265(_) => true, @@ -47,9 +60,8 @@ fn is_supported_av1(av1: &AV1) -> bool { /// Resolve the configured rungs against the source: derive geometry from the /// source aspect ratio and drop any rung that isn't strictly below the source. pub(crate) fn resolve_rungs(rungs: &[Rung], source_name: &str, source: &VideoConfig) -> Result, Error> { - let (source_width, source_height) = match (source.coded_width, source.coded_height) { - (Some(w), Some(h)) if w > 0 && h > 0 => (w as u64, h as u64), - _ => return Err(Error::SourceDimensions(source_name.to_string())), + let Some((source_width, source_height)) = dimensions(source) else { + return Err(Error::SourceDimensions(source_name.to_string())); }; let framerate = source .framerate @@ -93,26 +105,25 @@ pub(crate) fn resolve_rungs(rungs: &[Rung], source_name: &str, source: &VideoCon Ok(resolved) } -/// The catalog entry for a resolved rung. +/// The catalog entry for a resolved rung, probed from a throwaway encoder at the rung's geometry. /// -/// The codec string is computed from the ladder, not the bitstream, so the -/// catalog can be published before any encoder exists and stays deterministic: -/// avc3 (in-band parameter sets, matching what every `moq-video` backend -/// emits), High profile (a superset of what any backend produces, so decoder -/// capability checks pass), and the level from the Table A-1 lookup. -pub(crate) fn rung_entry(rung: &Resolved, source: &VideoConfig) -> VideoConfig { - let mut config = VideoConfig::new(H264 { - inline: true, - profile: 0x64, - constraints: 0, - level: h264_level(rung.size.width, rung.size.height, rung.framerate, rung.bitrate), - }); - config.coded_width = Some(rung.size.width); - config.coded_height = Some(rung.size.height); +/// The ladder is published before any rung has been encoded (a rung is only encoded once someone +/// asks for it), and nothing ever refines these entries from a bitstream the way an importer would. +/// So the codec string has to be right the first time: it is read back out of the encoder that will +/// serve the rung rather than guessed from the ladder. +pub(crate) async fn rung_entry( + rung: &Resolved, + source: &VideoConfig, + encoder: &moq_video::encode::Kind, +) -> Result { + let mut config = moq_video::encode::Config::new(rung.size.width, rung.size.height, rung.framerate); config.bitrate = Some(rung.bitrate); - config.framerate = Some(rung.framerate as f64); - config.optimize_for_latency = source.optimize_for_latency; - config + config.kind = encoder.clone(); + + let mut entry = config.probe().await?; + // A property of the source rather than the ladder: every rung shows the same picture. + entry.optimize_for_latency = source.optimize_for_latency; + Ok(entry) } /// Fill the derivative catalog: rung entries plus, when `source_rel` is set, @@ -168,43 +179,10 @@ pub(crate) fn populate( Ok(()) } -/// The smallest H.264 level (Table A-1) that fits the given geometry, frame -/// rate, and bitrate, as a `level_idc` (level 3.1 -> 31, printed `1f` in the -/// codec string). -fn h264_level(width: u32, height: u32, framerate: u32, bitrate: u64) -> u8 { - // (level_idc, MaxMBPS, MaxFS, MaxBR in kbit/s at the Baseline/Main factor). - const LEVELS: &[(u8, u64, u64, u64)] = &[ - (10, 1_485, 99, 64), - (11, 3_000, 396, 192), - (12, 6_000, 396, 384), - (13, 11_880, 396, 768), - (20, 11_880, 396, 2_000), - (21, 19_800, 792, 4_000), - (22, 20_250, 1_620, 4_000), - (30, 40_500, 1_620, 10_000), - (31, 108_000, 3_600, 14_000), - (32, 216_000, 5_120, 20_000), - (40, 245_760, 8_192, 20_000), - (41, 245_760, 8_192, 50_000), - (42, 522_240, 8_704, 50_000), - (50, 589_824, 22_080, 135_000), - (51, 983_040, 36_864, 240_000), - (52, 2_073_600, 36_864, 240_000), - ]; - - let macroblocks = width.div_ceil(16) as u64 * height.div_ceil(16) as u64; - let macroblocks_per_sec = macroblocks * framerate as u64; - for &(idc, max_mbps, max_fs, max_br) in LEVELS { - // High profile raises the bitrate cap by cpbBrVclFactor 1250/1000. - if macroblocks <= max_fs && macroblocks_per_sec <= max_mbps && bitrate <= max_br * 1250 { - return idc; - } - } - 52 -} - #[cfg(test)] mod tests { + use hang::catalog::H264; + use super::*; fn source(width: u32, height: u32, bitrate: Option) -> VideoConfig { @@ -269,6 +247,27 @@ mod tests { assert_eq!(resolved[0].size, moq_video::Size::new(202, 360)); } + /// A publisher that advertises its codec before opening its camera has no dimensions yet, and + /// `run` keeps waiting for a snapshot it can use. Choosing that rendition instead would fail on + /// geometry and terminate the transcode before any rung could create the demand that opens the + /// camera in the first place. + #[test] + fn dimensionless_rendition_is_not_a_source_yet() { + let mut provisional = source(0, 0, None); + provisional.coded_width = None; + provisional.coded_height = None; + + let mut video = Video::default(); + video.renditions.insert("video".to_string(), provisional.clone()); + assert!(matches!(choose_source(&video), Err(Error::NoSource))); + + // The keyframe fills the geometry in, and the same rendition becomes usable. + video.renditions.insert("video".to_string(), source(1920, 1080, None)); + let (name, chosen) = choose_source(&video).unwrap(); + assert_eq!(name, "video"); + assert_eq!(chosen.coded_width, Some(1920)); + } + #[test] fn source_needs_dimensions() { let mut config = source(0, 0, Some(1_000_000)); @@ -280,17 +279,38 @@ mod tests { )); } - #[test] - fn level_lookup() { - // 640x360 @ 30fps is 920 MBs * 30 = 27600 MB/s: past level 2.2's 20250, - // so it lands on level 3.0. - assert_eq!(h264_level(640, 360, 30, 600_000), 30); - // 1080p30 at 5 Mbit/s needs level 4.0 for the frame size. - assert_eq!(h264_level(1920, 1080, 30, 5_000_000), 40); - // 1080p60 pushes the MB rate past level 4.0 into 4.2. - assert_eq!(h264_level(1920, 1080, 60, 5_000_000), 42); - // Absurd input clamps to the highest level. - assert_eq!(h264_level(8192, 8192, 120, u64::MAX), 52); + /// A rung's entry describes the rung, not the source: the codec string's level and every + /// dimension come from what this rung will encode, since a player picks between rungs on + /// exactly those fields before a single frame exists. + #[tokio::test] + async fn rung_entry_describes_the_rung() { + let rung = Resolved { + name: "video/360p".to_string(), + size: moq_video::Size::new(640, 360), + bitrate: 600_000, + framerate: 30, + }; + let mut source = source(1920, 1080, Some(6_000_000)); + source.optimize_for_latency = Some(true); + + // Software (openh264) so the probe is deterministic and never touches a hardware backend. + let entry = rung_entry(&rung, &source, &moq_video::encode::Kind::Software) + .await + .unwrap(); + + // Read out of the encoder that will serve this rung, so the entry describes the rung rather + // than the source: a player picks between rungs on exactly these fields, before a single + // frame of any of them exists. + let hang::catalog::VideoCodec::H264(h264) = &entry.codec else { + panic!("expected H.264, got {}", entry.codec) + }; + assert!(h264.inline, "an avc3 rung carries its parameter sets in band"); + assert_eq!(entry.coded_width, Some(640)); + assert_eq!(entry.coded_height, Some(360)); + assert_eq!(entry.bitrate, Some(600_000)); + assert_eq!(entry.framerate, Some(30.0)); + // Inherited from the source: latency is a property of the stream, not the ladder. + assert_eq!(entry.optimize_for_latency, Some(true)); } #[test] diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index fc821edba8a..6a9291a00dc 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -81,10 +81,11 @@ pub async fn run( // Publish the derivative catalog before any encoder exists, so subscribers // can pick a rung immediately. - let entries: Vec<_> = rungs - .iter() - .map(|rung| (rung.name.clone(), catalog::rung_entry(rung, &source_config))) - .collect(); + let mut entries = Vec::with_capacity(rungs.len()); + for rung in &rungs { + let entry = catalog::rung_entry(rung, &source_config, &config.encoder).await?; + entries.push((rung.name.clone(), entry)); + } { let mut guard = derived.lock(); catalog::populate(&mut guard, &snapshot, &entries, config.source.as_ref())?; diff --git a/rs/moq-video/CHANGELOG.md b/rs/moq-video/CHANGELOG.md index 064a0ed4a1c..6ad935daeca 100644 --- a/rs/moq-video/CHANGELOG.md +++ b/rs/moq-video/CHANGELOG.md @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.16](https://github.com/moq-dev/moq/compare/moq-video-v0.0.15...moq-video-v0.0.16) - 2026-08-13 + +### Added + +- *(moq-video)* advertise the catalog rendition before the first keyframe ([#2768](https://github.com/moq-dev/moq/pull/2768)) + +### Fixed + +- *(release)* repair native package releases ([#2731](https://github.com/moq-dev/moq/pull/2731)) +- *(moq-ffi)* support iOS simulator builds ([#2710](https://github.com/moq-dev/moq/pull/2710)) + ## [0.0.15](https://github.com/moq-dev/moq/compare/moq-video-v0.0.14...moq-video-v0.0.15) - 2026-08-07 ### Added diff --git a/rs/moq-video/Cargo.toml b/rs/moq-video/Cargo.toml index d5b9b714d92..7f163cdc131 100644 --- a/rs/moq-video/Cargo.toml +++ b/rs/moq-video/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.0.15" +version = "0.0.16" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index 00f50c75d04..1d9973d13d7 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -84,19 +84,20 @@ impl Consumer { mod tests { use super::*; use crate::decode::Kind; - use crate::encode::{Codec, Config as EncodeConfig, Encoder, Kind as EncodeKind, Producer as EncodeProducer}; + use crate::encode::{Config as EncodeConfig, Encoder, Kind as EncodeKind, Producer as EncodeProducer}; #[tokio::test] async fn reads_cmaf_container_declared_by_catalog() { let mut source_broadcast = moq_net::broadcast::Info::new().produce(); let source_subscriber = source_broadcast.consume(); let source_catalog = moq_mux::catalog::Producer::new(&mut source_broadcast).unwrap(); - let mut producer = EncodeProducer::new(source_broadcast, source_catalog, Codec::H264).unwrap(); - let mut encoder = Encoder::new(&EncodeConfig { + let config = EncodeConfig { kind: EncodeKind::Software, ..EncodeConfig::new(320, 240, 30) - }) - .unwrap(); + }; + let rendition = config.probe().await.unwrap(); + let mut producer = EncodeProducer::new(source_broadcast, source_catalog, rendition).unwrap(); + let mut encoder = Encoder::new(&config).unwrap(); let rgba = vec![0x80u8; 320 * 240 * 4]; for index in 0..2 { encoder.keyframe(); diff --git a/rs/moq-video/src/encode/encoder.rs b/rs/moq-video/src/encode/encoder.rs index bc81fa653b0..c9f2cd6957b 100644 --- a/rs/moq-video/src/encode/encoder.rs +++ b/rs/moq-video/src/encode/encoder.rs @@ -97,6 +97,66 @@ impl Config { Size::new(self.width, self.height) } + /// The catalog rendition an encoder for this config produces. + /// + /// Resolved by opening a throwaway encoder and encoding one frame, so the profile, level, and + /// constraints are the ones this machine writes into the bitstream rather than a guess. The + /// backend picks all three itself (VideoToolbox asks for High, openh264 leaves it at Baseline, + /// VAAPI writes Main) and its choice depends on the config it opened with, so reading them back + /// is the only way to know. + /// + /// This is what lets a track be advertised before it carries anything: a subscriber can only + /// discover a track the catalog names, and an on-demand encoder only encodes once a subscriber + /// arrives. Publishing the probed rendition breaks that cycle without publishing a claim that + /// has to be corrected later, since it already says what the first keyframe will say. + /// + /// Costs an encoder open and a single frame, so call it once per track. Call it *before* + /// opening the encoder you will actually use, so the two never hold a codec session at once. + /// + /// # Errors + /// + /// Fails when this machine cannot encode the config at all, which makes it a fail-fast check: + /// better here than on the first frame of a track that is already advertised. + pub async fn probe(&self) -> Result { + // A `Sink` rather than an `Encoder`: this runs on whatever executor thread the caller is on, + // and the Windows backend's COM apartment has to be opened and closed on one thread. + let mut sink = super::Sink::open(self).await?; + + // Mid-gray, since the picture only has to make the encoder emit its parameter sets. + let size = self.size(); + let i420 = crate::I420::new( + size.width, + size.height, + vec![0x80u8; crate::I420::len(size.width, size.height)], + )?; + let frame = Frame::new(crate::Surface::I420(i420), moq_net::Timestamp::from_micros(0)?); + + sink.keyframe(); + let mut encoded = sink.encode(frame).await?; + // A backend that pipelines holds the first frame, so drain it rather than reading nothing. + if encoded.is_empty() { + encoded = sink.flush().await?; + } + + let annexb: Vec = encoded.iter().flat_map(|frame| frame.payload.iter().copied()).collect(); + let parsed = match self.codec { + Codec::H264 => moq_mux::codec::h264::config(&annexb), + Codec::H265 => moq_mux::codec::h265::config(&annexb), + }; + let mut rendition = parsed.map_err(|err| { + Error::Codec(anyhow::anyhow!( + "{} emitted no usable parameter sets: {err}", + sink.name() + )) + })?; + + // Neither is in the bitstream: the target bitrate is nowhere in it, and the framerate only + // rides in an optional VUI. Fill them from the config that produced the rest. + rendition.bitrate.get_or_insert(self.resolved_bitrate()); + rendition.framerate.get_or_insert(self.framerate.into()); + Ok(rendition) + } + /// Resolved input color space: explicit override, or the size-based guess /// every player makes for an untagged stream. Backends write this into the /// VUI; the crate's RGB conversions pick the same answer for the same size, @@ -107,14 +167,17 @@ impl Config { /// Resolved bitrate: explicit override, or a pixels-per-second estimate. pub(crate) fn resolved_bitrate(&self) -> u64 { - self.bitrate.unwrap_or_else(|| { - // 0.07 bits per pixel per second matches the JS publisher's - // default and lands ~4.4 Mbps for 1080p30. - ((self.size().pixels() * self.framerate as u64) as f64 * 0.07) as u64 - }) + self.bitrate + .unwrap_or_else(|| default_bitrate(self.size(), self.framerate)) } } +/// The bitrate an unconfigured encode resolves to: 0.07 bits per pixel per second, which matches +/// the JS publisher's default and lands ~4.4 Mbps for 1080p30. +pub(crate) fn default_bitrate(size: Size, framerate: u32) -> u64 { + ((size.pixels() * framerate as u64) as f64 * 0.07) as u64 +} + /// Video encoder. Build one with [`Encoder::new`], feed it raw [`Frame`]s via /// [`encode`](Self::encode), and publish the resulting [`Encoded`] access units /// through a [`Producer`](super::Producer) built for the same [`Codec`]. diff --git a/rs/moq-video/src/encode/mod.rs b/rs/moq-video/src/encode/mod.rs index bcdb9af6379..a5f74f01c97 100644 --- a/rs/moq-video/src/encode/mod.rs +++ b/rs/moq-video/src/encode/mod.rs @@ -14,6 +14,11 @@ //! that migrates between workers). //! - [`Producer`] alone publishes frames you already encoded. //! +//! A [`Producer`] advertises its catalog rendition as soon as the track exists, +//! resolved from the encoder itself via [`Config::probe`], so a subscriber can +//! discover a track nothing has encoded yet. That's what makes on-demand +//! encoding possible at all. +//! //! [`Options`] / [`Kind`] / [`Config`] configure them. The decode/consume //! counterpart (mirror of `moq-audio`'s consumer) lives in the sibling //! [`decode`](crate::decode) module. diff --git a/rs/moq-video/src/encode/producer.rs b/rs/moq-video/src/encode/producer.rs index 38ed3f54417..2ac36d52b5f 100644 --- a/rs/moq-video/src/encode/producer.rs +++ b/rs/moq-video/src/encode/producer.rs @@ -1,9 +1,11 @@ //! Publish encoded video frames as a moq video track, with optional capture. //! -//! Encoding is strictly on demand: the track and catalog entry are advertised -//! immediately, but the camera stays closed (LED off, no CPU) until a subscriber -//! appears. When the last viewer leaves, the camera is released again. This -//! mirrors `moq-boy`, which pauses its emulator on `track::Producer::used()` / +//! Encoding is strictly on demand: the track and its catalog rendition are +//! advertised immediately (the rendition is probed from the encoder, since +//! nothing has been encoded yet), and the encoder itself only runs while a +//! subscriber is watching. Capture opens its camera once at startup to learn +//! the mode it negotiates, then keeps it closed between viewers. This mirrors +//! `moq-boy`, which pauses its emulator on `track::Producer::used()` / //! `unused()`. #[cfg(feature = "capture")] @@ -24,6 +26,7 @@ use super::Encoded; use super::Sink; #[cfg(any(feature = "capture", test))] use super::encoder; +#[cfg(feature = "capture")] use super::encoder::Codec; #[cfg(feature = "capture")] use super::rate::{Control, Policy}; @@ -32,6 +35,26 @@ use super::rate::{Control, Policy}; #[cfg(feature = "capture")] const DEFAULT_FRAMERATE: u32 = 30; +/// The rendition as the importer wants it: what to publish now, and what to keep filling in on +/// every config it later resolves from the bitstream. +/// +/// A probed rendition is what the first keyframe carries, so the importer's own config matches it +/// field for field and the catalog is published once rather than corrected. The fields the +/// bitstream can't reveal (bitrate always, framerate outside an optional VUI) are the ones this +/// overlay keeps supplying. +fn rendition_hint(rendition: hang::catalog::VideoConfig) -> moq_mux::catalog::VideoHint { + let mut hint = moq_mux::catalog::VideoHint::default(); + hint.codec = Some(rendition.codec); + hint.coded_width = rendition.coded_width; + hint.coded_height = rendition.coded_height; + hint.display_aspect_width = rendition.display_aspect_width; + hint.display_aspect_height = rendition.display_aspect_height; + hint.framerate = rendition.framerate; + hint.bitrate = rendition.bitrate; + hint.optimize_for_latency = rendition.optimize_for_latency; + hint +} + /// Per-codec splitter + importer pair. Each codec frames its packets and resolves /// its catalog rendition differently, so the producer holds one of these. enum Codecs { @@ -60,29 +83,43 @@ pub struct Producer { } impl Producer { - /// Publish a track for `codec` into `broadcast`, registering its rendition - /// in `catalog`. The frames fed to [`publish`](Self::publish) must be in - /// that codec's framing (the matching [`Encoder`](super::Encoder) emits it). + /// Publish a track carrying `rendition` into `broadcast`, registering it in + /// `catalog`. The frames fed to [`publish`](Self::publish) must be in that + /// codec's framing, which is what the [`Encoder`](super::Encoder) the + /// rendition was probed from emits. + /// + /// `rendition` comes from [`Config::probe`](super::Config::probe), so it is + /// what the encoder will actually emit rather than a guess. It is published + /// immediately, before anything is encoded, which is what lets a subscriber + /// discover a track an on-demand encoder has not run for yet; because it + /// already says what the first keyframe says, that keyframe confirms the + /// catalog instead of correcting it. pub fn new( mut broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer, - codec: Codec, + rendition: hang::catalog::VideoConfig, ) -> Result { - let codecs = match codec { - Codec::H264 => { + let codecs = match &rendition.codec { + hang::catalog::VideoCodec::H264(_) => { let track = broadcast.unique_track(".avc3", catalog.track_info())?; Codecs::H264 { split: moq_mux::codec::h264::Split::new(), - import: moq_mux::codec::h264::Import::new(track, catalog.reserve(), Default::default())?, + import: moq_mux::codec::h264::Import::new(track, catalog.reserve(), rendition_hint(rendition))?, } } - Codec::H265 => { + hang::catalog::VideoCodec::H265(_) => { let track = broadcast.unique_track(".hev1", catalog.track_info())?; Codecs::H265 { split: moq_mux::codec::h265::Split::new(), - import: moq_mux::codec::h265::Import::new(track, catalog.reserve(), Default::default())?, + import: moq_mux::codec::h265::Import::new(track, catalog.reserve(), rendition_hint(rendition))?, } } + // Unreachable via `Config::probe`, which only encodes what `Codec` covers. + other => { + return Err(Error::Codec(anyhow::anyhow!( + "{other} is not a codec this producer can publish" + ))); + } }; Ok(Self { codecs }) } @@ -209,10 +246,14 @@ impl std::fmt::Debug for Options { /// Capture a webcam and publish it as an on-demand video track. /// /// Returns when the broadcast is dropped (the track stops being announced) -/// or the capture loop fails. The camera is opened only while at least one -/// subscriber is watching; frames are stamped from `clock`, so passing the +/// or the capture loop fails. Frames are stamped from `clock`, so passing the /// same [`Clock`](moq_mux::Clock) to a concurrent audio publish keeps the two /// tracks aligned. +/// +/// The camera is opened once at startup to probe the mode it negotiates, then released until a +/// subscriber arrives and reopened for as long as one is watching. That one open is what lets the +/// catalog rendition be exact before a single frame is published, so a consumer can size itself +/// against it (and discover the track at all) without waiting for an encoder that may never run. #[cfg(feature = "capture")] pub async fn publish_capture( broadcast: moq_net::broadcast::Producer, @@ -227,7 +268,27 @@ pub async fn publish_capture( return Err(Error::InvalidFramerate(0)); } - let mut producer = Producer::new(broadcast, catalog, encode.codec)?; + // Open the camera once to find out what it actually negotiated, since a requested size is only a + // hint (macOS ignores it outright) and the encoder is built from the mode, not the request. It + // closes again immediately: this costs one camera open at startup and buys a rendition that says + // exactly what the stream will carry, rather than one every consumer has to treat as provisional. + let rendition = { + let camera = capture::open(&capture).await?; + let mut probe_config = encoder::Config::new( + camera.width(), + camera.height(), + capture + .framerate + .or_else(|| camera.framerate()) + .unwrap_or(DEFAULT_FRAMERATE), + ); + probe_config.bitrate = encode.bitrate; + probe_config.codec = encode.codec; + probe_config.kind = encode.kind.clone(); + probe_config.probe().await? + }; + + let mut producer = Producer::new(broadcast, catalog, rendition)?; let demand = producer.demand(); let result = capture_loop(&mut producer, &demand, &capture, &encode, &clock).await; @@ -332,10 +393,8 @@ fn log_track_ended(err: moq_net::Error) { } } -/// Async capture/encode loop. Captures one frame up front to populate the -/// catalog (the codec/resolution only exist once the encoder has produced an -/// SPS), then releases the camera whenever the last viewer leaves and reopens it -/// when one returns. +/// Async capture/encode loop. Opens the camera while at least one viewer is +/// watching and releases it when the last one leaves. /// /// Cancel safety: every wait here is a real `.await` (a frame read, a demand /// transition, or an encode), so dropping this future (e.g. on Ctrl+C) drops @@ -351,19 +410,13 @@ async fn capture_loop( encode: &Options, clock: &moq_mux::Clock, ) -> Result<(), Error> { - // The catalog video rendition only appears once a frame has been encoded (the - // importer reads the SPS). Until then we capture regardless of demand so a - // catalog-driven subscriber can discover the track and trigger `used()`. - // After that we release the camera while unwatched. - let mut catalog_ready = false; - loop { - if catalog_ready { - // Idle until a viewer subscribes; the track ending is a clean exit. - if let Err(err) = demand.used().await { - log_track_ended(err); - return Ok(()); - } + // Idle until a viewer subscribes; the track ending is a clean exit. The + // catalog rendition was published when the track was created, so a + // subscriber can get here without a frame ever having been encoded. + if let Err(err) = demand.used().await { + log_track_ended(err); + return Ok(()); } // Open the camera and an encoder sized to its negotiated mode. @@ -395,29 +448,25 @@ async fn capture_loop( .map(|bandwidth| (bandwidth, Control::new(Policy::new(encoder_config.resolved_bitrate())))); loop { - // While watched, race the next frame against the last viewer leaving so - // we release the camera promptly when demand drops. `biased` checks - // demand first so an unwatched track stops before reading another frame. - let frame = if catalog_ready { - tokio::select! { - biased; - res = demand.unused() => { - if let Err(err) = res { - log_track_ended(err); - return Ok(()); - } - break; // no viewers: release the camera, then wait for one + // Race the next frame against the last viewer leaving so we release the + // camera promptly when demand drops. `biased` checks demand first so an + // unwatched track stops before reading another frame. + let frame = tokio::select! { + biased; + res = demand.unused() => { + if let Err(err) = res { + log_track_ended(err); + return Ok(()); } - // Retune between frames rather than mid-encode, and only when - // the policy says the target actually moved. - estimate = next_estimate(&mut rate) => { - apply_estimate(&mut encoder, &mut rate, estimate).await; - continue; - } - frame = camera.read() => frame, + break; // no viewers: release the camera, then wait for one + } + // Retune between frames rather than mid-encode, and only when + // the policy says the target actually moved. + estimate = next_estimate(&mut rate) => { + apply_estimate(&mut encoder, &mut rate, estimate).await; + continue; } - } else { - camera.read().await + frame = camera.read() => frame, }; let Some(surface) = frame else { break }; // device stopped producing frames @@ -429,43 +478,42 @@ async fn capture_loop( encoder.keyframe(); force_keyframe = false; } - let encoded = encoder.encode(frame).await?; - // Once the encoder emits a frame the importer has parsed the SPS and - // the catalog rendition exists, so demand gating can take over. - catalog_ready |= !encoded.is_empty(); - producer.publish(&encoded)?; + producer.publish(&encoder.encode(frame).await?)?; } // Drop the camera (LED off) and encoder before waiting for the next viewer. drop(camera); - if catalog_ready { - tracing::info!("no viewers: released camera"); - } + tracing::info!("no viewers: released camera"); } } #[cfg(test)] mod tests { + use moq_mux::catalog::Stream as _; + use super::*; use crate::encode::{Config, Encoder}; - /// Encode a handful of synthetic frames for `codec` and publish them through a - /// real [`Producer`], returning the catalog rendition's track name. The - /// rendition only appears once the matching importer parses the codec config - /// out of the encoded keyframe, so a returned name proves the whole - /// encode -> split -> import -> catalog path works for that codec. + /// Encode a handful of synthetic frames for `codec` and publish them through a real + /// [`Producer`], returning the catalog rendition's track name and config. /// - /// `kind` is explicit so the test picks a deterministic encoder rather than - /// `Auto`, which on Linux CI would try the NVENC backend and panic in cudarc - /// on a GPU-less runner. - async fn roundtrip_rendition(codec: Codec, kind: encoder::Kind) -> String { + /// Asserts the property the whole design rests on: the rendition published before anything is + /// encoded is the one the first keyframe resolves. A guessed codec string would be corrected + /// here; a probed one is confirmed, so the catalog is written once. + /// + /// `kind` is explicit so the test picks a deterministic encoder rather than `Auto`, which on + /// Linux CI would try the NVENC backend and panic in cudarc on a GPU-less runner. + async fn roundtrip_rendition(codec: Codec, kind: encoder::Kind) -> (String, hang::catalog::VideoConfig) { let mut broadcast = moq_net::broadcast::Info::new().produce(); let catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); - let mut producer = Producer::new(broadcast, catalog.clone(), codec).unwrap(); let mut config = Config::new(320, 240, 30); config.codec = codec; config.kind = kind; + + let mut producer = Producer::new(broadcast, catalog.clone(), config.probe().await.unwrap()).unwrap(); + let advertised = rendition(&catalog).expect("the rendition publishes before any frame").1; + let mut encoder = Encoder::new(&config).unwrap(); assert_eq!(encoder.codec(), codec); @@ -477,25 +525,79 @@ mod tests { } producer.publish(&encoder.finish().unwrap()).unwrap(); + let (name, resolved) = rendition(&catalog).expect("the importer should have registered a video rendition"); + // Jitter aside, which is measured from the frames rather than declared by either. + let (mut before, mut after) = (advertised, resolved.clone()); + before.jitter = None; + after.jitter = None; + assert_eq!( + before, after, + "the first keyframe should confirm the advertised rendition, not correct it" + ); + (name, resolved) + } + + /// The catalog's single video rendition, if it has one yet. + fn rendition(catalog: &moq_mux::catalog::Producer) -> Option<(String, hang::catalog::VideoConfig)> { let snapshot = catalog.snapshot(); - snapshot + let (name, config) = snapshot.video.renditions.iter().next()?; + Some((name.clone(), config.clone())) + } + + /// Regression: the rendition has to reach the wire before anything is encoded. + /// + /// A catalog reservation is held until the rendition resolves, and an unresolved one withholds + /// the whole catalog from the broadcast. An encoder that runs only while watched then closes a + /// cycle: the catalog waits on a keyframe, the keyframe waits on a subscriber, and the + /// subscriber waits on the catalog. Nothing errors on either side; the publisher simply serves + /// nothing, forever. + #[tokio::test] + async fn the_rendition_reaches_the_wire_before_the_first_frame() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); + + let mut config = Config::new(1920, 1080, 30); + config.bitrate = Some(6_000_000); + // Software (openh264) so the test is deterministic and never touches a hardware backend. + config.kind = encoder::Kind::Software; + let _producer = Producer::new(broadcast, catalog, config.probe().await.unwrap()).unwrap(); + + // Published, not merely staged: this reads the catalog track a subscriber would. + let mut stream = moq_mux::catalog::Consumer::<()>::new(&consumer, moq_mux::catalog::CatalogFormat::Hang) + .await + .unwrap(); + let snapshot = stream.next().await.unwrap().expect("a catalog before any frame"); + + let (name, rendition) = snapshot .video .renditions - .keys() + .iter() .next() - .cloned() - .expect("the importer should have registered a video rendition") + .expect("the track must be discoverable before it has encoded anything"); + assert!(name.ends_with(".avc3")); + + // Read out of the encoder rather than guessed: the avc3 shape (parameter sets in band) and + // the geometry it was opened at, which is what its first keyframe will carry. + let hang::catalog::VideoCodec::H264(h264) = &rendition.codec else { + panic!("expected H.264, got {}", rendition.codec) + }; + assert!(h264.inline, "an avc3 track carries its parameter sets in band"); + assert_eq!(rendition.coded_width, Some(1920)); + assert_eq!(rendition.coded_height, Some(1080)); + // Neither is in the bitstream, so both come from the config that was probed. + assert_eq!(rendition.framerate, Some(30.0)); + assert_eq!(rendition.bitrate, Some(6_000_000)); } #[tokio::test] async fn h264_roundtrip_publishes_avc3() { // Software (openh264) so the test is deterministic and never touches a // hardware backend. - assert!( - roundtrip_rendition(Codec::H264, encoder::Kind::Software) - .await - .ends_with(".avc3") - ); + let (name, config) = roundtrip_rendition(Codec::H264, encoder::Kind::Software).await; + assert!(name.ends_with(".avc3")); + assert_eq!(config.coded_width, Some(320)); + assert_eq!(config.coded_height, Some(240)); } /// H.265 has no software encoder, so this only runs where a hardware one @@ -503,10 +605,9 @@ mod tests { #[cfg(target_os = "macos")] #[tokio::test] async fn h265_roundtrip_publishes_hev1() { - assert!( - roundtrip_rendition(Codec::H265, encoder::Kind::Hardware) - .await - .ends_with(".hev1") - ); + let (name, config) = roundtrip_rendition(Codec::H265, encoder::Kind::Hardware).await; + assert!(name.ends_with(".hev1")); + assert_eq!(config.coded_width, Some(320)); + assert_eq!(config.coded_height, Some(240)); } } diff --git a/rs/moq-video/src/frame.rs b/rs/moq-video/src/frame.rs index 27dd23ea7a4..06f3a5e154e 100644 --- a/rs/moq-video/src/frame.rs +++ b/rs/moq-video/src/frame.rs @@ -454,7 +454,7 @@ impl I420 { /// Convert tightly-packed RGB (`width * height * 3` bytes) to I420 in /// [`Color::infer`]'s color space for this size. Used for MJPEG capture /// (Linux V4L2), which decodes to RGB. - #[cfg(target_os = "linux")] + #[cfg(all(target_os = "linux", feature = "capture"))] pub(crate) fn from_rgb(rgb: &[u8], width: u32, height: u32) -> Result { use yuv::rgb_to_yuv420; @@ -469,7 +469,7 @@ impl I420 { /// Convert packed YUYV (YUV 4:2:2, `stride` bytes per row) to I420. A chroma /// resample (4:2:2 -> 4:2:0), no color-space conversion. Used for the raw /// V4L2 capture path (Linux). - #[cfg(target_os = "linux")] + #[cfg(all(target_os = "linux", feature = "capture"))] pub(crate) fn from_yuyv(yuyv: &[u8], stride: u32, width: u32, height: u32) -> Result { use yuv::{YuvPackedImage, yuyv422_to_yuv420}; @@ -2081,7 +2081,7 @@ mod tests { /// 4:2:0 chroma resample must not claim it is BT.601: a 720p camera is /// usually BT.709, and mislabeling pins it to the wrong matrix instead of /// letting the resolution heuristic get it right. - #[cfg(target_os = "linux")] + #[cfg(all(target_os = "linux", feature = "capture"))] #[test] fn yuyv_capture_keeps_its_color_space_open() { let (width, height) = (1280, 720); diff --git a/rs/moq-video/src/lib.rs b/rs/moq-video/src/lib.rs index 582e7a80d48..86927be584d 100644 --- a/rs/moq-video/src/lib.rs +++ b/rs/moq-video/src/lib.rs @@ -24,8 +24,9 @@ //! Media Foundation / NVENC). Two entry points: //! - `encode::publish_capture` captures a webcam and publishes it (turnkey). //! It encodes strictly on demand: the track and catalog are advertised up -//! front, but the camera opens only while a subscriber is watching and is -//! released when the last one leaves. It requires the `capture` feature. +//! front (the camera opens once at startup so they can be exact), and the +//! encoder runs only while a subscriber is watching. Requires the `capture` +//! feature. //! - [`encode::Encoder`] encodes [`Frame`]s you supply (from capture, a //! decoder, or your own pixels via [`Surface::rgba`]) and //! [`encode::Producer`] publishes the results. diff --git a/rs/moq-wasm/src/transport.rs b/rs/moq-wasm/src/transport.rs index e977d79af97..f08f7c1b2ab 100644 --- a/rs/moq-wasm/src/transport.rs +++ b/rs/moq-wasm/src/transport.rs @@ -97,9 +97,16 @@ pub struct Options { pub server_certificate_hashes: Vec>, } +/// Advertise every version `moq-net` supports, so the peer picks one via ALPN. +/// Without this the browser negotiates no subprotocol and the session has no +/// version to start from. +fn builder() -> web_transport_wasm::ClientBuilder { + web_transport_wasm::ClientBuilder::new().with_protocols(moq_net::ALPNS.iter().copied()) +} + /// Open a browser WebTransport connection to `url`. pub async fn connect(url: Url, options: Options) -> Result { - let client = web_transport_wasm::ClientBuilder::new(); + let client = builder(); let client = match options.server_certificate_hashes.is_empty() { true => client.with_system_roots(), false => client.with_server_certificate_hashes(options.server_certificate_hashes), @@ -214,7 +221,9 @@ impl wtt::poll::Session for Session { } fn protocol(&self) -> Option<&str> { - self.inner.protocol() + // The browser reports "" when no subprotocol was negotiated, which means the + // same thing as `None`: fall back to negotiating the version over SETUP. + self.inner.protocol().filter(|p| !p.is_empty()) } fn close(&mut self, code: u32, reason: &str) { diff --git a/swift/README.md b/swift/README.md index ca84fc1eeab..7cb6246266b 100644 --- a/swift/README.md +++ b/swift/README.md @@ -16,7 +16,7 @@ The Swift integration ships as two SPM packages, each mirrored to its own repo: ## Install ```swift -.package(url: "https://github.com/moq-dev/moq-swift", from: "0.4.3"), +.package(url: "https://github.com/moq-dev/moq-swift", from: "0.4.4"), ``` SPM resolves `MoqFFI` (and its prebuilt `MoqFFI.xcframework`, attached to the matching `moq-ffi-v*` GitHub Release) transitively. You only depend on `moq-swift`. diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 9b2daa5cdba..6b0d956eeeb 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -43,6 +43,23 @@ public final class BroadcastConsumer: Sendable { GroupConsumer(try await ffi.fetchGroup(name: name, sequence: sequence, options: options)) } + /// Fetch one complete group and decode its track container into media frames. + public func fetchMediaGroup( + name: String, + sequence: UInt64, + container: Container, + options: FetchGroupOptions? = nil + ) async throws -> MediaGroupConsumer { + MediaGroupConsumer( + try await ffi.fetchMediaGroup( + name: name, + sequence: sequence, + container: container, + options: options + ) + ) + } + /// Subscribe to a media track, delivering frames in decode order. `container` /// comes from the catalog. `subscription` tunes delivery priority, group ordering /// priority, group range, and the latency budget; omit for defaults. Raise @@ -219,8 +236,9 @@ public final class BroadcastProducer: Sendable { /// encoded (H.264 or H.265) inside the FFI boundary per `input`/`output`. /// /// The track is named after the codec (`.avc3` / `.hev1`) and its catalog - /// rendition appears once the first keyframe has been encoded, so - /// subscribers discover it through the catalog rather than a name you pick. + /// rendition is published immediately, read out of the encoder itself, so + /// subscribers discover it through the catalog rather than a name you pick, + /// and can find it before the first frame exists. public func publishVideo(input: VideoEncoderInput, output: VideoEncoderOutput) throws -> VideoProducer { VideoProducer(try ffi.publishVideo(input: input, output: output)) } diff --git a/swift/Sources/Moq/Media.swift b/swift/Sources/Moq/Media.swift index fafacbda54f..890dd6b495d 100644 --- a/swift/Sources/Moq/Media.swift +++ b/swift/Sources/Moq/Media.swift @@ -60,6 +60,40 @@ public final class MediaConsumer: AsyncSequence, Sendable { } } +/// A finite, container-decoded media group returned by ``BroadcastConsumer/fetchMediaGroup(name:sequence:container:options:)``. +public final class MediaGroupConsumer: AsyncSequence, Sendable { + /// The decoded media frame emitted by this sequence. + public typealias Element = MediaFrame + + let ffi: MoqMediaGroupConsumer + + init(_ ffi: MoqMediaGroupConsumer) { + self.ffi = ffi + } + + /// The sequence number of this group within the track. + public var sequence: UInt64 { + ffi.sequence() + } + + /// The next frame, or `nil` once the group ends. + public func next() async throws -> MediaFrame? { + try await ffi.next() + } + + /// Cancel all current and future reads. + public func cancel() { + ffi.cancel() + } + + /// Create an iterator that cancels native reads when iteration ends. + public func makeAsyncIterator() -> AsyncThrowingStream.Iterator { + moqStream(cancel: { [ffi] in ffi.cancel() }) { [ffi] in + try await ffi.next() + }.makeAsyncIterator() + } +} + /// Write side of a media track fed pre-framed payloads. public final class MediaProducer: Sendable { let ffi: MoqMediaProducer diff --git a/swift/VERSION b/swift/VERSION index 17b2ccd9bf9..6f2743d65dc 100644 --- a/swift/VERSION +++ b/swift/VERSION @@ -1 +1 @@ -0.4.3 +0.4.4 diff --git a/swift/scripts/check.sh b/swift/scripts/check.sh index 4ef95a9f7a3..d168e48ff96 100755 --- a/swift/scripts/check.sh +++ b/swift/scripts/check.sh @@ -40,15 +40,28 @@ if [[ "${DEVELOPER_DIR:-}" == /nix/store/* ]]; then fi HOST_TARGET=$(rustc -vV | awk '/^host:/ {print $2}') +# Debug by default. This is a compile-and-test gate, not a benchmark, and a +# release build of moq-ffi shares no artifacts with the debug ones `just check` +# and `just test` already produce, so it was a third full compile of the +# dependency tree (~5 min of CI on its own, plus a whole target/release tree on +# a runner that was already tight on disk). Set MOQ_FFI_PROFILE=release for an +# optimized cdylib; the shipped artifacts are built by rs/moq-ffi/build.sh, +# which is release regardless. +PROFILE="${MOQ_FFI_PROFILE:-debug}" +# Expanded as ${CARGO_PROFILE[@]+...} at the use sites: macOS ships bash 3.2, +# where expanding an empty array under `set -u` is an "unbound variable" error. +CARGO_PROFILE=() +[[ "$PROFILE" == "release" ]] && CARGO_PROFILE=(--release) + echo "swift check: building moq-ffi for $HOST_TARGET..." -cargo build --release --package moq-ffi \ +cargo build ${CARGO_PROFILE[@]+"${CARGO_PROFILE[@]}"} --package moq-ffi \ --manifest-path "$WORKSPACE_DIR/Cargo.toml" TARGET_BASE=$(cargo metadata --format-version 1 --manifest-path "$WORKSPACE_DIR/Cargo.toml" --no-deps | sed -n 's/.*"target_directory":"\([^"]*\)".*/\1/p') -CDYLIB="$TARGET_BASE/release/libmoq_ffi.dylib" -STATIC="$TARGET_BASE/release/libmoq_ffi.a" +CDYLIB="$TARGET_BASE/$PROFILE/libmoq_ffi.dylib" +STATIC="$TARGET_BASE/$PROFILE/libmoq_ffi.a" [[ -f "$CDYLIB" && -f "$STATIC" ]] || { echo "swift check: missing $CDYLIB or $STATIC" >&2 exit 1 @@ -57,7 +70,7 @@ STATIC="$TARGET_BASE/release/libmoq_ffi.a" # Generate bindings. BINDGEN_OUT=$(mktemp -d) trap 'rm -rf "$BINDGEN_OUT"' EXIT -cargo run --release --package moq-ffi --bin uniffi-bindgen \ +cargo run ${CARGO_PROFILE[@]+"${CARGO_PROFILE[@]}"} --package moq-ffi --bin uniffi-bindgen \ --manifest-path "$WORKSPACE_DIR/Cargo.toml" -- \ generate --library "$CDYLIB" --language swift --out-dir "$BINDGEN_OUT" diff --git a/uv.lock b/uv.lock index 7753ee106da..49c49b21507 100644 --- a/uv.lock +++ b/uv.lock @@ -103,7 +103,7 @@ source = { editable = "py/moq-ffi" } [[package]] name = "moq-rs" -version = "0.4.3" +version = "0.4.4" source = { editable = "py/moq-rs" } dependencies = [ { name = "moq-ffi" },