diff --git a/.github/actions/just/action.yml b/.github/actions/just/action.yml new file mode 100644 index 00000000000..a41f055151a --- /dev/null +++ b/.github/actions/just/action.yml @@ -0,0 +1,11 @@ +name: Install just +description: Install the pinned just for jobs outside the nix dev shell, which already provides it. + +runs: + using: composite + steps: + # A checksum-verified prebuilt, so it costs seconds rather than a + # `cargo install`. Keep the version in step with nixpkgs' just in flake.lock. + - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 + with: + tool: just@1.58.0 diff --git a/.github/actions/rust-cache/action.yml b/.github/actions/rust-cache/action.yml index 572c730101a..43727027141 100644 --- a/.github/actions/rust-cache/action.yml +++ b/.github/actions/rust-cache/action.yml @@ -12,6 +12,8 @@ inputs: runs: using: composite steps: + # The pinned action saves in a post step guarded by success(), so failed + # builds cannot publish a cache even when dispatch saving is enabled. - uses: jdx/mr-boxington-action@7234d3dd1a6ca8f6c381eea8e4dfb03f18fcf777 # v1.3.0 with: version: 1.10.0 diff --git a/.github/justfile b/.github/justfile index f341da77296..1bccfc53380 100644 --- a/.github/justfile +++ b/.github/justfile @@ -1,13 +1,40 @@ -set fallback +set working-directory := '..' -# actionlint is skipped when absent locally; the root `_tools` preflight makes -# it a hard requirement under MOQ_STRICT, so CI can't skip it. - -# Lint GitHub Actions workflows. +# Lint GitHub Actions workflows, their alert coverage, and that every step runs a recipe. check: - python3 {{ source_directory() }}/scripts/install-formula.test.py - {{ source_directory() }}/scripts/release.test.sh - @if command -v nfpm >/dev/null 2>&1 && command -v envsubst >/dev/null 2>&1 && command -v dpkg-deb >/dev/null 2>&1 && command -v rpm >/dev/null 2>&1; then python3 {{ source_directory() }}/../rs/scripts/package-rename.test.py; fi - @if command -v actionlint >/dev/null 2>&1; then actionlint; fi - {{ source_directory() }}/scripts/alert.sh check-coverage - @if command -v rustc >/dev/null 2>&1; then {{ source_directory() }}/scripts/package-binary.test.sh; fi + actionlint + sh/gh/alert.sh check-coverage + bun sh/gh/check-runs.ts + +# Tests of the release tooling itself; nightly, not on every pull request. +test: + python3 sh/gh/install-formula.test.py + sh/gh/release.test.sh + python3 sh/rs/package-rename.test.py + sh/go/publish-wrapper.test.sh + bash .claude/hooks/direnv.test.sh + +# Release workflow helpers, e.g. `just gh release parse-version moq-cli`. +[positional-arguments] +release *args: + sh/gh/release.sh "$@" + +# Post a failed run to Discord, or check that alert.yml covers every workflow. +[positional-arguments] +alert *args: + sh/gh/alert.sh "$@" + +# Render a Homebrew formula template for a release. +[positional-arguments] +formula *args: + sh/gh/render-formula.sh "$@" + +# Copy a rendered formula into a Homebrew tap checkout, migrating renamed formulae. +[positional-arguments] +install-formula *args: + python3 sh/gh/install-formula.py "$@" + +# Trigger the apt-repo and rpm-repo workflows for a release tag. +[positional-arguments] +trigger-repo-publish *args: + sh/gh/trigger-repo-publish.sh "$@" diff --git a/.github/scripts/package-binary.test.sh b/.github/scripts/package-binary.test.sh deleted file mode 100755 index b1390552f15..00000000000 --- a/.github/scripts/package-binary.test.sh +++ /dev/null @@ -1,72 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -WORKSPACE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" - -tmp="$(mktemp -d)" -trap 'rm -rf "$tmp"' EXIT - -binary="$tmp/moq-relay" -printf '#!/usr/bin/env sh\necho test\n' >"$binary" -chmod 0755 "$binary" -target="$(rustc -vV | awk '/^host:/ {print $2}')" - -# This test covers archive staging, not the macOS Mach-O rewrite. -mkdir "$tmp/bin" -printf '#!/usr/bin/env sh\nprintf "Linux\\n"\n' >"$tmp/bin/uname" -chmod 0755 "$tmp/bin/uname" - -PATH="$tmp/bin:$PATH" "$WORKSPACE_DIR/rs/scripts/package-binary.sh" \ - --crate moq-relay \ - --bin moq-relay \ - --binary "$binary" \ - --bare \ - --version 0.14.13 \ - --target "$target" \ - --output "$tmp/dist" - -name="moq-relay-v0.14.13-$target" -bare="$tmp/dist/$name" -archive="$tmp/dist/$name.tar.gz" - -[[ -x "$bare" ]] -[[ -f "$archive" ]] - -mkdir "$tmp/extracted" -tar -xzf "$archive" -C "$tmp/extracted" -[[ -x "$tmp/extracted/$name/bin/moq-relay" ]] -[[ -f "$tmp/extracted/$name/LICENSE-MIT" ]] -[[ -f "$tmp/extracted/$name/LICENSE-APACHE" ]] -cmp "$binary" "$bare" -cmp "$binary" "$tmp/extracted/$name/bin/moq-relay" - -echo "release assets package together without path collisions" - -# Without --binary the script builds the flake package named after the binary: -# `.#moq` for the moq-cli crate, since `.#moq-cli` is a stub refusing the old name. -cat >"$tmp/bin/nix" <<'NIX' -#!/usr/bin/env bash -set -euo pipefail -[[ "$1 $3" == "build --out-link" && "$2" == *"#moq" ]] || { - echo "unexpected: nix $*" >&2 - exit 1 -} -mkdir -p "$4/bin" -printf '#!/usr/bin/env sh\necho moq\n' >"$4/bin/moq" -chmod 0755 "$4/bin/moq" -NIX -chmod 0755 "$tmp/bin/nix" - -PATH="$tmp/bin:$PATH" "$WORKSPACE_DIR/rs/scripts/package-binary.sh" \ - --crate moq-cli \ - --bin moq \ - --version 0.12.2 \ - --target "$target" \ - --output "$tmp/dist" - -name="moq-cli-v0.12.2-$target" -tar -xzf "$tmp/dist/$name.tar.gz" -C "$tmp/extracted" -[[ "$("$tmp/extracted/$name/bin/moq")" == moq ]] - -echo "a nix build packages the flake output named after the binary" diff --git a/.github/workflows/alert.yml b/.github/workflows/alert.yml index cdfc9180bec..e18364366f7 100644 --- a/.github/workflows/alert.yml +++ b/.github/workflows/alert.yml @@ -21,9 +21,9 @@ on: # Android) are omitted so they don't spawn a skipped Alert run on every # push to every PR. `just gh check` enforces both halves of that. # - # Swift and Platform are here despite also running on pull requests: Swift - # warms its own Rust cache on `main`, and Platform compiles every merge to - # `main` and `dev`. Those push runs are nobody's check, so a break in them + # Swift, OBS, and Platform are here despite also running on pull requests: + # Swift warms its own Rust cache on `main`, and OBS and Platform build every + # merge to `main` and `dev`. Those push runs are nobody's check, so a break in them # would otherwise go unseen. The cost is a skipped Alert run per pull # request. workflows: @@ -37,6 +37,7 @@ on: - moq-gst - moq-relay - Nightly + - OBS - Platform - release-brew - Release Dart @@ -80,6 +81,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Post to Discord env: DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }} @@ -90,4 +93,4 @@ jobs: RUN_REF: ${{ github.event.workflow_run.head_branch }} RUN_TITLE: ${{ github.event.workflow_run.display_title }} RUN_ACTOR: ${{ github.event.workflow_run.triggering_actor.login }} - run: .github/scripts/alert.sh discord + run: just gh alert discord diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml index 9a82759c2fb..9ff35d7e967 100644 --- a/.github/workflows/android.yml +++ b/.github/workflows/android.yml @@ -49,7 +49,6 @@ concurrency: env: CARGO_NDK_VERSION: 4.1.2 - JUST_VERSION: 1.52.0 jobs: android: @@ -73,15 +72,10 @@ jobs: # No Rust cache: this workflow only runs on pull requests, which may not # save one, so it would have nothing to restore. + - uses: ./.github/actions/just + - name: Install cargo-ndk run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" - # A checksummed release binary, where `cargo install` would spend ~2 minutes - # building just from source. - - name: Install just - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 - with: - tool: just@${{ env.JUST_VERSION }} - - name: Check run: just rs android diff --git a/.github/workflows/apt-repo.yml b/.github/workflows/apt-repo.yml index ff790e1583b..5e8905ed21c 100644 --- a/.github/workflows/apt-repo.yml +++ b/.github/workflows/apt-repo.yml @@ -34,6 +34,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Set up packaging tools uses: ./.github/actions/setup-packaging @@ -53,10 +55,9 @@ jobs: - name: Publish to R2 shell: bash env: - ARTIFACTS_DIR: artifacts R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }} R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }} SIGNING_KEY: ${{ secrets.SIGNING_KEY }} SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} - run: ./infra/apt/publish.sh + run: just infra apt publish "$GITHUB_WORKSPACE/artifacts" diff --git a/.github/workflows/cache.yml b/.github/workflows/cache.yml index 6e1a1291225..4fb0bf42805 100644 --- a/.github/workflows/cache.yml +++ b/.github/workflows/cache.yml @@ -40,10 +40,13 @@ on: # Priming a cold cache by hand, e.g. after a toolchain bump rolls the key. workflow_dispatch: -# Newest `main` wins; an older warm is worth less than the runner it holds. +# Queue rather than cancel. A warm takes 30-50 minutes and `main` merges more +# often than that, so cancelling meant no warm ever finished and every pull +# request restored a store hours stale. Actions keeps only the newest pending +# run per group, so merges that land mid-warm still coalesce into one. concurrency: group: cache-${{ github.ref }} - cancel-in-progress: true + cancel-in-progress: false jobs: warm: diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 8fa0ed62ea5..834ac0fac63 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -39,19 +39,7 @@ jobs: # Full history so `just ci check` can diff against origin/$GITHUB_BASE_REF. fetch-depth: 0 - # Quests, agent config, and root Markdown compile nothing, so a diff of only - # those skips the disk cleanup and Rust cache that exist for the build. - - name: Scope - id: scope - run: | - base=$(git merge-base "origin/$GITHUB_BASE_REF" HEAD) - files=$(git diff --name-only "$base") - if grep -qvE '^(quest/|\.claude/|[^/]+\.md$)' <<< "$files"; then - echo build=true >> "$GITHUB_OUTPUT" - fi - - name: Free disk space - if: steps.scope.outputs.build uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # main with: tool-cache: false @@ -75,20 +63,19 @@ jobs: # scope such an entry to the PR's own branch anyway, where no later PR # could read it while it ate the repository's 10 GB budget. - name: Rust cache - if: steps.scope.outputs.build uses: ./.github/actions/rust-cache # 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. + # plus their dependents, so a one-crate PR compiles one crate and a + # quest-only PR runs only the lints. sh/dispatch.sh's impact map is the one + # place that decides; the setup above always runs rather than keep a second + # path map here. # # MOQ_STRICT turns every "tool missing, skipping" guard into an error. # Locally an absent formatter means less gets checked; here it would mean # a green run that checked nothing, which is the failure mode worth # spending a preflight on. - - name: Test direnv hook - run: bash .claude/hooks/direnv.test.sh - - name: Check run: nix develop --command just ci check env: @@ -108,26 +95,12 @@ jobs: # Full history so `just ci test` can diff against origin/$GITHUB_BASE_REF. fetch-depth: 0 - # Same scope as the `check` job. No test covers those files either, so the - # job skips everything and reports green instead of spending a minute of - # setup to run nothing. - - name: Scope - id: scope - run: | - base=$(git merge-base "origin/$GITHUB_BASE_REF" HEAD) - files=$(git diff --name-only "$base") - if grep -qvE '^(quest/|\.claude/|[^/]+\.md$)' <<< "$files"; then - echo build=true >> "$GITHUB_OUTPUT" - fi - - name: Free disk space - if: steps.scope.outputs.build uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # main with: tool-cache: false - - if: steps.scope.outputs.build - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false # Trust the flake's cachix substituter. `nixConfig` in flake.nix is @@ -142,13 +115,11 @@ jobs: # Restore only, same as the `check` job above. - name: Rust cache - if: steps.scope.outputs.build uses: ./.github/actions/rust-cache # 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 - if: steps.scope.outputs.build run: nix develop --command just ci test env: MOQ_STRICT: 1 diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index fc6748864b7..5fcbc152e44 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -39,6 +39,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - id: parse env: CRATE: ${{ inputs.package }} @@ -58,7 +60,7 @@ jobs: *) package="$crate" ;; esac echo "package=${package}" >> "$GITHUB_OUTPUT" - .github/scripts/release.sh parse-version "$crate" + just gh release parse-version "$crate" build: name: Build ${{ matrix.platform }} diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index fb675f76b0d..d73e258dff7 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -26,7 +26,7 @@ on: - "test/justfile" - "package.json" # The Go client builds against the modules this script stages. - - "go/scripts/**" + - "sh/go/**" - ".github/workflows/interop.yml" concurrency: @@ -74,7 +74,6 @@ jobs: - name: Rust cache uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2 with: - cache-on-failure: true # A pull request's entry is scoped to its own branch, where no later # run reads it, while it spends the budget the shared store needs. save-if: ${{ github.event_name != 'pull_request' }} @@ -129,6 +128,14 @@ jobs: env: MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + # The same round-trip over an open-GOP clip: every leading picture after a + # recovery point must come back, in decode order. + - name: TS open GOP + run: nix develop --command just test ts --open-gop + shell: bash -leo pipefail {0} + env: + MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + # Builds the sparse-EPG and pending-version fixtures and round-trips # them, asserting the schedule survives and pending sections are dropped. - name: EIT fixtures diff --git a/.github/workflows/moq-c.yml b/.github/workflows/moq-c.yml index c2cf06b6f90..329f81b605e 100644 --- a/.github/workflows/moq-c.yml +++ b/.github/workflows/moq-c.yml @@ -40,11 +40,18 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Install Nix if: matrix.use_nix uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Install Rust (Windows) if: '!matrix.use_nix' @@ -55,12 +62,12 @@ jobs: - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version moq-c + run: just gh release parse-version moq-c - name: Build and package shell: bash run: | - ./rs/moq-c/build.sh \ + just rs package-moq-c \ --target ${{ matrix.target }} \ --version ${{ steps.parse.outputs.version }} \ --output dist @@ -85,13 +92,15 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version moq-c + run: just gh release parse-version moq-c - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-c + run: just gh release prev-tag moq-c - name: Download artifacts uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -105,7 +114,7 @@ jobs: RELEASE_TAG: ${{ github.ref_name }} RELEASE_TITLE: "moq-c v${{ steps.parse.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts # The OBS plugin (cpp/obs) statically links moq-c, so it ships with every # moq-c release: rebuild it against the release we just published (no @@ -137,10 +146,12 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version moq-c + run: just gh release parse-version moq-c # Native Xcode / Visual Studio; libobs/Qt6/ffmpeg come from the obs-deps # bundle and moq-c from the release we just published (--moq-c-release). @@ -150,7 +161,7 @@ jobs: TARGET: ${{ matrix.target }} VERSION: ${{ steps.parse.outputs.version }} run: | - ./cpp/obs/build.sh --target "$TARGET" --moq-c-release "$VERSION" --output dist + just obs package --target "$TARGET" --moq-c-release "$VERSION" --output dist - name: Upload artifact uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -171,9 +182,11 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version moq-c + run: just gh release parse-version moq-c # Only the obs-moq archives: the moq-c-* artifacts from the build job # belong to the moq-c release, not this one. @@ -208,4 +221,4 @@ jobs: RELEASE_TAG: "obs-moq-v${{ steps.parse.outputs.version }}" RELEASE_TITLE: "obs-moq v${{ steps.parse.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts diff --git a/.github/workflows/moq-cli.yml b/.github/workflows/moq-cli.yml index 141e47ecb8d..0258e0ca072 100644 --- a/.github/workflows/moq-cli.yml +++ b/.github/workflows/moq-cli.yml @@ -17,215 +17,11 @@ permissions: contents: read jobs: - build: - name: Build (${{ matrix.target }}) - runs-on: ${{ matrix.runs-on }} - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-unknown-linux-gnu - runs-on: ubuntu-22.04 - deb-arch: amd64 - rpm-arch: x86_64 - - target: aarch64-unknown-linux-gnu - runs-on: ubuntu-22.04-arm - deb-arch: arm64 - rpm-arch: aarch64 - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-cli - - - name: Set up packaging tools - uses: ./.github/actions/setup-packaging - - - name: Build (release, glibc 2.34) - shell: bash - # Pin to glibc 2.34 so one binary covers Ubuntu 22.04+ (.deb) - # and AlmaLinux/RHEL/Rocky 9+ (.rpm). - run: cargo zigbuild --locked --release --target ${{ matrix.target }}.2.34 -p moq-cli - - - name: Package release assets - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - TARGET: ${{ matrix.target }} - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-cli \ - --bin moq \ - --binary "target/${TARGET}/release/moq" \ - --bare \ - --version "$VERSION" \ - --target "$TARGET" \ - --output dist - - - name: Package .deb (Ubuntu 22.04 toolchain) - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.deb-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq - run: | - rs/scripts/package-nfpm.sh packaging/moq-cli/nfpm.yaml deb dist/ - rs/scripts/package-nfpm.sh packaging/moq-cli/transition.yaml deb dist/ - - - name: Package .rpm - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.rpm-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq - run: rs/scripts/package-nfpm.sh packaging/moq-cli/nfpm.yaml rpm dist/ - - - name: Upload artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-cli-${{ matrix.target }} - path: dist/* - - build-tarball-macos: - name: Build macOS tarball (${{ matrix.target }}) - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: aarch64-apple-darwin - os: macos-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main - with: - determinate: false - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-cli - - - name: Build and package tarball - shell: bash - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-cli \ - --bin moq \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-cli-${{ matrix.target }} - path: dist/* - - build-windows: - name: Build Windows zip (${{ matrix.target }}) - runs-on: windows-latest - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-pc-windows-msvc - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # aws-lc-rs assembles its x86_64 crypto with NASM on Windows. - - name: Install NASM - shell: pwsh - run: | - choco install nasm -y --no-progress - "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-cli - - - name: Build and package zip - shell: bash - run: | - ./rs/scripts/package-windows.sh \ - --crate moq-cli \ - --bin moq \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-cli-${{ matrix.target }} - path: dist/* - release: - name: Release - needs: [build, build-tarball-macos, build-windows] - if: github.ref_type == 'tag' - runs-on: ubuntu-latest + uses: ./.github/workflows/release-binary.yml + with: + crate: moq-cli + bin: moq permissions: contents: write actions: write - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-cli - - - name: Find previous tag - id: prev_tag - run: .github/scripts/release.sh prev-tag moq-cli - - - name: Download artifacts - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - path: artifacts - merge-multiple: true - - - name: Create or update release - env: - GH_TOKEN: ${{ github.token }} - RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-cli v${{ steps.parse.outputs.version }}" - RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts - - - name: Trigger apt/rpm repo publish - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.ref_name }} - run: .github/scripts/trigger-repo-publish.sh diff --git a/.github/workflows/moq-gst.yml b/.github/workflows/moq-gst.yml index 2c93d1ac9a7..7ce0e927052 100644 --- a/.github/workflows/moq-gst.yml +++ b/.github/workflows/moq-gst.yml @@ -34,14 +34,21 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version moq-gst + run: just gh release parse-version moq-gst - name: Build and package (tarball) shell: bash @@ -49,7 +56,7 @@ jobs: TARGET: ${{ matrix.target }} VERSION: ${{ steps.parse.outputs.version }} run: | - ./rs/moq-gst/build.sh \ + just rs package-gst \ --target "$TARGET" \ --version "$VERSION" \ --output dist @@ -80,7 +87,7 @@ jobs: run: | set -euo pipefail tar -xzf "dist/moq-gst-v${VERSION}-${TARGET}.tar.gz" -C dist/ - ./rs/moq-gst/smoke.sh "dist/moq-gst-v${VERSION}-${TARGET}/lib/gstreamer-1.0" + just rs gst-smoke "dist/moq-gst-v${VERSION}-${TARGET}/lib/gstreamer-1.0" - name: Upload artifact uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -112,6 +119,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable with: @@ -123,7 +132,7 @@ jobs: - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version moq-gst + run: just gh release parse-version moq-gst - name: Install GStreamer dev libraries shell: bash @@ -160,7 +169,7 @@ jobs: PLUGIN_DIR: /usr/lib/${{ matrix.deb-multiarch }}/gstreamer-1.0 run: | mkdir -p dist - rs/scripts/package-nfpm.sh packaging/moq-gst/nfpm.yaml deb dist/ + just rs package-nfpm packaging/moq-gst/nfpm.yaml deb dist/ - name: Package .rpm shell: bash @@ -172,7 +181,7 @@ jobs: PLUGIN_DIR: /usr/lib64/gstreamer-1.0 run: | mkdir -p dist - rs/scripts/package-nfpm.sh packaging/moq-gst/nfpm.yaml rpm dist/ + just rs package-nfpm packaging/moq-gst/nfpm.yaml rpm dist/ - name: Upload artifacts uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -195,13 +204,15 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version moq-gst + run: just gh release parse-version moq-gst - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-gst + run: just gh release prev-tag moq-gst - name: Download artifacts uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -215,10 +226,10 @@ jobs: RELEASE_TAG: ${{ github.ref_name }} RELEASE_TITLE: "moq-gst v${{ steps.parse.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts - name: Trigger apt/rpm repo publish env: GH_TOKEN: ${{ github.token }} TAG: ${{ github.ref_name }} - run: .github/scripts/trigger-repo-publish.sh + run: just gh trigger-repo-publish diff --git a/.github/workflows/moq-relay.yml b/.github/workflows/moq-relay.yml index 761ee0aba35..cfb4767b530 100644 --- a/.github/workflows/moq-relay.yml +++ b/.github/workflows/moq-relay.yml @@ -17,214 +17,11 @@ permissions: contents: read jobs: - build: - name: Build (${{ matrix.target }}) - runs-on: ${{ matrix.runs-on }} - - strategy: - fail-fast: false - matrix: - include: - # Native runners. Each binary is built on the same arch it ships - # for, so the .deb/.rpm linkage matches the distro's glibc on the - # oldest LTS we support (Ubuntu 22.04 / AlmaLinux 9). - - target: x86_64-unknown-linux-gnu - runs-on: ubuntu-22.04 - deb-arch: amd64 - rpm-arch: x86_64 - - target: aarch64-unknown-linux-gnu - runs-on: ubuntu-22.04-arm - deb-arch: arm64 - rpm-arch: aarch64 - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-relay - - - name: Set up packaging tools - uses: ./.github/actions/setup-packaging - - - name: Build (release, glibc 2.34) - shell: bash - # Pin to glibc 2.34 so one binary covers Ubuntu 22.04+ (.deb) - # and AlmaLinux/RHEL/Rocky 9+ (.rpm). - run: cargo zigbuild --locked --release --target ${{ matrix.target }}.2.34 -p moq-relay - - - name: Package release assets - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - TARGET: ${{ matrix.target }} - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-relay \ - --bin moq-relay \ - --binary "target/${TARGET}/release/moq-relay" \ - --bare \ - --version "$VERSION" \ - --target "$TARGET" \ - --output dist - - - name: Package .deb (Ubuntu 22.04 toolchain, glibc 2.35) - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.deb-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq-relay - run: rs/scripts/package-nfpm.sh packaging/moq-relay/nfpm.yaml deb dist/ - - - name: Package .rpm - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.rpm-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq-relay - run: rs/scripts/package-nfpm.sh packaging/moq-relay/nfpm.yaml rpm dist/ - - - name: Upload artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-relay-${{ matrix.target }} - path: dist/* - - build-tarball-macos: - name: Build macOS tarball (${{ matrix.target }}) - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: aarch64-apple-darwin - os: macos-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main - with: - determinate: false - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-relay - - - name: Build and package tarball - shell: bash - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-relay \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-relay-${{ matrix.target }} - path: dist/* - - build-windows: - name: Build Windows zip (${{ matrix.target }}) - runs-on: windows-latest - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-pc-windows-msvc - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # aws-lc-rs assembles its x86_64 crypto with NASM on Windows. - - name: Install NASM - shell: pwsh - run: | - choco install nasm -y --no-progress - "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-relay - - - name: Build and package zip - shell: bash - run: | - ./rs/scripts/package-windows.sh \ - --crate moq-relay \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-relay-${{ matrix.target }} - path: dist/* - release: - name: Release - needs: [build, build-tarball-macos, build-windows] - if: github.ref_type == 'tag' - runs-on: ubuntu-latest + uses: ./.github/workflows/release-binary.yml + with: + crate: moq-relay + bin: moq-relay permissions: contents: write actions: write - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-relay - - - name: Find previous tag - id: prev_tag - run: .github/scripts/release.sh prev-tag moq-relay - - - name: Download artifacts - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - path: artifacts - merge-multiple: true - - - name: Create or update release - env: - GH_TOKEN: ${{ github.token }} - RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-relay v${{ steps.parse.outputs.version }}" - RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts - - - name: Trigger apt/rpm repo publish - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.ref_name }} - run: .github/scripts/trigger-repo-publish.sh diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index fd37b476be8..9012fda13e4 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -53,6 +53,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= # Restore only, like `tests` below. Saving its own store cost 3.6 GB of the # repository's 10 GB budget and evicted the one every pull request restores. @@ -70,39 +75,43 @@ jobs: # over independent observers of the new live broadcast map. - name: JS origin broadcast map benchmark if: ${{ !cancelled() }} - run: | - nix develop --command bun install --frozen-lockfile - nix develop --command bun js/net/bench/broadcasts.ts + run: nix develop --command just js bench broadcasts # A route above several interest heads lands once per head, so its re-price # should expose any slope over heads times received routes. - name: JS origin announce forwarding benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/forward.ts + run: nix develop --command just js bench forward # Fails if reading a fragmented frame costs more per byte as the frame grows. - name: JS stream reader benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/reader.ts + run: nix develop --command just js bench reader # Fails if a chunk carrying many small frames costs as much per frame as one # carrying a single frame, on either the lite or moq-transport group stream, # which means decoding went back to a wakeup per frame. - name: JS group frame benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/frames.ts + run: nix develop --command just js bench frames # Times one varint encode and decode per wire format. No threshold: it only # has to keep running, and its numbers are the baseline for the generated codec. - name: JS varint benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/varint.ts + run: nix develop --command just js bench varint + + # Bytes and time for lite-06 against lite-07 frames, groups, and requests. No + # threshold: it only has to keep running. + - name: JS lite varint benchmark + if: ${{ !cancelled() }} + run: nix develop --command just js bench lite-varint # Fails if publishing a group costs more as the track retains more groups, # which means the latency guard or the cache went back to scanning them all. - name: JS track retention benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/track.ts + run: nix develop --command just js bench track # Runs each moq-net Criterion routine once, so a bench that panics (an # unparsable version, a shape that deadlocks) fails here instead of on the @@ -161,7 +170,8 @@ jobs: matrix: # `rs uring` is a separate feature compile (off the default set) and # kernel-gated below 6.12. The embedding tests for io_uring live there. - recipe: ["rs doctest --workspace", "rs loom", "test drill-sensitivity", "rs uring"] + # `gh test` exercises the release tooling, which no pull request runs. + recipe: ["rs doctest --workspace", "rs loom", "test drill-sensitivity", "rs uring", "gh test"] steps: - name: Free disk space uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # main @@ -174,6 +184,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Rust cache uses: ./.github/actions/rust-cache - name: Test @@ -277,6 +292,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Install nightly Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable with: diff --git a/.github/workflows/obs.yml b/.github/workflows/obs.yml index dd3cacfb166..5364b000976 100644 --- a/.github/workflows/obs.yml +++ b/.github/workflows/obs.yml @@ -7,7 +7,9 @@ name: OBS # Linux is the platform that needs no bundle at all -- nixpkgs has obs-studio, # Qt6 and ffmpeg, so the `.#obs` shell is the whole dependency set. The plugin is # platform-independent C++ over moq-c's C ABI, so a Linux compile catches the -# breakage a macOS developer would otherwise ship uncompiled. +# breakage a macOS developer would otherwise ship uncompiled. The macOS and +# Windows release builds cover the rest: each platform's link line and the +# obs-deps bundle. # # Narrow trigger, like swift.yml: the plugin's own sources, the moq-c header # they call through, and the flake that supplies the toolchain. @@ -36,19 +38,35 @@ name: OBS # A list of paths still can't be complete here -- a vendored C source or a # .cargo/config.toml could do it too -- and `rs/**` would run this on nearly # every PR, which is the cost that removed the Windows and macOS gates (#2600). -# So this filter covers the likely inputs at PR time and nightly.yml runs the -# same recipe diff-independently to cover the rest. +# So this filter covers the likely inputs at PR time, and pushes to `main` and +# `dev` rebuild on any Rust or plugin change to cover the rest. nightly.yml also +# runs the Linux recipe diff-independently. permissions: contents: read on: + push: + branches: [main, dev] + paths: + - "rs/**" + - "cpp/obs/**" + - "doc/lib/c/**" + - "doc/lib/samples.sh" + - ".cargo/**" + - "Cargo.toml" + - "Cargo.lock" + - "rust-toolchain.toml" + - "flake.nix" + - "flake.lock" + - ".github/workflows/obs.yml" pull_request: # `closed` is here only so merging/closing a PR cancels its in-flight run # via the concurrency group below; the job itself is skipped on close. types: [opened, synchronize, reopened, closed] paths: - "cpp/obs/**" + - "sh/obs/**" - "rs/moq-c/**" - "doc/lib/c/**" - "doc/lib/samples.sh" @@ -61,9 +79,12 @@ on: - "flake.lock" - ".github/workflows/obs.yml" +# Keyed and cancelled like platform.yml: a merged PR's `closed` run must not +# cancel the push run it triggers, and `main` merges faster than a push run +# finishes, so pushes queue rather than cancel. concurrency: - group: obs-${{ github.ref }} - cancel-in-progress: true + group: obs-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: build: @@ -108,3 +129,41 @@ jobs: # cargo step inside is a no-op and this is just a cc and a run. - name: moq-c C fixtures run: nix develop .#obs --command just rs c-tests + + # The release build of the OBS plugin, minus the published moq-c: build.sh + # without `--moq-c-release` links the in-tree rs/moq-c instead, so a PR is + # checked against its own C ABI. The obs-deps bundle (libobs, Qt6, ffmpeg) + # comes from buildspec.json at configure time, same as a tag build. + release: + name: OBS (${{ matrix.name }}) + if: github.event.action != 'closed' + runs-on: ${{ matrix.os }} + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + include: + - name: macOS + target: aarch64-apple-darwin + os: macos-latest + - name: Windows + target: x86_64-pc-windows-msvc + # The plugin preset uses the Visual Studio 17 2022 generator. + os: windows-2022 + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + + - uses: ./.github/actions/just + + - name: Build + shell: bash + env: + TARGET: ${{ matrix.target }} + run: just obs package --target "$TARGET" --output "$RUNNER_TEMP/obs" diff --git a/.github/workflows/platform.yml b/.github/workflows/platform.yml index a5b48af38b8..819d731bb63 100644 --- a/.github/workflows/platform.yml +++ b/.github/workflows/platform.yml @@ -3,18 +3,15 @@ name: Platform # Compiles the workspace on Windows and macOS, the `#[cfg(...)]` code no Linux # job compiles at all: moq-video's Media Foundation and VideoToolbox backends, # their capture paths, moq-audio's ScreenCaptureKit capture, and the smaller -# platform branches elsewhere. It also builds the OBS plugin against the -# obs-deps bundle, which obs.yml can't do on Linux. Without this, a change that -# breaks any of them (a moq-net type they consume, say) merges green and -# compiles for the first time in a tag-triggered release build. +# platform branches elsewhere. Without this, a change that breaks any of them +# (a moq-net type they consume, say) merges green and compiles for the first +# time in a tag-triggered release build. # -# Filtered to the Rust workspace and the OBS plugin, rather than to each job's -# exact dependency graph like android.yml: these are the slowest and most -# expensive runners in CI, and a quest or docs PR has nothing for them to build. -# -# Pushes to `main` and `dev` catch the break two individually green PRs make -# once both land, which is what the nightly run of these jobs used to cover. -# `dev` never ran the nightly at all. +# A pull request compiles only the crates it changed plus their dependents, +# the same selection the Linux `check` job makes, because these are the +# slowest and scarcest runners in CI. Pushes to `main` and `dev` compile +# everything, catching the break two individually green PRs make once both +# land. `dev` never ran the nightly at all. # # Outside Nix, like android.yml: neither runner has it, so each installs the # runner-native toolchain. rust-toolchain.toml still pins the compiler, and the @@ -32,12 +29,12 @@ on: branches: [main, dev] paths: - "rs/**" - - "cpp/**" - ".cargo/**" - "Cargo.toml" - "Cargo.lock" - "rust-toolchain.toml" - "justfile" + - "sh/**" - ".github/workflows/platform.yml" pull_request: # `closed` is here only so merging/closing a PR cancels its in-flight run @@ -45,12 +42,12 @@ on: types: [opened, synchronize, reopened, closed] paths: - "rs/**" - - "cpp/**" - ".cargo/**" - "Cargo.toml" - "Cargo.lock" - "rust-toolchain.toml" - "justfile" + - "sh/**" - ".github/workflows/platform.yml" concurrency: @@ -59,10 +56,10 @@ concurrency: # PR's `closed` run can report the base branch as its ref instead of the PR's # merge ref, and then wouldn't cancel the PR's in-flight run. group: platform-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }} - cancel-in-progress: true - -env: - JUST_VERSION: 1.52.0 + # Pushes queue instead: `main` merges faster than these jobs finish, so + # cancelling meant almost no push run ever reported. Actions keeps only the + # newest pending run, so queued merges still coalesce. + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: windows: @@ -76,6 +73,8 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + # Full history so a pull request can diff against its base. + fetch-depth: 0 - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable @@ -87,16 +86,13 @@ jobs: choco install nasm -y --no-progress "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - # A checksummed release binary, where `cargo install` would spend ~2 minutes - # building just from source. - - name: Install just - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 - with: - tool: just@${{ env.JUST_VERSION }} + - uses: ./.github/actions/just - name: Check shell: bash - run: just rs windows + env: + SCOPE: ${{ github.event_name == 'push' && '--all' || '' }} + run: just rs windows "$SCOPE" macos: name: macOS @@ -109,50 +105,14 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + fetch-depth: 0 - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - name: Install just - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 - with: - tool: just@${{ env.JUST_VERSION }} + - uses: ./.github/actions/just - name: Check - run: just rs macos - - # The release build of the OBS plugin, minus the published moq-c: build.sh - # without `--moq-c-release` links the in-tree rs/moq-c instead, so a PR is - # checked against its own C ABI. The obs-deps bundle (libobs, Qt6, ffmpeg) - # comes from buildspec.json at configure time, same as a tag build. - obs: - name: OBS (${{ matrix.name }}) - if: github.event.action != 'closed' - runs-on: ${{ matrix.os }} - timeout-minutes: 60 - strategy: - fail-fast: false - matrix: - include: - - name: macOS - target: aarch64-apple-darwin - os: macos-latest - - name: Windows - target: x86_64-pc-windows-msvc - # The plugin preset uses the Visual Studio 17 2022 generator. - os: windows-2022 - - steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - - name: Build - shell: bash env: - TARGET: ${{ matrix.target }} - run: ./cpp/obs/build.sh --target "$TARGET" --output "$RUNNER_TEMP/obs" + SCOPE: ${{ github.event_name == 'push' && '--all' || '' }} + run: just rs macos "$SCOPE" diff --git a/.github/workflows/release-binary.yml b/.github/workflows/release-binary.yml new file mode 100644 index 00000000000..88350386f05 --- /dev/null +++ b/.github/workflows/release-binary.yml @@ -0,0 +1,258 @@ +name: release-binary + +# Builds, packages, and (on a tag) releases one workspace binary. moq-cli.yml +# and moq-relay.yml call it; they keep the tag trigger and the workflow name +# that alert.yml, release-brew.yml, and release-winget.yml match on. + +on: + workflow_call: + inputs: + crate: + description: "Cargo package to build, e.g. moq-cli" + required: true + type: string + bin: + description: "Executable the package ships, e.g. moq" + required: true + type: string + +permissions: + contents: read + +env: + CRATE: ${{ inputs.crate }} + BIN: ${{ inputs.bin }} + +jobs: + build: + name: Build (${{ matrix.target }}) + runs-on: ${{ matrix.runs-on }} + + strategy: + fail-fast: false + matrix: + include: + # Native runners. Each binary is built on the same arch it ships + # for, so the .deb/.rpm linkage matches the distro's glibc on the + # oldest LTS we support (Ubuntu 22.04 / AlmaLinux 9). + - target: x86_64-unknown-linux-gnu + runs-on: ubuntu-22.04 + deb-arch: amd64 + rpm-arch: x86_64 + - target: aarch64-unknown-linux-gnu + runs-on: ubuntu-22.04-arm + deb-arch: arm64 + rpm-arch: aarch64 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + with: + targets: ${{ matrix.target }} + + - name: Parse version + id: parse + shell: bash + run: just gh release parse-version "$CRATE" + + - name: Set up packaging tools + uses: ./.github/actions/setup-packaging + + - name: Build (release, glibc 2.34) + shell: bash + # Pin to glibc 2.34 so one binary covers Ubuntu 22.04+ (.deb) + # and AlmaLinux/RHEL/Rocky 9+ (.rpm). + run: cargo zigbuild --locked --release --target ${{ matrix.target }}.2.34 -p "$CRATE" + + - name: Package release assets + shell: bash + env: + VERSION: ${{ steps.parse.outputs.version }} + TARGET: ${{ matrix.target }} + run: | + just rs package-binary \ + --crate "$CRATE" \ + --bin "$BIN" \ + --binary "target/${TARGET}/release/${BIN}" \ + --bare \ + --version "$VERSION" \ + --target "$TARGET" \ + --output dist + + # A transition.yaml beside nfpm.yaml is a deb-only package that keeps + # apt upgrades following a renamed package. + - name: Package .deb (Ubuntu 22.04 toolchain) + shell: bash + env: + VERSION: ${{ steps.parse.outputs.version }} + ARCH: ${{ matrix.deb-arch }} + BINARY_PATH: target/${{ matrix.target }}/release/${{ inputs.bin }} + run: | + just rs package-nfpm "packaging/$CRATE/nfpm.yaml" deb dist/ + if [[ -f "packaging/$CRATE/transition.yaml" ]]; then + just rs package-nfpm "packaging/$CRATE/transition.yaml" deb dist/ + fi + + - name: Package .rpm + shell: bash + env: + VERSION: ${{ steps.parse.outputs.version }} + ARCH: ${{ matrix.rpm-arch }} + BINARY_PATH: target/${{ matrix.target }}/release/${{ inputs.bin }} + run: just rs package-nfpm "packaging/$CRATE/nfpm.yaml" rpm dist/ + + - name: Upload artifacts + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.crate }}-${{ matrix.target }} + path: dist/* + + build-tarball-macos: + name: Build macOS tarball (${{ matrix.target }}) + runs-on: ${{ matrix.os }} + + strategy: + fail-fast: false + matrix: + include: + - target: aarch64-apple-darwin + os: macos-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - uses: ./.github/actions/just + + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main + with: + determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= + + - name: Parse version + id: parse + shell: bash + run: just gh release parse-version "$CRATE" + + - name: Build and package tarball + shell: bash + run: | + just rs package-binary \ + --crate "$CRATE" \ + --bin "$BIN" \ + --target ${{ matrix.target }} \ + --version ${{ steps.parse.outputs.version }} \ + --output dist + + - name: Upload artifact + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.crate }}-${{ matrix.target }} + path: dist/* + + build-windows: + name: Build Windows zip (${{ matrix.target }}) + runs-on: windows-latest + + strategy: + fail-fast: false + matrix: + include: + - target: x86_64-pc-windows-msvc + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + with: + targets: ${{ matrix.target }} + + # aws-lc-rs assembles its x86_64 crypto with NASM on Windows. + - name: Install NASM + shell: pwsh + run: | + choco install nasm -y --no-progress + "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append + + - name: Parse version + id: parse + shell: bash + run: just gh release parse-version "$CRATE" + + - name: Build and package zip + shell: bash + run: | + just rs package-windows \ + --crate "$CRATE" \ + --bin "$BIN" \ + --target ${{ matrix.target }} \ + --version ${{ steps.parse.outputs.version }} \ + --output dist + + - name: Upload artifact + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.crate }}-${{ matrix.target }} + path: dist/* + + release: + name: Release + needs: [build, build-tarball-macos, build-windows] + if: github.ref_type == 'tag' + runs-on: ubuntu-latest + permissions: + contents: write + actions: write + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Parse version + id: parse + run: just gh release parse-version "$CRATE" + + - name: Find previous tag + id: prev_tag + run: just gh release prev-tag "$CRATE" + + - name: Download artifacts + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 + with: + path: artifacts + merge-multiple: true + + - name: Create or update release + env: + GH_TOKEN: ${{ github.token }} + RELEASE_TAG: ${{ github.ref_name }} + RELEASE_TITLE: "${{ inputs.crate }} v${{ steps.parse.outputs.version }}" + RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} + run: just gh release create artifacts + + - name: Trigger apt/rpm repo publish + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.ref_name }} + run: just gh trigger-repo-publish diff --git a/.github/workflows/release-brew.yml b/.github/workflows/release-brew.yml index 20fe7211562..5e8594de054 100644 --- a/.github/workflows/release-brew.yml +++ b/.github/workflows/release-brew.yml @@ -41,6 +41,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Parse crate and version id: parse env: @@ -98,7 +100,7 @@ jobs: VERSION: ${{ steps.parse.outputs.version }} run: | mkdir -p rendered - ./.github/scripts/render-formula.sh \ + just gh formula \ --template ".github/homebrew/Formula/${CRATE}.rb.tmpl" \ --version "$VERSION" \ --release-dir release-assets \ @@ -156,7 +158,7 @@ jobs: EOF fi - python3 ../.github/scripts/install-formula.py "$CRATE" "../rendered/${CRATE}.rb" . + just gh install-formula "$CRATE" "rendered/${CRATE}.rb" homebrew-tap if git diff --quiet && [[ -z "$(git status --porcelain)" ]]; then echo "No changes to commit (formula already up to date)." diff --git a/.github/workflows/release-dart-ffi.yml b/.github/workflows/release-dart-ffi.yml index 0396251ace9..4e75507115c 100644 --- a/.github/workflows/release-dart-ffi.yml +++ b/.github/workflows/release-dart-ffi.yml @@ -12,13 +12,17 @@ on: # workflow this way so a broken build surfaces before the tag is cut. workflow_call: workflow_dispatch: + # Packaging changes only, like the other FFI release workflows. A change to + # the moq-ffi sources is covered on every platform by cheaper gates: check.yml + # compiles it and regenerates the Dart bindings, platform.yml and swift.yml + # compile it for macOS, Windows, and iOS, and nightly runs this full matrix. pull_request: paths: - ".github/workflows/release-dart-ffi.yml" + - ".github/workflows/release-ffi.yml" - "dart/moq_ffi/**" - - "dart/scripts/**" - - "rs/moq-ffi/**" - - "!rs/moq-ffi/Cargo.toml" + - "sh/dart/**" + - "rs/moq-ffi/build.sh" permissions: contents: read @@ -31,117 +35,71 @@ concurrency: group: release-dart-ffi-${{ github.ref_type == 'tag' && 'publish' || github.ref }} cancel-in-progress: ${{ github.ref_type != 'tag' }} -env: - CARGO_NDK_VERSION: 4.1.2 - jobs: - parse-version: - name: Parse version + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: dart + # The raw bindings are checked in under dart/moq_ffi, so none here. + bindings: false + default-features: false + targets: >- + [ + "aarch64-linux-android", + "armv7-linux-androideabi", + "x86_64-linux-android", + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "aarch64-apple-darwin", + "x86_64-apple-darwin", + "aarch64-apple-ios", + "aarch64-apple-ios-sim", + "x86_64-apple-ios", + "x86_64-pc-windows-msvc" + ] + + # hook/build.dart downloads moq-ffi--- and its + # .sha256 from the release, so each target's shared library is renamed flat. + assets: + name: Stage Native Assets + needs: [ffi] runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build Native Asset (${{ matrix.target }}) - needs: [parse-version] - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: aarch64-linux-android - os: ubuntu-latest - - target: armv7-linux-androideabi - os: ubuntu-latest - - target: x86_64-linux-android - os: ubuntu-latest - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-apple-darwin - os: macos-latest - - target: x86_64-apple-darwin - os: macos-latest - - target: aarch64-apple-ios - os: macos-latest - - target: aarch64-apple-ios-sim - os: macos-latest - - target: x86_64-apple-ios - os: macos-latest - - target: x86_64-pc-windows-msvc - os: windows-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + - name: Download per-target libs + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: Install cargo-ndk (Android) - if: contains(matrix.target, 'android') - run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" + path: libs-raw + pattern: dart-lib-* - - name: Build and stage asset - shell: bash + - name: Stage env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - IPHONEOS_DEPLOYMENT_TARGET: ${{ contains(matrix.target, 'apple-ios') && '16.0' || '' }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist \ - --no-default-features - - case "$BUILD_TARGET" in - *-apple-ios* | *-apple-darwin*) LIBRARY=libmoq_ffi.dylib ;; - *-windows-*) LIBRARY=moq_ffi.dll ;; - *) LIBRARY=libmoq_ffi.so ;; - esac - - NAME="moq-ffi-$BUILD_VERSION-$BUILD_TARGET-$LIBRARY" mkdir -p assets - cp "dist/moq-ffi-$BUILD_VERSION-$BUILD_TARGET/lib/$LIBRARY" "assets/$NAME" - if command -v sha256sum >/dev/null 2>&1; then - sha256sum "assets/$NAME" > "assets/$NAME.sha256" - else - shasum -a 256 "assets/$NAME" > "assets/$NAME.sha256" - fi - - - name: Upload Native Asset + for dir in libs-raw/dart-lib-*; do + target="${dir#libs-raw/dart-lib-}" + case "$target" in + *-apple-ios* | *-apple-darwin*) library=libmoq_ffi.dylib ;; + *-windows-*) library=moq_ffi.dll ;; + *) library=libmoq_ffi.so ;; + esac + name="moq-ffi-$BUILD_VERSION-$target-$library" + cp "$dir/$library" "assets/$name" + (cd assets && sha256sum "$name" > "$name.sha256") + done + ls -la assets + + - name: Upload Native Assets uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: - name: dart-asset-${{ matrix.target }} + name: dart-assets path: assets/* package: name: Check pub package - needs: [parse-version] + needs: [ffi] runs-on: ubuntu-latest steps: @@ -149,13 +107,15 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d # v1.8.1 - name: Stage and check package env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./dart/scripts/package.sh \ + just dart package \ --package moq_ffi \ --version "$BUILD_VERSION" \ --output release-out @@ -172,7 +132,7 @@ jobs: release: name: Attach Native Assets - needs: [parse-version, build] + needs: [ffi, assets] if: github.ref_type == 'tag' runs-on: ubuntu-latest permissions: @@ -184,29 +144,30 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-ffi + run: just gh release prev-tag moq-ffi - name: Download Native Assets uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: + name: dart-assets path: artifacts - pattern: dart-asset-* - merge-multiple: true - name: Create or update release env: GH_TOKEN: ${{ github.token }} RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-ffi v${{ needs.parse-version.outputs.version }}" + RELEASE_TITLE: "moq-ffi v${{ needs.ffi.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} RELEASE_CHECKSUMS: SHA256SUMS-dart - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts publish: name: Publish moq_ffi to pub.dev - needs: [parse-version, package, release] + needs: [ffi, package, release] if: github.ref_type == 'tag' runs-on: ubuntu-latest environment: @@ -225,5 +186,5 @@ jobs: - name: Publish env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: cd "package/moq_ffi-$BUILD_VERSION" && dart pub publish --force diff --git a/.github/workflows/release-dart.yml b/.github/workflows/release-dart.yml index 2c099bc3188..3578ae386c2 100644 --- a/.github/workflows/release-dart.yml +++ b/.github/workflows/release-dart.yml @@ -12,7 +12,7 @@ on: paths: - ".github/workflows/release-dart.yml" - "dart/moq/**" - - "dart/scripts/**" + - "sh/dart/**" permissions: contents: read @@ -37,6 +37,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d # v1.8.1 - name: Resolve version @@ -47,7 +49,7 @@ jobs: if [[ "$EVENT_NAME" == "pull_request" ]]; then VERSION=$(sed -n 's/^version: //p' dart/moq/pubspec.yaml | head -1) else - .github/scripts/release.sh parse-version moq-dart + just gh release parse-version moq-dart exit 0 fi echo "version=$VERSION" >> "$GITHUB_OUTPUT" @@ -69,7 +71,7 @@ jobs: env: BUILD_VERSION: ${{ steps.version.outputs.version }} run: | - ./dart/scripts/package.sh \ + just dart package \ --package moq \ --version "$BUILD_VERSION" \ --output release-out diff --git a/.github/workflows/release-ffi.yml b/.github/workflows/release-ffi.yml new file mode 100644 index 00000000000..ff7cfc85aee --- /dev/null +++ b/.github/workflows/release-ffi.yml @@ -0,0 +1,169 @@ +name: release-ffi + +# Builds rs/moq-ffi for each requested target and generates its UniFFI +# bindings. The release-{dart,go,kt,swift}-ffi.yml callers package and publish; +# they keep the moq-ffi-v* tag trigger and the workflow name that alert.yml and +# the workflow_run chains match on. +# +# Uploads, all prefixed by `language` so callers sharing one nightly run never +# collide: +# -lib- the target's native libraries (the lib/ directory) +# -bindings dist/bindings//, when `bindings` is set + +on: + workflow_call: + inputs: + language: + description: "Binding language and artifact prefix, e.g. kotlin" + required: true + type: string + targets: + description: "JSON array of Rust targets to build" + required: true + type: string + bindings: + description: "Generate and upload the bindings for `language`" + type: boolean + default: true + default-features: + description: "Build moq-ffi with its default features (audio and video)" + type: boolean + default: true + outputs: + version: + description: "moq-ffi version, from the tag or (off a tag) rs/moq-ffi/Cargo.toml" + value: ${{ jobs.parse-version.outputs.version }} + +permissions: + contents: read + +# Pinned rather than "latest": `--locked` only fixes the tool's own +# dependencies, not which version of the tool cargo selects. +env: + CARGO_NDK_VERSION: 4.1.2 + +jobs: + parse-version: + name: Parse version + runs-on: ubuntu-latest + outputs: + version: ${{ steps.parse.outputs.version }} + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Parse version + id: parse + run: just gh release parse-version moq-ffi + + build: + name: Build moq-ffi (${{ matrix.target }}) + needs: [parse-version] + runs-on: ${{ contains(matrix.target, '-apple-') && 'macos-latest' || contains(matrix.target, '-windows-') && 'windows-latest' || 'ubuntu-latest' }} + + strategy: + fail-fast: false + matrix: + target: ${{ fromJSON(inputs.targets) }} + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + with: + targets: ${{ matrix.target }} + + # No Rust cache: its entry would evict the store every pull request + # restores from the 10 GB budget. See cache.yml. + + - name: Install cross-compilation tools (Linux ARM64) + if: matrix.target == 'aarch64-unknown-linux-gnu' + run: | + sudo apt-get update + # g++ as well as gcc: moq-video's openh264 fallback is C++, and + # cc-rs looks for aarch64-linux-gnu-g++ by name. + sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu + + - name: Install cargo-ndk (Android) + if: contains(matrix.target, 'android') + run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" + + - name: Build + shell: bash + env: + BUILD_TARGET: ${{ matrix.target }} + BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + DEFAULT_FEATURES: ${{ inputs.default-features }} + # Set iOS deployment target to avoid ___chkstk_darwin linker errors. + IPHONEOS_DEPLOYMENT_TARGET: ${{ contains(matrix.target, 'apple-ios') && '16.0' || '' }} + run: | + args=(--target "$BUILD_TARGET" --version "$BUILD_VERSION" --output dist) + if [[ "$DEFAULT_FEATURES" == false ]]; then + args+=(--no-default-features) + fi + just rs package-ffi "${args[@]}" + + - name: Upload lib + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.language }}-lib-${{ matrix.target }} + # Only the lib/ contents, so a caller's download is /. + path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ + + bindings: + name: Generate bindings + needs: [parse-version] + if: inputs.bindings + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + + # No Rust cache: its entry would evict the store every pull request + # restores from the 10 GB budget. See cache.yml. + + # Go uses a third-party generator; build.sh skips Go when it is absent. + - name: Install uniffi-bindgen-go + if: inputs.language == 'go' + env: + # A fork until NordSecurity ships a uniffi 0.32 generator; see flake.nix. + # The revision is v0.10.0-kixelated.1+v0.32.0. + UNIFFI_BINDGEN_GO_REPO: https://github.com/kixelated/uniffi-bindgen-go + UNIFFI_BINDGEN_GO_REV: v0.10.0-kixelated.1+v0.32.0 + run: | + cargo install --locked uniffi-bindgen-go \ + --git "$UNIFFI_BINDGEN_GO_REPO" \ + --rev "$UNIFFI_BINDGEN_GO_REV" + + - name: Generate bindings + env: + BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + run: | + just rs package-ffi \ + --bindings-only \ + --version "$BUILD_VERSION" \ + --output dist + + - name: Upload bindings + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.language }}-bindings + path: dist/bindings/${{ inputs.language }}/ + # A language build.sh does not generate would otherwise upload nothing. + if-no-files-found: error diff --git a/.github/workflows/release-go-ffi.yml b/.github/workflows/release-go-ffi.yml index f7db014cd46..e35e940046b 100644 --- a/.github/workflows/release-go-ffi.yml +++ b/.github/workflows/release-go-ffi.yml @@ -16,10 +16,11 @@ on: pull_request: paths: - ".github/workflows/release-go-ffi.yml" - - ".github/scripts/release.sh" + - ".github/workflows/release-ffi.yml" + - "sh/gh/release.sh" - "go/ffi/**" - - "go/scripts/package-ffi.sh" - - "go/scripts/publish-ffi.sh" + - "sh/go/package-ffi.sh" + - "sh/go/publish-ffi.sh" - "rs/moq-ffi/build.sh" permissions: @@ -33,132 +34,32 @@ concurrency: group: release-go-ffi-${{ github.ref_type == 'tag' && 'publish' || github.ref }} cancel-in-progress: ${{ github.ref_type != 'tag' }} -env: - # A fork until NordSecurity ships a uniffi 0.32 generator; see flake.nix. - # The revision is v0.9.0+v0.32.0. - UNIFFI_BINDGEN_GO_REPO: https://github.com/kixelated/uniffi-bindgen-go - UNIFFI_BINDGEN_GO_REV: v0.9.0+v0.32.0 - jobs: - parse-version: - name: Parse version - runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build moq-ffi (${{ matrix.target }}) - needs: [parse-version] - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-apple-darwin - os: macos-latest - - target: x86_64-pc-windows-msvc - os: windows-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - # g++ as well as gcc: moq-video's openh264 fallback is C++, and - # cc-rs looks for aarch64-linux-gnu-g++ by name. - sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: Build - shell: bash - env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload lib - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: go-lib-${{ matrix.target }} - # package.sh expects /; upload just lib/ contents. - path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ - - bindings: - name: Generate bindings - needs: [parse-version] - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install uniffi-bindgen-go - run: | - cargo install --locked uniffi-bindgen-go \ - --git "$UNIFFI_BINDGEN_GO_REPO" \ - --rev "$UNIFFI_BINDGEN_GO_REV" - - - name: Generate bindings - env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --bindings-only \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload bindings - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: go-bindings - path: dist/bindings/go/ + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: go + targets: >- + [ + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "aarch64-apple-darwin", + "x86_64-pc-windows-msvc" + ] package: name: Package - needs: [parse-version, build, bindings] + needs: [ffi] runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download per-target libs uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -200,9 +101,9 @@ jobs: - name: Package env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./go/scripts/package-ffi.sh \ + just go package-ffi \ --version "$BUILD_VERSION" \ --source-dir go/ffi \ --lib-dir libs \ @@ -217,15 +118,17 @@ jobs: publish: name: Publish to Go module mirror - needs: [package, parse-version] + needs: [ffi, package] runs-on: ubuntu-latest if: github.ref_type == 'tag' steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -245,24 +148,26 @@ jobs: - name: Publish to moq-dev/moq-go-ffi mirror env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} # Token is minted fresh per run, expires in 1 hour, never at rest. GO_FFI_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./go/scripts/publish-ffi.sh + run: just go publish-ffi publish-dry-run: name: Publish dry-run - needs: [package, parse-version] + needs: [ffi, package] runs-on: ubuntu-latest if: github.ref_type != 'tag' steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -271,5 +176,5 @@ jobs: - name: Dry-run publish to mirror env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: ./go/scripts/publish-ffi.sh --dry-run + BUILD_VERSION: ${{ needs.ffi.outputs.version }} + run: just go publish-ffi --dry-run diff --git a/.github/workflows/release-go.yml b/.github/workflows/release-go.yml index 0f87ed9b743..bb817841acd 100644 --- a/.github/workflows/release-go.yml +++ b/.github/workflows/release-go.yml @@ -66,6 +66,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version: "1.23" @@ -105,7 +107,7 @@ jobs: if: github.event_name == 'push' env: FFI_VERSION: ${{ steps.ffi.outputs.version }} - run: .github/scripts/release.sh ffi-unreleased "$FFI_VERSION" + run: just gh release ffi-unreleased "$FFI_VERSION" # Skip on unreleased ffi changes, and when the pinned ffi's mirror tag is # missing (release-plz merged but Release Go FFI hasn't published yet): @@ -160,7 +162,7 @@ jobs: LINE: ${{ steps.line.outputs.line }} FFI_VERSION: ${{ steps.ffi.outputs.version }} run: | - ./go/scripts/package-wrapper.sh --line "$LINE" --ffi-version "$FFI_VERSION" --output release-out + just go package-wrapper --line "$LINE" --ffi-version "$FFI_VERSION" --output release-out - name: Upload wrapper module if: steps.gate.outputs.skip != 'true' @@ -180,6 +182,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -203,4 +207,4 @@ jobs: GO_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./go/scripts/publish-wrapper.sh + run: just go publish-wrapper diff --git a/.github/workflows/release-js.yml b/.github/workflows/release-js.yml index a8480c33106..422a685f123 100644 --- a/.github/workflows/release-js.yml +++ b/.github/workflows/release-js.yml @@ -38,6 +38,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does. Without it + # `nix develop` built the dev shell from source, about 13 minutes. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Setup npm registry uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6 diff --git a/.github/workflows/release-kt-ffi.yml b/.github/workflows/release-kt-ffi.yml index 7694fb4b839..0b48e10b929 100644 --- a/.github/workflows/release-kt-ffi.yml +++ b/.github/workflows/release-kt-ffi.yml @@ -20,131 +20,27 @@ concurrency: group: release-kt-ffi cancel-in-progress: false -# Pinned rather than "latest": `--locked` only fixes the tool's own -# dependencies, not which version of the tool cargo selects. -env: - CARGO_NDK_VERSION: 4.1.2 - jobs: - parse-version: - name: Parse version - runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build moq-ffi (${{ matrix.target }}) - needs: [parse-version] - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - # Android - - target: aarch64-linux-android - os: ubuntu-latest - - target: armv7-linux-androideabi - os: ubuntu-latest - - target: x86_64-linux-android - os: ubuntu-latest - # Desktop JVM - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-apple-darwin - os: macos-latest - - target: x86_64-pc-windows-msvc - os: windows-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - # g++ as well as gcc: moq-video's openh264 fallback is C++, and - # cc-rs looks for aarch64-linux-gnu-g++ by name. - sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: Install cargo-ndk (Android) - if: contains(matrix.target, 'android') - run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" - - - name: Build - shell: bash - env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload lib - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: kotlin-lib-${{ matrix.target }} - # Upload only the lib/ contents; package.sh expects /. - path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ - - bindings: - name: Generate bindings - needs: [parse-version] - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Generate bindings - env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --bindings-only \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload bindings - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: kotlin-bindings - # Upload only the kotlin subdir. - path: dist/bindings/kotlin/ + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: kotlin + # Android, then the desktop JVM. + targets: >- + [ + "aarch64-linux-android", + "armv7-linux-androideabi", + "x86_64-linux-android", + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "aarch64-apple-darwin", + "x86_64-pc-windows-msvc" + ] package: name: Package and publish - needs: [parse-version, build, bindings] + needs: [ffi] runs-on: ubuntu-latest env: # Picked up by com.vanniktech.maven.publish via Gradle project properties. @@ -160,6 +56,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1 with: distribution: temurin @@ -197,9 +95,9 @@ jobs: - name: Stage native libs + bindings into the gradle module env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./kt/scripts/package.sh \ + just kt package \ --version "$BUILD_VERSION" \ --lib-dir libs \ --bindings-dir bindings \ @@ -208,7 +106,7 @@ jobs: - name: Publish to Maven Central if: github.ref_type == 'tag' env: - MOQFFI_VERSION: ${{ needs.parse-version.outputs.version }} + MOQFFI_VERSION: ${{ needs.ffi.outputs.version }} ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }} ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }} run: | diff --git a/.github/workflows/release-kt-lib.yml b/.github/workflows/release-kt-lib.yml index 92fcbf64220..f3947ef2ac5 100644 --- a/.github/workflows/release-kt-lib.yml +++ b/.github/workflows/release-kt-lib.yml @@ -30,7 +30,7 @@ on: - "kt/build.gradle.kts" - "kt/settings.gradle.kts" - ".github/workflows/release-kt-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" pull_request: paths: - "kt/moq/**" @@ -38,7 +38,7 @@ on: - "kt/build.gradle.kts" - "kt/settings.gradle.kts" - ".github/workflows/release-kt-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" - "rs/moq-ffi/build.sh" # Manual trigger so a wrapper bump can be published once the bindings it # depends on land on Maven Central (the guard below skips otherwise). @@ -75,6 +75,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Read moq.version id: version run: | @@ -103,18 +105,18 @@ jobs: - name: Check for unreleased FFI changes id: ffi-diff if: github.event_name != 'workflow_run' - run: .github/scripts/release.sh ffi-unreleased "${{ steps.ffi.outputs.version }}" + run: just gh release ffi-unreleased "${{ steps.ffi.outputs.version }}" - name: Check wrapper publication id: wrapper - run: .github/scripts/release.sh maven-exists dev.moq moq "${{ steps.version.outputs.version }}" + run: just gh release maven-exists dev.moq moq "${{ steps.version.outputs.version }}" # The bindings this checkout generates must be on Maven Central, or the # wrapper's POM range resolves to an older moq-ffi without them. - name: Check bindings publication id: bindings if: github.event_name != 'workflow_run' && steps.wrapper.outputs.exists != 'true' && steps.ffi-diff.outputs.unreleased != 'true' - run: .github/scripts/release.sh maven-exists dev.moq moq-ffi "${{ steps.ffi.outputs.version }}" + run: just gh release maven-exists dev.moq moq-ffi "${{ steps.ffi.outputs.version }}" - name: Decide publish id: decide @@ -167,6 +169,8 @@ jobs: ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.sha }} persist-credentials: false + - uses: ./.github/actions/just + - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable @@ -178,7 +182,7 @@ jobs: env: BUILD_VERSION: ${{ needs.check-version.outputs.version }} run: | - ./rs/moq-ffi/build.sh --bindings-only --version "$BUILD_VERSION" --output dist + just rs package-ffi --bindings-only --version "$BUILD_VERSION" --output dist mkdir -p kt/moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/moq cp dist/bindings/kotlin/uniffi/moq/moq.kt \ kt/moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/moq/moq.kt @@ -202,7 +206,7 @@ jobs: - name: Recheck wrapper publication id: recheck if: github.event_name != 'pull_request' - run: .github/scripts/release.sh maven-exists dev.moq moq "${{ needs.check-version.outputs.version }}" + run: just gh release maven-exists dev.moq moq "${{ needs.check-version.outputs.version }}" - name: Publish to Maven Central if: github.event_name != 'pull_request' && steps.recheck.outputs.exists != 'true' diff --git a/.github/workflows/release-py-ffi.yml b/.github/workflows/release-py-ffi.yml index 2a79e7096ee..678abd24388 100644 --- a/.github/workflows/release-py-ffi.yml +++ b/.github/workflows/release-py-ffi.yml @@ -34,9 +34,11 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version moq-ffi + run: just gh release parse-version moq-ffi # Maturin reads the wheel version from rs/moq-ffi/Cargo.toml (via # `dynamic = ["version"]` in pyproject.toml). If a tag is pushed by diff --git a/.github/workflows/release-py.yml b/.github/workflows/release-py.yml index b2ba9f0cd2f..beb00e7dadf 100644 --- a/.github/workflows/release-py.yml +++ b/.github/workflows/release-py.yml @@ -19,7 +19,7 @@ on: paths: - "py/moq-rs/**" - ".github/workflows/release-py.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" workflow_run: workflows: ["Release Py FFI"] types: @@ -56,9 +56,11 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Read version id: version - run: .github/scripts/release.sh read-version py/moq-rs/pyproject.toml + run: just gh release read-version py/moq-rs/pyproject.toml - name: Resolve FFI version id: ffi @@ -78,14 +80,14 @@ jobs: if: github.event_name == 'push' env: FFI_VERSION: ${{ steps.ffi.outputs.version }} - run: .github/scripts/release.sh ffi-unreleased "$FFI_VERSION" + run: just gh release ffi-unreleased "$FFI_VERSION" - name: Check FFI on PyPI id: ffi-pypi if: github.event_name == 'push' && steps.ffi-gate.outputs.unreleased != 'true' env: FFI_VERSION: ${{ steps.ffi.outputs.version }} - run: .github/scripts/release.sh pypi-exists moq-ffi "$FFI_VERSION" + run: just gh release pypi-exists moq-ffi "$FFI_VERSION" - name: Unpublished FFI notice if: github.event_name == 'push' && steps.ffi-gate.outputs.unreleased != 'true' && steps.ffi-pypi.outputs.exists != 'true' @@ -100,11 +102,16 @@ jobs: id: pypi env: VERSION: ${{ steps.version.outputs.version }} - run: .github/scripts/release.sh pypi-exists moq-rs "$VERSION" + run: just gh release pypi-exists moq-rs "$VERSION" - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Build run: nix develop --command just py package diff --git a/.github/workflows/release-swift-ffi.yml b/.github/workflows/release-swift-ffi.yml index bb4c757256c..afa2fbf175e 100644 --- a/.github/workflows/release-swift-ffi.yml +++ b/.github/workflows/release-swift-ffi.yml @@ -23,100 +23,16 @@ concurrency: cancel-in-progress: false jobs: - parse-version: - name: Parse version - runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build moq-ffi (${{ matrix.target }}) - needs: [parse-version] - runs-on: macos-latest - - strategy: - fail-fast: false - matrix: - target: - - aarch64-apple-ios - - aarch64-apple-ios-sim - - aarch64-apple-darwin - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Build - shell: bash - env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - # Set iOS deployment target to avoid ___chkstk_darwin linker errors. - IPHONEOS_DEPLOYMENT_TARGET: ${{ contains(matrix.target, 'apple-ios') && '16.0' || '' }} - run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload lib - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: swift-lib-${{ matrix.target }} - path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ - - bindings: - name: Generate bindings - needs: [parse-version] - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Generate bindings - env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --bindings-only \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload bindings - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: swift-bindings - path: dist/bindings/swift/ + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: swift + targets: '["aarch64-apple-ios", "aarch64-apple-ios-sim", "aarch64-apple-darwin"]' package: name: Package - needs: [parse-version, build, bindings] + needs: [ffi] runs-on: macos-latest steps: @@ -124,6 +40,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download per-target libs uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -147,9 +65,9 @@ jobs: - name: Package env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./swift/scripts/package-ffi.sh \ + just swift package-ffi \ --version "$BUILD_VERSION" \ --lib-dir libs \ --bindings-dir bindings \ @@ -167,7 +85,7 @@ jobs: # points at this asset, so it must exist before any consumer resolves the # SPM tag. name: Attach assets to GitHub release - needs: [package, parse-version] + needs: [ffi, package] if: github.ref_type == 'tag' runs-on: ubuntu-latest permissions: @@ -181,9 +99,11 @@ jobs: # up GH_TOKEN directly, so don't persist a contents-write token. persist-credentials: false + - uses: ./.github/actions/just + - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-ffi + run: just gh release prev-tag moq-ffi - name: Download package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -195,9 +115,9 @@ jobs: env: GH_TOKEN: ${{ github.token }} RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-ffi v${{ needs.parse-version.outputs.version }}" + RELEASE_TITLE: "moq-ffi v${{ needs.ffi.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts verify: # Gate the mirror push on actually being able to resolve the staged package @@ -205,7 +125,7 @@ jobs: # fine but SPM cannot resolve (e.g. a path-based binaryTarget slipping in # where a URL+checksum is expected). name: Verify staged package resolves - needs: [release, parse-version] + needs: [ffi, release] runs-on: macos-latest steps: @@ -213,6 +133,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download staged package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -221,13 +143,13 @@ jobs: - name: Resolve and build smoke consumer env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./swift/scripts/verify-ffi.sh --tarball "artifacts/moq-ffi-${BUILD_VERSION}-swift-ffi.tar.gz" + just swift verify-ffi --tarball "artifacts/moq-ffi-${BUILD_VERSION}-swift-ffi.tar.gz" publish: name: Publish to Swift Package mirror - needs: [verify, parse-version] + needs: [ffi, verify] runs-on: ubuntu-latest steps: @@ -235,6 +157,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -254,9 +178,9 @@ jobs: - name: Publish to moq-dev/moq-swift-ffi mirror env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} # Token is minted fresh per run, expires in 1 hour, never at rest. SWIFT_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./swift/scripts/publish-ffi.sh + run: just swift publish-ffi diff --git a/.github/workflows/release-swift-lib.yml b/.github/workflows/release-swift-lib.yml index 6c5b07fc5a5..2684aa4f595 100644 --- a/.github/workflows/release-swift-lib.yml +++ b/.github/workflows/release-swift-lib.yml @@ -22,22 +22,22 @@ on: - "swift/Package.swift.template" - "swift/Sources/Moq/**" - "swift/Tests/**" - - "swift/scripts/package.sh" - - "swift/scripts/publish.sh" - - "swift/scripts/verify.sh" + - "sh/swift/package.sh" + - "sh/swift/publish.sh" + - "sh/swift/verify.sh" - ".github/workflows/release-swift-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" pull_request: paths: - "swift/VERSION" - "swift/Package.swift.template" - "swift/Sources/Moq/**" - "swift/Tests/**" - - "swift/scripts/package.sh" - - "swift/scripts/publish.sh" - - "swift/scripts/verify.sh" + - "sh/swift/package.sh" + - "sh/swift/publish.sh" + - "sh/swift/verify.sh" - ".github/workflows/release-swift-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" workflow_run: workflows: ["Release Swift FFI"] types: @@ -79,6 +79,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Read versions id: version env: @@ -101,13 +103,13 @@ jobs: if: github.event_name != 'workflow_run' env: FFI_VERSION: ${{ steps.version.outputs.ffi_version }} - run: .github/scripts/release.sh ffi-unreleased "$FFI_VERSION" + run: just gh release ffi-unreleased "$FFI_VERSION" - name: Check FFI mirror tag id: ffi-gate env: FFI_VERSION: ${{ steps.version.outputs.ffi_version }} - run: .github/scripts/release.sh git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" + run: just gh release git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" - name: Unpublished FFI notice if: steps.ffi-diff.outputs.unreleased != 'true' && steps.ffi-gate.outputs.exists != 'true' && github.event_name != 'pull_request' @@ -121,12 +123,12 @@ jobs: id: gate env: VERSION: ${{ steps.version.outputs.version }} - run: .github/scripts/release.sh git-tag-exists moq-dev/moq-swift "$VERSION" + run: just gh release git-tag-exists moq-dev/moq-swift "$VERSION" - name: Package env: BUILD_VERSION: ${{ steps.version.outputs.version }} - run: ./swift/scripts/package.sh --version "$BUILD_VERSION" --output release-out + run: just swift package --version "$BUILD_VERSION" --output release-out - name: Upload Swift package uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -149,6 +151,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Check FFI mirror tag id: ffi if: needs.build.outputs.publish == 'true' || (github.event_name == 'pull_request' && needs.build.outputs.ffi_unreleased != 'true') @@ -158,7 +162,7 @@ jobs: # rather than a hard failure, so the first bootstrap (before # moq-swift-ffi exists) skips the cross-package resolve instead of # failing the job. publish.sh stays idempotent regardless. - run: .github/scripts/release.sh git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" || echo "exists=false" >> "$GITHUB_OUTPUT" + run: just gh release git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" || echo "exists=false" >> "$GITHUB_OUTPUT" - name: Download staged package if: steps.ffi.outputs.exists == 'true' @@ -171,7 +175,7 @@ jobs: if: steps.ffi.outputs.exists == 'true' env: BUILD_VERSION: ${{ needs.build.outputs.version }} - run: ./swift/scripts/verify.sh --tarball "artifacts/moq-${BUILD_VERSION}-swift.tar.gz" + run: just swift verify --tarball "artifacts/moq-${BUILD_VERSION}-swift.tar.gz" - name: Skip notice if: needs.build.outputs.ffi_unreleased == 'true' @@ -194,6 +198,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -218,7 +224,7 @@ jobs: SWIFT_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./swift/scripts/publish.sh + run: just swift publish publish-dry-run: name: Publish dry-run @@ -231,6 +237,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -240,4 +248,4 @@ jobs: - name: Dry-run publish to mirror env: BUILD_VERSION: ${{ needs.build.outputs.version }} - run: ./swift/scripts/publish.sh --dry-run + run: just swift publish --dry-run diff --git a/.github/workflows/rpm-repo.yml b/.github/workflows/rpm-repo.yml index 4c7df9dd844..93dc8c4a943 100644 --- a/.github/workflows/rpm-repo.yml +++ b/.github/workflows/rpm-repo.yml @@ -32,6 +32,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Set up packaging tools uses: ./.github/actions/setup-packaging @@ -51,10 +53,9 @@ jobs: - name: Publish to R2 shell: bash env: - ARTIFACTS_DIR: artifacts R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }} R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }} SIGNING_KEY: ${{ secrets.SIGNING_KEY }} SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} - run: ./infra/rpm/publish.sh + run: just infra rpm publish "$GITHUB_WORKSPACE/artifacts" diff --git a/.github/workflows/swift.yml b/.github/workflows/swift.yml index 8c3cdcbfab8..6a806b3ce44 100644 --- a/.github/workflows/swift.yml +++ b/.github/workflows/swift.yml @@ -14,6 +14,7 @@ on: branches: [main] paths: - "swift/**" + - "sh/swift/**" - "doc/lib/swift/**" - "doc/lib/samples.sh" - "rs/moq-ffi/**" @@ -26,6 +27,7 @@ on: types: [opened, synchronize, reopened, closed] paths: - "swift/**" + - "sh/swift/**" - "doc/lib/swift/**" - "doc/lib/samples.sh" - "rs/moq-ffi/**" @@ -53,6 +55,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable with: @@ -66,7 +70,6 @@ jobs: # none of which depend on the event, so a pull request restores what a # push saved. save-if: ${{ github.event_name == 'push' }} - cache-on-failure: true - name: Rust simulator check shell: bash @@ -81,4 +84,4 @@ jobs: done - name: Swift check - run: ./swift/scripts/check.sh + run: just swift check diff --git a/.github/workflows/wasm.yml b/.github/workflows/wasm.yml index d0c8392de3d..5f93aab325c 100644 --- a/.github/workflows/wasm.yml +++ b/.github/workflows/wasm.yml @@ -43,6 +43,7 @@ on: - "test/wasm/**" - "test/lib/**" - "justfile" + - "js/justfile" - "test/justfile" - ".cargo/config.toml" - "package.json" diff --git a/.gitignore b/.gitignore index af3a5c21aca..53171c83752 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,8 @@ *.local.json # Claude Code scratch space. These are untracked working directories, and -# `just _changed` counts untracked files, so leaving them visible pushes the -# changed-file list past its cap and silently turns every scoped `just check` -# into `check --all`. The worktrees also carry their own biome.jsonc, which the +# `just check` counts untracked files, so leaving them visible would put their +# whole tree in scope. The worktrees also carry their own biome.jsonc, which the # unscoped run then rejects as a nested root config. /.claude/cache/ /.claude/tmp/ diff --git a/AGENTS.md b/AGENTS.md index d896defddc3..e97c9d5a700 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,7 @@ A bad shape costs a breaking change in every language, and the surface is huge. - Keep things private until a consumer needs them. Scrutinize every new exported item. - Never add `foo_with_x`, `foo_checked`, or a compatibility shim. Make the breaking change to `foo` on `dev` instead. Additive changes stay on `main`. - Let the type system make misuse unrepresentable +- A broadcast, track, or group name always means the same content. MoQ has no ETag-style invalidation, so a publisher that reuses a name for different content (such as restarting group numbers) is a bug; publish a new broadcast instead of working around it. - Avoid callback parameters. Return a handle, an event, or a Producer/Consumer split. - Avoid 4+ args; use a struct or object. - Name by role, not today's implementation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78529a74cce..1974205cd8c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,6 +50,10 @@ Wait for Codex to review the final head before merging. Merge only on its thumbs up, or once every Codex finding on the PR is fixed or replied to. Codex skips fork PRs; ask the maintainer to request one. +# CI + +Workflow steps run `just` recipes, never a script path; `just gh check` enforces it. + # Follow-ups If you encounter issues, or findings that are out of scope, create follow-up quests. diff --git a/Cargo.lock b/Cargo.lock index 855eea9f64f..7bd01a7c9a3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -210,7 +210,7 @@ version = "1.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" dependencies = [ - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -221,7 +221,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" dependencies = [ "anstyle", "once_cell_polyfill", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -1977,7 +1977,7 @@ dependencies = [ "cfg-if", "libc", "socket2 0.6.5", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -2186,7 +2186,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" dependencies = [ "libc", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -2592,7 +2592,7 @@ dependencies = [ "gobject-sys", "libc", "system-deps", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -2835,13 +2835,13 @@ dependencies = [ [[package]] name = "hang" -version = "0.21.8" +version = "0.21.9" dependencies = [ "anyhow", "bytes", "derive_more 2.1.1", "hex", - "kio 0.6.1", + "kio 0.6.2", "lazy_static", "moq-json", "moq-mux", @@ -3802,7 +3802,7 @@ dependencies = [ [[package]] name = "kio" -version = "0.6.1" +version = "0.6.2" dependencies = [ "criterion", "futures", @@ -3884,7 +3884,7 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981" [[package]] name = "libmoq" -version = "0.6.8" +version = "0.6.9" [[package]] name = "libredox" @@ -4135,7 +4135,7 @@ dependencies = [ [[package]] name = "moq-archive" -version = "0.0.8" +version = "0.0.9" dependencies = [ "async-trait", "bytes", @@ -4152,7 +4152,7 @@ dependencies = [ [[package]] name = "moq-audio" -version = "0.1.7" +version = "0.1.8" dependencies = [ "block2 0.6.2", "bytes", @@ -4160,7 +4160,7 @@ dependencies = [ "dispatch2", "fixed-resample", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-mux", "moq-net", "objc2 0.6.4", @@ -4183,14 +4183,14 @@ dependencies = [ [[package]] name = "moq-auth" -version = "0.1.5" +version = "0.2.0" dependencies = [ "anyhow", "aws-lc-rs", "axum", "base64 0.23.1", "jsonwebtoken", - "kio 0.6.1", + "kio 0.6.2", "moq-auth", "moq-pattern", "moq-token", @@ -4232,7 +4232,7 @@ dependencies = [ [[package]] name = "moq-boy" -version = "0.5.8" +version = "0.5.9" dependencies = [ "anyhow", "boytacean", @@ -4258,7 +4258,7 @@ dependencies = [ "bytes", "cbindgen", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-audio", "moq-json", "moq-loc", @@ -4276,7 +4276,7 @@ dependencies = [ [[package]] name = "moq-cli" -version = "0.12.8" +version = "0.13.0" dependencies = [ "anyhow", "axum", @@ -4297,6 +4297,7 @@ dependencies = [ "moq-tokio", "moq-transcode", "moq-video", + "mpeg2ts", "pollster", "reqwest", "rustls", @@ -4314,14 +4315,14 @@ dependencies = [ [[package]] name = "moq-e2ee" -version = "0.0.8" +version = "0.0.9" dependencies = [ "aws-lc-rs", "base64 0.23.1", "bytes", "criterion", "hex", - "kio 0.6.1", + "kio 0.6.2", "moq-net", "serde_json", "thiserror 2.0.21", @@ -4333,12 +4334,12 @@ dependencies = [ [[package]] name = "moq-ffi" -version = "0.4.8" +version = "0.4.9" dependencies = [ "bytes", "getrandom 0.4.3", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-audio", "moq-json", "moq-mux", @@ -4362,7 +4363,7 @@ version = "0.2.0" dependencies = [ "bytes", "flate2", - "kio 0.6.1", + "kio 0.6.2", "moq-net", "thiserror 2.0.21", "tracing", @@ -4370,7 +4371,7 @@ dependencies = [ [[package]] name = "moq-gst" -version = "0.4.8" +version = "0.4.9" dependencies = [ "anyhow", "bytes", @@ -4389,13 +4390,13 @@ dependencies = [ [[package]] name = "moq-hls" -version = "0.5.8" +version = "0.5.9" dependencies = [ "axum", "bytes", "hang", "humantime", - "kio 0.6.1", + "kio 0.6.2", "m3u8-rs", "moq-mux", "moq-net", @@ -4413,12 +4414,12 @@ dependencies = [ [[package]] name = "moq-json" -version = "0.5.5" +version = "0.5.6" dependencies = [ "bytes", "criterion", "json-patch", - "kio 0.6.1", + "kio 0.6.2", "moq-flate", "moq-net", "serde", @@ -4430,7 +4431,7 @@ dependencies = [ [[package]] name = "moq-loc" -version = "0.2.16" +version = "0.2.17" dependencies = [ "bytes", "moq-net", @@ -4448,7 +4449,7 @@ dependencies = [ [[package]] name = "moq-mux" -version = "0.10.8" +version = "0.10.9" dependencies = [ "anyhow", "base64 0.23.1", @@ -4456,7 +4457,7 @@ dependencies = [ "futures", "h264-parser", "hang", - "kio 0.6.1", + "kio 0.6.2", "memchr", "moq-flate", "moq-json", @@ -4474,6 +4475,7 @@ dependencies = [ "thiserror 2.0.21", "tokio", "tracing", + "tracing-test", "url", "web-async", "webm-iterable", @@ -4485,14 +4487,14 @@ version = "0.20.0" [[package]] name = "moq-net" -version = "0.3.7" +version = "0.3.8" dependencies = [ "arrayvec", "bytes", "criterion", "futures", "getrandom 0.4.3", - "kio 0.6.1", + "kio 0.6.2", "loom", "moq-pattern", "num_enum", @@ -4593,7 +4595,7 @@ dependencies = [ [[package]] name = "moq-pattern" -version = "0.1.1" +version = "0.1.2" dependencies = [ "moq-pattern", "serde", @@ -4602,7 +4604,7 @@ dependencies = [ [[package]] name = "moq-relay" -version = "0.15.8" +version = "0.16.0" dependencies = [ "anyhow", "axum", @@ -4646,9 +4648,9 @@ dependencies = [ [[package]] name = "moq-room" -version = "0.2.8" +version = "0.2.9" dependencies = [ - "kio 0.6.1", + "kio 0.6.2", "moq-auth", "moq-json", "moq-net", @@ -4660,7 +4662,7 @@ dependencies = [ [[package]] name = "moq-rtc" -version = "0.3.8" +version = "0.3.9" dependencies = [ "aws-lc-rs", "axum", @@ -4674,13 +4676,14 @@ dependencies = [ "thiserror 2.0.21", "tokio", "tracing", + "tracing-test", "url", "uuid", ] [[package]] name = "moq-rtmp" -version = "0.3.8" +version = "0.3.9" dependencies = [ "anyhow", "byteorder", @@ -4692,7 +4695,6 @@ dependencies = [ "moq-net", "moq-tokio", "rand 0.10.3", - "rml_amf0", "rustls", "sha2", "socket2 0.6.5", @@ -4715,7 +4717,7 @@ dependencies = [ [[package]] name = "moq-sock" -version = "0.1.0" +version = "0.2.0" dependencies = [ "core_affinity", "libc", @@ -4728,7 +4730,7 @@ dependencies = [ [[package]] name = "moq-srt" -version = "0.3.8" +version = "0.3.9" dependencies = [ "bytes", "futures", @@ -4740,11 +4742,12 @@ dependencies = [ "thiserror 2.0.21", "tokio", "tracing", + "tracing-test", ] [[package]] name = "moq-stats" -version = "0.2.8" +version = "0.2.9" dependencies = [ "futures", "moq-json", @@ -4777,7 +4780,7 @@ dependencies = [ [[package]] name = "moq-tokio" -version = "0.19.19" +version = "0.19.20" dependencies = [ "anyhow", "bytes", @@ -4831,12 +4834,12 @@ dependencies = [ [[package]] name = "moq-transcode" -version = "0.1.7" +version = "0.1.8" dependencies = [ "anyhow", "bytes", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-mux", "moq-net", "moq-tokio", @@ -4850,14 +4853,14 @@ dependencies = [ [[package]] name = "moq-uring" -version = "0.0.9" +version = "0.0.10" dependencies = [ "anyhow", "bytes", "criterion", "http", "io-uring", - "kio 0.6.1", + "kio 0.6.2", "libc", "moq-net", "moq-noq-proto", @@ -4907,7 +4910,7 @@ dependencies = [ [[package]] name = "moq-video" -version = "0.1.7" +version = "0.1.8" dependencies = [ "anyhow", "ash", @@ -4922,7 +4925,7 @@ dependencies = [ "futures", "h264-reader", "hang", - "kio 0.6.1", + "kio 0.6.2", "libc", "libloading 0.9.0", "linux-raw-sys 0.12.1", @@ -5498,7 +5501,7 @@ version = "0.50.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" dependencies = [ - "windows-sys 0.59.0", + "windows-sys 0.61.2", ] [[package]] @@ -6933,7 +6936,7 @@ dependencies = [ "once_cell", "socket2 0.5.10", "tracing", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -7288,16 +7291,6 @@ dependencies = [ "portable-atomic-util", ] -[[package]] -name = "rml_amf0" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "63551cfcd4d1f42733c190e4b58dd268b1eacb73410d9afbf62784aa12cac240" -dependencies = [ - "byteorder", - "thiserror 1.0.69", -] - [[package]] name = "rsa" version = "0.9.10" @@ -7372,7 +7365,7 @@ dependencies = [ "errno", "libc", "linux-raw-sys 0.4.15", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -7385,7 +7378,7 @@ dependencies = [ "errno", "libc", "linux-raw-sys 0.12.1", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -7444,7 +7437,7 @@ dependencies = [ "security-framework", "security-framework-sys", "webpki-root-certs", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -8122,7 +8115,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" dependencies = [ "libc", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -8597,10 +8590,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" dependencies = [ "fastrand", - "getrandom 0.4.3", + "getrandom 0.3.4", "once_cell", "rustix 1.1.5", - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -9248,7 +9241,7 @@ checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e" dependencies = [ "memoffset", "tempfile", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -10179,7 +10172,7 @@ version = "0.1.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" dependencies = [ - "windows-sys 0.59.0", + "windows-sys 0.52.0", ] [[package]] @@ -10327,15 +10320,6 @@ dependencies = [ "windows-targets 0.52.6", ] -[[package]] -name = "windows-sys" -version = "0.59.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" -dependencies = [ - "windows-targets 0.52.6", -] - [[package]] name = "windows-sys" version = "0.60.2" diff --git a/Cargo.toml b/Cargo.toml index e58b93783a0..28369f6eee8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -118,14 +118,14 @@ dispatch2 = "0.3.1" flate2 = { version = "1.1", default-features = false } futures = "0.3" getrandom = { version = "0.4", features = ["wasm_js"] } -hang = { version = "0.21.8", path = "rs/hang" } +hang = { version = "0.21.9", path = "rs/hang" } hex = "0.4" # HMAC-SHA256 for the mDNS membership proofs (moq-tokio's `mdns` feature). hmac = "0.13" humantime = "2.3" io-uring = "0.7.14" jsonwebtoken = "11" -kio = { version = "0.6.1", path = "rs/kio" } +kio = { version = "0.6.2", path = "rs/kio" } lazy_static = "1.5" libc = "0.2" libloading = "0.9" @@ -136,15 +136,15 @@ loom = { version = "0.7.2", features = ["futures"] } # DNS-SD advertisement and browsing for LAN peer discovery (moq-tokio's `mdns` feature). # `async` awaits the event channel instead of blocking a thread on it. mdns-sd = { version = "0.21", features = ["async"] } -moq-audio = { version = "0.1.7", path = "rs/moq-audio", default-features = false } -moq-auth = { version = "0.1.5", path = "rs/moq-auth" } +moq-audio = { version = "0.1.8", path = "rs/moq-audio", default-features = false } +moq-auth = { version = "0.2.0", path = "rs/moq-auth" } moq-flate = { version = "0.2.0", path = "rs/moq-flate" } -moq-hls = { version = "0.5.8", path = "rs/moq-hls", default-features = false } -moq-json = { version = "0.5.5", path = "rs/moq-json" } -moq-loc = { version = "0.2.16", path = "rs/moq-loc" } +moq-hls = { version = "0.5.9", path = "rs/moq-hls", default-features = false } +moq-json = { version = "0.5.6", path = "rs/moq-json" } +moq-loc = { version = "0.2.17", path = "rs/moq-loc" } moq-msf = { version = "0.5.1", path = "rs/moq-msf" } -moq-mux = { version = "0.10.8", path = "rs/moq-mux" } -moq-net = { version = "0.3.7", path = "rs/moq-net" } +moq-mux = { version = "0.10.9", path = "rs/moq-mux" } +moq-net = { version = "0.3.8", path = "rs/moq-net" } # The MoQ fork of noq (moq-dev/noq). iroh keeps upstream noq, so a build with the # iroh feature carries both stacks. moq-noq-proto = { version = "2.0", default-features = false } @@ -153,24 +153,24 @@ moq-noq-udp = "2.0" # driver at runtime. Compiles on any platform (macOS included) but only actually # used by moq-video on Linux. moq-nvenc = { version = "0.1.2", path = "rs/moq-nvenc" } -moq-pattern = { version = "0.1.1", path = "rs/moq-pattern" } -moq-relay = { version = "0.15.8", path = "rs/moq-relay", default-features = false } -moq-rtc = { version = "0.3.8", path = "rs/moq-rtc" } -moq-rtmp = { version = "0.3.8", path = "rs/moq-rtmp" } -moq-sock = { version = "0.1.0", path = "rs/moq-sock" } -moq-srt = { version = "0.3.8", path = "rs/moq-srt" } -moq-stats = { version = "0.2.8", path = "rs/moq-stats" } -moq-tokio = { version = "0.19.19", path = "rs/moq-tokio", default-features = false } +moq-pattern = { version = "0.1.2", path = "rs/moq-pattern" } +moq-relay = { version = "0.16.0", path = "rs/moq-relay", default-features = false } +moq-rtc = { version = "0.3.9", path = "rs/moq-rtc" } +moq-rtmp = { version = "0.3.9", path = "rs/moq-rtmp" } +moq-sock = { version = "0.2.0", path = "rs/moq-sock" } +moq-srt = { version = "0.3.9", path = "rs/moq-srt" } +moq-stats = { version = "0.2.9", path = "rs/moq-stats" } +moq-tokio = { version = "0.19.20", path = "rs/moq-tokio", default-features = false } # Default features off on moq-transcode and moq-video so each workspace consumer # chooses native codecs, OpenH264, and rendering explicitly. Both crates still # provide working native plus software defaults when depended on directly. # VAAPI is opt-in everywhere; its decoder is hardware-validated, while its # encoder is not yet. -moq-transcode = { version = "0.1.7", path = "rs/moq-transcode", default-features = false } +moq-transcode = { version = "0.1.8", path = "rs/moq-transcode", default-features = false } # default-features off (the noq backend) so the consumer picks which QUIC # stack the io_uring path compiles; cargo features are additive, so a default-on # backend could not be opted out of. -moq-uring = { version = "0.0.9", path = "rs/moq-uring", default-features = false } +moq-uring = { version = "0.0.10", path = "rs/moq-uring", default-features = false } # In-tree fork of `v4l` with the videodev2.h bindings checked in, so moq-video's # `capture` and `v4l2` need no libclang or kernel headers. Linux only; an empty # stub elsewhere. @@ -183,7 +183,7 @@ moq-vaapi = "0.1.0" # `features = ["capture"]` to a consumer that ships in those bindings pulls the # whole device graph into every one of them. Codec features are independent of # that argument, so moq-ffi and moq-c opt NVIDIA, OpenH264, and VAAPI back in. -moq-video = { version = "0.1.7", path = "rs/moq-video", default-features = false } +moq-video = { version = "0.1.8", path = "rs/moq-video", default-features = false } nix = { version = "0.31.3", features = ["net", "socket", "uio"] } # Upstream noq-proto, only for iroh's controller factory types. noq-proto = { version = "1.2", default-features = false } @@ -315,7 +315,7 @@ debug = true # Size-optimized build for the browser/WASM bindings (rs/moq-wasm). Shipping over # the wire, so optimize for size, not speed (~579KB -> ~471KB gzipped vs the -# default release profile). `just wasm` builds with `--profile wasm-release`. +# default release profile). `just js wasm` builds with `--profile wasm-release`. [profile.wasm-release] inherits = "release" opt-level = "z" diff --git a/bench/justfile b/bench/justfile deleted file mode 100755 index b3fa64c3929..00000000000 --- a/bench/justfile +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env just --justfile - -set working-directory := '..' - -# Benchmark the current tree, or compare it with a commit. -compare $BASE="": - #!/usr/bin/env bash - exec bench/run.sh "$BASE" - -# Compare the shared Tokio runtime with independent Tokio and io_uring workers. -runtime $ROUNDS="3" $WORKERS="": - #!/usr/bin/env bash - MOQ_BENCH_RUNTIME_ROUNDS="$ROUNDS" MOQ_BENCH_RUNTIME_WORKERS="$WORKERS" \ - exec bench/run.sh --runtime - -# Compile every binary and feature used by the repository-level harness. -check: - cargo check --locked --package moq-relay --package moq-bench \ - --features moq-relay/io-uring diff --git a/cpp/obs/justfile b/cpp/obs/justfile index e6e0a496dc0..5fc4ff39161 100644 --- a/cpp/obs/justfile +++ b/cpp/obs/justfile @@ -21,389 +21,48 @@ default: # Configure via CMake presets. MOQ_LOCAL defaults to the repo root inside # CMakeLists.txt (so moq-c builds from rs/moq-c); pass `path=/some/moq` to -# override. We deliberately don't compute the path here: `justfile_directory()` -# resolves to the root justfile when this runs as `just obs setup`, so the - -# relative math would point outside the repo. +# override it. setup preset="" path="": - #!/usr/bin/env bash - set -euo pipefail - PRESET=$(just preset "{{ preset }}") - if [ -n "{{ path }}" ]; then - echo "Configuring with preset: $PRESET and MOQ_LOCAL={{ path }}" - cmake --preset "$PRESET" -DMOQ_LOCAL="{{ path }}" - else - echo "Configuring with preset: $PRESET (MOQ_LOCAL defaults to the repo root)" - cmake --preset "$PRESET" - fi + cmake --preset "$(../../sh/obs/preset.sh '{{ preset }}')" {{ if path == "" { "" } else { "-DMOQ_LOCAL=" + quote(path) } }} # Build via CMake presets. Run `just obs setup` first (it configures + downloads - # deps); not chained here because on macOS setup reconfigures OBS, which is slow. build preset="": - #!/usr/bin/env bash - set -euo pipefail - PRESET=$(just preset "{{ preset }}") - cmake --build --preset "$PRESET" - -# Copy the freshly built plugin into the OBS user plugin dir and launch OBS. - -# Uses the installed OBS (no local OBS build required). macOS only for now. -run: - #!/usr/bin/env bash - set -euo pipefail - if [[ "$OSTYPE" != "darwin"* ]]; then - echo "just run is macOS-only for now; copy build_*/obs-moq.* into your OBS plugin dir manually" >&2 - exit 1 - fi - dest="$HOME/Library/Application Support/obs-studio/plugins" - mkdir -p "$dest" - cp -a build_macos/RelWithDebInfo/obs-moq.plugin "$dest/" - RUST_LOG=debug RUST_BACKTRACE=1 OBS_LOG_LEVEL=debug /Applications/OBS.app/Contents/MacOS/OBS + cmake --build --preset "$(../../sh/obs/preset.sh '{{ preset }}')" # Type-check every plugin source and unit test, without linking or an obs-deps -# download. -# -# This is the gate to run in a worktree. `just obs build` needs the -# multi-hundred-MB obs-deps bundle (macOS/Windows) and a full cargo build, per -# worktree; this needs neither, because the dev shell carries all three header -# sets: libobs pinned to the same OBS release buildspec.json downloads (see -# `obs-headers` in flake.nix), Qt6, and ffmpeg. CI links the real thing on Linux -# (.github/workflows/obs.yml). -# -# It compiles the Qt sources too, which the CMake build only does when -# ENABLE_QT and ENABLE_FRONTEND_API are on, so the definitions they gate on are -# set here to match. -# -# test/ is in scope because each test file defines the moq-c entry points the -# plugin calls, so a signature that drifts from the generated moq.h is a -# conflicting C declaration. Catching that needs only headers, which is why it -# belongs here: `just obs ci` finds the same drift, but only where obs.yml's -# path filter reaches, and `just obs test` is manual. +# download. The gate to run in a worktree. compile: - #!/usr/bin/env bash - set -euo pipefail - # Never skips, for the reason `test` doesn't: a compile gate that reports - # success without compiling is worse than no gate. Everything it needs is in - # the dev shell, so the fix is always to enter it. - cxx="${CXX:-c++}" - if ! command -v "$cxx" >/dev/null; then - echo "no C++ compiler at '$cxx'" >&2 - exit 1 - fi - for pkgs in "Qt6Widgets Qt6Gui Qt6Core" "libavcodec libavutil libswscale libswresample"; do - # shellcheck disable=SC2086 - if ! pkg-config --exists $pkgs; then - echo "missing headers for: $pkgs" >&2 - echo "run inside 'nix develop', which supplies Qt6 and ffmpeg on every platform" >&2 - exit 1 - fi - done - - # Assign first so a failure in `_includes` still aborts under `set -e`, - # then split on newlines only: an include path may contain spaces. - includes_raw=$(just _includes) - includes=() - while IFS= read -r flag; do includes+=("$flag"); done <<< "$includes_raw" - - qt=$(pkg-config --cflags Qt6Widgets Qt6Gui Qt6Core) - ffmpeg=$(pkg-config --cflags libavcodec libavutil libswscale libswresample) - - # MOQ_VERSION_STRING only reaches a label in the dock, so any value - # type-checks the same; CMake stamps the real moq-c version. - status=0 - for source in src/*.cpp test/*.cpp; do - # shellcheck disable=SC2086 - # -Wno-unused-command-line-argument: the nix compiler wrapper injects - # link flags, which a syntax-only run reports as unused, once per file. - # $qt and $ffmpeg stay unquoted on purpose: pkg-config hands back one - # space-separated string, and splitting it is the intended reading. - if ! "$cxx" -std=c++17 -fsyntax-only -Wno-unused-command-line-argument \ - "${includes[@]}" $qt $ffmpeg \ - -DMOQ_FRONTEND_ENABLED -DMOQ_VERSION_STRING='"0.0.0"' "$source"; then - status=1 - fi - done - exit $status + ../../sh/obs/compile.sh # Compile and link the plugin the way CI does, against the `.#obs` shell's own # libobs/Qt6/ffmpeg, then run the unit tests. Linux-only in practice: it's the -# one platform where nixpkgs has obs-studio, so nothing has to be downloaded. -# Manual elsewhere. -# -# The tests run here without ThreadSanitizer because this is the only recipe CI -# invokes (.github/workflows/obs.yml). `just obs test` is manual, so on its own -# it can't make a build red; the sanitizer finds more, but only what runs in CI -# gates a merge. -# -# CMAKE_BUILD_TYPE overrides the preset's RelWithDebInfo because the Rust cache -# CI restores holds dev-profile artifacts. A release build of moq-c would -# rebuild its whole dependency tree on every run, and the gate is about whether -# the plugin compiles, which the profile doesn't change. +# one platform where nixpkgs has obs-studio. The Debug build type reuses the +# dev-profile Rust artifacts CI restores, where a release moq-c would rebuild +# its whole dependency tree. ci preset="": - #!/usr/bin/env bash - set -euo pipefail - PRESET=$(just preset "{{ preset }}" ci) - cmake --preset "$PRESET" -DCMAKE_BUILD_TYPE=Debug - cmake --build --preset "$PRESET" - just _unit - -# Print the -I flags for libobs and moq-c, shared by `compile` and `_unit`. -# -# moq.h is generated by cbindgen from rs/moq-c/src, so regenerate rather than -# just locating it: a stale header is how a plugin call to a since-changed -# moq-c function type-checks anyway. -[private] -_includes: - #!/usr/bin/env bash - set -euo pipefail - # The dev shell's pinned headers first, so every platform checks against the - # same libobs. Then the obs-deps framework (macOS/Windows), the OBS sources - # CMake unpacks beside it, and a system install (Linux without nix). - obs_include="" - for candidate in \ - "${OBS_INCLUDE_DIR:-}" \ - .deps/Frameworks/libobs.framework/Versions/A/Headers \ - .deps/obs-studio-*/libobs; do - if [ -n "$candidate" ] && [ -f "$candidate/obs.h" ]; then - obs_include="$candidate" - break - fi - done - if [ -z "$obs_include" ] && command -v pkg-config >/dev/null && pkg-config --exists libobs; then - obs_include=$(pkg-config --variable=includedir libobs)/obs - fi - if [ -z "$obs_include" ]; then - echo "libobs headers not found; run inside 'nix develop' (or set OBS_INCLUDE_DIR)" >&2 - exit 1 - fi - - # obs.h reaches as of OBS 32, which used to be vendored - # under libobs/util/ and so came along with the headers above. The dev shell - # carries it (see flake.nix); the obs-deps bundle ships its own copy beside - # libobs, which is how the macOS and Windows builds get it. - simde_include="" - if command -v pkg-config >/dev/null && pkg-config --exists simde; then - simde_include=$(pkg-config --variable=includedir simde) - else - for candidate in .deps/obs-deps-*/include; do - if [ -f "$candidate/simde/x86/sse2.h" ]; then - simde_include="$candidate" - break - fi - done - fi - if [ -z "$simde_include" ]; then - echo "simde headers not found; run inside 'nix develop', which supplies them" >&2 - exit 1 - fi - - (cd ../.. && cargo check --locked --quiet -p moq-c) - - # rs/moq-c/build.rs writes the header into its OUT_DIR, so ask cargo where - # that is. Replays the check above from cache, so it costs a process rather - # than a compile. - out_dir=$(cd ../.. && cargo check --locked -p moq-c --message-format=json | - jq -r 'select(.reason == "build-script-executed") | select(.package_id | tostring | test("/moq-c#")) | .out_dir' | - tail -1) - if [ -z "$out_dir" ]; then - echo "cargo reported no build script output for moq-c" >&2 - exit 1 - fi - moq_include="$out_dir/include" - if [ ! -f "$moq_include/moq.h" ]; then - echo "$moq_include/moq.h missing after 'cargo check --locked -p moq-c'" >&2 - exit 1 - fi - - # One flag per line, path glued to the -I, so a caller can rebuild the - # arguments without splitting on the spaces in a path. - printf -- '-I%s\n' src "$obs_include" "$simde_include" "$moq_include" + cmake --preset "$(../../sh/obs/preset.sh '{{ preset }}' ci)" -DCMAKE_BUILD_TYPE=Debug + cmake --build --preset "$(../../sh/obs/preset.sh '{{ preset }}' ci)" + ../../sh/obs/unit.sh # Unit-test the plugin sources against stubbed libobs/moq-c/ffmpeg, under -# ThreadSanitizer. -# -# Manual because ThreadSanitizer needs its own build. `just obs ci` runs the -# same tests without it, so a regression these assertions catch still turns PR -# CI red; the sanitizer is what -# adds the races on top. Run this whenever you touch src/, especially the session -# callback plumbing, whose orderings the build can't check. +# ThreadSanitizer. Manual; `just obs ci` runs them without the sanitizer. test: - #!/usr/bin/env bash - set -euo pipefail - # Unlike the lint recipes, this one never skips: a test gate that reports - # success without running anything is worse than no gate. - cxx="${CXX:-c++}" - unsupported="'$cxx' cannot build and run -fsanitize=thread binaries. These tests need a - Clang or GCC whose ThreadSanitizer runtime works on this host: set CXX, or on Windows run - them from WSL, since neither MSVC nor Clang on Windows implements ThreadSanitizer. - They also run without the sanitizer as part of 'just obs ci'." - if ! command -v "$cxx" >/dev/null; then - echo "no C++ compiler at '$cxx'." >&2 - echo "$unsupported" >&2 - exit 1 - fi - - probe=$(mktemp -d) - trap 'rm -rf "$probe"' EXIT - - # Run the probe, don't just link it: a mismatch between the compiler's TSan - # runtime and the host kernel (macOS is where this shows up) links fine and - # then segfaults before main, which is an unreadable way for the real test - # to fail. - # The subshell keeps bash's own "Segmentation fault" job message out of the - # output, so the explanation below is all the reader gets. - if ! printf 'int main(){}\n' | "$cxx" -x c++ -fsanitize=thread -o "$probe/probe" - >/dev/null 2>&1 \ - || ! ("$probe/probe" >/dev/null 2>&1) 2>/dev/null; then - echo "$unsupported" >&2 - exit 1 - fi - - just _unit tsan + ../../sh/obs/test.sh -# Compile and run the unit tests, plain or under ThreadSanitizer. Shared by -# `test` and `ci` so both run the same assertions. -[private] -_unit mode="plain": - #!/usr/bin/env bash - set -euo pipefail - cxx="${CXX:-c++}" - if ! command -v "$cxx" >/dev/null; then - echo "no C++ compiler at '$cxx'" >&2 - exit 1 - fi - # moq-source.cpp decodes with ffmpeg, so its test needs the headers even - # though it stubs every function out of them. - if ! pkg-config --exists libavcodec libavutil libswscale; then - echo "missing ffmpeg headers" >&2 - echo "run inside 'nix develop', which supplies ffmpeg on every platform" >&2 - exit 1 - fi - - includes_raw=$(just _includes) - includes=() - while IFS= read -r flag; do includes+=("$flag"); done <<< "$includes_raw" - - ffmpeg=$(pkg-config --cflags libavcodec libavutil libswscale) - - flags=(-std=c++17 -g -O0 -pthread) - if [ "{{ mode }}" = "tsan" ]; then - flags+=(-fsanitize=thread) - fi - - out=$(mktemp -d) - trap 'rm -rf "$out"' EXIT - - # One binary per source under test: each test file defines its own libobs and - # moq-c stubs, so two of them can't share a link. Header-only helpers - # (quality defaults) build as a third binary with no plugin source. - for name in moq-output moq-source; do - # shellcheck disable=SC2086 - # $ffmpeg stays unquoted on purpose: pkg-config hands back one - # space-separated string, and splitting it is the intended reading. - "$cxx" "${flags[@]}" "${includes[@]}" $ffmpeg \ - -o "$out/$name-test" "test/$name-test.cpp" "src/$name.cpp" - TSAN_OPTIONS="halt_on_error=1" "$out/$name-test" - done - for name in moq-quality-defaults moq-dock-stop moq-error moq-encoder-latency moq-dial moq-spark; do - "$cxx" "${flags[@]}" "${includes[@]}" \ - -o "$out/$name-test" "test/$name-test.cpp" - TSAN_OPTIONS="halt_on_error=1" "$out/$name-test" - done - -# Lint formatting. Skips a tool silently if it isn't on $PATH (matches repo convention). +# Lint formatting and the OBS version pins. check: - #!/usr/bin/env bash - set -euo pipefail - if grep -Fq '"MOQ_VERSION"' CMakePresets.json; then - echo "CMakePresets.json must not pin MOQ_VERSION" >&2 - exit 1 - fi - # The headers `just obs compile` type-checks against are a second copy of - # the OBS version this spec downloads, so a bump here has to reach flake.nix - # or the two gates check different libobs. - spec_obs=$(jq -r '.dependencies["obs-studio"].version // ""' buildspec.json) - flake_obs=$(sed -n '/pname = "libobs-headers"/,/}/p' ../../flake.nix | sed -n 's/.*version = "\([^"]*\)".*/\1/p') - # Both are pattern matches against files this recipe doesn't own the shape - # of. An empty parse compares equal to an empty parse, so the guard would - # pass by reporting nothing rather than by finding the versions in sync. - if [ -z "$spec_obs" ] || [ -z "$flake_obs" ]; then - echo "couldn't read the obs-studio version: '$spec_obs' from buildspec.json, '$flake_obs' from flake.nix" >&2 - exit 1 - fi - if [ "$spec_obs" != "$flake_obs" ]; then - echo "obs-studio is $spec_obs in buildspec.json but $flake_obs in flake.nix (libobs-headers)" >&2 - exit 1 - fi - # And a third: `just obs ci` links against nixpkgs' obs-studio, the one OBS - # this repo doesn't pick. Without this the released macOS/Windows binaries - # could be a whole libobs API apart from what CI ever compiles. Patch - # releases carry no API change, so only the major.minor has to agree; that - # also keeps the guard quiet until flake.lock actually moves OBS, which is - # the change that opens the gap and so the one that should fail. - # OBS_LINKED_VERSION comes from the dev shell (see flake.nix), so this leg - # is skipped outside it, where there is no nixpkgs obs-studio to compare. - # MOQ_STRICT turns that skip into an error for the same reason it turns a - # missing tool into one: in CI a leg that checks nothing still reports green. - if [ -z "${OBS_LINKED_VERSION:-}" ]; then - if [ -n "${MOQ_STRICT:-}" ]; then - echo "MOQ_STRICT is set but OBS_LINKED_VERSION is unset; run inside 'nix develop', which exports it" >&2 - exit 1 - fi - else - spec_api=$(echo "$spec_obs" | cut -d. -f1,2) - linked_api=$(echo "$OBS_LINKED_VERSION" | cut -d. -f1,2) - if [ "$spec_api" != "$linked_api" ]; then - echo "obs-studio is $spec_obs in buildspec.json but $OBS_LINKED_VERSION in nixpkgs, which is what 'just obs ci' links" >&2 - echo "bump buildspec.json and flake.nix's libobs-headers to $OBS_LINKED_VERSION, or pin nixpkgs back" >&2 - exit 1 - fi - fi - if command -v cmake >/dev/null; then - build_dir=$(mktemp -d) - trap 'rm -rf "$build_dir"' EXIT - if cmake -S . -B "$build_dir" -DMOQ_LOCAL= >"$build_dir/configure.log" 2>&1; then - echo "CMake accepted a release build without MOQ_VERSION" >&2 - exit 1 - fi - if ! grep -Fq "MOQ_VERSION is required when MOQ_LOCAL does not contain rs/moq-c" "$build_dir/configure.log"; then - cat "$build_dir/configure.log" >&2 - exit 1 - fi - fi - if command -v clang-format >/dev/null; then - git ls-files 'src/*.cpp' 'src/*.h' 'test/*.cpp' | xargs clang-format --dry-run --Werror - fi - if command -v gersemi >/dev/null; then - gersemi --check CMakeLists.txt cmake - fi + ../../sh/obs/check.sh # Auto-fix formatting. fix: - #!/usr/bin/env bash - set -euo pipefail - if command -v clang-format >/dev/null; then - git ls-files 'src/*.cpp' 'src/*.h' 'test/*.cpp' | xargs clang-format -i - fi - if command -v gersemi >/dev/null; then - gersemi --in-place CMakeLists.txt cmake - fi + ../../sh/obs/fix.sh + +# Runs in the caller's directory, so a relative `--output` means what it would +# to the script itself. -# Detect the CMake preset for the current platform (or use the override). -# Pass `ci` as the second argument for the warnings-as-errors variant, whose -# name upstream spells differently on each platform. -preset override="" variant="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "{{ override }}" ]]; then - echo "{{ override }}" - elif [[ "$OSTYPE" == "darwin"* ]]; then - [[ "{{ variant }}" == "ci" ]] && echo "macos-ci" || echo "macos" - elif [[ "$OSTYPE" == "linux-gnu"* ]]; then - [[ "{{ variant }}" == "ci" ]] && echo "ubuntu-ci-x86_64" || echo "ubuntu-x86_64" - elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then - [[ "{{ variant }}" == "ci" ]] && echo "windows-ci-x64" || echo "windows-x64" - else - echo "Unknown platform: $OSTYPE" >&2 - exit 1 - fi +# Build and package the obs-moq plugin for release. +[no-cd] +[positional-arguments] +package *args: + {{ quote(justfile_directory() / "cpp/obs/build.sh") }} "$@" diff --git a/dart/README.md b/dart/README.md index 466876666c1..8feee4745f7 100644 --- a/dart/README.md +++ b/dart/README.md @@ -20,13 +20,14 @@ WebAssembly. Browser applications should use the TypeScript packages. ## Generator Bindings use [`kixelated/uniffi-dart`](https://github.com/kixelated/uniffi-dart) -tag `v0.3.0+v0.32.0`, which carries the UniFFI 0.32 and library-mode CLI -changes. The Nix development shell supplies that exact revision. Without Nix, -install it with: +tag `v0.3.1-kixelated.5+v0.32.0`, which carries the UniFFI 0.32 and +library-mode CLI changes. The Nix development shell supplies that exact +revision plus `nix/uniffi-dart-record-error.patch`. Without Nix, install it +with: ```bash cargo install --git https://github.com/kixelated/uniffi-dart \ - --tag 'v0.3.0+v0.32.0' --features binary uniffi-dart + --tag 'v0.3.1-kixelated.5+v0.32.0' --features binary uniffi-dart ``` ## Releases diff --git a/dart/justfile b/dart/justfile index 9823e8cf324..5c2fc803ffc 100644 --- a/dart/justfile +++ b/dart/justfile @@ -1,18 +1,22 @@ #!/usr/bin/env just --justfile # Check the generated bindings and both Dart packages. -check $FILES="": - ./scripts/check.sh "{{ FILES }}" +check: + ../sh/dart/check.sh # Format Dart sources. -fix $FILES="": - ./scripts/check.sh --fix "{{ FILES }}" +fix: + ../sh/dart/check.sh --fix # Regenerate the raw UniFFI Dart bindings. generate: - ./scripts/generate.sh + ../sh/dart/generate.sh -# Remove Dart tool state and build output. -clean: - rm -rf moq/.dart_tool moq_ffi/.dart_tool - rm -rf moq/build moq_ffi/build +# `package` runs in the caller's directory, so a relative `--output` means +# what it would to the script itself. + +# Package a Dart library for pub.dev. +[no-cd] +[positional-arguments] +package *args: + {{ quote(justfile_directory() / "sh/dart/package.sh") }} "$@" diff --git a/dart/moq_ffi/hook/build.dart b/dart/moq_ffi/hook/build.dart index 6916ea46a70..bfb465d6036 100644 --- a/dart/moq_ffi/hook/build.dart +++ b/dart/moq_ffi/hook/build.dart @@ -7,7 +7,7 @@ import 'package:http/http.dart' as http; /// The moq-ffi release whose native assets this package downloads. /// -/// dart/scripts/package.sh rewrites this when staging a release. The sentinel +/// sh/dart/package.sh rewrites this when staging a release. The sentinel /// is never used to download: a checkout builds from source instead, and a /// package built without the injection fails loudly rather than fetching a /// library that does not match these bindings. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 2687c80ae62..3e5e353de93 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -1846,7 +1846,7 @@ class MoqTrackInfo { final int? maxAgeUs; final int? timescale; MoqTrackInfo({ - this.priority = 0, + this.priority = 127, this.maxAgeUs = null, this.timescale = null, }); @@ -2180,6 +2180,16 @@ abstract class MoqException implements Exception { RustBuffer lower(); int allocationSize(); int write(Uint8List buf); + @override + String toString() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqerror_uniffi_trait_display( + FfiConverterMoqException.lower(this), + status, + ), + FfiConverterString.lift, + ); + } } class FfiConverterMoqException { @@ -2416,11 +2426,6 @@ class ProtocolMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "ProtocolMoqException($details)"; - } } class TransportMoqException extends MoqException { @@ -2459,11 +2464,6 @@ class TransportMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "TransportMoqException($v0)"; - } } class InternalMoqException extends MoqException { @@ -2502,11 +2502,6 @@ class InternalMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "InternalMoqException($v0)"; - } } class MediaMoqException extends MoqException { @@ -2545,11 +2540,6 @@ class MediaMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "MediaMoqException($v0)"; - } } class MuxMoqException extends MoqException { @@ -2588,11 +2578,6 @@ class MuxMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "MuxMoqException($v0)"; - } } class JsonTrackMoqException extends MoqException { @@ -2631,11 +2616,6 @@ class JsonTrackMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "JsonTrackMoqException($v0)"; - } } class UrlMoqException extends MoqException { @@ -2674,11 +2654,6 @@ class UrlMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "UrlMoqException($v0)"; - } } class TimeOverflowMoqException extends MoqException { @@ -2707,11 +2682,6 @@ class TimeOverflowMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "TimeOverflowMoqException"; - } } class LogLevelMoqException extends MoqException { @@ -2750,11 +2720,6 @@ class LogLevelMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "LogLevelMoqException($v0)"; - } } class TaskMoqException extends MoqException { @@ -2793,11 +2758,6 @@ class TaskMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "TaskMoqException($v0)"; - } } class JsonMoqException extends MoqException { @@ -2836,11 +2796,6 @@ class JsonMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "JsonMoqException($v0)"; - } } class CancelledMoqException extends MoqException { @@ -2869,11 +2824,6 @@ class CancelledMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "CancelledMoqException"; - } } class ClosedMoqException extends MoqException { @@ -2902,11 +2852,6 @@ class ClosedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "ClosedMoqException"; - } } class BusyMoqException extends MoqException { @@ -2935,11 +2880,6 @@ class BusyMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "BusyMoqException"; - } } class ConnectMoqException extends MoqException { @@ -2978,11 +2918,6 @@ class ConnectMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "ConnectMoqException($v0)"; - } } class BindMoqException extends MoqException { @@ -3021,11 +2956,6 @@ class BindMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "BindMoqException($v0)"; - } } class RejectMoqException extends MoqException { @@ -3064,11 +2994,6 @@ class RejectMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "RejectMoqException($v0)"; - } } class AlreadyRespondedMoqException extends MoqException { @@ -3097,11 +3022,6 @@ class AlreadyRespondedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "AlreadyRespondedMoqException"; - } } class CodecMoqException extends MoqException { @@ -3140,11 +3060,6 @@ class CodecMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "CodecMoqException($v0)"; - } } class UnauthorizedMoqException extends MoqException { @@ -3173,11 +3088,6 @@ class UnauthorizedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "UnauthorizedMoqException"; - } } class ForbiddenMoqException extends MoqException { @@ -3206,11 +3116,6 @@ class ForbiddenMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "ForbiddenMoqException"; - } } class NotFoundMoqException extends MoqException { @@ -3239,11 +3144,6 @@ class NotFoundMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "NotFoundMoqException"; - } } class UnsupportedMoqException extends MoqException { @@ -3272,11 +3172,6 @@ class UnsupportedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "UnsupportedMoqException"; - } } class AlreadyCommittedMoqException extends MoqException { @@ -3305,11 +3200,6 @@ class AlreadyCommittedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "AlreadyCommittedMoqException"; - } } class InvalidRouteMoqException extends MoqException { @@ -3348,11 +3238,6 @@ class InvalidRouteMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "InvalidRouteMoqException($v0)"; - } } class InvalidPatternMoqException extends MoqException { @@ -3391,11 +3276,6 @@ class InvalidPatternMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "InvalidPatternMoqException($v0)"; - } } class UnresolvableBroadcastMoqException extends MoqException { @@ -3434,11 +3314,6 @@ class UnresolvableBroadcastMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "UnresolvableBroadcastMoqException($v0)"; - } } class LogMoqException extends MoqException { @@ -3477,11 +3352,6 @@ class LogMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "LogMoqException($v0)"; - } } class MoqExceptionErrorHandler extends UniffiRustCallStatusErrorHandler { @@ -11771,6 +11641,14 @@ external Pointer uniffi_moq_ffi_fn_method_moqsession_status( Pointer ptr, ); +@Native)>( + assetId: _uniffiAssetId, +) +external RustBuffer uniffi_moq_ffi_fn_method_moqerror_uniffi_trait_display( + RustBuffer ptr, + Pointer uniffiStatus, +); + @Native)>( assetId: _uniffiAssetId, ) @@ -12767,7 +12645,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackconsumer_recv_datagram() != - 29049) { + 17412) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackconsumer_recv_group() != 60887) { diff --git a/dart/moq_ffi/pubspec.yaml b/dart/moq_ffi/pubspec.yaml index cf7a8ecadc2..0f53a4f24cb 100644 --- a/dart/moq_ffi/pubspec.yaml +++ b/dart/moq_ffi/pubspec.yaml @@ -1,6 +1,6 @@ name: moq_ffi description: Raw Dart and Flutter bindings for Media over QUIC. -# Overridden by dart/scripts/package.sh from the moq-ffi-v* tag. Committing a +# Overridden by sh/dart/package.sh from the moq-ffi-v* tag. Committing a # real version would go stale the moment release-plz bumps the crate. version: 0.0.0-dev repository: https://github.com/moq-dev/moq/tree/main/dart/moq_ffi diff --git a/dart/moq_ffi/test/smoke_test.dart b/dart/moq_ffi/test/smoke_test.dart index 0782864a596..6265d206fd6 100644 --- a/dart/moq_ffi/test/smoke_test.dart +++ b/dart/moq_ffi/test/smoke_test.dart @@ -28,6 +28,11 @@ void main() { ); }); + test('an exception prints the Rust error message', () { + expect(ClosedMoqException().toString(), 'closed'); + expect(TransportMoqException('reset').toString(), 'transport: reset'); + }); + test('raw track round trips a frame', () async { final broadcast = MoqBroadcastProducer(); final track = broadcast.publishTrack(name: 'events', info: null); diff --git a/demo/boy/justfile b/demo/boy/justfile index 9312d15bd55..5837865a5e9 100644 --- a/demo/boy/justfile +++ b/demo/boy/justfile @@ -11,13 +11,9 @@ default: "just wait && just web" # Download the given ROM from our R2 bucket. +[positional-arguments] download rom: - #!/usr/bin/env bash - if [ ! -f "rom/{{ rom }}" ]; then - mkdir -p rom - curl -fSL -o "rom/{{ rom }}.tmp" "https://rom.moq.dev/{{ rom }}" - mv "rom/{{ rom }}.tmp" "rom/{{ rom }}" - fi + @../../sh/demo/download.sh "https://rom.moq.dev/$1" "rom/$1" # Big2Small (puzzle): https://mdsteele.itch.io/big2small b2s: @@ -70,15 +66,9 @@ upload file: bun wrangler r2 object put "rom-moq-dev/{{ file }}" --file "rom/{{ file }}" --remote # Sync all ROMs to R2 +[positional-arguments] sync dir="rom": - #!/usr/bin/env bash - set -euo pipefail - for file in "{{ dir }}"/*; do - [ -e "$file" ] || continue - key=$(basename "$file") - echo "Uploading $key..." - bun wrangler r2 object put "rom-moq-dev/$key" --file "$file" --remote - done + ../../sh/demo/sync.sh rom-moq-dev "$@" # List files in the R2 bucket list: diff --git a/demo/justfile b/demo/justfile index bfd725f82d1..08b359d9ffa 100644 --- a/demo/justfile +++ b/demo/justfile @@ -1,65 +1,18 @@ set fallback -mod boy -mod pub -mod relay -mod sub -mod web - # Run the web demo (default). # -# Picks the first free port at/after 4443 (both UDP for QUIC and TCP for HTTP) -# so multiple worktrees can run `just dev` without colliding. The relay reads - -# the port from MOQ_LISTEN/MOQ_WEB_HTTP_LISTEN, overriding localhost.toml. +# Picks the first free port at/after 4443 so multiple worktrees can run +# `just dev` without colliding; see sh/demo/run.sh. default: - #!/usr/bin/env bash - set -euo pipefail bun install - - port=$(just port) - if [ "$port" != "4443" ]; then - echo ">>> Port 4443 is busy, using $port instead" >&2 - fi - - base="http://localhost:$port" - - # Scope the bind env vars to the relay only. The unified `moq` binary also - # reads MOQ_LISTEN, so exporting it globally would make the `pub` client - # try to start a server (and fail without a TLS cert). - bun run concurrently --kill-others --names rly,bbb,web --prefix-colors auto \ - "MOQ_LISTEN='[::]:$port' MOQ_WEB_HTTP_LISTEN='[::]:$port' just relay" \ - "just wait $base/certificate.sha256 && just pub bbb $base" \ - "just wait $base/certificate.sha256 && just web serve $base" - -# Find the first free port at/after `start` (checked on both TCP and UDP). -# `lsof` isn't available everywhere (e.g. Git Bash on Windows); without it we -# can't probe, so fall back to `start` and let the relay surface a bind error if - -# it's actually taken. -[private] -port start="4443": - #!/usr/bin/env bash - set -euo pipefail - port={{ start }} - if command -v lsof >/dev/null 2>&1; then - while lsof -nP -iTCP:"$port" -sTCP:LISTEN -t >/dev/null 2>&1 \ - || lsof -nP -iUDP:"$port" -t >/dev/null 2>&1; do - port=$((port + 1)) - done - fi - echo "$port" + ../sh/demo/run.sh # Wait for the localhost relay to be ready by repeatedly requesting the cert +[positional-arguments] [private] wait url="http://localhost:4443/certificate.sha256": - #!/usr/bin/env bash - set -euo pipefail - for i in $(seq 1 600); do - curl -sf "{{ url }}" > /dev/null 2>&1 && exit 0 - sleep 1 - done - exit 1 + ../sh/demo/wait.sh "$@" # Throttle UDP traffic for testing (macOS only, requires sudo). throttle: diff --git a/demo/pub/justfile b/demo/pub/justfile index fb780f5e73e..f50d1d5447f 100644 --- a/demo/pub/justfile +++ b/demo/pub/justfile @@ -1,4 +1,5 @@ set fallback +set shell := ["bash", "-euo", "pipefail", "-c"] # --- R2 bucket management (vid.moq.dev) --- @@ -18,15 +19,9 @@ upload file: bun wrangler r2 object put "video-moq-dev/{{ file }}" --file "media/{{ file }}" --remote # Sync all files in a local directory to R2 +[positional-arguments] sync dir="media": - #!/usr/bin/env bash - set -euo pipefail - for file in "{{ dir }}"/*; do - [ -e "$file" ] || continue - key=$(basename "$file") - echo "Uploading $key..." - bun wrangler r2 object put "video-moq-dev/$key" --file "$file" --remote - done + ../../sh/demo/sync.sh video-moq-dev "$@" # List files in the bucket list: @@ -36,6 +31,7 @@ list: # --- Publishing --- # Publish Big Buck Bunny to a relay server. +[positional-arguments] bbb url='http://localhost:4443' *args: just download bbb just download bbb-sd @@ -43,8 +39,8 @@ bbb url='http://localhost:4443' *args: ffmpeg -hide_banner -loglevel warning -copyts \ -stream_loop -1 -re -i media/bbb.mp4 \ -stream_loop -1 -re -i media/bbb-sd.mp4 \ - -map 0 -map 1:v -c copy -f mpegts -pes_payload_size 0 - \ - | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast bbb.hang import ts + -map 0 -map 1:v -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - \ + | cargo run --bin moq -- "${@:2}" --connect "{{ url }}" --broadcast bbb.hang import ts # Encode the video-only SD rendition, preserving source timestamps and loop duration. encode-bbb-sd: @@ -58,19 +54,22 @@ check-bbb: python3 bbb.py check # Publish Tears of Steel to a relay server. +[positional-arguments] tos url='http://localhost:4443' *args: just download tos - just ts tos "{{ url }}" {{ args }} + just ts tos "$@" # Publish a video using ffmpeg (CMAF / fMP4) to a relay server. +[positional-arguments] cmaf name url='http://localhost:4443' *args: cargo build --bin moq - just ffmpeg-cmaf "media/{{ name }}.mp4" | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast "{{ name }}.hang" import fmp4 + just ffmpeg-cmaf "media/{{ name }}.mp4" | cargo run --bin moq -- "${@:3}" --connect "{{ url }}" --broadcast "{{ name }}.hang" import fmp4 # Publish a video using ffmpeg (MPEG-TS) to a relay server. +[positional-arguments] ts name url='http://localhost:4443' *args: cargo build --bin moq - just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast "{{ name }}.hang" import ts + just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- "${@:3}" --connect "{{ url }}" --broadcast "{{ name }}.hang" import ts # Publish a video via iroh. iroh name url prefix="": @@ -79,82 +78,13 @@ iroh name url prefix="": just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- --iroh-enabled --connect "{{ url }}" --broadcast "{{ prefix }}{{ name }}.hang" import ts # Generate and ingest an HLS stream from a video file. +[positional-arguments] hls name relay="http://localhost:4443": - #!/usr/bin/env bash - set -euo pipefail - - just download "{{ name }}" - - INPUT="media/{{ name }}.mp4" - OUT_DIR="media/{{ name }}" - - rm -rf "$OUT_DIR" - mkdir -p "$OUT_DIR" - - echo ">>> Generating HLS stream to disk (1280x720 + 256x144)..." - - ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "$INPUT" \ - -filter_complex "\ - [0:v]split=2[v0][v1]; \ - [v0]scale=-2:720[v720]; \ - [v1]scale=-2:144[v144]" \ - -map "[v720]" -map "[v144]" -map 0:a:0 \ - -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ - -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 \ - -b:v:0 4M -maxrate:v:0 4.4M -bufsize:v:0 8M \ - -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 \ - -b:v:1 300k -maxrate:v:1 330k -bufsize:v:1 600k \ - -c:a aac -b:a 128k \ - -f hls -hls_time 2 -hls_list_size 6 \ - -hls_flags independent_segments+delete_segments \ - -hls_segment_type fmp4 \ - -master_pl_name master.m3u8 \ - -var_stream_map "v:0,agroup:audio,name:720 v:1,agroup:audio,name:144 a:0,agroup:audio,name:audio" \ - -hls_segment_filename "$OUT_DIR/v%v/segment_%09d.m4s" \ - "$OUT_DIR/v%v/stream.m3u8" & - - FFMPEG_PID=$! - - echo ">>> Waiting for HLS playlist generation..." - for i in {1..30}; do - if [ -f "$OUT_DIR/master.m3u8" ]; then break; fi - sleep 0.5 - done - - if [ ! -f "$OUT_DIR/master.m3u8" ]; then - kill $FFMPEG_PID 2>/dev/null || true - echo "Error: master.m3u8 not generated in time" - exit 1 - fi - - echo ">>> Waiting for variant playlists..." - sleep 2 - for i in {1..20}; do - if [ -f "$OUT_DIR/v0/stream.m3u8" ] || [ -f "$OUT_DIR/v720/stream.m3u8" ] || [ -f "$OUT_DIR/v144/stream.m3u8" ] || [ -f "$OUT_DIR/vaudio/stream.m3u8" ]; then - break - fi - sleep 0.5 - done - - CLEANUP_CALLED=false - cleanup() { - if [ "$CLEANUP_CALLED" = "true" ]; then return; fi - CLEANUP_CALLED=true - echo "Shutting down..." - kill $FFMPEG_PID 2>/dev/null || true - sleep 0.5 - kill -9 $FFMPEG_PID 2>/dev/null || true - } - trap cleanup SIGINT SIGTERM EXIT - - echo ">>> Importing HLS via moq-cli" - cargo run --bin moq -- --connect "{{ relay }}" --broadcast "{{ name }}.hang" import hls "$OUT_DIR/master.m3u8" - EXIT_CODE=$? - - cleanup - exit $EXIT_CODE + just download "$1" + ../../sh/demo/hls.sh "$@" # Publish a video using H.264 Annex B format. +[positional-arguments] h264 name url="http://localhost:4443" *args: just download "{{ name }}" cargo build --bin moq @@ -165,68 +95,31 @@ h264 name url="http://localhost:4443" *args: -c:v copy -an \ -bsf:v h264_mp4toannexb \ -f h264 \ - - | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast "{{ name }}.hang" import avc3 + - | cargo run --bin moq -- "${@:3}" --connect "{{ url }}" --broadcast "{{ name }}.hang" import avc3 # Publish a video using ffmpeg directly from moq to the localhost. +[positional-arguments] serve name *args: just download "{{ name }}" cargo build --bin moq - just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- {{ args }} --listen "[::]:4443" --listen-tls-generate "localhost" --auth-public "**" --broadcast "{{ name }}.hang" import ts + just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- "${@:2}" --listen "[::]:4443" --listen-tls-generate "localhost" --auth-public "**" --broadcast "{{ name }}.hang" import ts # Generate and serve an HLS stream from a video for testing. +[positional-arguments] serve-hls name port="8000": - #!/usr/bin/env bash - set -euo pipefail - - just download "{{ name }}" - - INPUT="media/{{ name }}.mp4" - OUT_DIR="media/{{ name }}" - - rm -rf "$OUT_DIR" - mkdir -p "$OUT_DIR" - - echo ">>> Starting HLS stream generation..." - echo ">>> Master playlist: http://localhost:{{ port }}/master.m3u8" - - cleanup() { - echo "Shutting down..." - kill $(jobs -p) 2>/dev/null || true - exit 0 - } - trap cleanup SIGINT SIGTERM - - ffmpeg -loglevel warning -re -stream_loop -1 -i "$INPUT" \ - -map 0:v:0 -map 0:v:0 -map 0:a:0 \ - -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ - -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 -bsf:v:0 dump_extra -b:v:0 4M -vf:0 "scale=1920:-2" \ - -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 -bsf:v:1 dump_extra -b:v:1 300k -vf:1 "scale=256:-2" \ - -c:a aac -b:a 128k \ - -f hls \ - -hls_time 2 -hls_list_size 12 \ - -hls_flags independent_segments+delete_segments \ - -hls_segment_type fmp4 \ - -master_pl_name master.m3u8 \ - -var_stream_map "v:0,agroup:audio v:1,agroup:audio a:0,agroup:audio" \ - -hls_segment_filename "$OUT_DIR/v%v/segment_%09d.m4s" \ - "$OUT_DIR/v%v/stream.m3u8" & - - sleep 2 - echo ">>> HTTP server: http://localhost:{{ port }}/" - cd "$OUT_DIR" && python3 -m http.server {{ port }} + just download "$1" + ../../sh/demo/serve-hls.sh "$@" # Publish the clock broadcast. +[arg("action", pattern="publish|subscribe")] +[positional-arguments] clock action url="http://localhost:4443" *args: - @if [ "{{ action }}" != "publish" ] && [ "{{ action }}" != "subscribe" ]; then \ - echo "Error: action must be 'publish' or 'subscribe', got '{{ action }}'" >&2; \ - exit 1; \ - fi - - cargo run -p moq-tokio --example clock -- --connect "{{ url }}" --broadcast "clock" {{ args }} {{ action }} + cargo run -p moq-tokio --example clock -- --connect "{{ url }}" --broadcast "clock" "${@:3}" "{{ action }}" # --- GStreamer --- # Publish a video using GStreamer to a relay server. +[positional-arguments] gst name url='http://localhost:4443' *args: just download "{{ name }}" cargo build -p moq-gst @@ -235,34 +128,36 @@ gst name url='http://localhost:4443' *args: gst-launch-1.0 -v -e multifilesrc location="media/{{ name }}.mp4" loop=true ! parsebin name=parse \ parse. ! queue ! identity sync=true ! mux.sink_0 \ parse. ! queue ! identity sync=true ! mux.sink_1 \ - moqsink name=mux url="{{ url }}" broadcast="{{ name }}.hang" {{ args }} + moqsink name=mux url="{{ url }}" broadcast="{{ name }}.hang" "${@:3}" # --- Private helpers --- # Download a test video (already fragmented on vid.moq.dev). +[positional-arguments] [private] download name: - @if [ ! -f "media/{{ name }}.mp4" ]; then \ - mkdir -p media; \ - curl -fsSL "https://vid.moq.dev/{{ name }}.mp4" -o "media/{{ name }}.mp4"; \ - fi + @../../sh/demo/download.sh "https://vid.moq.dev/$1.mp4" "media/$1.mp4" # Convert an h264 input file to CMAF (fmp4) format to stdout, with one fragment per sample. # -frag_duration rather than frag_every_frame: the latter repeats a fragment's tfdt when it # interleaves audio and video, landing two samples on one timestamp. +[positional-arguments] [private] ffmpeg-cmaf input output='-' *args: ffmpeg -hide_banner -v quiet \ -stream_loop -1 -re \ -i "{{ input }}" \ -c copy \ - -f mp4 -movflags cmaf+separate_moof+delay_moov+skip_trailer -frag_duration 1000 {{ args }} {{ output }} + -f mp4 -movflags cmaf+separate_moof+delay_moov+skip_trailer -frag_duration 1000 "${@:3}" "{{ output }}" # Convert an h264 input file to MPEG-TS format to stdout, with one PES per audio frame. +# -pes_payload_size 0 alone still queues audio frames under 170 bytes (silence) for up to +# 0.35 s; -muxdelay 0 writes each one as soon as the next arrives. +[positional-arguments] [private] ffmpeg-ts input output='-' *args: ffmpeg -hide_banner -v quiet \ -stream_loop -1 -re \ -i "{{ input }}" \ -c copy \ - -f mpegts -pes_payload_size 0 {{ args }} {{ output }} + -f mpegts -pes_payload_size 0 -muxdelay 0 "${@:3}" "{{ output }}" diff --git a/demo/relay/justfile b/demo/relay/justfile index c0e33a31971..db04682e600 100644 --- a/demo/relay/justfile +++ b/demo/relay/justfile @@ -34,60 +34,17 @@ leaf1: (cert "leaf1") # Generate a self-signed CA ca: - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - [ -f ca.pem ] && [ -f ca.key ] && exit 0 - rm -f ca.pem ca.key - printf '[req]\ndistinguished_name = req_dn\n[req_dn]\n' > ca.cnf - export OPENSSL_CONF="ca.cnf" - openssl req -x509 -sha256 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \ - -days 365 -subj "/CN=moq cluster CA" \ - -keyout ca.key -out ca.pem + ../../sh/demo/ca.sh # Generate a self-signed certificate using the root CA. - -# Chrome requires a <=14 day validity for self-signed certs. +[positional-arguments] cert name: ca - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - export OPENSSL_CONF="ca.cnf" - openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \ - -subj "/CN={{ name }}" \ - -keyout "{{ name }}.key" -out "{{ name }}.csr" - openssl x509 -req -sha256 -in "{{ name }}.csr" \ - -CA ca.pem -CAkey ca.key -CAcreateserial \ - -days 14 -extfile <(printf "subjectAltName=DNS:localhost\n") \ - -out "{{ name }}.crt" - rm "{{ name }}.csr" + ../../sh/demo/cert.sh "$@" # Generate a random secret key for authentication. key: - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - [ -f root.jwk ] && exit 0 - rm -f *.jwt - cargo run --bin moq -- auth generate --out root.jwk + ../../sh/demo/key.sh # Generate authentication tokens for local development. token: key - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - if [ ! -f demo-web.jwt ]; then - cargo run --quiet --bin moq -- auth sign --key root.jwk \ - --root demo --subscribe '**' --publish 'me/**' \ - > demo-web.jwt - fi - - if [ ! -f demo-cli.jwt ]; then - cargo run --quiet --bin moq -- auth sign --key root.jwk \ - --root demo --publish '**' \ - > demo-cli.jwt - fi + ../../sh/demo/token.sh diff --git a/demo/sub/justfile b/demo/sub/justfile index e7ec69ed855..824fd6674a2 100644 --- a/demo/sub/justfile +++ b/demo/sub/justfile @@ -1,6 +1,8 @@ set fallback +set shell := ["bash", "-euo", "pipefail", "-c"] # Subscribe to a broadcast using GStreamer and render to the screen. +[positional-arguments] gst name url='http://localhost:4443' *args: cargo build -p moq-gst @@ -8,6 +10,6 @@ gst name url='http://localhost:4443' *args: # by name so a bare `! decodebin3` can't latch onto the audio pad and leave the # video sink empty; route audio to its own sink so it doesn't stall the session. GST_PLUGIN_PATH_1_0="${PWD}/../../target/debug${GST_PLUGIN_PATH_1_0:+:$GST_PLUGIN_PATH_1_0}" \ - gst-launch-1.0 -v -e moqsrc name=s url="{{ url }}" broadcast="{{ name }}" {{ args }} \ + gst-launch-1.0 -v -e moqsrc name=s url="{{ url }}" broadcast="{{ name }}" "${@:3}" \ s.video_0 ! queue ! decodebin3 ! videoconvert ! autovideosink \ s.audio_0 ! queue ! decodebin3 ! audioconvert ! autoaudiosink diff --git a/doc/.vitepress/theme/Banner.vue b/doc/.vitepress/theme/Banner.vue index 8d85b53c0c4..73c5e6280d6 100644 --- a/doc/.vitepress/theme/Banner.vue +++ b/doc/.vitepress/theme/Banner.vue @@ -25,6 +25,13 @@ line-height: 1.4; } +@media (min-width: 960px) { + .moq-banner { + height: var(--moq-banner-height); + margin-top: var(--vp-nav-height); + } +} + .moq-banner p { margin: 0.15rem 0; color: var(--vp-c-text-2); diff --git a/doc/.vitepress/theme/custom.css b/doc/.vitepress/theme/custom.css index 80986a4c5ce..67020908878 100644 --- a/doc/.vitepress/theme/custom.css +++ b/doc/.vitepress/theme/custom.css @@ -1,4 +1,6 @@ :root { + --moq-banner-height: 2.55rem; + /* Brand colors - green accent matching moq.dev */ --vp-c-brand-1: #16a34a; --vp-c-brand-2: #15803d; @@ -130,6 +132,11 @@ border-bottom-color: #334155; } +/* The layout-top notice already clears the fixed navbar. */ +.Layout .VPContent { + padding-top: 0; +} + /* Community.vue is the GitHub/Discord pair in the desktop navbar. Keep the stock entries so the mobile overlay still has those links, and hide the duplicates here (VPNavBarExtra is also inside VPNavBar). */ @@ -143,11 +150,33 @@ background-color: #0f172a; } +@media (min-width: 960px) { + .Layout .VPSidebar { + top: calc(var(--vp-nav-height) + var(--moq-banner-height)); + height: calc(100vh - var(--vp-nav-height) - var(--moq-banner-height)); + padding-top: 0; + } +} + /* Home hero styling */ .VPHero .name { color: #22c55e; } +.vp-doc .language-icon { + width: 2rem; + height: 2rem; + object-fit: contain; + display: inline-block; + vertical-align: middle; + margin-right: 1rem; +} + +.vp-doc td:has(.language-icon) { + white-space: nowrap; + min-width: 10rem; +} + /* Feature layout - emoji in top right corner */ .VPFeature { position: relative; diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 6bd4245b5ac..3f22497a27f 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -48,7 +48,7 @@ clients by `--auth-url` or `--auth-public`, as the relay does (see ```bash # Publish a file (remux to MPEG-TS without re-encoding) -ffmpeg -re -i video.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ +ffmpeg -re -i video.mp4 -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - | \ moq --connect https://relay.example.com/anon --broadcast my-stream.hang import ts # Pull it back out @@ -75,11 +75,37 @@ ends the import like any other rewind. The same flag on an elementary PID other continuity-counter gap, and the 33-bit timestamp rollover move no clock and declare nothing. FLV covers H.264 + AAC. +`import ts` samples each elementary stream's access-unit count once a second and +logs a stream whose count stopped advancing, with how long it has been quiet on +the program clock, once per silence. The mux can keep flowing, PCR and +continuity intact, around a PID that delivers nothing, and no transport check +downstream sees it. A sparse stream such as SCTE-35 goes quiet between cues, so +the line reports rather than alarms; `Import::stats` carries the same counters +for a caller that sets its own limit. + +MPEG-TS import takes one program. A multi-program stream is refused before +anything is published, naming its programs, rather than merged onto one clock; +a PAT that adds a program mid-stream ends the import the same way. +`--program 2` imports program 2 alone. `--program all` publishes each program +the first PAT lists as its own broadcast, with its own clock and catalog, keeping +the catalog suffix last: `--broadcast event.hang` publishes `event/1.hang`, +`event/2.hang`, and so on. `export ts` writes one program per broadcast. +`import srt` takes the same `--program`. + +```bash +moq --connect https://relay.example.com/anon --broadcast event.hang import ts --program all < mux.ts +``` + MPEG-TS export restarts its clock and table cadence after a declared marker, discarding the old mux buffer. The first new clock packet signals the break and stdout pacing re-anchors. Every rendition joins the new program generation; no track is fenced across the marker. +MPEG-TS export frames AAC as ADTS, which labels only the AAC Main, LC, SSR, +and LTP profiles. HE-AAC and HE-AACv2 go out as their AAC-LC core, and decoders +find the SBR and PS in band, as ffmpeg's ADTS output does. A track whose +profile or channel layout ADTS cannot label is refused rather than mislabeled. + A constant-rate MPEG-TS source records its multiplex rate in the catalog (`mpegts.muxRate`, measured off the PCR clock, null stuffing included), and `export ts` pads its output with null packets back to that rate so an IRD or @@ -101,9 +127,11 @@ moq --connect https://relay.example.com/anon --broadcast my-stream.hang play moq ... play --delay 500ms # trade latency for a jittery link ``` -Decodes H.264, H.265, and AV1 video and Opus, PCM, and AAC-LC audio using -the platform hardware decoder where available. `--video-name` and -`--audio-name` pick a rendition. +Decodes H.264, H.265, and AV1 video using the platform hardware decoder where +available, and Opus, PCM, and AAC-LC (mono or stereo) audio in software. The +log names the decoder each track opened. `--video-name` and `--audio-name` +pick a rendition. HE-AAC signaled only in band (implicit SBR, as over MPEG-TS) +plays as its half-rate AAC-LC core. Playback runs on a clock it owns. `--delay` (default 100 ms) is how far it trails the live edge, which is both the jitter a late frame may absorb and the @@ -259,8 +287,8 @@ and publishes on the cluster origin. A `moq --cluster-lan` process and a `--cluster-lan` advertises this process on the LAN over mDNS and meshes with every other participating MoQ process. It reuses `--listen`, filling in an ephemeral port and a generated certificate when those are unset. A LAN peer -authenticates with its mDNS credential; `cluster.token` is for static and -gossip peers only. +authenticates with its mDNS credential; `cluster.token` is for +`--cluster-connect` and `--cluster-connect-api` peers only. ```bash moq --cluster-lan import capture @@ -278,8 +306,7 @@ under. Peers using a different name never discover this one. It defaults to configuration. An application built on the library picks its own name. The WAN flags (`--cluster-connect`, `--cluster-connect-api`, `--cluster-node`, -`--cluster-mesh`, `--cluster-token`, `--cluster-id`, `--cluster-tier`) match -the relay. `--cluster-connect` and `--cluster-connect-api` are a MoQ side on +`--cluster-token`, `--cluster-id`, `--cluster-tier`) match the relay. `--cluster-connect` and `--cluster-connect-api` are a MoQ side on their own, so `moq --cluster-connect https://relay.example import ts` needs no `--connect`. See [Clustering](/bin/relay/cluster). @@ -331,6 +358,14 @@ not arrival order, so two exporters of one broadcast emit them in one order. A track quiet for longer is muxed around until it catches up; a sparse track (SCTE-35) costs that wait once per cue. `--max-age 0` keeps arrival order. +A stdout export ends with the broadcast. `export ts --linger 10s` waits that +long for the broadcast to come back instead: a publisher that restarts within +it is picked up under the same PIDs, with the break flagged (PCR discontinuity, +PAT/PMT re-sent). Nothing is written while it is gone. When the linger runs out, +the exit code is that of the last end: 0 if the broadcast finished cleanly, 1 if +it dropped or failed. The default is `0s`, which exits on the first end the same +way. Only `ts` can mark the restart, so the other formats refuse `--linger`. + ## Debugging `RUST_LOG=debug` prints the negotiated version and every subscription. diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index fa2cc877e5e..117064a59a6 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -88,6 +88,12 @@ timeline epoch and resets the handoff baseline. The pause does not inflate advertised jitter, and previously measured maxima remain. Resumed timestamps must continue forward on the broadcast media clock. +A video pad joining mid-GOP drops delta frames until its first keyframe. If a +source rewinds below the producer's live edge without signalling a break, the +pad drops that frame and waits for a keyframe at or beyond the live edge. It +keeps the rendition alive and preserves the media timeline; it does not shift +rewound timestamps forward. + ## moqsrc Pads are named by kind and appear as the catalog announces renditions: diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index d313dd825a2..d64da538e70 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -22,6 +22,13 @@ relayed from what the peer just withdrew, rather than falling back to them one by one. During reconnect, another session from that peer can still advertise the broadcast; an old session's withdrawal does not invalidate that route. +A relay two hops from the publisher's still holds routes relayed through others. +So a change of a broadcast's best route waits 300 ms before it is announced, +while a new broadcast and a removed one go out at once. By then the withdrawal +has usually removed the other stale routes too, and the relay sends one +retraction instead of advertising each stale path in turn. Requests still +follow the current best route immediately; only the announcement waits. + Failover routes must carry copies of the same broadcast. For each track, the relay requires matching timescale, retention window, publisher priority, and group ordering. A source with different properties is refused before its groups @@ -29,9 +36,23 @@ are spliced in. If no compatible source remains, the track fails with `Unsupported`. New immutable properties require a new track name or broadcast identity. +A route whose original publisher (its first hop) changes is updated in place on +both wire protocols, so the broadcast never briefly vanishes downstream. +Subscriptions already in flight keep draining the old publisher until it ends +and are never spliced onto the new one. New requests resolve through the updated +route as a fresh broadcast, without the old publisher's track properties. + +A publisher whose protocol names no hop (moq-transport without the cluster +extension, moq-lite 01 through 03, or a peer that sends 0) gets a random first +hop from the relay it connects to, fresh for each connection, followed by a 0. +Its reconnect is therefore a new publisher downstream, a reprice on the same +connection stays in place, and the 0 keeps it ranked as anonymous. + ## Topology -List the peers each relay dials. That's the whole topology. +List the peers each relay dials. That's the whole topology: a relay dials only +peers from `connect`, [`connect_api`](#dynamic-peer-lists), or +[LAN discovery](#lan-discovery), never a URL learned from an announcement. ```toml # us-west.toml @@ -42,6 +63,10 @@ connect = ["https://us-east.example.com/"] A chain (`eu-west <- us-east <- us-west`) dedupes fetches through the middle; a full mesh trades that for one fewer hop. Mix shapes as your traffic demands. +For a full mesh, list every other relay, or serve the list from `connect_api`. +A session carries both directions, so one dial per pair is enough; listing a +pair on both sides opens a redundant second session. + ## Link costs Add `?cost=N` to a peer URL to route by price instead of hop count. An unpriced @@ -100,25 +125,12 @@ the warm side while the cold price still says who sits closest to the publisher. moq-transport has nowhere to carry the cold price, so a route learned from it ranks with an unknown (worst-case) one. -## Discovery - -Instead of listing every peer, tell each relay its own URL and turn on gossip. -Connected relays learn about each other and dial back; between any two -gossiping nodes, only the one with the smaller URL dials. - -```toml -[cluster] -connect = ["https://us-east.example.com/"] -node = "https://us-west.example.com/" -mesh = true -``` - -A relay with `node` and `mesh` but no `connect` is a passive rendezvous. +## LAN discovery -On a LAN there may be no seed peer to gossip through. `[cluster.lan]` advertises -this relay over mDNS and dials the peers that advertise back, so a rack or a -home lab meshes with no seed list. A `moq --cluster-lan` process on the same -network joins the same mesh: +On a LAN there may be no one to list. `[cluster.lan]` advertises this relay +over mDNS and dials the peers that advertise back, so a rack or a home lab +meshes with no seed list. A `moq --cluster-lan` process on the same network +joins the same mesh: ```toml [cluster] @@ -133,10 +145,10 @@ enabled = true ``` A LAN peer authenticates with its mDNS credential on `/.cluster/` -and is never handed `cluster.token`; that token is for static and gossip peers -only. The advertisement carries the listener fingerprint when the certificate -was generated or supplied in-memory, the `node` URL when one is configured, -and at least one of them. `secret` is optional. Without it, anyone who can +and is never handed `cluster.token`; that token is for `connect` and +`connect_api` peers only. The advertisement carries the listener fingerprint +when the certificate was generated or supplied in-memory, the `node` URL when +one is configured, and at least one of them. `secret` is optional. Without it, anyone who can reach the listener joins, so leave it unset only on networks you trust. With it, only peers that prove they hold the same key are discovered or accepted. mDNS is still an open channel: the secret authenticates the record, it does @@ -177,8 +189,8 @@ clients decode it. Peers dial with **mTLS** (recommended: `listen.tls.root` on the listener, `connect.tls.cert`/`key` on the dialer) or a **JWT** (inline `?jwt=` on a peer -URL, `token` on a peer object, or a shared `cluster.token` file for static and -gossip peers). The +URL, `token` on a peer object, or a shared `cluster.token` file for every +listed peer). The accepting relay admits a peer through the same lease as any client: its certificate is reported to the auth server, which grants it, so a mesh needs `moq auth serve --mtls-publish '**' --mtls-subscribe '**'` (or a server of @@ -197,5 +209,5 @@ accepted peer counts only when its grant sets `peer: true`; otherwise it looks like a client ingesting here. An embedder reads this as `Route::source()` and filters with `origin::Consumer::local()`. -The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) shows the cluster -as this relay sees it. +The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) lists the peers +this relay dialed and holds a session with. diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 6cec124121a..209b8032e3c 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -132,7 +132,6 @@ See [Authentication](/bin/relay/auth). [cluster] connect = ["https://us-east.example.com/?cost=10"] # Peers to dial. ?cost prices the link, or use {url, cost, egress, token} objects. node = "https://us-west.example.com/" # This relay's own URL. -mesh = true # Gossip: peers discover and dial `node`. connect_api = "https://api.example.com/peers" # Or fetch the peer list (JSON array of URLs and/or objects) live. token = "cluster.jwt" # JWT for dials without an inline ?jwt=. id = 12345 # Stable Hop ID across restarts. diff --git a/doc/bin/relay/http.md b/doc/bin/relay/http.md index 23743393e0a..4863714326b 100644 --- a/doc/bin/relay/http.md +++ b/doc/bin/relay/http.md @@ -95,9 +95,10 @@ curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?id=00ff' ### GET /nodes -This relay's view of the cluster: each visible node's URL, Hop ID, the route -its advertisement took, and the connections to it (with the same `conn` id the -logs use). A route is priced twice: `cost` as the cluster stands, which reads 0 -through a relay already carrying the broadcast, and `cold_cost` with those -discounts removed, which is what tells two warm relays apart. It is best-effort -correlation, not authenticated identity. +The peers this relay dialed and holds a session with: each node's URL, without +its query, and the connections to it, with the same `conn` id the logs use. +Peers that dialed this relay are not listed, since they declare no URL. + +```json +{ "nodes": [{ "node": "https://us-east.example.com/", "connections": [{ "id": 3 }] }] } +``` diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index f0caabd0112..a2af14c1061 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -13,7 +13,7 @@ relay serves video, audio, and data alike. - **QUIC, WebTransport, and WebSocket** listeners, so browsers and native clients connect to one process. - **Path-scoped authentication** with JWTs, mTLS for peers, and anonymous patterns, decided by an auth server or a static grant. See [Authentication](/bin/relay/auth). -- **Clustering** across hosts and regions with hop-list routing, per-link costs, gossip discovery, and dynamic peer lists. See [Clustering](/bin/relay/cluster). +- **Clustering** across hosts and regions with hop-list routing, per-link costs, LAN discovery, and dynamic peer lists. See [Clustering](/bin/relay/cluster). - **A group cache** with byte and age budgets, so late joiners and the HLS gateway can fetch recent history. - **HTTP endpoints** to list broadcasts, fetch groups, probe health, and scrape Prometheus metrics. See [HTTP](/bin/relay/http). - **Live stats** published as MoQ tracks per node and per tenant, split by billing tier. @@ -27,6 +27,9 @@ cargo install moq-relay # or brew, apt, dnf, winget, docker; see Instal moq-relay relay.toml ``` +The `.deb` and `.rpm` systemd service reads `/etc/moq-relay/relay.toml` +using the same positional config argument. + The relay takes one TOML file. A local development config: ```toml diff --git a/doc/bin/rtmp.md b/doc/bin/rtmp.md index 3dd8823fbbc..849fb9ed87f 100644 --- a/doc/bin/rtmp.md +++ b/doc/bin/rtmp.md @@ -39,6 +39,10 @@ Any other player receives one video rendition: the largest picture (then highest bitrate) in a codec it advertised. A push carries the largest one. Implemented in pure Rust (no librtmp). The CLI speaks plaintext `rtmp://` -only; the library adds RTMPS on the same port when the embedder supplies a TLS -config. FLAC and MP3 enhanced-audio payloads are dropped because hang has no +only. The library adds RTMPS on the same port when the embedder supplies a TLS +config, and by default still accepts plaintext `rtmp://` there, so stream keys +can arrive unencrypted. The embedder can set `plaintext` to `false` to serve +`rtmps://` only: a plaintext client is refused at its first byte and the refusal +is logged with the peer address. Refusing plaintext without a TLS config fails +at startup. FLAC and MP3 enhanced-audio payloads are dropped because hang has no catalog codec for them. diff --git a/doc/bin/srt.md b/doc/bin/srt.md index d923fa49b5b..ee4ff667119 100644 --- a/doc/bin/srt.md +++ b/doc/bin/srt.md @@ -8,7 +8,10 @@ description: SRT contribution and playback `moq import srt` accepts SRT pushes (`--listen`) or pulls from a remote SRT source (`--connect`); `moq export srt` serves SRT to players or pushes to a remote. The payload is MPEG-TS, so the same codecs as [`import ts`](/bin/cli) -apply: H.264/H.265 video and AAC, MP2, AC-3, or E-AC-3 audio. +apply: H.264/H.265 video and AAC, MP2, AC-3, or E-AC-3 audio. Ingest logs the +same per-stream lines as `import ts`, under an `srt{path=...}` span: an +elementary stream that stopped delivering access units, and audio frame sync +lost. ```bash # Accept a contribution feed and publish it @@ -25,6 +28,15 @@ moq --connect https://relay.example.com/anon --broadcast event.hang import srt - Import publishes the feed's own PTS and anchors the catalog clock on its first frame, as [`import ts`](/bin/cli) does. +A multi-program feed is refused, as with `import ts`, unless `--program` +picks one: `--program 2` imports program 2 alone, and `--program all` +publishes each program as its own broadcast (`event.hang` becomes +`event/1.hang`, `event/2.hang`, and so on). + +```bash +moq --connect https://relay.example.com/anon --broadcast event.hang import srt --listen '[::]:9000' --program all +``` + `--latency` sets the SRT receive buffer and doubles as the skip threshold on export. Export paces each SRT payload on the media clock, and re-anchors that pacing on a declared marker, so a restarted timeline plays out from the diff --git a/doc/concept/hang.md b/doc/concept/hang.md index c14d6685bf4..5846a0f62de 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -138,16 +138,14 @@ The `container.kind` on each rendition says how frames are framed: A consumer skips renditions with a kind it doesn't recognize and carries them through when republishing the catalog. -A Legacy video publisher can close the last frame's duration with an empty +A Legacy or LOC video publisher can close the last frame's duration with an empty codec payload whose timestamp is that frame's exclusive end. Consumers treat it as metadata and never pass it to a decoder. This lets a group close immediately without waiting for the next frame. Audio has codec-defined durations, and CMAF carries sample durations directly, so neither needs per-group duration markers. Audio retains its separate terminal marker before codec drain packets, allowing -consumers to discard encoder padding beyond the source endpoint. LOC readers -also skip empty payloads; LOC writers wait for the compatibility release before -emitting markers. Empty payloads on data tracks remain data, including empty -text cues. +consumers to discard encoder padding beyond the source endpoint. Empty payloads +on data tracks remain data, including empty text cues. ## Groups and keyframes diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 3e4c77e7964..6d70ac61376 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -32,20 +32,30 @@ and newer, each side also sends a `SETUP` message with its capabilities. Rust and TypeScript speak moq-lite 01 through 06 and moq-transport drafts 14 through 22. Clients offer `moq-lite-06` first by default. moq-lite 07 is still in progress: it negotiates as `moq-lite-07-wip`, and only when both -sides explicitly enable it. +sides explicitly enable it. moq-lite 07 also switches every varint from QUIC's +two-bit length prefix to moq-transport's leading-ones form, so values up to 127 +take one byte instead of up to 63, and the range widens from 62 to 64 bits. Rust +still refuses lite-07 values above 2^62-1 until its `VarInt` widens. ## Subscription completion On moq-lite 07, `SUBSCRIBE_END` counts the group streams opened for the subscription. Rust and TypeScript stop waiting for missing streams once that -many headers have arrived; skipped group sequences add no wait. Groups already -being received continue until their own stream ends or resets. +many headers have arrived; skipped group sequences add no wait. A stream whose +header arrived is always read to its end before the subscription completes. A stream reset before its header arrived cannot be counted, so the subscriber still allows a grace period for late streams. The grace uses the subscription's nonzero effective maximum age, or one second when no maximum age is set. -moq-lite 05 and 06 instead account for group sequences using received headers -and `SUBSCRIBE_DROP`. +moq-lite 05 and 06 instead account for group sequences using received headers, +datagrams, and `SUBSCRIBE_DROP`, from the start group the subscription last +asked for. A lost datagram is not owed, but its hole waits out the grace like a +lost stream. + +From moq-lite 06, an end that contradicts the groups received aborts the track: +a group at or past `SUBSCRIBE_END`, or a `SUBSCRIBE_END` below a group already +received. moq-lite 05 specified an inclusive end, so there it only drops that +group or the early boundary. ## Discovery @@ -65,7 +75,8 @@ that serves only some of the paths beneath its prefix refuses the rest as they are requested. Each route carries the chain of relay identities it passed through, which is how forwarding loops are caught, and a cost, which is how a subscriber picks among several routes to the same broadcast. A hop of 0 is the -anonymous mark and travels the chain unchanged. A route that passed through an +anonymous mark and travels the chain unchanged; when it is the first hop, a relay +puts a random ID, fresh per connection, in front of it to name the publisher. A route that passed through an anonymous hop at any depth ranks below every fully identified route, whatever the costs say; among anonymous routes, cost keeps ordering. @@ -84,7 +95,10 @@ in flight alone: each track runs to its own end or failure. On moq-lite 05 and newer, a clean end requires `SUBSCRIBE_END` before the publisher's FIN. A FIN without that declaration fails the subscription with `ProtocolViolation`; older moq-lite versions use FIN alone. moq-transport requires `PUBLISH_DONE` before FIN. -moq-transport sessions behave the same when a namespace is withdrawn. +moq-transport sessions behave the same when a namespace is withdrawn. A route +update that changes its first hop, the original publisher, is not a retraction: +subscriptions in flight drain the old publisher, and new requests resolve +through the new one. A graceful session close withdraws its announcements and waits up to one second for transport acknowledgement before disconnecting. Rust uses @@ -99,8 +113,8 @@ without waiting, since it has no FIN to acknowledge. A path segment starting with `.` hides a route from discovery, the way a dotfile hides from `ls`. A platform publishes its own broadcasts there (relay -stats under `.stats/`, cluster gossip under `.internal/`) without them turning -up in an app that lists everything and plays what it finds. Only segments +stats under `.stats/`) without them turning up in an app that lists +everything and plays what it finds. Only segments below the requested prefix count: listing the root skips `.stats/node`, but listing `.stats` shows `node`. A `.` elsewhere in a segment (`catalog.pro`) is part of the name. @@ -120,8 +134,12 @@ const announced = connection.announced(Path.Pattern.all(), { hidden: true }); On the wire, moq-lite 07 (`moq-lite-07-wip`, opt-in only) carries the opt-in on each announce request, and moq-transport carries it as a `SUBSCRIBE_NAMESPACE` parameter once the peer's -`SETUP` says it understands one ([hidden](/draft/moq-hidden)). An older peer -never opts in, so it never discovers hidden routes. Rust sessions always opt in +`SETUP` says it understands one ([hidden](/draft/moq-hidden)). An older MoQ Lite peer +never opts in, so it never discovers hidden routes. +IETF peers that omit the MoQ Hidden setup option receive all authorized +namespaces, including dot-prefixed namespaces. Peers that declare it opt in +per subscription; a prefix naming the dot segment itself also lists its +children. Rust sessions always opt in on the wire and filter per local reader, so a relay mirrors everything and each consumer decides. @@ -241,6 +259,13 @@ anything on its own. Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads, since the publisher only ever sees the most tolerant budget across its subscribers. +Across a native route failover, the reader still judges buffered groups against +the logical track's live edge, including groups it is draining from a retired +route. A successor group with no timestamp leaves the preceding group's reach +unbounded until its first frame arrives; if it is dropped first, the next group +takes its place. A cached open group's prefix remains +readable across repeated takeovers and idle resumes. + The publisher may declare a retention window per track. Omission sets no limit; zero keeps only the live edge. The origin cache ceiling and cache pool may still evict content sooner. Relays preserve the publisher's declaration rather than @@ -248,7 +273,8 @@ substituting a local default. Media tracks explicitly use 30 seconds so a segmented egress can still find its segments. IETF carries this value as MAX\_CACHE\_DURATION, received on every supported draft -and sent from draft 17 onward. Drafts 14–16 remain receive-only for compatibility +and sent from draft 17 onward. A relay reads it from FETCH\_OK as well as SUBSCRIBE\_OK, so a track it +only fetches still learns its window. Drafts 14–16 remain receive-only for compatibility with older implementations. This is an approximate mapping: IETF measures wall time, while max age uses media timestamps and always keeps the newest group. EXPIRES describes subscription lifetime and does not set retention. diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 6c7b3b8b48e..2d88de25676 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -26,21 +26,43 @@ maps everything else to "not supported" or a harmless equivalent. The [moq-lite page](/concept/moq-lite#what-moq-lite-leaves-out) lists the differences. +Rust and JavaScript subscribers accept object extension blocks up to 64 KiB. +This is an implementation limit, not a limit in the IETF draft. A larger +declared block stops its subgroup stream with `MALFORMED_TRACK` before reading +the block; other groups and the session stay open. + An IETF publisher declares the track's default priority in `SUBSCRIBE_OK` or `PUBLISH` when that draft carries track properties. Groups without a priority flag inherit it. If the property is absent, the IETF wire default of 128 maps -to model priority 127, where higher values are served first. - -On drafts 14–19, the Rust publisher serves relative joining `FETCH` requests -with offset zero for `NextObject` subscriptions. The fetch delivers the saved -current-group prefix, and the subscription delivers later objects. Standalone, -absolute joining, and nonzero-offset fetches are refused. Draft-20 uses -subscription fills instead. JavaScript publishing does not yet serve `FETCH`; +to model priority 127, where higher values are served first. A track that +never sets a priority is 127 as well, so it goes out as 128 on IETF and 127 +on moq-lite. + +On drafts 14–19, the Rust publisher answers a standalone `FETCH` within one +group from the cache. A relay fetches a missing group upstream with a `FETCH` +of that one whole group, and an upstream refusal is the refusal the fetcher +sees. A range touching several groups is refused with `NOT_SUPPORTED`, as is +any `FETCH` on draft-20 and later, which moved the range into +`LOCATION_FILTER`. A standalone `FETCH` +carries no timestamps, since no `SUBSCRIBE_OK` declared a timescale for it. + +On drafts 14–19, the Rust publisher also serves relative and absolute joining +`FETCH` requests for `NextObject` subscriptions, for the subscription group's +saved prefix only, while the subscription delivers later objects. One reaching +back to earlier groups is refused with `NOT_SUPPORTED`. Draft-20 uses +subscription fills instead. JavaScript +publishing does not yet serve `FETCH`; Rust and JavaScript subscribers request unfiltered delivery on older drafts because they do not issue joining fetches. Other publishers may replay a cached backlog for that filter; selecting the next group instead would leave static tracks waiting for a group that never arrives. +A moq-lite datagram is a single-frame group, so on moq-transport it travels +as an `OBJECT_DATAGRAM` at object 0 whose Group ID is the sequence, and a relay +forwards it without renumbering. A datagram carrying any other Object ID, or a +status other than Normal, is dropped. JavaScript does not yet carry datagrams +on moq-transport. + A client may present one credential in its `SETUP` with the `AUTHORIZATION TOKEN` option. The server reads a value (`USE_VALUE`, or `REGISTER`, which it treats as a value since it advertises no token cache) and hands its Token Type @@ -83,7 +105,7 @@ supports, and prints it in the logs. Publish a test pattern and play it back: ```bash ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 -f lavfi -i sine=frequency=440 \ -c:v libx264 -preset ultrafast -tune zerolatency -g 60 -c:a aac \ - -f mpegts -pes_payload_size 0 - \ + -f mpegts -pes_payload_size 0 -muxdelay 0 - \ | moq --connect https://relay.example.com --broadcast test.hang import ts moq --connect https://relay.example.com --broadcast test.hang export ts | ffplay - diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 23e2b39023a..f49b96850ea 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -43,7 +43,8 @@ pkg-config file included. - **Threading.** Any function from any thread. Raw publish calls block until the codec takes the frame, which paces a publisher. - **Connection health.** `moq_session_stats()` reports available metrics with per-field validity flags. `moq_session_snapshot()` samples those metrics and the negotiated draft name together from the same connection. Its protocol string is backed by static storage. Both return an offline error between reconnects and leave the destination untouched. `moq_session_bandwidth()` mints an allocator over the send estimate; `moq_bandwidth_reserve` claims a share for an app-owned track, and `moq_encode_video` / `moq_encode_audio` take the same handle so the built-in video encoder follows the grant. - **Raw playback.** Raw audio and video consumers start at the newest cached group when opened, so rebuilding a live decoder skips the retained backlog. -- **Raw audio encode.** `moq_audio_encoder_output.codec` names the codec (only `"opus"` today), and `frame_duration_us` sets the Opus frame length: 2500, 5000, 10000, 20000, 40000, or 60000, with 0 meaning the 20 ms default. +- **Raw audio encode.** `moq_audio_encoder_output.codec` names the codec: `"opus"`, `"pcm"`, or `"aac"`. `frame_duration_us` sets the Opus frame length: 2500, 5000, 10000, 20000, 40000, or 60000, with 0 meaning the codec's default (20 ms for Opus, 1024 samples for AAC). AAC-LC encodes through the platform's encoder, so a host without one refuses it. +- **Audio channel layouts.** A `channels` count also names the speaker layout, by the WAVE convention: 1 is mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved front left, front right, center, LFE, back, then side. `moq_decode_audio` remixes to the count you ask for; past 8 channels the samples pass through but can't be remixed. - **Raw decode output.** `moq_video_decoder_output` selects the decoded CPU pixel format (`MOQ_VIDEO_PIXEL_FORMAT_I420` or `_RGBA`) and target size (`width`/`height`, both zero for native; otherwise even and non-zero). Unknown formats and invalid sizes fail `moq_decode_video` before subscribing. - **Decoded frames.** Each frame id owns its decoded picture until `moq_decode_video_frame_free`, including after `moq_decode_video_cancel` and the terminal callback. The first `moq_decode_video_frame` call converts it to the requested layout and size; its `data` pointer then stays put until the id is freed. A conversion failure returns a negative code for that frame only. Free frames promptly: held frames hold decoder buffers, and a decoder whose buffers are all held stalls. - **Encoded video metadata.** `moq_video_init.hint` is a zero-initialized `moq_video_hint` with `has_*` flags for coded dimensions, bitrate (bits per second), frame rate, and latency preference. Hints seed a video codec track's catalog; detected dimensions take precedence. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index d38754de87c..6f6b98038a7 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -108,7 +108,8 @@ Cancelling a stream releases the native cursor. The package re-exports Generated configuration setters throw if a connect, listen, or accept is in flight, or after `cancel()`. Incoming requests report a `MoqTransport` enum. `ProtocolMoqException` carries a `MoqProtocolException` as `details` (scope, verbatim -code, kind) when the peer sent a session or stream code. +code, kind) when the peer sent a session or stream code. An exception's +`toString()` is the Rust error message. `moq.bandwidth()` divides the connection's send estimate; `reserve` a share for an app-owned encoder so several publishers on one session split the diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index a176d5131c3..47732078608 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -132,7 +132,19 @@ of the [shared feature list](/lib/#what-every-binding-can-do) maps one to one: `FetchGroup`/`FetchMediaGroup`, `Dynamic()` with `Requests(ctx)`, `Session.Bandwidth()` to divide the send estimate, `AppendDatagram`/`Datagrams(ctx)`, `SetCatalogSection`, `Demand()` for `Used`/`Unused`, -`Session().Stats()`. `moq.IsAuthError` and `moq.IsShutdown` classify errors. `moq.ProtocolError(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. +`Session().Stats()`. `moq.IsAuthError` and `moq.IsShutdown` classify errors. `moq.ProtocolError(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. `err.Error()` is the Rust error message. + +`EncodeAudio` encodes raw PCM inside the binding. Its codec is `OpusAudioCodec()` +or `AacAudioCodec()`, and `AudioEncoderOutput.FrameDurationUs` sets the Opus +frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. 0 takes +the codec's own frame, which AAC needs. AAC-LC encodes through the platform's +encoder, so a host without one refuses it. + +Audio `Channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. Each `VideoDecodedFrame` from `DecodeVideo` owns its decoded picture until `Close`, including after the consumer is cancelled. `Pixels(format)` converts it diff --git a/doc/lib/index.md b/doc/lib/index.md index d6107028574..ce003ab4bf4 100644 --- a/doc/lib/index.md +++ b/doc/lib/index.md @@ -10,14 +10,14 @@ protocol. A publisher in Python is consumable by a subscriber in Swift. | Language | Package | Best for | | --- | --- | --- | -| [Rust](/lib/rs/) | `moq-net`, `hang`, and friends on crates.io | Servers, CLIs, native apps, anything that needs the full stack including hardware codecs. | -| [TypeScript](/lib/js/) | `@moq/*` on npm | Browsers (WebTransport + WebCodecs) and Node/Bun/Deno. | -| [Swift](/lib/swift/) | `Moq` via SwiftPM | iOS, iPadOS, macOS. | -| [Kotlin](/lib/kt/) | `dev.moq:moq` on Maven Central | Android and the JVM. | -| [Python](/lib/py/) | `moq-rs` on PyPI | Scripts, ML pipelines, voice agents. | -| [Go](/lib/go/) | `moq.dev/moq` | Go services and tooling. | -| [Dart](/lib/dart/) | `moq` on pub.dev | Flutter apps. | -| [C](/lib/c/) | `moq-c` | C/C++ and any language with a C FFI. | +| [Rust](/lib/rs/) | `moq-net`, `hang`, and friends on crates.io | Servers, CLIs, native apps, anything that needs the full stack including hardware codecs. | +| [TypeScript](/lib/js/) | `@moq/*` on npm | Browsers (WebTransport + WebCodecs) and Node/Bun/Deno. | +| [Swift](/lib/swift/) | `Moq` via SwiftPM | iOS, iPadOS, macOS. | +| [Kotlin](/lib/kt/) | `dev.moq:moq` on Maven Central | Android and the JVM. | +| [Python](/lib/py/) | `moq-rs` on PyPI | Scripts, ML pipelines, voice agents. | +| [Go](/lib/go/) | `moq.dev/moq` | Go services and tooling. | +| [Dart](/lib/dart/) | `moq` on pub.dev | Flutter apps. | +| [C](/lib/c/) | `moq-c` | C/C++ and any language with a C FFI. | ## How they relate diff --git a/doc/lib/js/hang.md b/doc/lib/js/hang.md index 3487eeb136f..c8b03da1da6 100644 --- a/doc/lib/js/hang.md +++ b/doc/lib/js/hang.md @@ -30,3 +30,45 @@ handle's `path`. Run the same checks on a catalog from another source with Most apps never import it directly; the elements and `Broadcast` classes in the watch and publish packages do. Reach for it when hand-rolling a catalog or building a custom player. + +## Wall clock + +A catalog root may carry a `clock`: `{ wall, timescale }`, the wall-clock time +of PTS zero in `timescale` units (microseconds by default) since 2020-01-01. +`Catalog.wallClockTime(clock, pts, ptsTimescale)` maps a frame's PTS to a +`Date`. A `Container.Legacy` frame timestamp is microseconds, so pass `1_000_000`. + +```ts +for await (const root of Catalog.watch(broadcast)) { + if (!root.clock) continue; // the publisher exposes no clock + // `frame` comes from your own `Container.Legacy` consumer. + const captured = Catalog.wallClockTime(root.clock, frame.timestamp, 1_000_000); +} +``` + +- The mapping is fixed for the life of the broadcast. A discontinuity or a + system-clock adjustment on the publisher does not change it. +- It is independent of `archive`. A live-only broadcast carries a `clock` with + no segment index, so a DVR view can label its timeline from it either way. +- A `Date` holds whole milliseconds, so anything finer in the clock is + truncated. +- A result past the `Date` range comes back as an invalid `Date`, not an + exception, so check it before use. + +Two machines' wall times are only comparable when your application already +knows their clocks are synchronized. The catalog says where PTS zero was on the +publisher's clock, never whether the viewer's clock agrees with it. If you do +know, set `delay` to `target - (arrived - captured)`, where `arrived` is the +viewer's `Date.now()` for the frame that arrived earliest relative to its +timestamp, since `` anchors playback on that frame. That holds only +with the default zero `buffer`; a lookahead moves the anchor. `` adds +the largest active rendition's buffer on top, so a frame renders at about +`captured + target` plus that buffer: the rendition's catalog `delay` plus its +`jitter` (one video frame or one codec frame when unset), and for audio the +worklet quantum too. Viewers only line up when that buffer matches, and a +negative result means the target is already missed. + +The library never does this for you. Playback stays arrival-based: it does not +read the `clock`, estimate the viewer's clock from the session RTT, or +exchange time over a track, and a timestamp stays relative to the broadcast +rather than a reading of any wall clock. diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 8e00983cc21..4e77fa26593 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -54,7 +54,7 @@ for (;;) { - **Publisher retention** is optional `Track.Info.maxAge`: omission sets no limit, while zero keeps the live edge. No implicit five-second window is applied. - **Subscriptions** carry a priority, a `Time.Milli` max age, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. - **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. A remote track ends only once every group below its end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. -- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. +- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. - **Errors** live under one namespace: a stream reset throws `Error.Stream` with a `StreamCode`, while a session close gives `Error.Session` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Named conditions such as `Error.TooFarBehind`, `Error.FrameTooLarge`, and `Error.GroupTooLarge` subclass `Error.Stream`, so one `code` check handles a condition raised here or reported by the peer. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque. - **Paths** with `Path.relative` for the cross-broadcast catalog references hang uses. A `Broadcast.Consumer` names its broadcast by `path`: the path it was requested at relative to the origin handle's root, or empty for a standalone broadcast. Those references resolve against it. Path patterns (`Path.Pattern`, `Path.Patterns`) are re-exported from [`@moq/pattern`](https://www.npmjs.com/package/@moq/pattern). Literal `Path` stays a coordinate. diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index 9b5a97e4553..6c4805ba46a 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -37,6 +37,10 @@ in sync at the latency you ask for. | `announced` | Wait for the broadcast to be announced before subscribing (default on), so a player can be mounted before the stream exists. | | `catalog-format` | `hang` (default, from the `.hang` suffix), `hangz` (compressed), `msf`, or `manual` to supply the catalog yourself. | +Video holds its last picture while paused, out of view, or waiting for a +resumed rendition's first frame. Its reported timestamp stays with that picture. +Going offline or closing the player clears it. + The overlay adds play/pause, volume, fullscreen, a quality selector, a buffering indicator, an unsupported-codec warning, and a stats panel. `` shows what the browser can play. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 43f118b095d..af711d99ee9 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -99,12 +99,21 @@ connection's send estimate; pass it to `encodeVideo` / `encodeAudio` or `reserve` a share for an app-owned track. `MoqException.isAuth` and `isShutdown` classify errors. Microsecond fields read back as a `kotlin.time.Duration`: `stats.rtt`, `backoff.initial`, `frame.timestamp`. `protocolError` is the structured protocol failure -(scope, verbatim code, kind) when the peer sent one. Cancelling the collecting coroutine cancels the -native side. +(scope, verbatim code, kind) when the peer sent one. An exception's `toString()` is the Rust error message. +Cancelling the collecting coroutine cancels the native side. `encodeAudio` encodes raw PCM inside the binding. Its codec is an object, -`AudioCodec.opus()`, and `AudioEncoderOutput.frameDurationUs` sets the Opus -frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. +`AudioCodec.opus()` or `AudioCodec.aac()`, and +`AudioEncoderOutput.frameDurationUs` sets the Opus frame length: 2500, 5000, +10000, 20000 (the default), 40000, or 60000. 0 takes the codec's own frame, +which AAC needs. AAC-LC encodes through the platform's encoder, so a host +without one refuses it. + +Audio `channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. Each frame from `decodeVideo` owns its decoded picture until `close()` (or `use {}`), including after the consumer is cancelled. `frame.pixels(format)` diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 5580ee41866..8ca4dcaaa84 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -117,13 +117,22 @@ and a producer's `demand()`, a `TrackDemand` whose `used()`/`unused()` let capture idle when nobody is subscribed. `request.set_publish`/`set_consume` raise if the request is already answered, cancelled, or currently accepting. `session.bandwidth()` divides the connection's send estimate; pass it to `encode_video` / `encode_audio` or `reserve` a share for an -app-owned track. `moq.is_auth(err)` and `moq.is_shutdown(err)` classify errors. `moq.protocol_error(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. Catch `moq.Error.Busy` when a setter races an in-flight connect, listen, or accept. +app-owned track. `moq.is_auth(err)` and `moq.is_shutdown(err)` classify errors. `moq.protocol_error(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. `str(err)` is the Rust error message. Catch `moq.Error.Busy` when a setter races an in-flight connect, listen, or accept. Each server request reports a `moq.Transport` enum, including QUIC, Iroh, WebSocket, TCP, and Unix sockets. `encode_audio` encodes raw PCM inside the binding. Its codec is an object, -`moq.AudioCodec.opus()`, and `AudioEncoderOutput.frame_duration_us` sets the -Opus frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. +`moq.AudioCodec.opus()` or `moq.AudioCodec.aac()`, and +`AudioEncoderOutput.frame_duration_us` sets the Opus frame length: 2500, 5000, +10000, 20000 (the default), 40000, or 60000. 0 takes the codec's own frame, +which AAC needs. AAC-LC encodes through the platform's encoder, so a host +without one refuses it. + +Audio `channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. Each frame from `decode_video` owns its decoded picture until it is released, including after the consumer is cancelled. `frame.pixels(format)` converts it on diff --git a/doc/lib/rs/moq-audio.md b/doc/lib/rs/moq-audio.md index e320d7d1915..e42557e6aa6 100644 --- a/doc/lib/rs/moq-audio.md +++ b/doc/lib/rs/moq-audio.md @@ -13,8 +13,14 @@ the far end. Everything is Rust, so there is no C toolchain, CMake step, or codec to install. `Layout` names speaker meaning separately from a channel count. `Mono` is center, -`Stereo` is left then right, and `Discrete(n)` preserves unnamed channels without -inventing speaker positions. Encoding keeps source PCM in `encode::Input` and +`Stereo` is left then right, and the surround layouts up to `SevenPointOne` +interleave in the SMPTE/WAVE order (front left, front right, center, LFE, back, +side). A catalog carries only a count, which reads as that count's WAVE default +(`Layout::from_channels`: 6 is 5.1, 8 is 7.1). `Discrete(n)` preserves unnamed +channels without inventing speaker positions, so it passes through but never +remixes. Decoding and playback downmix with the ITU-R BS.775 coefficients and +upmix by leaving the extra speakers silent; the playback mix runs in whatever +layout the output device opened. Encoding keeps source PCM in `encode::Input` and codec requirements in `encode::Settings`; `encode::Options` adds publication policy. Decoding likewise separates low-level `decode::Config`, PCM `decode::Output`, and subscription `decode::Options`. @@ -22,18 +28,56 @@ policy. Decoding likewise separates low-level `decode::Config`, PCM | Module | Does | | --- | --- | | `capture` | Microphones via CoreAudio, WASAPI, ALSA (and PipeWire/PulseAudio hosts), plus macOS system audio | -| `encode` | PCM to Opus (with DTX and voice-activity signaling) or raw PCM for the lowest latency | +| `encode` | PCM to Opus (with DTX and voice-activity signaling), raw PCM for the lowest latency, or AAC-LC through a platform encoder | | `decode` | Opus, PCM, and AAC-LC back to PCM, resampled to the rate you want | | `playback` | One output device mixing every track in a call, with click-free volume ramps | | `aec` | Acoustic echo cancellation (a port of WebRTC's), so a laptop with no headset doesn't feed itself back | +`decode` picks a backend per track the way `moq-video` does: a platform decoder +first, then software. `decode::Config::kind` narrows it: `Kind::Software` skips +the platform tier, and `Kind::Named` requires the track to be a codec, by its +name (`"opus"`, `"pcm"`, or `"aac"`), and refuses any other. Backends are never +named; `Decoder::name()` reports which one opened. + +| Backend | Decodes | Hosts | +| --- | --- | --- | +| `libopus` | Opus, mono or stereo, and surround up to 7.1 (channel mapping family 1) | all | +| `pcm` | PCM | all | +| `symphonia` | AAC-LC, mono or stereo (the default-on `aac` feature) | all | + +No platform decoder is wired in yet, so multichannel AAC and HE-AAC declared in +its config are refused at construction on every host. HE-AAC signaled only in +band plays as its half-rate LC core. Linux has no OS audio decoder, so it will +stay that way there. Surround Opus is pure Rust, so it is the one multichannel +path every host has. Opus mapping families other than 0 and 1 (ambisonics, and +255's unpositioned channels) are refused, since they declare no speakers. + Opus always decodes at 48 kHz, its own clock, whatever input rate the OpusHead records (44.1 kHz and unknown included), and applies the head's pre-skip and output gain. A track without a description decodes mono or stereo from the catalog with neither. A description that is present but malformed (truncated, wrong signature, a new major version, or a channel count its mapping family -forbids) is refused, as is any channel mapping family other than 0, rather -than falling back to the catalog's fields. +forbids) is refused rather than falling back to the catalog's fields. + +`encode` selects the same way, through `encode::Settings::kind`, where +`Kind::Named` requires `Settings::codec` to match the codec name, and +`Encoder::name()` reports what opened. + +| Backend | Encodes | Hosts | +| --- | --- | --- | +| `libopus` | Opus, mono or stereo | all | +| `pcm` | PCM | all | + +`encode::Codec::Aac` is AAC-LC (`mp4a.40.2`) at the input's rate and layout: +mono, stereo, 3.0, 4.0, 5.0, 5.1, or 7.1, the layouts with an AAC +channelConfiguration. Frames are 1024 samples, so `Settings::from_input` sets +`frame_duration` to match. The catalog's AudioSpecificConfig is built from the +settings when the track is registered, and since it has no field for the +encoder's delay, packets are stamped that much earlier so the first input +sample still lands at the first timestamp. There is no software AAC encoder, +and no platform encoder is wired in yet, so `Codec::Aac` is refused at +construction on every host for now. Linux has no OS encoder, so it will stay +that way there. Highlights: diff --git a/doc/lib/rs/moq-mux.md b/doc/lib/rs/moq-mux.md index a1f71ff50d6..d240598c61a 100644 --- a/doc/lib/rs/moq-mux.md +++ b/doc/lib/rs/moq-mux.md @@ -14,7 +14,7 @@ Turns existing container formats into hang broadcasts and back. This is what | Format | Import | Export | Notes | | --- | --- | --- | --- | | fMP4 / CMAF | yes | yes | Passthrough as `cmaf` or repackaged as `legacy`. | -| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3; SCTE-35 and subtitle PIDs carried as tracks; service tables round-trip; signalled timebase discontinuities preserved; paced export. | +| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3, Opus up to 7.1; SCTE-35 and subtitle PIDs carried as tracks; service tables round-trip; signalled timebase discontinuities preserved; paced export. | | FLV / RTMP | yes | yes | Legacy H.264 + AAC + MP3, plus enhanced-RTMP HEVC, AV1, VP9, Opus, AC-3, E-AC-3, and multitrack. | | Matroska / WebM | yes | yes | | | Annex-B (H.264, H.265) | yes | yes | Parameter sets extracted to the catalog or re-injected per keyframe. | @@ -121,7 +121,7 @@ API: [docs.rs/moq-mux](https://docs.rs/moq-mux). Real-world usage: Container producers and consumers take a format configured from the track's audio or video catalog entry (`catalog::hang::Container::try_from(&config)`). For a raw track, supply `container::Kind` explicitly. `cut(Some(end))` flushes and closes the -group immediately. Legacy video writes an empty timestamped frame at that end; +group immediately. Legacy and LOC video write an empty timestamped frame at that end; audio and CMAF do not. With no explicit end, the producer uses a known sample duration or observed cadence, independently of batching and reorder jitter. Streaming consumers deliver frames immediately. The live fMP4 exporter receives diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index b5a7f954fd7..cb2975a2063 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -21,7 +21,7 @@ above ([hang](/lib/rs/hang)); relays and CDNs implement only this. - **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max age and can change them live. - **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget. - **Track ends**: `finish()` ends a track at its live edge, while `finish_at(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber awaits it with `finished()`. A remote track ends only once every group below its end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. -- **Datagrams** send a single small frame unreliably on moq-lite 05+. +- **Datagrams** send a single small frame unreliably on moq-lite 05+ and moq-transport. - **Routes** record the relay hops and a cost, which is what the relay [cluster](/bin/relay/cluster) routes on. A hop of 0 marks the chain anonymous: `Route::is_anonymous()` is true, and that route ranks below every fully identified one. `Route::source()` says where a delivered route entered: `Source::Local`, or `Source::Peer(hop)` when a handle marked `origin::Producer::peer()` announced it. `origin::Consumer::local()` sees only the local ones. - **Stats** counters per broadcast and session, drained by [`moq-stats`](https://docs.rs/moq-stats). diff --git a/doc/lib/rs/moq-video.md b/doc/lib/rs/moq-video.md index 327f96c398d..20bfaaec78b 100644 --- a/doc/lib/rs/moq-video.md +++ b/doc/lib/rs/moq-video.md @@ -40,7 +40,11 @@ are returned rather than treated as an empty list. Other platforms return `Error::Unsupported`. With `pipewire` enabled, `capture::cameras` also lists PipeWire camera nodes as -`pipewire:` after the V4L2 devices, and `pipewire` alone opens the +`pipewire:` after the V4L2 devices. V4L2 lists only devices offering +YUYV or MJPEG. A PipeWire V4L2 node is hidden only when its device path was +already listed by V4L2, so identical webcams stay distinct, and PipeWire-only +cameras and NV12- or RGB-only V4L2 devices remain visible through PipeWire. Explicit `pipewire:` +selectors still open hidden nodes, and `pipewire` alone opens the camera with the highest session priority, the session manager's default. That reaches cameras V4L2 cannot: a Raspberry Pi CSI camera behind libcamera, and any camera from inside a Flatpak or Snap sandbox, where the default camera comes diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 0ab10f3773e..e5897ca1de2 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -101,11 +101,21 @@ to one: `fetchGroup`/`fetchMediaGroup`, `dynamic()` for tracks and `dynamic(pref divides the connection's send estimate; pass it to `encodeVideo` / `encodeAudio` or `reserve` a share for an app-owned track. `MoqError.isAuth` and `isShutdown` classify errors. `protocolError` is the structured protocol failure -(scope, verbatim code, kind) when the peer sent one. +(scope, verbatim code, kind) when the peer sent one. An error's `description` is +the Rust error message. `encodeAudio` encodes raw PCM inside the binding. Its codec is an object, -`AudioCodec.opus()`, and `AudioEncoderOutput.frameDurationUs` sets the Opus -frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. +`AudioCodec.opus()` or `AudioCodec.aac()`, and +`AudioEncoderOutput.frameDurationUs` sets the Opus frame length: 2500, 5000, +10000, 20000 (the default), 40000, or 60000. 0 takes the codec's own frame, +which AAC needs. AAC-LC encodes through the platform's encoder, so a host +without one refuses it. + +Audio `channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. Each frame from `decodeVideo` owns its decoded picture until it is released, including after the consumer is cancelled. `frame.pixels(format:)` converts it diff --git a/doc/public/icons/languages/c.svg b/doc/public/icons/languages/c.svg new file mode 100644 index 00000000000..908f7bd169f --- /dev/null +++ b/doc/public/icons/languages/c.svg @@ -0,0 +1,20 @@ + + C + + + + diff --git a/doc/public/icons/languages/dart.svg b/doc/public/icons/languages/dart.svg new file mode 100644 index 00000000000..5282756c0b9 --- /dev/null +++ b/doc/public/icons/languages/dart.svg @@ -0,0 +1,27 @@ + + Dart + + + + diff --git a/doc/public/icons/languages/go.svg b/doc/public/icons/languages/go.svg new file mode 100644 index 00000000000..b463e050841 --- /dev/null +++ b/doc/public/icons/languages/go.svg @@ -0,0 +1,26 @@ + + Go + + + + + + + diff --git a/doc/public/icons/languages/kotlin.svg b/doc/public/icons/languages/kotlin.svg new file mode 100644 index 00000000000..4412d147f70 --- /dev/null +++ b/doc/public/icons/languages/kotlin.svg @@ -0,0 +1,19 @@ + + Kotlin + + + + diff --git a/doc/public/icons/languages/python.svg b/doc/public/icons/languages/python.svg new file mode 100644 index 00000000000..5f6f9871c17 --- /dev/null +++ b/doc/public/icons/languages/python.svg @@ -0,0 +1,30 @@ + + Python + + + + + diff --git a/doc/public/icons/languages/rust.svg b/doc/public/icons/languages/rust.svg new file mode 100644 index 00000000000..f2888db2d8a --- /dev/null +++ b/doc/public/icons/languages/rust.svg @@ -0,0 +1,54 @@ + + Rust (Ferris) + + + + + + + + diff --git a/doc/public/icons/languages/swift.svg b/doc/public/icons/languages/swift.svg new file mode 100644 index 00000000000..fb2c202112f --- /dev/null +++ b/doc/public/icons/languages/swift.svg @@ -0,0 +1,36 @@ + + Swift + + + + diff --git a/doc/public/icons/languages/typescript.svg b/doc/public/icons/languages/typescript.svg new file mode 100644 index 00000000000..d9a37061a9a --- /dev/null +++ b/doc/public/icons/languages/typescript.svg @@ -0,0 +1,29 @@ + + TypeScript + + + + diff --git a/doc/setup/dev.md b/doc/setup/dev.md index d8d35f9ff87..b17faa24049 100644 --- a/doc/setup/dev.md +++ b/doc/setup/dev.md @@ -7,7 +7,8 @@ description: Build, test, and debug the MoQ repository The repository uses [Just](https://github.com/casey/just) as its command runner. Run commands inside the Nix dev shell (`nix develop`) so your tools -match CI. +match CI. `just check` and `just fix` refuse to run outside it; set +`MOQ_ALLOW_HOST=1` to use the host toolchain anyway. | Command | Purpose | | --- | --- | @@ -72,6 +73,11 @@ just fix just check ``` +These diff the branch against its upstream (or `origin/main`) and run only the +modules the diff reaches. The map from paths to modules lives in +`sh/dispatch.sh`. Recipes stay thin: any logic (conditionals, loops, traps) +lives in a script under `sh/`. + See [CONTRIBUTING.md](https://github.com/moq-dev/moq/blob/main/CONTRIBUTING.md) for branch targeting, commit messages, and reviews, and [Agent setup](/setup/agent) if an AI coding agent is doing the work. diff --git a/doc/setup/install.md b/doc/setup/install.md index 175687d6ef0..83a5e9ce0f8 100644 --- a/doc/setup/install.md +++ b/doc/setup/install.md @@ -64,7 +64,7 @@ sudo apt install moq-relay moq gstreamer1.0-moq Fedora 39+, RHEL 9, Rocky 9, AlmaLinux 9. On openSUSE use `zypper addrepo`. ```bash -sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo +sudo curl -fsSL https://rpm.moq.dev/moq.repo -o /etc/yum.repos.d/moq.repo sudo dnf install moq-relay moq gstreamer1-moq ``` diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index 2206afa1234..149cb99f86f 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -72,6 +72,7 @@ variables follow the flag (`MOQ_SERVER_BIND` is `MOQ_LISTEN`). | TOML `listen`, `connect`, `failover_delay`, `reconnect`, `disable_verify` | `bind`, `url`, `race`, `once` (inverted), `insecure` | | `--cluster-linger` | removed; a broadcast closes when its last publisher is lost | | `--cluster-connect host:port` | a full URL, `https://host/?jwt=TOKEN` | +| `--cluster-mesh`, TOML `mesh` | removed; list every peer with `--cluster-connect` or `--cluster-connect-api` | | `moq --origin`, `--name`, `--latency-max` | `--hop`, `--broadcast`, `--max-age` | | `moq publish`, `moq subscribe` | `moq import`, `moq export` | | `moq token`, the `moq-token` binary | `moq auth` | @@ -121,9 +122,14 @@ Other changes to a deployment: the relay's client CA verifies, so keep that CA to cluster peers. - **`moq --listen` needs auth.** A CLI listener refuses to start without `--auth-url` or `--auth-public` instead of accepting everyone. -- **Other 0.14 auth differences kept.** A 0.14 peer that dials with a - cluster JWT no longer sees `.internal/origins` gossip; peers identify by - certificate or LAN path. An auth server's `root` alias may have any depth. +- **Gossip discovery is removed.** A relay dials only the peers it lists or + finds on the LAN, never a URL learned from an announcement, and no longer + announces `.internal/origins`. The `/nodes` endpoint lists only peers this + relay dialed. Until every relay that ran `--cluster-mesh` is upgraded, keep + client grants off `.internal/`: an older relay still dials any URL announced + there with `cluster.token`, and an upgraded peer still forwards it. +- **Other 0.14 auth differences kept.** Peers identify by certificate or LAN + path. An auth server's `root` alias may have any depth. A path in `--cluster-connect` is not refused, although it shifts the mesh frame. `moq auth serve --key` takes a file, not an https or JWKS URL. `moq auth sign --root` is the token root and JS `verify --root` the dialed diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 912be90e329..97d0760c1e4 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -109,7 +109,7 @@ It stands for an endpoint that did not negotiate this extension, and an endpoint Since any number of endpoints can be 0, it identifies nothing: - **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself and MUST NOT discard an advertisement merely because the path contains 0. -- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher. A receiver MUST NOT treat two such advertisements as interchangeable ({{selection}}). +- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher, which a relay names by putting a stamp of its own in front ({{stamping}}). A receiver MUST NOT treat two unstamped ones as interchangeable ({{selection}}). - **Filtering**: a peer that declared 0 gave the receiver nothing to filter that session on. The receiver MAY assign an ID of its own ({{assigned}}) as local selection state and MUST NOT write it into HOP_PATH. Duplicate *non-zero* Hop IDs in one HOP_PATH are a loop; duplicate zeros are not. @@ -121,14 +121,22 @@ It uses that ID as local selection state: as what it filters that session on, in The ID is the receiver's own, not the peer's, and MUST NOT be forwarded. An advertisement that arrives with its own HOP_PATH already names the sender there, as 0 if withheld. -A receiver writes 0 for an upstream that sent no HOP_PATH ({{bridging}}). +An unnamed publisher is stamped instead ({{stamping}}), which is not an assigned identity. An assigned ID MUST NOT be shared between peers not known to be the same endpoint. -Sharing one makes their content interchangeable ({{selection}}) and suppresses each one's advertisements to the other, so two unrelated publishers would be merged into one and starve each other of routes. +Sharing one suppresses each one's advertisements to the other, so two unrelated peers would starve each other of routes. -A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one stable ID, so its reconnects and redundant sessions are recognized as the same content; a fresh ID per connection would make one peer look like several. +A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one stable ID, so its reconnects and redundant sessions are filtered as one peer; a fresh ID per connection would make one peer look like several. An anonymous accepted session cannot be correlated with anything, so it SHOULD get a distinct ID per session: not an identity, but enough to keep routes learned from it from being advertised back to it, which is the loop 0 cannot prevent. +## Stamping an Unknown Publisher {#stamping} +A relay that records an advertisement whose first HOP_PATH entry is 0 MUST insert a random non-zero Hop ID in front of it, picked once for the session the advertisement arrived on. +One that arrived with no HOP_PATH ({{bridging}}) becomes that stamp followed by 0. + +Nothing on the wire says whether an unnamed publisher that reconnects is the same one, so a fresh stamp per session makes its reconnect a change of publisher downstream ({{updating}}), while an update on the same session keeps the stamp and applies in place. +The 0 behind the stamp keeps the path ranked below fully identified ones ({{selection}}), since the unnamed hop may hide any depth. +A stamp names a session, not a peer: it MUST NOT be reused across sessions or taken as the peer's identity. + # Namespace Advertisements {#namespace} HOP_PATH and ROUTE_COST are Key-Value-Pair parameters ({{moqt}} Section 2.5). @@ -191,7 +199,7 @@ Unknown, out-of-budget, and saturated routes are outside the guarantee: a receiv # Relay Behavior A relay forwarding an advertisement MUST append its own Hop ID to the HOP_PATH it received, so its ID is always the last entry. -A received 0 is forwarded unchanged. +A received 0 is forwarded unchanged, behind a stamp when it is the first entry ({{stamping}}). A relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. This check catches loops of any length and is the only loop defense required. @@ -199,7 +207,7 @@ A conforming sender never sends one ({{selection}}), so a receiver MAY close the ## Bridging {#bridging} An upstream that did not negotiate the extension sends no HOP_PATH. -The relay creates one with a single 0 entry for that upstream ({{zero}}), then appends its own Hop ID. +The relay creates one holding its stamp for that session followed by 0 ({{stamping}}), then appends its own Hop ID. The identity a receiver assigned that upstream ({{assigned}}) is local selection state and MUST NOT appear in HOP_PATH. ## Accumulating Cost {#accumulating} @@ -228,8 +236,9 @@ An advertisement lives as long as its stream, so an update on a new stream would An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session. An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. -If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. -If the publisher did change, the endpoint MUST withdraw the advertisement (PUBLISH_NAMESPACE_DONE or NAMESPACE_DONE) and advertise again rather than update in place. +If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary. +If the first entry changed, the publisher changed, and the endpoint still sends an ordinary update. +The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old publisher. The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. @@ -267,7 +276,7 @@ Under this extension an advertisement is a path, so a session advertises a names A receiver MAY still hold paths to several publishers of one namespace and choose between them as it sees fit: serve from the cheapest and move to the next when it fails. A refusal moves to another publisher only as {{selection}} allows: once, and only for NO_CAPACITY. -The advertised path and the served source stay the same publisher: a relay that moves to another MUST withdraw its advertisement and advertise the new path ({{updating}}), so the first Hop ID downstream always names the publisher whose Objects flow. +A relay that moves to another publisher MUST update its advertisement to the new path ({{updating}}), so the first Hop ID downstream names the publisher that new subscriptions reach. Moving between distinct publishers is a discontinuity: their groups are not one sequence, so a subscriber sees an unrelated Location, and a FETCH that succeeds against one may fail against the other. Redundant publishers of the same content avoid this by sharing a Hop ID ({{hop-ids}}), which makes their paths interchangeable and lets a subscription fail over at a group boundary. @@ -330,6 +339,8 @@ This document requests one registration in the "REQUEST_ERROR Codes" registry. ## moq-cluster-02 - Defined request resolution against the longest covering prefix and the NO_CAPACITY refusal with its single re-resolution; any other refusal is terminal, including between several publishers of one namespace. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. +- A change of original publisher is an ordinary update instead of a withdrawal and a new advertisement. Subscriptions already served drain the old source; new requests take the updated route. +- A relay puts a random Hop ID, picked per session, in front of an advertisement whose first HOP_PATH entry is 0, and writes that stamp followed by 0 for one with no HOP_PATH. ## moq-cluster-01 - Assigned identities are local selection state and MUST NOT be forwarded. diff --git a/drafts/draft-lcurley-moq-e2ee.md b/drafts/draft-lcurley-moq-e2ee.md index ec68f21aa9c..25ca49c8eac 100644 --- a/drafts/draft-lcurley-moq-e2ee.md +++ b/drafts/draft-lcurley-moq-e2ee.md @@ -227,7 +227,8 @@ An Object ID above `2^32-1` MUST be refused as `identity` before encryption or d ## Datagrams A datagram uses `domain = 0x01`, its 64-bit sequence as `group`, and `frame = 0`. -MoQ Transport has no datagram mapping in this profile; shared vectors cover grouped tracks on both transports and datagrams on moq-lite only. +On MoQ Transport, a datagram is an Object at ID 0 in an OBJECT_DATAGRAM whose Group ID is the sequence. +Shared vectors cover grouped tracks on both transports and datagrams on moq-lite only. ## Nonce The 96-bit AES-GCM nonce is: diff --git a/drafts/draft-lcurley-moq-hidden.md b/drafts/draft-lcurley-moq-hidden.md index ee1c14720ee..4f9089ccf43 100644 --- a/drafts/draft-lcurley-moq-hidden.md +++ b/drafts/draft-lcurley-moq-hidden.md @@ -24,7 +24,7 @@ informative: --- abstract This document defines an extension for MoQ Transport {{moqt}} that hides namespaces from discovery. -A namespace with a field starting with `.` below the prefix a subscriber asked for is left out of the advertisements it receives, unless its SUBSCRIBE_NAMESPACE opts in. +For peers that negotiate this extension, a namespace with a field starting with `.` below the prefix a subscriber asked for is left out of the advertisements it receives, unless its SUBSCRIBE_NAMESPACE opts in. A platform can then add internal namespaces, such as statistics, without them turning up in applications that list everything and use what they find. --- note_Note_to_Readers @@ -52,7 +52,7 @@ This extension reserves a leading `.` for such namespaces, as file systems do fo A hidden namespace is still published, routed, and subscribed to like any other; it is only left out of discovery by default. A subscriber that wants hidden namespaces too says so on the SUBSCRIBE_NAMESPACE that would list them. -The name alone decides: there is no publisher-side flag, so a namespace cannot be hidden from one subscriber and listed to another under the same prefix. +For peers that declare this extension, the namespace name and the requested prefix determine whether an opt-in is needed. # Setup Negotiation @@ -70,7 +70,7 @@ A receiver MUST ignore the value. An endpoint MUST NOT send the HIDDEN parameter to a peer that did not declare this option, because an unknown parameter fails decoding. A subscriber that wants hidden namespaces therefore waits for the peer's SETUP before sending SUBSCRIBE_NAMESPACE. -The rest of this extension applies whether or not the peer declared the option: a peer that never heard of it never opts in, so it is never told about hidden namespaces. +The filtering rules below apply only to peers that declared this option. A publisher MUST NOT hide namespaces from discovery solely because of a leading `.` when the peer did not declare it. Such peers receive all authorized namespaces, as in unextended MoQ Transport. # Opting In {#parameter} @@ -90,11 +90,12 @@ A receiver MUST close the session with a PROTOCOL_VIOLATION on any other value. # Advertising {#advertising} -A publisher SHOULD NOT advertise a hidden namespace in response to a SUBSCRIBE_NAMESPACE that did not opt in. +For a peer that declared the HIDDEN Setup Option, a publisher SHOULD NOT advertise a hidden namespace in response to a SUBSCRIBE_NAMESPACE that did not opt in. Hiding is a convenience for discovery, not access control, so a publisher MAY treat a subscriber it trusts, such as another relay in its own cluster, as opted in. -An unsolicited PUBLISH_NAMESPACE answers no prefix, so it is measured against the empty one: a publisher SHOULD NOT send one for a hidden namespace. +An unsolicited PUBLISH_NAMESPACE answers no prefix, so it is measured against the empty one: a publisher SHOULD NOT send one for a hidden namespace to a peer that declared the HIDDEN Setup Option. When unsolicited advertisements are live, a SUBSCRIBE_NAMESPACE is answered with only the namespaces they left out, which is to say those hidden from the empty prefix, that the subscription may see. +A peer that did not declare the option already receives all namespaces unsolicited, so its subscription adds no duplicate advertisements. That covers both an opt-in and a prefix that names a hidden field itself, and no namespace is advertised twice. Hiding narrows discovery and nothing else. @@ -133,6 +134,13 @@ Both values are even, so each is a bare varint. --- back +# Changelog + +## Since draft-lcurley-moq-hidden-00 (in progress) + +- Apply hidden filtering only to peers that declared the HIDDEN Setup Option. +- Measure visibility from the requested namespace prefix, independently of authorization scope. + # Acknowledgments {:numbered="false"} diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index cf6b4973293..7a018ff70a5 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -29,6 +29,7 @@ normative: date: false RFC3986: RFC6455: + RFC9000: RFC9002: informative: @@ -408,6 +409,9 @@ This is the only loop defense moq-lite requires, and it catches loops of any len A conforming sender never sends one (see below), so a receiver MAY instead close the session with a protocol violation; discarding is what keeps a mesh working when one member does not conform. A Hop ID of 0 means unknown and never matches anything; withholding an ID trades loop detection for privacy. A receiver MAY assign an identity of its own to a peer that declared 0, as local selection state for filtering that session; it MUST NOT forward that identity as a Hop ID. +A relay that records an announcement whose reconstructed path starts with 0 MUST insert a random non-zero Hop ID in front of it, picked once for the session it arrived on; an empty path becomes that stamp followed by 0. +Nothing on the wire says whether an unnamed publisher that reconnects is the same one, so its reconnect reads downstream as a new first hop, while an ANNOUNCE_UPDATE on the same session keeps the stamp. +The 0 behind the stamp keeps the path ranked below fully identified ones. A publisher MUST NOT advertise a path whose entries contain the Hop ID the subscriber declared in its SETUP (see [Hop Parameter](#hop-parameter)). The receiver can only discard it, and acting on it would form a loop, so sending one is never useful. @@ -679,6 +683,12 @@ A group whose frame does not fit is simply not eligible for datagram delivery. # Encoding This section covers the encoding of each message. +## Variable-Length Integers {#varint} +A field marked `(i)` is a variable-length integer. +moq-lite-07 uses the leading-ones encoding of [moqt]: the number of leading 1 bits in the first byte gives the length, from 1 byte carrying 7 bits to 9 bytes carrying 64, and every length is valid. +Earlier versions use the two-bit length prefix of [RFC9000], Section 16, which carries at most 2^62-1. +A relay that cannot encode a value for a peer on an earlier version MUST NOT truncate it. + ## Message Length Most messages are prefixed with a variable-length integer indicating the number of bytes in the message payload that follows. This length field does not include the length of the varint length itself. @@ -718,6 +728,8 @@ Setup Parameter { } ~~~ +The Message Length MUST NOT exceed 65,536 bytes; a receiver MUST treat a longer SETUP as a protocol violation and MAY reject it based on the length prefix alone. + **Parameter Count**: The number of Setup Parameters that follow. @@ -910,8 +922,8 @@ The responding publisher's own Hop ID is NOT included in the resolved list; it i When forwarding an announcement received from an upstream peer, a relay MUST append the upstream peer's ANNOUNCE_OK `Hop ID` to the resolved list, since that ID is no longer implicit downstream. The first entry of the reconstructed path identifies the endpoint that originated the route. A Hop ID value of 0 means the hop is unknown: either it was never assigned or a relay deliberately withholds it (see [Routing](#routing)). -A received 0 is forwarded unchanged. -When bridging an announcement from an upstream that sent no hop list, a relay writes 0 for that hop. +A received 0 is forwarded unchanged, behind a stamp when it is the first entry (see [Routing](#routing)). +When bridging an announcement from an upstream that sent no hop list, a relay writes its stamp followed by 0 for that hop. An identity a receiver assigned that upstream is local selection state and MUST NOT be forwarded as a Hop ID. A receiver MUST close the session with a PROTOCOL_VIOLATION if a non-zero Hop ID appears twice in the resolved list. @@ -1341,11 +1353,14 @@ The `Message Length` describes the payload size on the wire. - Made TRACK_INFO Publisher Max Age optional, encoded as milliseconds plus one with zero meaning no limit. - Assigned `moq-lite-07-wip` as this draft's protocol identifier until it is finalized as `moq-lite-07`. +- Switched every variable-length integer, including SETUP parameter values, from QUIC's two-bit length prefix to moq-transport's leading-ones encoding, widening the range to 64 bits. - Hid routes with a `.`-prefixed segment below the requested prefix from announce discovery, and added the ANNOUNCE_REQUEST `Hidden` field to opt in. - Added `Stream Count` to SUBSCRIBE_END: the number of Group Streams opened for the subscription. SUBSCRIBE_END is now sent once every counted Group Stream has opened, rather than as soon as the final group is known. - Removed SUBSCRIBE_DROP and its type 0x2; a group without a Group Stream is not counted. - The Subscribe Stream FIN now follows once every counted Group Stream has finished or been reset. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. +- Capped the SETUP Message Length at 65,536 bytes. +- A relay puts a random Hop ID, picked per session, in front of an announcement whose reconstructed path starts with 0, and writes that stamp followed by 0 for an empty path. ## moq-lite-06 diff --git a/drafts/justfile b/drafts/justfile index 547465396e7..bdb39c6e4df 100644 --- a/drafts/justfile +++ b/drafts/justfile @@ -5,92 +5,28 @@ # # The toolchain (kramdown-rfc, xml2rfc, mmark) comes from the nix dev shell # (see `draftsDeps` in flake.nix), so `nix develop --command just drafts build` -# renders with the same tool versions everywhere. There is no submodule or -# venv to bootstrap: `kramdown-rfc` turns the markdown into RFC XML, `xml2rfc` -# renders the txt/html. +# renders with the same tool versions everywhere. `kramdown-rfc` turns the +# markdown into RFC XML, `xml2rfc` renders the txt/html. set working-directory := '.' -# Common xml2rfc flags. --allow-local-file-access lets it read the CSS/refs. -xml2rfc := "xml2rfc -q --allow-local-file-access" - # List the draft names (the argument to `build` / `publish`). default: - @for f in draft-*.md; do echo "${f%.md}"; done + @ls draft-*.md | sed 's/\.md$//' -# Render one draft to .txt and .html (local editor's copy, -# gitignored). Renders the -latest docname as-is; use `publish` for a version. +# Render one draft to .txt and .html (local editor's copy, gitignored). build name: - kramdown-rfc --v3 < {{ name }}.md > {{ name }}.xml - {{ xml2rfc }} --text {{ name }}.xml -o {{ name }}.txt - {{ xml2rfc }} --html {{ name }}.xml -o {{ name }}.html - @echo "built {{ name }}.txt and {{ name }}.html" + ../sh/drafts/build.sh {{ name }} # Render every draft. all: - @for f in draft-*.md; do just build "${f%.md}"; done + ../sh/drafts/build.sh # Validate that every draft parses and that its generated XML passes validation. -# -# Both halves are needed. kramdown-rfc catches markdown and frontmatter errors, -# but happily emits XML for a cross-reference that points at no such section; -# xml2rfc is what rejects the dangling IDREF. Checking only the first half lets -# a broken `[text](#anchor)` pass here and then fail at `publish` time, which is -# the worst place to find it. -# -# --preptool stops after validation instead of rendering txt/html, and -N keeps -# it off the network (kramdown-rfc already inlined the references), which is -# what makes this a couple of seconds per draft rather than a minute. check: - bun install --frozen-lockfile --cwd .. - @grep -n "$(printf '\t')" draft-*.md; case $? in \ - 0) echo "tabs render unpredictably in xml2rfc; indent with spaces" >&2; exit 1;; \ - 1) ;; \ - *) exit 1;; \ - esac - @for f in draft-*.md; do \ - echo "checking $f"; \ - kramdown-rfc --v3 < "$f" > "${f%.md}.xml" || exit 1; \ - {{ xml2rfc }} --preptool -N "${f%.md}.xml" -o "${f%.md}.prepped.xml" \ - || { rm -f "${f%.md}.prepped.xml"; exit 1; }; \ - rm -f "${f%.md}.prepped.xml"; \ - done - @for f in moq-e2ee-*.ts; do \ - bun tsc --noEmit --skipLibCheck --target esnext --module esnext --moduleResolution bundler --types bun "$f" || exit 1; \ - bun "$f" || exit 1; \ - done - -# Remove generated files and the reference cache. -clean: - rm -f draft-*.xml draft-*.txt draft-*.html - rm -rf .refcache + ../sh/drafts/check.sh -# Submit a new draft version to the IETF datatracker. The datatracker emails -# the submitter a confirmation link; the submission is not final until that -# link is clicked. For a brand-new draft (-00) set "Replaces" on the -# confirmation page. -# Example: just drafts publish draft-lcurley-moq-lite 05 you@example.com +# Submit a new draft version to the IETF datatracker, e.g. +# `just drafts publish draft-lcurley-moq-lite 05 you@example.com`. publish name version email: - #!/usr/bin/env bash - set -euo pipefail - case "{{ version }}" in - [0-9][0-9]) ;; - *) echo "version must be two digits, e.g. 05" >&2; exit 1 ;; - esac - doc="{{ name }}-{{ version }}" - if [ ! -f "{{ name }}.md" ]; then - echo "no such draft: {{ name }}.md" >&2; exit 1 - fi - echo "Building $doc.xml" - sed "s/{{ name }}-latest/$doc/g" "{{ name }}.md" | kramdown-rfc --v3 > "$doc.xml" - echo "Submitting $doc.xml to the datatracker as {{ email }}" - resp="$(mktemp)" - code="$(curl -sS -o "$resp" -w '%{http_code}' \ - -F "user={{ email }}" -F "xml=@$doc.xml" \ - https://datatracker.ietf.org/api/submission)" - echo "HTTP $code" - cat "$resp"; echo; rm -f "$resp" - case "$code" in - 200|201) echo "Submitted. Check {{ email }} for the confirmation link." ;; - *) echo "Submission failed." >&2; exit 1 ;; - esac + ../sh/drafts/publish.sh {{ name }} {{ version }} {{ email }} diff --git a/flake.nix b/flake.nix index cbbd19cb38a..f60e34bbcbb 100644 --- a/flake.nix +++ b/flake.nix @@ -135,7 +135,7 @@ # unification would otherwise hide a broken single-crate build. cargo-hack cargo-nextest - # Browser/WASM bindings (rs/moq-wasm -> @moq/wasm via `just wasm`). + # Browser/WASM bindings (rs/moq-wasm -> @moq/wasm via `just js wasm`). # wasm-bindgen-cli must match the `wasm-bindgen` crate version (the # crate is pinned to nixpkgs' CLI version); bump both together. wasm-bindgen-cli @@ -245,10 +245,9 @@ ]; # Linters / formatters used by `just check` and `just fix`, which - # guard each tool with `command -v` so they skip silently when the - # binary isn't on $PATH. CI sets MOQ_STRICT=1, which turns that skip - # into an error (see `_tools` in the root justfile), so this list and - # that one have to stay in step. + # skip a module whose tools aren't on $PATH. CI sets MOQ_STRICT=1, + # which turns that skip into an error (see the tools map in + # sh/dispatch.sh), so this list and that one have to stay in step. lintDeps = with pkgs; [ shellcheck shfmt @@ -272,32 +271,33 @@ # 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.9.0+v0.32.0 -> uniffi 0.32), and it only understands - # metadata emitted by that uniffi, so it moves with the `uniffi` + # targets (v0.10.0-kixelated.1+v0.32.0 -> uniffi 0.32), and it only + # understands metadata emitted by that uniffi, so it moves with the `uniffi` # dependency in rs/moq-ffi/Cargo.toml. Five other places name the same # generator version and must be bumped together: the repo and revision # in release-go-ffi.yml, and the `cargo install` line in - # rs/moq-ffi/build.sh, go/ffi/README.md, go/scripts/check.sh, and - # go/scripts/stage.sh. + # rs/moq-ffi/build.sh, go/ffi/README.md, sh/go/check.sh, and + # sh/go/stage.sh. # # This points at a fork rather than NordSecurity because upstream has no # uniffi 0.32 generator: the metadata encoding changed in 0.32 even # though the contract version did not, so v0.7.1+v0.31.0 fails to read a # 0.32-built cdylib at all. The fork carries the port, tracked upstream - # as NordSecurity/uniffi-bindgen-go#96. Move back to NordSecurity once - # they tag a 0.32 release. + # as NordSecurity/uniffi-bindgen-go#96, and renders an enum error's + # exported Display as its Error(). Move back to NordSecurity once they + # tag a 0.32 release carrying both. uniffi-bindgen-go = pkgs.rustPlatform.buildRustPackage rec { pname = "uniffi-bindgen-go"; - version = "0.9.0+v0.32.0"; + version = "0.10.0-kixelated.1+v0.32.0"; src = pkgs.fetchFromGitHub { owner = "kixelated"; repo = "uniffi-bindgen-go"; rev = "v${version}"; - hash = "sha256-7Hli9SmLknZe5p7iGYsRNxmUL6ovKL2jhX62Z/79K4o="; + hash = "sha256-0DCIgHt4R5ndtLkeXw/KF500HidB13L2HeuS4eLvLHU="; }; - cargoHash = "sha256-ecpo/Z9hc3oPt/pF9Y+EB6SZANR8TDOJR6f/xSzJ9Uw="; + cargoHash = "sha256-wD+5Ghd4WFFQWAY2PXedXVPG+oPGozG9HbOhXB0fWco="; # The tag is a virtual workspace whose other members are uniffi test # fixtures. Building from the root would compile all of them, and CI @@ -323,13 +323,13 @@ # `-kixelated.N` pre-release so they never collide with upstream's. uniffi-bindgen-dart = pkgs.rustPlatform.buildRustPackage rec { pname = "uniffi-bindgen-dart"; - version = "0.3.1-kixelated.4+v0.32.0"; + version = "0.3.1-kixelated.5+v0.32.0"; src = pkgs.fetchFromGitHub { owner = "kixelated"; repo = "uniffi-dart"; rev = "v${version}"; - hash = "sha256-BCIooajAp0Wqt7LeanFSdmS/GT0uYo+d8Qv2jGWCJD8="; + hash = "sha256-MobLv4aov+ySk3X8bd6Sr5MLiXxCprkoFqEFt5xOerw="; }; # The upstream repository ignores Cargo.lock so cargo installs test @@ -530,6 +530,10 @@ ''; env = { + # What sh/dispatch.sh checks before a scoped `just check` or `just + # fix`. IN_NIX_SHELL would also pass inside another project's shell. + MOQ_DEV_SHELL = "1"; + # Where `just obs compile` and `just obs test` look for libobs. Set # on every platform so the plugin type-checks against the pinned OBS # release everywhere, rather than whatever the host happens to have. diff --git a/go/.gitignore b/go/.gitignore index 9d1c2961a27..4e2b41f06ea 100644 --- a/go/.gitignore +++ b/go/.gitignore @@ -1,4 +1,4 @@ -# Generated by scripts/{check,package-ffi}.sh; the main repo stays binary-free. +# Generated by sh/go/{check,package-ffi}.sh; the main repo stays binary-free. ffi/moq/moq.go ffi/moq/moq.h ffi/moq/lib/ diff --git a/go/ffi/README.md b/go/ffi/README.md index 23aae8b0253..6edaf6937e2 100644 --- a/go/ffi/README.md +++ b/go/ffi/README.md @@ -20,22 +20,22 @@ The published module ships prebuilt `libmoq_ffi.a` for `linux/amd64`, `linux/arm ## Local development -`go/scripts/stage.sh` builds `moq-ffi` for the host, runs `uniffi-bindgen-go` to regenerate `moq.go`, and stages this module plus the wrapper into `dist/` with the wrapper wired to the local ffi by a `replace`. It prints the two staged module directories, so anything that needs to build Go against this checkout (`go/scripts/check.sh`, `test/interop`) shares one staging path. +`sh/go/stage.sh` builds `moq-ffi` for the host, runs `uniffi-bindgen-go` to regenerate `moq.go`, and stages this module plus the wrapper into `dist/` with the wrapper wired to the local ffi by a `replace`. It prints the two staged module directories, so anything that needs to build Go against this checkout (`sh/go/check.sh`, `test/interop`) shares one staging path. -`go/scripts/check.sh` stages that way and then runs `go build`/`go vet`/`go test`. It also runs `publish-wrapper.test.sh`, which drives the wrapper publisher against a scratch bare repo (no cargo, no network). Run via `just go check`. Skips cleanly without `cargo`, `go`, or `uniffi-bindgen-go`. +`sh/go/check.sh` stages that way and then runs `go build`/`go vet`/`go test`. Run via `just go check`. Skips cleanly without `cargo`, `go`, or `uniffi-bindgen-go`. 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 \ --git https://github.com/kixelated/uniffi-bindgen-go \ - --rev v0.9.0+v0.32.0 \ + --rev v0.10.0-kixelated.1+v0.32.0 \ --locked ``` `--locked` matters: `uniffi_bindgen` depends on `toml` across a `>=0.9, <2` range, so a fresh resolve can pick a different `toml` than the generator was built against. -The revision is `v0.9.0+v0.32.0`, matching the `uniffi` version `rs/moq-ffi` depends on; `flake.nix` pins the same source. It points at a fork because upstream has no uniffi 0.32 release yet; `flake.nix` carries the details. Generated async calls take `context.Context` as the first argument. +The revision is `v0.10.0-kixelated.1+v0.32.0`, matching the `uniffi` version `rs/moq-ffi` depends on; `flake.nix` pins the same source. It points at a fork because upstream has no uniffi 0.32 release yet; `flake.nix` carries the details. Generated async calls take `context.Context` as the first argument. ## Layout @@ -49,8 +49,8 @@ go/ffi/ lib/_/libmoq_ffi.a (gitignored, staged at release time) ``` -Compiled binaries never live in the source tree. `scripts/check.sh` stages into the gitignored `dist/` working dir under the repo root; CI does the equivalent assembly into the [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) mirror. +Compiled binaries never live in the source tree. `sh/go/check.sh` stages into the gitignored `dist/` working dir under the repo root; CI does the equivalent assembly into the [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) mirror. ## Release -The `release-go-ffi.yml` workflow fires on every `moq-ffi-v*` tag, builds per-target static libraries, runs `uniffi-bindgen-go`, calls `go/scripts/package-ffi.sh` to assemble the module, and `go/scripts/publish-ffi.sh` to push the result to `moq-dev/moq-go-ffi` with a bare-semver tag (e.g. `v0.2.18`) lockstep with the crate. Go's module proxy picks up the new tag automatically. +The `release-go-ffi.yml` workflow fires on every `moq-ffi-v*` tag, builds per-target static libraries, runs `uniffi-bindgen-go`, calls `just go package-ffi` to assemble the module, and `just go publish-ffi` to push the result to `moq-dev/moq-go-ffi` with a bare-semver tag (e.g. `v0.2.18`) lockstep with the crate. Go's module proxy picks up the new tag automatically. diff --git a/go/ffi/moq/cgo.go b/go/ffi/moq/cgo.go index 64ed11c447a..f78a0171a8e 100644 --- a/go/ffi/moq/cgo.go +++ b/go/ffi/moq/cgo.go @@ -3,12 +3,12 @@ // moq.dev/moq wrapper, which builds on this package. // // The exported API is generated from rs/moq-ffi via uniffi-bindgen-go and -// dropped in alongside this file (moq.go) by scripts/package-ffi.sh; the in-tree -// source therefore does not build on its own. Run scripts/check.sh to stage a +// dropped in alongside this file (moq.go) by sh/go/package-ffi.sh; the in-tree +// source therefore does not build on its own. Run sh/go/check.sh to stage a // complete copy into dist/ and exercise it. // // The per-platform static archive is loaded from moq/lib/_/ -// inside the staged module, populated by scripts/package-ffi.sh from the release +// inside the staged module, populated by sh/go/package-ffi.sh from the release // build matrix. package moq diff --git a/go/justfile b/go/justfile index d842e27d103..b4fa2d0d07c 100644 --- a/go/justfile +++ b/go/justfile @@ -10,36 +10,41 @@ default: # Stages both the ffi and wrapper modules into dist/ (wiring the wrapper to the # local ffi via replace). Skips cleanly if cargo, go, or uniffi-bindgen-go is -# missing. -# -# This runs the tests too, so there is no separate `just go test`. Takes an -# optional newline-separated list of changed files and skips when none are -# Go-scoped; `just go check` (no FILES) always runs. +# missing. This runs the tests too, so there is no separate `just go test`. # Build moq-ffi, run uniffi-bindgen-go, then `go build`/`go vet`/`go test`. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '^(go/|rs/moq-ffi/)' <<< "$FILES"; then - echo "go: no Go changes; skipping." - exit 0 - fi - bash scripts/check.sh - -# Stage the in-tree go/ffi source + per-target moq-ffi libs + generated -# bindings into the moq.dev/moq-ffi module ready for publish. +check: + bash ../sh/go/check.sh + +# Release recipes run in the caller's directory, so a relative `--output` or +# `--tarball` means what it would to the script itself. + +# Stage the in-tree go/ffi source, per-target moq-ffi libs, and generated +# bindings into the moq.dev/moq-ffi module. + +# Stage the moq.dev/moq-ffi module for publish. +[no-cd] +[positional-arguments] package-ffi *args: - bash scripts/package-ffi.sh {{ args }} + {{ quote(justfile_directory() / "sh/go/package-ffi.sh") }} "$@" # Stage the in-tree go/wrapper source into the moq.dev/moq module, rewriting its -# moq.dev/moq-ffi require to the target ffi version, ready for publish. -package-wrapper *args: - bash scripts/package-wrapper.sh {{ args }} - -# The paths are the gitignored ones in go/.gitignore. `just go check` stages -# into the workspace dist/ instead, which `just js clean` sweeps, so these only -# show up when uniffi-bindgen-go or `go mod` is pointed at the tree directly. +# moq.dev/moq-ffi require to the target ffi version. -# Remove the generated bindings, native libs, and vendoring from go/. -clean: - rm -rf ffi/moq/moq.go ffi/moq/moq.h ffi/moq/lib ffi/go.sum ffi/vendor wrapper/go.sum wrapper/vendor +# Stage the moq.dev/moq wrapper module for publish. +[no-cd] +[positional-arguments] +package-wrapper *args: + {{ quote(justfile_directory() / "sh/go/package-wrapper.sh") }} "$@" + +# Push the staged moq-go-ffi module to the moq-dev/moq-go-ffi mirror. +[no-cd] +[positional-arguments] +publish-ffi *args: + {{ quote(justfile_directory() / "sh/go/publish-ffi.sh") }} "$@" + +# Push the staged moq-go wrapper module to the moq-dev/moq-go mirror. +[no-cd] +[positional-arguments] +publish-wrapper *args: + {{ quote(justfile_directory() / "sh/go/publish-wrapper.sh") }} "$@" diff --git a/go/wrapper/README.md b/go/wrapper/README.md index b3743abc41f..12c55234348 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -114,7 +114,7 @@ Raw tracks support best-effort datagrams alongside groups: `TrackProducer.Append sends one `Frame` and returns its sequence number, while `TrackConsumer.RecvDatagram` and `TrackConsumer.Datagrams` receive them in arrival order. Payloads are capped at 1200 bytes. Datagram delivery requires a datagram-capable transport and lite-05 or -newer moq-lite; IETF moq-transport, pre-lite-05, WebSocket, and TCP paths do not +newer moq-lite, or moq-transport; pre-lite-05, WebSocket, and TCP paths do not deliver them, and there is no stream fallback. ## Versioning @@ -125,4 +125,4 @@ The committed `go.mod` carries a `require moq.dev/moq-ffi v0.0.0` **placeholder* ## Local development -Run `just go check`: it builds `moq-ffi` for the host, regenerates the bindings, stages both modules into `dist/` with a `replace` wiring the wrapper to the local ffi, and runs `go build`/`go vet`/`go test`. It also runs `scripts/publish-wrapper.test.sh`, which exercises the publisher's release/no-op/recovery paths against a scratch bare repo standing in for the mirror. See [../ffi/README.md](../ffi/README.md) for the `uniffi-bindgen-go` install. +Run `just go check`: it builds `moq-ffi` for the host, regenerates the bindings, stages both modules into `dist/` with a `replace` wiring the wrapper to the local ffi, and runs `go build`/`go vet`/`go test`. See [../ffi/README.md](../ffi/README.md) for the `uniffi-bindgen-go` install. diff --git a/go/wrapper/errors_test.go b/go/wrapper/errors_test.go index aa5fe25d66d..360e8e98f60 100644 --- a/go/wrapper/errors_test.go +++ b/go/wrapper/errors_test.go @@ -30,6 +30,27 @@ func TestStreamAbortProtocolDetails(t *testing.T) { } } +func TestErrorMessage(t *testing.T) { + tests := []struct { + err error + want string + }{ + {ffi.NewMoqErrorClosed(), "closed"}, + {ffi.NewMoqErrorTransport("reset"), "transport: reset"}, + {ffi.NewMoqErrorProtocol(ffi.MoqProtocolError{ + Scope: ffi.MoqErrorScopeStream, + Code: 468, + Kind: ffi.MoqProtocolKindApp, + Message: "gone", + }), "gone"}, + } + for _, test := range tests { + if got := test.err.Error(); got != test.want { + t.Errorf("Error() = %q, want %q", got, test.want) + } + } +} + func TestErrorSentinels(t *testing.T) { tests := []struct { name string diff --git a/go/wrapper/go.mod b/go/wrapper/go.mod index e306de284d7..eba975c62c7 100644 --- a/go/wrapper/go.mod +++ b/go/wrapper/go.mod @@ -3,7 +3,7 @@ module moq.dev/moq go 1.23 // The require below is a placeholder. The real version is rewritten at release -// time by go/scripts/package-wrapper.sh to the latest published moq-ffi, and +// time by sh/go/package-wrapper.sh to the latest published moq-ffi, and // `just go check` injects a local `replace` to the freshly-generated bindings. // Do not "fix" this by hand or add a replace directive to the committed file. require moq.dev/moq-ffi v0.0.0 diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 99fcbedc3d7..f5db177a78c 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -193,7 +193,7 @@ func (b *BroadcastProducer) PublishContainerStream(format ContainerFormat) (*Con // EncodeAudio publishes a raw-audio track with an in-process encoder. // -// Select the codec with OpusAudioCodec (currently the only constructor). +// Select the codec with OpusAudioCodec or AacAudioCodec. // Pass bandwidth to reserve this track's bitrate against the session's // allocator so a co-resident video encoder sizes itself against what is left. func (b *BroadcastProducer) EncodeAudio(name string, input AudioEncoderInput, output AudioEncoderOutput, bandwidth *Bandwidth) (*AudioProducer, error) { diff --git a/go/wrapper/types.go b/go/wrapper/types.go index bb5c6399100..85c6274c4aa 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -8,14 +8,14 @@ import ffi "moq.dev/moq-ffi/moq" type ( // Audio describes one audio rendition in a broadcast catalog: codec, sample rate, channel count, and container. Audio = ffi.MoqAudio - // AudioCodec selects the audio encoder codec. Build one with OpusAudioCodec; + // AudioCodec selects the audio encoder codec. Build one with OpusAudioCodec or AacAudioCodec; // adding a codec later adds a constructor, not a breaking enum change. AudioCodec = ffi.MoqAudioCodec // AudioDecoderOutput configures the PCM format, sample rate, and channels DecodeAudio delivers. AudioDecoderOutput = ffi.MoqAudioDecoderOutput // AudioEncoderInput declares the PCM sample format, sample rate, and channel count of frames written to an audio producer. AudioEncoderInput = ffi.MoqAudioEncoderInput - // AudioEncoderOutput configures the Opus encoder: codec, optional sample rate, channels, bitrate, and frame duration. + // AudioEncoderOutput configures the encoder: codec, optional sample rate, channels, bitrate, and frame duration. AudioEncoderOutput = ffi.MoqAudioEncoderOutput // AudioSampleFormat is a raw PCM sample layout, mirroring WebCodecs AudioData.format. AudioSampleFormat = ffi.MoqAudioSampleFormat @@ -65,6 +65,7 @@ type ( // Subscription holds subscriber-side delivery preferences: priority, ordering, max age, and group range. Subscription = ffi.MoqSubscription // TrackInfo holds publisher-side track properties: priority, ordering, max age, and timescale. + // A zero Priority is the least urgent, not the default; set 127 for the midpoint a nil TrackInfo uses. TrackInfo = ffi.MoqTrackInfo // Video describes one catalog rendition, including whether the publisher recommends temporarily avoiding it. Video = ffi.MoqVideo @@ -203,6 +204,12 @@ func OpusAudioCodec() *AudioCodec { return ffi.MoqAudioCodecOpus() } +// AacAudioCodec selects AAC-LC through the platform's encoder for EncodeAudio. +// A host without one refuses it. Leave FrameDurationUs at 0 for AAC's own frame. +func AacAudioCodec() *AudioCodec { + return ffi.MoqAudioCodecAac() +} + // VideoPixelFormat values: the raw pixel layout fed to the in-process encoder, // and the one the in-process decoder delivers. const ( diff --git a/infra/rpm/publish.sh b/infra/rpm/publish.sh index d8a61ba1427..f8d2be9e37c 100755 --- a/infra/rpm/publish.sh +++ b/infra/rpm/publish.sh @@ -2,7 +2,8 @@ # # Regenerate yum/dnf repo metadata and push to the rpm-moq-dev R2 bucket. # Pull the current pool, merge in new .rpm files from $ARTIFACTS_DIR, -# rebuild repodata with createrepo_c, sign repomd.xml with GPG, and upload. +# sign every package, rebuild repodata with createrepo_c, sign repomd.xml +# with GPG, and upload. # # Required env: # ARTIFACTS_DIR directory containing new .rpm files to add @@ -12,7 +13,7 @@ # SIGNING_KEY ascii-armored GPG private key (shared with apt repo and maven publishing) # SIGNING_PASSWORD optional passphrase for SIGNING_KEY # -# Required tools: rclone, createrepo_c, gpg. +# Required tools: rclone, rpmsign, createrepo_c, gpg. set -euo pipefail @@ -86,11 +87,24 @@ if [[ ${#KEY_IDS[@]} -ne 1 ]]; then exit 1 fi KEY_ID="${KEY_IDS[0]}" +# Read the passphrase from a file so it never appears in a process list. GPG_PASS_ARGS=() if [[ -n "${SIGNING_PASSWORD:-}" ]]; then - GPG_PASS_ARGS=(--pinentry-mode loopback --passphrase "$SIGNING_PASSWORD") + printf '%s' "$SIGNING_PASSWORD" >"$GNUPGHOME/passphrase" + GPG_PASS_ARGS=(--pinentry-mode loopback --passphrase-file "$GNUPGHOME/passphrase") fi +# moq.repo sets gpgcheck=1, so dnf rejects any unsigned package. Sign the whole +# merged pool, not just the new artifacts: packages published before signing +# existed need it too. rpmsign skips any package already signed by this key, +# so only new or unsigned packages change and get re-uploaded. +echo ">> Sign packages..." +mapfile -t POOL < <(find "$WORK/${DIST}" -name '*.rpm') +rpmsign --addsign \ + --define "_gpg_name ${KEY_ID}" \ + --define "_gpg_sign_cmd_extra_args --batch ${GPG_PASS_ARGS[*]}" \ + "${POOL[@]}" + echo ">> Generate repodata per arch..." for arch in "${ARCHES[@]}"; do dir="$WORK/${DIST}/${arch}" diff --git a/js/auth/src/key.test.ts b/js/auth/src/key.test.ts index 663cfa4f181..bb4eb0fbd3a 100644 --- a/js/auth/src/key.test.ts +++ b/js/auth/src/key.test.ts @@ -4,7 +4,7 @@ import { exportJWK, generateKeyPair, SignJWT } from "jose"; import type { Algorithm } from "./algorithm.ts"; import { authorize, type Claims } from "./claims.ts"; import { INSECURE_TEST_RS256_OTHER, INSECURE_TEST_RSA_KEYS } from "./insecure-test-keys.ts"; -import { Key } from "./key.ts"; +import { Key, KeyIdSchema } from "./key.ts"; // Helper function to encode JSON to base64url function encodeJwk(obj: unknown): string { @@ -811,3 +811,15 @@ test("verify - enforces not before", async () => { expect((await Key.verify(key, await signRaw({ publish: ["**"], nbf: now - 60 }))).nbf).toBe(now - 60); await expect(Key.verify(key, await signRaw({ publish: ["**"], nbf: now + 3600 }))).rejects.toThrow(); }); + +test("key IDs share Rust's grammar and 128-character limit", async () => { + for (const kid of ["a", "A0_-", "a".repeat(128)]) { + expect(KeyIdSchema.parse(kid)).toBe(kid); + expect(Key.parse(JSON.stringify({ ...testKey, kid })).kid).toBe(kid); + } + for (const kid of ["", "bad.key", "é", "a".repeat(129)]) { + expect(KeyIdSchema.safeParse(kid).success).toBe(false); + expect(() => Key.parse(JSON.stringify({ ...testKey, kid }))).toThrow(); + } + await expect(Key.generate("HS256", "a".repeat(129))).rejects.toThrow(); +}); diff --git a/js/auth/src/key.ts b/js/auth/src/key.ts index 120d9f657d7..d546ec398de 100644 --- a/js/auth/src/key.ts +++ b/js/auth/src/key.ts @@ -6,9 +6,10 @@ import { type Claims, ClaimsSchema, ScopeSchema, scopeAllows } from "./claims.ts import { encodeGrants } from "./wire.ts"; /** - * A validated key identifier (kid). Only alphanumeric, hyphens, and underscores. + * A validated key identifier (kid). At most 128 alphanumeric, hyphen, or underscore characters. */ export const KeyIdSchema = z.string().check( + z.maxLength(128), z.refine((value) => /^[A-Za-z0-9_-]+$/.test(value), { message: "Key ID must contain only alphanumeric characters, hyphens, and underscores", }), diff --git a/js/common/workers.test.ts b/js/common/workers.test.ts deleted file mode 100644 index 5b11c5e1fba..00000000000 --- a/js/common/workers.test.ts +++ /dev/null @@ -1,45 +0,0 @@ -import { expect, test } from "bun:test"; -import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join, resolve } from "node:path"; - -test("worker checks select changed projects and propagate build failures", () => { - const temp = mkdtempSync(join(tmpdir(), "moq-workers-")); - const log = join(temp, "calls"); - writeFileSync( - join(temp, "bun"), - '#!/bin/sh\nprintf "%s %s\\n" "$PWD" "$*" >> "$WORKER_TEST_LOG"\nif [ "$*" = "run deploy --dry-run" ]; then exit "$WORKER_TEST_EXIT"; fi\n', - { mode: 0o755 }, - ); - try { - for (const project of ["infra/apt", "infra/rpm", "demo/pub"]) { - writeFileSync(log, ""); - const result = Bun.spawnSync(["just", "js", "check", `${project}/bun.lock`], { - cwd: resolve(import.meta.dir, "../.."), - env: { - ...process.env, - PATH: `${temp}:${process.env.PATH}`, - WORKER_TEST_LOG: log, - WORKER_TEST_EXIT: "0", - }, - }); - expect(result.exitCode).toBe(0); - expect(readFileSync(log, "utf8").trim().split("\n")).toEqual([ - `${resolve(import.meta.dir, "../..", project)} install --frozen-lockfile`, - `${resolve(import.meta.dir, "../..", project)} run deploy --dry-run`, - ]); - } - const failed = Bun.spawnSync(["just", "js", "check", "infra/apt/bun.lock"], { - cwd: resolve(import.meta.dir, "../.."), - env: { - ...process.env, - PATH: `${temp}:${process.env.PATH}`, - WORKER_TEST_LOG: log, - WORKER_TEST_EXIT: "1", - }, - }); - expect(failed.exitCode).not.toBe(0); - } finally { - rmSync(temp, { recursive: true, force: true }); - } -}); diff --git a/js/hang/bench/slow-group.ts b/js/hang/bench/slow-group.ts new file mode 100644 index 00000000000..68773f203eb --- /dev/null +++ b/js/hang/bench/slow-group.ts @@ -0,0 +1,42 @@ +// Run with `bun js/hang/bench/slow-group.ts` to measure warning traffic per catch-up. +import { Group, Time, Track, Varint } from "@moq/net"; +import { Signal } from "@moq/signals"; +import { Consumer } from "../src/container/consumer.ts"; +import { Format } from "../src/container/legacy.ts"; + +for (const count of [1, 16, 256, 1024]) { + const track = new Track.Producer("tone"); + const maxAge = new Signal(Time.Milli(30_000)); + const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(30_000) }), { + format: new Format("data"), + maxAge, + }); + const write = (sequence: number) => { + const group = new Group.Producer(sequence); + group.writeFrame({ payload: Varint.encode(sequence * 1000), timestamp: Time.Timestamp.now() }); + track.writeGroup(group); + }; + const buffered = async (timestamp: number) => { + while (consumer.buffered.peek().at(-1)?.end !== timestamp) await consumer.buffered.changed(); + }; + let warnings = 0; + let bytes = 0; + const warn = console.warn; + console.warn = (...args: unknown[]) => { + warnings++; + bytes += JSON.stringify(args).length; + }; + try { + for (let i = 0; i < count; i++) write(i); + await buffered(count - 1); + maxAge.set(Time.Milli.zero); + const started = performance.now(); + write(count); + await buffered(count); + console.log(JSON.stringify({ groups: count, warnings, bytes, catchupMs: performance.now() - started })); + } finally { + consumer.close(); + track.close(); + console.warn = warn; + } +} diff --git a/js/hang/src/container/cmaf/encode.test.ts b/js/hang/src/container/cmaf/encode.test.ts index 6f293404595..91efdd0ff0e 100644 --- a/js/hang/src/container/cmaf/encode.test.ts +++ b/js/hang/src/container/cmaf/encode.test.ts @@ -1,6 +1,7 @@ import { expect, test } from "bun:test"; import { readIsoBoxes, readTrun, type TrackRunBox } from "@svta/cml-iso-bmff"; -import { encodeDataSegment } from "./encode.ts"; +import { u53 } from "../../catalog/integers.ts"; +import { createAudioInitSegment, encodeDataSegment } from "./encode.ts"; for (const kind of ["audio", "video"] as const) { for (const keyframe of [false, true]) { @@ -23,3 +24,18 @@ for (const kind of ["audio", "video"] as const) { }); } } + +test("opus init segment without a description trims no pre-skip", () => { + const init = createAudioInitSegment({ + codec: "opus", + sampleRate: u53(48_000), + numberOfChannels: u53(2), + container: { kind: "legacy" }, + }); + const at = new TextDecoder().decode(init).indexOf("dOps"); + expect(at).toBeGreaterThan(0); + // dOps payload: version (1), channel count (1), pre-skip (2, big-endian). + const dops = new DataView(init.buffer, init.byteOffset + at + 4, 4); + expect(dops.getUint8(1)).toBe(2); + expect(dops.getUint16(2, false)).toBe(0); +}); diff --git a/js/hang/src/container/cmaf/encode.ts b/js/hang/src/container/cmaf/encode.ts index 9831b61083e..3c676d8cba9 100644 --- a/js/hang/src/container/cmaf/encode.ts +++ b/js/hang/src/container/cmaf/encode.ts @@ -873,8 +873,8 @@ function createDOpsBox(channelCount: number, sampleRate: number, description?: s dOps[offset++] = 0; // Version dOps[offset++] = channelCount; - view.setUint16(offset, 312, false); - offset += 2; // PreSkip (typical value) + view.setUint16(offset, 0, false); + offset += 2; // PreSkip: unknown without an OpusHead, so trim nothing, like the Rust exporter view.setUint32(offset, sampleRate, false); offset += 4; // InputSampleRate view.setInt16(offset, 0, false); diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts new file mode 100644 index 00000000000..dc845c47a4c --- /dev/null +++ b/js/hang/src/container/consumer.skips.test.ts @@ -0,0 +1,51 @@ +import { expect, spyOn, test } from "bun:test"; +import { Group, Time, Track, Varint } from "@moq/net"; +import { Signal } from "@moq/signals"; +import { Consumer } from "./consumer.ts"; +import { Format } from "./legacy.ts"; + +for (const count of [1, 16, 256]) { + test(`Consumer summarizes ${count} skipped groups once per catch-up`, async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("tone"); + const maxAge = new Signal(Time.Milli(30_000)); + const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(30_000) }), { + format: new Format("data"), + maxAge, + }); + const write = (sequence: number, timestamp: number) => { + const group = new Group.Producer(sequence); + group.writeFrame({ payload: Varint.encode(timestamp), timestamp: Time.Timestamp.now() }); + track.writeGroup(group); + return group; + }; + const buffered = async (timestamp: number) => { + while (consumer.buffered.peek().at(-1)?.end !== timestamp) await consumer.buffered.changed(); + }; + try { + // Sparse sequence numbers make the count differ from the sequence range. + for (let i = 0; i < count; i++) write(i * 2, i * 1000); + await buffered(count - 1); + expect(warn).not.toHaveBeenCalled(); + maxAge.set(Time.Milli.zero); + const newest = write(count * 2, count * 1000); + await buffered(count); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn).toHaveBeenLastCalledWith(`skipping slow groups: track=tone 0 -> ${count * 2} count=${count}`); + expect(consumer.buffered.peek()[0]?.start).toBe(Time.Milli(count)); + // The retained group is still delivered, and another catch-up reports separately. + expect((await consumer.next())?.group).toBe(count * 2); + newest.writeFrame({ payload: Varint.encode(count * 1000), timestamp: Time.Timestamp.now() }); + write(count * 2 + 2, (count + 1) * 1000); + await buffered(count + 1); + expect(warn).toHaveBeenCalledTimes(2); + expect(warn).toHaveBeenLastCalledWith( + `skipping slow groups: track=tone ${count * 2} -> ${count * 2 + 2} count=1`, + ); + } finally { + consumer.close(); + track.close(); + warn.mockRestore(); + } + }); +} diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 912ada6fc76..6996e9c920d 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -140,8 +140,8 @@ export class Consumer { // Arriving below the delivery cursor is not a reason to drop a group. Groups are // sent newest-first, so the head of a subscription arrives after the live edge it - // was served alongside, and both consumers can still place one: audio writes into - // a timestamp-indexed ring, video drops a late frame at render. How far back one + // was served alongside. Audio can place older groups in its timestamp-indexed ring; + // video must reject older groups before decode to preserve codec references. How far back one // may be is the subscription's own max age, applied before it ever reaches here. const group: Group = { consumer, @@ -304,7 +304,8 @@ export class Consumer { #checkMaxAge() { if (this.#active === undefined) return; - let skipped = false; + let skipped = 0; + const start = this.#groups[0]?.consumer.sequence; let hole = false; // Keep skipping the oldest group while the buffered span exceeds the max age. @@ -333,9 +334,6 @@ export class Consumer { this.#groups.shift(); this.#active = this.#groups[0]?.consumer.sequence; - console.warn( - `skipping slow group: track=${this.#track.name} ${first.consumer.sequence} -> ${this.#active}`, - ); const nextStart = this.#groups[0]?.frames.at(0)?.timestamp ?? this.#groups[0]?.end; const marker = !first.empty && !first.media; @@ -344,13 +342,16 @@ export class Consumer { } first.consumer.close(); first.frames.length = 0; - skipped = true; + skipped++; this.#gap = true; } if (hole) this.#markPlayhead(); if (skipped) { + console.warn( + `skipping slow groups: track=${this.#track.name} ${start} -> ${this.#active} count=${skipped}`, + ); this.#updateBuffered(); // Wake up any consumers waiting for a new frame. diff --git a/js/hang/src/util/aac.test.ts b/js/hang/src/util/aac.test.ts index c31059ec80f..50dfe903ad9 100644 --- a/js/hang/src/util/aac.test.ts +++ b/js/hang/src/util/aac.test.ts @@ -48,9 +48,11 @@ describe("audioSpecificConfig", () => { expect(audioSpecificConfig(48000, 8)).toEqual(new Uint8Array([0x11, 0xb8])); }); - // Unsupported channel counts fall back to stereo (config 2). - it("unsupported channel count falls back to stereo", () => { - expect(audioSpecificConfig(48000, 7)).toEqual(audioSpecificConfig(48000, 2)); + // A count with no channel configuration is refused rather than described as stereo. + it("refuses a channel count with no configuration", () => { + for (const count of [0, 7, 9]) { + expect(() => audioSpecificConfig(48000, count)).toThrow(); + } }); // Non-table sample rates use the 5-byte explicit-frequency form (freqIndex 0xF). diff --git a/js/hang/src/util/aac.ts b/js/hang/src/util/aac.ts index f417e4c0bdb..ca0cc2fd45b 100644 --- a/js/hang/src/util/aac.ts +++ b/js/hang/src/util/aac.ts @@ -45,19 +45,19 @@ export function pickRate(rate: number): number { const AAC_LC = 2; // audioObjectType for AAC-LC // Map a channel count to its AAC channelConfiguration (ISO 14496-3 Table 1.19). Configs 1..=6 are -// identity (5.1 is config 6 / 6 channels); 8 channels is config 7 (7.1). Anything else has no valid -// config, so fall back to stereo (matching the Rust muxer in rs/moq-mux/src/codec/aac). +// identity (5.1 is config 6 / 6 channels); 8 channels is config 7 (7.1). Anything else has no +// config, and describing it as stereo would mislabel every channel past the first two. function channelConfig(channelCount: number): number { - if (channelCount >= 1 && channelCount <= 6) return channelCount; + if (Number.isInteger(channelCount) && channelCount >= 1 && channelCount <= 6) return channelCount; if (channelCount === 8) return 7; - return 2; + throw new Error(`no AAC channel configuration for ${channelCount} channels`); } /** * Build the AAC-LC AudioSpecificConfig that decoders need when frames are raw (no ADTS header). * * Standard sample rates produce the 2-byte form; non-table rates fall back to the 5-byte form - * with an explicit 24-bit frequency. Mirrors the Rust muxer so JS and Rust agree on the bytes. + * with an explicit 24-bit frequency. Throws for a channel count no configuration names. */ export function audioSpecificConfig(sampleRate: number, channelCount: number): Uint8Array { const config = channelConfig(channelCount); diff --git a/js/json/src/snapshot/encoder.ts b/js/json/src/snapshot/encoder.ts index 82800aa9395..f42ec058142 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -13,6 +13,10 @@ const MAX_DELTA_FRAMES = 256; // entrypoint: the Producer needs it to know whether to hold a group open, nothing else does. export const DEFAULT_DELTA_RATIO = 8; +// Bytes a group may hold before it rolls when {@link Config.maxGroupBytes} is left unset: moq-net's +// per-group cache limit. Not re-exported from the package entrypoint; a test pins it to that limit. +export const DEFAULT_MAX_GROUP_BYTES = Group.MAX_GROUP_CACHE_BYTES; + /** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */ export interface Config { // Controls how aggressively the encoder emits deltas (merge patches) instead of full snapshots. @@ -45,7 +49,7 @@ export interface Config { /** * Bytes a group may hold before it rolls, defaulting to moq-net's per-group cache limit. Lets a - * test reach the limit without megabytes of JSON. + * test reach the limit without megabytes of JSON. Must fit the snapshot's own frame. * * @internal */ @@ -149,7 +153,7 @@ export class Encoder { constructor(config: Config = {}) { this.#config = config; this.#compress = isDeflate(config.compression); - this.#maxGroupBytes = config.maxGroupBytes ?? Group.MAX_GROUP_CACHE_BYTES; + this.#maxGroupBytes = config.maxGroupBytes ?? DEFAULT_MAX_GROUP_BYTES; } /** diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 668ddf7fac6..8b2f3457c6a 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -1,7 +1,7 @@ import { expect, test } from "bun:test"; import { Group, Error as NetError, StreamCode, Time, Track } from "@moq/net"; import { Consumer } from "./consumer.ts"; -import { Encoder } from "./encoder.ts"; +import { DEFAULT_MAX_GROUP_BYTES, Encoder } from "./encoder.ts"; import { Producer } from "./producer.ts"; type Value = Record; @@ -331,19 +331,24 @@ test("a rejected update leaves the previous value readable", async () => { expect(await drain(track.subscribe())).toEqual([{ keep: true }]); }); +test("the default group budget is moq-net's group cache limit", () => { + // The tests below shrink the budget, so pin the default they stand in for. + expect(DEFAULT_MAX_GROUP_BYTES).toBe(Group.MAX_GROUP_CACHE_BYTES); +}); + test("a delta that would overflow the snapshot rolls a new one instead", async () => { // A delta is only readable while its group still holds the snapshot it applies to. A patch - // that pushes the group past the cache would abort it, leaving a late subscriber with no + // that pushes the group past the budget would abort it, leaving a late subscriber with no // value. Mirrors the cumulative check in the Rust encoder. // - // The value is replaced rather than grown, so each snapshot fits the cache on its own while the + // The value is replaced rather than grown, so each snapshot fits the budget on its own while the // snapshot plus the patch that rewrites it does not. - const half = Math.floor(Group.MAX_GROUP_CACHE_BYTES * 0.6); + const size = 40; const track = new Track.Producer("test"); - const producer = new Producer({ track }); + const producer = new Producer({ track, maxGroupBytes: 64 }); - producer.update({ v: "x".repeat(half) }); - producer.update({ v: "y".repeat(half) }); + producer.update({ v: "x".repeat(size) }); + producer.update({ v: "y".repeat(size) }); producer.finish(); // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. @@ -354,7 +359,7 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( // The newest value is readable with no earlier frame to apply it to. const values = await drain(track.subscribe({ maxAge: REPLAY_LATENCY })); - expect(values[values.length - 1]).toEqual({ v: "y".repeat(half) }); + expect(values[values.length - 1]).toEqual({ v: "y".repeat(size) }); }); test("a compressed delta is gated on its encoded size, not its plaintext", async () => { diff --git a/js/justfile b/js/justfile index 4be426446e8..7118f097734 100644 --- a/js/justfile +++ b/js/justfile @@ -6,108 +6,53 @@ set working-directory := '.' -# Paths a JS check depends on: every bun workspace (they are not all under js/, -# see the root package.json) plus the config shared by all of them. `check`, -# `fix`, and `ci` all skip themselves when a diff misses this. -scope := '^(js/|doc/|drafts/|demo/(boy|web)/|test/interop/clients/js|test/wasm/|package\.json$|bun\.lock(b)?$|biome\.jsonc$)' - # Run all checks by default. default: just check -install: - bun install - -# Takes an optional newline-separated list of changed files and skips if none -# match the JS scope; `just js check` (no FILES) always runs. -# -# FILES is an exported parameter, not `{{ FILES }}`: just interpolates the -# latter into the recipe source, where a filename like `$(...)` would run as a -# command. Git-derived paths are untrusted input, so they stay data. - # `build` runs here rather than as its own gate: the per-package `check` script # is `tsc --noEmit`, which never runs declaration emit, so the errors that only # surface when emitting a `.d.ts` (TS4023 and friends) pass `check` and then # break a JSR/npm publish. It costs about 20s for every package. - +# # `common/deps.ts` runs first and cheaply: bundlers resolve an undeclared # workspace import through hoisting, so nothing else in `check` notices one. +# doc/ is in scope, so the binding pages' stats fields are checked here too. # Lint, type-check, biome-format, and build all packages. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - # These Workers have independent lockfiles outside the Bun workspace. - # Validate the deploy bundle without publishing or requiring credentials. - for project in infra/apt infra/rpm demo/pub; do - if [[ -z "$FILES" ]] || grep -qE "^($project/|js/justfile$)" <<< "$FILES"; then - ( - cd "../$project" - bun install --frozen-lockfile - bun run deploy --dry-run - ) - fi - done - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "js: no JS changes; skipping." - exit 0 - fi - # doc/ is in this scope, so the binding pages are checked here. - python3 ../rs/scripts/stats-docs.py +check: + python3 ../sh/rs/stats-docs.py bun install --frozen-lockfile bun common/deps.ts - if tty -s; then - bun run --filter='*' --elide-lines=0 check - else - bun run --filter='*' check - fi + bun run --filter='*' --elide-lines=0 check bun biome check just build -# Auto-fix lint and formatting issues. Skips on the same terms as `check`. -fix $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "js: no JS changes; skipping." - exit 0 - fi +# Validate the Worker deploy bundles outside the Bun workspace. +workers: + ../sh/js/workers.sh + +# Auto-fix lint and formatting issues. +fix: bun install bun biome check --write -# Run all unit tests. Skips on the same terms as `check`. -test $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "js: no JS changes; skipping tests." - exit 0 - fi +# Run all unit tests. +test: + bun install --frozen-lockfile + bun test common/declarations.test.ts common/deps.test.ts + bun run --filter='*' --elide-lines=0 test + +# Run one net benchmark: broadcasts, forward, reader, frames, track, varint, or lite-varint. +bench name: bun install --frozen-lockfile - bun test common/declarations.test.ts common/deps.test.ts common/workers.test.ts - if tty -s; then - bun run --filter='*' --elide-lines=0 test - else - bun run --filter='*' test - fi + bun net/bench/{{ name }}.ts # Build all packages. build: bun run --filter='*' build -# Remove node_modules and build output. The bun workspace spans the repo - -# (deps hoist to the root, not into js/), so sweep from the workspace root. -clean: - #!/usr/bin/env bash - set -euo pipefail - cd .. - find . -name .claude -prune -o \ - -type d \( -name node_modules -o -name dist -o -name out -o -name pkg \) \ - -prune -exec rm -rf {} + - find . -name .claude -prune -o -type f -name '*.tsbuildinfo' -exec rm -f {} + - -# Pull in new versions and report what's outdated. -update: - bun update - bun outdated +# Build browser/WASM bindings into @moq/wasm using the pinned wasm-bindgen toolchain. +wasm: + cargo build --locked -p moq-wasm --target wasm32-unknown-unknown --profile wasm-release + wasm-bindgen --target web --out-name moq --out-dir wasm/dist "${CARGO_TARGET_DIR:-../target}/wasm32-unknown-unknown/wasm-release/moq_wasm.wasm" diff --git a/js/net/bench/frames.ts b/js/net/bench/frames.ts index 34752d52625..bff942ce72c 100644 --- a/js/net/bench/frames.ts +++ b/js/net/bench/frames.ts @@ -7,6 +7,7 @@ import { Subscribe, SubscribeOk } from "../src/ietf/subscribe.ts"; import { Subscriber as IetfSubscriber } from "../src/ietf/subscriber.ts"; import { ALPN, Version as IetfVersion } from "../src/ietf/version.ts"; import { readFrames } from "../src/lite/group.ts"; +import { Version as LiteVersion } from "../src/lite/version.ts"; import { createMockTransportPair } from "../src/mock.ts"; import * as Path from "../src/path.ts"; import { Reader, Stream } from "../src/stream.ts"; @@ -48,7 +49,9 @@ const lite: Protocol = { async subscribe() { const open: Open = (stream) => { const producer = new Producer(0); - const done = readFrames(new Reader(stream), producer, 1_000_000).then(() => producer.close()); + const done = readFrames(new Reader(stream, undefined, LiteVersion.DRAFT_06), producer, 1_000_000).then(() => + producer.close(), + ); return { group: Promise.resolve(producer.consume()), done }; }; return { open, close: () => {} }; diff --git a/js/net/bench/lite-varint.ts b/js/net/bench/lite-varint.ts new file mode 100644 index 00000000000..4338a448e55 --- /dev/null +++ b/js/net/bench/lite-varint.ts @@ -0,0 +1,146 @@ +/** Lite-07 leading-ones varints against lite-06 QUIC varints, for what a publisher writes per frame, group, and request. */ +import { randomHop } from "../src/hop.ts"; +import { Datagram } from "../src/lite/datagram.ts"; +import { Group } from "../src/lite/group.ts"; +import { ProbeLevel, Setup } from "../src/lite/setup.ts"; +import { Subscribe } from "../src/lite/subscribe.ts"; +import { Version } from "../src/lite/version.ts"; +import * as Path from "../src/path.ts"; +import { type Cursor, Reader, Writer } from "../src/stream.ts"; + +const versions = [Version.DRAFT_06, Version.DRAFT_07]; +const minMs = 200; // Run each case at least this long. +let checksum = 0; + +/** A lite object: how the publisher writes it and how the subscriber reads it back. */ +interface Sample { + name: string; + encode(w: Writer, version: Version): Promise; + decode(r: Reader, version: Version): Promise; +} + +// A FRAME header: the zigzag timestamp delta, then the size. +const header = (c: Cursor) => { + c.u62(); + return c.u53(); +}; + +// FRAME headers with the payloads left out, as (timestamp delta in µs, size) pairs. +function frames(name: string, headers: [bigint, number][]): Sample { + const zigzag = (d: bigint) => (d << 1n) ^ (d >> 63n); + return { + name, + async encode(w) { + for (const [delta, size] of headers) { + await w.u62(zigzag(delta)); + await w.u53(size); + } + }, + async decode(r) { + // The subscriber's read loop, one synchronous decode per buffered frame, minus the payload. + let n = 0; + while (r.tryDecode(header) !== undefined) n++; + return n; + }, + }; +} + +const video = frames( + "Video", + Array.from({ length: 60 }, (_, n): [bigint, number] => { + if (n === 0) return [0n, 60_000]; + return [33_333n, n % 10 === 0 ? 17_000 : 8_000]; + }), +); +const audio = frames( + "Audio", + Array.from({ length: 50 }, (_, n): [bigint, number] => [n === 0 ? 0n : 20_000n, 160]), +); + +const group: Sample = { + name: "Group", + encode: (w, version) => new Group({ subscribe: 3n, sequence: 1_234 }).encode(w, version), + decode: (r, version) => Group.decode(r, version), +}; + +const subscribe: Sample = { + name: "Subscribe", + encode: (w, version) => + new Subscribe({ + id: 3n, + broadcast: Path.from("room/alice"), + track: "video", + priority: 2, + maxAge: 10_000, + }).encode(w, version), + decode: (r, version) => Subscribe.decode(r, version), +}; + +const datagram: Sample = { + name: "Datagram", + encode: (w, version) => w.write(new Datagram(3n, 1_234, 1_234_567_890, new Uint8Array()).encode(version)), + decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version)), +}; + +const hop = randomHop(); +const setup: Sample = { + name: "Setup", + encode: (w, version) => new Setup({ probe: ProbeLevel.Report, hop }).encode(w, version), + decode: (r, version) => Setup.decode(r, version), +}; + +/** Collect what one encode writes. */ +async function wire(sample: Sample, version: Version): Promise { + const chunks: Uint8Array[] = []; + const w = new Writer(new WritableStream({ write: (c) => void chunks.push(c.slice()) }), version); + await sample.encode(w, version); + w.close(); + await w.closed; + const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0)); + let offset = 0; + for (const c of chunks) { + out.set(c, offset); + offset += c.byteLength; + } + return out; +} + +/** Time `f` until `minMs` has passed, returning ns per call. */ +async function time(f: () => Promise): Promise { + for (let i = 0; i < 1_000; i++) await f(); // warm up + let calls = 0; + const start = performance.now(); + let elapsed = 0; + while (elapsed < minMs) { + for (let i = 0; i < 1_000; i++) await f(); + calls += 1_000; + elapsed = performance.now() - start; + } + return (elapsed * 1e6) / calls; +} + +// A Writer whose sink discards, so encode is timed without collecting bytes. +const sink = () => + new WritableStream({ + write: (c) => { + checksum += c.byteLength; + }, + }); + +console.log("sample,version,bytes,encode_ns,decode_ns"); +for (const sample of [video, audio, group, subscribe, datagram, setup]) { + for (const version of versions) { + const bytes = await wire(sample, version); + const encode = await time(async () => { + const w = new Writer(sink(), version); + await sample.encode(w, version); + }); + const decode = await time(async () => { + checksum += Number((await sample.decode(new Reader(undefined, bytes, version), version)) !== undefined); + }); + console.log( + `${sample.name},${version.toString(16)},${bytes.byteLength},${encode.toFixed(0)},${decode.toFixed(0)}`, + ); + } +} +if (checksum === 0) throw new Error("benchmark did no work"); diff --git a/js/net/bench/reader.ts b/js/net/bench/reader.ts index 76eac2e4c99..acdede13c64 100644 --- a/js/net/bench/reader.ts +++ b/js/net/bench/reader.ts @@ -1,4 +1,5 @@ /** Sweep frame size and chunk size for one Reader.read of a fragmented frame. */ +import { Version } from "../src/lite/version.ts"; import { Reader } from "../src/stream.ts"; const frameSizes = [16 * 1024, 256 * 1024, 1024 * 1024]; @@ -31,7 +32,7 @@ for (const frameSize of frameSizes) { controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, Version.DRAFT_06); const start = performance.now(); const read = await reader.read(frameSize); diff --git a/js/net/bench/varint.ts b/js/net/bench/varint.ts index d8322a1c1e7..1cc8812e852 100644 --- a/js/net/bench/varint.ts +++ b/js/net/bench/varint.ts @@ -15,7 +15,7 @@ let checksum = 0; const formats = [ { name: "quic", - version: undefined, + version: Version.DRAFT_16, encode: Varint.encodeTo, values: [2 ** 6 - 1, 2 ** 14 - 1, 2 ** 30 - 1, Number.MAX_SAFE_INTEGER], }, diff --git a/js/net/src/announced.test.ts b/js/net/src/announced.test.ts index 2ff05b0b506..7763431e17e 100644 --- a/js/net/src/announced.test.ts +++ b/js/net/src/announced.test.ts @@ -48,7 +48,7 @@ test("a same-name re-announce is a distinct update", async () => { // The stream is a log, not a set: it carries a redundant announce as its own update rather // than collapsing it. Deciding what a repeat means belongs to the session layer, which resolves - // a restart into either nothing (a route change) or an end + start (a new publisher). + // a restart into either nothing (an identical route) or an in-place update. const route = Route.default; producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "start", route }); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 28d202c48c6..9c77d51b06c 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -135,6 +135,54 @@ test("a sibling producer's groups do not settle an aborted end", async () => { broadcast.close(); }); +test("a clean close ends at the track's own last group, not a sibling's", async () => { + const broadcast = new BroadcastProducer(); + const firstSubscriber = broadcast.track("media").subscribe(); + const secondSubscriber = broadcast.track("media").subscribe(); + const firstRequest = await wireOf(broadcast).requested(); + const secondRequest = await wireOf(broadcast).requested(); + if (!firstRequest || !secondRequest) throw new Error("expected requests"); + const firstProducer = firstRequest.accept(); + const secondProducer = secondRequest.accept(); + + const reader = firstProducer.subscribe(); + firstProducer.appendGroup().close(); + for (let i = 0; i < 3; i++) secondProducer.appendGroup().close(); + firstProducer.close(); + + // The sibling took 1..3, which the first producer will never send. + expect(reader.final()).toBe(1); + + firstSubscriber.close(); + secondSubscriber.close(); + secondProducer.close(); + broadcast.close(); +}); + +test("finishAt accepts an end below a sibling's groups", async () => { + const broadcast = new BroadcastProducer(); + const firstSubscriber = broadcast.track("media").subscribe(); + const secondSubscriber = broadcast.track("media").subscribe(); + const firstRequest = await wireOf(broadcast).requested(); + const secondRequest = await wireOf(broadcast).requested(); + if (!firstRequest || !secondRequest) throw new Error("expected requests"); + const firstProducer = firstRequest.accept(); + const secondProducer = secondRequest.accept(); + + const reader = firstProducer.subscribe(); + firstProducer.appendGroup().close(); + for (let i = 0; i < 3; i++) secondProducer.appendGroup().close(); + expect(() => firstProducer.finishAt(0)).toThrow("track end 0 is below the next sequence 1"); + firstProducer.finishAt(2); + expect(reader.final()).toBe(2); + + firstSubscriber.close(); + secondSubscriber.close(); + firstProducer.close(); + secondProducer.close(); + broadcast.close(); +}); + test("closing a broadcast rejects a dequeued request", async () => { const broadcast = new BroadcastProducer(); const subscriber = broadcast.track("media").subscribe(); @@ -439,3 +487,19 @@ test("a fetch waits for a group still to come", async () => { broadcast.close(); }); + +test("aborting a fetch rejects with the signal's reason", async () => { + const broadcast = new BroadcastProducer(); + broadcast.createTrack("video"); + + const early = new Error("early"); + await expect(wireOf(broadcast).fetchGroup("video", 0, { signal: AbortSignal.abort(early) })).rejects.toBe(early); + + const controller = new AbortController(); + const pending = wireOf(broadcast).fetchGroup("video", 0, { signal: controller.signal }); + const late = new Error("late"); + controller.abort(late); + await expect(pending).rejects.toBe(late); + + broadcast.close(); +}); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index cff6a07f3ae..d477986c999 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -10,6 +10,7 @@ import { Route } from "./hop.ts"; import { hooks, type TrackSequence } from "./internal.ts"; import * as Path from "./path.ts"; import * as track from "./track.ts"; +import { untilAborted } from "./util/abort.ts"; import { registerWire, trackOf, type Broadcast as Wire } from "./wire.ts"; /** The origin callback a created broadcast uses to advertise its exact path. @internal */ @@ -129,11 +130,12 @@ async function fetchGroup( sequence: number, options: track.FetchGroupOptions = {}, ): Promise { + options.signal?.throwIfAborted(); const subscriber = subscribe(state, name, { priority: options.priority }); hooks.exemptFetch(subscriber); try { for (;;) { - const group = await subscriber.recvGroup(); + const group = await untilAborted(subscriber.recvGroup(), options.signal); if (!group) throw new NotFound(`group ${sequence}`); if (group.sequence === sequence) { // Close the subscription when the returned group finishes, not now: an diff --git a/js/net/src/connection/accept.ts b/js/net/src/connection/accept.ts index d0f4f2c2977..86a9ac33ad3 100644 --- a/js/net/src/connection/accept.ts +++ b/js/net/src/connection/accept.ts @@ -142,7 +142,7 @@ async function acceptSetup( wiring: SessionProps, ): Promise { // Accept bidi, read ClientSetup, write ServerSetup - const stream = await Stream.accept(transport); + const stream = await Stream.accept(transport, version); if (!stream) throw new Error("no incoming bidi stream for SETUP"); const clientCompat = await stream.reader.u53(); @@ -187,7 +187,7 @@ async function acceptNegotiated( ): Promise { const setupVersion = Ietf.Version.DRAFT_14; - const stream = await Stream.accept(transport); + const stream = await Stream.accept(transport, setupVersion); if (!stream) throw new Error("no incoming bidi stream for SETUP"); const clientCompat = await stream.reader.u53(); diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index ffd3004750d..fc79b2454ea 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -297,7 +297,7 @@ async function negotiate(url: URL, session: WebTransport, wiring: SessionProps): throw new Error(`unsupported WebTransport protocol: ${protocol}`); } - const stream = await Stream.open(session); + const stream = await Stream.open(session, { version: setupVersion }); await stream.writer.u53(Lite.StreamId.ClientCompat); const encoder = new TextEncoder(); diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index cbb2c0d1cfc..b5e69ebc766 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -66,6 +66,20 @@ export function randomHop(): Hop { return HopSchema.parse(raw === 0n ? 1n : raw); } +/** + * Name an unknown original publisher: put `stamp`, the receiving connection's own random id, + * in front of a chain that starts with 0, and turn an empty chain into `[stamp, 0]`. A + * publisher that reconnects then reads downstream as a new first hop, while the 0 after the + * stamp keeps the route ranked as anonymous. `undefined` if the chain is full or already holds + * `stamp`. Mirrors `Hops::stamp` in rs/moq-net. + */ +export function stampHops(hops: readonly Hop[], stamp: Hop): Hop[] | undefined { + if (hops.length === 0) return [stamp, UNKNOWN_HOP]; + if (hops[0] !== UNKNOWN_HOP) return [...hops]; + if (hops.length >= MAX_HOPS || hops.includes(stamp)) return undefined; + return [stamp, ...hops]; +} + /** * What pulling content via a route costs, in two magnitudes accumulated together * and compared in that order: lower {@link Cost.warm} wins, and {@link Cost.cold} diff --git a/js/net/src/ietf/adapter.ts b/js/net/src/ietf/adapter.ts index b51e48d8dac..780b6a1b39c 100644 --- a/js/net/src/ietf/adapter.ts +++ b/js/net/src/ietf/adapter.ts @@ -212,9 +212,7 @@ export class ControlStreamAdapter implements Session { }, }); - const stream = new Stream({ readable, writable: sendWritable }); - stream.reader.version = this.version; - stream.writer.version = this.version; + const stream = new Stream({ readable, writable: sendWritable, version: this.version }); return stream; } @@ -339,9 +337,7 @@ export class ControlStreamAdapter implements Session { const sendWritable = this.#createSendWritable(); - const stream = new Stream({ readable, writable: sendWritable }); - stream.reader.version = this.version; - stream.writer.version = this.version; + const stream = new Stream({ readable, writable: sendWritable, version: this.version }); this.#streams.set(requestId, { controller }); diff --git a/js/net/src/ietf/cluster.ts b/js/net/src/ietf/cluster.ts index 3215ec5e732..9a77b3cea0b 100644 --- a/js/net/src/ietf/cluster.ts +++ b/js/net/src/ietf/cluster.ts @@ -14,9 +14,9 @@ * `lite/announce.ts`); this module is the moq-transport binding, negotiated on draft-17+ * only, where SETUP is a Key-Value-Pair block. * - * We are a leaf, never a relay: the only path we can advertise is our own, so we stamp a - * single-entry HOP_PATH and seed the cost at 0. What we get out of declaring is the other - * direction. A relay that knows our Hop ID withholds the advertisements that already flowed + * A broadcast we produce carries a single-entry HOP_PATH and a cost of 0, and a route we + * forward carries its own hop chain and warm cost with our id appended. What we get out of + * declaring is also the other direction. A relay that knows our Hop ID withholds the advertisements that already flowed * through us, so publishing a broadcast no longer announces it back to us, which is what * moq-lite has always done with its own hop chain. * diff --git a/js/net/src/ietf/connection.ts b/js/net/src/ietf/connection.ts index d9eb83c6e71..b957ac5a308 100644 --- a/js/net/src/ietf/connection.ts +++ b/js/net/src/ietf/connection.ts @@ -139,6 +139,7 @@ export class Connection implements Established { session: this.#session, publish, requiresSolicitation: solicit ?? false, + hidden, cluster, }); this.#solicit = solicit; diff --git a/js/net/src/ietf/hidden.ts b/js/net/src/ietf/hidden.ts index cd22aff02ff..ea732799303 100644 --- a/js/net/src/ietf/hidden.ts +++ b/js/net/src/ietf/hidden.ts @@ -6,7 +6,7 @@ import { SetupOption, type SetupOptions } from "./parameters.ts"; * A namespace with a field starting with `.` below the prefix a subscription asked for is * left out of discovery unless the SUBSCRIBE_NAMESPACE opts in with the HIDDEN parameter. * An unknown parameter fails decoding, so the parameter is only sent to a peer whose SETUP - * carried the HIDDEN option. + * carried the HIDDEN option. Peers that did not declare the option receive every namespace. * * @module * @internal diff --git a/js/net/src/ietf/ietf.test.ts b/js/net/src/ietf/ietf.test.ts index ec6d906c20a..cfd7d29525d 100644 --- a/js/net/src/ietf/ietf.test.ts +++ b/js/net/src/ietf/ietf.test.ts @@ -1068,7 +1068,7 @@ test("TrackStatusRequest v17: round trip with requiredRequestIdDelta", async () // Helper to encode a namespace to raw bytes async function encodeNamespace(namespace: Path.Valid): Promise { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, Version.DRAFT_14); await Namespace.encode(writer, namespace); writer.close(); await writer.closed; @@ -1077,14 +1077,14 @@ async function encodeNamespace(namespace: Path.Valid): Promise { // Helper to decode a namespace from raw bytes async function decodeNamespace(bytes: Uint8Array): Promise { - const reader = new Reader(undefined, bytes); + const reader = new Reader(undefined, bytes, Version.DRAFT_14); return await Namespace.decode(reader); } // Helper to encode raw IETF namespace tuple fields async function encodeNamespaceTuple(parts: string[]): Promise { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, Version.DRAFT_14); await writer.u53(parts.length); for (const part of parts) await writer.string(part); writer.close(); diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index ab37261e0ab..9d6a63b883d 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -1,7 +1,11 @@ -import { type Cursor, type Reader, Writer } from "../stream.ts"; +import { StreamCode, Stream as StreamError } from "../error.ts"; +import { asIetf, type Cursor, type Reader, Writer } from "../stream.ts"; import { Timescale, Timestamp } from "../time.ts"; import { type IetfVersion, Version } from "./version.ts"; +// Implementation limit for object extension blocks, independent of the IETF draft. +const MAX_OBJECT_EXTENSIONS = 64 * 1024; + const GROUP_END = 0x03; const END_OF_TRACK = 0x04; @@ -43,12 +47,7 @@ function hasDeltaObjectPropertyTypes(version: IetfVersion | undefined): boolean } } -async function encodeObjectPropertyType( - w: Writer, - id: bigint, - prev: bigint, - version: IetfVersion | undefined, -): Promise { +async function encodeObjectPropertyType(w: Writer, id: bigint, prev: bigint, version: IetfVersion): Promise { const encoded = hasDeltaObjectPropertyTypes(version) ? id - prev : id; await w.u62(encoded); } @@ -61,7 +60,7 @@ async function encodeObjectTime( w: Writer, timestamp: Timestamp, timescale: Timescale, - version: IetfVersion | undefined, + version: IetfVersion, ): Promise { const value = Math.round((timestamp.value * timescale) / timestamp.scale); await encodeObjectPropertyType(w, PROP_TIMESTAMP, 0n, version); @@ -71,7 +70,7 @@ async function encodeObjectTime( async function encodeObjectExtensions( timestamp: Timestamp | undefined, timescale: Timescale, - version: IetfVersion | undefined, + version: IetfVersion, ): Promise { if (timestamp === undefined) { return new Uint8Array(); @@ -108,7 +107,7 @@ function decodeObjectTime(c: Cursor, timescale: Timescale): Timestamp | undefine while (c.remaining > 0) { const step = c.u62(); - const id = !hasDeltaObjectPropertyTypes(c.version) || first ? step : prevType + step; + const id = !hasDeltaObjectPropertyTypes(asIetf(c.version)) || first ? step : prevType + step; first = false; prevType = id; @@ -281,7 +280,7 @@ export class Frame { * `idDelta` is the first object's absolute Object ID and zero for every later one, so a * group whose head was trimmed by a filter still puts the true numbering on the wire. */ - async encode(w: Writer, flags: GroupFlags, timescale: Timescale, version = w.version, idDelta = 0): Promise { + async encode(w: Writer, flags: GroupFlags, timescale: Timescale, version: IetfVersion, idDelta = 0): Promise { await w.u53(idDelta); if (flags.hasExtensions) { @@ -321,6 +320,9 @@ export class Frame { let timestamp: Timestamp | undefined; if (flags.hasExtensions) { const extensionsLength = c.u53(); + if (extensionsLength > MAX_OBJECT_EXTENSIONS) { + throw new StreamError(StreamCode.MalformedTrack, { message: "object extensions exceed 64 KiB" }); + } // A track that declared no timescale opted out of timestamps, so its objects // are stamped on arrival even if one carries a Timestamp we cannot interpret. if (timescale !== undefined) { @@ -391,7 +393,7 @@ export class FetchFrame { } /** Encode this object at `position`, stamping it in the track's timescale. */ - async encode(w: Writer, position: FetchPosition, timescale: Timescale, version = w.version): Promise { + async encode(w: Writer, position: FetchPosition, timescale: Timescale, version: IetfVersion): Promise { if (position.first) { // Include the priority too: "same as the prior object" has no prior to refer to. const properties = this.timestamp !== undefined ? FETCH_PROPERTIES : 0; diff --git a/js/net/src/ietf/priority.test.ts b/js/net/src/ietf/priority.test.ts index a05f8b26505..b04da83354e 100644 --- a/js/net/src/ietf/priority.test.ts +++ b/js/net/src/ietf/priority.test.ts @@ -1,4 +1,5 @@ import { expect, test } from "bun:test"; +import { infoDefaults } from "../track.ts"; import { fromWire, toWire } from "./priority.ts"; test("IETF subscriber priority is lower first", () => { @@ -17,3 +18,7 @@ test("subscriber priority round trips", () => { expect(fromWire(toWire(priority))).toBe(priority); } }); + +test("an unset track priority is the draft's usual publisher priority", () => { + expect(toWire(infoDefaults().priority)).toBe(128); +}); diff --git a/js/net/src/ietf/publish_namespace.ts b/js/net/src/ietf/publish_namespace.ts index f094b7c57a0..1be3e59c458 100644 --- a/js/net/src/ietf/publish_namespace.ts +++ b/js/net/src/ietf/publish_namespace.ts @@ -75,8 +75,8 @@ export class PublishNamespace { * REQUEST_UPDATE (0x02) on a PUBLISH_NAMESPACE stream: the cluster parameters that * changed (draft-lcurley-moq-cluster, Updating an Advertisement). * - * Draft-17+ only: the extension negotiates on nothing earlier. We are a leaf and never - * reprice, so only a relay sends one to us. + * Draft-17+ only: the extension negotiates on nothing earlier. The publisher sends one when + * a forwarded route's price or hop chain moves behind the same original publisher. */ export class PublishNamespaceUpdate { static id = 0x02; diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index b7d2bf6c97f..aeee04da778 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1,4 +1,4 @@ -import { expect, mock, spyOn, test } from "bun:test"; +import { expect, jest, mock, spyOn, test } from "bun:test"; import { Signal } from "@moq/signals"; import type { Producer as BroadcastProducer } from "../broadcast.ts"; import { error } from "../error.ts"; @@ -16,11 +16,11 @@ import type * as Cluster from "./cluster.ts"; import { FetchHeader } from "./fetch.ts"; import { Frame, Group as GroupMessage } from "./object.ts"; import { PublishDone } from "./publish.ts"; -import { PublishNamespace } from "./publish_namespace.ts"; +import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts"; import { Publisher } from "./publisher.ts"; import { RequestError, RequestOk } from "./request.ts"; import { Subscribe, SubscribeOk } from "./subscribe.ts"; -import { SubscribeNamespace, SubscribeNamespaceEntry } from "./subscribe_namespace.ts"; +import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDone } from "./subscribe_namespace.ts"; import { TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; @@ -940,34 +940,425 @@ test("an advertisement carries our hop id once the peer declared one", async () } }); -test("an advertisement carries the announced route and re-prices in place", async () => { - const self: Hop = HopSchema.parse(7n); - const peer: Hop = HopSchema.parse(9n); - const via: Hop = HopSchema.parse(3n); - const pair = createMockTransportPair(ALPN.DRAFT_19); - const { pub, origin } = publisher(pair.server, { cluster: { self, peer } }); - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [via], cost: 4n }); - void pub.runPublishNamespaces(); +/** Let every pending promise chain run without letting a faked timer fire. */ +async function flush() { + for (let i = 0; i < 20; i++) await new Promise((resolve) => setImmediate(resolve)); +} - const stream = await nextStream(pair.client); - if (!stream) throw new Error("no PUBLISH_NAMESPACE for the broadcast"); +/** Advance faked time in steps, letting the loop react between them as it would in real time. */ +async function advance(ms: number, step = 50) { + for (let elapsed = 0; elapsed < ms; elapsed += step) { + jest.advanceTimersByTime(step); + await flush(); + } +} + +/** Advance faked time until `done` holds, failing once `limit` has passed without it. */ +async function advanceUntil(done: () => boolean, limit: number, step = 50) { + for (let elapsed = 0; !done(); elapsed += step) { + if (elapsed >= limit) throw new Error(`still waiting after ${limit}ms`); + jest.advanceTimersByTime(step); + await flush(); + } +} + +/** How a promise has settled so far, read without awaiting it. */ +function watch(promise: Promise): { state: "pending" | "resolved" | "rejected"; value?: T } { + const status: { state: "pending" | "resolved" | "rejected"; value?: T } = { state: "pending" }; + promise.then( + (value) => { + status.state = "resolved"; + status.value = value; + }, + () => { + status.state = "rejected"; + }, + ); + return status; +} + +/** + * Every stream the publisher opens, in order, collected as they arrive so a test can ask + * whether one came without a timer. + */ +function accepted(transport: WebTransport): Stream[] { + const queue: Stream[] = []; + void (async () => { + const reader = transport.incomingBidirectionalStreams.getReader(); + for (;;) { + const next = await reader.read().catch(() => undefined); + if (!next || next.done) return; + queue.push(new Stream({ readable: next.value.readable, writable: next.value.writable, version: VERSION })); + } + })(); + return queue; +} + +/** Take the next stream the publisher opened, failing if it has not opened one. */ +async function take(queue: Stream[]): Promise { + await flush(); + const stream = queue.shift(); + if (!stream) throw new Error("expected the publisher to open a stream"); + return stream; +} + +/** Read one PUBLISH_NAMESPACE and its cluster parameters, then accept it. */ +async function acceptClustered(stream: Stream): Promise { expect(await stream.reader.u53()).toBe(PublishNamespace.id); const msg = await PublishNamespace.decode(stream.reader, VERSION, true); - expect(msg.trackNamespace).toBe(Path.from("mine")); - expect(msg.cluster).toEqual({ hops: [via, self], cost: 4n }); await acceptPublishNamespace(stream); + return msg.cluster; +} - broadcast.announce({ hops: [via], cost: 8n }); - const next = await nextStream(pair.client); - if (!next) throw new Error("no PUBLISH_NAMESPACE for the re-price"); - expect(await next.reader.u53()).toBe(PublishNamespace.id); - const updated = await PublishNamespace.decode(next.reader, VERSION, true); - expect(updated.trackNamespace).toBe(Path.from("mine")); - expect(updated.cluster).toEqual({ hops: [via, self], cost: 8n }); - await acceptPublishNamespace(next); +/** Read one REQUEST_UPDATE off a PUBLISH_NAMESPACE stream. */ +async function readUpdate(stream: Stream): Promise { + expect(await stream.reader.u53()).toBe(PublishNamespaceUpdate.id); + return (await PublishNamespaceUpdate.decode(stream.reader, VERSION)).update; +} - origin.close(); +/** A clustered publisher on fake time, with every stream it opens collected. */ +function clustered(requiresSolicitation = false) { + jest.useFakeTimers(); + const self: Hop = HopSchema.parse(7n); + const peer: Hop = HopSchema.parse(9n); + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server, { cluster: { self, peer }, requiresSolicitation }); + const streams = accepted(pair.client); + const close = () => { + origin.close(); + jest.useRealTimers(); + }; + return { self, pair, pub, origin, streams, close }; +} + +const VIA: Hop = HopSchema.parse(3n); +const MID: Hop = HopSchema.parse(4n); +const OTHER: Hop = HopSchema.parse(5n); + +/** + * A reprice is a REQUEST_UPDATE on the request that already carries the namespace, with + * only what changed. A cost that drops to 0 has to say so: REQUEST_UPDATE keeps an omitted + * parameter, so leaving it out would leave the peer holding the old price. + */ +test("a price change on a held namespace is one REQUEST_UPDATE, not a withdrawal", async () => { + const { self, pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + expect(await acceptClustered(stream)).toEqual({ hops: [VIA, self], cost: 4n }); + + broadcast.announce({ hops: [VIA], cost: 8n }); + expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 8n }); + await acceptPublishNamespace(stream); + + broadcast.announce({ hops: [VIA], cost: 0n }); + expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 0n }); + await acceptPublishNamespace(stream); + + // Still the one request, still open: nothing was withdrawn or advertised again. + const more = watch(stream.reader.done()); + await flush(); + expect(more.state).toBe("pending"); + expect(streams).toHaveLength(0); + } finally { + close(); + } +}); + +test("a hop path change behind the same publisher is one REQUEST_UPDATE carrying HOP_PATH", async () => { + const { self, pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA, MID], cost: 4n }); + expect(await readUpdate(stream)).toEqual({ hops: [VIA, MID, self], cost: undefined }); + await acceptPublishNamespace(stream); + + const more = watch(stream.reader.done()); + await flush(); + expect(more.state).toBe("pending"); + expect(streams).toHaveLength(0); + } finally { + close(); + } +}); + +/** + * NAMESPACE has no REQUEST_UPDATE; the receiver reads a repeat as a replacement. That holds + * for a new original publisher too. + */ +test.each([ + ["a hop path and cost change", [VIA, MID], 8n], + ["a first-hop change", [OTHER], 4n], +] as const)("a solicited namespace takes %s as one NAMESPACE and no NAMESPACE_DONE", async (_, hops, cost) => { + const { self, pair, pub, origin, close } = clustered(true); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + + const subscription = await Stream.open(pair.client, { version: VERSION }); + const stream = await Stream.accept(pair.server, VERSION); + if (!stream) throw new Error("the subscription stream was never accepted"); + void pub.runSubscribeNamespace(new SubscribeNamespace({ requestId: 0n, namespace: Path.empty() }), stream); + + const entry = async () => { + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + return await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); + }; + + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, VERSION); + expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [VIA, self], cost: 4n } }); + + broadcast.announce({ hops: [...hops], cost }); + expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [...hops, self], cost } }); + + const more = watch(subscription.reader.u53()); + await flush(); + expect(more.state).toBe("pending"); + subscription.close(); + } finally { + close(); + } +}); + +/** + * A different original publisher updates the PUBLISH_NAMESPACE in place, as any other + * change does: withdrawing it would make the namespace briefly vanish downstream. + */ +test("a first-hop change is one REQUEST_UPDATE carrying HOP_PATH, not a withdrawal", async () => { + const { self, pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [OTHER], cost: 4n }); + expect(await readUpdate(stream)).toEqual({ hops: [OTHER, self], cost: undefined }); + await acceptPublishNamespace(stream); + + const more = watch(stream.reader.done()); + await flush(); + expect(more.state).toBe("pending"); + expect(streams).toHaveLength(0); + } finally { + close(); + } +}); + +/** A different broadcast is not an update: it withdraws the old one and advertises again. */ +function republish(origin: OriginProducer, old: BroadcastProducer) { + const next = origin.createBroadcast(Path.from("mine")); + next.announce({ hops: [VIA], cost: 4n }); + old.close(); +} + +test("a republish withdraws the PUBLISH_NAMESPACE and advertises again", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const old = await take(streams); + await acceptClustered(old); + + republish(origin, broadcast); + + // Draft-17+ withdraws with the FIN alone, and the replacement waits for it. + expect(await old.reader.done()).toBe(true); + const next = await take(streams); + expect(await acceptClustered(next)).toMatchObject({ cost: 4n }); + } finally { + close(); + } +}); + +test("a republish withdraws the solicited NAMESPACE and sends it again", async () => { + const { pair, pub, origin, close } = clustered(true); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + + const subscription = await Stream.open(pair.client, { version: VERSION }); + const stream = await Stream.accept(pair.server, VERSION); + if (!stream) throw new Error("the subscription stream was never accepted"); + void pub.runSubscribeNamespace(new SubscribeNamespace({ requestId: 0n, namespace: Path.empty() }), stream); + + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, VERSION); + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); + + republish(origin, broadcast); + + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntryDone.id); + expect((await SubscribeNamespaceEntryDone.decode(subscription.reader, VERSION)).suffix).toBe(Path.from("mine")); + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + expect((await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true)).suffix).toBe( + Path.from("mine"), + ); + subscription.close(); + } finally { + close(); + } +}); + +/** + * A REQUEST_ERROR on an update withdraws the advertisement, and the fresh offer that + * brings it back waits out the interval the peer named, or never comes for an interval + * of 0. + */ +test.each([ + ["waits out its retry interval", 10_000n], + ["that forbids retrying is never re-offered", 0n], +])("a refused update %s", async (_, retryInterval) => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + await readUpdate(stream); + await declinePublishNamespace(stream, retryInterval); + + // Our side finishes too, which completes the withdrawal. + expect(await stream.reader.done()).toBe(true); + + // Well past our own backoff, but inside the interval the peer asked for. + await advance(9_000); + expect(streams).toHaveLength(0); + + if (retryInterval === 0n) { + await advance(20_000); + expect(streams).toHaveLength(0); + return; + } + + // Past the interval, the next backoff (at most its ceiling) brings it back. + await advanceUntil(() => streams.length > 0, 6_500); + const fresh = await take(streams); + expect(await acceptClustered(fresh)).toMatchObject({ cost: 8n }); + } finally { + close(); + } +}); + +/** + * A peer that refuses an update and then closes its side can make our withdrawal's wait + * on the FIN reject. The request is gone either way, so the loop keeps the refusal and + * re-offers the namespace instead of ending. + */ +test("a refused update whose peer closes the request keeps the loop running", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + let failed: unknown; + void pub.runPublishNamespaces().catch((err: unknown) => { + failed = err; + }); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + await readUpdate(stream); + await declinePublishNamespace(stream, 1n); + stream.close(); + + await advanceUntil(() => streams.length > 0 || failed !== undefined, 10_000); + expect(failed).toBeUndefined(); + const fresh = await take(streams); + expect(await acceptClustered(fresh)).toMatchObject({ cost: 8n }); + } finally { + close(); + } +}); + +/** + * One update is outstanding per stream, which is what satisfies MAX_REQUEST_UPDATES + * without reading it: a change landing while one waits for its answer goes out after. + */ +test("a change while an update is unanswered waits for its answer", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 8n }); + + broadcast.announce({ hops: [VIA], cost: 12n }); + const second = watch(stream.reader.u53()); + await advance(1_000); + expect(second.state).toBe("pending"); + expect(streams).toHaveLength(0); + + await acceptPublishNamespace(stream); + await flush(); + expect(second.state).toBe("resolved"); + expect(second.value).toBe(PublishNamespaceUpdate.id); + expect((await PublishNamespaceUpdate.decode(stream.reader, VERSION)).update).toEqual({ + hops: undefined, + cost: 12n, + }); + await acceptPublishNamespace(stream); + } finally { + close(); + } +}); + +/** + * A peer that never answers an update cannot be assumed to hold either price, so the + * request is dropped and the namespace comes back on a fresh one. + */ +test("an unanswered update drops the request and re-offers the namespace fresh", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + await readUpdate(stream); + const reset = watch(stream.reader.u53()); + + await advance(4_900); + expect(reset.state).toBe("pending"); + expect(streams).toHaveLength(0); + + // The timeout resets the request, then the retry offers it on a new one. + await advance(100); + expect(reset.state).toBe("rejected"); + await advanceUntil(() => streams.length > 0, 200); + const fresh = await take(streams); + expect(await acceptClustered(fresh)).toMatchObject({ cost: 8n }); + } finally { + close(); + } }); /** @@ -1808,3 +2199,70 @@ test("draft-20: PUBLISH_DONE waits for a queued group and counts every stream", client.close(); } }); + +for (const version of [Version.DRAFT_15, Version.DRAFT_19] as const) { + for (const declared of [false, true]) { + for (const solicited of [false, true]) { + for (const optIn of [false, true]) { + test(`hidden negotiation: ${version}, declared=${declared}, solicited=${solicited}, optIn=${optIn}`, async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const origin = new OriginProducer(); + // Authorization heads must not replace the request's empty visibility prefix. + const scope = new Path.Patterns([ + Path.Pattern.subtree(Path.from(".stats")), + Path.Pattern.subtree(Path.from("visible")), + ]); + const pub = new Publisher({ + quic: pair.server, + session: new NativeSession(pair.server, version, true), + publish: origin.scope(Path.empty(), scope).consume(), + requiresSolicitation: solicited, + hidden: declared, + }); + publish(origin, Path.from(".stats/node")); + publish(origin, Path.from("visible")); + let subscription: Stream | undefined; + let run: Promise; + if (solicited) { + subscription = await Stream.open(pair.client, { version: version }); + const accepted = await Stream.accept(pair.server, version); + if (!accepted) throw new Error("missing subscription"); + run = pub.runSubscribeNamespace( + new SubscribeNamespace({ requestId: 0n, namespace: Path.empty(), hidden: optIn }), + accepted, + ); + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, version); + } else { + run = pub.runPublishNamespaces(); + } + const expected = !declared || (solicited && optIn) ? [".stats/node", "visible"] : ["visible"]; + const advertisements: Stream[] = []; + for (const path of expected) { + if (subscription && version !== Version.DRAFT_15) { + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + expect((await SubscribeNamespaceEntry.decode(subscription.reader, version)).suffix).toBe( + Path.from(path), + ); + } else { + const stream = await Stream.accept(pair.client, version); + if (!stream) throw new Error("missing advertisement"); + advertisements.push(stream); + expect(await stream.reader.u53()).toBe(PublishNamespace.id); + const msg = await PublishNamespace.decode(stream.reader, version); + expect(msg.trackNamespace).toBe(Path.from(path)); + await stream.writer.u53(RequestOk.id); + await new RequestOk({ + requestId: version === Version.DRAFT_15 ? msg.requestId : undefined, + }).encode(stream.writer, version); + } + } + subscription?.close(); + origin.close(); + await run; + for (const stream of advertisements) stream.close(); + }); + } + } + } +} diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index dcd0477d021..8e04fbbb06d 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -3,7 +3,7 @@ import type * as broadcast from "../broadcast.ts"; import { Withdrawal } from "../connection/withdrawal.ts"; import { controlTimeout, error, reason, StreamCode, StreamError } from "../error.ts"; import type * as group from "../group.ts"; -import type { Route } from "../hop.ts"; +import type { Hop, Route } from "../hop.ts"; import { hiddenBelow, hooks, presented } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -22,7 +22,12 @@ import { FetchFrame, Frame, Group as GroupMessage } from "./object.ts"; import { fromWire, toWire } from "./priority.ts"; import * as Properties from "./properties.ts"; import { PublishDone, PublishDoneStatus } from "./publish.ts"; -import { PublishNamespace, PublishNamespaceDone, PublishNamespaceOk } from "./publish_namespace.ts"; +import { + PublishNamespace, + PublishNamespaceDone, + PublishNamespaceOk, + PublishNamespaceUpdate, +} from "./publish_namespace.ts"; import { RequestError, RequestOk } from "./request.ts"; import { type Subscribe, SubscribeError, SubscribeOk } from "./subscribe.ts"; import { @@ -50,16 +55,37 @@ function clusterFor(base: Cluster.Advert | undefined, route: Route): Cluster.Adv } /** - * Whether the peer would decode the same advertisement: the same broadcast and, with MoQ - * Cluster, the same hop chain and warm cost. The cold cost, and the whole route without - * Cluster, never reach the wire, so a change there must not restart the namespace. + * What it takes to move the peer from `held` to `next`. + * + * - `"same"`: the peer would decode the same advertisement. The cold cost, and the whole + * route without Cluster, never reach the wire, so a change there sends nothing. + * - `"restart"`: nothing is held, nothing is wanted, or a different broadcast, which is + * withdrawn and advertised again. + * - Otherwise the same broadcast at a new hop chain or warm cost: the cluster parameters + * the peer holds and the ones it should, for the target to update. */ -function sameAdvert(base: Cluster.Advert | undefined, a: Advertised | undefined, b: Advertised | undefined): boolean { - if (a === undefined || b === undefined || a.identity !== b.identity) return false; - const x = clusterFor(base, a.route); - const y = clusterFor(base, b.route); - if (x === undefined || y === undefined) return x === y; - return x.cost === y.cost && x.hops.length === y.hops.length && x.hops.every((hop, i) => hop === y.hops[i]); +function change( + base: Cluster.Advert | undefined, + held: Advertised | undefined, + next: Advertised | undefined, +): "same" | "restart" | Reprice { + if (held === undefined || next === undefined || held.identity !== next.identity) return "restart"; + const from = clusterFor(base, held.route); + const to = clusterFor(base, next.route); + if (from === undefined || to === undefined) return from === to ? "same" : "restart"; + if (from.cost === to.cost && sameHops(from.hops, to.hops)) return "same"; + return { from, to }; +} + +/** A held advertisement's cluster parameters, and the ones the peer should hold instead. */ +interface Reprice { + from: Cluster.Advert; + to: Cluster.Advert; +} + +/** Whether two hop paths list the same hops in the same order. */ +function sameHops(a: Hop[], b: Hop[]): boolean { + return a.length === b.length && a.every((hop, i) => hop === b[i]); } /** @@ -84,6 +110,39 @@ function retryAfter(delay: number): Promise { */ type Refused = "never" | number; +/** + * How the peer answered an advertisement or an update: it holds the namespace, it does + * not and said nothing about coming back (`"dropped"`), or it refused. + */ +type Answer = "held" | "dropped" | Refused; + +/** The open PUBLISH_NAMESPACE request per advertised path. */ +type Requests = Map; + +/** What one announce loop knows about the peer, keyed the way that loop names namespaces. */ +interface Namespaces { + /** What the peer holds, by identity plus route. */ + active: Map; + + /** What the peer refused, and whether coming back is worth anything. */ + refused: Map; + + /** The identity each refusal was about, so a republish at the same path clears it. */ + offered: Map; +} + +/** Where one announce loop sends its advertisements. */ +interface Target { + /** Advertise a namespace the peer does not hold. */ + advertise(key: Path.Valid, next: Advertised): Promise; + + /** Reprice a namespace the peer holds: the same broadcast at a new hop chain or cost. */ + update(key: Path.Valid, next: Advertised, reprice: Reprice): Promise; + + /** Withdraw a namespace the peer holds. */ + withdraw(key: Path.Valid): Promise; +} + /** What {@link Publisher.runGroup} needs to serve one group. */ interface RunGroup { /** The subscription's request ID, doubling as the track alias. */ @@ -171,6 +230,7 @@ export class Publisher { #quic: WebTransport; #session: Session; #requiresSolicitation: boolean; + #hidden: boolean; // The origin this session serves, borrowed: it outlives the session, and closing the // session leaves its broadcasts alone. The namespaces are advertised with an unsolicited @@ -194,6 +254,7 @@ export class Publisher { session, publish, requiresSolicitation, + hidden = false, cluster, }: { /** The WebTransport session, for uni streams. */ @@ -204,6 +265,8 @@ export class Publisher { publish?: OriginConsumer; /** Whether the peer's SETUP asked to be told on request (MoQ Solicit). */ requiresSolicitation: boolean; + /** Whether the peer declared MoQ Hidden. */ + hidden?: boolean; /** The Hop IDs the SETUP exchange settled (MoQ Cluster). */ cluster?: Cluster.Hops; }) { @@ -213,6 +276,7 @@ export class Publisher { this.#advertised = origin?.advertised ?? new Signal(new Map()); this.#publish = publish; this.#requiresSolicitation = requiresSolicitation; + this.#hidden = hidden; this.#advert = Cluster.advertise(cluster); } @@ -729,8 +793,9 @@ export class Publisher { * This carries the advertisements when the peer asked to be told on request (MoQ * Solicit); otherwise {@link runPublishNamespaces} has already announced everything * visible and repeating it here would leave the peer holding two sources for one - * broadcast, so only the hidden namespaces it may see ride here (MoQ Hidden). Draft-16+ streams Namespace entries inline; draft-14/15 predate those - * messages, so each advertisement is a PUBLISH_NAMESPACE request of its own. + * broadcast, so only the hidden namespaces it may see ride here (MoQ Hidden). + * Draft-16+ streams Namespace entries inline; draft-14/15 predate those messages, so + * each advertisement is a PUBLISH_NAMESPACE request of its own. * * @internal */ @@ -745,7 +810,7 @@ export class Publisher { const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15; // Draft-14/15: the open PUBLISH_NAMESPACE request per advertised suffix. - const requests = new Map(); + const requests: Requests = new Map(); // Drains the requests map, so calling it twice is safe and the second is a no-op. const withdrawAll = async () => { for (const path of [...requests.keys()]) { @@ -771,38 +836,38 @@ export class Publisher { // peer asked to be told only on request, it has already heard everything visible // from the empty prefix unasked, so this stream carries only what that hid. const carries = (covered: Path.Valid) => - (msg.hidden || !hiddenBelow(prefix, covered)) && - (this.#requiresSolicitation || hiddenBelow(Path.empty(), covered)); - - // 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, snap: Advertised): Promise => { - const cluster = clusterFor(this.#advert, snap.route); - if (legacy) { - return await this.#advertise(Path.join(prefix, suffix), requests, refused, cluster); - } - + (!this.#hidden || msg.hidden || !hiddenBelow(prefix, covered)) && + (this.#requiresSolicitation || (this.#hidden && hiddenBelow(Path.empty(), covered))); + + // Inline entries always land, and the receiver treats a repeated NAMESPACE as a + // replacement, so repricing one is just sending it again, a new original + // publisher included, as Rust does. Only a legacy PUBLISH_NAMESPACE request can + // be declined. + const namespace = async (suffix: Path.Valid, snap: Advertised): Promise => { await stream.writer.u53(SubscribeNamespaceEntry.id); + const cluster = clusterFor(this.#advert, snap.route); await new SubscribeNamespaceEntry({ suffix, cluster }).encode(stream.writer, version); - return true; + return "held"; }; - const withdraw = async (suffix: Path.Valid) => { - if (legacy) { - await this.#withdraw(Path.join(prefix, suffix), requests); - } else { - await stream.writer.u53(SubscribeNamespaceEntryDone.id); - await new SubscribeNamespaceEntryDone({ suffix }).encode(stream.writer, version); - } - }; - - // 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(); + const target: Target = legacy + ? { + advertise: (suffix, snap) => + this.#advertise(Path.join(prefix, suffix), requests, clusterFor(this.#advert, snap.route)), + update: (suffix, _snap, reprice) => this.#update(Path.join(prefix, suffix), requests, reprice), + withdraw: (suffix) => this.#withdraw(Path.join(prefix, suffix), requests), + } + : { + advertise: namespace, + update: namespace, + withdraw: async (suffix) => { + await stream.writer.u53(SubscribeNamespaceEntryDone.id); + await new SubscribeNamespaceEntryDone({ suffix }).encode(stream.writer, version); + }, + }; + + // Keyed by suffix, as the entries name them. + const ns: Namespaces = { active: new Map(), refused: new Map(), offered: new Map() }; let retry = 0; - // What the peer refused, and whether coming back is worth anything. - const refused = new Map(); - // The identity each refusal was about, so a republish at the same path clears it. - const offered = new Map(); for (;;) { // Subscribe BEFORE reconciling, for the same reason as @@ -820,50 +885,7 @@ export class Publisher { break; } - const updated = presented(prefix, advertised, carries); - - // 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 snap = suffix === null ? undefined : updated.get(suffix); - if (snap === undefined || offered.get(path) !== snap.identity) { - 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 or re-price reads as withdraw-then-advertise - // (a restart). Identity change is a new broadcast; a route change is the - // same one at a new cost or hop chain. - for (const [removed, snap] of active) { - if (sameAdvert(this.#advert, updated.get(removed), snap)) continue; - await withdraw(removed); - held.delete(removed); - } - for (const [added, snap] of updated) { - if (sameAdvert(this.#advert, held.get(added), snap)) continue; - if (!this.#offerable(Path.join(prefix, added), refused)) continue; - offered.set(Path.join(prefix, added), snap.identity); - if (await advertise(added, snap)) held.set(added, snap); - } - - 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, snap]) => - !sameAdvert(this.#advert, active.get(suffix), snap) && - this.#pending(Path.join(prefix, suffix), refused), - ); + const outstanding = await this.#reconcile(ns, presented(prefix, advertised, carries), target); retry = outstanding ? Math.min(retry ? retry * 2 : RETRY_BASE, RETRY_MAX) : 0; // Wait for the next change, or for the peer to unsubscribe. @@ -919,7 +941,12 @@ export class Publisher { } // The open PUBLISH_NAMESPACE request per advertised path. - const requests = new Map(); + const requests: Requests = new Map(); + const target: Target = { + advertise: (path, snap) => this.#advertise(path, requests, clusterFor(this.#advert, snap.route)), + update: (path, _snap, reprice) => this.#update(path, requests, reprice), + withdraw: (path) => this.#withdraw(path, requests), + }; // 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 @@ -933,14 +960,9 @@ export class Publisher { let dispose: Dispose | undefined; try { - // What the peer holds: keyed by path, valued by identity plus route, so a - // republish diffs as withdraw-then-advertise rather than nothing. - let active = new Map(); + // Keyed by path. + const ns: Namespaces = { active: new Map(), refused: new Map(), offered: new Map() }; let retry = 0; - // What the peer refused, and whether coming back is worth anything. - const refused = new Map(); - // The identity 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 @@ -961,50 +983,12 @@ export class Publisher { const updated = new Map(); for (const [covered, candidates] of advertised) { - // Unasked, a hidden namespace stays off the wire (MoQ Hidden). - if (hiddenBelow(Path.empty(), covered) || candidates.length === 0) continue; + // Only peers that declared MoQ Hidden filter unsolicited discovery. + if ((this.#hidden && hiddenBelow(Path.empty(), covered)) || candidates.length === 0) continue; updated.set(covered, candidates[0]); } - // 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 snap = updated.get(path); - if (snap === undefined || offered.get(path) !== snap.identity) { - refused.delete(path); - offered.delete(path); - } - } - - // Withdraw first so a republish or re-price reads as withdraw-then-advertise - // (a restart) rather than nothing. - for (const [removed, snap] of active) { - if (sameAdvert(this.#advert, updated.get(removed), snap)) continue; - await this.#withdraw(removed, requests); - } - for (const [added, snap] of updated) { - if (sameAdvert(this.#advert, active.get(added), snap)) continue; - if (!this.#offerable(added, refused)) continue; - offered.set(added, snap.identity); - await this.#advertise(added, requests, refused, clusterFor(this.#advert, snap.route)); - } - - // 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 snap = updated.get(path); - return snap ? [[path, snap] 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, snap]) => !sameAdvert(this.#advert, active.get(path), snap) && this.#pending(path, refused), - ); + const outstanding = await this.#reconcile(ns, updated, target); 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. @@ -1028,14 +1012,82 @@ export class Publisher { } } + /** + * Bring the peer's view in line with `updated`, one namespace at a time, and report + * whether anything it should hold is still missing and worth coming back for. + * + * Nothing the peer cannot see is sent, a reprice updates the namespace in place, and + * anything else is withdrawn first so a republish reads as withdraw-then-advertise. + * `ns` records what the peer holds rather than what we attempted: a declined + * advertisement or update stays out of it, so the next turn offers it fresh instead + * of believing it is already up. + */ + async #reconcile(ns: Namespaces, updated: Map, target: Target): Promise { + // 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. Rust gets this + // by rebuilding the watched entry. + for (const key of [...ns.refused.keys()]) { + const snap = updated.get(key); + if (snap === undefined || ns.offered.get(key) !== snap.identity) { + ns.refused.delete(key); + ns.offered.delete(key); + } + } + + const held = new Map(ns.active); + for (const [key, snap] of ns.active) { + if (change(this.#advert, snap, updated.get(key)) !== "restart") continue; + await target.withdraw(key); + held.delete(key); + } + + for (const [key, snap] of updated) { + const prev = held.get(key); + const diff = change(this.#advert, prev, snap); + if (diff === "same") continue; + + let answer: Answer; + if (prev !== undefined && diff !== "restart") { + answer = await target.update(key, snap, diff); + } else { + // A fresh offer waits for what a refusal asked for, whatever brought us back. + if (!this.#offerable(key, ns.refused)) continue; + answer = await target.advertise(key, snap); + } + // `offered` pairs with `refused`, so a held or withdrawn path leaves nothing behind. + if (answer === "held") { + held.set(key, snap); + ns.refused.delete(key); + ns.offered.delete(key); + } else { + held.delete(key); + if (answer !== "dropped") { + ns.refused.set(key, answer); + ns.offered.set(key, snap.identity); + } + } + } + + ns.active = held; + + // 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. + return [...updated].some( + ([key, snap]) => change(this.#advert, held.get(key), snap) !== "same" && this.#pending(key, ns.refused), + ); + } + /** * 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); + #offerable(key: Path.Valid, refused: Map): boolean { + const entry = refused.get(key); if (entry === undefined) return true; return entry !== "never" && Date.now() >= entry; } @@ -1048,26 +1100,35 @@ export class Publisher { * 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"; + #pending(key: Path.Valid, refused: Map): boolean { + return refused.get(key) !== "never"; + } + + /** + * What a REQUEST_ERROR's retry interval, in milliseconds, says about re-offering the + * namespace. + * + * Draft-14/15 carry no such field, so a 0 there says nothing and our own backoff + * stands; everywhere else 0 means the peer does not want this again. + */ + #refusal(err: RequestError): Answer { + const version = this.#session.version; + if (version === Version.DRAFT_14 || version === Version.DRAFT_15) return "dropped"; + return err.retryInterval === 0n ? "never" : Date.now() + Number(err.retryInterval); } /** * 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, + requests: Requests, cluster: Cluster.Advert | undefined = this.#advert, - ): Promise { + ): Promise { const requestId = await this.#session.nextRequestId(); - if (requestId === undefined) return false; + if (requestId === undefined) return "dropped"; // 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 @@ -1082,8 +1143,8 @@ export class Publisher { // 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 () => { + const answer = await withTimeout( + (async (): Promise => { await stream.writer.u53(PublishNamespace.id); const msg = new PublishNamespace({ requestId, trackNamespace: path, cluster }); await msg.encode(stream.writer, this.#session.version); @@ -1091,26 +1152,16 @@ export class Publisher { // 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: ${requestReason( - err.errorCode, - err.reasonPhrase, - "publish_namespace", - this.#session.version, - )}`, + const why = requestReason( + err.errorCode, + err.reasonPhrase, + "publish_namespace", + this.#session.version, ); + console.warn(`announce refused: broadcast=${path} error=${why}`); + stream.abort(new Error(`PublishNamespace rejected: ${why}`)); + return this.#refusal(err); } if (respTypeId !== RequestOk.id) { throw new Error(`PublishNamespace rejected: typeId=0x${respTypeId.toString(16)}`); @@ -1121,29 +1172,91 @@ export class Publisher { } else { await RequestOk.decode(stream.reader, this.#session.version); } + return "held"; })(), 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; + if (answer === "held") requests.set(path, { path, requestId, stream }); + return answer; } catch (err: unknown) { // The peer never answered the advertisement: a control timeout, not late content. const e = err instanceof TimeoutError ? controlTimeout(err) : error(err); console.warn(`announce failed: broadcast=${path} error=${reason(e)}`); request?.abort(e); - return false; + return "dropped"; } } + /** + * Update a namespace the peer holds: REQUEST_UPDATE on the request that carries it, + * with only the parameters that changed, then its answer. + * + * Waiting for the answer keeps one update outstanding per stream, which satisfies any + * MAX_REQUEST_UPDATES the peer set without reading it; a change landing meanwhile waits + * for the next turn. The answer decides whether the peer still holds the namespace: a + * REQUEST_ERROR closes the peer's side and withdraws the advertisement, so ours is + * finished too, and an unanswered update is dropped abruptly, since a peer that ignored + * it cannot be assumed to hold either price. Either way the retry re-offers it fresh. + * + * A different original publisher is an update like any other: the receiver drains what + * it already serves from the old one and never splices the two. + */ + async #update(path: Path.Valid, requests: Requests, { from, to }: Reprice): Promise { + const request = requests.get(path); + if (!request) return "dropped"; + + const update: Cluster.Update = { + hops: sameHops(from.hops, to.hops) ? undefined : to.hops, + cost: from.cost === to.cost ? undefined : to.cost, + }; + const version = this.#session.version; + let answer: Answer; + try { + const requestId = await this.#session.nextRequestId(); + if (requestId === undefined) throw new Error("no request ID for the update"); + + answer = await withTimeout( + (async (): Promise => { + const { writer, reader } = request.stream; + await writer.u53(PublishNamespaceUpdate.id); + await new PublishNamespaceUpdate({ requestId, update }).encode(writer, version); + + const typeId = await reader.u53(); + if (typeId === RequestError.id) { + const err = await RequestError.decode(reader, version); + const why = requestReason(err.errorCode, err.reasonPhrase, "publish_namespace", version); + console.warn(`publish_namespace update refused: broadcast=${path} error=${why}`); + return this.#refusal(err); + } + if (typeId !== RequestOk.id) { + throw new Error(`unexpected answer to the update: typeId=0x${typeId.toString(16)}`); + } + await RequestOk.decode(reader, version); + return "held"; + })(), + ADVERTISE_TIMEOUT_MS, + `update timed out after ${ADVERTISE_TIMEOUT_MS}ms waiting for the peer's answer`, + ); + } catch (err: unknown) { + const e = err instanceof TimeoutError ? controlTimeout(err) : error(err); + console.warn(`publish_namespace update failed: broadcast=${path} error=${reason(e)}`); + requests.delete(path); + request.stream.abort(e); + return "dropped"; + } + + // The peer already closed out a refused request, and its STOP_SENDING can reject the + // wait on our FIN. That is the withdrawal finishing, not a reason to end the loop. + if (answer !== "held") await this.#withdraw(path, requests).catch(() => undefined); + return answer; + } + /** * Close out a namespace's PUBLISH_NAMESPACE request with PUBLISH_NAMESPACE_DONE. */ - async #withdraw( - path: Path.Valid, - requests: Map, - ) { + async #withdraw(path: Path.Valid, requests: Requests) { const request = requests.get(path); if (!request) return; requests.delete(path); diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 4f1307097d4..bdaf6b07d0b 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1,7 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import type * as announce from "../announced.ts"; -import { ProtocolViolation } from "../error.ts"; -import { type Hop, HopSchema } from "../hop.ts"; +import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; +import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts"; import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; @@ -111,6 +111,33 @@ test("an unsolicited announcement lands", async () => { }); }); +/** + * A session without the Cluster extension names no publisher, so each connection stamps its + * own random Hop ID in front of a 0: a publisher that reconnects reads as a new one, and the 0 + * keeps it ranked below identified routes. + */ +test("an advertisement with no path is stamped per connection", async () => { + const stamp = async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true) }); + const announced = subscriber.announced(); + expect(await nextStream(pair.client)).toBeDefined(); + + const stream = await Stream.open(pair.server, { version: VERSION }); + void subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("legacy") }), + stream, + ); + const hops = (await nextRoute(announced))?.route.hops ?? []; + expect(hops).toHaveLength(2); + expect(hops[0]).not.toBe(UNKNOWN_HOP); + expect(hops[1]).toBe(UNKNOWN_HOP); + return hops[0]; + }; + + expect(await stamp()).not.toBe(await stamp()); +}); + /** * Answer the SUBSCRIBE_NAMESPACE the subscriber just opened, then hand back its stream so * the test can feed inline NAMESPACE entries down it. @@ -625,11 +652,11 @@ test("a PUBLISH_NAMESPACE repricing is acknowledged in place", async () => { }); /** - * An update whose first Hop ID differs names a different publisher, whose content is not - * continuous with what is held. The draft has the sender withdraw and advertise again - * instead, so the update is refused and the stream closed, which is that withdrawal. + * An update whose first Hop ID differs names a different publisher. It still updates the + * advertisement in place and the stream stays open. A broadcast already held keeps + * draining, while the next consume starts fresh. */ -test("a PUBLISH_NAMESPACE update that changes the publisher is refused", async () => { +test("a PUBLISH_NAMESPACE update that changes the publisher applies in place", async () => { const pair = createMockTransportPair(ALPN.DRAFT_19); const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); @@ -652,16 +679,27 @@ test("a PUBLISH_NAMESPACE update that changes the publisher is refused", async ( if (!peer) throw new Error("no PUBLISH_NAMESPACE stream"); expect(await peer.reader.u53()).toBe(RequestOk.id); await RequestOk.decode(peer.reader, VERSION); + const held = subscriber.consume(Path.from("theirs")); await peer.writer.u53(PublishNamespaceUpdate.id); await new PublishNamespaceUpdate({ requestId: 3n, update: { hops: [HopSchema.parse(8n), PEER] } }).encode( peer.writer, VERSION, ); - expect(await peer.reader.u53()).toBe(RequestError.id); - await RequestError.decode(peer.reader, VERSION); + expect(await peer.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(peer.reader, VERSION); + expect(await announced.next()).toMatchObject({ + prefix: Path.from("theirs"), + kind: "update", + route: { hops: [HopSchema.parse(8n), PEER] }, + }); - // The refusal closed the stream, which withdrew the advertisement. + const fresh = subscriber.consume(Path.from("theirs")); + expect(fresh.closed).not.toBe(held.closed); + expect(held.closed.peek()).toBeUndefined(); + + // Still announced: the stream ending is what retracts it. + peer.close(); await handler; expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("theirs"), kind: "end" }); }); @@ -1069,3 +1107,69 @@ test("returning demand survives a blocked unsubscribe", async () => { broadcast.close(); session.close(); }); + +test("local readers filter hidden unsolicited namespaces from a legacy peer", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true) }); + const plain = subscriber.announced(); + const opted = subscriber.announced(undefined, { hidden: true }); + const handlers: Promise[] = []; + const streams: Stream[] = []; + for (const path of [".stats/node", "visible"]) { + const stream = await Stream.open(pair.server, { version: VERSION }); + streams.push(stream); + handlers.push( + subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from(path) }), + stream, + ), + ); + } + expect((await nextRoute(plain))?.prefix).toBe(Path.from("visible")); + expect((await nextRoute(opted))?.prefix).toBe(Path.from(".stats/node")); + expect((await nextRoute(opted))?.prefix).toBe(Path.from("visible")); + for (const stream of streams) stream.close(); + plain.close(); + opted.close(); + await Promise.all(handlers); +}); + +test("object extension limit accepts 64 KiB and stops one byte over before reading", async () => { + for (const size of [65536, 65537]) { + for (const first of [true, false]) { + const { subscriber, track } = await subscribeTrack(); + const bytes = new Uint8Array((first ? 0 : 4) + 4 + (size === 65536 ? size + 2 : 0)); + let offset = 0; + if (!first) { + bytes.set([0, 0, 1, 42]); + offset = 4; + } + // Object delta zero followed by a three-byte leading-ones varint length. + bytes.set([0, 0xc1, 0, size - 65536], offset); + if (size === 65536) bytes.set([1, 42], bytes.length - 2); + const reader = new Reader(undefined, bytes, VERSION); + const stop = spyOn(reader, "stop"); + const header = new GroupMessage({ + trackAlias: ALIAS, + groupId: 3, + subGroupId: 0, + publisherPriority: 0, + flags: { ...groupFlags(true), hasExtensions: true }, + }); + await subscriber.handleGroup(header, reader); + if (size === 65536) { + expect(stop.mock.calls).toEqual([]); + const group = await track.ordered().nextGroup(); + expect(group?.frameCount).toBe(first ? 1 : 2); + expect(await group?.readString()).toBe("*"); + } else { + expect(stop).toHaveBeenCalledTimes(1); + const err = stop.mock.calls[0][0]; + expect(err).toBeInstanceOf(StreamError); + expect((err as StreamError).code).toBe(StreamCode.MalformedTrack); + } + stop.mockRestore(); + track.close(); + } + } +}); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index c198945623d..a748d1aa4f3 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -4,11 +4,11 @@ import * as broadcast from "../broadcast.ts"; import { BroadcastCache } from "../consume.ts"; import { closeError, controlTimeout, error, ProtocolViolation, reason, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { Cost, type Route, randomHop, routesEqual, stampHops, UNKNOWN_HOP } from "../hop.ts"; import { hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import type { Cursor, Reader, Stream } from "../stream.ts"; -import { TAIL_GRACE_MS, Tail } from "../tail.ts"; +import { Tail } from "../tail.ts"; import { Milli, type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; @@ -52,6 +52,8 @@ type Subscription = { // The group streams received, so the subscription can wait for the ones PUBLISH_DONE // says are still owed. tail: Tail; + // The track's exclusive end, once an END_OF_TRACK declares it. + end?: number; }; // Out-parameter for #openSubscribe: lets the caller observe partial progress @@ -117,6 +119,10 @@ export class Subscriber { // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. #consumes = new BroadcastCache(); + // A random Hop ID of this connection's own, written as the first hop of any path that + // names no publisher, so a publisher that reconnects reads as a new one. + #stamp = randomHop(); + // 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. @@ -175,10 +181,16 @@ export class Subscriber { return advert !== undefined && this.#cluster !== undefined && Cluster.loops(advert, this.#cluster.self); } - /** The route an advertisement carries; one without a path is anonymous and free. */ + /** + * The route an advertisement carries; one without a path is free. A path that names no + * publisher, or none at all, gets this connection's stamp in front of a 0. + */ #route(advert: Cluster.Advert | undefined): Route { - if (advert === undefined) return { hops: [UNKNOWN_HOP], cost: Cost.zero }; - return { hops: advert.hops, cost: { warm: advert.cost, cold: advert.cost } }; + if (advert === undefined) return { hops: [this.#stamp, UNKNOWN_HOP], cost: Cost.zero }; + // A full chain, or a stamp colliding with an entry (a 1-in-2^53 draw), keeps the + // path as sent. + const hops = stampHops(advert.hops, this.#stamp) ?? [...advert.hops]; + return { hops, cost: { warm: advert.cost, cold: advert.cost } }; } /** @@ -242,10 +254,14 @@ export class Subscriber { * Replace the stored route for a path that is already announced. A no-op when the * hops and cost did not change; otherwise consumers hear `update` so a forwarder * can reprice without retracting. + * + * A new first hop is a new publisher: holders keep their broadcast to drain, but the + * next consume starts fresh rather than reusing the old publisher's cached track info. */ #updateAnnounce(path: Path.Valid, route: Route) { const existing = this.#announced.get(path); if (existing === undefined || routesEqual(existing.route, route)) return; + if (existing.route.hops[0] !== route.hops[0]) this.#consumes.evict(path); existing.route = route; console.debug(`announced: broadcast=${path} rerouted`); for (const [consumer, filter] of this.#announcedConsumers) { @@ -686,7 +702,7 @@ export class Subscriber { const { tail, track } = subscription; const complete = () => count > 0n && BigInt(tail.streams) >= count; - await tail.settle(complete, TAIL_GRACE_MS, track.closed); + await tail.settle(complete, track.closed); } /** @@ -914,20 +930,7 @@ export class Subscriber { throw new ProtocolViolation("cluster parameters on a session that negotiated none"); } } else { - // A different original publisher is a different advertisement, which the - // draft has withdrawn and made again: its content is not continuous with - // what is held. Refusing the update closes the stream, which is that - // withdrawal. - if (update.update.hops !== undefined && update.update.hops[0] !== held.hops[0]) { - console.warn(`publish_namespace update changes the publisher: broadcast=${path}`); - await stream.writer.u53(RequestError.id); - await new RequestError({ - errorCode: toRequestCode("not_supported", "publish_namespace", version), - reasonPhrase: "a new publisher is a new advertisement", - }).encode(stream.writer, version); - stream.close(); - return; - } + // A different original publisher applies in place too, as it does inline. held = Cluster.apply(held, update.update); } @@ -1037,6 +1040,12 @@ export class Subscriber { let producer: netGroup.Producer | undefined; const open = () => { if (!producer) { + // The publisher contradicted its own end, which no later group can repair. + if (subscription.end !== undefined && group.groupId >= subscription.end) { + throw new ProtocolViolation( + `group ${group.groupId} is at or past the declared end ${subscription.end}`, + ); + } producer = new netGroup.Producer(group.groupId); track.writeGroup(producer); } @@ -1087,6 +1096,7 @@ export class Subscriber { } catch (err: unknown) { throw new ProtocolViolation(`invalid END_OF_TRACK: ${reason(error(err))}`); } + subscription.end ??= end; return; } if (frame.payload === undefined) break; diff --git a/js/net/src/ietf/tail.test.ts b/js/net/src/ietf/tail.test.ts index da233686e77..3f43b53dc92 100644 --- a/js/net/src/ietf/tail.test.ts +++ b/js/net/src/ietf/tail.test.ts @@ -178,6 +178,20 @@ test("END_OF_TRACK at object 0 ends the track before its group, which never exis expect(reader.final()).toBe(2); }); +test("a group at or past the END_OF_TRACK aborts the track", async () => { + const { subscriber, reader } = await subscribed(); + const end = groupStream(subscriber, 2); + end.write(END_OF_TRACK); + end.finish(); + expect(await reader.finished()).toBe(2); + + const late = groupStream(subscriber, 2); + late.write(object("2.0")); + late.finish(); + await late.handled; + expect(await reader.closed).toBeInstanceOf(ProtocolViolation); +}); + test("a bare FIN without PUBLISH_DONE aborts the track", async () => { const { reader, fin } = await subscribed(); await fin(); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index a96b56d0b25..fcde98ca10d 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -432,18 +432,20 @@ async function announcedUntil(announced: Announce.Consumer, until: string) { // A `.`-named broadcast is left out of discovery unless the request opts in or names the // dot segment. lite-06 cannot carry the opt-in, so its peer never lists the hidden path. -for (const [protocol, carriesOptIn] of [ +for (const [protocol, carriesOptIn, version] of [ [Lite.ALPN_07_WIP, true], [Lite.ALPN_06, false], [Ietf.ALPN.DRAFT_19, true], [Ietf.ALPN.DRAFT_16, true], + ["", true, Ietf.Version.DRAFT_14], + [Ietf.ALPN.DRAFT_15, true], ] as const) { test(`integration: ${protocol} hides dot paths from discovery`, async () => { const pair = createMockTransportPair(protocol); const origin = new OriginProducer(); const [client, server] = await Promise.all([ connect(url, { transport: pair.client }), - accept(pair.server, url, { publish: origin.consume() }), + accept(pair.server, url, { publish: origin.consume(), version }), ]); // Published first, so a reader that may see it lists it before `visible`. diff --git a/js/net/src/lite/announce.test.ts b/js/net/src/lite/announce.test.ts index 69b34cb9e5a..86b212d308a 100644 --- a/js/net/src/lite/announce.test.ts +++ b/js/net/src/lite/announce.test.ts @@ -25,10 +25,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -37,7 +38,11 @@ async function bytes(f: (w: Writer) => Promise): Promise { } async function roundTrip(msg: AnnounceBroadcast, version: Version): Promise { - const reader = new Reader(undefined, await bytes((w) => encodeAnnounceBroadcast(w, msg, version))); + const reader = new Reader( + undefined, + await bytes((w) => encodeAnnounceBroadcast(w, msg, version), version), + version, + ); return decodeAnnounceBroadcast(reader, version); } @@ -74,8 +79,8 @@ test("AnnounceBroadcast skips an unknown type on draft-06", async () => { await w.u53(4); await w.u53(1); await w.u8(0); - }); - const reader = new Reader(undefined, encoded); + }, Version.DRAFT_06); + const reader = new Reader(undefined, encoded, Version.DRAFT_06); expect(await decodeAnnounceBroadcast(reader, Version.DRAFT_06)).toEqual({ status: "skipped" }); }); @@ -91,37 +96,49 @@ test("AnnounceBroadcast drops the route cost before draft-06", async () => { test("AnnounceBroadcast rejects cross-version forms", async () => { await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 1n }, Version.DRAFT_05)), + bytes((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 1n }, Version.DRAFT_05), Version.DRAFT_05), ).rejects.toThrow(); await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 1n, hops: [] }, Version.DRAFT_05)), + bytes( + (w) => encodeAnnounceBroadcast(w, { status: "restart", id: 1n, hops: [] }, Version.DRAFT_05), + Version.DRAFT_05, + ), ).rejects.toThrow(); await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "ended", suffix: Path.from("room/cam") }, Version.DRAFT_06)), + bytes( + (w) => encodeAnnounceBroadcast(w, { status: "ended", suffix: Path.from("room/cam") }, Version.DRAFT_06), + Version.DRAFT_06, + ), ).rejects.toThrow(); }); test("AnnounceBroadcast accepts explicit restart status on draft-05", async () => { - const wire = await bytes((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_05), + const wire = await bytes( + (w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_05), + Version.DRAFT_05, ); wire[1] = 2; - const got = await decodeAnnounceBroadcast(new Reader(undefined, wire), Version.DRAFT_05); + const got = await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_05), Version.DRAFT_05); expect(got).toEqual({ status: "active", suffix: Path.from("room/cam"), hops: [] }); }); test("AnnounceBroadcast rejects explicit restart status before draft-05", async () => { - const wire = await bytes((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_04), + const wire = await bytes( + (w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_04), + Version.DRAFT_04, ); wire[1] = 2; - await expect(decodeAnnounceBroadcast(new Reader(undefined, wire), Version.DRAFT_04)).rejects.toThrow(); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_04), Version.DRAFT_04), + ).rejects.toThrow(); }); async function requestRoundTrip(msg: AnnounceRequest, version: Version): Promise { - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version))); + const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version), version), version); return AnnounceRequest.decode(reader, version); } @@ -139,8 +156,8 @@ test("AnnounceRequest drops excludeHop on draft-06", async () => { const got = await requestRoundTrip(msg, Version.DRAFT_06); expect(got.excludeHop).toBe(0n); - const with05 = await bytes((w) => msg.encode(w, Version.DRAFT_05)); - const with06 = await bytes((w) => msg.encode(w, Version.DRAFT_06)); + const with05 = await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05); + const with06 = await bytes((w) => msg.encode(w, Version.DRAFT_06), Version.DRAFT_06); expect(with06.byteLength).toBeLessThan(with05.byteLength); }); @@ -158,7 +175,11 @@ test("AnnounceRequest carries hidden from draft-07", async () => { // conforming publisher. test("AnnounceOk accepts the reserved unknown origin", async () => { const msg = new AnnounceOk(UNKNOWN_HOP, 3); - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await AnnounceOk.decode(reader, Version.DRAFT_05); expect(got.hop).toBe(UNKNOWN_HOP); expect(got.active).toBe(3); @@ -166,7 +187,11 @@ test("AnnounceOk accepts the reserved unknown origin", async () => { test("AnnounceOk round-trips a declared origin", async () => { const msg = new AnnounceOk(HopSchema.parse(42n), 1); - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await AnnounceOk.decode(reader, Version.DRAFT_05); expect(got.hop).toBe(HopSchema.parse(42n)); expect(got.active).toBe(1); @@ -179,7 +204,9 @@ test("a hop chain that revisits a hop is refused in both directions", async () = // Outbound: refused before it reaches the wire. A receiver must close the session over // a repeated Hop ID, so sending one costs someone else their session. - await expect(bytes((w) => encodeAnnounceBroadcast(w, looped, Version.DRAFT_06))).rejects.toThrow("appears twice"); + await expect(bytes((w) => encodeAnnounceBroadcast(w, looped, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow( + "appears twice", + ); // Inbound: encode a chain that is legal, then rewrite its last hop to repeat the // first. Only a non-conforming sender produces these bytes, which is why they have to @@ -189,7 +216,7 @@ test("a hop chain that revisits a hop is refused in both directions", async () = suffix: Path.from("room"), hops: [four, eight, HopSchema.parse(9n)], }; - const forged = await bytes((w) => encodeAnnounceBroadcast(w, legal, Version.DRAFT_06)); + const forged = await bytes((w) => encodeAnnounceBroadcast(w, legal, Version.DRAFT_06), Version.DRAFT_06); const nine = forged.lastIndexOf(9); expect(nine).toBeGreaterThan(0); forged[nine] = 4; @@ -197,12 +224,12 @@ test("a hop chain that revisits a hop is refused in both directions", async () = // The type carries the consequence, not just the text: the subscriber's dispatch closes // the session on `instanceof ProtocolViolation`, so a plain Error here would reset the // stream and leave a nonconforming peer free to repeat itself. - await expect(decodeAnnounceBroadcast(new Reader(undefined, forged), Version.DRAFT_06)).rejects.toThrow( - ProtocolViolation, - ); - await expect(decodeAnnounceBroadcast(new Reader(undefined, forged), Version.DRAFT_06)).rejects.toThrow( - "appears twice", - ); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, forged, Version.DRAFT_06), Version.DRAFT_06), + ).rejects.toThrow(ProtocolViolation); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, forged, Version.DRAFT_06), Version.DRAFT_06), + ).rejects.toThrow("appears twice"); // Repeated unknowns are not a loop: 0 identifies nothing, so any number of hops may // be unknown. A lite-03 announcement is nothing but these. @@ -225,7 +252,7 @@ function unhex(text: string): Uint8Array { // Resolve every announcement on a lite-07 stream, as the subscriber does. async function resolveStream(data: Uint8Array) { - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, Version.DRAFT_07); const history = new AnnounceHistory(); const out: unknown[] = []; for (;;) { @@ -260,7 +287,7 @@ const GOLDEN_RESOLVED = [ // Pinned from the Rust encoder (`lite::compress::tests::golden_stream_is_pinned`), so the // JS decoder is checked against real compressed output. const GOLDEN = - "001600000a726f6f6d2f612f63616d000251116222000000000d0102036d696301017333010000020a00010180004444010000010101000d02010162020180005555010000"; + "001600000a726f6f6d2f612f63616d00029111a222000000000d0102036d69630101b3330100000209000101c04444010000010101000c020101620201c05555010000"; test("AnnounceHistory resolves the Rust encoder's compressed stream", async () => { expect(await resolveStream(unhex(GOLDEN))).toEqual(GOLDEN_RESOLVED); @@ -268,7 +295,7 @@ test("AnnounceHistory resolves the Rust encoder's compressed stream", async () = // JS always encodes literally; Rust decodes these bytes too (`js_literal_stream_decodes`). const JS_LITERAL = - "001600000a726f6f6d2f612f63616d000251116222000000001600000a726f6f6d2f612f6d6963000273336222000000020c0000028000444462220000000101010014000006726f6f6d2f620002800055556222000000"; + "001600000a726f6f6d2f612f63616d00029111a222000000001600000a726f6f6d2f612f6d69630002b333a222000000020b000002c04444a2220000000101010013000006726f6f6d2f620002c05555a222000000"; test("the literal draft-07 stream matches what Rust decodes", async () => { const wire = await bytes(async (w) => { @@ -291,7 +318,7 @@ test("the literal draft-07 stream matches what Rust decodes", async () => { { status: "active", suffix: Path.from("room/b"), hops: [hop(0x5555n), relay], cost }, v, ); - }); + }, Version.DRAFT_07); expect(hex(wire)).toBe(JS_LITERAL); expect(await resolveStream(wire)).toEqual(GOLDEN_RESOLVED); }); @@ -335,10 +362,10 @@ test("a keep without a base is a violation on draft-07", async () => { await w.u53(0); await w.u53(8); for (const b of [0, 1, 0, 0, 0, 0, 0, 0]) await w.u8(b); - }); - await expect(decodeAnnounceBroadcast(new Reader(undefined, wire), Version.DRAFT_07)).rejects.toThrow( - ProtocolViolation, - ); + }, Version.DRAFT_07); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07), + ).rejects.toThrow(ProtocolViolation); }); test("draft-06 has no room for a base", async () => { @@ -348,5 +375,31 @@ test("draft-06 has no room for a base", async () => { hops: [], pathBase: { distance: 1n, keep: 1 }, }; - await expect(bytes((w) => encodeAnnounceBroadcast(w, msg, Version.DRAFT_06))).rejects.toThrow(); + await expect(bytes((w) => encodeAnnounceBroadcast(w, msg, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow(); +}); + +// Costs saturate at 2^62-1 on every version: a larger one from a lite-07 peer reads as the +// ceiling, and one set locally goes out as the ceiling, so a cost always forwards to lite-06. +test("route costs saturate at 2^62-1 on every version", async () => { + const ceiling = 2n ** 62n - 1n; + const huge = 2n ** 64n - 1n; + for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { + const got = await roundTrip( + { status: "active", suffix: Path.from("x"), hops: [], cost: { warm: huge, cold: huge } }, + version, + ); + expect(got).toMatchObject({ cost: { warm: ceiling, cold: ceiling } }); + } + + // ANNOUNCE_START: path base, path keep, empty suffix, hop base, no hops, hop keep, then + // warm and cold at 2^64-1, which only lite-07's varints can carry. + const wire = await bytes(async (w) => { + await w.u53(0); + await w.u53(24); + for (const b of [0, 0, 0, 0, 0, 0]) await w.u8(b); + await w.u62(huge); + await w.u62(huge); + }, Version.DRAFT_07); + const got = await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07); + expect(got).toMatchObject({ cost: { warm: ceiling, cold: ceiling } }); }); diff --git a/js/net/src/lite/announce.ts b/js/net/src/lite/announce.ts index da874389fa6..69ee0c09445 100644 --- a/js/net/src/lite/announce.ts +++ b/js/net/src/lite/announce.ts @@ -176,16 +176,20 @@ async function decodeHopsBlock(r: Reader, version: Version): Promise<{ hops: Hop } // The route cost rides lite-06+ announcements as two varints, warm then cold; older -// versions carry neither. +// versions carry neither. Costs saturate at 2^62-1 on every version, even where lite-07's +// varints could carry more, so a cost always forwards to a peer on an older version. +const MAX_COST = 2n ** 62n - 1n; +const saturate = (v: bigint) => (v > MAX_COST ? MAX_COST : v); + async function encodeRouteCost(w: Writer, version: Version, cost: Cost | undefined) { if (!hasRouteCost(version)) return; - await w.u62(cost?.warm ?? 0n); - await w.u62(cost?.cold ?? 0n); + await w.u62(saturate(cost?.warm ?? 0n)); + await w.u62(saturate(cost?.cold ?? 0n)); } async function decodeRouteCost(r: Reader, version: Version): Promise { if (!hasRouteCost(version)) return undefined; - return { warm: await r.u62(), cold: await r.u62() }; + return { warm: saturate(await r.u62()), cold: saturate(await r.u62()) }; } // lite-06 message body (no discriminator; the type is carried outside the length prefix). diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index ebd4ed2cd6f..427c1e51a7b 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -118,6 +118,11 @@ export class Connection implements Established { this.url = url; this.#quic = quic; this.#session = session; + // The session stream was opened at the SETUP exchange's version; the rest of it speaks this one. + if (session) { + session.reader.version = version; + session.writer.version = version; + } this.version = versionName(version); this.#version = version; this.transport = transportOf(quic); @@ -212,7 +217,7 @@ export class Connection implements Established { // our session identity so the peer can filter // reflected announcements (lite-06 removed ANNOUNCE_REQUEST's exclude_hop for it). async #sendSetup(): Promise { - const writer = await Writer.open(this.#quic); + const writer = await Writer.open(this.#quic, { version: this.#version }); try { await writer.u53(DataType.Setup); const probe = await probeLevel(this.#quic, this.#version); @@ -226,7 +231,7 @@ export class Connection implements Established { async #runBidis() { for (;;) { - const stream = await Stream.accept(this.#quic); + const stream = await Stream.accept(this.#quic, this.#version); if (!stream) break; this.#runBidi(stream) @@ -267,7 +272,7 @@ export class Connection implements Established { } async #runUnis() { - const readers = new Readers(this.#quic); + const readers = new Readers(this.#quic, this.#version); for (;;) { const stream = await readers.next(); diff --git a/js/net/src/lite/datagram.test.ts b/js/net/src/lite/datagram.test.ts index ff2b8d04f77..80abce58db8 100644 --- a/js/net/src/lite/datagram.test.ts +++ b/js/net/src/lite/datagram.test.ts @@ -1,28 +1,38 @@ import { expect, test } from "bun:test"; import { Datagram } from "./datagram.ts"; +import { Version } from "./version.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); test("datagram body round-trips", async () => { - const dg = new Datagram(7n, 42, 1000, enc.encode("hello")); - const decoded = await Datagram.decode(dg.encode()); - expect(decoded.subscribe).toBe(7n); - expect(decoded.sequence).toBe(42); - expect(decoded.timestamp).toBe(1000); - expect(dec.decode(decoded.payload)).toBe("hello"); + for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { + const dg = new Datagram(7n, 42, 1000, enc.encode("hello")); + const decoded = await Datagram.decode(dg.encode(version), version); + expect(decoded.subscribe).toBe(7n); + expect(decoded.sequence).toBe(42); + expect(decoded.timestamp).toBe(1000); + expect(dec.decode(decoded.payload)).toBe("hello"); + } }); test("datagram body has no inner length prefix", () => { const dg = new Datagram(1n, 2, 3, enc.encode("world")); - const body = dg.encode(); + const body = dg.encode(Version.DRAFT_06); // Three single-byte varints (values < 64) followed by the raw 5-byte payload. expect(body.byteLength).toBe(8); expect(dec.decode(body.slice(3))).toBe("world"); }); +test("datagram body varints follow the version's encoding", () => { + // 100 takes the two-byte QUIC form on lite-06 and one leading-ones byte on lite-07. + const dg = new Datagram(100n, 100, 100, new Uint8Array()); + expect([...dg.encode(Version.DRAFT_06)]).toEqual([0x40, 0x64, 0x40, 0x64, 0x40, 0x64]); + expect([...dg.encode(Version.DRAFT_07)]).toEqual([0x64, 0x64, 0x64]); +}); + test("datagram body round-trips an empty payload", async () => { const dg = new Datagram(0n, 0, 0, new Uint8Array()); - const decoded = await Datagram.decode(dg.encode()); + const decoded = await Datagram.decode(dg.encode(Version.DRAFT_07), Version.DRAFT_07); expect(decoded.payload.byteLength).toBe(0); }); diff --git a/js/net/src/lite/datagram.ts b/js/net/src/lite/datagram.ts index 1f76707e17a..6fbb0df9d02 100644 --- a/js/net/src/lite/datagram.ts +++ b/js/net/src/lite/datagram.ts @@ -3,8 +3,8 @@ * * @module */ -import { Reader } from "../stream.ts"; -import * as Varint from "../varint.ts"; +import { encodeVarint, Reader } from "../stream.ts"; +import type { Version } from "./version.ts"; /** * A QUIC datagram body: `subscribe (i) | sequence (i) | timestamp (i) | payload (b)`. @@ -31,10 +31,10 @@ export class Datagram { } /** Encode the body to a single `Uint8Array` (no length prefix; the datagram boundary delimits it). */ - encode(): Uint8Array { - const subscribe = Varint.encodeTo(new ArrayBuffer(8), this.subscribe); - const sequence = Varint.encodeTo(new ArrayBuffer(8), this.sequence); - const timestamp = Varint.encodeTo(new ArrayBuffer(8), this.timestamp); + encode(version: Version): Uint8Array { + const subscribe = encodeVarint(this.subscribe, version); + const sequence = encodeVarint(this.sequence, version); + const timestamp = encodeVarint(this.timestamp, version); const out = new Uint8Array( subscribe.byteLength + sequence.byteLength + timestamp.byteLength + this.payload.byteLength, @@ -51,8 +51,8 @@ export class Datagram { } /** Decode a datagram body from the raw bytes of one QUIC datagram. */ - static async decode(data: Uint8Array): Promise { - const r = new Reader(undefined, data); + static async decode(data: Uint8Array, version: Version): Promise { + const r = new Reader(undefined, data, version); const subscribe = await r.u62(); const sequence = await r.u53(); const timestamp = await r.u53(); diff --git a/js/net/src/lite/fetch.test.ts b/js/net/src/lite/fetch.test.ts index 0eb06dca94e..c073a51cd90 100644 --- a/js/net/src/lite/fetch.test.ts +++ b/js/net/src/lite/fetch.test.ts @@ -19,6 +19,7 @@ async function encode(version: Version, fetch: Fetch): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await fetch.encode(writer, version); writer.close(); @@ -27,7 +28,7 @@ async function encode(version: Version, fetch: Fetch): Promise { } async function roundtrip(version: Version, fetch: Fetch): Promise { - const reader = new Reader(undefined, await encode(version, fetch)); + const reader = new Reader(undefined, await encode(version, fetch), version); return Fetch.decode(reader, version); } diff --git a/js/net/src/lite/goaway.test.ts b/js/net/src/lite/goaway.test.ts index 17d7a43800e..a051b010ce6 100644 --- a/js/net/src/lite/goaway.test.ts +++ b/js/net/src/lite/goaway.test.ts @@ -18,6 +18,7 @@ async function encode(msg: Goaway, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await msg.encode(writer, version); writer.close(); @@ -26,7 +27,7 @@ async function encode(msg: Goaway, version: Version): Promise { } async function decode(bytes: Uint8Array, version: Version): Promise { - const reader = new Reader(undefined, bytes); + const reader = new Reader(undefined, bytes, version); return await Goaway.decode(reader, version); } diff --git a/js/net/src/lite/group.test.ts b/js/net/src/lite/group.test.ts index e0df4212ed0..44e2c9b64e7 100644 --- a/js/net/src/lite/group.test.ts +++ b/js/net/src/lite/group.test.ts @@ -3,9 +3,13 @@ import { Producer } from "../group.ts"; import { Reader } from "../stream.ts"; import * as Varint from "../varint.ts"; import { readFrames } from "./group.ts"; +import { Version } from "./version.ts"; const SCALE = 1000; +// The frames below are QUIC varints, so the streams read them as lite-06. +const VERSION = Version.DRAFT_06; + /** Frames as a group stream carries them: a zigzag timestamp delta when timestamped, then the sized payload. */ function encode(frames: { delta?: number; payload: number[] }[]): Uint8Array { const bytes: number[] = []; @@ -24,6 +28,8 @@ function streamOf(chunks: Uint8Array[]): Reader { controller.close(); }, }), + undefined, + VERSION, ); } @@ -86,7 +92,7 @@ test("a stream that ends inside a frame rejects", async () => { test("stops once the group closes", async () => { const producer = new Producer(0); // Never ends: only the close can stop the read. - const stream = new Reader(new ReadableStream()); + const stream = new Reader(new ReadableStream(), undefined, VERSION); const done = readFrames(stream, producer, SCALE); producer.close(); await done; diff --git a/js/net/src/lite/message.ts b/js/net/src/lite/message.ts index eb289d6bf77..b48552e5542 100644 --- a/js/net/src/lite/message.ts +++ b/js/net/src/lite/message.ts @@ -1,6 +1,10 @@ import { Reader, Writer } from "../stream.ts"; -export async function encode(writer: Writer, f: (w: Writer) => Promise) { +/** The largest message body either side accepts, matching the Rust implementation. */ +const MAX_SIZE = 64 * 1024 * 1024; + +// Encodes a message with a varint size prefix, refusing a body the peer would reject. +export async function encode(writer: Writer, f: (w: Writer) => Promise, max = MAX_SIZE) { let scratch = new Uint8Array(); const temp = new Writer( @@ -27,24 +31,32 @@ export async function encode(writer: Writer, f: (w: Writer) => Promise) { } }, }), + writer.version, ); await f(temp); temp.close(); await temp.closed; + if (scratch.byteLength > max) { + throw new Error(`message too large: ${scratch.byteLength} bytes (max ${max})`); + } + await writer.u53(scratch.byteLength); if (scratch.byteLength > 0) { await writer.write(scratch); } } -// Reads a message with a varint size prefix. -export async function decode(reader: Reader, f: (r: Reader) => Promise): Promise { +// Reads a message with a varint size prefix, refusing an oversized body before reading it. +export async function decode(reader: Reader, f: (r: Reader) => Promise, max = MAX_SIZE): Promise { const size = await reader.u53(); + if (size > max) { + throw new Error(`message too large: ${size} bytes (max ${max})`); + } const data = await reader.read(size); - const limit = new Reader(undefined, data); + const limit = new Reader(undefined, data, reader.version); const msg = await f(limit); // Check that we consumed exactly the right number of bytes diff --git a/js/net/src/lite/priority.test.ts b/js/net/src/lite/priority.test.ts index 5adf91897ef..25733b381de 100644 --- a/js/net/src/lite/priority.test.ts +++ b/js/net/src/lite/priority.test.ts @@ -3,6 +3,7 @@ import { Producer as BroadcastProducer } from "../broadcast.ts"; import { type SendStream, Writer } from "../stream.ts"; import { Priority, sendOrder } from "./priority.ts"; +import { Version } from "./version.ts"; // The last position that still fits below the track priority. const MAX_POSITION = 2 ** 44 - 1; @@ -64,7 +65,7 @@ function ranking(options: { priority?: number; ordered?: boolean } = {}) { const open = () => { const stream = new WritableStream() as SendStream; streams.push(stream); - return new Writer(stream); + return new Writer(stream, Version.DRAFT_06); }; return { priority: new Priority(subscriber), open, streams, broadcast }; diff --git a/js/net/src/lite/probe.test.ts b/js/net/src/lite/probe.test.ts index 150f96c8c7d..ff44a4f7484 100644 --- a/js/net/src/lite/probe.test.ts +++ b/js/net/src/lite/probe.test.ts @@ -14,10 +14,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -26,7 +27,7 @@ async function bytes(f: (w: Writer) => Promise): Promise { } async function roundTrip(msg: Probe, version: Version = Version.DRAFT_05): Promise { - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version))); + const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version), version), version); const got = await Probe.decode(reader, version); expect(await reader.done()).toBe(true); return got; @@ -66,7 +67,9 @@ test("lite-03 carries the bitrate alone", async () => { // varint encoder converts with `BigInt`, which throws on one, and the publisher's // catch would then close the probe stream for the rest of the session. test("a fractional RTT must not reach the encoder", async () => { - await expect(bytes((w) => new Probe({ bitrate: 1_000, rtt: 12.34 }).encode(w, Version.DRAFT_05))).rejects.toThrow(); + await expect( + bytes((w) => new Probe({ bitrate: 1_000, rtt: 12.34 }).encode(w, Version.DRAFT_05), Version.DRAFT_05), + ).rejects.toThrow(); // Rounding first is what the publisher does, and it encodes cleanly. const got = await roundTrip(new Probe({ bitrate: 1_000, rtt: Math.round(12.34) })); diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 8bafb3d26dd..fa47bd12e32 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -44,6 +44,7 @@ test.each([Version.DRAFT_01, Version.DRAFT_03, Version.DRAFT_06])( await Promise.resolve(); const failure = new Error("peer stopped receiving announcements"); const stream = new Stream({ + version: version, readable: new ReadableStream(), writable: new WritableStream({ write() { @@ -95,6 +96,7 @@ test.each([ const written: Uint8Array[] = []; const stream = new Stream({ + version: version, readable: new ReadableStream(), writable: new WritableStream({ write(chunk) { @@ -131,8 +133,8 @@ async function subscribeEnd(sequences: number[], version: Version = Version.DRAF const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version }); + const server = await Stream.accept(pair.server, version); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }); @@ -194,8 +196,8 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -278,8 +280,8 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -342,8 +344,8 @@ test("lite draft-05: a subscribe update during the stream open still ranks the g return open(options); }; - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -391,8 +393,8 @@ test("lite draft-05: many concurrent groups share one subscription listener", as const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -450,7 +452,7 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async group.close(); track.writeGroup(group); - const client = await Stream.open(pair.client); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); // Accept by hand rather than via Stream.accept, so the test keeps the writable the // publisher ranks (a real WebTransportSendStream takes the same assignment). @@ -458,7 +460,7 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async const accepted = await incoming.read(); incoming.releaseLock(); if (accepted.done) throw new Error("publisher never saw the fetch stream"); - const server = new Stream(accepted.value); + const server = new Stream({ ...accepted.value, version: Version.DRAFT_05 }); const msg = new Fetch({ broadcast: Path.from("test"), track: "video", priority: 3, group: 7 }); try { @@ -544,7 +546,7 @@ async function servedSubscription( const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video", { maxAge: options.maxAge }); - const client = await Stream.open(pair.client); + const client = await Stream.open(pair.client, { version: version }); // Accept by hand rather than via Stream.accept, so the gate sits between the publisher // and the wire. @@ -554,7 +556,7 @@ async function servedSubscription( if (accepted.done) throw new Error("publisher never accepted the subscribe stream"); const gate = gateWrites(accepted.value.writable, options.gated ?? false); - const server = new Stream({ readable: accepted.value.readable, writable: gate.writable }); + const server = new Stream({ readable: accepted.value.readable, writable: gate.writable, version: version }); const msg = replaySubscribe({ id: 0n, @@ -596,7 +598,7 @@ async function servedSubscription( clearTimeout(timer); if (!next || next.done) return undefined; - const reader = new Reader(next.value); + const reader = new Reader(next.value, undefined, version); await reader.u53(); // stream type const header = await GroupMessage.decode(reader, version); @@ -1045,8 +1047,8 @@ test("lite draft-07: subscribe end waits for groups below a declared finish", as const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_07 }); + const server = await Stream.accept(pair.server, Version.DRAFT_07); if (!server) throw new Error("publisher never accepted the subscribe stream"); void publisher.runSubscribe( new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }), @@ -1100,8 +1102,8 @@ async function heldOpenEnd() { return createUni(options); }); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_07 }); + const server = await Stream.accept(pair.server, Version.DRAFT_07); if (!server) throw new Error("publisher never accepted the subscribe stream"); void publisher.runSubscribe( new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }), @@ -1177,8 +1179,8 @@ async function serve( const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_06 }); + const server = await Stream.accept(pair.server, Version.DRAFT_06); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = new Subscribe({ @@ -1220,7 +1222,7 @@ async function serve( clearTimeout(timer); if (!next || next.done) break; - const stream = new Reader(next.value); + const stream = new Reader(next.value, undefined, Version.DRAFT_06); await stream.u53(); // stream type const header = await GroupMessage.decode(stream, Version.DRAFT_06); @@ -1366,8 +1368,8 @@ async function saturatedGroup() { const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }); @@ -1445,8 +1447,8 @@ test("lite draft-05: a blocked group header is reset when the group expires", as const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); try { @@ -1532,8 +1534,8 @@ test("runProbe rounds a fractional smoothedRtt instead of killing the stream", a const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop()); // The subscriber opens the probe stream; the publisher only replies on it. - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the probe stream"); // `runProbe` loops until the stream closes, so close it rather than leaving the @@ -1602,8 +1604,8 @@ test("lite draft-05: a group that goes stale while its stream opens writes nothi return stale; }); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); try { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index dd0e764958d..2b4bb7a93e6 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -986,7 +986,7 @@ export class Publisher { // Convert the timestamp to the track's advertised timescale, matching #serveGroup. const ts = Math.round(datagram.timestamp.as(timescale)); - const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode(); + const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode(this.version); // No group fallback: drop anything that doesn't fit a single datagram. if (body.byteLength > maxSize) { @@ -1050,6 +1050,7 @@ export class Publisher { // in the order we asked, which is oldest-first, exactly backwards for live media. // Failing here drops the group and lets the next one compete for the next slot. const stream = await Writer.tryOpen(this.#quic, { + version: this.version, sendOrder: priority.rank(group.sequence), cancel: unsubscribed, waitUntilAvailable: false, diff --git a/js/net/src/lite/setup.test.ts b/js/net/src/lite/setup.test.ts index 371ebbad780..7a7b805142c 100644 --- a/js/net/src/lite/setup.test.ts +++ b/js/net/src/lite/setup.test.ts @@ -23,10 +23,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -35,7 +36,11 @@ async function bytes(f: (w: Writer) => Promise): Promise { } async function roundTrip(msg: Setup): Promise { - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await Setup.decode(reader, Version.DRAFT_05); expect(await reader.done()).toBe(true); return got; @@ -49,14 +54,14 @@ async function decodeParam(id: bigint, value: Uint8Array): Promise { await w.u62(id); await w.u53(value.byteLength); if (value.byteLength > 0) await w.write(value); - }); + }, Version.DRAFT_05); const framed = await bytes(async (w) => { await w.u53(body.byteLength); // Message size prefix await w.write(body); - }); + }, Version.DRAFT_05); - return await Setup.decode(new Reader(undefined, framed), Version.DRAFT_05); + return await Setup.decode(new Reader(undefined, framed, Version.DRAFT_05), Version.DRAFT_05); } test("empty SETUP round-trips on draft-05", async () => { @@ -98,15 +103,18 @@ test("Both is the wire default, so it is omitted rather than encoded", async () // Both must be the absence of the parameter, so a server that predates it decodes a // Both client back to Both. Assert the empty bag directly: comparing against another // default-constructed Setup would agree with itself even if we encoded Both. - const both = await bytes((w) => new Setup({ role: Role.Both }).encode(w, Version.DRAFT_05)); + const both = await bytes((w) => new Setup({ role: Role.Both }).encode(w, Version.DRAFT_05), Version.DRAFT_05); const emptyBag = await bytes(async (w) => { await w.u53(1); // Message size prefix: one byte of body follows await w.u53(0); // parameter count - }); + }, Version.DRAFT_05); expect(both).toEqual(emptyBag); // A directional role is still encoded, so the check above can actually fail. - const publisher = await bytes((w) => new Setup({ role: Role.Publisher }).encode(w, Version.DRAFT_05)); + const publisher = await bytes( + (w) => new Setup({ role: Role.Publisher }).encode(w, Version.DRAFT_05), + Version.DRAFT_05, + ); expect(publisher.byteLength).toBeGreaterThan(both.byteLength); }); @@ -140,12 +148,12 @@ test("hop 0 decodes as absent", async () => { }); test("SETUP is rejected before draft-05", async () => { - await expect(bytes((w) => new Setup().encode(w, Version.DRAFT_04))).rejects.toThrow(); + await expect(bytes((w) => new Setup().encode(w, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow(); }); test("SETUP decode is rejected before draft-05", async () => { - const framed = await bytes((w) => new Setup().encode(w, Version.DRAFT_05)); - await expect(Setup.decode(new Reader(undefined, framed), Version.DRAFT_04)).rejects.toThrow(); + const framed = await bytes((w) => new Setup().encode(w, Version.DRAFT_05), Version.DRAFT_05); + await expect(Setup.decode(new Reader(undefined, framed, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow(); }); test("empty path decodes as the root", async () => { @@ -157,3 +165,21 @@ test("empty path decodes as the root", async () => { test("SETUP rejects a path with malformed UTF-8", async () => { await expect(decodeParam(PARAM_PATH, new Uint8Array([0xc3, 0x28]))).rejects.toThrow(); }); + +test("SETUP encode stops at the 64 KiB receive limit", async () => { + // Count, id, and a 4-byte length varint precede the path. + const atLimit = 64 * 1024 - 6; + const msg = new Setup({ path: "a".repeat(atLimit) }); + expect((await roundTrip(msg)).path).toBe(msg.path); + + const over = new Setup({ path: "a".repeat(atLimit + 1) }); + await expect(bytes((w) => over.encode(w, Version.DRAFT_05), Version.DRAFT_05)).rejects.toThrow("too large"); +}); + +test("SETUP decode refuses an oversized length before reading the body", async () => { + // Only the prefix is present, so reading the body would fail with a different error. + const prefix = await bytes((w) => w.u53(64 * 1024 + 1), Version.DRAFT_05); + await expect(Setup.decode(new Reader(undefined, prefix, Version.DRAFT_05), Version.DRAFT_05)).rejects.toThrow( + "too large", + ); +}); diff --git a/js/net/src/lite/setup.ts b/js/net/src/lite/setup.ts index b49c08d385f..22b61b42680 100644 --- a/js/net/src/lite/setup.ts +++ b/js/net/src/lite/setup.ts @@ -6,9 +6,8 @@ */ import { type Hop, HopSchema } from "../hop.ts"; -import type { Reader, Writer } from "../stream.ts"; +import { encodeVarint, Reader, type Writer } from "../stream.ts"; import { decodeUtf8 } from "../util/utf8.ts"; -import * as Varint from "../varint.ts"; import * as Message from "./message.ts"; import { hasSetupStream, type Version } from "./version.ts"; @@ -24,6 +23,9 @@ const PARAM_HOP = 0x5n; /** Cap on the number of parameters in a bag, matching the Rust decoder. */ const MAX_PARAMS = 64; +/** SETUP only carries negotiation parameters, so it gets a far smaller cap than other messages. */ +const MAX_SETUP_SIZE = 64 * 1024; + /** * The probe capability an endpoint advertises in SETUP. * @@ -111,20 +113,21 @@ class Parameters { return this.#entries.get(id); } - /** Set a parameter to a varint value, replacing any existing entry. */ - setVarint(id: bigint, value: number | bigint) { - this.#entries.set(id, Varint.encode(Number(value))); + /** Set a parameter to a varint value in `version`'s encoding, replacing any existing entry. */ + setVarint(id: bigint, value: number | bigint, version: Version) { + this.#entries.set(id, encodeVarint(value, version)); } - /** Decode a parameter as a single varint, if present. Throws if trailing bytes remain. */ - getVarint(id: bigint): bigint | undefined { + /** Decode a parameter as a single varint in `version`'s encoding, if present. Throws if trailing bytes remain. */ + async getVarint(id: bigint, version: Version): Promise { const bytes = this.#entries.get(id); if (bytes === undefined) return undefined; - const [value, remain] = Varint.decode(bytes); - if (remain.byteLength !== 0) { + const r = new Reader(undefined, bytes, version); + const value = await r.u62(); + if (!(await r.done())) { throw new Error("trailing bytes after varint parameter"); } - return BigInt(value); + return value; } async encode(w: Writer) { @@ -222,29 +225,29 @@ export class Setup { } } - async #encode(w: Writer) { + async #encode(w: Writer, version: Version) { const params = new Parameters(); // None is the wire default, so omit it to keep the message empty when nothing is set. if (this.probe !== ProbeLevel.None) { - params.setVarint(PARAM_PROBE, this.probe); + params.setVarint(PARAM_PROBE, this.probe, version); } if (this.path !== undefined) { params.setBytes(PARAM_PATH, new TextEncoder().encode(this.path)); } // Both is the wire default, sent as the absence of the parameter. if (this.role !== Role.Both) { - params.setVarint(PARAM_ROLE, this.role); + params.setVarint(PARAM_ROLE, this.role, version); } if (this.hop !== undefined && this.hop !== 0n) { - params.setVarint(PARAM_HOP, this.hop); + params.setVarint(PARAM_HOP, this.hop, version); } await params.encode(w); } - static async #decode(r: Reader): Promise { + static async #decode(r: Reader, version: Version): Promise { const params = await Parameters.decode(r); - const probeCode = params.getVarint(PARAM_PROBE); + const probeCode = await params.getVarint(PARAM_PROBE, version); const probe = probeCode === undefined ? ProbeLevel.None : probeFromCode(probeCode); // An empty path is valid and means the same as omitting the parameter, so a @@ -252,11 +255,11 @@ export class Setup { const pathBytes = params.getBytes(PARAM_PATH); const path = pathBytes === undefined ? undefined : decodeUtf8(pathBytes); - const roleCode = params.getVarint(PARAM_ROLE); + const roleCode = await params.getVarint(PARAM_ROLE, version); const role = roleCode === undefined ? Role.Both : roleFromCode(roleCode); // 0 carries no identity (it cannot be excluded), so it decodes as absent. - const hopRaw = params.getVarint(PARAM_HOP); + const hopRaw = await params.getVarint(PARAM_HOP, version); const hop = hopRaw === undefined || hopRaw === 0n ? undefined : HopSchema.parse(hopRaw); return new Setup({ probe, path, role, hop }); @@ -265,12 +268,12 @@ export class Setup { /** Encode the SETUP message with its size prefix. Throws on pre-lite-05 versions. */ async encode(w: Writer, version: Version): Promise { Setup.#guard(version); - return Message.encode(w, this.#encode.bind(this)); + return Message.encode(w, (w) => this.#encode(w, version), MAX_SETUP_SIZE); } /** Decode a SETUP message with its size prefix. Throws on pre-lite-05 versions. */ static async decode(r: Reader, version: Version): Promise { Setup.#guard(version); - return Message.decode(r, Setup.#decode); + return Message.decode(r, (r) => Setup.#decode(r, version), MAX_SETUP_SIZE); } } diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index afd4c7c0a66..4da1af09185 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -32,6 +32,7 @@ async function encode(version: Version, resp: SubscribeResponse): Promise({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await encodeSubscribeResponse(writer, resp, version); writer.close(); @@ -40,12 +41,12 @@ async function encode(version: Version, resp: SubscribeResponse): Promise { - const reader = new Reader(undefined, await encode(version, resp)); + const reader = new Reader(undefined, await encode(version, resp), version); return decodeSubscribeResponse(reader, version); } async function encodeSubscribe(msg: Subscribe): Promise { - const writer = new Writer(new WritableStream()); + const writer = new Writer(new WritableStream(), Version.DRAFT_06); try { await msg.encode(writer, Version.DRAFT_06); } finally { @@ -60,6 +61,7 @@ async function encodeMessage( const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await message.encode(writer, version); writer.close(); @@ -90,7 +92,7 @@ test("Subscribe round-trips every option including startGroup 0", async () => { // Lite-06 carries the raw floor, and a floor of 0 with no frame offset is the same // absence of a constraint as no floor at all, so it canonicalizes to undefined. const got = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message), Version.DRAFT_06), Version.DRAFT_06, ); expect(got.priority).toBe(7); @@ -102,7 +104,7 @@ test("Subscribe round-trips every option including startGroup 0", async () => { // partway through group 0 (a catalog never leaves it). message.startFrame = 4; const resumed = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message), Version.DRAFT_06), Version.DRAFT_06, ); expect(resumed.startGroup).toBe(0); @@ -112,7 +114,7 @@ test("Subscribe round-trips every option including startGroup 0", async () => { // A pre-06 wire folds the vacuous floor back to absent: an explicit group 0 there // would mean "replay from the beginning", which is not what a floor of 0 asks for. const folded = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_05, message), Version.DRAFT_05), Version.DRAFT_05, ); expect(folded.startGroup).toBeUndefined(); @@ -127,7 +129,7 @@ test("SubscribeUpdate round-trips every option including startGroup 0", async () endGroup: 12, }); const got = await SubscribeUpdate.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message), Version.DRAFT_06), Version.DRAFT_06, ); expect(got.priority).toBe(8); @@ -137,7 +139,7 @@ test("SubscribeUpdate round-trips every option including startGroup 0", async () // The same fold as SUBSCRIBE on a pre-06 wire. const folded = await SubscribeUpdate.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_05, message), Version.DRAFT_05), Version.DRAFT_05, ); expect(folded.startGroup).toBeUndefined(); @@ -173,9 +175,9 @@ test("SubscribeDrop is gone on draft-07", async () => { // A draft-06 DROP is an unknown response type on draft-07. const wire06 = await encode(Version.DRAFT_06, drop); - await expect(decodeSubscribeResponse(new Reader(undefined, wire06), Version.DRAFT_07)).rejects.toThrow( - "unknown subscribe response type: 2", - ); + await expect( + decodeSubscribeResponse(new Reader(undefined, wire06, Version.DRAFT_07), Version.DRAFT_07), + ).rejects.toThrow("unknown subscribe response type: 2"); }); test("SubscribeDrop is type 0x2 on draft-05 and 0x1 on draft-04", async () => { diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 3d8d5254785..f203d8d295b 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1,7 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import { Signal } from "@moq/signals"; import type { Probe as ProbeStats } from "../connection/stats.ts"; -import { error, reason, StreamCode, StreamError } from "../error.ts"; +import { error, fromTransport, reason, StreamCode, StreamError } from "../error.ts"; import { HopSchema, isAnonymous, MAX_HOPS, Route, UNKNOWN_HOP } from "../hop.ts"; import * as Path from "../path.ts"; import { Writer } from "../stream.ts"; @@ -82,6 +82,7 @@ function announceHarness(version: Version, origin = 1n) { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -194,26 +195,35 @@ test("an unidentified responder keeps hop 0 on a nonempty chain", async () => { subscriber.close(); }); -test("a received empty hop list is filled with hop 0 and marked anonymous", async () => { - const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); - const announced = subscriber.announced(); - await settle(); +test("a received hop list naming no publisher is stamped per connection", async () => { + const first = async () => { + const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); + const announced = subscriber.announced(); + await settle(); - await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); - await send((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), - ); - expect(await nextRoute(announced)).toMatchObject({ - prefix: Path.from("room"), - kind: "start", - route: { hops: [UNKNOWN_HOP] }, - }); + await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); + await send((w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), + ); + const update = await nextRoute(announced); + expect(update).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + const hops = update?.route.hops ?? []; + expect(hops).toHaveLength(2); + expect(hops[0]).not.toBe(UNKNOWN_HOP); + // The 0 after the stamp keeps the unnamed publisher ranked as anonymous. + expect(hops[1]).toBe(UNKNOWN_HOP); + expect(update && isAnonymous(update.route)).toBe(true); + + announced.close(); + subscriber.close(); + return hops[0]; + }; - announced.close(); - subscriber.close(); + // A reconnect is a new connection, so the same unnamed publisher reads as a new one. + expect(await first()).not.toBe(await first()); }); -test("a received chain with hop 0 is marked anonymous", async () => { +test("a received chain starting with hop 0 keeps it behind the stamp", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); @@ -226,50 +236,71 @@ test("a received chain with hop 0 is marked anonymous", async () => { Version.DRAFT_06, ), ); - expect(await nextRoute(announced)).toMatchObject({ - prefix: Path.from("room"), - kind: "start", - }); + const update = await nextRoute(announced); + expect(update).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + const [stamp, ...rest] = update?.route.hops ?? []; + expect(stamp).not.toBe(UNKNOWN_HOP); + expect(rest).toEqual([UNKNOWN_HOP, PUBLISHER_A, PEER]); announced.close(); subscriber.close(); }); -test("a restart from the same publisher is a route change, not a republish", async () => { +test("a restart updates the route in place, even from another publisher", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); + const room = Path.from("room"); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); + await send((w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: room, hops: [PUBLISHER_A] }, Version.DRAFT_06), + ); + expect(await nextRoute(announced)).toMatchObject({ prefix: room, kind: "start" }); + const held = subscriber.consume(room); + + // Same publisher over an identical route: no metadata to forward, so nothing surfaces. + await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); + + // A reprice from the same publisher surfaces, which proves the identical restart above + // emitted nothing. The same publisher keeps sharing one broadcast. await send((w) => encodeAnnounceBroadcast( w, - { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_A] }, + { status: "restart", id: 0n, hops: [PUBLISHER_A], cost: { warm: 4n, cold: 4n } }, Version.DRAFT_06, ), ); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); - - // Same publisher over an identical route. In-flight subscriptions resume across it, - // and there is no metadata to forward, so the subscriber must not surface a restart. - await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); + expect(await nextRoute(announced)).toMatchObject({ prefix: room, kind: "update" }); + const same = subscriber.consume(room); + expect(same.closed).toBe(held.closed); - // A different publisher took the path: nothing carries over, so this one does surface, - // as an end before the start. Reaching it proves the identical reroute above emitted nothing. + // A different publisher took the path: an in-place update, never a retraction. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_B] }, Version.DRAFT_06)); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "end" }); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + expect(await nextRoute(announced)).toMatchObject({ + prefix: room, + kind: "update", + route: { hops: [PUBLISHER_B, PEER] }, + }); - // A third publisher takes over. The replacement above has to leave its own publisher on - // record, or this one reads as a first announcement and skips the end. - await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_C] }, Version.DRAFT_06)); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "end" }); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + // The holder keeps its broadcast to drain, but the next consume starts fresh rather + // than reusing the old publisher's cached track info. + const fresh = subscriber.consume(room); + expect(fresh.closed).not.toBe(held.closed); + expect(held.closed.peek()).toBeUndefined(); - // And the new owner's own reroute is still transparent. + // A third publisher is another update. The one above has to leave its own publisher on + // record, or this one would not read as a change. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_C] }, Version.DRAFT_06)); + expect(await announced.next()).toMatchObject({ + prefix: room, + kind: "update", + route: { hops: [PUBLISHER_C, PEER] }, + }); + expect(subscriber.consume(room).closed).not.toBe(fresh.closed); + await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, Version.DRAFT_06)); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "end" }); + expect(await nextRoute(announced)).toMatchObject({ prefix: room, kind: "end" }); announced.close(); subscriber.close(); @@ -326,33 +357,41 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { // On lite-05 a restart travels as a duplicate ANNOUNCE rather than its own message. await send(active([PUBLISHER_A])); await send(active([PUBLISHER_B])); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "end" }); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "update" }); announced.close(); subscriber.close(); }); // A responder that withholds its Hop ID sends the reserved 0, and an empty chain means it -// originated the path itself, so the advertisement names nobody. Two such advertisements can -// be unrelated publishers, so a restart must replace the broadcast rather than reroute it: -// cached track info and in-flight subscriptions must not splice across them. Mirrors the Rust -// `unknown_publisher_restart_replaces` regression. -test("a restart from an unidentified publisher replaces rather than reroutes", async () => { +// originated the path itself, so the advertisement names nobody and the connection stamps it. +// A restart on the same connection keeps that stamp, so it is a reprice that updates in place +// and keeps the shared broadcast. Only a first hop that changes names a new publisher. +test("a restart from an unidentified publisher updates in place", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); + const room = Path.from("room"); await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); + await send((w) => encodeAnnounceBroadcast(w, { status: "active", suffix: room, hops: [] }, Version.DRAFT_06)); + expect(await nextRoute(announced)).toMatchObject({ prefix: room, kind: "start" }); + const held = subscriber.consume(room); + await send((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), + encodeAnnounceBroadcast( + w, + { status: "restart", id: 0n, hops: [], cost: { warm: 4n, cold: 4n } }, + Version.DRAFT_06, + ), ); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + expect(await nextRoute(announced)).toMatchObject({ prefix: room, kind: "update" }); + expect(subscriber.consume(room).closed).toBe(held.closed); - // Nobody is named on either side, so this is not provably the same content. - await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [] }, Version.DRAFT_06)); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "end" }); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + // Naming a publisher is a change of publisher: the next consume starts fresh. + await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); + expect(await nextRoute(announced)).toMatchObject({ prefix: room, kind: "update" }); + expect(subscriber.consume(room).closed).not.toBe(held.closed); announced.close(); subscriber.close(); @@ -364,6 +403,7 @@ async function probeBytes(probes: Probe[], version: Version): Promise({ write: (chunk) => void chunks.push(new Uint8Array(chunk)) }), + version, ); for (const probe of probes) await probe.encode(writer, version); writer.close(); @@ -693,11 +733,10 @@ test("a draft-05 duplicate start is still a restart", async () => { // Same publisher over a new route: transparent, and emphatically not an error. await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_05)); - // A different publisher does surface, which is what proves the reroute above passed. + // A different publisher surfaces as an update, which is what proves the reroute above passed. const replaced: AnnounceBroadcast = { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_B] }; await send((w) => encodeAnnounceBroadcast(w, replaced, Version.DRAFT_05)); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "end" }); - expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "start" }); + expect(await nextRoute(announced)).toMatchObject({ prefix: Path.from("room"), kind: "update" }); announced.close(); subscriber.close(); @@ -821,6 +860,7 @@ async function answerTrackInfo(stream: FakeStream): Promise { const chunks: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void chunks.push(new Uint8Array(chunk)) }), + Version.DRAFT_05, ); await new TrackInfo({}).encode(writer, Version.DRAFT_05); for (const chunk of chunks) stream.inbound.enqueue(chunk); @@ -886,3 +926,85 @@ test("a fetch started after the subscriber closes rejects without opening a stre expectCut(err, undefined); expect(streams.length).toBe(0); }); + +test("an already-aborted fetch rejects without opening a stream", async () => { + const { quic, streams } = fakeSession(); + const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); + const cause = new Error("gone"); + + const err = await subscriber + .fetchGroup(Path.from("room"), "video", 0, { signal: AbortSignal.abort(cause) }) + .catch((err: unknown) => err); + expect(err).toBe(cause); + expect(streams.length).toBe(0); +}); + +// Coalesced fetches share one FETCH stream. An abort releases only that caller's share; the +// stream is cancelled once the last sharer leaves, before its FETCH is sent if it can be. +test("one of two fetch sharers aborting leaves the other's fetch", async () => { + const { quic, streams } = fakeSession(); + const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); + + const controller = new AbortController(); + const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: controller.signal }); + const b = subscriber.fetchGroup(Path.from("room"), "video", 0); + + await drainUntil(() => streams.length === 1); + await answerTrackInfo(streams[0]); + await drainUntil(() => streams.length === 2); + await streams[1].reading; + + const cause = new Error("gone"); + controller.abort(cause); + expect(await a.catch((err: unknown) => err)).toBe(cause); + + let aborted = false; + void streams[1].aborted.then(() => { + aborted = true; + }); + // An empty-group FIN accepts the fetch. + streams[1].inbound.close(); + const group = await b; + expect(await group.readFrame()).toBeUndefined(); + expect(aborted).toBe(false); + + subscriber.close(); +}); + +test.each([ + ["the TRACK_INFO", "track"], + ["the FETCH", "fetch"], +] as const)("the last fetch sharer aborting during %s cancels it", async (_, stage) => { + const { quic, streams } = fakeSession(); + const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); + + const first = new AbortController(); + const second = new AbortController(); + const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: first.signal }); + const b = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: second.signal }); + + await drainUntil(() => streams.length === 1); + await streams[0].reading; + if (stage === "fetch") { + await answerTrackInfo(streams[0]); + await drainUntil(() => streams.length === 2); + await streams[1].reading; + } + + first.abort(new Error("first")); + second.abort(new Error("second")); + expect(((await a.catch((err: unknown) => err)) as Error).message).toBe("first"); + expect(((await b.catch((err: unknown) => err)) as Error).message).toBe("second"); + + if (stage === "track") { + // The TRACK_INFO still completes, but no FETCH is sent for the abandoned group. + await answerTrackInfo(streams[0]); + for (let i = 0; i < 100; i++) await Promise.resolve(); + expect(streams.length).toBe(1); + } else { + const err = fromTransport(await streams[1].aborted) as StreamError; + expect(err.code).toBe(StreamCode.Cancel); + } + + subscriber.close(); +}); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 7af0c71518e..228ec19d495 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -5,13 +5,14 @@ import type { Probe as ProbeStats } from "../connection/stats.ts"; import { BroadcastCache } from "../consume.ts"; import { controlTimeout, error, ProtocolViolation, reason, StreamCode, StreamError, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Hop, MAX_HOPS, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { Cost, type Hop, MAX_HOPS, type Route, randomHop, routesEqual, stampHops, UNKNOWN_HOP } from "../hop.ts"; import { groupBounds, hiddenBelow, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import { type OpenOptions, type Reader, Stream } from "../stream.ts"; import { TAIL_GRACE_MS, Tail } from "../tail.ts"; import * as Time from "../time.ts"; import type * as track from "../track.ts"; +import { untilAborted } from "../util/abort.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; import { overrideBroadcastWire, wireOf } from "../wire.ts"; import { @@ -82,6 +83,8 @@ interface SubscribeEntry { // The group streams received, so the subscription can wait for the ones still owed // after the publisher ends it. tail: Tail; + // The first group the SUBSCRIBE asked for, if any. + requested?: number; // The first group the publisher serves (SUBSCRIBE_START) and the track's exclusive end // (SUBSCRIBE_END), once it declares them. start?: number; @@ -134,6 +137,10 @@ export class Subscriber { // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. #consumes = new BroadcastCache(); + // A random Hop ID of this connection's own, written as the first hop of any chain that + // names no publisher, so a publisher that reconnects reads as a new one. + #stamp: Hop; + // Dedup in-flight one-shot fetches, keyed by [broadcast, track, sequence]. Concurrent (or // repeat, while still open) fetchGroup() calls for the same group share one FETCH stream and // each get an independent mirror; the entry is evicted once the group closes. @@ -168,6 +175,7 @@ export class Subscriber { this.#quic = quic; this.version = version; this.hop = hop; + this.#stamp = randomHop(); this.#probe = probe; this.#peerSetup = peerSetup; } @@ -211,7 +219,7 @@ export class Subscriber { // Lite03/04: lands the initial set once the stream goes quiet. let quiet: announce.Quiet | undefined; try { - stream = await Stream.open(this.#quic); + stream = await Stream.open(this.#quic, { version: this.version }); } catch (err: unknown) { announced.close(error(err)); return; @@ -246,9 +254,9 @@ export class Subscriber { // the map instead would let a later announce take the path, and the skipped one's // `endedId` would then retract that one's state. // - // `publisher` is what lets a restart tell a route change (same publisher, - // subscriptions resume) from a replacement (a new generation took the path, - // nothing carries over). + // `publisher` is what lets a restart tell a route change (same publisher) from a + // new publisher on the route, whose content the next consume must not share + // with the old one's. type Advertisement = { publisher: Hop | undefined; live: boolean; @@ -267,16 +275,16 @@ export class Subscriber { // they go on record and obey the same one-per-path rule: the initial set // naming a path twice is the same violation as two ANNOUNCE_STARTs for it, // and the record is what catches either. Draft01/02 carry no hop ids and no - // ANNOUNCE_OK, so nothing names the publisher. + // ANNOUNCE_OK, so this connection's stamp names the publisher. for (const suffix of init.suffixes) { const path = Path.join(prefix, suffix); if (advertised.has(path)) { throw new ProtocolViolation(`duplicate announce for ${path}`); } - const route = { hops: [UNKNOWN_HOP], cost: Cost.zero }; + const route = { hops: [this.#stamp, UNKNOWN_HOP], cost: Cost.zero }; const live = visible(path); const captures = scopeCaptures(scope, path); - advertised.set(path, { publisher: undefined, live, route, captures }); + advertised.set(path, { publisher: this.#stamp, live, route, captures }); if (!live) continue; console.debug(`announced: broadcast=${path} active=true`); announced.append({ prefix: path, captures, kind: "start", route }); @@ -421,23 +429,17 @@ export class Subscriber { } // The first hop identifies the original publisher; an empty chain means the - // peer itself originated it. See `restart_announce` in the Rust subscriber. - const publisher = hops?.[0] ?? responderOrigin; - - // A publisher with no identity (an empty chain from a peer that withheld its - // own id, or a lite-03 UNKNOWN placeholder) never proves continuity: two such - // advertisements can be unrelated publishers. Mirrors the - // `publisher == Hop::UNKNOWN` arm of the Rust `restart_announce`. - const identified = publisher !== undefined && publisher !== UNKNOWN_HOP; - const fullHops = + // peer itself originated it. One that names nobody (lite-01..03, or a peer + // reporting 0) gets this connection's stamp in front of its 0. + const fullHops = stampHops( hops !== undefined && responderOrigin !== undefined ? [...hops, responderOrigin] - : [...(hops ?? [])]; - // A received empty list is the anonymous mark, not a local announcement. - if (fullHops.length === 0) fullHops.push(UNKNOWN_HOP); + : [...(hops ?? [])], + this.#stamp, + ); // Appending a withheld AnnounceOk(0) onto a 32-entry list is the same // drop Rust's Hops::push makes: do not expose an overlong chain. - if (fullHops.length > MAX_HOPS) { + if (fullHops === undefined || fullHops.length > MAX_HOPS) { console.debug(`announced: broadcast=${path} dropped (hop chain at MAX_HOPS)`); advertised.set(path, { publisher: undefined, @@ -447,6 +449,7 @@ export class Subscriber { }); continue; } + const publisher = fullHops[0]; const route: Route = { hops: fullHops, cost: cost ?? Cost.zero }; const captures = scopeCaptures(scope, path); if (!visible(path)) { @@ -455,30 +458,22 @@ export class Subscriber { } // A second advertisement for a path we already carry is a restart: either an - // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. + // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. It updates the + // route in place, so a forwarder re-prices without retracting. const previous = advertised.get(path); if (previous?.live) { - if (identified && previous.publisher === publisher) { - // Same publisher, new route. In-flight subscriptions resume across it. - // Emit the route so a forwarder can re-price without retracting. - if (!routesEqual(previous.route, route)) { - advertised.set(path, { publisher, live: true, route, captures }); - console.debug(`announced: broadcast=${path} rerouted`); - announced.append({ prefix: path, captures, kind: "update", route }); - } else { - console.debug(`announced: broadcast=${path} rerouted`); - } - continue; + // A different publisher took the path. Subscriptions already open drain + // the old copy, but the next consume starts fresh rather than reusing the + // old publisher's cached track info. + if (previous.publisher !== publisher) this.#consumes.evict(path); + advertised.set(path, { publisher, live: true, route, captures }); + console.debug(`announced: broadcast=${path} rerouted`); + if (!routesEqual(previous.route, route)) { + announced.append({ prefix: path, captures, kind: "update", route }); } - - // A different publisher took the path, so cached track info and existing - // subscriptions must not carry over. Surface a real end before the start. - retract(); + continue; } - // After `retract()`, which clears the entry: the path is advertised again, by - // whoever just took it over. Recording it before would leave nothing behind, so - // the *next* takeover would read as a first announcement and skip its own end. advertised.set(path, { publisher, live: true, route, captures }); console.debug(`announced: broadcast=${path} active=true`); @@ -612,7 +607,7 @@ export class Subscriber { const subscriptionUpdates = this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02 ? undefined - : this.#runSubscriptionUpdates(id, broadcast, producer, msg, stream); + : this.#runSubscriptionUpdates(id, broadcast, entry, msg, stream); // Terminal conditions (stream end, track close, a failed subscription update) settle at most // once; race them into one stable promise so the demand loop doesn't re-subscribe each pass. @@ -678,10 +673,23 @@ export class Subscriber { } // Register before opening SUBSCRIBE so a racing GROUP stream finds the entry. - const entry: SubscribeEntry = { track: producer, timescale, tail: new Tail() }; + const entry: SubscribeEntry = { + track: producer, + timescale, + // The effective max age is the stopgap grace: the wrong clock (it bounds + // presentation-time drift), but it is how long the subscriber was willing to wait + // for a late group anyway. Already the smaller of the subscriber's and the track's. + tail: new Tail({ + grace: () => { + const maxAge = producer.subscription.peek()?.maxAge ?? Time.Milli.zero; + return maxAge > 0 ? maxAge : TAIL_GRACE_MS; + }, + }), + requested: msg.startGroup, + }; this.#subscribes.set(id, entry); - state.stream = await Stream.open(this.#quic); + state.stream = await Stream.open(this.#quic, { version: this.version }); await state.stream.writer.u53(StreamId.Subscribe); await msg.encode(state.stream.writer, this.version); @@ -698,7 +706,7 @@ export class Subscriber { // Opens a TRACK stream, reads the single TRACK_INFO, and FINs. Lite-05+ only. async #trackInfo(broadcast: Path.Valid, track: string): Promise { - return this.#exchange(undefined, async (stream) => { + return this.#exchange({ version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Track); await new TrackMessage(broadcast, track).encode(stream.writer, this.version); const info = await TrackInfo.decode(stream.reader, this.version); @@ -711,7 +719,7 @@ export class Subscriber { // Opens a stream and runs a request/response exchange on it, resetting the stream if `run` // fails. Subscriber.close() also resets it while `run` is pending, so a peer that never // answers cannot hold it open, and a stream that opens after the close is reset at once. - async #exchange(options: OpenOptions | undefined, run: (stream: Stream) => Promise): Promise { + async #exchange(options: OpenOptions, run: (stream: Stream) => Promise): Promise { const closed = this.#closed.signal; closed.throwIfAborted(); const stream = await Stream.open(this.#quic, options); @@ -757,24 +765,32 @@ export class Subscriber { sequence: number, options: track.FetchGroupOptions = {}, ): Promise { + options.signal?.throwIfAborted(); + // Coalesce onto a still-open fetch of the same group so we don't open a second FETCH // stream (and re-download it); each caller reads an independent mirror. + // + // Reserve each caller's mirror before the fetch starts or is awaited: the fetch watches + // demand from the start, and a fast FIN cannot discard frames before these callers + // receive their handles. An abort closes only this caller's mirror, so the stream is + // cancelled once the last one leaves. const key = JSON.stringify([broadcast, track, sequence]); let entry = this.#fetches.get(key); - if (!entry || entry.group.isClosed) { + let consumer: netGroup.Consumer; + if (entry && !entry.group.isClosed) { + consumer = entry.group.mirror(); + } else { const group = new netGroup.Producer(sequence); - entry = { group, accepted: this.#runFetch(broadcast, track, sequence, options, group) }; + consumer = group.mirror(); + entry = { group, accepted: this.#runFetch(broadcast, track, sequence, options.priority ?? 0, group) }; this.#fetches.set(key, entry); void group.closed.then(() => { if (this.#fetches.get(key)?.group === group) this.#fetches.delete(key); }); } - // Reserve each caller's mirror before awaiting acceptance so the pump sees demand, - // and a fast FIN cannot discard frames before these callers receive their handles. - const consumer = entry.group.mirror(); try { - await entry.accepted; + await untilAborted(entry.accepted, options.signal); return consumer; } catch (err) { consumer.close(); @@ -783,12 +799,13 @@ export class Subscriber { } // Open the FETCH stream and pump the response into the shared group. Setup errors close the - // group, evict the entry, and reject every caller waiting for acceptance. + // group, evict the entry, and reject every caller waiting for acceptance. A setup every caller + // has abandoned is cancelled the same way. async #runFetch( broadcast: Path.Valid, track: string, sequence: number, - options: track.FetchGroupOptions, + priority: number, group: netGroup.Producer, ): Promise { try { @@ -799,10 +816,10 @@ export class Subscriber { // Lite has no FETCH_OK, so a publisher that never answers would hold the setup forever. // Subscriber.close() closing the group releases every caller at any stage, and resets // the streams the setup opened. - const setup = this.#fetchSetup(broadcast, track, sequence, options); + const setup = this.#fetchSetup(broadcast, track, sequence, priority, group); let accepted: { stream: Stream; info: TrackInfo }; try { - accepted = await untilClosed(group, setup); + accepted = await untilAbandoned(group, setup); } catch (err: unknown) { // A setup that finishes just after the close hands back a stream nobody will read. void setup.then( @@ -820,20 +837,21 @@ export class Subscriber { } // Resolve the track's timescale, then open the FETCH stream and wait for it to be accepted. + // Closing the group during that wait resets the stream. async #fetchSetup( broadcast: Path.Valid, track: string, sequence: number, - options: track.FetchGroupOptions, + priority: number, + group: netGroup.Producer, ): Promise<{ stream: Stream; info: TrackInfo }> { - const info = await this.#trackInfo(broadcast, track); - const priority = options.priority ?? 0; - return this.#exchange({ sendOrder: sendOrder({ priority }) }, async (stream) => { + const info = await untilClosed(group, this.#trackInfo(broadcast, track)); + return this.#exchange({ sendOrder: sendOrder({ priority }), version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Fetch); await new FetchMessage({ broadcast, track, priority, group: sequence }).encode(stream.writer, this.version); // A byte or an empty-group FIN accepts the fetch; a reset rejects it. // done() buffers that byte so the response pump can decode it normally. - await stream.reader.done(); + await untilClosed(group, stream.reader.done()); return { stream, info }; }); } @@ -898,6 +916,9 @@ export class Subscriber { if ("start" in resp) { entry.start = resp.start.group; + // The groups the SUBSCRIBE asked for below it are unavailable, whatever the + // demand asks later. + if (entry.requested !== undefined) entry.tail.account(entry.requested, entry.start); } else if ("end" in resp) { if (entry.end !== undefined) throw new ProtocolViolation("duplicate SUBSCRIBE_END"); entry.end = resp.end.group; @@ -907,7 +928,13 @@ export class Subscriber { try { entry.track.finishAt(entry.end); } catch (err) { - throw new ProtocolViolation(`invalid SUBSCRIBE_END: ${reason(error(err))}`); + // lite-05 specified an inclusive end, and @moq/net 0.1.3 to 0.1.9 sent one, so + // there an end below a received group only costs the early boundary: the FIN + // still finishes the track. Later drafts made it exclusive. + if (this.version !== Version.DRAFT_05) { + throw new ProtocolViolation(`invalid SUBSCRIBE_END: ${reason(error(err))}`); + } + console.warn(`invalid SUBSCRIBE_END: ${reason(error(err))}`); } } else if ("drop" in resp) { entry.tail.account(resp.drop.start, resp.drop.end + 1); @@ -923,9 +950,6 @@ export class Subscriber { // headers arrived keep reading until their own FIN or reset. #settleTail(entry: SubscribeEntry): Promise { const { tail, track } = entry; - // Already the smaller of the subscriber's and the track's max age. - const maxAge = track.subscription.peek()?.maxAge ?? Time.Milli.zero; - const grace = maxAge > 0 ? maxAge : TAIL_GRACE_MS; const complete = () => { if (entry.streams !== undefined) return tail.streams >= entry.streams; @@ -933,13 +957,17 @@ export class Subscriber { if (entry.end === undefined) return false; // Without SUBSCRIBE_START the publisher served no group at all. if (entry.start === undefined) return true; - const bounds = groupBounds(track.subscription.peek()?.groups ?? {}); - const start = Math.max(entry.start, bounds.start); + // Owed from the floor the demand last asked for, which an update can move either + // way, or where SUBSCRIBE_START resolved a live-edge one. The groups the SUBSCRIBE + // asked for below its SUBSCRIBE_START were accounted for when it arrived. + const groups = track.subscription.peek()?.groups; + const bounds = groupBounds(groups ?? {}); + const start = groups?.start === undefined ? entry.start : bounds.start; const end = bounds.end === undefined ? entry.end : Math.min(entry.end, bounds.end); return tail.covers(start, end); }; - return tail.settle(complete, grace, track.closed); + return tail.settle(complete, track.closed); } /** @@ -956,10 +984,11 @@ export class Subscriber { async #runSubscriptionUpdates( id: bigint, broadcast: Path.Valid, - track: track.Producer, + entry: SubscribeEntry, msg: Subscribe, stream: Stream, ): Promise { + const track = entry.track; const stopped: Promise = race([track.closed, stream.reader.closed]).then(() => null); let lastSent: track.Subscription = { priority: msg.priority, @@ -984,6 +1013,12 @@ export class Subscriber { const bounds = groupBounds(current.groups); if (emptyRange({ startGroup: bounds.start, endGroup: bounds.end })) throw new Error(EMPTY_RANGE); + // A lowered floor owes groups nobody asked for until now. + if (current.groups?.start !== undefined) { + const floor = lastSent.groups?.start === undefined ? entry.start : groupBounds(lastSent.groups).start; + entry.tail.demand(bounds.start, floor ?? Number.POSITIVE_INFINITY); + } + // Round-trip the other Subscribe parameters so the publisher doesn't // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxAge/etc. const update = new SubscribeUpdate({ @@ -1031,6 +1066,16 @@ export class Subscriber { const read = tail.open(group.sequence); try { + // The publisher contradicted its own end, which no later group can repair. lite-05 + // specified an inclusive end, so its last group lands on it: the write below drops + // only that group there. + if (entry.end !== undefined && group.sequence >= entry.end && this.version !== Version.DRAFT_05) { + const violation = new ProtocolViolation( + `group ${group.sequence} is at or past the declared end ${entry.end}`, + ); + track.close(violation); + throw violation; + } track.writeGroup(producer); // Block until the timescale is known; the group's stream can arrive before @@ -1108,7 +1153,7 @@ export class Subscriber { // Decode one datagram body and hand it to the matching subscription's producer. Drops the // datagram (best-effort) if the subscription is unknown/closed or its timescale isn't resolved. async #routeDatagram(payload: Uint8Array): Promise { - const dg = await DatagramMessage.decode(payload); + const dg = await DatagramMessage.decode(payload, this.version); const entry = this.#subscribes.get(dg.subscribe); if (!entry) return; // Unknown or already-closed subscription. @@ -1161,7 +1206,7 @@ export class Subscriber { // transport hiccup) MUST NOT tear down the connection. On error, drop the // estimates so consumers know they're stale. try { - const stream = await Stream.open(this.#quic); + const stream = await Stream.open(this.#quic, { version: this.version }); await stream.writer.u53(StreamId.Probe); for (;;) { @@ -1221,6 +1266,17 @@ async function untilClosed(group: netGroup.Producer, step: Promise): Promi return value as T; } +// Like untilClosed, but also cancels once every reader has left. Demand is level-triggered, so a +// caller that coalesces onto the group before the check re-arms it. +async function untilAbandoned(group: netGroup.Producer, step: Promise): Promise { + const idle: unique symbol = Symbol("idle"); + for (;;) { + const value = await untilClosed(group, race([step, group.unused().then((): typeof idle => idle)])); + if (value !== idle) return value as T; + if (!group.used.peek()) throw new StreamError(StreamCode.Cancel, { message: "cancel" }); + } +} + /** * A broadcast consumed from a lite session. It resolves `track.Consumer.query()` and * `.fetchGroup()` over the wire (lite-05+ TRACK / FETCH streams) by reaching into the diff --git a/js/net/src/lite/tail.test.ts b/js/net/src/lite/tail.test.ts index 245791287da..b6717c2860e 100644 --- a/js/net/src/lite/tail.test.ts +++ b/js/net/src/lite/tail.test.ts @@ -6,6 +6,7 @@ import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; import { Milli } from "../time.ts"; +import type { Groups } from "../track.ts"; import { Group as GroupMessage } from "./group.ts"; import { StreamId } from "./stream.ts"; import { @@ -36,7 +37,7 @@ function groupStream(subscriber: Subscriber, sequence: number) { const readable = new ReadableStream({ start: (c) => (controller = c) }); const handled = subscriber.runGroup( new GroupMessage({ subscribe: 0n, sequence }), - new Reader(readable, undefined, undefined), + new Reader(readable, undefined, subscriber.version), ); return { write: (payload: string) => controller.enqueue(frame(payload)), @@ -51,19 +52,19 @@ function groupStream(subscriber: Subscriber, sequence: number) { * it answers TRACK_INFO, then writes whatever responses the test asks for on the subscribe * stream and FINs it when told. */ -async function subscribed(version: Version, maxAge = GRACE) { +async function subscribed(version: Version, maxAge = GRACE, groups?: Groups) { const pair = createMockTransportPair(ALPN_05); const subscriber = new Subscriber(pair.client, version, randomHop()); - const reader = subscriber.consume(Path.from("room")).track("video").subscribe({ maxAge }); + const reader = subscriber.consume(Path.from("room")).track("video").subscribe({ maxAge, groups }); - const info = await Stream.accept(pair.server); + const info = await Stream.accept(pair.server, version); if (!info) throw new Error("the subscriber never asked for TRACK_INFO"); expect(await info.reader.u53()).toBe(StreamId.Track); await TrackMessage.decode(info.reader, version); await new TrackInfo({ maxAge: 60_000 }).encode(info.writer, version); info.close(); - const sub = await Stream.accept(pair.server); + const sub = await Stream.accept(pair.server, version); if (!sub) throw new Error("the subscriber never subscribed"); expect(await sub.reader.u53()).toBe(StreamId.Subscribe); await Subscribe.decode(sub.reader, version); @@ -210,16 +211,91 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver expect(reader.final()).toBe(0); }); - test("a SUBSCRIBE_END below a group already received aborts the track", async () => { + // lite-05 specified an inclusive end, so there the group costs only its own stream. + test(`a group at or past SUBSCRIBE_END ${version === Version.DRAFT_05 ? "is dropped" : "aborts the track"}`, async () => { const { subscriber, reader, respond } = await subscribed(version); await respond({ start: new SubscribeStart(0) }); + await respond({ end: new SubscribeEnd(2, 2) }); + expect(await reader.finished()).toBe(2); + + await groupStream(subscriber, 2).handled; + if (version === Version.DRAFT_05) { + expect(await settlesWithin(Promise.resolve(reader.closed), 50)).toBe(false); + } else { + expect(await reader.closed).toBeInstanceOf(ProtocolViolation); + } + }); + + test("a floor below SUBSCRIBE_START owes nothing below it", async () => { + const { subscriber, reader, respond, fin } = await subscribed(version, Milli(60_000), { + start: { included: 1 }, + }); + await respond({ start: new SubscribeStart(3) }); + const group = groupStream(subscriber, 3); + group.finish(); + await group.handled; + await respond({ end: new SubscribeEnd(4, 1) }); + await fin(); + + expect((await reader.recvGroup())?.sequence).toBe(3); + expect(await settlesWithin(reader.recvGroup(), 1000)).toBe(true); + expect(await reader.closed).toBeNull(); + }); + + test.skipIf(version === Version.DRAFT_07)("a lowered floor owes the groups it newly asked for", async () => { + const maxAge = Milli(60_000); + const { subscriber, respond, fin } = await subscribed(version, maxAge, { start: { included: 3 } }); + await respond({ start: new SubscribeStart(3) }); + const group = groupStream(subscriber, 3); + group.write("3.0"); + group.finish(); + await group.handled; + + // A second reader lowers the floor, which the subscription forwards as an update. + const lower = subscriber + .consume(Path.from("room")) + .track("video") + .subscribe({ maxAge, groups: { start: { included: 1 } } }); + await respond({ end: new SubscribeEnd(4, 1) }); + await fin(); + // Long enough for a subscription that owed nothing more to have ended. + await new Promise((resolve) => setTimeout(resolve, 50)); + + // QUIC does not order streams, so the lowered groups land after the FIN. + for (const sequence of [1, 2]) { + const late = groupStream(subscriber, sequence); + late.write(`${sequence}.0`); + late.finish(); + await late.handled; + } + + const received: number[] = []; + for (;;) { + const next = await lower.recvGroup(); + if (!next) break; + received.push(next.sequence); + } + expect(received).toContain(1); + expect(received).toContain(2); + expect(await lower.closed).toBeNull(); + }); + + // lite-05 specified an inclusive end, and @moq/net 0.1.3 to 0.1.9 sent one, so there an end + // below a received group only costs the early boundary. + test(`a SUBSCRIBE_END below a group already received ${version === Version.DRAFT_05 ? "finishes clean" : "aborts the track"}`, async () => { + const { subscriber, reader, respond, fin } = await subscribed(version); + await respond({ start: new SubscribeStart(0) }); const group = groupStream(subscriber, 3); group.finish(); await group.handled; await respond({ end: new SubscribeEnd(2, 2) }); - const closed = await reader.closed; - expect(closed).toBeInstanceOf(Error); + if (version === Version.DRAFT_05) { + await fin(); + expect(await reader.closed).toBeNull(); + } else { + expect(await reader.closed).toBeInstanceOf(ProtocolViolation); + } }); }); diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index d385e2826b3..034642fc9ab 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -17,10 +17,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -34,7 +35,11 @@ test("TrackInfo round-trips on draft-05", async () => { maxAge: 2000, timescale: 90000, }); - const reader = new Reader(undefined, await bytes((w) => info.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await TrackInfo.decode(reader, Version.DRAFT_05); expect(got.priority).toBe(7); expect(got.maxAge).toBe(2000); @@ -43,14 +48,18 @@ test("TrackInfo round-trips on draft-05", async () => { test("TrackInfo defaults match cross-language wire bytes", async () => { const info = new TrackInfo(infoDefaults()); - expect(await bytes((w) => info.encode(w, Version.DRAFT_05))).toEqual( - new Uint8Array([0x0c, 0x00, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8]), + expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( + new Uint8Array([0x0c, 0x7f, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8]), ); }); test("Track request round-trips on draft-05", async () => { const msg = new Track(Path.from("room"), "video"); - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await Track.decode(reader, Version.DRAFT_05); expect(got.broadcast).toBe(Path.from("room")); expect(got.track).toBe("video"); @@ -58,7 +67,7 @@ test("Track request round-trips on draft-05", async () => { test("TRACK_INFO is rejected before draft-05", async () => { const info = new TrackInfo({ timescale: 90000 }); - await expect(bytes((w) => info.encode(w, Version.DRAFT_04))).rejects.toThrow(); + await expect(bytes((w) => info.encode(w, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow(); }); test("TrackInfo round-trips valid boundary metadata", async () => { @@ -67,7 +76,11 @@ test("TrackInfo round-trips valid boundary metadata", async () => { maxAge: Number.MAX_SAFE_INTEGER - 1, timescale: Number.MAX_SAFE_INTEGER, }); - const reader = new Reader(undefined, await bytes((w) => info.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await TrackInfo.decode(reader, Version.DRAFT_05); expect(got.priority).toBe(255); expect(got.maxAge).toBe(Number.MAX_SAFE_INTEGER - 1); @@ -116,6 +129,7 @@ test("mutated TrackInfo fields emit no bytes on encode", async () => { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + Version.DRAFT_05, ); await expect(info.encode(writer, Version.DRAFT_05)).rejects.toThrow(RangeError); writer.close(); @@ -127,8 +141,8 @@ test("mutated TrackInfo fields emit no bytes on encode", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { test(`optional max age survives ${version}`, async () => { for (const maxAge of [undefined, 0, 30_000, Number.MAX_SAFE_INTEGER]) { - const encoded = await bytes((w) => new TrackInfo({ maxAge }).encode(w, version)); - const got = await TrackInfo.decode(new Reader(undefined, encoded), version); + const encoded = await bytes((w) => new TrackInfo({ maxAge }).encode(w, version), version); + const got = await TrackInfo.decode(new Reader(undefined, encoded, version), version); expect(got.maxAge).toBe( version !== Version.DRAFT_07 && maxAge === Number.MAX_SAFE_INTEGER ? undefined : maxAge, ); @@ -138,8 +152,8 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { test(`legacy unlimited value fits the old u53 reader on ${version}`, async () => { - const encoded = await bytes((w) => new TrackInfo({}).encode(w, version)); - const old = new Reader(undefined, encoded); + const encoded = await bytes((w) => new TrackInfo({}).encode(w, version), version); + const old = new Reader(undefined, encoded, version); await old.u53(); // message length await old.u8(); // priority if (version === Version.DRAFT_05) await old.bool(); @@ -156,12 +170,12 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { if (version === Version.DRAFT_05) await w.bool(false); await w.u62(age); await w.u53(1000); - }); + }, version); const encoded = await bytes(async (w) => { await w.u53(payload.length); await w.write(payload); - }); - const info = await TrackInfo.decode(new Reader(undefined, encoded), version); + }, version); + const info = await TrackInfo.decode(new Reader(undefined, encoded, version), version); expect(info.maxAge).toBe(age < boundary ? Number(age) : undefined); } }); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 7aa4e5ff6a9..6b184909b30 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -2,7 +2,7 @@ import { expect, spyOn, test } from "bun:test"; import { getter, Once, race, Signal } from "@moq/signals"; import { type Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; import { StreamCode, StreamError } from "./error.ts"; -import { HopSchema, Route } from "./hop.ts"; +import { HopSchema, Route, stampHops } from "./hop.ts"; import type { Consumer, Table } from "./origin.ts"; import { Producer } from "./origin.ts"; import * as Path from "./path.ts"; @@ -127,6 +127,23 @@ test("unscoped broadcast getters share one fresh snapshot per mutation", () => { origin.close(); }); +test("a stamped route ranks below an identified one of the same length", () => { + const origin = new Producer(); + const path = Path.from("room/alice"); + const stamped = stampHops([], HopSchema.parse(5n)); + if (!stamped) throw new Error("an empty chain always has room"); + const identified = [HopSchema.parse(11n), PEER]; + expect(stamped).toHaveLength(identified.length); + + const legacy = wireOf(origin).receive(path, { hops: stamped, cost: 0n }); + const named = wireOf(origin).receive(path, { hops: identified, cost: 9n }); + expect(origin.consume().broadcasts().peek().get(path)).toEqual(Route.normalize({ hops: identified, cost: 9n })); + + legacy.close(); + named.close(); + origin.close(); +}); + test("an announced local path competes with a received route on cost", async () => { const origin = new Producer(); const consumer = origin.consume(); diff --git a/js/net/src/stream.test.ts b/js/net/src/stream.test.ts index 1c54ff92c81..c2b770f2f3a 100644 --- a/js/net/src/stream.test.ts +++ b/js/net/src/stream.test.ts @@ -11,10 +11,14 @@ import { StreamError, } from "./error.ts"; import { Version } from "./ietf/version.ts"; -import { type Cursor, Reader, Stream, Writer } from "./stream.ts"; +import { Version as Lite } from "./lite/version.ts"; +import { type Cursor, Reader, Stream, type StreamVersion, Writer } from "./stream.ts"; import { TimeoutError } from "./util/timeout.ts"; import { U64 } from "./util/u64.ts"; +// The generic tests below read and write QUIC varints on the moq-lite stream code registry. +const QUIC = Lite.DRAFT_06; + // Helper to create a writable stream that captures written data function createTestWritableStream(): { stream: WritableStream; written: Uint8Array[] } { const written: Uint8Array[] = []; @@ -40,7 +44,7 @@ function concatChunks(chunks: Uint8Array[]): Uint8Array { test("Writer u8", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u8(42); await writer.u8(255); @@ -56,7 +60,7 @@ test("Writer u8", async () => { test("Writer u8 refuses out of range values before emitting bytes", async () => { for (const value of [-1, 1.5, 256, Number.NaN, Number.POSITIVE_INFINITY]) { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await expect(writer.u8(value)).rejects.toThrow(RangeError); writer.close(); await writer.closed; @@ -66,7 +70,7 @@ test("Writer u8 refuses out of range values before emitting bytes", async () => test("Writer i32", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.i32(0); await writer.i32(-1); @@ -87,7 +91,7 @@ test("Writer i32", async () => { test("Writer u53", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u53(0); await writer.u53(63); // MAX_U6 @@ -119,7 +123,7 @@ test("Writer u53 refuses unsafe values before emitting bytes", async () => { 2 ** 62 + 1, ]) { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await expect(writer.u53(value)).rejects.toThrow(RangeError); writer.close(); await writer.closed; @@ -129,7 +133,7 @@ test("Writer u53 refuses unsafe values before emitting bytes", async () => { test("Writer string", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.string("hello"); await writer.string("🎉"); @@ -140,7 +144,7 @@ test("Writer string", async () => { const result = concatChunks(written); // Create a reader to parse the result - const reader = new Reader(undefined, result); + const reader = new Reader(undefined, result, QUIC); const str1 = await reader.string(); const str2 = await reader.string(); @@ -150,14 +154,14 @@ test("Writer string", async () => { }); test("Reader string rejects malformed UTF-8", async () => { - const reader = new Reader(undefined, new Uint8Array([2, 0xc3, 0x28])); + const reader = new Reader(undefined, new Uint8Array([2, 0xc3, 0x28]), QUIC); await expect(reader.string()).rejects.toThrow(); }); test("Reader u8", async () => { const data = new Uint8Array([42, 255, 0, 128]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); expect(await reader.u8()).toBe(42); expect(await reader.u8()).toBe(255); @@ -169,7 +173,7 @@ test("Reader u8", async () => { test("Reader read with exact sizes", async () => { const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); const chunk1 = await reader.read(3); expect(chunk1).toEqual(new Uint8Array([1, 2, 3])); @@ -185,7 +189,7 @@ test("Reader read with exact sizes", async () => { test("Reader read with zero size", async () => { const data = new Uint8Array([1, 2, 3]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); const chunk = await reader.read(0); expect(chunk).toEqual(new Uint8Array([])); @@ -197,7 +201,7 @@ test("Reader read with zero size", async () => { test("Reader readAll", async () => { const data = new Uint8Array([1, 2, 3, 4, 5]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); // Read some data first await reader.read(2); @@ -214,7 +218,7 @@ test("Reader u53 varint decoding", async () => { const testValues = [0, 63, 64, 16383, 16384, 1073741823, 1073741824, Number.MAX_SAFE_INTEGER]; const { stream, written } = createTestWritableStream(); - const testWriter = new Writer(stream); + const testWriter = new Writer(stream, QUIC); for (const value of testValues) { await testWriter.u53(value); @@ -224,7 +228,7 @@ test("Reader u53 varint decoding", async () => { await testWriter.closed; const data = concatChunks(written); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); for (const expectedValue of testValues) { const actualValue = await reader.u53(); @@ -241,13 +245,13 @@ test("Reader u53 rejects integers that cannot be represented exactly", async () for (const value of wireValues) { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u62(value); writer.close(); await writer.closed; // A failed decode consumes nothing; the stream is unusable after it anyway. - const reader = new Reader(undefined, concatChunks(written)); + const reader = new Reader(undefined, concatChunks(written), QUIC); await expect(reader.u53()).rejects.toThrow(`value larger than 53-bits: ${value}`); expect(await reader.done()).toBe(false); } @@ -257,7 +261,7 @@ test("Reader u62 varint decoding", async () => { const testValues = [0n, 63n, 64n, 16383n, 16384n, 1073741823n, 1073741824n, 9007199254740991n]; // MAX_U53 const { stream, written } = createTestWritableStream(); - const testWriter = new Writer(stream); + const testWriter = new Writer(stream, QUIC); for (const value of testValues) { await testWriter.u62(value); @@ -267,7 +271,7 @@ test("Reader u62 varint decoding", async () => { await testWriter.closed; const data = concatChunks(written); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); for (const expectedValue of testValues) { const actualValue = await reader.u62(); @@ -281,7 +285,7 @@ test("Reader string decoding", async () => { const testStrings = ["hello", "🎉", "", "world with spaces", "multi\nline\nstring"]; const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); for (const str of testStrings) { await writer.string(str); @@ -291,7 +295,7 @@ test("Reader string decoding", async () => { await writer.closed; const data = concatChunks(written); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); for (const expectedString of testStrings) { const actualString = await reader.string(); @@ -313,7 +317,7 @@ test("Reader from stream", async () => { }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); // Read all data const result = await reader.readAll(); @@ -332,7 +336,7 @@ test("Reader stream with partial reads", async () => { }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); // Read specific amounts that cross chunk boundaries const first = await reader.read(3); // Should span first two chunks @@ -357,7 +361,7 @@ test("Reader preserves returned views across fills", async () => { controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); const head = await reader.read(1); expect(head).toEqual(new Uint8Array([1])); const joined = await reader.read(3); @@ -376,7 +380,7 @@ test("Reader returns a view of a chunk that already holds the read", async () => controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); const read = await reader.read(3); expect(read.buffer).toBe(chunk.buffer); expect(read).toEqual(new Uint8Array([1, 2, 3])); @@ -390,7 +394,7 @@ test("Reader joins every chunk a read spans", async () => { controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); expect(await reader.u8()).toBe(0); expect(await reader.read(98)).toEqual(Uint8Array.from({ length: 98 }, (_, index) => index + 1)); expect(await reader.done()).toBe(false); @@ -400,13 +404,13 @@ test("Reader joins every chunk a read spans", async () => { test("Reader u53 decodes two-byte stream type prefixes", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u53(0x40); writer.close(); await writer.closed; - const reader = new Reader(undefined, concatChunks(written)); + const reader = new Reader(undefined, concatChunks(written), QUIC); expect(await reader.u53()).toBe(0x40); expect(await reader.done()).toBe(true); }); @@ -416,7 +420,7 @@ const sized = (c: Cursor) => c.read(c.u53()); test("Reader tryDecode drains every buffered message, then consumes nothing from a partial one", async () => { let controller!: ReadableStreamDefaultController; - const reader = new Reader(new ReadableStream({ start: (c) => (controller = c) })); + const reader = new Reader(new ReadableStream({ start: (c) => (controller = c) }), undefined, QUIC); controller.enqueue(new Uint8Array([1, 0xa, 2, 0xb, 0xc, 3, 0xd])); expect(await reader.done()).toBe(false); @@ -434,13 +438,13 @@ test("Reader tryDecode drains every buffered message, then consumes nothing from }); test("Reader tryDecode holds only the decode that ran short to the bytes it needs", () => { - const reader = new Reader(undefined, new Uint8Array([2, 0xa])); + const reader = new Reader(undefined, new Uint8Array([2, 0xa]), QUIC); expect(reader.tryDecode(sized)).toBeUndefined(); expect(reader.tryDecode((c) => c.u8())).toBe(2); }); test("Reader decode rejects a stream that ends inside a message", async () => { - const reader = new Reader(undefined, new Uint8Array([3, 0xa])); + const reader = new Reader(undefined, new Uint8Array([3, 0xa]), QUIC); expect(reader.tryDecode(sized)).toBeUndefined(); await expect(reader.decode(sized)).rejects.toThrow("unexpected end of stream"); }); @@ -449,13 +453,13 @@ test("Reader refuses an oversized value even when it is already buffered", async const size = 64 * 1024 * 1024 + 1; const buffer = new Uint8Array(4 + size); buffer.set([0x84, 0x00, 0x00, 0x01]); // the 4-byte varint for size - await expect(new Reader(undefined, buffer).string()).rejects.toThrow("exceeds max size"); - await expect(new Reader(undefined, buffer.subarray(4)).read(size)).rejects.toThrow("exceeds max size"); + await expect(new Reader(undefined, buffer, QUIC).string()).rejects.toThrow("exceeds max size"); + await expect(new Reader(undefined, buffer.subarray(4), QUIC).read(size)).rejects.toThrow("exceeds max size"); }); test("Reader refuses a buffered decode whose fields together exceed the max size", async () => { const half = 32 * 1024 * 1024; - const reader = new Reader(undefined, new Uint8Array(2 * half + 1)); + const reader = new Reader(undefined, new Uint8Array(2 * half + 1), QUIC); await expect(reader.decode((c) => [c.read(half), c.read(half + 1)])).rejects.toThrow("exceeds max size"); }); @@ -477,6 +481,8 @@ test("Reader closed rejects with the decoded reset code", async () => { new ReadableStream({ start: (controller) => controller.error(new Reset(2)), }), + undefined, + QUIC, ); const err = await reader.closed.then( @@ -492,6 +498,7 @@ test("Writer closed rejects with the decoded reset code", async () => { new WritableStream({ start: (controller) => controller.error(new Reset(31)), }), + QUIC, ); const err = await writer.closed.then( @@ -504,7 +511,7 @@ test("Writer closed rejects with the decoded reset code", async () => { test("Writer reset forwards only a stream error code", async () => { const session = new SessionError(SessionCode.Unauthorized); - const sessionWriter = new Writer(new WritableStream()); + const sessionWriter = new Writer(new WritableStream(), QUIC); sessionWriter.reset(session); const sessionResult = await sessionWriter.closed.then( () => undefined, @@ -513,7 +520,7 @@ test("Writer reset forwards only a stream error code", async () => { expect(sessionResult).toBe(session); const stream = new StreamError(StreamCode.DeliveryTimeout); - const streamWriter = new Writer(new WritableStream()); + const streamWriter = new Writer(new WritableStream(), QUIC); streamWriter.reset(stream); const streamResult = await streamWriter.closed.then( () => undefined, @@ -524,7 +531,7 @@ test("Writer reset forwards only a stream error code", async () => { }); test("closed is stable, so racing it per frame does not allocate", async () => { - const reader = new Reader(new ReadableStream()); + const reader = new Reader(new ReadableStream(), undefined, QUIC); expect(reader.closed).toBe(reader.closed); }); @@ -592,7 +599,7 @@ function stalledBidiTransport() { test("open gives up on a peer that never frees a bidi slot", async () => { const { quic, freeSlot, discarded } = stalledBidiTransport(); - await expect(Stream.open(quic, { timeout: EXPIRES_MS })).rejects.toThrow(/timed out/); + await expect(Stream.open(quic, { timeout: EXPIRES_MS, version: QUIC })).rejects.toThrow(/timed out/); freeSlot(); await discarded; @@ -601,7 +608,7 @@ test("open gives up on a peer that never frees a bidi slot", async () => { test("open waits for a bidi slot rather than failing on a busy session", async () => { const { quic, freeSlot } = stalledBidiTransport(); - const opening = Stream.open(quic, { timeout: OUTLASTS_TEST_MS }); + const opening = Stream.open(quic, { timeout: OUTLASTS_TEST_MS, version: QUIC }); expect(await Promise.race([opening.then(() => "opened"), Promise.resolve("waiting")])).toBe("waiting"); freeSlot(); @@ -614,7 +621,7 @@ test("tryOpen gives up on a cancel that settled before the open", async () => { const { quic, freeSlot, aborted } = stalledTransport(); freeSlot(); - expect(await Writer.tryOpen(quic, { cancel: Promise.resolve() })).toBeUndefined(); + expect(await Writer.tryOpen(quic, { cancel: Promise.resolve(), version: QUIC })).toBeUndefined(); await aborted; }); @@ -626,7 +633,7 @@ test("tryOpen gives up when cancelled, resetting a stream that opens afterwards" cancel = resolve; }); - const opening = Writer.tryOpen(quic, { cancel: cancelled }); + const opening = Writer.tryOpen(quic, { cancel: cancelled, version: QUIC }); cancel(); expect(await opening).toBeUndefined(); @@ -642,7 +649,7 @@ test("tryOpen rethrows a rejected cancel, resetting a stream that opens afterwar fail = reject; }); - const opening = Writer.tryOpen(quic, { cancel: cancelled }); + const opening = Writer.tryOpen(quic, { cancel: cancelled, version: QUIC }); fail(new Error("stop sending")); await expect(opening).rejects.toThrow("stop sending"); @@ -655,7 +662,9 @@ test("tryOpen rethrows a rejected cancel, resetting a stream that opens afterwar test("tryOpen gives up when the peer never frees a slot", async () => { const { quic, freeSlot, aborted } = stalledTransport(); - expect(await Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: EXPIRES_MS })).toBeUndefined(); + expect( + await Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: EXPIRES_MS, version: QUIC }), + ).toBeUndefined(); freeSlot(); await aborted; @@ -664,7 +673,7 @@ test("tryOpen gives up when the peer never frees a slot", async () => { test("tryOpen returns the stream when a slot is available", async () => { const { quic, freeSlot } = stalledTransport(); - const opening = Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: OUTLASTS_TEST_MS }); + const opening = Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: OUTLASTS_TEST_MS, version: QUIC }); freeSlot(); expect(await opening).toBeInstanceOf(Writer); @@ -680,7 +689,7 @@ test("tryOpen shares one reaction on a cancel reused across opens", async () => const cancel = new Promise(() => {}); const reactions = spyOn(cancel, "then"); for (let i = 0; i < 100; i++) { - expect(await Writer.tryOpen(quic, { cancel })).toBeInstanceOf(Writer); + expect(await Writer.tryOpen(quic, { cancel, version: QUIC })).toBeInstanceOf(Writer); } expect(reactions).toHaveBeenCalledTimes(1); }); @@ -698,10 +707,10 @@ test("open waits for a stream slot instead of rejecting once the peer's limit is }, } as unknown as WebTransport; - await Stream.open(quic, { sendOrder: 7 }); - await Writer.open(quic); + await Stream.open(quic, { sendOrder: 7, version: QUIC }); + await Writer.open(quic, { version: QUIC }); // The one path that opens faster than a peer can retire streams opts out. - await Writer.open(quic, { waitUntilAvailable: false }); + await Writer.open(quic, { waitUntilAvailable: false, version: QUIC }); expect(options).toEqual([ { sendOrder: 7, waitUntilAvailable: true }, @@ -714,7 +723,7 @@ test("open waits for a stream slot instead of rejecting once the peer's limit is // each row says what it costs on a draft that predates the registration. TOO_FAR_BEHIND // arrived in draft-17, and moq-lite's own 48-63 codes are in no draft at all. for (const [version, tooFarBehind] of [ - [undefined, StreamCode.TooFarBehind], + [QUIC, StreamCode.TooFarBehind], [Version.DRAFT_14, StreamCode.Internal], [Version.DRAFT_19, StreamCode.TooFarBehind], [Version.DRAFT_20, StreamCode.TooFarBehind], @@ -723,9 +732,9 @@ for (const [version, tooFarBehind] of [ for (const [reason, expected] of [ [new Lagged(), tooFarBehind], [new Reset(5), tooFarBehind], - [new FrameTooLarge(), version === undefined ? StreamCode.FrameTooLarge : StreamCode.Internal], - [new GroupTooLarge(), version === undefined ? StreamCode.GroupTooLarge : StreamCode.Internal], - [new NotFound("broadcast"), version === undefined ? StreamCode.NotFound : StreamCode.Internal], + [new FrameTooLarge(), version === QUIC ? StreamCode.FrameTooLarge : StreamCode.Internal], + [new GroupTooLarge(), version === QUIC ? StreamCode.GroupTooLarge : StreamCode.Internal], + [new NotFound("broadcast"), version === QUIC ? StreamCode.NotFound : StreamCode.Internal], // Assigned by every draft, so these survive the translation intact. [new TimeoutError("open"), StreamCode.DeliveryTimeout], [new ProtocolViolation("bad message"), StreamCode.SessionClosed], @@ -793,20 +802,69 @@ for (const [version, tooFarBehind] of [ ); const err = await reader.closed.catch((err: unknown) => err); expect(err).toBeInstanceOf(StreamError); - expect((err as StreamError).code).toBe(version === undefined ? StreamCode(70) : StreamCode.Internal); - if (version !== undefined) expect((err as StreamError).message).toContain("70"); + expect((err as StreamError).code).toBe(version === QUIC ? StreamCode(70) : StreamCode.Internal); + if (version !== QUIC) expect((err as StreamError).message).toContain("70"); }); } +async function written(version: Lite, f: (w: Writer) => Promise): Promise { + const { stream, written } = createTestWritableStream(); + const writer = new Writer(stream, version); + await f(writer); + writer.close(); + await writer.closed; + return [...concatChunks(written)]; +} + +test("lite-07 varints count leading ones; lite-06 keeps the QUIC form", async () => { + expect(await written(Lite.DRAFT_06, (w) => w.u53(100))).toEqual([0x40, 0x64]); + expect(await written(Lite.DRAFT_07, (w) => w.u53(100))).toEqual([0x64]); + expect(await written(Lite.DRAFT_07, (w) => w.u62(2n ** 62n - 1n))).toEqual([ + 0xff, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, + ]); + + expect(await new Reader(undefined, new Uint8Array([0x40, 0x64]), Lite.DRAFT_06).u53()).toBe(100); + expect(await new Reader(undefined, new Uint8Array([0x80, 0x64]), Lite.DRAFT_07).u53()).toBe(100); + // The 7-byte form, reserved only on draft-17. + const seven = new Uint8Array([0xfd, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd]); + expect(await new Reader(undefined, seven, Lite.DRAFT_07).u62()).toBe(0x1_2345_6789_abcdn); +}); + +test("the varint range follows the version: 64 bits on lite-07, 62 on lite-06", async () => { + const max = 2n ** 64n - 1n; + const wire = await written(Lite.DRAFT_07, (w) => w.u62(max)); + expect(wire).toEqual(Array(9).fill(0xff)); + expect(await new Reader(undefined, Uint8Array.from(wire), Lite.DRAFT_07).u62()).toBe(max); + await expect(written(Lite.DRAFT_06, (w) => w.u62(2n ** 62n))).rejects.toThrow("62-bits"); +}); + +test("a lite-07 stream decodes reset codes with the moq-lite registry", async () => { + // 0x4 is GOING_AWAY on moq-lite but a foreign code on draft-17. + const reset = async (version: StreamVersion) => { + const reader = new Reader( + new ReadableStream({ + start: (controller) => controller.error(new Reset(4)), + }), + undefined, + version, + ); + const err = await reader.closed.then( + () => undefined, + (e: unknown) => e, + ); + return (err as StreamError).code; + }; + expect(await reset(Lite.DRAFT_07)).toBe(StreamCode.GoingAway); + expect(await reset(Version.DRAFT_17)).toBe(StreamCode.Internal); +}); + test("Writer and Reader varint round-trip every size in both formats", async () => { const values = [0n, 63n, 64n, 127n, 128n, 2n ** 14n, 2n ** 21n, 2n ** 28n, 2n ** 30n, 2n ** 32n, 2n ** 35n]; values.push(2n ** 42n, 2n ** 49n, 2n ** 53n, 2n ** 56n, 2n ** 62n - 1n); - for (const version of [undefined, Version.DRAFT_16, Version.DRAFT_17, Version.DRAFT_19]) { + for (const version of [Lite.DRAFT_06, Lite.DRAFT_07, Version.DRAFT_16, Version.DRAFT_17, Version.DRAFT_19]) { // Only leading-ones varints reach past 62 bits. const all = - version === Version.DRAFT_17 || version === Version.DRAFT_19 - ? [...values, 2n ** 62n, 2n ** 64n - 1n] - : values; + version === Lite.DRAFT_06 || version === Version.DRAFT_16 ? values : [...values, 2n ** 62n, 2n ** 64n - 1n]; const { stream, written } = createTestWritableStream(); const writer = new Writer(stream, version); for (const value of all) await writer.varint(U64.fromBigInt(value)); @@ -821,7 +879,7 @@ test("Writer and Reader varint round-trip every size in both formats", async () test("Writer varint refuses a QUIC varint past 62 bits before emitting bytes", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, Version.DRAFT_16); await expect(writer.varint(U64.fromBigInt(2n ** 62n))).rejects.toThrow(/larger than 62-bits/); await expect(writer.varint(U64.MAX)).rejects.toThrow(/larger than 62-bits/); expect(written).toEqual([]); @@ -830,7 +888,7 @@ test("Writer varint refuses a QUIC varint past 62 bits before emitting bytes", a test("Reader u53 decodes every size in both formats, one byte per chunk", async () => { const values = [0, 63, 64, 127, 128, 16383, 16384, 2 ** 21, 2 ** 28 - 1, 2 ** 28, 2 ** 30 - 1, 2 ** 30]; values.push(2 ** 35, 2 ** 42, 2 ** 49, Number.MAX_SAFE_INTEGER); - for (const version of [undefined, Version.DRAFT_17]) { + for (const version of [Lite.DRAFT_06, Lite.DRAFT_07, Version.DRAFT_17]) { const { stream, written } = createTestWritableStream(); const writer = new Writer(stream, version); for (const value of values) await writer.u53(value); diff --git a/js/net/src/stream.ts b/js/net/src/stream.ts index 47e3d374d55..c2847f395a1 100644 --- a/js/net/src/stream.ts +++ b/js/net/src/stream.ts @@ -2,6 +2,7 @@ import { race } from "@moq/signals"; import { fromTransport, StreamCode, StreamError, toStreamCode, toTransport } from "./error.ts"; import type { IetfVersion } from "./ietf/version.ts"; import { Version } from "./ietf/version.ts"; +import { Version as Lite, type Version as LiteVersion } from "./lite/version.ts"; import { TimeoutError, withTimeout } from "./util/timeout.ts"; import { POW32, toBigInt, toNumber, U64 } from "./util/u64.ts"; import { decodeUtf8 } from "./util/utf8.ts"; @@ -20,7 +21,8 @@ import { // Decode raw transport errors before mapping so they cannot bypass the negotiated // registry. Ordinary errors already send 0 and retain their local identity. -function withCode(reason: unknown, version?: IetfVersion): unknown { +function withCode(reason: unknown, stream: StreamVersion): unknown { + const version = asIetf(stream); const decoded = fromTransport(reason, { version }); const code = toStreamCode(decoded, { version }); return code === StreamCode.Internal && decoded === reason ? reason : toTransport(code, decoded.message); @@ -60,13 +62,59 @@ async function openWithin(opening: Promise, timeout: number, discard: (str } } -function isLeadingOnes(version?: IetfVersion): boolean { - return ( - version !== undefined && - version !== Version.DRAFT_14 && - version !== Version.DRAFT_15 && - version !== Version.DRAFT_16 - ); +/** + * The version a stream's bytes follow: a moq-transport draft or a moq-lite draft. Required on + * every stream so the varint form never defaults silently; a stream opened before negotiation + * names the version its handshake is encoded with. + */ +export type StreamVersion = IetfVersion | LiteVersion; + +const LITE: ReadonlySet = new Set(Object.values(Lite)); + +function isLite(version: StreamVersion): version is LiteVersion { + return LITE.has(version); +} + +/** The moq-transport draft a stream follows, or undefined on moq-lite, whose stream codes are the same on every draft. */ +export function asIetf(version: StreamVersion): IetfVersion | undefined { + return isLite(version) ? undefined : version; +} + +// Every draft newer than these counts leading ones, so a new version falls forward. +function isLeadingOnes(version: StreamVersion): boolean { + switch (version) { + case Version.DRAFT_14: + case Version.DRAFT_15: + case Version.DRAFT_16: + case Lite.DRAFT_01: + case Lite.DRAFT_02: + case Lite.DRAFT_03: + case Lite.DRAFT_04: + case Lite.DRAFT_05: + case Lite.DRAFT_06: + return false; + default: + return true; + } +} + +// Encode `hi`/`lo` into `dst` in the varint form `version` uses: QUIC up to 2^62-1, leading-ones up to 2^64-1. +function encodeTo(dst: ArrayBuffer, hi: number, lo: number, version: StreamVersion): Uint8Array { + let buf: Uint8Array; + if (isLeadingOnes(version)) { + buf = new Uint8Array(dst, 0, lengthLeadingOnes(hi, lo)); + writeLeadingOnes(buf, hi, lo, buf.length); + } else { + buf = new Uint8Array(dst, 0, lengthQuic(hi, lo)); + writeQuic(buf, hi, lo, buf.length); + } + return buf; +} + +/** Encode one varint in the form `version` uses, for a body written outside a {@link Writer}. */ +export function encodeVarint(v: number | bigint, version: StreamVersion): Uint8Array { + const lo = split(v); + return encodeTo(new ArrayBuffer(9), parts.hi, lo, version); } /** @@ -83,8 +131,8 @@ export type SendStream = WritableStream & { sendOrder?: number }; /** Options for opening an outgoing stream. */ export interface OpenOptions { - /** The negotiated IETF version, which selects the varint encoding. */ - version?: IetfVersion; + /** The negotiated version, which selects the varint encoding. */ + version: StreamVersion; /** * The transport send order, where HIGHER values are transmitted first. @@ -125,7 +173,7 @@ export class Stream { constructor(props: { writable: WritableStream; readable: ReadableStream; - version?: IetfVersion; + version: StreamVersion; }); /** Pair halves that were opened separately, as the SETUP exchange does. */ constructor(props: { writer: Writer; reader: Reader }); @@ -134,17 +182,19 @@ export class Stream { readable?: ReadableStream; writer?: Writer; reader?: Reader; - version?: IetfVersion; + version?: StreamVersion; }) { - const writer = props.writer ?? (props.writable && new Writer(props.writable, props.version)); - const reader = props.reader ?? (props.readable && new Reader(props.readable, undefined, props.version)); + const version = props.version; + const writer = props.writer ?? (props.writable && version !== undefined && new Writer(props.writable, version)); + const reader = + props.reader ?? (props.readable && version !== undefined && new Reader(props.readable, undefined, version)); if (!writer || !reader) throw new Error("stream needs both halves"); this.writer = writer; this.reader = reader; } - static async accept(quic: WebTransport, version?: IetfVersion): Promise { + static async accept(quic: WebTransport, version: StreamVersion): Promise { for (;;) { const reader = quic.incomingBidirectionalStreams.getReader() as ReadableStreamDefaultReader; @@ -163,7 +213,7 @@ export class Stream { * @param options - The version its varints encode with, and the send order ranking it * against the session's other streams */ - static async open(quic: WebTransport, options?: OpenOptions): Promise { + static async open(quic: WebTransport, options: OpenOptions): Promise { const { readable, writable } = await openWithin( quic.createBidirectionalStream(sendOptions(options)), options?.timeout ?? OPEN_TIMEOUT_MS, @@ -172,7 +222,7 @@ export class Stream { void stream.readable.cancel().catch(() => void 0); }, ); - return new Stream({ readable, writable, version: options?.version }); + return new Stream({ readable, writable, version: options.version }); } close() { @@ -202,12 +252,16 @@ export class Reader { #closed?: Promise; // The decode that last ran short and how far, so a retry can wait for those bytes. #short?: { decode: (c: Cursor) => unknown; err: Short }; - version?: IetfVersion; + version: StreamVersion; // Either stream or buffer MUST be provided. - constructor(stream: ReadableStream, buffer?: Uint8Array, version?: IetfVersion); - constructor(stream: undefined, buffer: Uint8Array, version?: IetfVersion); - constructor(stream?: ReadableStream, buffer?: Uint8Array, version?: IetfVersion) { + constructor(stream: ReadableStream, buffer: Uint8Array | undefined, version: StreamVersion); + constructor(stream: undefined, buffer: Uint8Array, version: StreamVersion); + constructor( + stream: ReadableStream | undefined, + buffer: Uint8Array | undefined, + version: StreamVersion, + ) { this.#buffer = buffer ?? new Uint8Array(); this.#stream = stream; this.#reader = this.#stream?.getReader(); @@ -223,7 +277,7 @@ export class Reader { // Every read of this stream funnels through here, so decoding the peer's reset code // once is enough to keep the raw transport error out of every caller (and every app). const result = await this.#reader.read().catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); if (result.done) { @@ -397,7 +451,7 @@ export class Reader { // shape depending on which one won. Derived once, so racing it per frame doesn't allocate. get closed(): Promise { this.#closed ??= (this.#reader?.closed ?? Promise.resolve()).catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); return this.#closed; } @@ -424,7 +478,7 @@ const EMPTY = new Short(1); * anything before its last read, must not swallow what it throws, and must read at least a byte. */ export class Cursor { - readonly version?: IetfVersion; + readonly version: StreamVersion; #buffer: Uint8Array; #offset = 0; // Resolved once, since every varint read branches on it. @@ -435,7 +489,7 @@ export class Cursor { // First bytes below this are a varint of at most 4 bytes: 0xc0 for QUIC, 0xf0 for leading-ones. #word: number; - constructor(buffer: Uint8Array, version?: IetfVersion) { + constructor(buffer: Uint8Array, version: StreamVersion) { this.#buffer = buffer; this.version = version; this.#leadingOnes = isLeadingOnes(version); @@ -591,9 +645,9 @@ export class Writer { // Scratch buffer for each primitive write, sized for the longest (a 9-byte leading-ones varint). #scratch: ArrayBuffer; - version?: IetfVersion; + version: StreamVersion; - constructor(stream: WritableStream, version?: IetfVersion) { + constructor(stream: WritableStream, version: StreamVersion) { this.#stream = stream; this.#scratch = new ArrayBuffer(9); this.#writer = this.#stream.getWriter(); @@ -656,22 +710,14 @@ export class Writer { } #varint(hi: number, lo: number): Promise { - let buf: Uint8Array; - if (isLeadingOnes(this.version)) { - buf = new Uint8Array(this.#scratch, 0, lengthLeadingOnes(hi, lo)); - writeLeadingOnes(buf, hi, lo, buf.length); - } else { - buf = new Uint8Array(this.#scratch, 0, lengthQuic(hi, lo)); - writeQuic(buf, hi, lo, buf.length); - } - return this.write(buf); + return this.write(encodeTo(this.#scratch, hi, lo, this.version)); } async write(v: Uint8Array) { // Mirrors Reader.#fill: every write funnels through here, so a STOP_SENDING from the // peer surfaces as a typed code rather than the transport's own error shape. await this.#writer.write(v).catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); } @@ -689,7 +735,7 @@ export class Writer { // typed code it would get from a write. get closed(): Promise { this.#closed ??= this.#writer.closed.catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); return this.#closed; } @@ -704,14 +750,14 @@ export class Writer { * @param options - The version its varints encode with, and the send order ranking it * against the session's other streams */ - static async open(quic: WebTransport, options?: OpenOptions): Promise { + static async open(quic: WebTransport, options: OpenOptions): Promise { const writable = await openWithin( quic.createUnidirectionalStream(sendOptions(options)) as Promise>, options?.timeout ?? OPEN_TIMEOUT_MS, (stream) => void stream.abort().catch(() => void 0), ); - return new Writer(writable, options?.version); + return new Writer(writable, options.version); } /** @@ -771,9 +817,9 @@ function setInt32(dst: ArrayBuffer, v: number): Uint8Array { // Returns the next stream from the connection export class Readers { #reader: ReadableStreamDefaultReader>; - #version?: IetfVersion; + #version: StreamVersion; - constructor(quic: WebTransport, version?: IetfVersion) { + constructor(quic: WebTransport, version: StreamVersion) { this.#reader = quic.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream >; diff --git a/js/net/src/tail.test.ts b/js/net/src/tail.test.ts index 142ff05e80c..972df8faec9 100644 --- a/js/net/src/tail.test.ts +++ b/js/net/src/tail.test.ts @@ -1,11 +1,12 @@ -import { expect, test } from "bun:test"; +import { describe, expect, test } from "bun:test"; +import { Once } from "@moq/signals"; import { accept, connect } from "./connection/index.ts"; import * as Ietf from "./ietf/index.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; -import { TAIL_GRACE_MS } from "./tail.ts"; +import { TAIL_GRACE_MS, Tail } from "./tail.ts"; import { Milli } from "./time.ts"; import type { Ordered } from "./track.ts"; import { wireOf } from "./wire.ts"; @@ -103,3 +104,74 @@ test.each([Ietf.ALPN.DRAFT_16, Ietf.ALPN.DRAFT_17, Ietf.ALPN.DRAFT_20])( } }, ); + +describe("Tail", () => { + const GRACE = Milli(1000); + + function tail() { + const clock = { now: 0 }; + return { clock, tail: new Tail({ grace: () => GRACE, now: () => clock.now }) }; + } + + test("a gap older than the grace folds away", () => { + const { clock, tail: t } = tail(); + t.account(0, 1); + t.account(2, 3); + clock.now = GRACE / 2; + t.account(4, 5); + expect(t.covers(0, 3)).toBe(false); + + // Splitting the younger gap keeps it as late as it was. + t.account(6, 7); + clock.now = GRACE; + t.account(8, 9); + expect(t.covers(0, 3)).toBe(true); + expect(t.covers(0, 5)).toBe(false); + }); + + test("splitting a gap leaves both halves with its age", () => { + const { clock, tail: t } = tail(); + t.account(0, 1); + t.account(9, 10); + clock.now = GRACE / 2; + t.account(5, 6); + expect(t.covers(0, 10)).toBe(false); + + clock.now = GRACE; + t.account(9, 10); + expect(t.covers(0, 10)).toBe(true); + }); + + test("a lowered floor restarts the gap age", () => { + const { clock, tail: t } = tail(); + t.account(3, 4); + t.account(9, 10); + + clock.now = GRACE * 2; + t.demand(1, 3); + t.account(1, 2); + expect(t.covers(1, 4)).toBe(false); + // Only the gap the floor reached restarts. + expect(t.covers(3, 10)).toBe(true); + + clock.now = GRACE * 3; + t.account(9, 10); + expect(t.covers(1, 10)).toBe(true); + }); + + test("the grace waits for a stream being read", async () => { + const t = new Tail({ grace: () => Milli(10) }); + const read = t.open(0); + let settled = false; + const settling = t + .settle(() => false, new Once()) + .then(() => { + settled = true; + }); + + await new Promise((resolve) => setTimeout(resolve, 50)); + expect(settled).toBe(false); + read(); + await settling; + }); +}); diff --git a/js/net/src/tail.ts b/js/net/src/tail.ts index e516f1ea089..b732ae11338 100644 --- a/js/net/src/tail.ts +++ b/js/net/src/tail.ts @@ -14,6 +14,18 @@ export const TAIL_GRACE_MS = Milli(1000); // setTimeout truncates a longer delay to a signed 32-bit int and fires at once. const MAX_TIMEOUT_MS = 2 ** 31 - 1; +// A run of accounted sequences `[start, end)`, and when the gap below it opened (in +// `performance.now()` milliseconds), which is when its missing groups became late. +type Run = { start: number; end: number; since: number }; + +/** How a {@link Tail} measures its grace. */ +export interface TailOptions { + /** How long to wait for a group that cannot be accounted for. Read each time it is needed. */ + grace?: () => Milli; + /** The clock, in `performance.now()` milliseconds. */ + now?: () => number; +} + /** * The group streams a subscription has received, so its end can wait for the ones still owed. * @@ -22,16 +34,28 @@ const MAX_TIMEOUT_MS = 2 ** 31 - 1; * the publisher dropped them) and how many streams are still being read, and {@link settle} * waits on them. * + * A lost datagram is not owed: it leaves a hole that waits out the grace like a stream reset + * before its header. + * * @internal */ export class Tail { - // Disjoint, sorted, exclusive-end ranges of accounted sequences. A gap splits a range, so - // this stays as small as the number of gaps rather than the number of groups. - #accounted: [number, number][] = []; + // Disjoint, sorted, non-adjacent runs of accounted sequences. A gap older than the grace + // can no longer be waited for, so it folds into the runs around it, which bounds this by + // the gaps opened within the grace rather than every gap in the subscription. A fold is + // final: a later, longer grace or a lowered floor cannot reopen it. + #runs: Run[] = []; // Group streams whose header arrived, and those still being read. #streams = 0; #active = 0; #changed = new Signal(0); + #grace: () => Milli; + #now: () => number; + + constructor(options: TailOptions = {}) { + this.#grace = options.grace ?? (() => TAIL_GRACE_MS); + this.#now = options.now ?? (() => performance.now()); + } /** Group streams whose header arrived, whether they finished or were reset. */ get streams(): number { @@ -61,29 +85,44 @@ export class Tail { this.#account(start, end); } + /** Restart the age of every gap reaching into `[start, end)`, which the demand newly asks for. */ + demand(start: number, end: number): void { + if (start >= end) return; + const now = this.#now(); + let below = 0; + this.#runs = this.#runs.map((run) => { + const reached = below < end && start < run.start; + below = run.end; + return reached ? { ...run, since: now } : run; + }); + } + /** Whether every sequence in `[start, end)` is accounted for. */ covers(start: number, end: number): boolean { if (start >= end) return true; - // Ranges are merged on insert, so one range covers the span or none does. - return this.#accounted.some(([lo, hi]) => lo <= start && end <= hi); + // Runs are merged on insert, so one run covers the span or none does. + return this.#runs.some((run) => run.start <= start && end <= run.end); } /** - * Wait until every stream is read to its end and `complete()` holds, or `grace` - * milliseconds pass with nothing left being read, or `closed` settles. + * Wait until every stream is read to its end and `complete()` holds, or the grace passes + * with nothing left being read, or `closed` settles. * * A stream still being read is always waited for: a group ends on its own stream's FIN * or reset, never because its track ended. The grace only gives up on streams that never * arrived. */ - async settle(complete: () => boolean, grace: Milli, closed: GetPromise): Promise { + async settle(complete: () => boolean, closed: GetPromise): Promise { + // A gap that aged past the grace since the last insert is no longer waited for either. + this.#expire(this.#now()); + let expired = false; const timer = setTimeout( () => { expired = true; this.#bump(); }, - Math.min(grace, MAX_TIMEOUT_MS), + Math.min(this.#grace(), MAX_TIMEOUT_MS), ); try { while (closed.peek() === undefined) { @@ -98,27 +137,48 @@ export class Tail { #account(start: number, end: number): void { if (start >= end) return; - const merged: [number, number][] = []; - let lo = start; - let hi = end; + const now = this.#now(); + const runs: Run[] = []; + let merged: Run | undefined; let placed = false; - for (const range of this.#accounted) { - if (range[1] < lo) { - merged.push(range); - } else if (hi < range[0]) { - if (!placed) merged.push([lo, hi]); + for (const run of this.#runs) { + if (run.end < start) { + runs.push(run); + } else if (end < run.start) { + // Splitting a gap leaves both halves as late as it was. + if (!placed) runs.push(merged ?? { start, end, since: run.since }); placed = true; - merged.push(range); + runs.push(run); } else { - lo = Math.min(lo, range[0]); - hi = Math.max(hi, range[1]); + merged = { + start: Math.min(merged?.start ?? start, run.start), + end: Math.max(merged?.end ?? end, run.end), + since: merged?.since ?? run.since, + }; } } - if (!placed) merged.push([lo, hi]); - this.#accounted = merged; + // A run past every other one opens a new gap. + if (!placed) runs.push(merged ?? { start, end, since: now }); + this.#runs = runs; + this.#expire(now); this.#bump(); } + // Fold every gap older than the grace into the runs around it. + #expire(now: number): void { + const grace = this.#grace(); + const runs: Run[] = []; + for (const run of this.#runs) { + const below = runs.at(-1); + if (below && now - run.since >= grace) { + runs[runs.length - 1] = { ...below, end: run.end }; + } else { + runs.push(run); + } + } + this.#runs = runs; + } + #bump(): void { this.#changed.update((revision) => revision + 1); } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index ba20d2d4a0c..b26afa694dc 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -27,9 +27,9 @@ function mockMonotonicTime(initial: number) { }; } -test("priority reads the committed info and is 0 before accept", () => { +test("priority reads the committed info and is the midpoint before accept", () => { const producer = new TrackProducer("video"); - expect(producer.priority).toBe(0); + expect(producer.priority).toBe(127); producer.accept({ priority: 60 }); expect(producer.priority).toBe(60); }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 7ccb5d039c8..e4d6a63ba17 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -27,6 +27,10 @@ const MAX_TIMEOUT_MS = 2 ** 31 - 1; // The cache scans at most this many times per retention window. const PRUNE_SLICES = 8; +// The higher-first midpoint. IETF flips priority (lower first), so this goes out as 128, the +// draft's usual publisher priority, while moq-lite carries 127 as written: one urgency on both. +const DEFAULT_PRIORITY = 127; + /** Maximum buffered datagrams per subscriber; mirrors Rust's bounded send buffer. */ const MAX_DATAGRAMS = 64; @@ -68,7 +72,7 @@ export interface Info { * or non-finite value and a result past `Number.MAX_SAFE_INTEGER`. */ maxAge?: Milli; - /** Tie-break priority between subscriptions of equal subscriber priority (`0..=255`). */ + /** Tie-break priority between subscriptions of equal subscriber priority (`0..=255`, higher first). Defaults to `127`. */ priority: number; } @@ -101,7 +105,7 @@ export function infoDefaults(info: Partial = {}): Info { return { timescale: Timescale(info.timescale ?? Timescale.MILLI), maxAge: info.maxAge === undefined ? undefined : maxAgeMillis(info.maxAge), - priority: priorityByte(info.priority ?? 0), + priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), }; } @@ -241,6 +245,14 @@ export class Request { export interface FetchGroupOptions { /** Delivery priority for the fetch stream. Defaults to `0`. */ priority?: number; + + /** + * Abandons this fetch, rejecting with the signal's reason. Concurrent fetches of the same + * group share one stream, cancelled only once every caller has left. An already-aborted + * signal rejects before anything is sent, and aborting after the group resolves has no + * effect; close the group instead. + */ + signal?: AbortSignal; } /** @@ -523,13 +535,13 @@ export class Producer { } /** - * Publisher priority from the committed {@link Info}, or 0 before {@link accept}. + * Publisher priority from the committed {@link Info}, or the default before {@link accept}. * * Higher is served first. Hang publishers set this from `Catalog.PRIORITY` so * audio outranks video on the wire and in the bandwidth allocator. */ get priority(): number { - return this.#state.info.peek()?.priority ?? 0; + return this.#state.info.peek()?.priority ?? DEFAULT_PRIORITY; } /** @@ -904,8 +916,8 @@ export class Producer { if (!Number.isSafeInteger(final) || final < 0) throw new RangeError(`invalid track end: ${final}`); const declared = this.#state.final.peek(); if (declared !== undefined) throw new Error(`track already ends at ${declared}`); - if (final < this.#sequence.next) { - throw new Error(`track end ${final} is below the next sequence ${this.#sequence.next}`); + if (final < this.#received) { + throw new Error(`track end ${final} is below the next sequence ${this.#received}`); } this.#declareFinal(final); } @@ -929,7 +941,7 @@ export class Producer { if (this.#state.closed.peek() !== undefined) return; if (abort && this.#settled()) abort = undefined; if (abort === undefined && this.#state.final.peek() === undefined) { - this.#declareFinal(this.#sequence.next); + this.#declareFinal(this.#received); } // Nobody will finish these, so a subscriber that has not taken one yet never sees it. // Not evicted: a reader already holding one keeps its frames and sees the abort. diff --git a/js/net/src/util/abort.ts b/js/net/src/util/abort.ts new file mode 100644 index 00000000000..ed1f32ba8b2 --- /dev/null +++ b/js/net/src/util/abort.ts @@ -0,0 +1,18 @@ +import { race } from "@moq/signals"; + +// Settle with `promise`, or reject with the signal's reason once it aborts. An already-aborted +// signal rejects at once. There's no cancellation of `promise` itself; the caller releases +// whatever it holds when this rejects. +export async function untilAborted(promise: Promise, signal?: AbortSignal): Promise { + if (!signal) return promise; + signal.throwIfAborted(); + + const { promise: aborted, reject } = Promise.withResolvers(); + const onAbort = () => reject(signal.reason); + signal.addEventListener("abort", onAbort, { once: true }); + try { + return await race([promise, aborted]); + } finally { + signal.removeEventListener("abort", onAbort); + } +} diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 5dfce688b5a..60f7ea50102 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -12,7 +12,17 @@ class FakeVideoEncoder { // Every accepted probe, so a test can assert a published config was actually validated. static accepted: string[] = []; + // The codec string the encoder reports in its output for a configured one. Echoes by default, + // like Chrome and Firefox. + static report: (codec: string) => string | undefined = (codec) => codec; + state: CodecState = "unconfigured"; + #output: VideoEncoderInit["output"]; + #codec?: string; + + constructor(init: VideoEncoderInit) { + this.#output = init.output; + } static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { FakeVideoEncoder.probes++; @@ -24,32 +34,50 @@ class FakeVideoEncoder { return { supported }; } - configure(): void { + configure(config: VideoEncoderConfig): void { this.state = "configured"; + this.#codec = config.codec; } encode(): void {} + // Only the probe flushes, so only it sees an output; the live encoder holds every frame. + async flush(): Promise { + const codec = this.#codec && FakeVideoEncoder.report(this.#codec); + const chunk = { type: "key", timestamp: 0, byteLength: 1, copyTo: () => {} }; + this.#output(chunk as never, (codec ? { decoderConfig: { codec } } : {}) as never); + } + close(): void { this.state = "closed"; } } +class FakeVideoFrame { + timestamp = 0; + close(): void {} +} + function installFakeVideoEncoder() { const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder"); + const frame = Object.getOwnPropertyDescriptor(globalThis, "VideoFrame"); Object.defineProperty(globalThis, "VideoEncoder", { configurable: true, value: FakeVideoEncoder, writable: true, }); + Object.defineProperty(globalThis, "VideoFrame", { configurable: true, value: FakeVideoFrame, writable: true }); return { [Symbol.dispose]() { + FakeVideoEncoder.report = (codec) => codec; if (original) { Object.defineProperty(globalThis, "VideoEncoder", original); } else { Reflect.deleteProperty(globalThis, "VideoEncoder"); } + if (frame) Object.defineProperty(globalThis, "VideoFrame", frame); + else Reflect.deleteProperty(globalThis, "VideoFrame"); }, }; } @@ -350,12 +378,15 @@ test("an invalid knob settles the encoder without a config", async () => { out: { display: new Signal({ width: 1920, height: 1080 }) }, }; const config = new Signal<{ bitrateScale?: number } | undefined>({ bitrateScale: -1 }); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); const encoder = new Encoder("video", { enabled: true, capture: capture as never, config }); try { await settle(); expect(encoder.out.catalog.peek()).toBeUndefined(); expect(encoder.settled.peek()).toBe(true); expect(error).toHaveBeenCalled(); + // Refused before the browser could coerce it into an unsigned bitrate. + expect(probe).not.toHaveBeenCalled(); // Fixing the knob clears the failure and resolves a config. config.set(undefined); @@ -365,6 +396,7 @@ test("an invalid knob settles the encoder without a config", async () => { } finally { encoder.close(); error.mockRestore(); + probe.mockRestore(); } }); @@ -458,40 +490,8 @@ test("frame sources retain their dimensions and nominal frame rate", async () => test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s", async (reason) => { const clock = spyOn(performance, "now").mockReturnValue(0); - class DelayedVideoEncoder { - static probes = 0; - state: CodecState = "unconfigured"; - #output: VideoEncoderInit["output"]; - - constructor(init: VideoEncoderInit) { - this.#output = init.output; - } - - static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { - DelayedVideoEncoder.probes++; - return { supported: config.codec.startsWith("avc1") }; - } - - configure(): void { - this.state = "configured"; - } - - encode(): void { - // Hold the output: a throttled encoder never hands frames to the session. - } - - close(): void { - this.state = "closed"; - void this.#output; - } - } - - const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder"); - Object.defineProperty(globalThis, "VideoEncoder", { - configurable: true, - value: DelayedVideoEncoder, - writable: true, - }); + // The fake holds every live output, like a throttled encoder that never hands frames to the session. + using _videoEncoder = installFakeVideoEncoder(); class Frame { codedWidth = 640; @@ -565,8 +565,192 @@ test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s", encoder.close(); fanout.close(); clock.mockRestore(); - if (original) Object.defineProperty(globalThis, "VideoEncoder", original); - else Reflect.deleteProperty(globalThis, "VideoEncoder"); + } +}); + +// Every browser refuses a bare hint, so probing one only delays the fallback, and a browser that +// accepted it would publish a codec no native player can decode. +test("the probe only offers full codec strings", async () => { + using _videoEncoder = installFakeVideoEncoder(); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported").mockImplementation(async () => ({ supported: false })); + const error = spyOn(console, "error").mockImplementation(() => {}); + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + try { + await settle(); + const probed = probe.mock.calls.map(([config]) => config.codec); + expect(probed.length).toBeGreaterThan(0); + expect(probed.filter((codec) => codec !== "vp8" && !codec.includes("."))).toEqual([]); + expect(encoder.settled.peek()).toBe(true); + } finally { + encoder.close(); + probe.mockRestore(); + error.mockRestore(); + } +}); + +// The catalog is written before any subscriber starts the real encoder, so it has to carry what the +// bitstream will say from the first announce, not a probe input a native player may refuse. +test("the catalog advertises the codec string a probe encode reports", async () => { + using _videoEncoder = installFakeVideoEncoder(); + // Refine the configured string, as an encoder that picks its own level would. + const REPORTED: Record = { + "vp09.00.10.08": "vp09.00.31.08", + "avc1.640028": "avc1.64001F", + }; + const probe = spyOn(FakeVideoEncoder, "isConfigSupported").mockImplementation(async (config) => ({ + supported: config.codec in REPORTED, + })); + FakeVideoEncoder.report = (codec) => REPORTED[codec]; + + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + const advertised: string[] = []; + const unsubscribe = encoder.out.catalog.subscribe((catalog) => { + if (catalog) advertised.push(catalog.codec); + }); + + try { + await settle(); + expect(encoder.out.resolved.peek()?.codec).toBe("vp09.00.10.08"); + expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.31.08"); + + // A codec change re-probes and advertises the new encoder's string. + encoder.config.set({ codec: "avc1" }); + await settle(); + expect(encoder.out.resolved.peek()?.codec).toBe("avc1.640028"); + expect(encoder.out.catalog.peek()?.codec).toBe("avc1.64001F"); + + // The configured strings were never advertised, not even briefly. + expect([...new Set(advertised)]).toEqual(["vp09.00.31.08", "avc1.64001F"]); + } finally { + unsubscribe(); + encoder.close(); + probe.mockRestore(); + } +}); + +test("a probe encode that reports no codec string fails loud", async () => { + using _videoEncoder = installFakeVideoEncoder(); + FakeVideoEncoder.report = () => undefined; + const error = spyOn(console, "error").mockImplementation(() => {}); + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + try { + await settle(); + expect(encoder.out.catalog.peek()).toBeUndefined(); + expect(encoder.settled.peek()).toBe(true); + expect(error).toHaveBeenCalled(); + } finally { + encoder.close(); + error.mockRestore(); + } +}); + +// An encoder may pick its level from the frame rate or bitrate, so the probe encodes with both. The +// bitrate is the ceiling, so a bandwidth grant caps the live encoder without re-probing. +test("the probe encodes with the frame rate and bitrate ceiling", async () => { + using _videoEncoder = installFakeVideoEncoder(); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); + + const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const sub = track.subscribe(); + const rendition = { + config: new Signal(undefined), + track: new Signal(track), + close: () => track.close(), + }; + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }), frames: new Signal(undefined) }, + }; + const estimate = new Signal(100_000_000); + const bandwidth = new Moq.Bandwidth.Allocator(estimate); + const encoder = new Encoder("video", { + enabled: true, + broadcast: { video: () => rendition, baseline: new Baseline() } as never, + capture: capture as never, + bandwidth, + }); + const accepted = () => + probe.mock.calls.map(([config]) => config).filter((config) => config.codec.startsWith("avc1")); + + try { + await settle(); + const first = accepted().at(-1); + expect(first).toMatchObject({ framerate: 30 }); + expect(first?.bitrate).toBeGreaterThan(0); + expect(encoder.out.resolved.peek()?.bitrate).toBe(first?.bitrate); + + // A grant below the ceiling caps the live config but leaves the probe alone. + const probes = probe.mock.calls.length; + estimate.set(500_000); + await settle(); + expect(encoder.out.resolved.peek()?.bitrate).toBe(500_000); + expect(probe.mock.calls.length).toBe(probes); + + // A frame rate change re-probes with the new rate and its larger ceiling. + encoder.config.set({ frameRate: 60 }); + await settle(); + expect(probe.mock.calls.length).toBeGreaterThan(probes); + const second = accepted().at(-1); + expect(second).toMatchObject({ framerate: 60 }); + expect(second?.bitrate).toBeGreaterThan(first?.bitrate ?? 0); + expect(encoder.out.catalog.peek()?.framerate).toBe(60); + } finally { + encoder.close(); + bandwidth.close(); + sub.close(); + probe.mockRestore(); + } +}); + +// A re-probe keeps the rendition advertised while it runs: dropping it, even for a moment, would +// tell every subscriber the track went away. +test("a re-probe swaps the catalog entry in one update", async () => { + using _videoEncoder = installFakeVideoEncoder(); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + + try { + await settle(); + expect(encoder.out.catalog.peek()?.framerate).toBe(30); + + const published: (number | undefined)[] = []; + const unsubscribe = encoder.out.catalog.subscribe((catalog) => published.push(catalog?.framerate)); + try { + // A frame rate change re-probes, and the catalog goes straight from the old entry to the new. + let probes = probe.mock.calls.length; + encoder.config.set({ frameRate: 60 }); + await settle(); + expect(probe.mock.calls.length).toBeGreaterThan(probes); + expect(published).toEqual([60]); + + // A re-probe that lands on the same config leaves the catalog untouched. + probes = probe.mock.calls.length; + encoder.config.set({ frameRate: 60, maxPixels: 1280 * 720 }); + await settle(); + expect(probe.mock.calls.length).toBeGreaterThan(probes); + expect(published).toEqual([60]); + } finally { + unsubscribe(); + } + } finally { + encoder.close(); + probe.mockRestore(); } }); @@ -574,17 +758,31 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms const keys: number[] = []; class RecordingVideoEncoder { state: CodecState = "unconfigured"; + #output: VideoEncoderInit["output"]; + #codec?: string; + + constructor(init: VideoEncoderInit) { + this.#output = init.output; + } static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { return { supported: config.codec.startsWith("avc1") }; } - configure(): void { + configure(config: VideoEncoderConfig): void { this.state = "configured"; + this.#codec = config.codec; } + // Records the test's frames only, not the probe's. encode(frame: VideoFrame, options?: VideoEncoderEncodeOptions): void { - if (options?.keyFrame) keys.push(frame.timestamp / 1000); + if (options?.keyFrame && frame instanceof Frame) keys.push(frame.timestamp / 1000); + } + + // Only the probe flushes; report the configured codec, as Chrome does. + async flush(): Promise { + const chunk = { type: "key", timestamp: 0, byteLength: 1, copyTo: () => {} }; + this.#output(chunk as never, { decoderConfig: { codec: this.#codec } } as never); } close(): void { @@ -598,6 +796,8 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms value: RecordingVideoEncoder, writable: true, }); + const videoFrame = Object.getOwnPropertyDescriptor(globalThis, "VideoFrame"); + Object.defineProperty(globalThis, "VideoFrame", { configurable: true, value: FakeVideoFrame, writable: true }); class Frame { readonly timestamp: number; @@ -668,5 +868,7 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms track.close(); if (original) Object.defineProperty(globalThis, "VideoEncoder", original); else Reflect.deleteProperty(globalThis, "VideoEncoder"); + if (videoFrame) Object.defineProperty(globalThis, "VideoFrame", videoFrame); + else Reflect.deleteProperty(globalThis, "VideoFrame"); } }); diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index 0702a97dc6a..b690588b581 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -134,18 +134,23 @@ export class Encoder { // The output dimensions of the video in pixels. #dimensions = new Signal<{ width: number; height: number } | undefined>(undefined); - // The codec the browser will actually encode with, tagged with the inputs it was probed against. + // The config the browser accepted and encoded a probe frame with, and the codec string it reported. + // Kept through a re-probe, so the rendition stays in the catalog until the new probe replaces it. #codec = new Signal(undefined); + // The probed config capped by the bandwidth grant, and the codec string to advertise for it. One + // signal, so the catalog never pairs a new probe's string with the previous config. + #live = new Signal<{ config: VideoEncoderConfig; reported: string } | undefined>(undefined); + // Uncapped target bitrate (pixels, maxBitrate), the reservation's ceiling. #ceiling = new Signal(undefined); // This rendition's claim on the connection, held while a track is live. #reservation = new Signal(undefined); - // Only the codec prefix the user asked for, narrowed out of `config` so tuning any other knob - // doesn't re-probe the hardware. - #codecFilter: Computed; + // Only the knobs the probe encodes with, narrowed out of `config` and the source so tuning any + // other knob, or a bandwidth grant, doesn't re-probe the hardware. + #target: Computed; // A keyframe asked for by {@link cut} and not yet encoded. #cut = false; @@ -177,7 +182,23 @@ export class Encoder { bandwidth: getter(props?.bandwidth), }; this.config = Signal.from(props?.config); - this.#codecFilter = this.#signals.computed((effect) => effect.get(this.config)?.codec ?? ""); + this.#target = this.#signals.computed((effect): Target | undefined => { + const capture = effect.get(this.in.capture); + if (!capture) return; + + const source = effect.get(capture.in.source); + if (!source) return; + + const user = effect.get(this.config) ?? {}; + return { + required: user.codec ?? "", + // Prefer the explicitly requested rate; the encode loop drops frames to enforce it. + framerate: user.frameRate ?? sourceFrameRate(source) ?? 30, + maxPixels: user.maxPixels, + bitrateScale: user.bitrateScale ?? 0.07, + maxBitrate: user.maxBitrate, + }; + }); this.settled = this.#signals.computed( (effect) => effect.get(this.#out.catalog) !== undefined || effect.get(this.#failures) > 0, ); @@ -416,14 +437,17 @@ export class Encoder { // Returns the catalog for the configured settings, or undefined while disabled / unresolved. #runCatalog(effect: Effect): void { const enabled = effect.get(this.in.enabled); - const config = effect.get(this.out.resolved); - if (!enabled || !config) { + const live = effect.get(this.#live); + if (!enabled || !live) { effect.set(this.#out.catalog, undefined); return; } + // Advertise the codec string the probe's encoder reported rather than the one we configured, + // so it names the profile and level the bitstream actually carries. + const { config, reported } = live; const catalog: Catalog.VideoConfig = { - codec: config.codec, + codec: reported, bitrate: config.bitrate ? Catalog.u53(config.bitrate) : undefined, framerate: config.framerate, codedWidth: Catalog.u53(config.width), @@ -437,95 +461,49 @@ export class Encoder { effect.set(this.#out.catalog, catalog); } - // Probe the hardware for the best codec. Deliberately depends on as little as possible: every - // rerun blanks the codec (and with it the resolved config and the catalog entry) for however long - // the probe takes, which on a busy GPU process is a long time. + // Probe the hardware for the best codec. Deliberately depends on as little as possible, since a + // probe on a busy GPU process takes a long time. The previous result stays in place meanwhile, so + // a re-probe swaps the catalog entry in one update, or not at all when nothing changed. #runCodec(effect: Effect): void { - if (!effect.get(this.in.enabled)) return; - + const enabled = effect.get(this.in.enabled); const dimensions = effect.get(this.#dimensions); - if (!dimensions) return; - - const required = effect.get(this.#codecFilter) ?? ""; + const target = effect.get(this.#target); + if (!enabled || !dimensions || !target) { + this.#codec.set(undefined); + return; + } + // Captured now: the run's signal is replaced once a rerun starts. + const superseded = effect.abort; effect.spawn(async () => { try { - const detected = await this.#bestCodec(required, dimensions); - if (!detected) return; - - effect.set(this.#codec, { ...detected, required, ...dimensions }); + const detected = await this.#bestCodec(dimensions, target); + if (!superseded.aborted) this.#codec.set(detected); } catch (err) { + // A newer probe reports its own outcome. + if (superseded.aborted) return; + + this.#codec.set(undefined); this.#fail(effect); throw err; } }); } - // Size the bitrate for the detected codec. Synchronous, so a new bandwidth estimate updates the - // config within the same microtask instead of leaving it blank while something re-derives it. + // Cap the probed config's bitrate by the bandwidth grant. Synchronous, so a new bandwidth estimate + // updates the config within the same microtask instead of leaving it blank while something + // re-derives it. Everything else comes from the probe as-is, so the resolved config is always one + // the hardware accepted. #runResolved(effect: Effect): void { - // NOTE: dimensions already factors in user provided maxPixels. - // It's a separate effect in order to deduplicate. if (!effect.get(this.in.enabled)) return; - const capture = effect.get(this.in.capture); - if (!capture) return; - - const source = effect.get(capture.in.source); - if (!source) return; - - const dimensions = effect.get(this.#dimensions); - if (!dimensions) return; - const detected = effect.get(this.#codec); if (!detected) return; - // A probe only speaks for the inputs it ran against. Changing them reruns the probe, which - // clears the stale result, but a bandwidth sample landing in the same batch schedules this - // effect independently: it then runs against dimensions that are already written while the - // probe hasn't been torn down yet. Wait for a probe that matches rather than publishing a - // pairing the hardware never accepted. - const required = effect.get(this.#codecFilter) ?? ""; - if (detected.required !== required) return; - if (detected.width !== dimensions.width || detected.height !== dimensions.height) return; - - const { codec, hardwareAcceleration } = detected; - // Get the user provided config. - const user = effect.get(this.config) ?? {}; - - // Prefer the explicitly requested rate; the encode loop drops frames to enforce it. - const framerate = user.frameRate ?? sourceFrameRate(source) ?? 30; - - const maxPixels = user.maxPixels ?? dimensions.width * dimensions.height; - const bitrateScale = user.bitrateScale ?? 0.07; - - // TARGET BITRATE CALCULATION (h264) - // 480p@30 = 1.0mbps - // 480p@60 = 1.5mbps - // 720p@30 = 2.5mbps - // 720p@60 = 3.5mpbs - // 1080p@30 = 4.5mbps - // 1080p@60 = 6.0mbps - - // 30fps is the baseline, applying a multiplier for higher framerates. - // Framerate does not cause a multiplicative increase in bitrate because of delta encoding. - // TODO Make this better. - const framerateFactor = 30.0 + (framerate - 30) / 2; - - // ACTUAL BITRATE CALCULATION - // 480p@30 = 409920 * 30 * 0.07 = 0.9 Mb/s - // 480p@60 = 409920 * 45 * 0.07 = 1.3 Mb/s - // 720p@30 = 921600 * 30 * 0.07 = 1.9 Mb/s - // 720p@60 = 921600 * 45 * 0.07 = 2.9 Mb/s - // 1080p@30 = 2073600 * 30 * 0.07 = 4.4 Mb/s - // 1080p@60 = 2073600 * 45 * 0.07 = 6.5 Mb/s - let bitrate = Math.round(maxPixels * bitrateScale * framerateFactor * codecBitrateScale(codec)); - - bitrate = Math.round(Math.min(bitrate, user.maxBitrate || bitrate)); - // The reservation's ceiling is what we can ever send, not the grant: a // grant that followed our own output would hand the room away on a still // picture and not have it back when the picture moved. + let bitrate = detected.config.bitrate; effect.set(this.#ceiling, bitrate); const reservation = effect.get(this.#reservation); @@ -535,20 +513,9 @@ export class Encoder { if (grant != null) bitrate = Math.min(bitrate, grant); } - const config: VideoEncoderConfig = { - codec, - width: dimensions.width, - height: dimensions.height, - framerate, - bitrate, - avc: codec.startsWith("avc1") ? { format: "annexb" } : undefined, - // @ts-expect-error Typescript needs to be updated. - hevc: codec.startsWith("hev1") ? { format: "annexb" } : undefined, - latencyMode: "realtime", - hardwareAcceleration, - }; - + const config = { ...detected.config, bitrate }; effect.set(this.#out.resolved, config); + effect.set(this.#live, { config, reported: detected.reported }); } #runDimensions(effect: Effect): void { @@ -591,40 +558,28 @@ export class Encoder { } // Try to determine the best config for the given settings. - async #bestCodec( - required: string, - dimensions: { width: number; height: number }, - ): Promise< - | { - codec: string; - hardwareAcceleration: HardwareAcceleration; - } - | undefined - > { - // A list of codecs to try, in order of preference. + async #bestCodec(dimensions: { width: number; height: number }, target: Target): Promise { + // A list of codecs to try, in order of preference. Only full RFC 6381 strings: Chrome, Firefox, + // and Safari all refuse a bare `avc1` or `vp09`, and native players can't decode without the profile. const HARDWARE_CODECS = [ // VP9 // More likely to have hardware decoding, but hardware encoding is less likely. "vp09.00.10.08", - "vp09", // Browser's choice // H.264 // Almost always has hardware encoding and decoding. "avc1.640028", "avc1.4D401F", "avc1.42E01E", - "avc1", // AV1 // One day will get moved higher up the list, but hardware decoding is rare. "av01.0.08M.08", - "av01", // HEVC (aka h.265) // More likely to have hardware encoding, but less likely to be supported (licensing issues). // Unfortunately, Firefox doesn't support decoding so it's down here at the bottom. "hev1.1.6.L93.B0", - "hev1", // Browser's choice // VP8 // A terrible codec but it's easy. @@ -637,7 +592,6 @@ export class Encoder { "avc1.640028", // High "avc1.4D401F", // Main "avc1.42E01E", // Baseline - "avc1", // VP8 "vp8", @@ -645,12 +599,10 @@ export class Encoder { // VP9 // It's a bit more expensive to encode so we shy away from it. "vp09.00.10.08", - "vp09", // HEVC (aka h.265) // This likely won't work because of licensing issues. "hev1.1.6.L93.B0", - "hev1", // Browser's choice ]; // Try hardware encoding first. @@ -658,38 +610,25 @@ export class Encoder { // VideoToolbox only hardware-encodes H.264 and HEVC. Skip the hardware pass and let it fall // through to the software pass, which is H.264 first, since Safari routes that through // VideoToolbox anyway regardless of the hint. - if (hardwareReliable()) { - for (const codec of HARDWARE_CODECS) { - if (!codec.startsWith(required)) continue; - - const hardwareAcceleration: HardwareAcceleration = "prefer-hardware"; - - const hardware: VideoEncoderConfig = { - codec, - width: dimensions.width, - height: dimensions.height, - latencyMode: "realtime", - hardwareAcceleration, - avc: codec.startsWith("avc1") ? { format: "annexb" } : undefined, - // @ts-expect-error Typescript needs to be updated. - hevc: codec.startsWith("hev1") ? { format: "annexb" } : undefined, - }; - - const { supported } = await VideoEncoder.isConfigSupported(hardware); - if (supported) return { codec, hardwareAcceleration }; - } - } - - // Try software encoding. - for (const codec of SOFTWARE_CODECS) { - if (!codec.startsWith(required)) continue; + const candidates: [string, HardwareAcceleration][] = [ + ...(hardwareReliable() + ? HARDWARE_CODECS.map((codec) => [codec, "prefer-hardware"] as [string, HardwareAcceleration]) + : []), + ...SOFTWARE_CODECS.map((codec) => [codec, "prefer-software"] as [string, HardwareAcceleration]), + ]; - const hardwareAcceleration: HardwareAcceleration = "prefer-software"; + for (const [codec, hardwareAcceleration] of candidates) { + if (!codec.startsWith(target.required)) continue; - const software: VideoEncoderConfig = { + // The full config, like moq-video's probe: an encoder may pick its level from the frame rate + // or bitrate. The bitrate is the ceiling rather than the grant, so a bandwidth estimate never + // re-probes. + const config: Detected["config"] = { codec, width: dimensions.width, height: dimensions.height, + framerate: target.framerate, + bitrate: ceiling(codec, dimensions, target), latencyMode: "realtime", hardwareAcceleration, avc: codec.startsWith("avc1") ? { format: "annexb" } : undefined, @@ -697,8 +636,8 @@ export class Encoder { hevc: codec.startsWith("hev1") ? { format: "annexb" } : undefined, }; - const { supported } = await VideoEncoder.isConfigSupported(software); - if (supported) return { codec, hardwareAcceleration }; + const { supported } = await VideoEncoder.isConfigSupported(config); + if (supported) return { config, reported: await reportedCodec(config) }; } throw new Error("no supported codec"); @@ -731,17 +670,99 @@ function sourceFrameRate(source: Source): number | undefined { return "frames" in source ? source.frameRate : normalizeSource(source).track.getSettings().frameRate; } -// A hardware probe result, carrying the inputs it ran against so a consumer can tell whether it -// still applies. -type Detected = { - codec: string; - hardwareAcceleration: HardwareAcceleration; - // The codec prefix the user required at probe time. +// The knobs a probe encodes with, besides the dimensions. +type Target = { + // The codec prefix the user required. required: string; - width: number; - height: number; + framerate: number; + maxPixels?: number; + bitrateScale: number; + maxBitrate?: number; +}; + +// A hardware probe result. +type Detected = { + // The config the browser accepted and encoded a probe frame with. Its bitrate is the ceiling, + // before any bandwidth grant. + config: VideoEncoderConfig & { framerate: number; bitrate: number }; + // The codec string the encoder reported for it, which the catalog advertises. + reported: string; }; +// The most this rendition ever sends with `codec`, before a bandwidth grant caps it. +function ceiling(codec: string, dimensions: { width: number; height: number }, target: Target): number { + // NOTE: dimensions already factors in user provided maxPixels. + const maxPixels = target.maxPixels ?? dimensions.width * dimensions.height; + + // TARGET BITRATE CALCULATION (h264) + // 480p@30 = 1.0mbps + // 480p@60 = 1.5mbps + // 720p@30 = 2.5mbps + // 720p@60 = 3.5mpbs + // 1080p@30 = 4.5mbps + // 1080p@60 = 6.0mbps + + // 30fps is the baseline, applying a multiplier for higher framerates. + // Framerate does not cause a multiplicative increase in bitrate because of delta encoding. + // TODO Make this better. + const framerateFactor = 30.0 + (target.framerate - 30) / 2; + + // ACTUAL BITRATE CALCULATION + // 480p@30 = 409920 * 30 * 0.07 = 0.9 Mb/s + // 480p@60 = 409920 * 45 * 0.07 = 1.3 Mb/s + // 720p@30 = 921600 * 30 * 0.07 = 1.9 Mb/s + // 720p@60 = 921600 * 45 * 0.07 = 2.9 Mb/s + // 1080p@30 = 2073600 * 30 * 0.07 = 4.4 Mb/s + // 1080p@60 = 2073600 * 45 * 0.07 = 6.5 Mb/s + const bitrate = Math.round(maxPixels * target.bitrateScale * framerateFactor * codecBitrateScale(codec)); + const capped = Math.round(Math.min(bitrate, target.maxBitrate || bitrate)); + + // Refuse a bad knob here, before the browser coerces it into an unsigned bitrate. + if (!(capped > 0)) throw new Error(`bitrate must be positive: ${capped}`); + return capped; +} + +// Encode one frame with a throwaway encoder and return the codec string it reports, like +// moq-video's `Config::probe`. The encoder picks the profile and level it actually writes, so reading +// them back lets the rendition be advertised before a subscriber starts the real encoder, without a +// claim the first keyframe would contradict. It closes before the config resolves, so it never +// overlaps the first real encoder; only a re-probe while serving briefly holds two sessions. +async function reportedCodec(config: VideoEncoderConfig): Promise { + let reported: string | undefined; + const encoder = new VideoEncoder({ + output: (_chunk, metadata) => { + reported ??= metadata?.decoderConfig?.codec; + }, + // flush() rejects with the same error. + error: () => {}, + }); + + try { + encoder.configure(config); + + // Mid-gray, since the picture only has to make the encoder emit its config. + const { width, height } = config; + const frame = new VideoFrame(new Uint8Array((width * height * 3) / 2).fill(0x80), { + format: "I420", + codedWidth: width, + codedHeight: height, + timestamp: 0, + }); + try { + encoder.encode(frame, { keyFrame: true }); + } finally { + frame.close(); + } + + await encoder.flush(); + } finally { + if (encoder.state !== "closed") encoder.close(); + } + + if (!reported) throw new Error(`${config.codec} encoder reported no codec string`); + return reported; +} + // Scale the bitrate for more efficient codecs, relative to H.264. // TODO This shouldn't be linear, as the efficiency is very similar at low bitrates. function codecBitrateScale(codec: string): number { diff --git a/js/wasm/.gitignore b/js/wasm/.gitignore index d3d540b01fb..b7322370aeb 100644 --- a/js/wasm/.gitignore +++ b/js/wasm/.gitignore @@ -1,3 +1,3 @@ -# Generated by `just wasm` (wasm-bindgen). The .wasm binary and JS glue are +# Generated by `just js wasm` (wasm-bindgen). The .wasm binary and JS glue are # build artifacts, not source: build them, never commit them. /dist/ diff --git a/js/wasm/README.md b/js/wasm/README.md index a3f2c2f2949..0cb4a6c4686 100644 --- a/js/wasm/README.md +++ b/js/wasm/README.md @@ -32,7 +32,7 @@ calls. Freeing a `Session` also closes it. `dist/` is generated, not committed. Build it from the repo root: ```bash -just wasm +just js wasm ``` That compiles `rs/moq-wasm` for `wasm32-unknown-unknown`, runs `wasm-bindgen` diff --git a/js/watch/src/audio/buffer.test.ts b/js/watch/src/audio/buffer.test.ts new file mode 100644 index 00000000000..07499287778 --- /dev/null +++ b/js/watch/src/audio/buffer.test.ts @@ -0,0 +1,28 @@ +import { describe, expect, it } from "bun:test"; +import type { Time } from "@moq/net"; +import { createAudioBuffer } from "./buffer"; +import type { InitShared } from "./render"; +import { SharedRingBuffer } from "./shared-ring-buffer"; + +describe("SharedAudioBuffer", () => { + // The worklet keeps reading the old ring until `init-shared` lands, so a rise that grows the ring + // has to park that one too, or audio drains ahead of video in between. + it("parks the ring the worklet still reads when a rise grows it", () => { + const sent: InitShared[] = []; + const worklet = { port: { postMessage: (msg: InitShared) => sent.push(msg) } } as unknown as AudioWorkletNode; + const buffer = createAudioBuffer(worklet, 1, 1000, 100); + try { + const old = new SharedRingBuffer(sent[0]); + buffer.insert(0 as Time.Micro, [new Float32Array(100).fill(1.0)]); + expect(old.read([new Float32Array(50)])).toBe(50); + + buffer.setLatency(1000); + expect(sent.length).toBe(2); + expect(old.stalled).toBe(true); + expect(old.read([new Float32Array(50)])).toBe(0); + expect(new SharedRingBuffer(sent[1]).stalled).toBe(true); + } finally { + buffer.close(); + } + }); +}); diff --git a/js/watch/src/audio/buffer.ts b/js/watch/src/audio/buffer.ts index 4c3a0263e5d..528ed936081 100644 --- a/js/watch/src/audio/buffer.ts +++ b/js/watch/src/audio/buffer.ts @@ -188,16 +188,17 @@ class SharedAudioBuffer implements AudioBuffer { setLatency(samples: number): void { this.#backpressure.setHeadroom(samplesToMicro(samples, this.rate)); + // Park the current ring before any resize: the worklet keeps reading it until `init-shared` + // lands, and `resize` carries the floor and the park over to the copy. + this.#ring.setLatency(samples); + // Grow the ring (preserving the unread window) if it's too small for the new latency. if (this.#ring.capacity < samples * 1.5) { const newCapacity = Math.max(this.rate, samples * 2); this.#ring = this.#ring.resize(newCapacity); - this.#ring.setLatency(samples); const msg: InitShared = { type: "init-shared", ...this.#ring.init }; this.#worklet.port.postMessage(msg); - } else { - this.#ring.setLatency(samples); } } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 8745d04af45..1af6875c66f 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -20,17 +20,13 @@ import type { Sync } from "../sync"; import { type AudioBuffer, createAudioBuffer } from "./buffer"; import { type DecoderConfig, decoderConfig, type PlaybackIdentity, playbackIdentity } from "./config"; import { Handover } from "./handover"; -import { reanchorFloor, ringSamples } from "./latency"; +import { ringSamples } from "./latency"; // Compiled and inlined as a blob URL via vite-plugin-worklet. import RenderWorklet from "./render-worklet.ts?worklet"; import type { Source } from "./source"; import { type DecodedSpan, Terminal } from "./terminal"; import { Warmup } from "./warmup"; -// How long the latency target must hold steady before a floor increase re-anchors. Coalesces a -// slider drag (many small steps) into a single re-anchor once the user settles on a value. -const LATENCY_REANCHOR_DEBOUNCE_MS = 150; - const LEGACY_WARMUP_CALLBACKS = 3; export type DecoderInput = { @@ -108,10 +104,6 @@ export class Decoder { // Ordered discontinuity and endpoint state from the container consumer. #terminal = new Terminal(); - // The latency floor as of the last settled change, to detect a floor *increase* (needs a deeper - // cushion) versus a decrease or a real-time RTT wiggle. See #runLatencyReanchor. - #prevFloor?: Time.Milli; - // Which subscription the ring's buffered samples came from. See #runDecoder. #handover = new Handover(); @@ -144,7 +136,6 @@ export class Decoder { this.#signals.run(this.#runWorklet.bind(this)); this.#signals.run(this.#runEnabled.bind(this)); this.#signals.run(this.#runLatency.bind(this)); - this.#signals.run(this.#runLatencyReanchor.bind(this)); this.#signals.run(this.#runDecoder.bind(this)); } @@ -247,39 +238,12 @@ export class Decoder { const ring = this.#ring; if (!ring) return; + // A rise parks playback until the ring refills to the new floor, which is what keeps audio in + // step with video. A catalog's jitter estimate can rise a millisecond at a time. const delay = effect.get(this.sync.out.delay); ring.setLatency(ringSamples(ring.rate, delay)); } - // Re-anchor when the delay floor *increases*. A larger floor needs a deeper cushion: video - // rebuilds it implicitly (its per-frame sync.wait() reads the live buffer, so it just holds - // longer), but the audio ring keeps draining at its old depth -- resize() (via setLatency) only - // re-stalls an *empty* ring, so a mid-playback ring never refills to the new floor and audio runs - // ahead of video (the "raise latency, only video re-buffers" desync). reset() re-stalls the ring - // so it refills to the new floor. Watch the latency target and media delay, excluding adaptive - // RTT jitter, and debounce so a slider drag coalesces into one re-anchor. Decreases are left to - // natural catch-up. - #runLatencyReanchor(effect: Effect): void { - const delay = effect.get(this.sync.out.delay); - const jitter = effect.get(this.sync.out.jitter); - const floor = reanchorFloor({ - delay: effect.get(this.sync.in.delay), - media: Time.Milli.sub(delay, jitter), - }); - if (this.#prevFloor === undefined) { - // Startup: the initial fill already builds the cushion; just record the baseline. - this.#prevFloor = floor; - return; - } - // When the timer fires, the floor read above is still current: any change would have rerun - // this effect (tearing down the timer), so compare it against the pre-change baseline directly. - const baseline = this.#prevFloor; - effect.timer(() => { - if (floor > baseline) this.reset(); - this.#prevFloor = floor; - }, LATENCY_REANCHOR_DEBOUNCE_MS); - } - #runDecoder(effect: Effect): void { const enabled = effect.get(this.in.enabled); if (!enabled) return; diff --git a/js/watch/src/audio/latency.test.ts b/js/watch/src/audio/latency.test.ts index ecc7c1f4d23..e6918210456 100644 --- a/js/watch/src/audio/latency.test.ts +++ b/js/watch/src/audio/latency.test.ts @@ -1,20 +1,9 @@ import { describe, expect, it } from "bun:test"; import type { Time } from "@moq/net"; -import { reanchorFloor, ringSamples } from "./latency"; +import { ringSamples } from "./latency"; const ms = (value: number) => value as Time.Milli; -describe("reanchorFloor", () => { - it("includes the fixed delay and the largest media delay", () => { - expect(reanchorFloor({ delay: ms(100), media: ms(80) })).toBe(ms(180)); - }); - - it("tracks rendition delay without adaptive RTT jitter", () => { - expect(reanchorFloor({ delay: "auto", media: ms(80) })).toBe(ms(80)); - expect(reanchorFloor({ delay: "auto", media: ms(200) })).toBe(ms(200)); - }); -}); - describe("ringSamples", () => { // `delay="instant"` reports a zero buffer. Passed through, the ring rejects it and the // worklet is left with no backend that any later resize can revive. diff --git a/js/watch/src/audio/latency.ts b/js/watch/src/audio/latency.ts index 1766d2b8d58..1885d28fd9f 100644 --- a/js/watch/src/audio/latency.ts +++ b/js/watch/src/audio/latency.ts @@ -1,22 +1,4 @@ import { Time } from "@moq/net"; -import type { Delay } from "../sync"; - -/** The inputs that determine whether audio needs a deeper playback cushion. */ -export interface ReanchorFloor { - /** How far playback trails the live edge. */ - delay: Delay; - - /** Largest additional delay required by the registered media decoders. */ - media?: Time.Milli; -} - -/** The stable delay floor whose increase requires the audio ring to refill. */ -export function reanchorFloor(props: ReanchorFloor): Time.Milli { - // "auto" and "instant" contribute nothing: the adaptive RTT component is deliberately excluded - // so an RTT wiggle doesn't re-anchor, and "instant" holds nothing at all. - const target = typeof props.delay === "number" ? props.delay : Time.Milli.zero; - return Time.Milli.add(target, props.media ?? Time.Milli.zero); -} // An AudioWorkletProcessor renders in fixed 128-sample quanta, so a ring shallower than one can // never be read from. diff --git a/js/watch/src/audio/ring-buffer.test.ts b/js/watch/src/audio/ring-buffer.test.ts index 5d1fb2ceba0..a53d2111e1f 100644 --- a/js/watch/src/audio/ring-buffer.test.ts +++ b/js/watch/src/audio/ring-buffer.test.ts @@ -419,7 +419,7 @@ describe("resize", () => { expect(buffer.capacity).toBe(50); expect(buffer.length).toBe(50); // Truncated to new capacity - expect(buffer.stalled).toBe(true); // Should trigger stall + expect(buffer.stalled).toBe(false); // Already covers the new floor }); it("should be a no-op when capacity is unchanged", () => { @@ -458,7 +458,7 @@ describe("resize", () => { buffer.resize(50 as Time.Milli); expect(buffer.capacity).toBe(50); expect(buffer.length).toBe(50); - expect(buffer.stalled).toBe(true); + expect(buffer.stalled).toBe(false); }); it("should handle resize when buffer is empty", () => { @@ -495,17 +495,16 @@ describe("resize", () => { expect(buffer.stalled).toBe(false); }); - it("should exit stall and read new data after resize", () => { + it("should resume and then read new data after a shrinking resize", () => { const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); // Write some initial data write(buffer, 0 as Time.Milli, 50, { channels: 1, value: 1.0 }); - // Resize to smaller buffer + // Resize to a floor the buffered data already covers buffer.resize(50 as Time.Milli); - expect(buffer.stalled).toBe(true); + expect(buffer.stalled).toBe(false); - // Write new data to fill the buffer and exit stall // The overflow will discard preserved samples and advance readIndex write(buffer, 50 as Time.Milli, 50, { channels: 1, value: 2.0 }); expect(buffer.stalled).toBe(false); @@ -771,31 +770,52 @@ describe("buffered mode", () => { }); }); -describe("latency increase re-anchor", () => { - it("resize() does not re-stall a mid-playback ring, but reset() does", () => { +describe("latency increase", () => { + // Video holds a deeper floor on its own, so audio has to park for the difference or it runs + // ahead. Flushing instead cost the whole floor in silence for every rise, however small. + it("parks a playing ring until the deeper floor refills, keeping what it buffered", () => { const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); - // Fill to the floor so playback starts (un-stalls), then play some samples. + // Fill to the floor so playback starts, then play half of it. write(buffer, 0 as Time.Milli, 100, { channels: 1, value: 1.0 }); expect(buffer.stalled).toBe(false); read(buffer, 50, 1); - // Raising the latency floor grows the target but must NOT re-stall a ring mid-playback: - // resize() only re-stalls an empty ring, so it keeps draining at the old depth. This is - // exactly why setLatency() alone doesn't re-buffer -- the desync the Decoder re-anchor fixes. - buffer.resize(200 as Time.Milli); - expect(buffer.stalled).toBe(false); + buffer.resize(110 as Time.Milli); + expect(buffer.stalled).toBe(true); + expect(buffer.length).toBe(50); - // reset() re-stalls, so the ring refills to the (new) floor before playing again. The Decoder - // calls reset() on a latency-floor increase (#runLatencyReanchor) to re-anchor to the cushion. - buffer.reset(); + // Refilling to the 110-sample floor takes 60 more samples, not the whole floor. + write(buffer, 100 as Time.Milli, 59, { channels: 1, value: 2.0 }); expect(buffer.stalled).toBe(true); + write(buffer, 159 as Time.Milli, 1, { channels: 1, value: 2.0 }); + expect(buffer.stalled).toBe(false); + + // Playback resumes where it parked rather than at the refill. + expect(Time.Milli.fromMicro(buffer.timestamp)).toBe(50 as Time.Milli); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); + }); - // ...and it refills to the *new* 200-sample floor, not the old 100: still stalled at 199, - // un-stalls only once the 200th sample lands. This proves resize(200) moved the target. - write(buffer, 0 as Time.Milli, 199, { channels: 1, value: 1.0 }); + it("keeps playing through a shallower floor", () => { + const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); + write(buffer, 0 as Time.Milli, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.resize(90 as Time.Milli); + expect(buffer.stalled).toBe(false); + }); + + it("resumes a refill once a shallower floor is already covered", () => { + const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); + write(buffer, 0 as Time.Milli, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.resize(110 as Time.Milli); expect(buffer.stalled).toBe(true); - write(buffer, 199 as Time.Milli, 1, { channels: 1, value: 1.0 }); + + // No further frame arrives, as when the source stops, so only the lower floor can resume it. + buffer.resize(50 as Time.Milli); expect(buffer.stalled).toBe(false); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); }); }); diff --git a/js/watch/src/audio/ring-buffer.ts b/js/watch/src/audio/ring-buffer.ts index fb94f036928..38387a13a3b 100644 --- a/js/watch/src/audio/ring-buffer.ts +++ b/js/watch/src/audio/ring-buffer.ts @@ -65,10 +65,24 @@ export class AudioRingBuffer { } resize(latency: Time.Milli): void { - this.#latencySamples = Math.ceil(this.rate * Time.Second.fromMilli(latency)); + const latencySamples = Math.ceil(this.rate * Time.Second.fromMilli(latency)); + + // A deeper floor parks playback until it refills. Video holds the extra delay on its own, so + // audio that kept draining at the old depth would run ahead by the difference. Parking keeps + // what is buffered, so a rise costs only its own size in silence, and none if the buffer + // already covers the new floor. + if (latencySamples > this.#latencySamples) this.#stalled = true; + this.#latencySamples = latencySamples; const newCapacity = this.#capacityFor(this.#latencySamples); - if (newCapacity === this.capacity) return; + if (newCapacity !== this.capacity) this.#reallocate(newCapacity); + + // Resume a refill that the buffer already covers, which `write` would only notice on the + // next frame, never for a source that has stopped. + if (latencySamples > 0 && this.length >= latencySamples) this.#stalled = false; + } + + #reallocate(newCapacity: number): void { if (newCapacity === 0) throw new Error("empty buffer"); const newBuffer: Float32Array[] = []; diff --git a/js/watch/src/audio/shared-ring-buffer.test.ts b/js/watch/src/audio/shared-ring-buffer.test.ts index 2647ea3cc7e..72e3a621a48 100644 --- a/js/watch/src/audio/shared-ring-buffer.test.ts +++ b/js/watch/src/audio/shared-ring-buffer.test.ts @@ -476,6 +476,104 @@ describe("setLatency", () => { const output2 = read(buffer, 128, 1); expect(output2[0].length).toBe(20); }); + + // Video holds a deeper floor on its own, so audio has to park for the difference or it runs + // ahead. Flushing instead cost the whole floor in silence for every rise, however small. + it("parks a playing ring until the deeper floor refills, keeping what it buffered", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 100, { channels: 1, value: 1.0 }); + expect(buffer.stalled).toBe(false); + read(buffer, 50, 1); + + buffer.setLatency(110); + expect(buffer.stalled).toBe(true); + expect(read(buffer, 128, 1)[0].length).toBe(0); + + // Refilling to the 110-sample floor takes 60 more samples, not the whole floor. + insert(buffer, 100, 59, { channels: 1, value: 2.0 }); + expect(buffer.stalled).toBe(true); + insert(buffer, 159, 1, { channels: 1, value: 2.0 }); + expect(buffer.stalled).toBe(false); + + // Playback resumes where it parked rather than at the refill. + expect(Time.Milli.fromMicro(buffer.timestamp)).toBe(50 as Time.Milli); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); + }); + + it("silences a quantum already in flight when the floor rises", () => { + const init = allocSharedRingBuffer(1, 256, 1000); + const main = new SharedRingBuffer(init); + main.setLatency(100); + insert(main, 0, 100, { channels: 1, value: 1.0 }); + const worklet = new SharedRingBuffer(init); + const out = [new Float32Array(50).fill(-1)]; + + // Raise the floor from inside the read's LATENCY load: past the STALLED check, before the + // copy and publish, which is where the worklet sits whenever the two threads overlap. + const LATENCY = 1; + let fired = false; + const realLoad = Atomics.load; + const atomics = Atomics as { load: unknown }; + atomics.load = (arr: Int32Array | BigInt64Array, idx: number) => { + const value = realLoad(arr as Int32Array, idx); + if (!fired && arr instanceof Int32Array && idx === LATENCY) { + fired = true; + main.setLatency(110); + } + return value; + }; + + let result = -1; + try { + result = worklet.read(out); + } finally { + atomics.load = realLoad; + } + expect(fired).toBe(true); + + // The quantum raced the park, so none of it renders and the playhead stays put. + expect(result).toBe(0); + expect(out[0]).toEqual(new Float32Array(50)); + expect(Time.Milli.fromMicro(main.timestamp)).toBe(0 as Time.Milli); + + insert(main, 100, 10, { channels: 1, value: 2.0 }); + expect(main.stalled).toBe(false); + expect(read(worklet, 1, 1)[0][0]).toBe(1.0); + }); + + it("keeps playing through a shallower floor", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.setLatency(90); + expect(buffer.stalled).toBe(false); + }); + + it("keeps playing through a deeper floor the buffer already covers", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 40, { channels: 1, value: 1.0 }); + insert(buffer, 40, 110, { channels: 1, value: 2.0 }); + + buffer.setLatency(110); + expect(buffer.stalled).toBe(false); + // The skip lands on the new floor: the last 110 samples. + expect(read(buffer, 1, 1)[0][0]).toBe(2.0); + }); + + it("resumes a refill once a shallower floor is already covered", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.setLatency(110); + expect(buffer.stalled).toBe(true); + + // No further frame arrives, as when the source stops, so only the lower floor can resume it. + buffer.setLatency(50); + expect(buffer.stalled).toBe(false); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); + }); }); describe("stalled getter", () => { diff --git a/js/watch/src/audio/shared-ring-buffer.ts b/js/watch/src/audio/shared-ring-buffer.ts index ce790948547..f4c0ba2a4f2 100644 --- a/js/watch/src/audio/shared-ring-buffer.ts +++ b/js/watch/src/audio/shared-ring-buffer.ts @@ -206,14 +206,14 @@ export class SharedRingBuffer { } /** - * Step the epoch by one, leaving the playhead wherever the reader has taken it. + * Step the epoch by `by`, leaving the playhead wherever the reader has taken it. * * Retries while the word changes under it: only the epoch half is the writer's to move. */ - #step(): void { + #step(by: number): void { for (;;) { const state = Atomics.load(this.#state, 0); - const next = pack((epochOf(state) + 1) | 0, readOf(state)); + const next = pack((epochOf(state) + by) | 0, readOf(state)); if (Atomics.compareExchange(this.#state, 0, state, next) === state) return; } } @@ -300,11 +300,15 @@ export class SharedRingBuffer { // Advance WRITE (only forward) Atomics.store(this.#control, WRITE, i32Max(Atomics.load(this.#control, WRITE), end)); - // Un-stall: if buffered data >= LATENCY - const currentRead = readOf(Atomics.load(this.#state, 0)); - const currentWrite = Atomics.load(this.#control, WRITE); + this.#resume(); + } + + // Un-stall once the buffered data covers LATENCY. + #resume(): void { + const read = readOf(Atomics.load(this.#state, 0)); + const write = Atomics.load(this.#control, WRITE); const latency = Atomics.load(this.#control, LATENCY); - if (((currentWrite - currentRead) | 0) >= latency && latency > 0) { + if (((write - read) | 0) >= latency && latency > 0) { Atomics.store(this.#control, STALLED, 0); } } @@ -371,9 +375,28 @@ export class SharedRingBuffer { return count; } - /** Update the target latency in samples. */ + /** + * Update the target latency in samples. Main thread only. + * + * A deeper floor parks playback until it refills. Video holds the extra delay on its own, so + * audio that kept draining at the old depth would run ahead by the difference. Parking keeps + * what is buffered, so a rise costs only its own size in silence, and none if the buffer + * already covers the new floor. + */ setLatency(samples: number): void { - Atomics.store(this.#control, LATENCY, samples); + const previous = Atomics.exchange(this.#control, LATENCY, samples); + if (previous > 0 && samples > previous) { + Atomics.store(this.#control, STALLED, 1); + // A reader already past the STALLED check would still publish its quantum. Moving the + // word fails its exchange, and one that snapshots after this sees STALLED. Two keeps the + // epoch even, since odd belongs to `truncate`. + this.#step(2); + } + + // Parked, the playhead holds still, so this measures exactly what is buffered. It also + // resumes a refill that a shallower floor has already covered, which `insert` would only + // notice on the next frame, never for a source that has stopped. + this.#resume(); } /** @@ -389,7 +412,7 @@ export class SharedRingBuffer { // Bracket the retreat with epoch steps, so a reader is never left holding a WRITE this // dropped the tail of. See `epochOf`. - this.#step(); + this.#step(1); for (;;) { const write = Atomics.load(this.#control, WRITE); // Never retreat past the playhead: those samples are already due. The worklet can still @@ -401,7 +424,7 @@ export class SharedRingBuffer { if (((write - clamped) | 0) <= 0) break; if (Atomics.compareExchange(this.#control, WRITE, write, clamped) === write) break; } - this.#step(); + this.#step(1); } /** diff --git a/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index fac3a7bbde7..b1565a597db 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -1,6 +1,7 @@ -import { describe, expect, it } from "bun:test"; +import { describe, expect, it, spyOn } from "bun:test"; import * as Catalog from "@moq/hang/catalog"; -import type * as Moq from "@moq/net"; +import * as Container from "@moq/hang/container"; +import * as Moq from "@moq/net"; import { Time } from "@moq/net"; import { Signal } from "@moq/signals"; import type { Broadcast } from "../broadcast"; @@ -147,3 +148,144 @@ describe("Decoder jitter across a source switch", () => { } }); }); + +// Drain reactive work without advancing playback time. +async function microtasks() { + for (let i = 0; i < 40; i++) await Promise.resolve(); +} + +class Picture { + closed = false; + displayWidth = 16; + displayHeight = 16; + readonly timestamp: number; + constructor(timestamp: number) { + this.timestamp = timestamp; + } + clone() { + return new Picture(this.timestamp); + } + close() { + this.closed = true; + } +} + +type Read = NonNullable>>; +function sample(group: number, timestamp: number, discontinuity = 0): Read { + return { + group, + discontinuity, + continuous: true, + frame: { timestamp: Time.Micro(timestamp), payload: new Uint8Array([1]), keyframe: true }, + }; +} + +async function guardedPlayback(kind: "legacy" | "cmaf", reads: Read[]) { + const originalDecoder = Object.getOwnPropertyDescriptor(globalThis, "VideoDecoder"); + const originalChunk = Object.getOwnPropertyDescriptor(globalThis, "EncodedVideoChunk"); + const submitted: number[] = []; + const next = spyOn(Container.Consumer.prototype, "next").mockImplementation(async () => reads.shift()); + class Codec { + state = "configured"; + readonly callbacks: VideoDecoderInit; + constructor(callbacks: VideoDecoderInit) { + this.callbacks = callbacks; + } + configure() {} + decode(chunk: EncodedVideoChunk) { + submitted.push(chunk.timestamp); + this.callbacks.output(new Picture(chunk.timestamp) as unknown as VideoFrame); + } + close() { + this.state = "closed"; + } + } + Object.defineProperty(globalThis, "VideoDecoder", { configurable: true, value: Codec }); + Object.defineProperty(globalThis, "EncodedVideoChunk", { + configurable: true, + value: class { + timestamp: number; + constructor(init: EncodedVideoChunkInit) { + this.timestamp = init.timestamp; + } + }, + }); + const video = config({ codedWidth: 16, codedHeight: 16, description: "01640028ffe100046764002801000268ee" }); + if (kind === "cmaf") + video.container = { kind, init: Buffer.from(Container.Cmaf.createVideoInitSegment(video)).toString("base64") }; + const producer = new Moq.Broadcast.Producer(); + const consumer = producer.consume(); + const catalog = new Signal({ video: { renditions: { video } } }); + const broadcast = new Signal({ + out: { catalog }, + relativeBroadcast: () => consumer, + } as unknown as Broadcast); + const source = new Source({ broadcast, supported: async () => true }); + const sync = new Sync({ delay: "instant" }); + const enabled = new Signal(true); + const decoder = new Decoder({ source, sync, enabled }); + await microtasks(); + return { + decoder, + enabled, + submitted, + close() { + decoder.close(); + source.close(); + sync.close(); + consumer.close(); + producer.close(); + next.mockRestore(); + for (const [name, original] of [ + ["VideoDecoder", originalDecoder], + ["EncodedVideoChunk", originalChunk], + ] as const) { + if (original) Object.defineProperty(globalThis, name, original); + else Reflect.deleteProperty(globalThis, name); + } + }, + }; +} + +it("promoting from no active track holds its picture and timestamp until a frame arrives", async () => { + const playback = await guardedPlayback("legacy", [sample(10, 1000)]); + try { + const held = playback.decoder.out.frame.peek(); + expect(held).toBeDefined(); + expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(1)); + playback.enabled.set(false); + await microtasks(); + playback.enabled.set(true); + await microtasks(); + expect(playback.decoder.out.frame.peek()).toBe(held); + expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(1)); + expect((held as unknown as Picture).closed).toBe(false); + } finally { + playback.close(); + } +}); + +// A late marker from older history raises a discontinuity without making older groups newer. +function marker(group: number, end: number, discontinuity: number): Read { + return { group, discontinuity, continuous: false, frame: undefined, end: Time.Micro(end) }; +} + +for (const kind of ["legacy", "cmaf"] as const) { + it(`${kind} skips older groups before decode, even across a stale marker's discontinuity`, async () => { + const playback = await guardedPlayback(kind, [ + sample(10, 1000), + sample(9, 900), + sample(10, 1100), + marker(8, 850, 1), + sample(7, 700, 1), + sample(11, 1200, 1), + ]); + try { + expect(playback.submitted).toEqual([1000, 1100, 1200]); + // Rejected payloads were still received, but never counted as frames. + expect(playback.decoder.out.stats.peek()).toEqual({ frameCount: 3, bytesReceived: 5 }); + } finally { + playback.close(); + } + }); +} diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 592eb898d33..2d91fdb0d13 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -222,12 +222,13 @@ export class Decoder { // proxy() would share the same reference, allowing the source to close our frame. effect.run((inner) => { const frame = inner.get(active.frame); + if (!frame) return; // A promoted track holds the previous picture until its first frame. + this.#out.timestamp.set(Time.Milli.fromMicro(frame.timestamp as Time.Micro)); this.#out.frame.update((prev) => { prev?.close(); - return frame?.clone(); + return frame.clone(); }); }); - effect.proxy(this.#out.timestamp, active.timestamp); effect.proxy(this.#out.buffered, active.buffered); } @@ -428,6 +429,7 @@ class DecoderTrack { }); let previous: Time.Micro | undefined; + let latest: number | undefined; effect.spawn(async () => { for (;;) { @@ -440,6 +442,16 @@ class DecoderTrack { const { frame } = next; if (!frame) continue; // The group is done + // An older keyframe would replace the codec references needed by live deltas. Group + // sequences only grow within a subscription, so a discontinuity (which a stale marker + // can raise) never resets this guard. Rejected payloads still count as received bytes. + const stale = latest !== undefined && next.group < latest; + this.stats.update((current) => ({ + frameCount: (current?.frameCount ?? 0) + (stale ? 0 : 1), + bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, + })); + if (stale) continue; + // Mark that we received this frame right now. const timestamp = Time.Milli.fromMicro(frame.timestamp as Time.Micro); this.sync.received(timestamp, "video"); @@ -450,12 +462,6 @@ class DecoderTrack { timestamp: frame.timestamp, }); - // Track both frame count and bytes received for stats in the UI - this.stats.update((current) => ({ - frameCount: (current?.frameCount ?? 0) + 1, - bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, - })); - // Track decode buffer: frames sent to decoder but not yet rendered. Only bridge from // the previous frame when the consumer says nothing is missing in between. Group ids // can't answer that: they aren't required to be sequential (some encoders derive them @@ -467,6 +473,7 @@ class DecoderTrack { previous = frame.timestamp; + latest = next.group; decoder.decode(chunk); } }); @@ -505,6 +512,7 @@ class DecoderTrack { }); let previous: Time.Micro | undefined; + let latest: number | undefined; effect.spawn(async () => { for (;;) { @@ -517,15 +525,19 @@ class DecoderTrack { const { frame } = next; if (!frame) continue; - // Mark that we received this frame right now. - const timestamp = Time.Milli.fromMicro(frame.timestamp); - this.sync.received(timestamp, "video"); - - // Track stats + // An older keyframe would replace the codec references needed by live deltas. Group + // sequences only grow within a subscription, so a discontinuity (which a stale marker + // can raise) never resets this guard. Rejected payloads still count as received bytes. + const stale = latest !== undefined && next.group < latest; this.stats.update((current) => ({ - frameCount: (current?.frameCount ?? 0) + 1, + frameCount: (current?.frameCount ?? 0) + (stale ? 0 : 1), bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, })); + if (stale) continue; + + // Mark that we received this frame right now. + const timestamp = Time.Milli.fromMicro(frame.timestamp); + this.sync.received(timestamp, "video"); // Track decode buffer (see #runLegacy: bridge on the consumer's continuity signal, // never on group adjacency, which proves nothing about the timeline). @@ -536,6 +548,7 @@ class DecoderTrack { previous = frame.timestamp; if (decoder.state === "closed") break; + latest = next.group; decoder.decode( new EncodedVideoChunk({ type: frame.keyframe ? "key" : "delta", diff --git a/justfile b/justfile index 669c36022a6..c20feb7f2d6 100644 --- a/justfile +++ b/justfile @@ -1,5 +1,8 @@ #!/usr/bin/env just --justfile # Using Just: https://github.com/casey/just?tab=readme-ov-file#installation +# +# Every recipe is a menu entry: one line that runs a tool, or a script under +# sh/. Logic belongs in the script. set unstable @@ -29,10 +32,6 @@ mod relay 'demo/relay' mod sub 'demo/sub' mod web 'demo/web' -# Byte budget for a changed-file list, sized so it survives being passed as a -# single argv/env string on every hop of the dispatch. See `_changed`. -changed_max := '65536' - # Run the demo by default. default: just demo @@ -43,912 +42,47 @@ dev: # Benchmark the current tree, or compare it with a commit: `just bench origin/main`. bench $BASE="": - #!/usr/bin/env bash - exec just --justfile bench/justfile compare "$BASE" + bench/run.sh "$BASE" # Compare one multi-threaded Tokio runtime with the same number of independent -# Tokio/epoll and io_uring workers. Defaults to every logical CPU. -bench-runtime $ROUNDS="3" $WORKERS="": - #!/usr/bin/env bash - exec just --justfile bench/justfile runtime "$ROUNDS" "$WORKERS" - -# A linked worktree's Git metadata does not live under its own root: the -# per-worktree directory is `--git-dir` and everything shared (objects, remote -# refs, the branch namespace) is under `--git-common-dir`, which for an agent -# checkout is inside the main repository. Write access to the source tree -# therefore says nothing about whether this checkout can fetch, branch, or -# rebase; the answer is a property of those two directories, and finding out by -# running `git fetch` and reading the error is the slow way. -# -# `check` reports; `setup` fetches, points the branch at its base, and records -# the SHA it fetched under the per-worktree Git directory, where `check` reads it -# back to say how stale the recorded base has become. Neither ever resets, -# rebases, cleans, or checks anything out: a dirty tree is someone's work in -# progress, and adopting a checkout must not be able to destroy it. -# -# BASE follows the same rule as the rest of the repo (see `_base`): `main` -# unless the branch's upstream says otherwise. - -# Report a worktree's base, Git metadata access, and state; `setup` also fetches. -worktree ACTION="check" $BASE="": - #!/usr/bin/env bash - set -euo pipefail - - case "{{ ACTION }}" in - check | setup) ;; - *) - echo "usage: just worktree [check|setup] [BASE]" >&2 - exit 2 - ;; - esac - - root=$(git rev-parse --show-toplevel) - git_dir=$(cd "$(git rev-parse --git-dir)" && pwd) - common_dir=$(cd "$(git rev-parse --git-common-dir)" && pwd) - branch=$(git branch --show-current || true) - - # A written probe rather than `[[ -w ]]`: the directory can be readable and - # nominally writable while the sandbox, a read-only mount, or an ACL refuses - # the create, and it is the create that fetch and branch creation need. - access() { - local dir="$1" probe - [[ -d "$dir" ]] || { echo missing; return; } - [[ -r "$dir" ]] || { echo denied; return; } - probe="$dir/.moq-access-probe.$$" - if (umask 077 && : > "$probe") 2>/dev/null; then - rm -f "$probe" - echo write - else - echo read-only - fi - } - - # A directory git will create on demand is only as writable as its nearest - # existing parent, so probe upward instead of reporting it missing. - access_or_parent() { - local dir="$1" parent - while [[ ! -d "$dir" ]]; do - parent=$(dirname "$dir") - [[ "$parent" != "$dir" ]] || { echo missing; return; } - dir="$parent" - done - access "$dir" - } - - base=$(just _base "$BASE") - stamp="$git_dir/moq-base" - # Whichever remote provides the base, not always origin. A base whose first - # segment names no remote (a local branch, a tag) leaves origin. - remote="${base%%/*}" - git remote | grep -qx "$remote" || remote=origin - - objects=$(access "$common_dir/objects") - heads=$(access "$common_dir/refs/heads") - worktree_meta=$(access "$git_dir") - worktree=$(access "$root") - # Tracking is `branch..remote`/`.merge` in the repository config, which - # lives in the common directory alongside the `config.lock` the write needs, - # not in the branch's ref. Probing refs/heads for it would refuse on a - # writable config and, worse, proceed on a read-only one. - config=$(access "$common_dir") - # A fetch writes three places, not one: objects, the remote-tracking refs it - # updates, and FETCH_HEAD in the per-worktree directory. The refs are the - # narrow one: `refs/remotes/` is where `.lock` is created, so - # probing `refs/remotes` stops a directory short and passes a split that git - # then fails on. - tracking=$(access_or_parent "$common_dir/refs/remotes/$remote") - - echo "worktree: $root" - echo "branch: ${branch:-(detached)} $(git rev-parse --short HEAD)" - echo "git-dir: $git_dir ($worktree_meta)" - echo "common-dir: $common_dir ($config)" - echo " fetch needs $common_dir/objects: $objects" - echo " $common_dir/refs/remotes/$remote: $tracking" - echo " $git_dir (FETCH_HEAD): $worktree_meta" - echo " branch needs $common_dir/refs/heads: $heads" - echo " upstream needs $common_dir/config: $config" - echo " rebase needs $git_dir: $worktree_meta" - echo " $root: $worktree" - echo " $common_dir/refs/heads: $heads" - - dirty=$(git status --porcelain | wc -l | tr -d ' ') - echo "dirty: $dirty tracked/untracked path(s)" +# Tokio/epoll and io_uring workers; WORKERS defaults to every logical CPU. - if [[ "{{ ACTION }}" == setup ]]; then - blocked="" - [[ "$objects" == write ]] || blocked="$blocked $common_dir/objects ($objects)" - [[ "$tracking" == write ]] || blocked="$blocked $common_dir/refs/remotes/$remote ($tracking)" - [[ "$worktree_meta" == write ]] || blocked="$blocked $git_dir ($worktree_meta)" - if [[ -n "$blocked" ]]; then - echo "error: cannot fetch;$blocked" >&2 - echo " grant write access to the main repository's Git directory, not just this worktree" >&2 - exit 1 - fi - # The remote resolved above, not always origin: recording a stamp against a - # ref nobody refreshed is worse than recording none, and `just check` would - # scope the branch against a base that has since moved. - git fetch --quiet "$remote" - # Repointing an upstream someone chose would silently change what `just - # check` scopes against, so only three cases write it: no upstream, an - # upstream `_base` discards anyway (the branch's own remote copy, which - # `git push -u` leaves behind and which says nothing about what the branch - # merges into), and a base the caller named on the command line. - upstream=$(git rev-parse --abbrev-ref '@{upstream}' 2> /dev/null || true) - # Two things stop the write, and they fail identically: a detached HEAD has - # no branch to hang an upstream on, and the config it lands in may be - # read-only. Skipping either silently would report a setup that recorded - # the caller's base while `just check` still scoped against origin/main. - blocker="" - if [[ -z "$branch" ]]; then - blocker="HEAD is detached" - elif [[ "$config" != write ]]; then - blocker="$common_dir/config is $config" - fi - if [[ -z "$upstream" ]] || [[ "$upstream" == */"$branch" ]] || [[ -n "$BASE" ]]; then - if [[ -z "$blocker" ]]; then - git branch --set-upstream-to "$base" "$branch" - elif [[ "$base" == origin/main ]]; then - # Nothing is lost: with no upstream `_base` falls back to - # origin/main, which is what this would have written. - echo "warning: cannot record the upstream; $blocker" >&2 - else - # The upstream is the only place this choice survives, so a setup - # that could not write it did not do what it was asked. - echo "error: cannot set the upstream to $base; $blocker" >&2 - echo " the branch would keep scoping against origin/main" >&2 - exit 1 - fi - fi - # Resolved, written, then renamed into place. A redirect straight into the - # stamp truncates it before git runs, so a failure there would leave an - # empty file that reads back as a recorded base that never existed. Each - # setup needs its own temporary file so concurrent runs cannot rename or - # overwrite each other's in-progress stamp. - if [[ "$worktree_meta" == write ]]; then - stamp_tmp=$(mktemp "$git_dir/.moq-base.XXXXXXXX") - if ! git rev-parse "$base" > "$stamp_tmp"; then - rm -f "$stamp_tmp" - exit 1 - fi - mv "$stamp_tmp" "$stamp" - fi - fi - - if ! git rev-parse --verify --quiet "$base^{commit}" > /dev/null; then - echo "base: $base (NOT FETCHED; run 'just worktree setup')" - exit 0 - fi - - head=$(git rev-parse "$base") - echo "base: $base $(git rev-parse --short "$base")" - echo "upstream: $(git rev-parse --abbrev-ref '@{upstream}' 2> /dev/null || echo '(unset)')" - echo "behind: $(git rev-list --count "HEAD..$base") commit(s)" - - recorded="" - [[ -f "$stamp" ]] && recorded=$(cat "$stamp") - - # A stamp that no longer names a commit is worse than none: reporting it would - # abort here on the `rev-parse --short` rather than say what to do about it. - # An interrupted setup, or a base garbage-collected out of the repository. - if [[ -z "$recorded" ]]; then - echo "recorded: (none; run 'just worktree setup')" - elif ! git rev-parse --verify --quiet "$recorded^{commit}" > /dev/null; then - echo "recorded: $recorded (UNKNOWN COMMIT; run 'just worktree setup')" - elif [[ "$recorded" == "$head" ]]; then - echo "recorded: $(git rev-parse --short "$recorded") (current)" - else - echo "recorded: $(git rev-parse --short "$recorded") (STALE; $base has moved since setup)" - fi +# Compare a shared Tokio runtime with independent workers: `just bench-runtime 5 16`. +bench-runtime $ROUNDS="3" $WORKERS="": + MOQ_BENCH_RUNTIME_ROUNDS="$ROUNDS" MOQ_BENCH_RUNTIME_WORKERS="$WORKERS" bench/run.sh --runtime # Install repo-wide tooling. Per-language deps install on first check. install: bun install - cargo install --locked cargo-shear cargo-sort cargo-upgrades cargo-edit cargo-semver-checks release-plz - -# Resolve BASE: arg > $GITHUB_BASE_REF > upstream > origin/main. A branch's -# upstream is the branch it merges into, which is the base a `dev`-targeted -# branch needs. `git push -u` repoints upstream at the branch's own remote copy, -# which would diff HEAD against itself, so ignore that case (see AGENTS.md). -# GITHUB_BASE_REF outranks the upstream because a PR checkout has no upstream -# configured, and the branch being merged into is exactly the base GitHub is -# asking about. -# -# Shared by `_changed` and `worktree`, so a checkout's scope and its reported -# base can never disagree. - -# Print the ref this branch is based on. -[private] -_base $BASE="": - #!/usr/bin/env bash - set -euo pipefail - - base="$BASE" - if [[ -z "$base" && -n "${GITHUB_BASE_REF:-}" ]]; then - base="origin/${GITHUB_BASE_REF}" - fi - if [[ -z "$base" ]]; then - base=$(git rev-parse --abbrev-ref '@{upstream}' 2>/dev/null || true) - if [[ -z "$base" || "$base" == */"$(git branch --show-current)" ]]; then - base="origin/main" - fi - fi - printf '%s\n' "$base" - -# Reports the base it picked on stderr, so a surprising scope is traceable. -# -# LIMIT is the byte budget for the printed list, and exists as a parameter so -# `_changed-test` can force the oversized path without a synthetic 30k-file diff. - -# Print the files this branch changed relative to BASE, one per line, or `ALL`. -[private] -_changed $BASE $LIMIT=changed_max: - #!/usr/bin/env bash - set -euo pipefail - - base=$(just _base "$BASE") - - merge_base=$(git merge-base "$base" HEAD) || { - echo "error: cannot resolve merge-base against $base (is full history fetched?)" >&2 - exit 1 - } - echo "base: $base" >&2 - - # Untracked files count too: a brand new crate or module is the whole change. - files=$({ - git diff --name-only "$merge_base" - git ls-files --others --exclude-standard - } | sort -u) - - # Assigned rather than tested inline, so a failing `_changed-cap` aborts here - # under `set -e`. Inside `[[ ]]` its exit status is discarded, and the caller - # would then scope to a list that never got budgeted -- straight back into the - # E2BIG this exists to prevent. - cap=$(printf '%s' "$files" | just _changed-cap "$LIMIT") - if [[ "$cap" == ALL ]]; then - echo ALL - exit 0 - fi - - # Guarded because a bare printf of an empty list prints a newline, and the - # callers test the result for emptiness to decide whether anything changed. - if [[ -n "$files" ]]; then - printf '%s\n' "$files" - fi - -# Every hop of the dispatch takes the changed-file list as one argument, and -# just exports recipe parameters into the child's environment, so the whole list -# has to fit in a single execve string. Linux caps one string at MAX_ARG_STRLEN -# (32 pages, 131072 bytes) however large ARG_MAX is, so past that each hop dies -# with E2BIG, which just reports as exit code 126 and no mention of the diff. A -# diff that large selects most of the workspace anyway, so the callers widen to -# the unscoped suite, which passes no list at all. -# -# Split out from `_changed` so `_changed-test` can drive the decision with a -# synthetic list, rather than needing the working tree to hold a diff of a -# particular size. -# -# The list arrives on stdin, which is both the only channel that can carry an -# oversized one and the only way to measure it honestly: `${#var}` counts -# CHARACTERS under a UTF-8 locale while execve counts BYTES, so a path set of -# 3-byte characters would read as a third of its real size and sail past a -# budget it actually blows. - -# Print `ALL` when the changed-file list on stdin is too long for one argument. -[private] -_changed-cap $LIMIT=changed_max: - #!/usr/bin/env bash - set -euo pipefail - - [[ "$LIMIT" =~ ^[0-9]+$ ]] || { - echo "changed: not a byte count: $LIMIT" >&2 - exit 2 - } - - bytes=$(wc -c | tr -d '[:space:]') - if ((bytes > LIMIT)); then - echo "changed: $bytes bytes of paths exceeds the $LIMIT budget; selecting everything." >&2 - echo ALL - fi - -# Guards the thing that fails LOUDLY but unhelpfully: past the budget every -# `just` hop dies with "Argument list too long" and exit 126, naming neither the -# diff nor the recipe that could not receive it. Both halves matter -- a budget -# that never trips scopes nothing, and one above what execve accepts still dies. - -# Check that an oversized diff widens to `ALL`, and that the budget fits in argv. -[private] -_changed-test $LIMIT=changed_max: - #!/usr/bin/env bash - set -euo pipefail - - fail() { echo "changed: _changed-test: $1" >&2; exit 1; } - - # Synthetic sizes rather than whatever the working tree happens to hold: a - # clean checkout has no diff at all, and `check --all` runs there (cache.yml - # warms the cache from `main`), so a test keyed on the real list would take - # down the one job allowed to write the shared Rust cache. - [[ "$(printf 'aaaa' | just _changed-cap 3)" == ALL ]] || fail "over budget must print ALL" - [[ -z "$(printf 'aaa' | just _changed-cap 3)" ]] || fail "at budget must print nothing" - [[ -z "$(printf '' | just _changed-cap 3)" ]] || fail "an empty diff must print nothing" - - # The smallest nonempty list there is, against the only budget below it. - [[ "$(printf 'x' | just _changed-cap 0)" == ALL ]] || fail "a 1-byte list must exceed a 0 budget" - - # execve counts bytes, so the budget has to as well. Spelled as raw bytes - # rather than as characters: this is one CJK character, 3 bytes wide, which - # `${#var}` would count as 1 under a UTF-8 locale and let past a 2-byte - # budget it actually blows. - [[ "$(printf '\xe6\x97\xa5' | just _changed-cap 2)" == ALL ]] \ - || fail "the budget must count bytes, not characters" - - # A byte count is the whole input, so anything else is a caller bug, not a - # reason to silently scope to nothing. - ! printf '' | just _changed-cap not-a-number 2> /dev/null || fail "a bad budget must be rejected" - - # ...and that rejection has to reach the caller. A swallowed one would hand - # back an unbudgeted list, which is the failure this whole recipe prevents. - ! just _changed "" not-a-number 2> /dev/null || fail "a rejected budget must fail _changed" - - # Linux caps a single argv/env string at MAX_ARG_STRLEN (32 pages), whatever - # ARG_MAX says, and the list travels as one string. Asserted rather than - # probed because this repo's CI is the Linux host and a dev box may be laxer. - ((LIMIT <= 131072)) || fail "budget $LIMIT exceeds Linux MAX_ARG_STRLEN" - - # The budget still has to survive the hop it was sized for, which the checks - # above cannot show: they never pass a list that big to anything. - payload=$(head -c "$LIMIT" /dev/zero | tr '\0' x) - [[ "$(just _echo "$payload" | wc -c)" -eq $((LIMIT + 1)) ]] \ - || fail "a $LIMIT-byte list does not survive an argv hop" - - # End to end, but only when there is a diff to be oversized: see above. The - # budget is zero rather than one because the real list is whatever the - # checkout holds, and a single one-character root path is a one-byte list - # that a one-byte budget does not exceed. Zero is below every nonempty list. - if [[ -n "$(just _changed "" 100000000)" ]]; then - [[ "$(just _changed "" 0)" == ALL ]] || fail "a diff over budget must print ALL" - fi - - echo "changed: budget ok" - -# Print an argument back, to measure what survives a `just` invocation. -[private] -_echo $VALUE: - @printf '%s\n' "$VALUE" - -# Tools every scope guards with `command -v`, so an incomplete local toolchain -# checks less instead of failing. That trade is wrong in CI, where a skip is -# indistinguishable from a pass, so CI exports MOQ_STRICT=1 and this turns the -# required set into a precondition. Checked up front, and as one list, so a -# missing tool is reported before a long compile rather than after it. -# -# Required per scope, mirroring what `check` actually dispatches for a given -# diff: demanding gradle on a docs-only PR would fail a run that was never going -# to invoke it. Takes the same file list as the dispatch, or `ALL` to require -# everything (`check --all`). -# -# 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] -_tools $FILES="": - #!/usr/bin/env bash - set -euo pipefail - [[ -n "${MOQ_STRICT:-}" ]] || exit 0 - - scoped() { [[ "$FILES" == ALL ]] || grep -qE "$1" <<< "$FILES"; } - - # `_check-common` runs on every invocation, so its tools are unconditional. - tools=(actionlint bun jq nix nixfmt shellcheck shfmt taplo python3 nfpm dpkg-deb envsubst rpm) - scoped '^(drafts/|doc/\.vitepress/drafts\.ts$)' && tools+=(kramdown-rfc xml2rfc) - scoped '^(bench/|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) - scoped '^(quest/|flake\.lock$)' && tools+=(quest) - scoped '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' && tools+=(uv) - scoped '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' && 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. rsync because the - # publish scripts stage the mirror tree with it, so the publisher test skips - # without it, and a skip that keeps `just check` green is what MOQ_STRICT is - # here to prevent. - scoped '^(go/|rs/moq-ffi/)' && tools+=(go uniffi-bindgen-go cargo rsync) - scoped '^(dart/|rs/moq-ffi/)' && tools+=(cargo dart uniffi_bindgen_dart) - # Two obs recipes with two dispatch scopes, so two lines: over-requiring - # would fail a diff that never runs the recipe. `just obs compile` needs - # cargo to regenerate moq.h and pkg-config to locate Qt6 and ffmpeg. Every - # platform: the plugin type-checks against headers, and the dev shell ships - # those even on Darwin, where obs-studio can't build. - scoped '^(cpp/obs/|rs/moq-c/|flake\.nix$)' && tools+=(pkg-config cargo) - # `just obs check` lints with clang-format and gersemi, validates the CMake - # release configuration, and compares the three OBS pins, one of which moves - # on a flake.lock bump alone. - scoped '^(cpp/obs/|flake\.(nix|lock)$)' && tools+=(clang-format gersemi cmake) - - # Scopes overlap (rs/moq-ffi/ is in five 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") - done - if ((${#missing[@]})); then - echo "error: MOQ_STRICT is set but these tools are missing: ${missing[*]}" >&2 - echo " run inside 'nix develop', or unset MOQ_STRICT to skip what isn't installed" >&2 - exit 1 - fi + cargo install --locked cargo-shear cargo-sort cargo-semver-checks release-plz # Lints, compiles, and tests only the packages the branch changed plus -# everything depending on them, so several worktrees can build at once. Rust -# compiles once: the test build doubles as the clippy gate (see `rs check-test`). -# `check --all` is the unscoped suite. +# everything depending on them; `check --all` is the unscoped suite. BASE +# defaults to the branch's upstream. Rust compiles once: its test build doubles +# as the clippy gate (see `rs check-test`). # Lint, compile, and test what the branch changed since BASE, plus its dependents. check $BASE="": - just _check "$BASE" true + sh/dispatch.sh check "$BASE" -# CI splits `check` into two parallel jobs, since one runner doing both takes -# about the sum of their times. Both share `check`'s scoping (and CI adds -# MOQ_STRICT=1), so there is no second, drifting definition of "checked". +# CI runs `check` as two parallel jobs, since one runner doing both takes about +# the sum of their times. Same dispatch, with MOQ_STRICT=1. -# Run half of `check` for CI: `check` lints and compiles, `test` runs the tests. +# Run half of `check` for CI: JOB `check` lints and compiles, `test` runs the tests. ci $JOB $BASE="": - #!/usr/bin/env bash - set -euo pipefail - case "$JOB" in - check) just _check "$BASE" false ;; - test) just _test "$BASE" ;; - *) - echo "ci: unknown job '$JOB', want check or test" >&2 - exit 2 - ;; - esac - -# TEST=false is `ci check`: Rust lints through `cargo clippy`, which only -# emits metadata and so finishes sooner than the test build it stands in for. - -# Lint and compile what the branch changed since BASE, and test it when TEST=true. -[private] -_check $BASE $TEST: - #!/usr/bin/env bash - set -euo pipefail - - if [[ "$BASE" == --all ]]; then - files=ALL - else - files=$(just _changed "$BASE") - fi - - # `_changed` says ALL when the list outgrew what argv can carry. The unscoped - # suite is the path that passes no list at all, so it is the one that works. - # The dispatch below lives in this file, which matches no - # language scope, so a PR that rewrites how CI dispatches would otherwise - # validate none of it. Widen to the unscoped suite instead. - if [[ "$files" != ALL ]] && grep -qE '^justfile$' <<< "$files"; then - echo "check: root orchestration changed; checking everything." >&2 - files=ALL - fi - - just _tools "$files" - - if [[ "$files" == ALL ]]; then - just js check - just drafts check - if [[ "$TEST" == true ]]; then - just rs check-test --workspace --exclude moq-net-fuzz - just rs play - else - just rs check --workspace --exclude moq-net-fuzz - fi - just rs tokio-features - just rs media-features - just --justfile bench/justfile check - quest check - just test drill-sensitivity --apply-only - # Not covered by the line above: moq-wasm only exists on the wasm32 target. - just rs wasm - just py check - just kt check - just swift check - just go check - just dart check - just obs check - just obs compile - just _flake - elif [[ -n "$files" ]]; then - just js check "$files" - just rs check-changed "$files" "$TEST" - if echo "$files" | grep -q '^bench/'; then - just --justfile bench/justfile check - fi - # Draft sources render into the doc site and carry their own kramdown-rfc - # plus vector checks; a drafts-only diff would otherwise skip both. - if echo "$files" | grep -qE '^(drafts/|doc/\.vitepress/drafts\.ts$)'; then - just drafts check - fi - # Quest documents form one graph, so validate the whole living tree when - # either a quest or the flake-pinned validator changes. - if echo "$files" | grep -qE '^(quest/|flake\.lock$)'; then - quest check - fi - # The drill mutations patch Rust source, so a Rust change can move the - # code they target. Only nightly runs the drills against them; this - # catches a stale patch in the PR that moved its code. - if echo "$files" | grep -qE '^(rs/|test/drill/)'; then - just test drill-sensitivity --apply-only - fi - just py check "$files" - just kt check "$files" - just swift check "$files" - just go check "$files" - just dart check "$files" - # Type-checking the plugin and its unit tests needs only headers, so it - # runs here rather than waiting for obs.yml to link them on Linux. moq-c - # is in scope because the plugin calls through its generated C header, and - # the tests restate those entry points as stubs, so an ABI change breaks - # both. flake.nix because it owns the libobs headers this compiles - # against -- obs.yml links against nixpkgs' obs-studio instead, so nothing - # else would notice that package going bad. - if echo "$files" | grep -qE '^(cpp/obs/|rs/moq-c/|flake\.nix$)'; then - just obs compile - fi - # flake.nix is in scope because `just obs check` is what compares the OBS - # version pinned there against buildspec.json, and either side can move. - # flake.lock too, because the third OBS the guard compares is nixpkgs' - # obs-studio, the one `just obs ci` links: it moves on a lock bump alone, - # and that bump is the change that opens the gap. - if echo "$files" | grep -qE '^(cpp/obs/|flake\.(nix|lock)$)'; then - just obs check - fi - # Validates flake eval + dev shell build; it no longer compiles the - # workspace, so it's cheap. Gated anyway: a pure doc/JS PR can't - # affect flake eval. - if echo "$files" | grep -qE '(^rs/|^Cargo\.(toml|lock)$|^flake\.lock$|\.nix$)'; then - just _flake - fi - else - echo "check: nothing changed." - fi - - # Rust already ran its tests above, from the build that linted it. The kt, - # swift, go, and dart checks always run theirs, so only js and py remain. - # An empty list means "everything" to the per-language recipes. - if [[ "$TEST" == true && -n "$files" ]]; then - scope=$files - [[ "$scope" == ALL ]] && scope= - just js test "$scope" - just py test "$scope" - fi - - just _check-common - -# `ci test`'s half of `_check`: the same scoping, but only the languages whose -# tests are separate from their check (js, rs, py). - -# Run unit tests for what the branch changed since BASE, plus its dependents. -[private] -_test $BASE: - #!/usr/bin/env bash - set -euo pipefail - - if [[ "$BASE" == --all ]]; then - files=ALL - else - files=$(just _changed "$BASE") - fi - - # Mirrors `_check`: widen to everything when the list outgrew argv or the - # dispatch itself changed. - if [[ "$files" != ALL ]] && grep -qE '^justfile$' <<< "$files"; then - echo "test: root orchestration changed; testing everything." >&2 - files=ALL - fi - - just _tools "$files" - - if [[ "$files" == ALL ]]; then - just js test - just rs test --workspace --exclude moq-net-fuzz - just rs play - just py test - elif [[ -n "$files" ]]; then - just js test "$files" - just rs test-changed "$files" - just py test "$files" - else - echo "test: nothing changed." - fi - -# Skips when nix is absent: the flake is not a precondition for working on the -# repo, and `_tools` already makes it required under MOQ_STRICT. - -# Validate flake evaluation and the dev shell build. -[private] -_flake: - @if command -v nix >/dev/null 2>&1; then nix flake check; fi - -# Repository-wide non-compiling checks shared by scoped and unscoped `check`. -# Optional shell, workflow, TOML, Nix, and justfile lints skip if missing. -# -# `bun install` because remark-cli lives in node_modules and `just js check` is -# where it would otherwise be installed, which a Rust-only diff skips. - -# Run shell checks or formatting over tracked files that exist in the worktree. -[private] -_shell $ACTION: - #!/usr/bin/env bash - set -euo pipefail - - if ! command -v shfmt >/dev/null 2>&1; then - exit 0 - fi - if [[ "$ACTION" == "check" ]] && ! command -v shellcheck >/dev/null 2>&1; then - exit 0 - fi - - scripts_file=$(mktemp) - trap 'rm -f "$scripts_file"' EXIT - shfmt -f=0 . > "$scripts_file" - - scripts=() - while IFS= read -r -d '' file; do - if git --literal-pathspecs ls-files --error-unmatch -- "$file" >/dev/null 2>&1; then - scripts+=("$file") - fi - done < "$scripts_file" - ((${#scripts[@]})) || exit 0 - - case "$ACTION" in - check) - shfmt --diff "${scripts[@]}" - shellcheck "${scripts[@]}" - ;; - fix) - shfmt --write "${scripts[@]}" - ;; - *) - echo "invalid shell action: $ACTION" >&2 - exit 2 - ;; - esac - -# remark-cli has no `--check`. `--frail` raises the exit code on lint messages, -# and only `--output` formats, so a file that is merely misformatted passes both -# ways. Format a scratch mirror and diff that, so the check stays read-only -# while `fix` still writes in place. - -# Run Markdown lints over the worktree, either checking formatting or applying it. -[private] -_markdown $ACTION: - #!/usr/bin/env bash - set -euo pipefail - - case "$ACTION" in - check) ;; - fix) - bun remark . --quiet --output - exit 0 - ;; - *) - echo "invalid markdown action: $ACTION" >&2 - exit 2 - ;; - esac - - mirror=$(mktemp -d) - trap 'rm -rf "$mirror"' EXIT - - extension_list=$(bun -e \ - 'import extensions from "markdown-extensions"; console.log(extensions.join("\n"))') - patterns=() - while IFS= read -r extension; do - [[ -n "$extension" ]] && patterns+=("*.$extension") - done <<< "$extension_list" - ((${#patterns[@]})) || { - echo "error: remark reported no Markdown extensions" >&2 - exit 1 - } - - # Untracked files are in scope so a new doc is linted before it is staged; - # --exclude-standard keeps build output out. - files=() - while IFS= read -r -d '' file; do - [[ -f "$file" ]] || continue - files+=("$file") - mkdir -p "$mirror/$(dirname "$file")" - cp "$file" "$mirror/$file" - done < <(git ls-files -z --cached --others --exclude-standard -- "${patterns[@]}") - ((${#files[@]})) || exit 0 - - # The config rides along so every .remarkignore pattern resolves against the - # mirror root exactly as it does here, and node_modules is where the plugins - # named by .remarkrc.mjs come from. - cp .remarkrc.mjs .remarkignore "$mirror/" - ln -s "$PWD/node_modules" "$mirror/node_modules" - - status=0 - (cd "$mirror" && bun remark . --quiet --frail --output) || status=$? - - stale=() - for file in "${files[@]}"; do - cmp -s "$file" "$mirror/$file" || stale+=("$file") - done - - if ((${#stale[@]})); then - echo "error: these files are not formatted, run 'just fix':" >&2 - printf ' %s\n' "${stale[@]}" >&2 - status=1 - fi - - exit "$status" - -# Check Markdown formatting detection without touching the caller's worktree. -[private] -_markdown-test: - #!/usr/bin/env bash - set -euo pipefail - - fail() { echo "markdown: _markdown-test: $1" >&2; exit 1; } - - repo=$PWD - fixture=$(mktemp -d) - trap 'rm -rf "$fixture"' EXIT - - git -C "$fixture" init --quiet - cp .remarkrc.mjs .remarkignore "$fixture/" - ln -s "$repo/node_modules" "$fixture/node_modules" - for file in dirty.md dirty.markdown; do - printf '# dirty_heading\n' > "$fixture/$file" - git -C "$fixture" add "$file" - done - - original='# dirty_heading' - if just --justfile "$repo/justfile" --working-directory "$fixture" \ - _markdown check > "$fixture/check.log" 2>&1; then - fail "formatter-only drift must fail the check" - fi - for file in dirty.md dirty.markdown; do - [[ "$(<"$fixture/$file")" == "$original" ]] \ - || fail "the check modified $file" - grep -q "$file" "$fixture/check.log" \ - || fail "the check did not name $file" - done - - just --justfile "$repo/justfile" --working-directory "$fixture" _markdown fix - for file in dirty.md dirty.markdown; do - [[ "$(<"$fixture/$file")" == '# dirty\_heading' ]] \ - || fail "the fix did not format $file" - done - just --justfile "$repo/justfile" --working-directory "$fixture" _markdown check - - echo "markdown: check/fix regression ok" - -# Repository-wide lints, shared by scoped and unscoped `check`. -[private] -_check-common: - just _changed-test - bun install --frozen-lockfile - just _markdown-test - just _markdown check - just _shell check - @if command -v taplo >/dev/null 2>&1; then RUST_LOG=error taplo format --check; fi - @if command -v nixfmt >/dev/null 2>&1; then nixfmt --check $(find . -name '*.nix' -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); fi - @for f in $(find . -name justfile -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); do just --fmt --check --justfile "$f"; done - just gh check - -# Scoped exactly like `check`, because `clippy --fix` compiles what it fixes. -# Pass `--all` for the unscoped version. + sh/dispatch.sh "ci-$JOB" "$BASE" # Auto-fix lint and formatting for what the branch changed since BASE. fix $BASE="": - #!/usr/bin/env bash - set -euo pipefail - - if [[ "$BASE" == --all ]]; then - files=ALL - else - files=$(just _changed "$BASE") - fi - - # Mirrors `check`: too long for argv means fix everything instead. - if [[ "$files" == ALL ]]; then - just js fix - just rs fix --workspace --exclude moq-net-fuzz - just py fix - just dart fix - just obs fix - elif [[ -n "$files" ]]; then - just js fix "$files" - just rs fix-changed "$files" - just py fix "$files" - just dart fix "$files" - if echo "$files" | grep -q '^cpp/obs/'; then - just obs fix - fi - else - echo "fix: nothing changed." - fi - - just _fix-common - -# Optional tools skip if missing locally. `bun install` for the same reason as -# `_check-common`. - -# Repository-wide fixes, shared by scoped and unscoped `fix`. -[private] -_fix-common: - bun install - just _markdown fix - just _shell fix - @if command -v taplo >/dev/null 2>&1; then RUST_LOG=error taplo format; fi - @if command -v nixfmt >/dev/null 2>&1; then nixfmt $(find . -name '*.nix' -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); fi - @for f in $(find . -name justfile -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); do just --fmt --justfile "$f"; done + sh/dispatch.sh fix "$BASE" # Build the packages. build: just js build just rs build - if command -v uv &> /dev/null; then just py build; fi - if command -v wasm-bindgen &> /dev/null; then just wasm; fi - -# Build browser/WASM bindings into @moq/wasm using the pinned wasm-bindgen toolchain. -wasm: - cargo build --locked -p moq-wasm --target wasm32-unknown-unknown --profile wasm-release - wasm-bindgen --target web --out-name moq \ - --out-dir js/wasm/dist "${CARGO_TARGET_DIR:-target}/wasm32-unknown-unknown/wasm-release/moq_wasm.wasm" - -# Only this checkout by default. Agent worktrees each carry their own artifacts -# now that the shared target dir is gone, and another agent is usually building -# in one right now: `cargo clean` under a running build fails it, and there is no -# way to tell a finished worktree from a busy one from out here. `just clean all` -# is the explicit opt-in for a machine the caller knows is idle. -# -# Source is never touched either way, dirty or untracked: this deletes build -# output, not work. Nothing here reaches a machine-wide store -- no Nix garbage -# collection, no cargo/bun/uv home cache -- because those are shared with every -# other checkout and rebuilding them costs far more than the space they hold. + just py build + just js wasm # Delete this checkout's build artifacts and caches; `all` includes agent worktrees. clean SCOPE="here": - #!/usr/bin/env bash - set -euo pipefail - - case "{{ SCOPE }}" in - here | all) ;; - *) - echo "usage: just clean [here|all]" >&2 - exit 2 - ;; - esac - - just rs clean - just js clean - just py clean - just kt clean - just swift clean - just go clean - just dart clean - - # Caches not owned by any one language: nix build result, direnv, wrangler. - rm -rf result .direnv - find . -name .claude -prune -o -type d -name .wrangler -prune -exec rm -rf {} + - - # Worktrees don't nest, so this recurses exactly one level. Tolerate stale - # worktrees on branches that predate this recipe. - if [[ "{{ SCOPE }}" == all ]]; then - for wt in .claude/worktrees/*/; do - [ -f "${wt}justfile" ] || continue - echo "==> cleaning ${wt}" - (cd "$wt" && just clean) || echo " (skipped: just clean failed in ${wt})" - done - fi - -# Upgrade any tooling -update: - just js update - just rs update - nix flake update - -# Serve the documentation locally. -doc: - cd doc && bun run dev + sh/clean.sh {{ SCOPE }} diff --git a/kt/.gitignore b/kt/.gitignore index 25c4ac20b35..ae71352dba6 100644 --- a/kt/.gitignore +++ b/kt/.gitignore @@ -4,7 +4,7 @@ build/ local.properties .kotlin/ -# Generated by kt/scripts/{check,package}.sh. Never check these in. +# Generated by sh/kt/{check,package}.sh. Never check these in. moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/ moq-ffi/src/jvmMain/resources/ moq-ffi/src/androidMain/jniLibs/ diff --git a/kt/README.md b/kt/README.md index af610b0b084..c4187827fe9 100644 --- a/kt/README.md +++ b/kt/README.md @@ -54,7 +54,7 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **Fetched media**: `fetchMediaGroup(...).frames()` streams the decoded frames of one retained group, then completes. - **Duration extensions** (`Durations.kt`): the FFI carries microseconds as integers, so `stats.rtt`, `backoff.initial`, `frame.timestamp`, and their siblings read back as a `kotlin.time.Duration`. - **`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. +- **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 or moq-transport, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. ## Versioning @@ -91,7 +91,6 @@ kt/ src/ jvmAndAndroidMain/kotlin/dev/moq/ Wrapper sources (Moq, Server, Aliases, Flows, Durations, Errors) jvmAndAndroidTest/ Facade smoke test - scripts/ check.sh, package.sh ``` The native/UniFFI layer stays in a single `dev.moq:moq-ffi` artifact because uniffi-linked libraries can't be split across separately packaged artifacts (the Python `moq-rs` wheel is one umbrella for the same reason). That constraint is about the *native* layer; the pure-Kotlin `dev.moq:moq` wrapper sits cleanly on top of it as its own artifact because it ships no native code. diff --git a/kt/justfile b/kt/justfile index 8acb7ebe9b6..2a3994710a6 100644 --- a/kt/justfile +++ b/kt/justfile @@ -9,42 +9,23 @@ set working-directory := '.' default: just check -# Missing tools are errors so wrapper drift cannot slip past a green check. -# # This runs the tests too, so there is no separate `just kt test`: the script -# builds, generates, and tests as one gradle invocation. Takes an optional -# newline-separated list of changed files and skips when none are Kotlin-scoped; -# `just kt check` (no FILES) always runs. +# builds, generates, and tests as one gradle invocation. # Build moq-ffi, regenerate the bindings, and run :moq-ffi:jvmTest + :moq:jvmTest. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' <<< "$FILES"; then - echo "kt: no Kotlin changes; skipping." - exit 0 - fi - bash scripts/check.sh +check: + bash ../sh/kt/check.sh # Regenerate the checked-in uniffi bindings and host native library without # compiling or testing. For environments that intentionally lack Gradle. generate: - bash scripts/generate.sh + bash ../sh/kt/generate.sh -# Assemble the KMP module from per-target moq-ffi binaries + bindings. -# Used by .github/workflows/release-kt-ffi.yml; see kt/README.md for the +# Runs in the caller's directory, so a relative `--lib-dir` or `--output` means +# what it would to the script itself. See kt/README.md for the --lib-dir layout. -# expected --lib-dir layout. +# Assemble the KMP module from per-target moq-ffi binaries and bindings. +[no-cd] +[positional-arguments] package *args: - bash scripts/package.sh {{ args }} - -# Remove gradle output plus the moq-ffi bindings and native libs that -# scripts/check.sh generates into the source tree (see kt/.gitignore). -clean: - #!/usr/bin/env bash - set -euo pipefail - find . -name .claude -prune -o -type d \( -name build -o -name .gradle -o -name .kotlin \) -prune -exec rm -rf {} + - rm -rf local.properties \ - moq/src/jvmAndAndroidMain/kotlin/uniffi \ - moq/src/jvmMain/resources \ - moq/src/androidMain/jniLibs + {{ quote(justfile_directory() / "sh/kt/package.sh") }} "$@" diff --git a/kt/moq-ffi/build.gradle.kts b/kt/moq-ffi/build.gradle.kts index c5e76a9f0bd..4aa387e97fe 100644 --- a/kt/moq-ffi/build.gradle.kts +++ b/kt/moq-ffi/build.gradle.kts @@ -11,7 +11,7 @@ // ├─ jvmMain JVM-specific: native libs as JAR resources // └─ androidMain Android-specific: native libs in jniLibs // -// Native libraries + bindings are populated by `kt/scripts/package.sh`: +// Native libraries + bindings are populated by `sh/kt/package.sh`: // src/jvmMain/resources/-/ (JNA classpath layout) // src/androidMain/jniLibs//libmoq_ffi.so (Android packaging layout) // src/jvmAndAndroidMain/kotlin/uniffi/moq/moq.kt (uniffi-bindgen output) diff --git a/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt b/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt index 08603e68bc2..ebc481b3dd1 100644 --- a/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt +++ b/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt @@ -6,6 +6,7 @@ import uniffi.moq.MoqException import uniffi.moq.MoqOriginConfig import uniffi.moq.MoqOriginProducer import kotlin.test.Test +import kotlin.test.assertEquals import kotlin.test.assertFailsWith /** @@ -24,6 +25,12 @@ class BindingsSmokeTest { } } + @Test + fun `an exception prints the Rust error message`() { + assertEquals("closed", MoqException.Closed().toString()) + assertEquals("transport: reset", MoqException.Transport("reset").toString()) + } + @Test fun `origin producer constructs and consumes`() = runTest { MoqOriginProducer(MoqOriginConfig()).use { origin -> diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 11154a920c9..3d237b19e42 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -149,7 +149,7 @@ typealias FetchGroupOptions = uniffi.moq.MoqFetchGroupOptions typealias TrackInfo = uniffi.moq.MoqTrackInfo /** One audio frame: PCM payload bytes plus a presentation timestamp. */ typealias AudioFrame = uniffi.moq.MoqAudioFrame -/** Selects the audio encoder codec. Build one with `AudioCodec.opus()`. */ +/** Selects the audio encoder codec. Build one with `AudioCodec.opus()` or `AudioCodec.aac()`. */ typealias AudioCodec = uniffi.moq.MoqAudioCodec /** A raw PCM sample format, mirroring WebCodecs `AudioData.format`. */ typealias AudioSampleFormat = uniffi.moq.MoqAudioSampleFormat diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt index 07e047ee815..9f15448a620 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt @@ -1,4 +1,4 @@ -// The inputs the documentation samples leave to the reader. kt/scripts/check.sh +// The inputs the documentation samples leave to the reader. sh/kt/check.sh // compiles every Kotlin sample from the docs beside this file, so a sample that // names a missing symbol or the wrong arity fails the check. Never executed. package dev.moq.docs diff --git a/nix/overlay.nix b/nix/overlay.nix index 234186c6872..e614c462a89 100644 --- a/nix/overlay.nix +++ b/nix/overlay.nix @@ -49,7 +49,16 @@ let ); moqRelayArgs = crateInfo ../rs/moq-relay/Cargo.toml // { - src = cleanCargoSource; + # A config test `include_str!`s the packaged systemd unit so its ExecStart + # keeps parsing, and the default filter drops non-Cargo files. + src = final.lib.cleanSourceWith { + src = ../.; + name = "source"; + filter = + path: type: + (final.lib.hasSuffix "/packaging/moq-relay/moq-relay.service" path) + || (filterCargoSources path type); + }; cargoExtraArgs = "-p moq-relay --features jemalloc"; # Enable frame pointers for profiling support (negligible overhead on x86_64). # This also ensures the CDN build matches what Cachix caches. diff --git a/packaging/moq-relay/moq-relay.service b/packaging/moq-relay/moq-relay.service index 8cbe5ed7b63..8af96bdf591 100644 --- a/packaging/moq-relay/moq-relay.service +++ b/packaging/moq-relay/moq-relay.service @@ -6,7 +6,7 @@ Wants=network-online.target [Service] Type=notify -ExecStart=/usr/bin/moq-relay --file /etc/moq-relay/relay.toml +ExecStart=/usr/bin/moq-relay /etc/moq-relay/relay.toml # Escalating restart backoff: 5s after the first failure, stepping up to a minute. A relay that # dies on a bad config or an unbindable port would otherwise restart every 5s forever, which buries # the real error under a restart loop and hammers whatever it dials. RestartSteps and diff --git a/py/justfile b/py/justfile index b95d0de995c..da3fc8cfbf7 100644 --- a/py/justfile +++ b/py/justfile @@ -10,16 +10,6 @@ set working-directory := '.' -# Paths a Python check depends on. `rs/moq-ffi` is in scope because maturin -# bundles it into the moq-ffi wheel. `check`, `fix`, and `test` all skip -# themselves when a diff misses this; no FILES at all means force-run. The docs -# are in scope because `check` type-checks their samples against the wrapper. -# -# They also skip when uv is absent, matching the kt/swift/go check scripts: an -# incomplete local toolchain should check less rather than fail. The root -# `_tools` preflight makes uv a hard requirement under MOQ_STRICT. -scope := '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' - default: just check @@ -40,17 +30,7 @@ _develop: # the Docs after the fact. It mocks the native module, so it costs no Rust build. # Lint, type-check, editable-build, check the doc samples, and render the docs. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "py: no Python changes; skipping." - exit 0 - fi - if ! command -v uv >/dev/null 2>&1; then - echo "py: uv not on PATH, skipping" >&2 - exit 0 - fi +check: uv sync --locked --no-install-workspace uv run --no-sync ruff check . uv run --no-sync ruff format --check . @@ -59,50 +39,18 @@ check $FILES="": just samples just docs -# Samples leave their inputs (`payload`, `pts`) to the reader, so they follow -# the declarations in moq-rs/tests/doc_prelude.py. - # Type-check every Python sample in the docs against the installed wrapper. samples: - #!/usr/bin/env bash - set -euo pipefail - out=$(mktemp -d) - trap 'rm -rf "$out"' EXIT - { - cat moq-rs/tests/doc_prelude.py - bash ../doc/lib/samples.sh python ../doc/lib/py/index.md moq-rs/README.md moq-rs/docs/index.md - } > "$out/samples.py" - echo '{"pythonVersion": "3.10"}' > "$out/pyrightconfig.json" - uv run --no-sync pyright --project "$out" "$out/samples.py" + ../sh/py/samples.sh -# Auto-fix lint and formatting issues. Skips on the same terms as `check`. -fix $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "py: no Python changes; skipping." - exit 0 - fi - if ! command -v uv >/dev/null 2>&1; then - echo "py: uv not on PATH, skipping" >&2 - exit 0 - fi +# Auto-fix lint and formatting issues. +fix: uv sync --no-install-workspace uv run --no-sync ruff check --fix . uv run --no-sync ruff format . -# Run the unit tests. Skips on the same terms as `check`. -test $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "py: no Python changes; skipping tests." - exit 0 - fi - if ! command -v uv >/dev/null 2>&1; then - echo "py: uv not on PATH, skipping" >&2 - exit 0 - fi +# Run the unit tests. +test: uv sync --locked --no-install-workspace just _develop uv run --no-sync pytest moq-rs/tests/ moq-ffi/tests/ @@ -114,18 +62,6 @@ build: uv sync --locked --no-install-workspace just _develop -# Remove the virtualenv, release dist, bytecode caches, and the uniffi -# bindings maturin drops in during editable installs. The uv workspace venv - -# lives at the repo root, so reach up for it. -clean: - #!/usr/bin/env bash - set -euo pipefail - rm -rf dist moq-ffi/moq_ffi/_uniffi - rm -rf ../.venv .venv - find . -name .claude -prune -o -type d -name __pycache__ -prune -exec rm -rf {} + - find . -name .claude -prune -o -type f -name '*.pyc' -exec rm -f {} + - # Build the pure-python moq-rs wrapper sdist + wheel into py/dist (for release). # moq-ffi is built separately by maturin (see release-py.yml); the wrapper is diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 3c2a94acfe7..69339fe6ce7 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -156,7 +156,7 @@ client = moq.Client( - `.publish_audio(format, init, *, label=None, track=None) → MediaProducer`. `init` is required: an OpusHead or AudioSpecificConfig resolves the whole rendition. `track` names the track; otherwise a unique name is derived from the format. - `.publish_video(format, init=b"", *, label=None, hint=None, track=None) → MediaProducer`. `init` may be empty for a format that resolves in band; a `VideoHint` pins catalog fields the stream can't reveal (bitrate) or publishes the catalog before the first keyframe. `track` names the track as in `publish_audio`. - `.encode_video(input, output, *, bandwidth=None) → VideoProducer`. Encode raw `VideoFrame`s inside the binding; `.write(frame)` each one. - - `.encode_audio(name, input, output, *, bandwidth=None) → AudioProducer`. Encode raw PCM `AudioFrame`s; the codec is `output.codec`, e.g. `AudioCodec.opus()`, with `output.frame_duration_us` setting the Opus frame length. + - `.encode_audio(name, input, output, *, bandwidth=None) → AudioProducer`. Encode raw PCM `AudioFrame`s; the codec is `output.codec`, e.g. `AudioCodec.opus()` or `AudioCodec.aac()`, with `output.frame_duration_us` setting the Opus frame length (0 takes the codec's own frame, which AAC needs). - `.close()` ends the broadcast for good; a second call is a no-op. - **`BroadcastDynamic`**. Async source of tracks requested by subscribers. - `await .requested_track() → TrackRequest`. Call `.accept()` on it for a `TrackProducer`, or `.abort(code)` to reject. @@ -214,7 +214,7 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting - **`Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`. - **`Frame`**. `.payload: bytes`, `.timestamp_us: int`. The unit of every write and every raw read. - **`MediaFrame`**. `.payload: bytes`, `.timestamp_us: int`, `.keyframe: bool`. Returned by media subscriptions. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. -- **`Datagram`**. `.sequence: int`, `.timestamp_us: int`, `.payload: bytes`. Delivered only on datagram-capable transports and lite-05 or newer moq-lite. +- **`Datagram`**. `.sequence: int`, `.timestamp_us: int`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. - **`Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.description`. - **`Video`**. `.codec`, `.coded: Dimensions`, `.display_aspect`, `.bitrate`, `.stalled`, `.framerate`, `.description`. A true `.stalled` recommends temporarily avoiding the rendition without making it unavailable. - **`Subscription`**. Subscriber delivery preferences: priority, staleness, and optional group range. diff --git a/py/moq-rs/moq/errors.py b/py/moq-rs/moq/errors.py index 73cc48f7367..ecc76a8b928 100644 --- a/py/moq-rs/moq/errors.py +++ b/py/moq-rs/moq/errors.py @@ -3,10 +3,30 @@ from __future__ import annotations from moq_ffi import MoqError, MoqProtocolKind +from moq_ffi._uniffi.moq import ( + _uniffi_rust_call, + _UniffiFfiConverterString, + _UniffiFfiConverterTypeMoqError, + _UniffiLib, +) from .types import ProtocolError +def _display(self: MoqError) -> str: + # moq-ffi exports MoqError's Display, but upstream uniffi's Python template + # renders no traits on errors, so call the exported method directly. + return _UniffiFfiConverterString.lift( + _uniffi_rust_call( + _UniffiLib.uniffi_moq_ffi_fn_method_moqerror_uniffi_trait_display, + _UniffiFfiConverterTypeMoqError.lower(self), + ) + ) + + +MoqError.__str__ = _display + + def is_shutdown(err: BaseException) -> bool: """True for `Cancelled` and `Closed`, which arise from graceful shutdown rather than actual failures. diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 8138961e296..71da932da6c 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -753,8 +753,8 @@ def encode_audio( ) -> AudioProducer: """Publish a raw-audio track with an in-process encoder. - Select the codec with ``moq.AudioCodec.opus()`` (currently the only - constructor), placed in ``output``. + Select the codec with ``moq.AudioCodec.opus()`` or + ``moq.AudioCodec.aac()``, placed in ``output``. Pass ``bandwidth`` to reserve this track's bitrate against the session's allocator so a co-resident video encoder sizes itself against what is left. diff --git a/py/moq-rs/pyproject.toml b/py/moq-rs/pyproject.toml index 71c3999f462..d638ca09cca 100644 --- a/py/moq-rs/pyproject.toml +++ b/py/moq-rs/pyproject.toml @@ -28,11 +28,11 @@ classifiers = [ "Topic :: Multimedia :: Sound/Audio", "Topic :: Multimedia :: Video", ] -# Compatible-release pin: floats to the latest 0.3.x moq-ffi patch without a -# wrapper re-release. A moq-ffi minor bump (0.4) is the only thing that forces -# bumping this constraint. Floor is 0.4.3, the first release with the WebSocket -# fallback setters. -dependencies = ["moq-ffi ~= 0.4.3"] +# Compatible-release pin: floats to the latest 0.4.x moq-ffi patch without a +# wrapper re-release. A moq-ffi minor bump (0.5) is the only thing that forces +# bumping this constraint. Floor is 0.4.9, the first release that exports +# MoqError's Display, which `moq.errors` calls for `str(err)`. +dependencies = ["moq-ffi ~= 0.4.9"] [project.urls] Homepage = "https://github.com/moq-dev/moq" diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 4350d97d2c1..64d4b7b4e93 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -137,6 +137,13 @@ def test_protocol_error_helper_covers_known_app_and_unknown(): assert moq.protocol_error(RuntimeError("nope")) is None +def test_error_str_is_rust_display(): + assert str(moq.Error.Closed()) == "closed" # type: ignore[attr-defined] + assert str(moq.Error.Transport("reset")) == "transport: reset" # type: ignore[attr-defined] + details = moq.ProtocolError(scope=moq.ErrorScope.STREAM, code=468, kind=moq.ProtocolKind.APP, message="gone") + assert str(moq.Error.Protocol(details)) == "gone" # type: ignore[attr-defined] + + def test_publish_media_lifecycle(): broadcast = moq.BroadcastProducer() media = broadcast.publish_audio(moq.AudioFormat.OPUS, opus_head()) diff --git a/quest/README.md b/quest/README.md index dcc3e3b52d5..38d4b4b9bc4 100644 --- a/quest/README.md +++ b/quest/README.md @@ -7,18 +7,24 @@ grouped into milestones ordered by priority. ## Plan -m0 is everything in flight now: announce and wildcard routing, and audio -playout (jitter target, quality harness, A/V clock). m1 is the next wave across reliability, features, -performance, and planning. m2 holds later features, design studies, and -experiments. m3 is deferred: work whose first step is outside this repository. -m4 waits on an upstream release or external dependency to ship. Priority is +m0 is everything in flight now: relay hardening and IETF interop ahead of +Seattle, wildcard routing, and audio playout (jitter target and quality +harness). m1 is the next wave across reliability, features, performance, and +planning. m2 holds later features, design studies, and experiments. m3 is +gated on the outside world: hardware, a partner, a consumer, or a provider's +offer. m4 waits on an upstream release. Priority is separate from branch targeting: published API and wire breaks still land on dev under the repository rules. +A quest waiting on the outside world, in any milestone, states that condition +as a plain-text `Required` bullet, so `quest ready` reports it blocked. +`/quest-audit` re-checks those gates; when one clears, remove the bullet and +move the quest to the milestone its priority belongs in. + ## Required -- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: announce and wildcard routing, and audio playout +- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and IETF interop for Seattle, wildcard routing, and audio playout - [m1: next wave](/quest/m1/README.md) - reliability, capabilities, performance, and the planning that settles their contracts - [m2: later work](/quest/m2/README.md) - deferred features, design studies, and experiments -- [m3: deferred](/quest/m3/README.md) - gated on the outside world: hardware nobody has, a partner, or a provider's offer -- [m4: upstream](/quest/m4/README.md) - waiting on an upstream release or external dependency, re-checked periodically +- [m3: deferred](/quest/m3/README.md) - gated on the outside world: hardware, a partner, a consumer, or a provider's offer +- [m4: upstream](/quest/m4/README.md) - waiting on an upstream release, re-checked periodically diff --git a/quest/m0/README.md b/quest/m0/README.md index 5327fdc0e54..5ec1c79c845 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -2,11 +2,13 @@ ## Goal -The work in flight now, in two independent tracks. Routing: a publisher stops -sending announce updates the wire cannot tell apart, a service claims the -prefix it could serve instead of enumerating broadcasts. Audio playout: the target is a measured -estimate of arrival timing in both languages, a browser regression fails a -nightly run, and the audio playhead becomes the clock video follows. +The work in flight now, in three independent tracks. Relay hardening: legal +moq-transport input never fails a session ahead of Seattle interop on +2026-10-12, every resource a peer can make the relay hold is bounded by what +it sent or by a budget, and no peer input panics the process. Routing: a +service claims the prefix it could serve instead of enumerating broadcasts. +Audio playout: the target is a measured estimate of arrival timing in both +languages, and a browser regression fails a nightly run. ## Plan @@ -15,27 +17,44 @@ done. moq.pro tracks this repository as a submodule rather than a release, so no release quest gates this milestone. The Pronto GPU integration lives in moq.pro. -Routing: announce-update dedupe is a wire-compatible fix on every version. The -wildcard line is prefix-only on the wire; its resolve and demand work is done -on the line branch and waits to land. Serving the relay's ingested-only -view (`origin::Consumer::local()`) to localhost workers belongs to moq.pro's -edge, which embeds moq-relay; it moved there on 2026-09-28. +Relay hardening: IETF interop leads the ranking, since only those quests +block Seattle. IETF stream types came from m1 in the 2026-09-30 audit +because a session ended by legal input is exactly what Seattle would hit. The DoS hardening +from an external review on 2026-09-29, verified against `main`, stays in m0 +as security work. Its quests describe fixes, not exploits. + +Routing: the wildcard line is prefix-only on the wire; its resolve and demand +work is done on the line branch and waits to land. Serving the relay's +ingested-only view (`origin::Consumer::local()`) to localhost workers belongs +to moq.pro's edge, which embeds moq-relay; it moved there on 2026-09-28. Audio playout: the jitter target replaces the round-trip guess. The harness's browser lane grades it nightly and records the traces it replays; the native -lane is a standalone m1 quest, since nothing here waits on it. The A/V clock -builds on the jitter target's per-track spread. +lane is a standalone m1 quest, since nothing here waits on it. The harness +line lands before the jitter line, since both add +`js/watch/src/audio/replay.test.ts`. The [A/V clock](/quest/m1/av-clock.md) +moved to m1 in the 2026-09-30 audit: it waits on the whole jitter line and is +a published `@moq/watch` break on dev. Published API or wire breaks still land on dev; each quest's Plan says so. ## Required -- [Packaged relay starts](/quest/m0/relay-systemd-unit.md) - the `.deb` and `.rpm` relay service starts instead of crash-looping on `--file` +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - draft-20+ FETCH, allowed parameters, INCLUDE_PROPERTIES and FORWARD=0 decode and are refused per request, not session-fatal +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - a request stream FIN stops updates without cancelling, and REQUEST_UPDATE on a subscribe is parsed +- [IETF stream types](/quest/m0/ietf-uni-stream-types.md) - padding streams are discarded stream-only and an unknown uni type closes the session, per draft-21 +- [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` +- [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - noq carries quinn's stream reassembly cap and the connection receive window is finite by default +- [qmux reset race](/quest/m0/qmux-reset-race.md) - qmux handles RESET_STREAM under one lock instead of panicking +- [Path hunting](/quest/m0/path-hunting.md) - a withdrawn path is retracted about once per relay instead of hunting stale alternatives, with a hold-down on route updates and no wire change +- [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers +- [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - frame buffers pre-allocate within a per-session budget and otherwise grow with bytes received +- [Handshake deadline](/quest/m0/handshake-deadline.md) - an unfinished handshake or slow HTTP header times out +- [Revalidate overflow](/quest/m0/revalidate-overflow.md) - no auth duration can overflow a deadline and abort the relay - [Wildcard](/quest/m0/wildcard/README.md) - a relay resolves subscriptions against advertised prefixes, a service claims the prefix it could serve and refuses the rest instead of enumerating broadcasts, and the browser player treats a covering claim as availability - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - a browser playout latency regression fails a nightly run instead of arriving as a bug report, and its recorder supplies the jitter target's replay traces - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess -- [A/V clock](/quest/m0/plan-av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles ## Related diff --git a/quest/m0/audio-jitter-target/README.md b/quest/m0/audio-jitter-target/README.md index 9ccd989e690..9b5c88ad7de 100644 --- a/quest/m0/audio-jitter-target/README.md +++ b/quest/m0/audio-jitter-target/README.md @@ -14,8 +14,8 @@ the same arrival trace. Boundaries: convergence still uses skip-ahead and silence, so playing slightly faster or slower to converge stays [Time stretch](/quest/m1/watch-audio-time-stretch.md). No packet loss concealment. -Video keeps its own target; making the audio playhead the clock is [Plan: A/V -clock](/quest/m0/plan-av-clock.md). +Video keeps its own target; making the audio playhead the clock is [A/V +clock](/quest/m1/av-clock.md). ## Plan @@ -42,15 +42,15 @@ reporter; they replace the #3477 traces wherever the quests name them. The algorithm is written down at `doc/concept/audio-jitter.md`, with a conformance corpus beside it that both implementations will read. -Neither `main` nor `dev` has a measured estimator. `js/watch/src/sync.ts:159` +Neither `main` nor `dev` has a measured estimator yet. `js/watch/src/sync.ts:159` still computes `max(MIN_JITTER, minRtt * 1.25)` from the connection's PROBE, and `js/watch/src/audio/latency.ts` still exists. `sync.ts` also adds the advertised jitter to that term, where the document settles on a maximum. -The prior art is the branch of PR #3517, -`origin/quest/m0/3477-watch-auto-latency`, two commits ahead of `dev`. The PR -is closed and never merged; the watch quest starts from the branch rather than -from `dev`. It already deletes the RTT term +The prior art from PR #3517 (closed 2026-09-10, branch deleted 2026-09-30) +landed on this line's branch through +[#3954](https://github.com/moq-dev/moq/pull/3954), so the watch quest works +there. It deletes the RTT term (`MIN_JITTER`, `FALLBACK_JITTER`, `#minRtt`, and the `probe` input are gone from `sync.ts`; `latency.ts` survives, minus `reanchorFloor`) and plumbs a per-track arrival `spread` through `Container.Consumer`, measured at container @@ -66,7 +66,7 @@ is immediate and unclamped, so a tune-in across a stale group sets the target to seconds. Note that `sync.ts` has since been refactored on `main` to a `register(jitter)` -list, so the branch does not rebase cleanly. +list, which is one of the conflicts merging `main` in resolves. Native has no jitter buffer at all. `rs/moq-audio`'s `decode::Options` (`rs/moq-audio/src/decode/consumer.rs`) carries `max_age`, how far @@ -76,7 +76,8 @@ buffer against uneven arrivals. ## Required -- [Watch](/quest/m0/audio-jitter-target/watch.md) - js/watch and js/hang bring the #3517 branch's estimator into conformance +- [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - lands first, since both lines add `js/watch/src/audio/replay.test.ts`; it also records the traces the watch quest replays +- [Watch](/quest/m0/audio-jitter-target/watch.md) - js/watch and js/hang bring the #3954 estimator into conformance - [Native](/quest/m0/audio-jitter-target/native.md) - rs/moq-audio grows a measured jitter buffer from the same algorithm ## Closes @@ -85,6 +86,4 @@ buffer against uneven arrivals. ## Related -- [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - the automated proof, and the recorder of the traces the watch quest replays - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - inaudible convergence, on top of this -- [Plan: A/V clock](/quest/m0/plan-av-clock.md) - the clock this target eventually feeds diff --git a/quest/m0/audio-jitter-target/watch.md b/quest/m0/audio-jitter-target/watch.md index a1a258f61ed..0151ecdd387 100644 --- a/quest/m0/audio-jitter-target/watch.md +++ b/quest/m0/audio-jitter-target/watch.md @@ -92,13 +92,9 @@ The branch also replaces `probe` in `SyncInput` with per-track `audioSpread` and `videoSpread` inputs, which breaks the published `@moq/watch` type. This quest lands on `main`, so it adds the spread inputs beside `probe` and stops reading `probe`; removing it is part of the `SyncInput` reshape in -[Plan: A/V clock](/quest/m0/plan-av-clock.md). Land the estimator so +[Plan: A/V clock](/quest/m1/av-clock.md). Land the estimator so that quest can adopt it without a second estimator change. ## Required - [Browser harness](/quest/m0/audio-quality-harness/browser.md) - records the arrival traces this quest replays - -## Related - -- [Plan: A/V clock](/quest/m0/plan-av-clock.md) - reshapes `SyncInput` around the per-track spread this quest produces diff --git a/quest/m0/frame-alloc-budget.md b/quest/m0/frame-alloc-budget.md new file mode 100644 index 00000000000..25c28fba887 --- /dev/null +++ b/quest/m0/frame-alloc-budget.md @@ -0,0 +1,32 @@ +# [M] Frame buffers are backed by bytes received + +## Goal + +The memory a relay commits to an incoming frame tracks what the peer has +sent, not only the size it declared. Today the first payload byte allocates +the whole declared size (up to `MAX_CACHE_BYTES`, 32 MiB) with +`vec![0u8; size]` and charges it to the cache, with no aggregate bound. + +## Plan + +- Pre-allocating the declared size is a deliberate optimization, so keep it + within a per-session budget: a frame whose declared size fits the + session's remaining budget is allocated up front; past the budget the + buffer grows as bytes arrive. Bytes are returned to the budget when the + frame completes or aborts. Decided 2026-09-29. +- Charge the cache by bytes written rather than declared size + (`model/group.rs` `state.cache += frame.size`). +- Benchmark first (`rs/moq-net/benches`): frame receive throughput swept over + frame size and concurrent streams, for today, full growth, and the budget, + so the budget's default comes from the measurement. +- Paths: `model/frame.rs` `MutableFrameBuf::new`, `coding/reader.rs` + `poll_read_frame`, called from both `lite/subscriber.rs` and + `ietf/subscriber.rs`. + +Public API: none expected; if the budget needs a knob, it goes on the relay +config, not moq-net. Wire: none. + +## Related + +- [Frame slot charge](/quest/m1/frame-slot-charge.md) - lands first; both change the cache charge in `model/group.rs` +- [Peer limits](/quest/m1/quic/peer-limits.md) - stream counts and windows per peer diff --git a/quest/m0/handshake-deadline.md b/quest/m0/handshake-deadline.md new file mode 100644 index 00000000000..e8f998804b3 --- /dev/null +++ b/quest/m0/handshake-deadline.md @@ -0,0 +1,24 @@ +# [S] Handshakes and HTTP headers have deadlines + +## Goal + +A connection that never completes its QUIC, WebTransport, WebSocket or MoQ +SETUP handshake is closed after a deadline, and the relay's HTTP listener +times out slow request headers. Today `moq-tokio/src/server.rs` pushes +`accept_request` futures with no deadline, and the 5 s keep-alive keeps an +idle pre-SETUP connection alive indefinitely. axum-server 0.8 builds hyper +without a timer, so hyper's `header_read_timeout` never fires +(`moq-relay/src/web.rs`). + +## Plan + +- Wrap the accept future in a timeout covering everything up to a completed + SETUP, then close with the transport's timeout code. The timeout is a + config value with a default of around 10 s. +- Configure `http1().timer(TokioTimer).header_read_timeout(..)` on the + relay's HTTP builder. +- Tests on a paused clock: a stalled SETUP is closed at the deadline, and a + completed one is not. +- Document both in `doc/bin/relay/config.md`. + +Public API: a config field on the server. Wire: none. diff --git a/quest/m0/ietf-fin-not-cancel.md b/quest/m0/ietf-fin-not-cancel.md new file mode 100644 index 00000000000..ccae4e3d282 --- /dev/null +++ b/quest/m0/ietf-fin-not-cancel.md @@ -0,0 +1,35 @@ +# [M] A request stream FIN is not a cancellation + +## Goal + +On moq-transport's bidi request streams (draft 19+), a peer's FIN means no +more updates, not cancel. Only RESET_STREAM, STOP_SENDING or our own end +cancels. Today a FIN withdraws a PUBLISH_NAMESPACE +(`ietf/subscriber.rs`), ends a SUBSCRIBE_NAMESPACE, and cancels a SUBSCRIBE +(`ietf/publisher.rs`). Draft-21 section 6.4.2.2 says a requester MAY FIN +right after its message. A REQUEST_UPDATE on a subscribe stream is never +parsed either: its first byte makes `poll_closed` return an error and +silently ends the subscription. + +## Plan + +- Gate on version: drafts 17 and 18 say a FIN cancels SUBSCRIBE_NAMESPACE, + so keep that there, and test both sides of the gate. +- Separate the read side's clean FIN (`Reader::poll_closed` returning Ok) + from a reset. On FIN, keep serving and stop reading. Watch the writer for + STOP_SENDING. +- Parse REQUEST_UPDATE on subscribe streams, where the draft allows it. + Apply what we support and refuse the rest `NOT_SUPPORTED`. +- Check the same FIN handling in `js/net`. +- Tests for each request type: FIN right after the request keeps it alive, + a reset cancels it, and a REQUEST_UPDATE is applied. + +Public API: none. Wire: conformance fix; no draft change. + +## Required + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - lands first; both change `ietf/fetch.rs` and the request close path + +## Related + +- [Lite request streams](/quest/m1/request-stream-serve.md) - lite deliberately treats a FIN as ending the request; don't unify the two diff --git a/quest/m0/ietf-legal-input.md b/quest/m0/ietf-legal-input.md new file mode 100644 index 00000000000..32ebf87922b --- /dev/null +++ b/quest/m0/ietf-legal-input.md @@ -0,0 +1,49 @@ +# [L] Legal IETF input never fails the session + +## Goal + +Every message a conformant draft-14 to draft-22 peer may send decodes, and +anything we don't support is refused per request, not by closing the session. +moxygen and libquicr send several of these today, and Seattle interop is +2026-10-12. + +## Plan + +Each of these closes the session today with `PROTOCOL_VIOLATION`: + +- FETCH on drafts 20+ still decodes the removed Fetch Type field + (`ietf/fetch.rs`). Decode the draft-20 layout: namespace, name and params, + with the range in LOCATION_FILTER. Refuse it `NOT_SUPPORTED` until + [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) serves it. Fix the encoder and + the pinned test in `version.rs`. +- Request parameters the draft allows on a message fail `decode_params!`: + AUTHORIZATION TOKEN (0x03) anywhere, NEW_GROUP_REQUEST (0x32) and the + object and track filters (0x25 to 0x29) on SUBSCRIBE and REQUEST_UPDATE, + FILL_TIMEOUT (0x0A) and 0x21 and 0x35 on FETCH, and any parameter on TRACK_STATUS. Accept each + one where the draft allows it. The token is decoded and ignored, since the + session grant still applies; [Request token](/quest/m1/auth/request-token.md) + gives it meaning (decided 2026-09-29). An unknown key stays fatal, per the + draft. +- INCLUDE_PROPERTIES (0x35) is read as length-prefixed; the draft defines a + uint8 (`ietf/subscribe.rs`). Encode and decode it as `u8`, and delete the + doc comment arguing for key-parity framing: that rule covers Setup and + Properties KVPs, not message parameters. +- FORWARD=0 returns `DecodeError::Unsupported`. Decode it, then refuse the + request `NOT_SUPPORTED`. + +Not in scope: pre-draft-20 subscribe filters other than Largest Object stay +ignored. `older_drafts_are_ignored` in `ietf/publisher.rs` records that +choice, since honoring them would change what existing peers receive. + +- Tests: one decode test per message and draft, built from the draft's + message figures and bytes captured from moxygen and libquicr, plus a + session test showing each refusal leaves the session open. +- Mirror the decode in `js/net`. + +Public API: none. Wire: fixes conformance; no draft change. + +## Related + +- [Request token](/quest/m1/auth/request-token.md) - also edits `decode_params!`, turning the ignored token into a per-request grant +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - the other interop blocker +- [IETF stream types](/quest/m0/ietf-uni-stream-types.md) - same stream-scoped-before-fatal rule for uni streams diff --git a/quest/m1/ietf-uni-stream-types.md b/quest/m0/ietf-uni-stream-types.md similarity index 92% rename from quest/m1/ietf-uni-stream-types.md rename to quest/m0/ietf-uni-stream-types.md index 6b0ca089c90..1dfd4e01040 100644 --- a/quest/m1/ietf-uni-stream-types.md +++ b/quest/m0/ietf-uni-stream-types.md @@ -8,6 +8,10 @@ so it ships on main. ## Plan +Moved from m1 to m0 in the 2026-09-30 audit: a padding stream answered with +INTERNAL_ERROR is legal input mishandled, which m0 fixes before Seattle +interop on 2026-10-12. + `run_unis` in `rs/moq-net/src/ietf/session.rs` routes every non-SETUP uni stream to `run_uni_group`, which rejects padding and unknown types alike while leaving the session alive. That stream-only rejection reaches the wire as diff --git a/quest/m0/noq-reassembly-cap.md b/quest/m0/noq-reassembly-cap.md new file mode 100644 index 00000000000..cc4a200a020 --- /dev/null +++ b/quest/m0/noq-reassembly-cap.md @@ -0,0 +1,44 @@ +# [M] noq carries quinn's stream reassembly cap + +## Goal + +The QUIC stacks the relay builds on bound how many out-of-order chunks a +stream or CRYPTO buffer holds, as quinn-proto 0.11.15 does, and a connection's +receive window is finite by default. Today `moq-noq-proto` 1.3.2 (`main`) and +2.0.0 (`dev`), and upstream `noq-proto` 1.3.0 (pulled in by the relay's default `iroh` +feature), predate quinn's fix, and `cargo audit` cannot match them because +the crates are renamed. + +## Plan + +- Port quinn [fed0321a](https://github.com/quinn-rs/quinn/commit/fed0321a) + ([quinn#2694](https://github.com/quinn-rs/quinn/pull/2694), + RUSTSEC-2026-0185) to moq-dev/noq: `Assembler::insert` returns an error past + 1024 buffered chunks after defragmenting, the stream path closes with + `INTERNAL_ERROR`, and the CRYPTO path does the same. Keep quinn's test. + 1.3.3 and 2.0.1 are already taken by the open release PRs moq-dev/noq#21 + and #22: fold the port into those releases or take the next patch numbers, + then bump the pins here. +- Open the same port as a PR on n0-computer/noq (approved 2026-09-29; the + advisory is public; opened as + [noq#828](https://github.com/n0-computer/noq/pull/828)). iroh builds stay on the unfixed upstream crate until + n0 releases it; bump when they do. +- Give `moq-tokio` a finite default connection `receive_window` instead of + the backend's `VarInt::MAX` (`rs/moq-tokio/src/noq.rs` `apply_windows`, + `quic.rs`). Pick the value with a throughput measurement, not a + guess, and update `doc/bin/relay/config.md`. Size it so relay-to-relay + cluster sessions, which carry every viewer's traffic on one connection, + are not throttled; per-peer windows wait for + [Peer limits](/quest/m1/quic/peer-limits.md). +- `rs/moq-uring` depends on `moq-noq-proto` too, so the same pin bump + covers the io_uring workers. + +The in-tree [fork](/quest/m1/quic/fork/README.md) inherits the cap from +quinn main, so after it lands only the receive-window default and iroh's noq +pin remain relevant on `dev`. + +Public API: none. Wire: a peer that exceeds the chunk cap is closed. + +## Related + +- [Peer limits](/quest/m1/quic/peer-limits.md) - per-peer windows and stream limits, which later let cluster sessions take a larger window than clients diff --git a/quest/m0/path-hunting.md b/quest/m0/path-hunting.md new file mode 100644 index 00000000000..7ca416b2467 --- /dev/null +++ b/quest/m0/path-hunting.md @@ -0,0 +1,49 @@ +# [M] A withdrawn path stops hunting + +## Goal + +When a broadcast ends, each relay in a lite-06 mesh retracts it about once, +instead of re-announcing stale alternatives. Today one withdrawal on live's +34-relay graph costs hundreds to over a thousand extra announce starts, and +on Kick dev an ended name drew 575 to 57,805 mesh announce starts (median +about 13,000) while live names drew one flood (moq-dev/moq.pro#2116). New +and removed routes still propagate at once, and no wire changes. + +## Plan + +Promoted from the cluster routing line to m0 on 2026-09-30: it is today's +partial-mesh hunting that #4399 left open, and it is hurting production. + +Decided (2026-09-30), lite-06, no wire change: + +- A route *update*, where a relay's advertised route for a path switches to a + different route, waits a short hold-down before it is re-advertised. A new + path (nothing advertised yet) and a removal (nothing left) go out at once. +- So when the best route is withdrawn and an alternative remains, the relay + retracts at once and re-announces the alternative only if it survives the + hold-down. Stale alternatives are withdrawn inside that window and never + spread. A genuine failover, where a link dies but the origin still + publishes, is delayed by the hold-down; pick the value from the repro, and + report the failover cost it adds. +- Check the interaction with #4399's withdrawal hiding and with + subscriptions already pinned to a route (fronts keep serving from a live + source; only advertisements are held). + +Test first: land moq.pro's in-process repro upstream (real lite-06 sessions +over the mock transport on live's 34-relay graph, mocked time), asserting +about one retraction per relay for a single withdrawal from a non-hub +publisher, plus a failover test where a link dies and the path comes back +through another route after the hold-down. It must fail on `main` today. + +Then moq.pro moves its pin and confirms about one retraction wave per ended +name on Kick dev after a deploy the user approves (moq.pro's own quest). + +If no hold-down closes it, the fallback is a per-origin seqno on cluster +links in the wip lite version; report before building it. + +Public API: none expected. Wire: none. + +## Related + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - tiers shrink the core graph this hunts on +- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - closed broadcasts announced for minutes, the same symptom diff --git a/quest/m0/qmux-reset-race.md b/quest/m0/qmux-reset-race.md new file mode 100644 index 00000000000..0aa6adcdd39 --- /dev/null +++ b/quest/m0/qmux-reset-race.md @@ -0,0 +1,27 @@ +# [XS] qmux handles RESET_STREAM under one lock + +## Goal + +qmux's RESET_STREAM handling never panics when the writer task removes the +receive stream concurrently. Today `session.rs` checks +`streams.recv.contains_key`, drops the lock, and later re-locks with +`.expect("live recv stream")`; a `StopSending` queued by a dropped +`RecvStream` can remove the entry in between. A missing entry must be a +no-op, not a panic. + +## Plan + +- In moq-dev/web-transport `rs/qmux/src/session.rs`, look the entry up once + under a single lock (`if let Some(recv) = get_mut`); a missing entry means + the stream already closed and the reset is a no-op. +- Regression test that removes the entry between the two points. +- Audit the other `expect`s on the stream maps (`sched.rs`) for the same + pattern. +- Release a patch on the pinned 0.5 line and on 0.6, then bump the 0.5 pin + here. Moving to 0.6 is not part of this quest. + +Public API: none. Wire: none. + +## Related + +- [qmux on noq-proto](/quest/m2/quic-qmux.md) - replaces these stream maps entirely, later diff --git a/quest/m0/quest-check-everywhere.md b/quest/m0/quest-check-everywhere.md index c62ab16a6f6..447eadfca61 100644 --- a/quest/m0/quest-check-everywhere.md +++ b/quest/m0/quest-check-everywhere.md @@ -7,21 +7,13 @@ ## Plan -- `dev` has no `quest` flake input and no `quest check` in its justfile; - #4428's main-into-dev sync brings both. After it lands, convert the - old-format quests on `dev` until `quest check` passes there. -- Line branches pin their own `quest` revision (the wildcard line pinned - 46d7fe8 against main's 8590d2a), so an old pin passes an old format. - Merging `main` into each active line bumps the pin; do that for the lines - that fail today and fix what the new check reports. -- `just ci check` runs `quest check` on pull requests only. Also run it on - push to `main`, `dev`, and `quest/**`, so a direct merge commit (such as - `main` merged into a line) can't land a broken tree. Use a dedicated job - that runs `quest check` unconditionally: `check.yml`'s scope steps diff - against `origin/$GITHUB_BASE_REF`, which is empty on a push. +- `check.yml` runs `quest check` on pull requests only. Also run it on push to + `main`, `dev`, and `quest/**`, so a direct merge commit (such as `main` + merged into a line) can't land a broken tree. Use a dedicated job that runs + `quest check` unconditionally: `check.yml`'s scope steps diff against + `origin/$GITHUB_BASE_REF`, which is empty on a push. +- `dev` already pins main's `quest` (8590d2a) and passes since #4428. Only the + wildcard line still pins 46d7fe8: merge `main` into it to bump the pin, and + fix what the new check reports. Public API: none. Wire: none. - -## Required - -- #4428 merged to `dev` diff --git a/quest/m0/relay-systemd-unit.md b/quest/m0/relay-systemd-unit.md deleted file mode 100644 index 37a7e51a19c..00000000000 --- a/quest/m0/relay-systemd-unit.md +++ /dev/null @@ -1,18 +0,0 @@ -# [XS] Packaged relay starts - -## Goal - -The `.deb` and `.rpm` relay service starts. Today -`packaging/moq-relay/moq-relay.service` runs `moq-relay --file -/etc/moq-relay/relay.toml`, but the config path is positional and the relay -rejects unknown flags, so every packaged install crash-loops. - -## Plan - -`ExecStart=/usr/bin/moq-relay /etc/moq-relay/relay.toml`. Add the reporter's -unit test in the relay crate that parses the unit's `ExecStart` with the -relay's own `Cli`, so the unit and the parser can't drift again. - -## Closes - -- [#4343](https://github.com/moq-dev/moq/issues/4343) - close this issue when the quest finishes diff --git a/quest/m0/request-caps.md b/quest/m0/request-caps.md new file mode 100644 index 00000000000..d0ee8679a20 --- /dev/null +++ b/quest/m0/request-caps.md @@ -0,0 +1,40 @@ +# [L] Peer-declared lengths and request counts are bounded + +## Goal + +Every length and count a peer declares is bounded before the relay buffers +or tracks it. That covers three things: + +- lite control messages, which may declare 64 MiB each + (`lite/message.rs`, buffered by `coding/reader.rs` `poll_read_more`); +- IETF FETCH object properties, decoded as a bare `Vec` with no cap; +- IETF incoming request IDs, which are never checked against the + `MAX_REQUEST_ID` we advertise on drafts 14 to 16 (`u32::MAX`, + `rs/moq-net/src/server.rs` and `client.rs`). + +Announces and subscriptions per session are capped as well. + +## Plan + +- Lite: per-message `MAX_SIZE` sized to the largest legitimate message + (SETUP already caps at 64 KiB). Anything larger is a decode error. +- Audit `rs/moq-net/src/coding/` for any other decode that allocates from a + peer length, and cap the fetch properties. This absorbs the deleted + `coding-reader-cap` quest. +- IETF drafts 14 to 16: advertise a finite `MAX_REQUEST_ID` window, grant more with + MAX_REQUEST_ID as requests close, and close with the draft's error on an ID + past it (`ietf/control.rs`, `ietf/adapter.rs`). Draft-17 removed + MAX_REQUEST_ID; there QUIC's bidi stream limit and the per-session cap + bound requests. +- A per-session cap on live announces and subscriptions on both protocols, + refused per request rather than session-fatal where the protocol allows. +- Benchmark per-session request churn swept over sessions and requests per + session, so the window refill shows no slope. +- Mirror the lite message cap in `js/net`. + +Public API: possibly caps on the session config; propose the shape in the PR. +Wire: behaviour within the drafts' existing limits. No format change. + +## Required + +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - MAX_REQUEST_ID refills as requests close, and that change decides when a request closes diff --git a/quest/m0/revalidate-overflow.md b/quest/m0/revalidate-overflow.md new file mode 100644 index 00000000000..f42c8ba0ad1 --- /dev/null +++ b/quest/m0/revalidate-overflow.md @@ -0,0 +1,18 @@ +# [XS] Auth durations cannot overflow a deadline + +## Goal + +No auth-server or token duration can panic the relay. Today +`moq-auth/src/client.rs` computes `Instant::now() + cadence` for the +`revalidate` value, and `Grant::deadline` adds a token's `exp` the same way. +A value near `u64::MAX` seconds overflows and panics. + +## Plan + +- Use `checked_add`. `Grant::validate` refuses a `revalidate` longer than the + grant's expiry, and treats an `exp` beyond `Instant`'s range as no expiry. +- Unit tests with `u64::MAX` revalidate and exp. +- Grep the workspace for other `Instant + Duration` on peer- or + server-supplied values. + +Public API: none. Wire: none. diff --git a/quest/m0/shared-fronts.md b/quest/m0/shared-fronts.md new file mode 100644 index 00000000000..272681e48c3 --- /dev/null +++ b/quest/m0/shared-fronts.md @@ -0,0 +1,33 @@ +# [M] Viewer sessions share a front + +## Goal + +The number of origin fronts for a path is bounded by the peers that appear in +its route chains, not by viewer sessions. Today every session gets +`Hop::random()`, the lite publisher serves through `origin.excluding(hop)`, +and fronts are keyed by `(path, Horizon)` (`model/origin.rs`). Each viewer +therefore mints its own front plus a driver task, and `run_front` only ends +on route retraction or source close, so fronts accumulate for the life of a +long-running broadcast. + +## Plan + +- Key a front by its effective exclusion: a hop that appears in no route + chain for the path excludes nothing, so its sessions share the plain front. + When such a hop later shows up in a chain, the sessions it covers move to + the filtered front. Decided 2026-09-29, over ending idle fronts after a + linger, because it also removes the per-viewer cost while viewers are + active. +- Check whether prefix routes mint fronts for arbitrary covered paths + (`origin.rs` optimistic resolve) and bound that the same way. +- Measure with a benchmark swept over viewers and broadcasts + (`rs/moq-net/benches/origin.rs`): fronts and bytes per viewer before and + after, plus reconnect churn. + +Public API: none. Wire: none. + +## Related + +- [Front deadlines](/quest/m1/front-deadline-index.md) - per-front cost per track +- [Front parking](/quest/m1/origin-front-parks.md) - also changes what mints a front +- [Wildcard](/quest/m0/wildcard/README.md) - its line rewrites `model/origin.rs` heavily (+401 lines, fronts end on a standing refusal); land after it or rebase onto it diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index 8e9173b6d0a..78e88a1dd5a 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -22,9 +22,8 @@ over FETCH wants to say "if nobody is publishing this live, I have it", which is the catch-all `**`, a claim about every path at once. The cost of enumerating is real even though its last measurement is stale. -[relay-memory](/quest/m1/relay-memory.md) measured one announcement at 8.8 KB -per relay plus 4.3 KB per additional route before prefix routes made a -standby route a table entry, and owns remeasuring it. Whatever the current +One announcement measured 8.8 KB per relay plus 4.3 KB per additional route +before prefix routes made a standby route a table entry. Whatever the current number, every relay that hears an announcement pays it whether or not anything there subscribes, so "workers times broadcasts" is that number multiplied across the fleet in resident memory. @@ -51,8 +50,8 @@ Route cost already names this case: "The original publisher seeds it with its production cost: zero for a live publish, something large for a standby that would have to start working (a cold transcoder)" (`drafts/draft-lcurley-moq-lite.md`). `moq_auth::Claims.publish` and -`origin::Producer` gain versioned patterns through -[Path patterns](/quest/m1/path-patterns.md), so tokens and filters reuse the +`origin::Producer` gained versioned patterns on the +[Auth](/quest/m1/auth/README.md) line, so tokens and filters reuse the same matcher; advertisements stay prefixes. `Cost { warm, cold }` (`rs/moq-net/src/model/origin.rs:426`) is the route cost since [#2925](https://github.com/moq-dev/moq/pull/2925). @@ -88,8 +87,8 @@ field. ### Decisions - **One prefix on the wire, one pattern in the token and the filter.** An - advertisement is a path prefix; the [path-patterns](/quest/m1/path-patterns.md) - dialect is what tokens and the consume-side filter use, matched by the + advertisement is a path prefix; the pattern dialect from the + [Auth](/quest/m1/auth/README.md) line is what tokens and the consume-side filter use, matched by the shared matcher, so nothing resembles a second grammar and nothing on the wire spells a wildcard. - **Longest prefix wins, and its refusal is final.** This is the rule @@ -140,7 +139,7 @@ field. refused. A prefix wider than the grant is accepted, but it only routes requests for paths the grant covers. Fleet-wide services use the cluster identity; a customer service serves only what its own v1 grant contains. - Until [Advertise-only authorization](/quest/m1/processor/advertise-auth.md) + Until [Advertise-only authorization](/quest/m2/processor/advertise-auth.md) lands, the publish scope stands in for advertising; a credential with its own advertise scope is checked against that instead. - **Claims are visible to subscribers.** A subscriber sees every advertised @@ -189,7 +188,7 @@ field. - **Patterns are independent of clustering.** The `moq-pattern` crate owns the matching semantics tokens and filters share, with no draft of its own; no announce message carries a pattern on either protocol (AUTH grants on - lite-06 do, per [Path patterns](/quest/m1/path-patterns.md)). moq-cluster adds hop + lite-06 do, per the [Auth](/quest/m1/auth/README.md) line). moq-cluster adds hop lists, costs, pool selection, and request resolution to prefix advertisements. @@ -206,7 +205,9 @@ never see `.pro/` broadcasts, which could confuse their business logic. Those versions cannot opt into hidden routes, so the relay never announces them there. Hidden routes are a moq-lite-07 feature, so the player's covering check (Demand, done on the line branch) opts into them and sees a claim only when -lite-07 is negotiated. A customer who wants transcodes upgrades, or +lite-07 is negotiated. Finalizing lite-07 is a rollout condition, not a +blocker for this line (decided in the 2026-09-30 audit), since the check works +whenever lite-07 is negotiated. A customer who wants transcodes upgrades, or subscribes to the explicit `.pro//...` path, which works on any version. Grants and metering are the deployment's; moq.pro's are in its [wildcard questline](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/wildcard/README.md). @@ -219,13 +220,9 @@ distinguish recording generations reads the catalog's archive entry ## Related -- [path-patterns](/quest/m1/path-patterns.md) - owns the pattern dialect - and the shared matcher tokens and filters reuse - [archive](/quest/m1/archive/README.md) - an archive claims the root, and its catalog names the generations a claim cannot -- [Cluster routing](/quest/m1/cluster-routing.md) - origin selection by cost - with an HRW tie-break, built on this line's longest-prefix rule - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - derived output mirrors the source path, `@` segment included -- [Suffix announce](/quest/m3/suffix-announce.md) - moq-lite-only suffix - claims, deferred until a service prefix cannot express one +- [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite-only exact, + suffix, and prefix+suffix claims that survive relay hops diff --git a/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md b/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md deleted file mode 100644 index a10eafb6a04..00000000000 --- a/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md +++ /dev/null @@ -1,43 +0,0 @@ -# [M] Open-GOP H.264: fixture and cold tune-in characterization - -## Goal - -An open-GOP H.264 broadcast (non-IDR recovery-point keyframes with leading -pictures) round-trips in the `test/ts` harness as a regression fixture, and -the cold tune-in behaviour in a WebCodecs viewer is measured and written down: -glitch duration, dropped versus corrupt frames, and whether any decoder errors. - -## Plan - -#2066 taught the H.264 splitter to treat a recovery-point SEI as a keyframe, -so groups start at the recovery point and the rendition resolves. The -reference capture from #2050 is the hard case: every recovery point is -followed in decode order by about seven pictures presented *before* it, which -reference the previous GOP. At a cold tune-in those leading pictures decode -against missing references, and nothing in the Rust splitter or the JS -consumer identifies them. Continuous playback across a recovery point has all -the references and should be clean. - -- Fixture: `rs/moq-mux/src/container/ts/test_data/scte35/kyrion_dirtystart.ts` - is already open GOP with B-frames; confirm it carries leading pictures - (POC below the keyframe after a recovery point) and use it, else generate a - clip with x264 `open-gop=1` and a recovery-point SEI. The generated clip in - `test/ts/run.sh` is closed-GOP IDR today, so add the open-GOP source as a - second round-trip rather than replacing it. -- Characterization: drive `` through the media harness - (`just test media`, `test/interop/clients/js/media.ts`) with the - open-GOP fixture: continuous playback across recovery points and a cold - tune-in at one, counting dropped and corrupt frames and decoder errors; a - hardware decoder by hand if available. Record the numbers in the PR and in the - leading-picture quest. -- The consumer-side fix is - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md), which - waits on these numbers. - -## Closes - -- [#2067](https://github.com/moq-dev/moq/issues/2067) - close this issue when the quest finishes - -## Related - -- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - the tune-in drop this characterizes diff --git a/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md b/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md deleted file mode 100644 index b85a2da1693..00000000000 --- a/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md +++ /dev/null @@ -1,32 +0,0 @@ -# [XS] hang: document the broadcast wall clock - -## Goal - -A browser application can find how to map presentation time to wall time -from `doc/lib/js/hang.md`, so an application that knows its viewers share a -clock can compute the delay that renders one frame at one instant everywhere, -and a DVR view can label its timeline. - -The library itself never synchronizes playback on wall time. That is the -decision behind [#2278](https://github.com/moq-dev/moq/issues/2278): frame -timestamps are relative by design, `Timestamp::now()` is a one-way bridge with -a per-process jitter to deter wall-clock readings, and two machines' clocks are -only comparable when the application already knows they are synced. No -absolute `delay` mode, no client clock estimation from the session RTT, and no -sync exchange over a track. - -## Plan - -The API already exists: the catalog root's optional `clock` (`ClockSchema`, -`Clock`) and `wallClockTime(clock, pts, ptsTimescale)` in -`js/hang/src/catalog/clock.ts`, exported from `@moq/hang/catalog`. Only the -docs are missing. Add a short section to `doc/lib/js/hang.md`: read `clock` -from a catalog root, convert a frame's PTS with `wallClockTime`, note that a -live-only broadcast carries it without an `archive` entry, that the mapping is -fixed for the broadcast's life, and that comparing wall times across machines -requires the application to know their clocks are synchronized. Keep -`js/watch` arrival-based Sync unchanged. - -## Closes - -- [#2278](https://github.com/moq-dev/moq/issues/2278) - close this issue when the quest finishes diff --git a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md b/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md index 946a68a0a6c..9aaee72e13b 100644 --- a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md +++ b/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md @@ -33,20 +33,18 @@ grant; `Options::bandwidth` documents that their own loop; the capture driver's `_reservation` goes away. Public entry points for a manual ceiling stay `Producer::set_bitrate` and `Encoder::set_bitrate`. -- The audio-codecs line branch moves the Opus encoder behind a backend seam: - the rate setter and its floor live in - `rs/moq-audio/src/encode/backend/libopus.rs` there, and - `Encoder::set_bitrate` dispatches through the backend. Target whichever - shape is on the base when this starts. -- Floor: `set_opus_bitrate` refuses anything outside +- The Opus encoder sits behind the encode backend seam: the rate setter and + its floor live in `rs/moq-audio/src/encode/backend/libopus.rs`, and + `Encoder::set_bitrate` dispatches through the backend. +- Floor: the libopus backend's `set_bitrate` refuses anything outside `opus::bitrate_floor(codec_rate, frame_size).max(500)` to - `300_000 * channels` (`encoder.rs`, `rs/moq-audio/src/opus.rs`). `Policy::min` defaults to a tenth of + `300_000 * channels` (`backend/libopus.rs`, `rs/moq-audio/src/opus.rs`). `Policy::min` defaults to a tenth of the ceiling (`rs/moq-mux/src/rate.rs`); for Opus it is the codec floor, so a grant below it clamps there and never errors. The reservation's ceiling is the configured bitrate; only the policy target moves. - PCM: `pcm::bitrate(sample_rate, channels)` is `pub(crate)` (`rs/moq-audio/src/pcm.rs`), `Settings::bitrate` is refused for it - and so is `set_bitrate` (`encoder.rs`). A PCM + and so is `set_bitrate` (`encoder.rs`, `backend/pcm.rs`). A PCM Producer reserves its fixed rate and runs no policy. That is the same reserve-only usage passthrough imports use, so nothing new is added for it. - Priority is unchanged: `PRIORITY` puts audio at 80 and video at 60 diff --git a/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md b/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md index 9f04697e6ce..0c36f01a0bd 100644 --- a/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md +++ b/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md @@ -1,44 +1,27 @@ -# [M] js/net: decode messages synchronously from buffered bytes +# [XS] js/net: cap the publisher's subscription controls ## Goal -The lite publisher applies every buffered control before it pops a group, -with no read-ahead queue: bounded memory and exact control-first ordering at -once. +A peer flooding `SUBSCRIBE_UPDATE` while the lite publisher is blocked in a +control-stream write cannot grow its memory without bound: past a fixed cap +the session fails with a protocol error. ## Plan -The serving loop must apply every buffered `SUBSCRIBE_UPDATE` before it pops a -group, or a group goes out under a range the peer already superseded. Rust gets -that from `poll_decode_maybe` in `rs/moq-net/src/lite/publisher.rs`, which -decodes straight out of the reader's buffer and so drains controls to -exhaustion in one poll. `js/net/src/lite/publisher.ts` works around -the async `Reader` by decoding ahead into `SubscriptionControls`, which the -loop drains synchronously. That queue is unbounded: it grows while the loop is -blocked in a control-stream write, so a peer flooding updates during a stalled -write converts flow-controlled bytes into heap objects. A single-message slot -was tried in #2820 and broke ordering, because `take()` cannot yield to the -decoder without letting a group pop slip in between. - -`Reader` in `js/net/src/stream.ts` already decodes synchronously: a decode is -a function over a `Cursor`, whose reads throw an internal short signal when the -buffered bytes run out. `tryDecode` returns undefined and consumes nothing in -that case, and `decode`/`decodeMaybe` are the one async driver that fills and -retries. The primitives (`u62`, `u53`, `read`, `string`, ...) are that driver -applied to the `Cursor` reads, and the group and FETCH frame loops drain every -buffered frame with `tryDecode` (`js/net/bench/frames.ts`). The 22 -`static async decode` message decoders under `js/net/src/lite/`, plus four -`decodeMaybe` variants, still await a primitive per field. - -- Convert all 26 decoders to a single synchronous body over a `Cursor`, with - the async form as `reader.decode(...)` rather than a second copy. `Message` - in `lite/message.ts` becomes a sync size-prefixed wrapper. -- The publisher drains controls synchronously in its loop and - `SubscriptionControls` goes away. -- Tests: the publisher applies N buffered updates before the next group - pop; a partial update with a group already ready waits for the second fill - and pops the group under the new range, so incomplete is never read as "no - control pending"; the flood case stays bounded. +`SubscriptionControls` in `js/net/src/lite/publisher.ts` (:169) decodes +ahead of the serving loop so every buffered update applies before the next +group pop. It keeps only the newest range for the loop, but the decoder runs +on its own and calls `apply` for each update, so a peer can turn +flow-controlled bytes into unbounded work and heap while the loop is stalled. +First confirm what still grows on the current code, then cap the updates +decoded between two drains by the loop and fail the session on overflow, +matching Rust's refusal of malformed input. Test: a flood during a stalled +write fails the session instead of growing. + +Decided in the 2026-09-30 audit: the rewrite to synchronous decoders is +dropped. Generated lite from the [rs2ts line](/quest/m1/rs2ts/README.md) +replaces hand-written js/net, and it gets control-first ordering from moq-net's +`poll_decode_maybe`. This quest only closes the memory hole until then. ## Closes diff --git a/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md b/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md deleted file mode 100644 index 891110d96d6..00000000000 --- a/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] Integrate the hardened reuseport group with QUIC workers - -## Goal - -The owning tokio worker group uses `moq_sock::shard::Group`'s enforced -formation and socket-retention contract. Complete and retained socket groups -preserve connection-ID steering through partial startup and member teardown. - -## Plan - -The published `Workers::split` ownership change and functional group shutdown -have landed. Do not repeat -that API redesign here. This follow-up replaces the worker's private lifetime -bookkeeping with the hardened socket-group primitive. - -Adopt moq-sock's claims and complete-group ownership. No member serves before -the final bind and filter attachment, and every socket stays owned until -serving has stopped for the group. Preserve the dev owner, shutdown, failure -propagation, and worker-local builder contract without another published -signature change. - -Use Linux runtime regressions to exercise incomplete startup, a failed final -bind, dropping an unused server handle, and a serving member completing or -failing. Check the socket group and connection-ID steering on a surviving -session while unused handles are dropped, and prove all serving stops when -the group terminates. Wire the tests into normal or nightly CI. - -Public API: no further `moq-tokio` ownership change. The hardened group -already exists (`Group::bind` and `Group::complete` over `Claim` in -`rs/moq-sock/src/shard.rs`). Wire: no format change. Close #2964 only when -both the dev ownership proof and this integration are complete. - -## Closes - -- [#2964](https://github.com/moq-dev/moq/issues/2964) - close this issue when the quest finishes diff --git a/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md b/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md index 53691398992..886144d2d0e 100644 --- a/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md +++ b/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md @@ -86,3 +86,8 @@ the closed producer's cache or terminal state. ## Closes - [#2991](https://github.com/moq-dev/moq/issues/2991) - close this issue when the quest finishes + +## Related + +- [Resume latest](/quest/m1/resume-latest.md) - edits `resume.rs` and its takeover tests (#4491) +- [Parked reads wake](/quest/m1/parked-read-wakes.md) - edits the same `resume.rs` wakeups diff --git a/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md b/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md index 0df856a18a3..b12adcc5407 100644 --- a/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md +++ b/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md @@ -1,37 +1,36 @@ -# [M] GStreamer preserves the broadcast PTS-to-wall clock +# [S] GStreamer picks the broadcast wall epoch ## Goal -`moqsink` maps every media pad onto one continuous broadcast clock, exposing -its fixed wall epoch through the shared Hang contract. Source restarts never -change the interpretation of media already published. +`moqsink` exposes one fixed wall epoch for the broadcast through the shared +Hang clock contract, so every pad's timestamps relate to UTC the same way. ## Plan -Use the current broadcast-wide segment timeline and clock contract, not the -old per-rendition timeline or removed `set_wall` method. Map the buffer PTS -through its TIME segment into the broadcast's running-time domain before -publication, preserving valid within-group B-frame reordering. - -Choose the wall epoch once. Prefer GstReferenceTimestampMeta only when it -names a recognized absolute clock domain; otherwise relate the pipeline clock, -base time, running time, and local SystemTime. Account for the mapped PTS when -computing PTS zero. An unidentified reference clock is not UTC. Every pad uses -the same mapping rather than independently sampling a new epoch. - -Keep that mapping through flushes, encoder restarts, and source PTS resets. -Translate a restarted source forward on the existing clock, including idle -gaps; refuse a source that cannot be mapped consistently. Discontinuity -markers never change wall or retime retained records. Do not add per-record -anchors or define a GStreamer-specific catalog shape. - -Test recognized reference metadata, deterministic local-clock fallback, -delayed first buffers, multiple pads, timescale conversion, numeric limits, -source restarts, idle gaps, and a system-clock adjustment. Existing timeline -records remain unchanged. Consume the prerequisite's catalog format; no new -transport TIMESTAMP/TIMESCALE semantics, synchronization protocol, or drift -correction is introduced here. Run the GStreamer CI and `interop --all` lanes. +The PTS mapping already exists: `rs/moq-gst/src/sink/pad.rs` maps each +buffer PTS through its TIME segment into the shared running-time domain +(`rs/moq-gst/src/sink/timeline.rs`), and #4480 made rewinds drop frames. Only +the wall-epoch choice remains. + +Choose the wall epoch once per broadcast. Prefer GstReferenceTimestampMeta +only when it names a recognized absolute clock domain; otherwise relate the +pipeline clock, base time, running time, and local SystemTime. An unidentified +reference clock is not UTC. Every pad uses the same epoch rather than sampling +its own. Do not define a GStreamer-specific catalog shape. + +Decided in the 2026-09-30 audit: a restart is a new broadcast epoch, not a +forward re-anchor on the old clock (per remove-live and +[GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md)), and +[#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) +handles the sink side. + +Test recognized reference metadata, the deterministic local-clock fallback, +delayed first buffers, and multiple pads sharing one epoch. ## Closes - [#3021](https://github.com/moq-dev/moq/issues/3021) - close this issue when the quest finishes + +## Related + +- [GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md) - a restarted pipeline publishes a new epoch diff --git a/quest/m1/3489-ts-import-stream-liveness.md b/quest/m1/3489-ts-import-stream-liveness.md deleted file mode 100644 index 8107a665b5e..00000000000 --- a/quest/m1/3489-ts-import-stream-liveness.md +++ /dev/null @@ -1,51 +0,0 @@ -# [M] moq import ts: every elementary stream reports its access units and how long it has been quiet - -## Goal - -An operator polling `moq import ts` can tell that a specific PID stopped -delivering access units while the mux kept flowing. `Import::stats` carries a -row for every elementary stream, video and verbatim included, with the -published access-unit count and the current gap since the last one, measured -on the transport's own clock. No threshold and no warning: a sparse stream -such as SCTE-35 is legitimately quiet, so liveness is derived by whoever -alarms. Nothing changes in what is published or how tracks are mapped. - -## Plan - -Measured in #3489: a 60 s video outage behind a running mux passes every TR -101 290 P1 check, produces identical logs, and delivers a 57 s hole; only the -audio half is visible, late, through #3372's resync line. - -- `rs/moq-mux/src/container/ts/import.rs`: `Stream::stats` returns `None` - for `H264`, `H265`, `Opus`, `Verbatim`, and `Clock`, and `Stats` documents - that an absent PID is healthy. Give every elementary stream a row and - retire the absence contract; the `lost.then_some(stats)` gate goes with it. - `StreamStats` is `#[non_exhaustive]`, so the new fields are additive. -- Clock: the packet loop reads the adaptation field for the discontinuity - indicator and skips the PCR bytes; parse the PCR there. `last_pts` advances - on video PES only and freezes with the very stream this must catch. Record - the clock at each access unit in `flush`; the gap is the current clock - minus that mark. Reuse the `discontinuity_indicator` helper the timebase-break - path already shares with duplicate detection. -- Surface: `rs/moq-cli/src/publish.rs` `log_stats` gains a line for a stream - whose count stopped advancing across a sample, distinct from the audio - resync message. The SRT gateway reports nothing today; that surface is - [SRT import stats](/quest/m1/srt-import-stats.md). -- Name and shape the counters so the TR 101 290 quest adopts them as its - `PID_error` check, and leave the catalog `stalled` bit alone: the importer - already sets it for a quiet video PID (`Stream::tick` after each decode - batch, #3630). These counters add no timeout; anything that must bound a - wait on a silent PID (the shared-shift quest) brings its own. -- Tests with the issue's stimulus shape: suppress one PID's PES while keeping - its PCR and continuity legal, assert the row's count stops and the gap - grows; audio and SCTE-35 arms. - -## Closes - -- [#3489](https://github.com/moq-dev/moq/issues/3489) - close this issue when the quest finishes - -## Related - -- [SRT import stats](/quest/m1/srt-import-stats.md) - the same rows read from the SRT gateway -- [#1838](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - the monitoring model that subsumes this as `PID_error` -- [Client stats](/quest/m1/qos/stats/schema.md) - where per-rendition liveness rides a publisher's stats broadcast diff --git a/quest/m1/README.md b/quest/m1/README.md index bc7f3674607..dbd3d4780ff 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -15,156 +15,149 @@ Give one agent ownership of each shared code area at a time (origin/auth, the JS Reader, audio playback, media containers and archive, bindings, worker transport, benchmark tooling); worktrees isolate commits, not semantics. +A line with no named consumer waits in m2 until one appears. The 2026-09-30 +audit moved P2P, one-port, ladder, processor, timed metadata, the installer, +the OBS GPU paths, the IETF half of rs2ts, and the unmeasured io_uring and +QUIC studies there on that rule. + ## Required -- [Late joiner history](/quest/m1/relay-late-joiner-history.md) - a subscriber joining a relay's track from group 0 later still receives the cached finished group below the live one -- [Cluster routing](/quest/m1/cluster-routing.md) - an announcement says where a broadcast originates, not how to reach it, and a relay hears only the prefixes its clients asked for -- [Exact scope](/quest/m1/exact-scope.md) - a reader never sees an exact broadcast outside its scope, in Rust or JS; prefix routes above it still present as the empty path +- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - a relay notices a silent peer relay within seconds, not after the shared 30 s QUIC idle timeout +- [moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md) - no moq-transport session negotiates the cluster extension, so none can splice a pool's members on a Hop ID label +- [Cluster routing](/quest/m1/cluster-routing/README.md) - edge and core tiers carry each broadcast into a region once over path vector, with the backbone hidden from end users +- [Remove `--hop`](/quest/m1/hop-removal.md) - on `dev`, redundant publishers share an explicit `@`, and `--hop` and the publisher's Hop ID are gone +- [One route cost](/quest/m1/route-cost.md) - on `dev`, Warm and Cold collapse to one static route cost - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` +- [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below -- [Error messages](/quest/m1/error-display.md) - Python, Go, and Dart print `MoqError` with Rust's message, as Kotlin and Swift do +- [Android logcat](/quest/m1/android-logcat.md) - on dev, Android builds always log to logcat and the `android-logcat` feature is gone - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one +- [IETF drain before close](/quest/m1/ietf-drain-before-close.md) - moq-transport sessions deliver finished tracks before a graceful close, as moq-lite does +- [Close waits for the tail](/quest/m1/close-tail.md) - on lite-07, `close()` returns `Ok` only after each subscriber FINs its Subscribe Stream, having read the track to its end +- [moq play drain tail](/quest/m1/play-drain-tail.md) - retired renditions and finite tracks play their last 10 ms of audio - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted - [moq announced](/quest/m1/cli-announced.md) - `moq ls` becomes a follow-only live view named `moq announced`, with local-only shell completion - [Delete the live marker](/quest/m1/announce-live-removal.md) - announce streams yield only route events; the `Live` marker and its hold machinery are gone -- [IETF hidden default](/quest/m1/ietf-hidden-default.md) - a moq-transport peer without the MoQ Hidden option is advertised hidden namespaces; one with it filters per subscription -- [moqsink recoverable errors](/quest/m1/moqsink-keyframe-latch.md) - a leading delta or a timestamp rewind drops frames until a keyframe instead of invalidating a moqsink pad -- [Splice edge cases](/quest/m1/splice-edges.md) - an unstamped successor, a pruned segment's boundary group, and a warm head during a takeover are each handled correctly +- [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover -- [Track tail hardening](/quest/m1/track-tail-hardening.md) - Rust and JS wait out a track's tail by the same rules, with the known hang, count, truncation, grace, and memory holes closed -- [JS close end](/quest/m1/js-track-close-end.md) - a JS track's clean close ends at its own last group, not a sibling producer's - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every stream group in a lite subscription arrives or is dropped by name, and lite-07 drops its stream count for it - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - on dev, a lite-07 SUBSCRIBE asks for past and live ranges in either order and replaces FETCH; relays fill misses by range, including over moq-transport -- [FIN wait expiry](/quest/m1/fin-wait-expiry.md) - a group awaiting its FIN ack still expires and follows priority updates on lite and IETF - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls +- [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does +- [Parked reads wake](/quest/m1/parked-read-wakes.md) - a read parked on an evicted or aborted group wakes and re-judges, for resume successors and plain tracks alike +- [Reader end parity](/quest/m1/reader-end-parity.md) - JS readers see a track's end once the newest group reaches the declared end, as Rust readers do +- [JS cache window](/quest/m1/js-prune-cache-window.md) - js/net ages idle groups on a cache window and keeps max_age as media-time staleness, as Rust does +- [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death -- [Watch video guards](/quest/m1/watch-video-guards.md) - promoting a video track holds the last picture, and an older group never reaches the codec between live deltas -- [Watch decoder recovery](/quest/m1/watch-decoder-recovery.md) - one malformed packet rebuilds the audio or video decoder instead of ending playback -- [Watch audio under CSP](/quest/m1/watch-worklet-file.md) - production builds ship the audio worklet as a file, so `script-src 'self'` pages play audio -- [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause -- [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - the interop audio tone check stops failing on cold start, fixed at its cause -- [Auth outage clock](/quest/m1/auth-outage-clock.md) - the relay and moq-auth outage tests run on a paused clock again and assert both bounds of `expires` +- [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL +- [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause +- [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs +- [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux +- [Rewind detail](/quest/m1/timestamp-rewind-detail.md) - a refused timestamp rewind names the frame's timestamp and the live edge - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end -- [Slow group log](/quest/m1/slow-group-log.md) - a starved viewer reports skipped groups once per catch-up, not once per group -- [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN -- [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main -- [CI hygiene](/quest/m1/ci-hygiene.md) - a push to one PR never cancels another's run, and a failed run never saves the Rust cache +- [Plan: max-delay](/quest/m1/plan-max-delay.md) - decide whether `max_age` becomes `max_delay` across the CLI, APIs, and bindings - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container -- [Full codec string](/quest/m1/publish-codec-string.md) - browser-published video carries the encoder's full RFC 6381 codec string, so native players decode it -- [TS program selection](/quest/m1/ts-programs.md) - `import ts` refuses a multi-program stream unless `--program ` picks one or publishes each -- [TS export jitter](/quest/m1/ts-export-jitter.md) - the video reorder bound follows later catalogs and the declared reorder depth, so a late B-frame never reorders TS output; an undeclared stream can reorder once per new maximum depth -- [ffmpeg muxdelay](/quest/m1/ts-publish-muxdelay.md) - the documented MPEG-TS publish line adds `-muxdelay 0`, so quiet audio is not clumped -- [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives -- [PipeWire duplicate cameras](/quest/m1/pipewire-dup-cameras.md) - a webcam lists once with PipeWire enabled -- [Catalog wall clock](/quest/m1/catalog-wall-clock.md) - `Clock::wall_clock` keeps the catalog's full precision instead of truncating to milliseconds +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers fed one stream publish identical groups and timestamps, so failover between a redundant pair survives - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check -- [RTMP TLS only](/quest/m1/rtmp-tls-only.md) - an RTMP listener configured for TLS can refuse plaintext instead of sniffing and serving it -- [HLS linger](/quest/m1/hls-linger.md) - `moq_hls::Server` serves an ended broadcast for its playlist window plus grace, so the moq.pro edge drops its own pool -- [iroh versions](/quest/m1/iroh-lite-wip.md) - `iroh://` negotiates the configured versions, so `moq-lite-07-wip` can be opted into +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import +- [TS damaged units](/quest/m1/ts-damaged-units.md) - one malformed PES or access unit is dropped, counted as `damaged`, and resynced at the next keyframe instead of ending the import +- [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies +- [TS stats module](/quest/m1/ts-stats-module.md) - on dev, the TS stats types move under `ts::stats` as `Snapshot` and `Stream`, with an owned `track` +- [Audio capture without ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound +- [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away +- [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables +- [Data track clock](/quest/m1/data-track-clock.md) - JSON and binary data tracks stamp on the catalog's clock at write time, matching the media's anchored clock - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers -- [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass -- [JS IETF reprice](/quest/m1/js-ietf-reprice.md) - `@moq/net`'s IETF publisher reprices a held namespace in place, like Rust, instead of withdraw-then-advertise -- [Cluster publisher in place](/quest/m1/cluster-publisher-in-place.md) - under the IETF cluster extension a publisher change updates an advertisement in place, like lite, and never splices across publishers +- [Publishing requires a timestamp](/quest/m1/publish-timestamp.md) - every Rust and binding publish API takes a timestamp; nothing fills in now for the caller +- [JS publishing requires a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net +- [Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) - decide what a frame's timestamp is when a moq-transport or pre-lite-05 peer sends none +- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding +- [Nested data configs](/quest/m1/data-config-nesting.md) - docs nest `BinaryConfig`/`JsonConfig` in an application section instead of flattening it +- [Omit empty catalog sections](/quest/m1/catalog-omit-empty.md) - a Rust catalog with no video or audio leaves those keys out, as JS does +- [Public clock anchor](/quest/m1/clock-anchor-public.md) - an application demuxer shares one source offset across its tracks through `Anchor` and `Lane` +- [Delete SourceMap](/quest/m1/source-map-removal.md) - on dev, `Anchor` with its `Lane`s is the one way onto the broadcast clock +- [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - a draft-20+ FETCH within one group is served from its LOCATION_FILTER, as older drafts are +- [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - a relay fetches from an IETF upstream without subscribing, finished tracks included, with End of Track always reported +- [IETF timestamp units](/quest/m1/ietf-timestamp-units.md) - drafts 14-16 stop sending Timestamp properties they can't give units for - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust +- [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - no FETCH, replay to a new subscriber, or cache fill ever returns a datagram group - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers -- [JS fetch cancel](/quest/m1/js-fetch-cancel.md) - `FetchGroupOptions.signal` abandons one pending fetch without closing the track - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the catalog entry and format may break in place, since no archives exist -- [Tooling](/quest/m1/tooling/README.md) - justfiles become a one-line menu over `sh/`, one impact map scopes CI, and every workflow step runs a recipe -- [Path patterns](/quest/m1/path-patterns.md) - one matcher for every predicate over broadcast paths: tokens, origins, interest - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` -- [Shaper virtual time](/quest/m1/shaper-virtual-time.md) - `moq-shaper` tests judge seeded decisions on paused time, not on wall-clock delivery under load -- [Rust compressed gate test](/quest/m1/json-compressed-gate-rs.md) - `rs/moq-json` proves a snapshot delta is gated on its encoded size -- [Shrink the JS overflow test](/quest/m1/json-rolls-snapshot-test.md) - the `js/json` roll-on-overflow test uses a small `maxGroupBytes` budget instead of megabytes of JSON - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [Retire the libmoq stub](/quest/m1/libmoq-retire.md) - on dev, the published `libmoq` crate stops after its final release points users at `moq-c` - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - replace FFmpeg video and audio decoding with moq-video and moq-audio, deliver GPU frames, and use native audio/video encoders -- [Opus concealment](/quest/m1/opus-conceal.md) - a lost Opus packet conceals the last packet's length, not 120 ms -- [Audio codecs](/quest/m1/audio-codecs/README.md) - platform audio codecs, explicit unsupported cases, and channel layouts up to 7.1 +- [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers +- [HE-AAC catalog output](/quest/m1/he-aac-catalog-output.md) - HE-AAC catalog entries name the output rate and layout, not the LC core +- [TS Opus export refusals](/quest/m1/ts-opus-export-refusals.md) - the TS exporter refuses Opus heads its channel code cannot describe instead of mislabeling them +- [TS Opus channel codes](/quest/m1/ts-opus-channel-codes.md) - TS Opus with a channel code of 0x81 or above imports with its real head or is refused, never guessed as stereo +- [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - macOS and iOS encode AAC-LC +- [AAC encode refusals](/quest/m1/aac-encode-refusals.md) - on dev, `Config::encode` refuses channel counts it cannot name instead of writing stereo +- [AAC parse truncated SBR](/quest/m1/aac-parse-truncated-sbr.md) - `Config::parse` refuses SBR and PS configs cut off before their core +- [GStreamer surround Opus](/quest/m1/gst-opus-surround.md) - the moq-gst sink publishes 3 to 8 channel Opus with the OpusHead its caps describe +- [TS AAC PCE joins](/quest/m1/ts-aac-pce-join.md) - PCE-described AAC over TS plays after a mid-stream join or resume, and a missing PCE silences only its track +- [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) - on dev, the binding audio encoder takes the codec's own frame by default, so `aac()` needs no explicit 0 - [Opus mapping family](/quest/m1/opus-mapping-family.md) - on dev, the Opus head config keeps its mapping family only in `mapping` -- [Opus catalog rate](/quest/m1/opus-catalog-rate.md) - MKV Opus import publishes the 48 kHz codec rate in the catalog, not the OpusHead input rate - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table - [CMAF surround Opus](/quest/m1/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table -- [js/hang dOps pre-skip](/quest/m1/js-dops-pre-skip.md) - CMAF encoding in js/hang stops hard-coding a 312-sample pre-skip - [GPU CI](/quest/m1/gpu-ci.md) - NVIDIA tests run nightly on a self-hosted GPU runner, and `just rs nvidia` runs them locally instead of skipping - [Capture cut test](/quest/m1/capture-cut-e2e.md) - the capture loop's keyframe throttle is tested end to end against an encoder with its own GOP - [NVENC keyframe flag](/quest/m1/nvenc-keyframe-flag.md) - NVENC flags keyframes from its reported picture type instead of scanning the bitstream - [JS rendition ranking](/quest/m1/js-ranked.md) - `@moq/hang` ranks video renditions like Rust, and `@moq/watch`'s fallback uses it - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name -- [FLV rebind before header](/quest/m1/flv-rebind.md) - single-track FLV switches to a better rendition announced before the header - [FLV catalog stream](/quest/m1/flv-catalog-stream.md) - on dev, `flv::Export` takes a catalog stream like fmp4, replacing `with_select` -- [Own the QUIC stack](/quest/m1/quic/README.md) - the moq-noq fork carries ACK progress, reliable reset, hierarchical scheduling, deadlines, peer limits, and qmux -- [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, and client stats broadcasts from publishers and viewers, on dev +- [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the relay's io_uring workers honor the QUIC flow-control windows instead of refusing them +- [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding +- [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, on dev +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - catalog rendition keys become aliases with an optional `track` name, so one catalog lists renditions from several broadcasts +- [Media stats](/quest/m1/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and a Rust encoder adapts to them - [Drain](/quest/m1/drain/README.md) - relay restarts drain sessions over GOAWAY instead of hard-dropping them - [Strict Redirect::resolve](/quest/m1/redirect-resolve.md) - on dev, `Redirect::resolve` can no longer quietly turn a refused redirect into a redial - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - a session that came up over WebSocket moves to QUIC once the QUIC dial lands, handing over at a group boundary -- [P2P](/quest/m1/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy -- [One port](/quest/m1/one-port/README.md) - a relay speaks QUIC, STUN, WebRTC media, and SRT on one UDP port and HTTP, RTMP, and RTMPS on one TCP port -- [Signed priority](/quest/m1/signed-priority.md) - on dev, every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants -- [Stream sessions](/quest/m1/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most - [IETF on the ring](/quest/m1/uring-ietf.md) - the io_uring workers serve moq-transport sessions too, so a uring relay drops no client protocol - [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) - packet bookkeeping scales with completed entries instead of scanning the flight on every ACK - [Perf](/quest/m1/perf/README.md) - eliminate measured hot-path costs across moq-uring, kio, and the moq-net model - [#2924](/quest/m1/2924-moq-relay-tls-rotation-is-not-atomic-across-thread-per.md) - every listener on both runtimes shares one reloadable served identity, so rotation is atomic and generate works with workers -- [#2964](/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md) - integrate the dev worker owner with hardened socket-group formation - [Benchmark regressions in CI](/quest/m1/bench-ci.md) - PRs get a non-blocking comparison of the Criterion benches they affect, and a nightly trend on main alerts on regressions - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - retained evidence, repeated paired runs, and uncertainty for performance claims - [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - moq-bench reports per-interval latency percentiles so the ramp leaves the steady state - [Relay session bench](/quest/m1/bench-relay.md) - the same scenario through moq-relay's own connection handling -- [Bench coverage](/quest/m1/bench-coverage.md) - Criterion targets for moq-mux containers, the hang catalog, moq-auth verification, and moq-pattern matching -- [Stats producer bench](/quest/m1/stats-producer-bench.md) - the stats drain and encode cost per tick, swept over held paths and tiers and run nightly - [Relay profiling](/quest/m1/performance-profiles.md) - reproducible CPU and allocation captures under the existing workloads - [Browser benchmarks](/quest/m1/browser-benchmarks.md) - measure JS transport, container, decode, and render costs in an identified browser - [Generated @moq/net](/quest/m1/rs2ts/README.md) - the browser runs moq-net as TypeScript generated from the Rust source, retiring js/net's hand-written protocol and model code - [Plan: watch worker](/quest/m1/plan-watch-worker.md) - prototype an invisible page worker against app-spawned workers, and land the jank harness that decides - [Watch worker](/quest/m1/watch-worker.md) - watch playback runs in a worker onto an OffscreenCanvas, so main-thread jank never stalls video or audio -- [Closure counters](/quest/m1/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw -- [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - with the default pool, relay memory plateaus at the expiry window on every version - [Plan: cache age-out](/quest/m1/cache-wall-eviction.md) - a swept benchmark decides whether the track cache ages groups out on wall time without a write - [Frame slot charge](/quest/m1/frame-slot-charge.md) - a group's frame slots past the first four count against the cache pool, including capacity a released group keeps -- [Relay memory](/quest/m1/relay-memory.md) - remeasure what an announcement costs after prefix routes - [Front deadlines](/quest/m1/front-deadline-index.md) - a front's per-event cost stops growing with its track count: an expiry index and per-track wakes, proven by a churn benchmark - [Front parking](/quest/m1/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence - [JS abandonment](/quest/m1/js-subscribe-abandonment.md) - a viewer returning during IETF subscribe setup keeps its track across microtasks -- [IETF stream types](/quest/m1/ietf-uni-stream-types.md) - padding streams are discarded stream-only and an unknown uni type closes the session, per draft-21 -- [Rust decode caps](/quest/m1/coding-reader-cap.md) - every Rust decode that allocates from a peer-supplied length is bounded - [Epoch primitive](/quest/m1/epoch.md) - one `Epoch` type in moq-net and @moq/net, carried as a trailing `@` path segment, shared by e2ee and broadcast epochs - [E2EE](/quest/m1/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - each publish of a name gets a fresh `@` epoch, viewers follow the newest live one at once, and bare names still resolve on every version -- [Processor](/quest/m1/processor/README.md) - a customer-run worker publishes an on-demand contribution under its own service prefix with scoped access - [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - watch: the video decoder resets on a declared discontinuity - [#933](/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md) - the catalog rotation follows the live camera's orientation - [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` -- [Ladder](/quest/m1/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling -- [LOC duration marker](/quest/m1/loc-duration-marker.md) - LOC producers write the marker once released consumers skip it -- [#2278](/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - hang: document reading the catalog-root clock and converting PTS to wall time, without synchronizing library playback to wall time - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - js/watch: the audio ring converges by time-stretching instead of skipping or going silent +- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles - [Native audio quality](/quest/m1/audio-quality-native.md) - the browser lane's profiles, budgets, and metric schema run against `moq play` on a dummy device -- [fMP4 emsg](/quest/m1/emsg.md) - event messages survive fMP4 import, and the timed-metadata contract ID3, SCTE-35, and FLV script tags share is settled with them -- [#2279](/quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition - [Caption import](/quest/m1/captions-import.md) - fMP4 and MKV subtitle tracks import as text renditions instead of erroring or being dropped - [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption, subtitle, or sign-language track survives conversion to a hang catalog -- [CEA-608/708](/quest/m1/captions-cea.md) - captions carried inside video SEI become a real text rendition at import -- [Colour model](/quest/m1/color-model.md) - the catalog describes a rendition's colour and HDR properties instead of leaving a TODO -- [#2067](/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md) - Open-GOP H.264: a regression fixture and a measured cold tune-in +- [Encoder colour](/quest/m1/color-model.md) - every moq-video encode path signals the colour its output actually has, or refuses instead of mislabelling - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms -- [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - GStreamer maps every pad onto one continuous broadcast clock across source restarts -- [Export linger](/quest/m1/export-linger.md) - every `moq export` waits `--linger` for a broadcast to return, and exits 0 on a clean end and 1 on a drop -- [TS byte schedule](/quest/m1/ts-export-byte-schedule.md) - moq export ts places PCRs and padding on the byte grid `mpegts.muxRate` implies, so a receiver can clock off arrival -- [#3489](/quest/m1/3489-ts-import-stream-liveness.md) - moq import ts: every elementary stream reports its access units and how long it has been quiet -- [SRT import stats](/quest/m1/srt-import-stats.md) - the SRT gateway reports the same per-stream counters instead of nothing -- [Text availability](/quest/m1/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline -- [ID3 catalog section](/quest/m1/id3.md) - timed ID3 as a first-class container-neutral catalog section -- [FLV script tags](/quest/m1/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import +- [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - moq-gst picks the broadcast wall epoch; a restarted source is a new epoch, not a forward re-anchor +- [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the T-STD buffer model, starting with a fixed `--delay` +- [FLV export delay](/quest/m1/flv-export-delay.md) - FLV interleaves through the shared fixed-delay release stage +- [MKV export delay](/quest/m1/mkv-export-delay.md) - MKV interleaves through the shared fixed-delay release stage - [Release profile](/quest/m1/release-profile.md) - every release build gets fat LTO, one codegen unit, and stripping from the workspace profile instead of three script exports - [Size report](/quest/m1/size-report.md) - a nightly job reports every shipped artifact's size, native and JS, and alerts when one grows - [Publish lazy file source](/quest/m1/publish-lazy-file.md) - a camera or screen `` stops downloading mediabunny's ~99 KB gzip @@ -173,16 +166,11 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Bindings size profile](/quest/m1/ffi-size-profile.md) - a benchmark decides whether the moq-ffi builds ship at opt-level "s", which halves the dylib - [Go mirror delivery](/quest/m1/go-mirror-delivery.md) - the Go binding's staticlibs stop growing git history by ~210 MiB per release - [Relay iroh opt-in](/quest/m1/relay-iroh-opt-in.md) - moq-relay drops iroh from its defaults and shipped builds, while moq-cli keeps it for P2P +- [Rust owns mobile codecs](/quest/m1/mobile-ownership.md) - the settled verdict (Rust codecs, CVPixelBuffer bridge) is written where binding work reads it - [Dart on iOS](/quest/m1/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can - [Kotlin JVM exit](/quest/m1/kt-jvm-exit.md) - a Kotlin/JVM program exits cleanly whatever the moq-ffi runtime thread is doing, like Python does since #3766 - [Dart publish](/quest/m1/dart-publish.md) - the packages are built and dry-run clean but exist nowhere consumers can install from - [Dart codec parity](/quest/m1/dart-codecs.md) - Dart is the one binding that cannot originate media -- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net: decode messages synchronously from buffered bytes and delete the publisher read-ahead queue -- [Install moq](/quest/m1/moq-installer.md) - one command installs or upgrades the released CLI on macOS and Linux -- [Install URL](/quest/m1/moq-install-url.md) - moq.dev serves the canonical installer at /install.sh -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - the relay runs under a `moq` verb with its own flags and TOML, while `moq-relay` stays a minimal binary +- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net caps the publisher's subscription controls so a flood cannot grow memory without bound - [`moq --listen` admission](/quest/m1/cli-serve.md) - a listening CLI session is authenticated, scoped, counted, and drained like a relay's instead of accepting everything - [#709](/quest/m1/709-automatic-letsencrypt-support.md) - the relay provisions and renews its own ACME certificate through rustls-acme over TLS-ALPN-01, persisted on disk -- [Audio capture without ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound -- [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables -- [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the relay's io_uring workers honor the QUIC flow-control windows instead of refusing them diff --git a/quest/m1/aac-encode-refusals.md b/quest/m1/aac-encode-refusals.md new file mode 100644 index 00000000000..5f6dca02906 --- /dev/null +++ b/quest/m1/aac-encode-refusals.md @@ -0,0 +1,27 @@ +# [S] AAC config encode refuses unnameable channel counts + +## Goal + +`moq_mux::codec::aac::Config::encode` never writes an AudioSpecificConfig that +names the wrong layout. A channel count no channelConfiguration names is +refused, not logged and written as stereo, the way the ADTS writer refuses it. + +## Plan + +- `encode` returns `Bytes` today, so refusing is a published API break: this + retargets to `dev`. Decide whether it returns a `Result` or whether a + constructor validates the count up front so encoding cannot fail. +- A count a program config element could describe (7, or more than 8) is + still refused unless the caller supplies a layout; guessing speaker + positions is what this removes. +- Callers in `moq-audio` (encoder config, description synthesis) already + validate first; check they keep their error messages. `Producer` synthesizes + the ASC at construction, so it refuses such a layout there. +- JS already matches: `@moq/hang`'s `audioSpecificConfig` throws for the same + counts (#4119). Test every count from 1 to 8 and one beyond. + +Public API: `Config::encode` (or its constructor) changes. Wire: none. + +## Related + +- [#4283](https://github.com/moq-dev/moq/pull/4283) - the ADTS export refusals this mirrors diff --git a/quest/m1/aac-parse-truncated-sbr.md b/quest/m1/aac-parse-truncated-sbr.md new file mode 100644 index 00000000000..3a6d94fc831 --- /dev/null +++ b/quest/m1/aac-parse-truncated-sbr.md @@ -0,0 +1,21 @@ +# [XS] AAC config parse refuses truncated SBR and PS + +## Goal + +`Config::parse` refuses an AudioSpecificConfig that signals SBR or PS +(object type 5 or 29) but ends before its extension rate and core object type, +instead of accepting it as if the core were known. + +## Plan + +- The export path already requires these fields; `parse` stays lenient only + because `Config::encode` writes a two-byte config for those object types. + Once encode refuses or completes them, the leniency has no producer. +- Check the `moq-audio` tests that feed a two-byte HE-AAC config; they should + keep asserting a refusal, just a different one. + +Public API: none beyond a new error case. Wire: none. + +## Required + +- [AAC encode refusals](/quest/m1/aac-encode-refusals.md) - encode stops producing truncated SBR and PS configs diff --git a/quest/m1/android-logcat.md b/quest/m1/android-logcat.md new file mode 100644 index 00000000000..233f09e880f --- /dev/null +++ b/quest/m1/android-logcat.md @@ -0,0 +1,41 @@ +# [XS] Android logs always go to logcat + +## Goal + +On dev, `moq_tokio::Log::init` sends logs to logcat on every Android build, so +the published Kotlin and Dart bindings (and libmoq) stop losing every Rust log +to stderr, which Android app processes discard. The `android-logcat` Cargo +feature is gone from `moq-tokio` and `moq-ffi`. + +## Plan + +Today the logcat layer in `rs/moq-tokio/src/log.rs` is gated on +`all(target_os = "android", feature = "android-logcat")`, and no shipped build +enables the feature: libmoq has no `[features]`, and `rs/moq-ffi/build.sh`, the +Dart build hook, and the release workflows build Android without it. The +published `dev.moq:moq-ffi-android` 0.4.8 does not link `liblog`. + +Decided (maintainer, 2026-09-30): gate the layer on `target_os = "android"` +alone and delete the feature, rather than wire it through every build, so no +Android consumer has to know to turn it on. Logging stays opt-in at runtime, +since `Log::init` runs only when the app calls it. Removing a feature from +published crates is a break, so this targets dev; no no-op feature is kept. + +- `tracing-android` becomes a plain dependency under the existing + `cfg(target_os = "android")` target table in `rs/moq-tokio/Cargo.toml`; it + must stay target-gated because `android_log-sys` links `liblog` + unconditionally. +- Fix the `Log::init` doc comment, which already claims logcat. +- Leave the `rs/moq-native` tombstone alone. +- Regression check: the Android CI workflow builds moq-ffi for one Android + target and asserts the `.so` imports `__android_log_*`. + +The reporter ([#4456](https://github.com/moq-dev/moq/issues/4456)) has this +working locally and offered the PR. + +Public API: breaking on dev, the `android-logcat` feature is removed from +`moq-tokio` and `moq-ffi`. Wire: none. + +## Closes + +- [#4456](https://github.com/moq-dev/moq/issues/4456) - Rust logs never reach logcat on Android diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index dd334aa40b5..28cf3ecec7e 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -114,9 +114,7 @@ owned by that prerequisite, not duplicated in archive storage. - [Recording writer](/quest/m1/archive/writer.md) - feed the segmenter from a `broadcast::Consumer`, store each segment, then commit its record - [Recording reader](/quest/m1/archive/reader.md) - serve archived FETCH through a supplied `broadcast::Producer` -- [Paced replay](/quest/m1/archive/paced-replay.md) - a replay pushes its groups to live subscribers on one shared clock, so any live player plays it - [Replay provenance](/quest/m1/archive/provenance.md) - a replay's catalog names its timeline, replay path, store URL, and format version -- [Browser archive](/quest/m1/archive/browser.md) - the same contract for browser-published broadcasts - [Offline archive HLS](/quest/m1/archive/hls.md) - render playlists from the archive timeline and fetch segment media lazily - [DVR rewind](/quest/m1/archive/dvr.md) - seek through a bounded archive and return to live playback - [Enrollment flake](/quest/m1/archive/enrollment-flake.md) - the opening-snapshot test waits for real enrollment, not the `.info` file diff --git a/quest/m1/archive/enrollment-flake.md b/quest/m1/archive/enrollment-flake.md index 43950247033..f8a02346e09 100644 --- a/quest/m1/archive/enrollment-flake.md +++ b/quest/m1/archive/enrollment-flake.md @@ -22,5 +22,5 @@ Public API: none. Wire: none. ## Related -- [More tests hold up under load](/quest/m1/test-flakes-2.md) - the same +- [More tests hold up under load](/quest/m1/test-flakes-2/README.md) - the same round of load-only failures on `main` diff --git a/quest/m1/archive/writer.md b/quest/m1/archive/writer.md index 16eb74108d2..3a1329e1f74 100644 --- a/quest/m1/archive/writer.md +++ b/quest/m1/archive/writer.md @@ -70,6 +70,14 @@ Wait the deletion grace period from successful recovery, then delete unreference left by interrupted expiration or uploads. Failed or incomplete recovery must prevent deletion. Preserve `.info` and timeline checkpoint objects. +On resume, fail loud on a track that goes backward. The resume step already +refuses a group ID at or below the recovered track's last one; also refuse a +first group whose timestamp is before the recovered track's last recorded +timestamp, instead of writing overlapping media time. The caller starts a new +prefix. Test a backward and a forward restart. Decided in the 2026-09-30 +audit: folded in from a separate quest, and the archive format may break in +place since it is unreleased. + Keep archive policy out of protocol libraries. As the native application that owns its storage and track choices, `moq-cli` attaches the writer to every import path and enrolls the resulting `broadcast::Consumer` tracks. Downstream diff --git a/quest/m1/audio-codecs/README.md b/quest/m1/audio-codecs/README.md deleted file mode 100644 index e6051c995d2..00000000000 --- a/quest/m1/audio-codecs/README.md +++ /dev/null @@ -1,70 +0,0 @@ -# Audio codecs - -## Goal - -A broadcast that plays in the browser plays natively. Today the browser -decodes whatever the platform offers (HE-AAC, 5.1 AAC, AC-3, surround Opus) -while `moq-audio` decodes Opus and AAC-LC in mono or stereo, so the same -stream plays on moq.dev and fails in OBS, `moq play`, and every binding. The -native side grows the backend seam `moq-video` already has, uses the OS codec -where one exists, keeps symphonia as the pure-Rust fallback, and carries more -than two channels end to end. Encoding follows the same seam so a native -publisher can produce AAC. - -## Plan - -Platform first, exactly like video: AudioToolbox on macOS and iOS, Media -Foundation on Windows, MediaCodec on Android, and symphonia (AAC-LC -mono/stereo) as the software fallback that openh264 is for H.264. Linux has no -OS audio decoder, so HE-AAC and multichannel AAC stay refused there, stated in -the docs and rejected at construction. A platform backend claims every catalog -codec its framework opens, so AC-3, E-AC-3, MP3, and FLAC ride along on the -hosts that have them; each still needs a fixture before the backend advertises -it. - -Use the extensible `Layout` contract settled in main, with well-known layouts in one -canonical order, derived from the codec description (AAC channelConfiguration, -OpusHead mapping) so the catalog and wire do not change. Every decoder reorders -from its codec's native order into that one, so the mixer, the FFI, and OBS -never guess where the LFE is. Playback downmixes to whatever the output device -opened. Preserve the existing arbitrary-channel PCM passthrough through an -unspecified discrete layout; refuse spatial remixing when speaker positions -are unknown instead of guessing them. - -Encode mirrors decode: an `encode::backend` seam, `Codec::Aac` meaning AAC-LC -at the input's layout, and platform encoders behind it. Opus encode stays -mono/stereo. - -The next merge from main conflicts in `rs/moq-audio/src/decode/decoder.rs`: -[#4442](https://github.com/moq-dev/moq/pull/4442) conceals one Opus frame on -loss there, while this line moved that logic into `decode/backend/libopus.rs`. -Port the fix by hand, taking the concealed duration from the multistream -packet rather than the single-stream call. - -The core configuration and layout contracts land in main. These quests implement -surround and backend dispatch on that contract; each platform then lands as -its own decode and encode quest so verification stays per host. The -HE-AAC refusal and the PCE parse are defects in what ships today and are -ready now. - -## Required - -- [Named codecs](/quest/m1/audio-codecs/named-codecs.md) - `decode::Kind::Named` keeps the published codec names and picks backends internally; must land before the line merges -- [HE-AAC refusal](/quest/m1/audio-codecs/he-aac-refusal.md) - implicit-SBR HE-AAC over TS is refused instead of half-decoded as the LC core -- [AAC PCE](/quest/m1/audio-codecs/aac-pce.md) - a channel_config of 0 parses the program config element instead of guessing stereo -- [Layout](/quest/m1/audio-codecs/layout.md) - the settled `Layout` carries up to 7.1 through decode, resample, playback, and the FFI -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - `decode::backend` selects a platform decoder before symphonia, mirroring moq-video -- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers -- [Opus surround](/quest/m1/audio-codecs/opus-surround.md) - mapping family 1 decodes on every host through the multistream decoder -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - `encode::backend` and `Codec::Aac`, so a native publisher can produce AAC-LC -- [AudioToolbox encode](/quest/m1/audio-codecs/encode-audiotoolbox.md) - macOS and iOS encode AAC-LC - -## Related - -- [OBS native codecs](/quest/m1/obs-moq-video/README.md) - the OBS source and encoder adapters consume this through moq-ffi; #3498 narrowed OBS to what moq-audio decodes today -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - Windows and Android verification needs a host; the Windows and macOS CI gates only compile -- [Dart codec parity](/quest/m1/dart-codecs.md) - Dart gains these once it builds with the `audio` feature -- [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer -- [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC -- [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - Android decodes HE-AAC, multichannel AAC, and what else the device offers -- [MediaCodec encode](/quest/m2/audio-encode-mediacodec.md) - Android encodes AAC-LC diff --git a/quest/m1/audio-codecs/aac-pce.md b/quest/m1/audio-codecs/aac-pce.md deleted file mode 100644 index db99ec93f95..00000000000 --- a/quest/m1/audio-codecs/aac-pce.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] moq-mux: an AAC channel_config of 0 parses the PCE or refuses the track - -## Goal - -The catalog never invents an AAC channel count. A stream whose -channelConfiguration is 0 gets its count from the program config element it -carries, and a reserved value refuses the track with a clear error. Today -both map to stereo with a warning. - -## Plan - -The ADTS and ASC importers in `rs/moq-mux/src/codec/aac` map -`channel_config == 0` and every value from 8 to 15 to stereo and warn. -Warn-then-continue is banned: supported or refused. - -- ASC: with `channel_config == 0` the GASpecificConfig carries a - `program_config_element`; parse its front, side, back, and LFE element - counts into the channel count (and, once [Layout](/quest/m1/audio-codecs/layout.md) - lands, into a layout). -- ADTS: channel_config 0 means the PCE is in the first raw data block. Parse - it there, once per track, the same way the HE-AAC sniff reads the first - block's fill elements. -- Give every ASC configuration from 8 to 15 an explicit disposition: implement - any supported channel mapping and return `Error::Unsupported` for every - remaining value, including reserved configurations. -- Regression: an ASC fixture with a PCE reports its real count; an ADTS - fixture with an in-band PCE does too; each value from 8 to 15 has its - supported count asserted or is refused; the - common configurations 1 to 7 are unchanged. - -## Related - -- [HE-AAC refusal](/quest/m1/audio-codecs/he-aac-refusal.md) - reads the same first block -- [Layout](/quest/m1/audio-codecs/layout.md) - what the parsed PCE eventually maps to diff --git a/quest/m1/audio-codecs/decode-backend.md b/quest/m1/audio-codecs/decode-backend.md deleted file mode 100644 index ecfb6f64ba9..00000000000 --- a/quest/m1/audio-codecs/decode-backend.md +++ /dev/null @@ -1,43 +0,0 @@ -# [M] A decode backend seam that prefers the platform codec - -## Goal - -`moq_audio::decode` selects a backend per codec the way `moq_video::decode` -does: platform first, software fallback, and a `Kind` to force one. Opus, -PCM, and symphonia AAC-LC become the software backends, and the crate -documents which codecs each host decodes. - -## Plan - -Mirror `rs/moq-video/src/decode/backend` in name and shape: a crate-private -`Backend` trait (`decode`, `flush`, `name`), an `open(codec, config)` that -walks the platform candidates before the software ones and refuses when none -takes the track. Use the backend-selection configuration and Decoder -constructor settled in main rather than adding a conflicting public shape. -`Decoder::name()` reports what was opened, which the OBS -stats and `moq play` surface. - -- The seam is generic over `hang::catalog::AudioCodec`, so a backend advertises - the set it opens and the selector asks each in order. Symphonia advertises - AAC-LC mono/stereo only; the platform backends that follow advertise what - their framework opens and has a fixture for. -- Move today's Opus, PCM, and symphonia code behind the trait without changing - behavior; the HE-AAC sniff from [HE-AAC refusal](/quest/m1/audio-codecs/he-aac-refusal.md) - lands in the symphonia backend. -- A backend's output rate and layout are what it produced, not what the - catalog said (HE-AAC doubles the rate); `Consumer` already resamples and - remixes to the requested output, so that stays the seam's contract. -- The `aac` feature keeps gating symphonia. Platform backends are - `cfg(target_os)` like their video counterparts. Audio has no MediaCodec - feature yet; its Android quest introduces the optional dependency following - the settled media build policy. -- Docs: `doc/lib/rs/moq-audio.md` gains the backend table `moq-video.md` has, - and states the Linux gap. `doc/bin/cli.md` and `doc/bin/obs.md` follow. -- Regression: the selection order and `Named` refusal, tested with a stub - backend like the video seam's `probe`. - -The FFI does not expose `Kind` until a consumer asks. - -## Related - -- [Layout](/quest/m1/audio-codecs/layout.md) - independent; the platform backends need both diff --git a/quest/m1/audio-codecs/encode-audiotoolbox.md b/quest/m1/audio-codecs/encode-audiotoolbox.md deleted file mode 100644 index 401142b2919..00000000000 --- a/quest/m1/audio-codecs/encode-audiotoolbox.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] AudioToolbox AAC encode on macOS and iOS - -## Goal - -On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's -layout, up to 7.1, and the result plays in the browser, `moq play`, and OBS. - -## Plan - -An `AudioConverter` from interleaved `f32` to `kAudioFormatMPEG4AAC`, behind -the encode seam as the platform candidate on macOS and iOS. - -- The catalog ASC is synthesized at construction per the encode seam; read - `kAudioConverterCompressionMagicCookie` at open and assert it matches. - `kAudioConverterPrimeInfo` gives the delay the timestamps fold in. -- Bitrate through `kAudioConverterEncodeBitRate`, updated live where the - converter allows. -- Regression: a stereo and a 5.1 encode round-trip through the AudioToolbox - decoder and through symphonia (stereo only), with timestamps continuous - across the priming. -- Decided in [#4183](https://github.com/moq-dev/moq/pull/4183): the uniffi - `MoqAudioEncoderOutput::frame_duration_us` default moves from 20000 to 0 - (the codec's own frame) with this quest, so `aac()` works without an - explicit 0. Changing a published binding default is a break, so that - change targets `dev`. - -## Required - -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts -- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - the round-trip regression decodes through it diff --git a/quest/m1/audio-codecs/encode-backend.md b/quest/m1/audio-codecs/encode-backend.md deleted file mode 100644 index c1eb4a7b290..00000000000 --- a/quest/m1/audio-codecs/encode-backend.md +++ /dev/null @@ -1,50 +0,0 @@ -# [M] An encode backend seam and an AAC output codec - -## Goal - -`moq_audio::encode` selects a backend the way `moq_video::encode` does, and -`Codec::Aac` is a valid output: AAC-LC at the input's sample rate and layout, -published with the AudioSpecificConfig description every player expects. A -host with no AAC encoder refuses it at construction. - -## Plan - -Mirror the decode seam: `encode::backend` with a crate-private `Backend` -trait (`encode`, `flush`, `set_bitrate`, `name`), an `open(codec, config)` -that walks platform candidates before software ones, using the public settings -and selection contract settled in main. Opus and PCM retain their behavior. This -quest adds AAC through platform encoders; no software AAC dependency is selected. - -- `encode::Codec` gains `Aac`, meaning `mp4a.40.2`, and `as_str` / `FromStr` - accept `"aac"`, which is what moq-c's codec string carries. moq-ffi's - immutable codec object gains an `aac()` constructor and conversion; do not - reintroduce a closed binding enum. The generated bindings, hand-written - wrappers, and docs follow the Cross-Package Sync table. -- Catalog emission: `AudioCodec::AAC` with profile 2, `Container::Legacy`, - and the encoder's reported delay folded into timestamps like Opus pre-skip - is today. `Producer` registers the rendition before the first frame is - written, so the ASC `description` is synthesized at construction from the - config with `moq_mux::codec::aac::Config::encode`, never read back from the - backend's first packet. A backend that reports its own header (a magic - cookie, `csd-0`, `MF_MT_USER_DATA`) must produce one equal to the synthesized - ASC, asserted in its tests. -- The line branch's `aac-encode-refusals` quest makes `Config::encode` refuse - a channel count no channelConfiguration names instead of writing stereo, so - that synthesis is fallible and `Producer` refuses such a layout at - construction. JS matches: `@moq/hang`'s `audioSpecificConfig` throws for the - same counts (#4119, on the line). This absorbs the former m2 - aac-encode-refusal quest, a duplicate of that line quest. -- Frame size is the codec's (1024 samples for AAC), so `frame_duration` is - validated per codec rather than against the Opus table. -- Bitrate updates go through the backend; one that cannot change rate - mid-stream keeps its opening rate, as the video seam documents. -- Regression: the selection order with a stub backend; `Codec::Aac` refused on - a host with no backend; the Opus and PCM paths unchanged. - -## Required - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the naming and shape this mirrors - -## Related - -- [OBS audio publishing](/quest/m1/obs-moq-video/audio-publish.md) - the OBS encoder adapter can offer AAC once this lands diff --git a/quest/m1/audio-codecs/he-aac-refusal.md b/quest/m1/audio-codecs/he-aac-refusal.md deleted file mode 100644 index f7995cc0f71..00000000000 --- a/quest/m1/audio-codecs/he-aac-refusal.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] Refuse implicit-SBR HE-AAC instead of half-decoding it - -## Goal - -An HE-AAC stream that signals AAC-LC and carries SBR only in band is refused -with a clear error, the same way explicitly signaled and backward-compatible -HE-AAC already are. Today it decodes as the LC core at half the sample rate -with no indication anything is wrong. - -## Plan - -ADTS carries a 2-bit profile, so HE-AAC over MPEG-TS (SRT, `moq import ts`) -always arrives as `mp4a.40.2` with a synthesized LC AudioSpecificConfig. The -config-level checks in `rs/moq-audio/src/aac.rs` cannot see it, and the code -says so. The stream itself can: the first raw data block carries an `ID_FIL` -element with `EXT_SBR_DATA` (or `EXT_SBR_DATA_CRC`), and every later frame -does too. - -- Sniff the fill elements of the first packet before handing it to symphonia. - An SBR extension makes the track `Error::Unsupported` with the same wording - as the config-level refusal, naming the host's decoder as the reason. -- Symphonia already walks the element tree, so the sniff is a small parser - over the same syntax, not a decode. It runs once per track. -- Regression: an ADTS fixture with implicit SBR is refused; the existing - explicit and backward-compatible fixtures keep their errors; an LC fixture - with an unrelated fill element still decodes. -- When a platform decoder handles the track ([Decode seam](/quest/m1/audio-codecs/decode-backend.md)), - the sniff belongs to the symphonia backend only; the OS decoders read SBR in - band themselves. - -## Related - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the sniff becomes the software backend's contract -- [AAC PCE](/quest/m1/audio-codecs/aac-pce.md) - the other place the catalog lies about an AAC stream diff --git a/quest/m1/audio-codecs/layout.md b/quest/m1/audio-codecs/layout.md deleted file mode 100644 index 07b184f5f2f..00000000000 --- a/quest/m1/audio-codecs/layout.md +++ /dev/null @@ -1,51 +0,0 @@ -# [M] Channel layouts through decode, playback, and the FFI - -## Goal - -`moq-audio` carries up to 7.1 end to end. A decoded frame says which layout -it is in, the playback mixer downmixes it to whatever the device opened, a raw -PCM consumer can ask for a layout, and the FFI and moq-c expose the same. -Proven with multichannel PCM, the one codec that needs no new decoder. - -## Plan - -Extend the Layout contract settled in main with supported surround layouts -(2.1, quad, 5.0, 5.1, 6.1, 7.1, and the other AAC channelConfiguration and -Opus mapping family 1 entries) in one canonical order, the SMPTE/WAVE order. -Keep the representation extensible. Each codec module maps its native -order into it: AAC's `C L R Ls Rs LFE` and Opus's Vorbis `L C R Ls Rs LFE` -both become `L R C LFE Ls Rs`. An unspecified discrete PCM layout remains -valid for passthrough but is refused for spatial remixing; never invent speaker -positions from an arbitrary channel count. - -- Reuse the settled PCM descriptors and codec/consumer settings. This quest - adds supported layout behavior rather than replacing public field types. - Frame stays layout-free since the consumer fixed it at construction. -- `resample::remix` becomes a generic remix over layouts: ITU-R BS.775 - coefficients for downmix, silence in the extra speakers for upmix, and the - existing mono/stereo paths as the two-channel special cases. The resampler is - already channel-generic. -- Playback: the mix bus takes the device's layout instead of fixed stereo, the - device chooser prefers the widest well-known layout the device offers (a - 5.1 HDMI sink opens at six channels, a headset at two), and each `Sink` - remixes into the bus. Today's "silence past the front pair" fan-out goes. -- moq-ffi and moq-c keep `channels` as a count, and the count means the - default layout for that count (the WAVE convention: 3 is 2.1, 4 is quad, 6 - is 5.1, 8 is 7.1), delivered or accepted in the canonical order. No record, - `repr(C)` struct, or binding changes, so this stays on `main`; only the - Rust API names the layout, and a binding that needs 5.0 rather than 5.1 is - a later additive field. Document the mapping in every binding's audio doc. -- The catalog does not change: `channel_count` already carries what the - description implies, and `js/hang`'s `aac.ts` stops falling back to stereo - for a count it cannot map. -- Regressions: a 5.1 PCM broadcast published through `encode::Producer` and - read back through `decode::Consumer` at 5.1, at stereo, and at mono; the - mixer fed a 5.1 sink into a stereo bus and a stereo sink into a 5.1 bus; the - device chooser picking six channels when offered. - -Capture stays mono/stereo, and Opus encode stays mapping family 0. - -## Related - -- [Opus surround](/quest/m1/audio-codecs/opus-surround.md) - the first coded multichannel consumer of the layout -- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - the first platform decoder producing more than stereo diff --git a/quest/m1/audio-codecs/named-codecs.md b/quest/m1/audio-codecs/named-codecs.md deleted file mode 100644 index 4bba08d514e..00000000000 --- a/quest/m1/audio-codecs/named-codecs.md +++ /dev/null @@ -1,27 +0,0 @@ -# [XS] Kind::Named keeps its codec names - -## Goal - -`moq_audio::decode::Kind::Named` accepts what published moq-audio 0.1.6 -accepts, the codec names (`"opus"`, `"aac"`, `"pcm"`), so the line can merge -to `main` without breaking callers. [#4131](https://github.com/moq-dev/moq/pull/4131) -switched it to backend names (`"libopus"`, `"symphonia"`, `"pcm"`) on the line -branch, which turns every existing `Named("opus")` or `Named("aac")` into -`Error::Unsupported` after an upgrade. This must land before the line PR -[#4081](https://github.com/moq-dev/moq/pull/4081) merges to `main`. - -## Plan - -- Decided: keep codec names; backends are picked internally. Which backend - decodes AAC (AudioToolbox, Media Foundation, symphonia) is the library's - choice through `Auto` and `Software`, not a string a caller has to know and - that changes per platform. This reverses #4131's reasoning on purpose: the - published contract wins over matching moq-video's backend naming. -- Make `encode::Kind` read the same way. It is unpublished, so drop `Named` - there or give it the same codec meaning, whichever leaves the two enums - mirrored; don't keep backend names on one side only. -- Tests that forced a backend by name move to a crate-private seam. -- Docs and the `Kind` doc comments list the codec names. - -Public API: `decode::Kind::Named` returns to its published meaning, so the -line stays additive on `main`. Wire: none. diff --git a/quest/m1/audio-codecs/opus-surround.md b/quest/m1/audio-codecs/opus-surround.md deleted file mode 100644 index de6247ae0c0..00000000000 --- a/quest/m1/audio-codecs/opus-surround.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] Opus surround through the multistream decoder - -## Goal - -An Opus track with channel mapping family 1 (up to 7.1, RFC 7845 §5.1.1) -decodes on every host, delivered in the canonical `Layout` order. Pure Rust, -so this is the one multichannel path Linux gets. - -## Plan - -- `moq_mux::codec::opus::Config` parses the channel mapping (family, stream - count, coupled count, and the mapping table) instead of skipping it. Family - 0 stays mono/stereo; family 1 maps to a `Layout` by channel count; family - 255 and unknown families are refused, since they carry no speaker - assignment. -- The Opus decode backend opens `opus_multistream_decoder_create` from - `unsafe-libopus` when the family is 1, and reorders Vorbis order into the - canonical one on the way out. -- Encode stays family 0; `Config::encode` keeps refusing more than two - channels. -- Regression: a family-1 5.1 fixture decodes to six channels in canonical - order; family 255 is refused at construction. - -## Required - -- [Layout](/quest/m1/audio-codecs/layout.md) - the type the mapping resolves to diff --git a/quest/m1/audio-codecs/decode-audiotoolbox.md b/quest/m1/audio-decode-audiotoolbox.md similarity index 70% rename from quest/m1/audio-codecs/decode-audiotoolbox.md rename to quest/m1/audio-decode-audiotoolbox.md index effbebb8098..cda8f73b5cc 100644 --- a/quest/m1/audio-codecs/decode-audiotoolbox.md +++ b/quest/m1/audio-decode-audiotoolbox.md @@ -10,9 +10,14 @@ documents as unsupported. ## Plan An `AudioConverter` from the packetized format to interleaved `f32` at the -codec's native rate and layout, behind the decode seam as the first platform -candidate on `target_os = "macos"` and `"ios"`. `objc2-audio-toolbox` is the -binding, alongside the `objc2-core-audio-types` the crate already carries. +codec's native rate and layout, behind the decode seam +(`rs/moq-audio/src/decode/backend`) as the first platform candidate on +`target_os = "macos"` and `"ios"`. `objc2-audio-toolbox` is the binding, +alongside the `objc2-core-audio-types` the crate already carries. + +- With a platform tier in place, `Auto` falling past a refusing platform + decoder to software should warn, as moq-video's `select` does; the seam + only aggregates the refusals into its error today. - Build the `AudioStreamBasicDescription` and magic cookie from the catalog description; the converter reports the output layout, which maps to @@ -20,7 +25,8 @@ binding, alongside the `objc2-core-audio-types` the crate already carries. - HE-AAC: the converter reads SBR in band and reports the doubled rate; the seam passes it through. No config-level guessing. - Priming and remainder: AudioToolbox reports `kAudioConverterPrimeInfo`; - trim it so timestamps line up with symphonia's output on the same stream. + report it as the backend's startup delay, which the front end trims, so + timestamps line up with symphonia's output on the same stream. - Every codec the backend advertises has a fixture and a decode test, and the test asserts the layout order matches the canonical one (the LFE and centre end up where `Layout` says). @@ -29,11 +35,6 @@ binding, alongside the `objc2-core-audio-types` the crate already carries. - Docs: `doc/bin/obs.md` drops the HE-AAC and multichannel caveat on macOS, and the backend table names what this host decodes. -## Required - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as - ## Related - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - the same shape on Windows diff --git a/quest/m1/audio-encode-audiotoolbox.md b/quest/m1/audio-encode-audiotoolbox.md new file mode 100644 index 00000000000..6892e275b16 --- /dev/null +++ b/quest/m1/audio-encode-audiotoolbox.md @@ -0,0 +1,37 @@ +# [M] AudioToolbox AAC encode on macOS and iOS + +## Goal + +On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's +layout, up to 7.1, and the result plays in the browser, `moq play`, and OBS. + +## Plan + +An `AudioConverter` from interleaved `f32` to `kAudioFormatMPEG4AAC`, behind +the encode seam as the platform candidate on macOS and iOS. + +- The catalog ASC is synthesized at construction per the encode seam; read + `kAudioConverterCompressionMagicCookie` at open and assert it matches. + `kAudioConverterPrimeInfo` gives the delay the timestamps fold in. +- Bitrate through `kAudioConverterEncodeBitRate`, updated live where the + converter allows. +- The seam assumes one packet per frame. If the converter holds output back, + the backend needs a `flush` and a zero-or-more return, which changes + `Encoder::encode` and so targets `dev`. +- Gate the seam's "AAC refused without a platform encoder" test to hosts + without one. +- Regression: a stereo and a 5.1 encode round-trip through the AudioToolbox + decoder and through symphonia (stereo only), with timestamps continuous + across the priming. +- That continuity fails today for an epoch below the delay: `Producer::timestamp` + (`rs/moq-audio/src/encode/producer.rs`) clamps each priming packet to zero, + so a zero epoch stamps `[0, 0, 0, 20_000]`, and `decode::Consumer` reads the + duplicates as holes and resets AAC between them. Shift the whole timeline by + the deficit instead, including the terminal end (found in #4081 review). +- Until [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) + lands on `dev`, binding callers pass `frame_duration_us: 0` with `aac()`. + Split out on 2026-09-30 so this quest stays on `main`. + +## Required + +- [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - the round-trip regression decodes through it diff --git a/quest/m1/auth-outage-clock.md b/quest/m1/auth-outage-clock.md deleted file mode 100644 index 43c923a8b3e..00000000000 --- a/quest/m1/auth-outage-clock.md +++ /dev/null @@ -1,63 +0,0 @@ -# [M] Auth outage tests on a paused clock - -## Goal - -The moq-relay and moq-auth outage tests run on tokio's paused clock again and -assert both bounds: a session (or grant) survives an auth outage until its -`expires`, and closes at `expires`, not later. No wall-clock sleeps, no -widened timeouts, and no dependence on how fast the OS delivers loopback. - -## Plan - -- The tests: `an_outage_keeps_the_session_until_expires` in - `rs/moq-relay/tests/auth_lifetime.rs` - ([#4244](https://github.com/moq-dev/moq/pull/4244)) and - `an_outage_keeps_the_grant_until_expires` in `rs/moq-auth/src/client.rs` - ([#4291](https://github.com/moq-dev/moq/pull/4291)). Both moved to the real - clock because a paused clock auto-advances while the runtime waits on a - real socket, so a virtual timer fired before macOS delivered loopback. That - swapped one violation of "unit tests mock time" for another, and #4244 - dropped the upper bound. Read both PR descriptions: they list what was - tried and why it failed (restoring a listener probe, pausing after setup, - waiting on the log). -- The race is real sockets under virtual time, so fix it by taking the - sockets out of these tests. Look at what the codebase already offers - before building anything: `rs/moq-net/tests/support/mock.rs` (an in-memory - session pair), `moq_relay::auth::Auth::embedded` with its `Admissions` - (decides leases in-process), and the lease driver in moq-auth, which could - be exercised against an in-process answer source instead of HTTP. If the - relay's `Connection` or moq-auth's `Client` cannot take such a transport, - prefer the small seam that lets them over a test-only shim. -- Decide where each assertion belongs. The outage semantics (a 503 keeps the - grant until `expires`) are moq-auth's; the relay test may only need to show - that a lease reaching `expires` closes the session as `Expired` and reports - `end`. Don't keep two tests proving the same thing. -- Measure against tokio's clock, not `SystemTime`: the grant still carries a - wall-clock `expires`, so pin how it maps onto the paused clock. -- Other paused-clock tests touch real sockets and would share the hazard - once a timeout lands on their path. #4291's audit named - `a_grant_within_clock_skew_stays_live` (moq-auth) and - `fixed_addresses_keep_tls_name_and_request_host` (moq-tokio websocket); - moq-auth's `clock_server` helper exists only to keep axum on the paused - clock. Move those onto the same seam if it is cheap. -- Prove it: loop the tests with every core loaded, on macOS if available, - and mutate the deadline both ways (close early, close late) to see each - bound fail. - -Public API: none unless a transport seam is needed; report it if so. Wire: -none. - -## Related - -- [More tests under load](/quest/m1/test-flakes-2.md) - the same rule - applied to other load-only failures -- [moq-shaper virtual time](/quest/m1/shaper-virtual-time.md) - the same - paused-clock-versus-real-socket fight in moq-shaper -- [#4280](https://github.com/moq-dev/moq/pull/4280) - moq-archive and - moq-hls tests poll with real-clock sleeps, on the archive track-timeline - line -- [#4281](https://github.com/moq-dev/moq/pull/4281) - OBS `WaitFor` polling, - on the C++ line -- [Nightly 2026-09-26](https://github.com/moq-dev/moq/actions/runs/36240326747/job/108399481809) - - the macOS relay tarball job failed this test with "publisher connect - timeout", before #4244 landed diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index df9b46f7c89..df7c411cabb 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -47,8 +47,8 @@ Decisions settled while planning, recorded so review does not relitigate them: root, and every token in a union shares the connection's root. Unscoped permission is `**`; an empty union grants nothing. Legacy AUTH wire codecs explicitly convert representable prefix unions, where `[""]` means all, - and refuse patterns they cannot represent. [Pattern interest](/quest/m1/path-patterns.md) - upgrades AUTH and ANNOUNCE_REQUEST wire fields together without changing + and refuse patterns they cannot represent. Pattern interest (#4277, on this + line) upgrades AUTH and ANNOUNCE_REQUEST wire fields together without changing the public pattern-valued grant type. - **Fail loud by aborting the session.** A publisher whose origin announces a broadcast outside the union aborts the session with `Unauthorized`, naming @@ -111,7 +111,7 @@ existing lite-06 ALPN. - [Expired token error](/quest/m1/auth/expired-error.md) - an expired token reports `Error::Expired`, not `Unauthorized`, in Rust, JS, and the bindings - [Bindings](/quest/m1/auth/bindings.md) - grants and tokens reach every - binding through moq-ffi and moq-c + binding through moq-ffi - [Token in band](/quest/m1/auth/token-in-band.md) - the credential can leave the URL: a session starts on what the URL carried and its AUTH streams add the rest, with the URL kept for peers below lite-06 @@ -120,7 +120,6 @@ existing lite-06 ALPN. ## Related -- [Pattern interest](/quest/m1/path-patterns.md) - moves AUTH's legacy grant prefixes to patterns; ANNOUNCE_REQUEST stays a prefix -- [Expiring media grants](/quest/m1/processor/grant-lease.md) - a worker's +- [Expiring media grants](/quest/m2/processor/grant-lease.md) - a worker's lease renewal is a new in-band token -- [P2P](/quest/m1/p2p/README.md) - the first consumer of hop-bound peer grants +- [P2P](/quest/m2/p2p/README.md) - the first consumer of hop-bound peer grants diff --git a/quest/m1/auth/bindings.md b/quest/m1/auth/bindings.md index 7f652ef27ba..c46c2540c8b 100644 --- a/quest/m1/auth/bindings.md +++ b/quest/m1/auth/bindings.md @@ -2,43 +2,44 @@ ## Goal -Every binding can read a session's grant and present more tokens: moq-ffi and -moq-c expose it, and the hand-written Python, Swift, Kotlin, Go, and Dart -wrappers and their docs carry it. An OBS user whose token is about to expire -mid-stream can be handed a new one without the plugin reconnecting. +Every binding can read a session's grant and present more tokens: moq-ffi +exposes it, the generated C and C++ bindings pick it up from moq-ffi, and the +hand-written Python, Swift, Kotlin, Go, and Dart wrappers and their docs carry +it. An OBS user whose token is about to expire mid-stream can be handed a new +one without the plugin reconnecting. ## Plan - `MoqSession` in `rs/moq-ffi/src/session.rs` gains `auth()` returning an `Arc` object, the shape `publisher()` uses, with `grant() -> - Option` (a record: publish prefixes, subscribe prefixes, expiry as - a duration) for the union, `async grant_changed() -> MoqGrant` so a caller + Option` (a record: publish patterns, subscribe patterns, expiry + as a duration, matching `auth::Grant`) for the union, `async grant_changed() -> MoqGrant` so a caller can await the next change without polling, and `async add(token: String) -> Arc` whose object carries that token's own `grant()` and `closed()` and whose release withdraws it, raising the structured error moq-ffi already maps on refusal. `MoqClient` sessions reached through the reconnecting connection use the accessor [Relay tokens](/quest/m1/auth/relay-refresh.md) adds. -- moq-c: `moq_session_auth_grant`, `moq_session_auth_add`, and - `moq_auth_token_close` with the terminal-status callback contract the other - async calls use, in `rs/moq-c/src/api.rs` and the session table; - regenerate `moq.h`, and update `cpp/obs/src` only if the plugin surfaces a - token field, otherwise leave it. -- Interop: the Python, Go, and C interop clients print their grant and join +- No new libmoq API: the hand-written C ABI gets no more feature work. The + generated C and C++ bindings get this from moq-ffi, and OBS reaches it + through [C++ through moq-ffi](/quest/m1/cpp/README.md); update `cpp/obs/src` + only if the plugin surfaces a token field. +- Interop: the Python, Go, and C++ interop clients print their grant and join the assertion [Interop grants](/quest/m1/auth/interop.md) adds for Rust and JS. - Wrappers: `py/moq-rs/moq/session.py`, `swift/Sources/Moq`, `kt/.../Flows.kt` (a `Flow` over `grant_changed`), `go/wrapper/moq/session.go` (context-cancellable like the rest), and `dart/moq/lib/moq.dart`. Kotlin typealiases pick up the raw methods for free; the flow is the idiomatic add. -- Docs: `doc/lib/{py,swift,kt,go,dart,c}` each gain a short auth section, and +- Docs: `doc/lib/{py,swift,kt,go,dart}` each gain a short auth section, and `doc/lib/rs` documents `Session::auth()`. - Tests: each wrapper's existing session test reads a grant from a local relay, adds a second token minted by `moq auth`, sees the union grow, and releases it; the refusal path surfaces the structured error in each language. -Additive. +Additive. Decided in the 2026-09-30 audit: libmoq is frozen, so the C +surface comes from moq-ffi rather than new `moq_session_auth_*` calls. ## Required diff --git a/quest/m1/auth/lite.md b/quest/m1/auth/lite.md index 6d54e56217e..2c5eb5add95 100644 --- a/quest/m1/auth/lite.md +++ b/quest/m1/auth/lite.md @@ -144,8 +144,3 @@ app-added token does not suspend the check; a reset AUTH stream reports cross-language harness. On main, additive. - -## Related - -- [Pattern interest](/quest/m1/path-patterns.md) - moves AUTH's grant - prefixes to patterns; ANNOUNCE_REQUEST stays a prefix diff --git a/quest/m1/auth/peer-grant.md b/quest/m1/auth/peer-grant.md index 7a839443d82..bdf539b257d 100644 --- a/quest/m1/auth/peer-grant.md +++ b/quest/m1/auth/peer-grant.md @@ -46,7 +46,7 @@ serves only the granted paths. A missing, expired, HMAC-signed, or unproven grant is not a grant. P2P is the first consumer: -[Signaling and policy](/quest/m1/p2p/signal.md) presents the grant in band +[Signaling and policy](/quest/m2/p2p/signal.md) presents the grant in band on each direct session. This quest does not depend on that line. Docs: `doc/bin/relay/auth.md` states that peer grants need an asymmetric @@ -66,4 +66,4 @@ Additive. ## Related -- [Signaling and policy](/quest/m1/p2p/signal.md) - the first consumer +- [Signaling and policy](/quest/m2/p2p/signal.md) - the first consumer diff --git a/quest/m1/auth/relay-refresh.md b/quest/m1/auth/relay-refresh.md index cff68ecc51a..65fa8ddc8b1 100644 --- a/quest/m1/auth/relay-refresh.md +++ b/quest/m1/auth/relay-refresh.md @@ -81,7 +81,6 @@ Additive. ## Required - [Origin narrowing](/quest/m1/auth/narrowing.md) - the live re-scope a shrinking token union needs, so no temporary close-on-shrink policy ships -- [Pattern interest](/quest/m1/path-patterns.md) - AUTH can represent the complete grants relay revalidation returns - [Lite stream](/quest/m1/auth/lite.md) - supplies the AUTH stream and `auth::Request` this consumes - [Unauthorized reset](/quest/m1/auth/unauthorized.md) - the code this diff --git a/quest/m1/auth/request-token.md b/quest/m1/auth/request-token.md index fa93750186c..f7336308975 100644 --- a/quest/m1/auth/request-token.md +++ b/quest/m1/auth/request-token.md @@ -11,8 +11,9 @@ does not cover it, by the token on the request; with neither it is refused `UNAUTHORIZED`. The token's grant covers only the request it rode on and lives exactly as long as that request, and a REQUEST_UPDATE carrying a new token replaces it, which is how a peer refreshes. It scopes by path, never -by method. Today the strict decoder on newer drafts fails the whole message -on the unknown key, and the legacy drafts silently ignore it. +by method. [Legal IETF input](/quest/m0/ietf-legal-input.md) decodes and +ignores the key first, so a token no longer fails the session; this quest +gives it meaning. ## Plan @@ -20,8 +21,9 @@ on the unknown key, and the legacy drafts silently ignore it. (`rs/moq-net/src/ietf/token.rs`, `js/net/src/ietf/token.ts`): `USE_VALUE` yields the token, `REGISTER` is a value since we advertise no `MAX_AUTH_TOKEN_CACHE_SIZE`, and `DELETE` or `USE_ALIAS` closes with `PROTOCOL_VIOLATION`. Both decoder families change: the strict - `decode_params!` path, which rejects the key today, and the generic KVP - path the legacy drafts use, which ignores it. + `decode_params!` path, which ignores the key after + [Legal IETF input](/quest/m0/ietf-legal-input.md), and the generic KVP + path the legacy drafts use, which also ignores it. - Fallback only: a request the session grant already covers is served without verifying its token. Otherwise its token becomes an `auth::Request` on the session's `auth::Handle`, the seam an AUTH stream's @@ -73,3 +75,7 @@ to) and on `moq_auth::Client` (the per-request lease). Wire: none new; the param - [Relay tokens](/quest/m1/auth/relay-refresh.md) - supplies the lease revalidation the per-request lease reuses + +## Related + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - also edits `decode_params!`; refresh this Plan when it lands, since the strict decoder then decodes and ignores the token diff --git a/quest/m1/auth/token-in-band.md b/quest/m1/auth/token-in-band.md index ccd2e32874f..574bf9c96c5 100644 --- a/quest/m1/auth/token-in-band.md +++ b/quest/m1/auth/token-in-band.md @@ -24,8 +24,11 @@ AUTH can carry the full grant once the pattern-interest prerequisite lands. the client makes. A `?jwt=` in the URL stays a member of the union, which is how cluster dial targets keep their per-peer credential, and per-dial extras use the session's `auth().add()` once connected. moq-ffi - `MoqClient::set_tokens`, moq-c `moq_client_set_tokens` (mirrored in the - wrappers and `cpp/obs/src`), and `js/net`'s `connect` options field follow. + `MoqClient::set_tokens` (mirrored in the wrappers, and reaching the + generated C and C++ bindings and OBS through + [C++ through moq-ffi](/quest/m1/cpp/README.md)) and `js/net`'s `connect` + options field follow. Decided in the 2026-09-30 audit: no new libmoq API, + since it gets no more feature work. - Credential refresh belongs with token presentation. Resolve the configured credential source before each dial. After an authorization refusal, resolve it once more and retry only when the credential changed; do not loop on a diff --git a/quest/m0/plan-av-clock.md b/quest/m1/av-clock.md similarity index 95% rename from quest/m0/plan-av-clock.md rename to quest/m1/av-clock.md index c82e3ff855c..fe19a250911 100644 --- a/quest/m0/plan-av-clock.md +++ b/quest/m1/av-clock.md @@ -11,6 +11,9 @@ the next re-anchor. ## Plan +Moved from m0 to m1 in the 2026-09-30 audit: it waits on the whole jitter +line and is a published `@moq/watch` break on dev, so it is not in flight. + Settled: per-track handles, and this quest lands them. `sync.track("audio")` and `sync.track("video")` each report their advertised delay and measured spread, and one is nominated as the clock source. `SyncInput` diff --git a/quest/m1/bbr-ack-cleanup.md b/quest/m1/bbr-ack-cleanup.md index 3439bf801ef..a0b9db7614b 100644 --- a/quest/m1/bbr-ack-cleanup.md +++ b/quest/m1/bbr-ack-cleanup.md @@ -10,10 +10,10 @@ behavior. ## Plan -The fix lives in moq-dev/noq. In released 1.3.1 (`ff9d2ab5`), -[`on_end_acks`](https://github.com/moq-dev/noq/blob/ff9d2ab518cfb155f9ebb9925f1c784665eac92a/noq-proto/src/congestion/bbr3/mod.rs#L1783) -runs `retain` over all tracked packets, then scans them again to mark stale -entries. Draining a flight with fixed-size ACK batches has quadratic total +The fix lives in moq-dev/noq. The baseline is the current releases: the +workspace pins moq-noq 1.3.2 and 2.0.0 is out. In both, `on_end_acks` +(`noq-proto/src/congestion/bbr3/mod.rs:1845`) runs `retain` over all tracked +packets, then scans them again to mark stale entries. Draining a flight with fixed-size ACK batches has quadratic total cleanup work. [Google QUICHE](https://github.com/google/quiche/blob/c961965aa3ee8f2b6f05ebcac794f7854101adcd/quiche/quic/core/congestion_control/bandwidth_sampler.cc#L377) uses packet-number lookup and obsolete-prefix reclamation; use that as a reference without copying a TCP or single-space assumption into QUIC. @@ -53,8 +53,12 @@ immutable fork release, and pin the corrected dependency chain here before completing this quest. Do not wait for the broader QUIC stack release. Update internal packet-lifetime comments inline; no new user guide is needed. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Related -- [Loss sampling](/quest/m1/quic/bbr-loss-parity.md) - preserve packet metadata needed by the separate loss-sample repair; both edit `bbr3/mod.rs`, so sequence them - [BBR starvation edges](/quest/m1/quic/bbr-app-limited-edges.md) - also edits `bbr3/mod.rs`; one owner there at a time - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - reusable measurement guidance, not a prerequisite for this fix +- [Loss sampling](/quest/m2/quic-bbr-loss-parity.md) - preserve packet metadata needed by the separate loss-sample repair; both edit `bbr3/mod.rs`, so sequence them diff --git a/quest/m1/bench-ci.md b/quest/m1/bench-ci.md index 4df11aa246b..79f0081e916 100644 --- a/quest/m1/bench-ci.md +++ b/quest/m1/bench-ci.md @@ -23,8 +23,8 @@ a GitHub App: - PR: one job builds base and head on the same runner and runs only the selected targets, saving and comparing Criterion baselines. Selection is the - changed crates plus their dependents, from the impact map that the - [tooling line](/quest/m1/tooling/README.md) lands. No selected bench + changed crates plus their dependents, from the impact map in + `sh/dispatch.sh`. No selected bench means no job. Extend `bench/run.sh` with a Criterion-only, crate-scoped mode behind a recipe instead of writing a second runner. Hosted runners vary by about 3%, so the comment highlights only changes Criterion calls @@ -43,11 +43,7 @@ a GitHub App: - Document the comment, the trend, and local reproduction in `bench/README.md`. -## Required - -- [Tooling](/quest/m1/tooling/README.md) - owns the diff-to-crate impact map the PR job reuses - ## Related - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - extends the same `bench/run.sh` with repeated paired rounds -- [Bench coverage](/quest/m1/bench-coverage.md) - more targets for this job to track +- [Bench coverage](/quest/m2/bench-coverage.md) - more targets for this job to track diff --git a/quest/m1/bench-coverage.md b/quest/m1/bench-coverage.md deleted file mode 100644 index 05d5b3077a3..00000000000 --- a/quest/m1/bench-coverage.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Benchmarks for containers, catalog, auth, and path matching - -## Goal - -Hot paths that have no benchmark get Criterion targets, so CI tracks them: -`moq-mux` container import and export per frame, `hang` catalog encode, decode, -and update, `moq-auth` token verification, and `moq-pattern` path matching. - -## Plan - -- `moq-mux`: fMP4/CMAF and Annex-B import and export over checked-in or - generated fixtures, with throughput in frames and bytes. Keep fixture - generation out of the timed region. -- `hang`: catalog encode and decode swept over rendition count, plus the - per-update cost a publisher pays. -- `moq-auth`: JWT verification per connection, swept over algorithm and claim - size. The in-band token path gets its bench with - [In-band token](/quest/m1/auth/token-in-band.md), not here. -- `moq-pattern`: matching swept over pattern count and path depth. Coordinate - with [Path patterns](/quest/m1/path-patterns.md) so the matcher gets one - bench, not two. - -Anything that fans out gets a sweep over both axes. Name each target after -what it measures, so the CI comment reads without opening the file. - -## Related - -- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - tracks these targets on PRs and nightly diff --git a/quest/m1/broadcast-epoch/README.md b/quest/m1/broadcast-epoch/README.md index f355ee25d31..3f8b69c8572 100644 --- a/quest/m1/broadcast-epoch/README.md +++ b/quest/m1/broadcast-epoch/README.md @@ -14,9 +14,10 @@ The epoch rides in the path, so it survives any moq-transport relay, and no wire message changes. At an epoch-aware relay, a request for a bare name resolves to its newest live epoch on every protocol version. -Non-goals: redundant publishers sharing one epoch, and failing over between -them faster than the keep-alive (the [redundant ingest](/quest/m2/redundant-ingest.md) -study). Also out of scope: trusting the publisher's clock (a far-future epoch +Non-goals: pooling redundant publishers that share one epoch, which +[Cluster routing](/quest/m1/cluster-routing/README.md)'s selection and +`--hop` removal own; this line only keeps an epoch a caller supplies. Also out +of scope: trusting the publisher's clock (a far-future epoch wins until its route goes away). ## Plan @@ -61,5 +62,6 @@ This README owns: - [Origin](/quest/m1/broadcast-epoch/origin.md) - moq-net publish mints an epoch, consumers follow the newest live one, and bare requests resolve to it on every version - [Apps](/quest/m1/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web publish under epochs and play bare names - [Gateways](/quest/m1/broadcast-epoch/gateways.md) - RTMP, SRT, and WHIP ingest mint an epoch per incoming connection, so an encoder reconnect is a clean takeover -- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi, moq-c, and every wrapper expose the epoch and inherit the default +- [TS restart](/quest/m1/broadcast-epoch/ts-restart.md) - on dev, a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch +- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and inherit the default - [GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md) - moqsink and the OBS plugin publish each run under a fresh epoch diff --git a/quest/m1/broadcast-epoch/bindings.md b/quest/m1/broadcast-epoch/bindings.md index 7db6c064677..e7bb2876fd4 100644 --- a/quest/m1/broadcast-epoch/bindings.md +++ b/quest/m1/broadcast-epoch/bindings.md @@ -2,8 +2,9 @@ ## Goal -`moq-ffi`, `moq-c`, and the py, swift, kt, go, and dart wrappers publish under -the default epoch and follow bare names like Rust. The epoch of a published or +`moq-ffi` and the py, swift, kt, go, and dart wrappers publish under the +default epoch and follow bare names like Rust. The generated C and C++ +bindings pick it up from moq-ffi; libmoq gets no new API. The epoch of a published or consumed broadcast is readable, and a caller can pass an explicit one. The reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. @@ -13,9 +14,12 @@ reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. argument. Keep the surface to what a binding consumer needs. - Rename `session.epoch()` in every binding (for example to `connects()`). That is a break, so it lands on `dev`. -- Update `doc/lib/{py,swift,kt,go,dart,c}` per the cross-package sync table, +- Update `doc/lib/{py,swift,kt,go,dart}` per the cross-package sync table, and run `just test smoke --all`. +Decided in the 2026-09-30 audit: libmoq is frozen (renamed `rs/moq-c` on +`dev`), so C and C++ consumers get epochs from moq-ffi. + ## Required - [Origin](/quest/m1/broadcast-epoch/origin.md) - the behavior the bindings surface diff --git a/quest/m1/broadcast-epoch/gateways.md b/quest/m1/broadcast-epoch/gateways.md index 89a3df5c853..0b0f059aa5b 100644 --- a/quest/m1/broadcast-epoch/gateways.md +++ b/quest/m1/broadcast-epoch/gateways.md @@ -17,3 +17,7 @@ describes ingest paths. ## Required - [Origin](/quest/m1/broadcast-epoch/origin.md) - the publish default + +## Related + +- [TS restart](/quest/m1/broadcast-epoch/ts-restart.md) - a signalled restart inside one connection, which this quest's per-connection epoch does not cover diff --git a/quest/m1/broadcast-epoch/gst-obs.md b/quest/m1/broadcast-epoch/gst-obs.md index c00cf203e31..35604ee5e4d 100644 --- a/quest/m1/broadcast-epoch/gst-obs.md +++ b/quest/m1/broadcast-epoch/gst-obs.md @@ -10,9 +10,11 @@ restarted pipeline or a stop and start in OBS is a clean takeover for viewers. `moqsink` takes the origin default per session. When [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) lands, each of its publication generations is a new epoch. OBS gets it -through moq-c. Update `doc/bin/gstreamer.md` and `doc/bin/obs.md` if they -show paths. +through the generated C++ bindings from moq-ffi (decided in the 2026-09-30 +audit: libmoq gets no new API). Update `doc/bin/gstreamer.md` and +`doc/bin/obs.md` if they show paths. ## Required -- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - OBS publishes through moq-c +- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi exposes epochs +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - OBS publishes through the generated C++ diff --git a/quest/m1/broadcast-epoch/origin.md b/quest/m1/broadcast-epoch/origin.md index 1e065f18acd..0c02eab0ba0 100644 --- a/quest/m1/broadcast-epoch/origin.md +++ b/quest/m1/broadcast-epoch/origin.md @@ -32,6 +32,9 @@ any wire change. exclusion and the per-path fronts from #3312 stay intact. - Benchmark resolution swept over epochs per name and names per origin, so following does not scan the table. +- Open: does a catalog `broadcast` reference by bare name pin the epoch its + catalog came from, or follow the newest? Settle it with + [Catalog track alias](/quest/m1/catalog-track-alias.md). - Update `doc/concept` and `drafts/draft-lcurley-moq-lite.md` wherever they describe resolution or takeover. The rule is a relay behavior, so state it in the draft even though no field changes. @@ -43,4 +46,6 @@ Wire: none. ## Related +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - cross-broadcast catalog references, which must pick an epoch + - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - a new epoch starts each track at sequence 0 diff --git a/quest/m1/broadcast-epoch/ts-restart.md b/quest/m1/broadcast-epoch/ts-restart.md new file mode 100644 index 00000000000..2e438ff31b6 --- /dev/null +++ b/quest/m1/broadcast-epoch/ts-restart.md @@ -0,0 +1,52 @@ +# [M] A signalled TS restart continues as a new epoch + +## Goal + +On dev, when a TS feed rewinds its time base and signals it +(`discontinuity_indicator` on the PCR PID, ISO/IEC 13818-1 2.4.3.5), +`moq import ts` and `moq-srt` finish the current broadcast cleanly and publish +the rest of the same input as a new broadcast under a fresh epoch, in the same +process and connection. This covers an encoder restart or source switch behind +a gateway that keeps its connection up, and a looping playout server, none of +which makes a new connection for [Gateways](/quest/m1/broadcast-epoch/gateways.md) +to turn into an epoch. An unsignalled rewind stays fatal, as #4543 decided. + +## Plan + +Since #4543 (on dev), every rewind ends the import with `TimestampRewind` from +`Producer::write`; the importer already reads the flag in `timebase_break`, +and a flagged forward jump publishes break markers and carries on. + +Decided (maintainer, 2026-09-30): + +- A rewind is new content, so it is always a new broadcast at a new epoch + path, never a continuation of the old name. Viewers of the bare name follow + it through [Origin](/quest/m1/broadcast-epoch/origin.md). +- `decode` stops at the flagged rewind and reports it. The caller finishes the + old broadcast (a clean end, not an abort, so its viewers read to its end), + publishes a new broadcast at a fresh epoch path, and calls + `import.restart(broadcast)`. The importer carries over only the PAT/PMT + layout and the bytes it has not consumed, so there is no wait for the next + PSI repetition; tracks, groups, and timestamps start fresh. `ts::Programs` + does this per program. Returning unconsumed bytes to a fresh `Import` was + rejected for the PSI wait, and letting the importer publish its own + broadcast was rejected for coupling moq-mux to origin publishing. +- A flag with the next PCR behind the last one is a restart; a flag with a + forward jump stays a break marker. The 33-bit wrap is modular, not a rewind. +- Callers: `moq import ts` (`rs/moq-cli`) and `moq-srt`'s `Publisher`, single + program and `Program::All`. + +Tests: a fixture with a flagged rewind publishes two broadcasts, the second +starting at the rewound PTS; the same rewind unflagged still errors; one SRT +connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`. + +Public API: breaking in moq-mux on dev, `ts::Import::decode` reports a restart +and `restart` is new. Wire: none. + +## Required + +- [Origin](/quest/m1/broadcast-epoch/origin.md) - the fresh epoch path the rest of the feed publishes under + +## Closes + +- [#4582](https://github.com/moq-dev/moq/issues/4582) - a signalled backward TS discontinuity ends the import diff --git a/quest/m1/browser-close-code.md b/quest/m1/browser-close-code.md new file mode 100644 index 00000000000..95df47c7672 --- /dev/null +++ b/quest/m1/browser-close-code.md @@ -0,0 +1,35 @@ +# [M] A browser sees the close code on every WebTransport backend + +## Goal + +A browser interop case proves a relay's rejection reaches the page: the relay +closes the session with an application code and reason, and the page reads +both from `WebTransport.closed`. Every `moq-dev/web-transport` backend that +speaks WebTransport (noq, quinn, iroh) delivers the close capsule, verified by +that case or an equivalent test, and any that doesn't is fixed upstream. + +## Plan + +[WebTransport close upstream](/quest/m1/wt-close-upstream.md) fixed +`web-transport-moq`'s close path with a Rust regression test, but only +Chromium treats the H3 control stream ending early as fatal, so no Rust peer +proves the browser path. The playwright interop harness in `test/interop/` +has no close-code scenario yet. + +- Add the browser case: a relay (or `Request::reject`) closes with a code, and + the page asserts the code and reason. It should fail with the capsule fix + reverted. +- Audit `web-transport-noq`, `-quinn`, and `-iroh` for the same bug: a close + capsule sent from a task that doesn't keep the H3 control streams alive. + `web-transport-iroh` 0.7 sends no capsule at all, only a QUIC close; decide + there whether iroh's WebTransport path should send one. +- Fix upstream, release, and bump the pins, once wt-close finishes. + +Decided with the maintainer: the browser case and the backend audit ship +together, since the case is what proves each backend. + +Public API: none. Wire: none, unless iroh starts sending the capsule. + +## Required + +- [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - the noq fix and pin bump the browser case needs diff --git a/quest/m1/cache-expiry-growth.md b/quest/m1/cache-expiry-growth.md index 0aafd2b2c1f..7bbe215a52c 100644 --- a/quest/m1/cache-expiry-growth.md +++ b/quest/m1/cache-expiry-growth.md @@ -27,7 +27,3 @@ Otherwise reproduce with a focused test. Unexpired groups at higher throughput, expiry not running on some path, or groups held outside the pool's accounting would each explain it. Fix what is actually wrong. Consider whether an unbounded default is the right default for an origin at all. - -## Related - -- [Relay memory](/quest/m1/relay-memory.md) - what an announcement costs in memory diff --git a/quest/m1/cache-wall-eviction.md b/quest/m1/cache-wall-eviction.md index 083a2857e52..7643c0075e4 100644 --- a/quest/m1/cache-wall-eviction.md +++ b/quest/m1/cache-wall-eviction.md @@ -42,4 +42,4 @@ Public API: none from the plan. Wire: none. ## Related - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - relay memory past the expiry window, in the same cache -- [Cache shard](/quest/m1/perf/cache-shard.md) - the pool's shared counters under many workers +- [Cache shard](/quest/m2/cache-shard.md) - the pool's shared counters under many workers diff --git a/quest/m1/capture-default.md b/quest/m1/capture-default.md new file mode 100644 index 00000000000..d27fde791eb --- /dev/null +++ b/quest/m1/capture-default.md @@ -0,0 +1,37 @@ +# [S] Capture is a default feature + +## Goal + +`capture` is on by default in moq-video and moq-audio, so the pre-merge +`just check` compiles and tests device capture like any other default code, +and the separate capture CI gate goes away. The flag stays so a minimal build +can opt out. Workspace consumers that set `default-features = false` (the +relay, the language bindings) keep building without it. + +## Plan + +Decided in planning (09-29), after capture-control (#4545) found that +pre-merge `just check` never runs moq-video's `capture` tests: + +- **Default-on, keep the flag.** Removing the flag was rejected: consumers + that don't want device stacks would pay for them. +- moq-video's `capture` already costs nothing to build on any platform. Its + Cargo comment says it stays off only "until every distribution ships it", a + packaging concern this reverses. +- moq-audio's `capture` links libasound when it builds on Linux, which is why + it depends on [ALSA link](/quest/m1/capture-alsa-link.md). Once libasound + loads at runtime, the default costs no system library. +- Delete the special capture gate (`rs capture`, `capture-test`, and the + capture branch in `sh/rs/select.sh`) once default + `just check` covers it. Keep the platform jobs (`just rs macos`, + `just rs windows`). +- Update the Cargo feature comments, moq-cli's `capture` feature (it may + become redundant), and `doc/` wherever capture is described as opt-in. + +Verify: `just check` on a moq-video or moq-audio change runs the capture +tests, and a `default-features = false` consumer (for example +`cargo tree -p moq-ffi -e features`) pulls no capture dependency. + +## Required + +- [ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture can't be on by default while it links libasound at build time diff --git a/quest/m1/catalog-estimate-rate.md b/quest/m1/catalog-estimate-rate.md new file mode 100644 index 00000000000..3aa26cf7fcb --- /dev/null +++ b/quest/m1/catalog-estimate-rate.md @@ -0,0 +1,44 @@ +# [S] A rising catalog estimate republishes at most once a second + +## Goal + +A publisher whose `jitter` or `delay` estimate keeps rising under load stops +republishing the catalog on every 1 ms step. Estimate-driven republishes are +rate-limited to one per second in `js/publish` and `moq-mux`: the first rise +publishes at once, and later rises inside the window coalesce into one publish +at the window's end carrying the latest value. Track additions, removals, and +config changes still publish immediately. + +## Plan + +Found in [#4529](https://github.com/moq-dev/moq/pull/4529): under load, the +lifetime-maximum `Estimator` (`js/publish/src/jitter.ts`, mirroring +`moq_mux::catalog::Estimator`) rises 1 ms at a time and each rise republishes +the catalog, which makes every player send a subscribe update on every track. + +Decided with the maintainer: + +- Rate limit, not quantization, so the advertised value stays exact. +- Leading and trailing edge, 1 s window: a first estimate arrives without + delay and the catalog never trails the estimate by more than a window. +- Estimate-driven changes only; a structural catalog change never waits. +- Keep the draft's never-lower rule. #4529 also saw an estimate grow to about + 586 ms on an overloaded machine, so resuming refilled that whole delay. That + is the rule working as written ("a burst it emitted once it may emit + again"), not a bug for this quest. + +A pending trailing publish folds into any structural publish that happens +first. Unit tests drive the window on a mocked clock in both languages. + +The churn fans out (every rise reaches every subscriber on every track), so +add a benchmark swept over tracks x subscribers that drives a rising estimate +and counts catalog publishes and subscribe updates. It shows the saving now and +catches a regression later as a slope. `moq-mux` has no benches yet; add one +there or extend `rs/moq-net/benches/session.rs`. + +Public API: none expected. Wire: none; catalog contents are unchanged, only +how often they are sent. + +## Related + +- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the player-side target the advertised jitter floors diff --git a/quest/m1/catalog-omit-empty.md b/quest/m1/catalog-omit-empty.md new file mode 100644 index 00000000000..93818c6114b --- /dev/null +++ b/quest/m1/catalog-omit-empty.md @@ -0,0 +1,23 @@ +# [XS] The hang catalog omits empty video and audio sections + +## Goal + +A Rust-published hang catalog with no video or audio renditions leaves out the +`video` or `audio` key, as the JS publisher already does, instead of writing +`"video":{"renditions":{}},"audio":{"renditions":{}}`. + +## Plan + +Requested by an external consumer (OneTooMany, Discord): data-only broadcasts +fill logs with misleading empty sections. + +Give `Video` and `Audio` an `is_empty` (no renditions), as `Text` has, and add +`skip_serializing_if` on `video` and `audio` in +`rs/hang/src/catalog/root.rs`, like `text`/`json`/`binary`, and update the +tests that pin the empty output (`root.rs` and +`rs/moq-mux/src/catalog/hang/ext.rs`). + +Wire-compatible, so it lands on `main`: Rust already defaults an absent +section on read, and `@moq/hang` has accepted an absent one since #401 +(2025-06). The draft already marks both optional; decided to leave its wording +unchanged. diff --git a/quest/m1/catalog-track-alias.md b/quest/m1/catalog-track-alias.md new file mode 100644 index 00000000000..d2abff6177c --- /dev/null +++ b/quest/m1/catalog-track-alias.md @@ -0,0 +1,52 @@ +# [M] hang catalog rendition keys are aliases + +## Goal + +A hang catalog's video and audio rendition keys are aliases, unique within +the catalog, rather than wire track names. A rendition config gains an +optional `track`, the wire track name, beside its existing `broadcast`; +absent, the track name is the alias, so every catalog published today parses +and plays unchanged. One catalog can then list renditions from several +broadcasts that share a track name. + +## Plan + +Decided (2026-09-29) while planning [media stats](/quest/m1/stats/README.md), +which keys its snapshots by this alias: without it, a catalog referencing two +broadcasts that both publish `video` cannot list both, and a snapshot keyed by +track name would collapse them. + +- The field is `track`, beside `broadcast` on `VideoConfig` and `AudioConfig` + in `rs/hang` and their zod schemas in `js/hang`. Additive on main: an + optional field on `#[non_exhaustive]` types. +- Every reader that subscribes by the map key resolves the wire name through + one helper instead, in Rust and JS, so no path keeps assuming key equals + name. Publishers keep writing no `track` unless they need it. +- Open: a released reader ignores `track` and subscribes by the key, so it + cannot play a rendition whose `track` differs from its alias. Candidates: + accept that, since such a listing was not expressible before and a + publisher sets `track` only when it must; or move the reader change to + `dev` behind a catalog version. The maintainer settled it as additive on + main; confirm the forward-compatibility cost before starting. +- The MSF conversion in `rs/moq-mux` names MSF tracks by the key today. + It carries the wire name and keeps the alias through a round-trip test, or + refuses a catalog whose `track` differs from its alias. +- Scope: `rs/hang`, `js/hang`, their readers, `drafts/draft-lcurley-moq-hang.md` + (validate with `just drafts check`), and `doc/concept/hang.md`. +- Tests: an old catalog resolves each track name to its key; a catalog with + two renditions naming the same `track` in different broadcasts round-trips + in both languages and plays each. +- Open: text, JSON, and binary sections also carry `broadcast` and key by + track name. Candidates: keep this to video and audio, as decided, or give + every section with `broadcast` a `track` through the same helper so + resolution is uniform. +- Open: video and audio are separate maps, so one key can appear in both. + Within one broadcast that already means one track for two kinds, but with + `broadcast` references it parses today. Candidates: refuse a cross-kind + duplicate (a validation tightening on main), or accept it and kind-qualify + the stats and echo keys. + +## Related + +- [Media stats](/quest/m1/stats/README.md) - keys stats and feedback by this + alias diff --git a/quest/m1/catalog-wall-clock.md b/quest/m1/catalog-wall-clock.md deleted file mode 100644 index 1b25deeeef9..00000000000 --- a/quest/m1/catalog-wall-clock.md +++ /dev/null @@ -1,28 +0,0 @@ -# [XS] Catalog wall clock keeps sub-millisecond precision - -## Goal - -`hang::catalog::Clock::wall_clock` returns the wall time at the precision the -catalog carries, not truncated to milliseconds. The wire field is `{ wall, -timescale }` with a `u32` timescale defaulting to microseconds, and `pts` -arrives at its own timescale, but `wall_clock` divides down to Unix -milliseconds before building the `SystemTime`, which holds nanoseconds. The -capture clock fixtures from [#4125](https://github.com/moq-dev/moq/pull/4125) -assert at millisecond precision because of it. - -## Plan - -- Rust: compute the offset from the moq epoch in nanoseconds (or as a - `Duration` from whole seconds plus the remainder at the clock's timescale) - and add it to `UNIX_EPOCH + MOQ_EPOCH_UNIX_MILLIS`. Keep the existing - overflow and JSON-safe range checks. Tighten the fixtures that currently - assert milliseconds. -- JS: `wallClockTime` in `js/hang/src/catalog/clock.ts` returns a `Date`, - which only holds milliseconds. Leave its return type alone unless a caller - needs more; note the platform limit in its doc so the two sides are not - mistaken for a mismatch. -- Callers that format the value (HLS `EXT-X-PROGRAM-DATE-TIME`, DASH - `availabilityStartTime`) choose their own output precision; check none - relied on the truncation. - -Public API and wire: none. diff --git a/quest/m1/ci-hygiene.md b/quest/m1/ci-hygiene.md deleted file mode 100644 index b535f60eb56..00000000000 --- a/quest/m1/ci-hygiene.md +++ /dev/null @@ -1,25 +0,0 @@ -# [XS] CI runs don't cancel each other or cache a broken build - -## Goal - -A push to one PR never cancels another PR's run, and a failed run never -saves the Rust cache later runs restore. - -## Plan - -- Concurrency: `check.yml`, `obs.yml`, `android.yml`, `wasm.yml`, and - `interop.yml` group by `${{ github.ref }}` only. Key them by event and PR - number the way `platform.yml` does (#4370). A `pull_request` run's - `github.ref` is already `refs/pull//merge`, so first find which runs - actually shared a group, and confirm the new key separates them. -- Cache: `interop.yml` and `swift.yml` set Swatinem's - `cache-on-failure: true`; #4384's interop cache got saved broken that way - (`failed to run custom build command for aws-lc-rs`). Drop it. Check - whether the shared `.github/actions/rust-cache` saves on failure, and make - it save only on success. - -Public API: none. Wire: none. - -## Related - -- [Merge queue](/quest/m1/merge-queue.md) - also touches the concurrency groups for queue refs diff --git a/quest/m1/ci-runner-stalls.md b/quest/m1/ci-runner-stalls.md new file mode 100644 index 00000000000..ae944c35bfe --- /dev/null +++ b/quest/m1/ci-runner-stalls.md @@ -0,0 +1,28 @@ +# [S] Interop freezes on CI runners are attributed + +## Goal + +The 0.4 to 0.8 s freezes where both interop tracks stop at once on CI are +attributed to the runner, the relay, or the player, with evidence from the +nightly traces. A cause in our code is fixed at its source; a runner stall is +documented, and the interop checks tell it apart from a playback bug instead +of failing on it as one. + +## Plan + +Found in [#4529](https://github.com/moq-dev/moq/pull/4529) while chasing the +cold-start tone check: some CI traces show both tracks freezing together, +which that fix shortens but cannot remove. #4529 added the player's `delay` to +the interop trace, so a week of nightlies after it lands shows the freezes +without the delay-flush noise that hid them. + +Collect the failing and passing nightly interop traces for that week, line up +each freeze against relay and player timestamps, and look for what the +runner was doing (CPU steal, GC, disk). Decided with the maintainer: diagnose +first from real nightlies rather than assume a runner stall. + +Public API: none. Wire: none. + +## Required + +- A week of nightly interop runs on `main` after #4529, which adds the `delay` column these traces need diff --git a/quest/m1/cli-packaging.md b/quest/m1/cli-packaging.md index 730b83b3bcc..33a48b9b306 100644 --- a/quest/m1/cli-packaging.md +++ b/quest/m1/cli-packaging.md @@ -30,6 +30,20 @@ than at run. Then verify the shipped artifact runs `moq devices` and `moq play` on each platform, since a feature that compiles into the binary and then fails to open a device is the same gap one layer down. +Also enable `v4l2` in the Linux ARM release build, so a released binary on a +Raspberry Pi 4 publishes from `moq import capture` through the V4L2 M2M +hardware encoder (`rs/moq-video/src/v4l2.rs`, already run on a Pi 4's +`bcm2835-codec`) with no GStreamer detour. Verify that once on a Pi 4. + +Add a board hardware note to `doc/bin/cli.md` next to the capture build +instructions: Raspberry Pi 5 has no video encoder and Jetson Orin Nano ships +without NVENC; Pi 4, CM4, Zero 2 W, and Orin NX and above encode. RK3588 +encodes through rkmpp in a vendor kernel, not V4L2, so it stays on the +`moq-gst` route. + +Decided in the 2026-09-30 audit: the v4l2 encode quest folded in here, since +its remaining work was one release feature flag and a doc note. + ## Required - [Audio capture without runtime system libraries](/quest/m1/capture-alsa-link.md) - the microphone path must start without system audio libraries before every distribution can ship it diff --git a/quest/m1/cli-serve.md b/quest/m1/cli-serve.md index 9456879ca9f..298cd2a3f67 100644 --- a/quest/m1/cli-serve.md +++ b/quest/m1/cli-serve.md @@ -30,6 +30,11 @@ relay. configured; the unauthenticated import-to-export smoke keeps passing with `--auth-public`. -## Required +Decided in the 2026-09-30 audit: no longer waits on +[`moq relay`](/quest/m2/moq-relay-subcommand.md). `moq-cli` already depends +on `moq-relay`, and the open-relay listener is a security gap that should not +wait on an m2 subcommand. -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - the CLI hosts the relay library, which `serve` comes from +## Related + +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the CLI later hosts the whole relay diff --git a/quest/m1/clock-anchor-public.md b/quest/m1/clock-anchor-public.md new file mode 100644 index 00000000000..d491aa60981 --- /dev/null +++ b/quest/m1/clock-anchor-public.md @@ -0,0 +1,29 @@ +# [S] moq-mux exports the per-source clock anchor + +## Goal + +An application running its own demuxer puts several tracks of one source on +the broadcast `Clock` with one shared offset, as the built-in TS, fMP4, and +FLV importers do, without going through a built-in importer. + +## Plan + +Requested by an external consumer (OneTooMany, Discord): their MPEG-TS +ingest publishes video, KLV, and sometimes audio from one program. One +`SourceMap` per track lets tracks drift apart by their first-PTS difference, +and one shared `SourceMap` reads interleave (beyond `MAX_REORDER`) as a reset. + +Decided: make `clock::Anchor` and `clock::Lane` public with the API the +importers already use: `Anchor::new(clock)`, `translate(&mut lane, pts)`, +`translate_at`, `extend`, and `Lane::restart`, with `Lane: Default`. Additive, +so it lands on `main` for a 0.10 patch. + +Open for the PR: the export path. Proposal: `pub mod clock` with +`moq_mux::clock::{Anchor, Lane}`, keeping the root `Clock` re-export. Ask the +maintainer with alternatives. + +Document both in `doc/lib/rs/moq-mux.md`, with a two-track example. + +Their other `ts::Import` gaps (MPEG-2 video, KLV reassembly) stay unplanned +until requested directly. The H.265 per-packet error is +[TS damaged units](/quest/m1/ts-damaged-units.md). diff --git a/quest/m1/close-tail.md b/quest/m1/close-tail.md new file mode 100644 index 00000000000..1c1e75dfb9d --- /dev/null +++ b/quest/m1/close-tail.md @@ -0,0 +1,69 @@ +# [M] A graceful close waits for the subscriber to read the tail + +## Goal + +When `Session::close()` returns `Ok` on moq-lite-07, every subscriber has read +each finished track to its end: every frame of the final group, then a clean +end. Today close counts a group delivered once the peer's QUIC stack acks it, +then sends `CONNECTION_CLOSE`, and a real QUIC stack discards stream data the +subscriber's moq-net has not read yet. The subscriber loses the final group and +sees `Session(Cancel)`, while the publisher is told the close succeeded. + +## Plan + +Root cause: a lite serve decrements the publisher's `owed` count once its +group streams and Subscribe Stream FIN are acked (`poll_close` in +`rs/moq-net/src/lite/publisher.rs`), and `Publisher::drained()` reads only that +count. `poll_drain` in `rs/moq-net/src/session.rs` then closes the session with +`Cancel`. The lost final group is unread data the subscriber's QUIC stack +discards on `CONNECTION_CLOSE`; the subscriber's abort then ends the track with +that group still open. `tests/session_close.rs` passes only because the mock +transport keeps unread data after close. + +Decided (maintainer, 2026-09-30): + +- The fix is a FIN handshake, per subscription. On lite-07 the subscriber FINs + its side of the Subscribe Stream once its tail accounting settles the track's + end, never earlier: every group below the end has been read to its FIN, + reset, or dropped. Today that accounting is SUBSCRIBE_END's `Stream Count`; + once [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) lands it is a received + group or a SUBSCRIBE_DROP per sequence. The FIN rule rides on whichever is in + place, so neither quest waits on the other. The publisher's + drain waits until each served Subscribe Stream is closed both ways (the + subscriber's FIN or a reset), under the same `CLOSE_TIMEOUT`, before + `CONNECTION_CLOSE`. A session-level GOAWAY handshake was rejected: the peer + would need the same per-subscription knowledge to know when to close. +- lite-07 only, since it is still wip and the draft can require the + subscriber FIN there. On lite-05 and lite-06 an old subscriber never FINs, + so close keeps today's ack-based drain rather than time out every close. + #4508's repro is on lite-05, and that path stays as it is: this quest closes + the issue by fixing the close on the version that can carry the FIN rule. + IETF sessions stay with [IETF drain before close](/quest/m1/ietf-drain-before-close.md). +- Both subscribers change: moq-net and `@moq/net`. + +Update `drafts/draft-lcurley-moq-lite.md` (the Subscribe section gains the +subscriber FIN rule, with a changelog entry) and `doc/concept/moq-lite.md` +(a subscription ends with both sides' FIN, and a graceful close waits for it). Check that a lite-07 publisher +already treats a subscriber FIN after SUBSCRIBE_END as the end of a finished +subscription, not a cancel of one still in flight +([Request stream cancel](/quest/m1/request-stream-serve.md)). + +Tests: the reporter's `close_tail` case (one session, paused clock, a mock +switch that acks a FIN as soon as it is sent, as a real transport does) fails +today and passes with the fix; a subscriber that never FINs makes close return +`Error::Timeout`; a final range with a skipped and a reset group still settles +and FINs. Run `just test interop --all`, since both the Rust and JS subscribers change; +[Track tail interop](/quest/m1/track-tail-interop.md) is the cross-language +proof over a real relay. + +Public API: none. Wire: on lite-07 a subscriber FINs its Subscribe Stream +after reading the track's end, and a publisher closing gracefully waits for it. + +## Closes + +- [#4508](https://github.com/moq-dev/moq/issues/4508) - `close()` returns `Ok` while the subscriber gets a cut track + +## Related + +- [IETF drain before close](/quest/m1/ietf-drain-before-close.md) - the same drain for moq-transport sessions +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - replaces the lite-07 tail accounting the FIN rule waits on diff --git a/quest/m1/cluster-idle-timeout.md b/quest/m1/cluster-idle-timeout.md new file mode 100644 index 00000000000..5bbf7d739b8 --- /dev/null +++ b/quest/m1/cluster-idle-timeout.md @@ -0,0 +1,29 @@ +# [S] Cluster idle timeout + +## Goal + +A relay notices a silent peer relay within seconds, not after the 30 s QUIC +idle timeout it shares with every viewer. moq.pro's routing simulator found +that failure detection, not routing, sets every outage window: a silent link +or relay loss goes unnoticed for the idle timeout in every routing design, +and subscribes through it go nowhere meanwhile. + +## Plan + +- Cluster sessions get their own idle timeout and keep-alive, shorter than + the `--quic-*` defaults (`rs/moq-tokio/src/quic.rs`, 30 s idle and 5 s + keep-alive). A keep-alive alone only keeps a quiet session open; the + timeout is what detects loss. +- QUIC's effective idle timeout is the smaller of the two endpoints' + (RFC 9000 section 10.1), so the dialing relay's setting bounds both sides of + a cluster link. Say so where the setting is documented. +- Pick the default in the PR with its reasoning: loss detection against + spurious drops on a lossy intercontinental link. +- Docs: `doc/bin/relay/cluster.md` and `doc/bin/relay/config.md`. + +Public API: adds a relay config field; lands on `main`. + +## Related + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - its liveness and failover depend on this detection +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - viewers wait out the same timeout for an old route diff --git a/quest/m1/cluster-publisher-in-place.md b/quest/m1/cluster-publisher-in-place.md deleted file mode 100644 index 1b46dacb42a..00000000000 --- a/quest/m1/cluster-publisher-in-place.md +++ /dev/null @@ -1,89 +0,0 @@ -# [M] A publisher change updates a cluster advertisement in place - -## Goal - -Under the IETF cluster extension, an advertisement whose original publisher -(first HOP_PATH entry) changes is updated in place, like any other change, -instead of withdrawn and advertised again. A subscriber never sees a -namespace briefly vanish because its publisher moved. Subscriptions already -served from the old publisher drain it until it ends; new requests take the -updated route; nothing is resumed or spliced across two publishers. - -## Plan - -Decided 2026-09-28: match moq-lite. A route's first hop is its identity: -routes update in place, and across differing first hops a relay must not -splice a live subscription. The cluster draft instead requires -PUBLISH_NAMESPACE_DONE or NAMESPACE_DONE and a fresh advertisement, using the -withdraw to force that discontinuity. The maintainer prefers updating over -quickly toggling a namespace. - -Decided 2026-09-29 by the maintainer: a first-hop update does not end -subscriptions already served from the old publisher. In-flight tracks keep -draining the old copy until it ends on its own, and new requests take the -updated route. This replaces the earlier same-day decision to end them and -fail over to another route from the old publisher. Why: the lite draft -already leaves in-flight subscriptions "undisturbed" by ANNOUNCE_UPDATE, the -cluster draft already forbids tearing down subscriptions because an update -arrived, and Rust already drains: a front pinned to `Pin::Publisher` stops -qualifying once its route's first hop changes (`qualifies` in -`rs/moq-net/src/model/origin.rs`), and `selected(None)` in `front.rs` ends -it, which stops new requests while its live copies play out. Draining needs -no abort plumbing and no draft narrowing. - -Decided 2026-09-29: accept the compatibility break. Released moq-net (0.3.5 -and later) refuses a first-hop REQUEST_UPDATE with a retry interval of 0, -which leaves a moved publisher withdrawn on that session during a rolling -upgrade. Only this tree's relays speak the cluster extension, so there is no -withdraw fallback and no negotiation. - -- `drafts/draft-lcurley-moq-cluster.md` (Updating an Advertisement, and the - "moves to another MUST withdraw" line under Several Publishers): a - publisher change is sent as an ordinary update (REQUEST_UPDATE, or a - re-sent NAMESPACE). A receiver that sees the first entry change keeps - in-flight subscriptions on the old source until it ends, serves new - requests from the updated route, and MUST NOT resume or splice a - subscription onto it. Add a changelog entry, and run `just drafts check`. -- Rust `rs/moq-net/src/ietf/publisher.rs` (`sync_namespace`): the - PUBLISH_NAMESPACE path stops withdrawing on a first-hop change; the inline - path already updates in place. -- Receivers in both languages accept a first-hop change in place instead of - refusing it: `run_publish_namespace_updates` in - `rs/moq-net/src/ietf/subscriber.rs` and `runPublishNamespace` in - `js/net/src/ietf/subscriber.ts` close the stream today. -- Rust model: an anonymous front (first hop 0) is pinned to its route - (`Pin::Route`), so it keeps taking new requests when that route's first hop - changes to a named publisher, pairing the old broadcast's cached track - metadata with the new publisher. End it on a first-hop change like a named - front, so its copies drain and new requests get a fresh front. -- JS lite `js/net/src/lite/subscriber.ts`: a different first hop calls - `retract()` and announces again, so a forwarding relay withdraws the - namespace. Emit an in-place update instead. In-flight subscriptions drain - the old copy, and new requests neither reuse the old publisher's cached - track info nor splice onto a live subscription, matching Rust. -- JS sender `js/net/src/ietf/publisher.ts` (`runPublishNamespaces`): once - JS IETF reprice gives it in-place updates, a first-hop change uses them too - instead of withdrawing. -- Docs: `doc/bin/relay/cluster.md`, and any `doc/concept` page that - describes the cluster extension, say a publisher change updates in place, - in-flight subscriptions drain the old publisher, and new requests take the - new one. -- Tests in both languages: a first-hop change sends one update and no - withdrawal; the receiver applies it without closing the stream; an - in-flight subscription keeps receiving the old publisher's groups until - that copy ends and never receives a group from the new one; a request - after the update resolves through the new publisher without the old - publisher's track info. Cover an anonymous (hop 0) to named change, and a - lite ANNOUNCE_UPDATE in JS. Run `just test interop --all`. - -Public API: none. Wire: the cluster extension's update semantics change (no -message or parameter changes), breaking first-hop updates toward released -relays as decided above. - -## Required - -- [JS IETF reprice](/quest/m1/js-ietf-reprice.md) - the JS IETF publisher updates a held namespace in place, which a first-hop change then reuses - -## Related - -- [Cluster routing](/quest/m1/cluster-routing.md) - the routing plan these advertisements feed diff --git a/quest/m1/cluster-routing.md b/quest/m1/cluster-routing.md deleted file mode 100644 index 35dd9c22f19..00000000000 --- a/quest/m1/cluster-routing.md +++ /dev/null @@ -1,209 +0,0 @@ -# [XL] Cluster routing - -## Goal - -A broadcast event reaches each relay at most once, and a relay learns only the -prefixes its own clients asked for. An announcement says a path exists at an -origin relay, at a cost; how to reach that origin comes from a shared relay -topology, so no announcement inside a cluster carries a hop list. This quest -records the design; its wire and implementation quests are planned from the -simulator's report. - -Non-goals: warm re-origination (a warm relay would be one more origin with a -cost, so leave room for it), and a permanently mixed-version cluster. - -## Plan - -### Why not path vector or Babel - -Today every relay advertises its best route to every peer not already in the -hop chain. One publish costs about R·(d-1) announces for R relays of mesh -degree d, every relay learns every broadcast (`.stats` and `.internal` -included), and a link change rewrites every route crossing it. On moq.pro's -live fleet (26 PoPs, average degree about 5) each relay receives every event -about five times. Babel ([RFC 8966](https://www.rfc-editor.org/rfc/rfc8966)) -shrinks the message and skips equal-cost reroutes, but it is still distance -vector: the same fan-out, the same global knowledge, and no loop freedom -when several sources claim a prefix (section 2.7), which pools and wildcards -make MoQ's common case. - -moq.pro's routing simulator (`just rs sim`, -[moq.pro#2020](https://github.com/moq-dev/moq.pro/pull/2020)) measured worse -than that on live's relay graph (34 relays, mean degree 8.4): a publish costs -about 750 announces, and ending a path's only publisher explores stale -alternatives for about a second and 39k to 80k announces, with subscribes -looping meanwhile. Coalescing each writer for 10 ms cuts that by 7x and leaves -the loops. Hiding the routes through a peer that withdrew the path -([#4399](https://github.com/moq-dev/moq/pull/4399)) reduces that path hunting -but does not end it; see the findings below. - -### Decisions - -- Existence is split from reachability. An announcement carries the path, its - origin relay, and the origin's cost, and nothing about the path to it. -- An existence event carries the origin's seqno, scoped to its incarnation. A - relay applies an event only when it is newer than the last it applied for - that path and origin, and keeps an ended path's seqno, so a start delayed on - a stale tree or a failed-over registry cannot revive it. Babel keeps - feasibility past withdrawal for the same reason - ([RFC 8966 section 3.7.3](https://www.rfc-editor.org/rfc/rfc8966#section-3.7.3)). -- A new incarnation is learned from existence, never inferred from liveness: - it announces a reset (its incarnation at seqno 0) that ends everything the - old one published, and a relay applies a reset and the records after it as - one batch. Incarnations are ordered, so a delayed reset from an older one is - dropped. Purging on a liveness report instead drops a restarted origin's - broadcasts until their re-announce lands, which the simulator showed as live - broadcasts reported offline. -- The topology is configured: `--cluster-connect` or the connect API gives the - relay graph and link costs. Relays flood per-link liveness among themselves - with a per-link seqno. The seqno is scoped to the relay's incarnation, so a - restarted relay's links supersede its stale ones instead of looking older. - Gossip discovery (`cluster.mesh`) stays for zero-config self-hosting and - derives the topology from what it discovers; it need not scale. - - A relay batches the liveness reports it sends, its own and those it - forwards, for a short hold-down (50 ms in the simulator), and recomputes - its trees after a matching delay, as OSPF's SPF delay does. Unbatched, one - relay restart at 340 relays sent half a million messages; batched, 27k. - - On session up, relays exchange a digest (each reporter's incarnation and - its seqno per link) and send only what the other lacks. A reporter's - reports flood separately, so its newest seqno alone would hide a missing - older one. The digest already counts the fresh report of the link that - just came up; sending the database first replays the relay's own report - from when the link went down, and the peer drops the link it is using. -- A relay picks the origin with the lowest shortest-path distance plus origin - cost, ties broken by rendezvous hashing (HRW) of the requested path and the - origin id, and forwards along its shortest path. Distance compares cost, - then hop count, so every hop strictly shortens it even across `?cost=0` - links. That is a shortest path to a virtual node linked to every origin, so - it is loop-free whenever relays agree on the topology. The longest covering - prefix still ranks first, per [Wildcard](/quest/m0/wildcard/README.md). The - simulator saw no loop while views agreed, and HRW split an equal-cost pool - 63/49 where today's hash of the announced prefix sends all of it to one - sibling. -- The first relay's choice rides the SUBSCRIBE, and transit relays forward - toward that origin by topology alone, never re-selecting. Re-selection - against another existence view loops: a relay that lost a specific claim - falls back to a broader one through a relay still routing to the specific - one ([RFC 8966 section 3.5.4](https://www.rfc-editor.org/rfc/rfc8966#section-3.5.4)). - If the origin no longer serves the path, it refuses, and the first relay - selects again. -- SUBSCRIBE and FETCH carry a visited-relay list end to end. It catches loops - while liveness views disagree and names the path for stats. Narrowing it to - cluster hops is later work. The serving origin's identity rides the reply, - per Wildcard's Spread quest. On live's graph no disagreement looped across - 20 seeds of link, cost, and relay churn; the list is a safety net. -- Announcements are on demand. A relay forwards only the union of its clients' - ANNOUNCE_REQUEST prefixes, never the empty prefix. A wide prefix that many - edges' viewers request is that customer's cost. `.stats` becomes ordinary - demand. -- Registries are an optional, configured tier: moq-relay in a registry mode, - one or more per region. - - An ingest relay registers its broadcasts with its nearest registry, and an - edge sends its ANNOUNCE_REQUEST there. - - Registries form a small full mesh and flood existence among themselves, so - an event crosses an ocean once per remote registry, not once per relay. - Announce latency is about one round trip to the nearest registry, - whatever the path length. - - A relay fails over to the next-nearest registry and reconciles its view - instead of treating the lost session as ends, so a registry failure never - reports a live broadcast offline. - - The reconcile is the relay's full live set at its current seqno, which - ends whatever it leaves out. The registry's snapshot carries each - relevant origin's last reconcile seqno, and the relay names the origins it - already holds, so a view kept through a freeze ends what ended meanwhile. - - With no registry reachable, a relay freezes: it keeps its view, learns - nothing new, and alerts. Falling back to flooding would cascade the - failure. -- Without registries (self-hosting), existence floods along the shortest-path - tree, one copy per relay. A relay forwards an event only when it changes its - view, so a duplicate copy, from trees built on disagreeing liveness, stops - there. A relay that gains a child in its tree (a view change or a new - session) pushes that origin's reset and records to it; without the push a - relay misses events while views disagree. -- Between clusters, announcements stay path vector with cluster ids as the - hops, like BGP between autonomous systems. A customer's on-prem cluster is - one hop, and an announcement naming the receiving cluster is dropped. -- The cluster switches versions as a whole; older lite and IETF sessions stay - at its edges. - -### Simulator findings - -The report is moq.pro's `just rs sim` (every scenario on live's graph) and -`just rs sim sweep` (synthetic regional graphs of 34, 340, and 1020 relays). -It carries messages and bytes by kind, per relay and cross-region, -convergence, loop, stall, and failover windows, and state per relay and per -registry. What decides the wire: - -- Existence costs about one message per relay per event flooded, and one per - interested relay plus one per remote registry with registries. On live, a - wide customer prefix with `.stats` from every relay cost 2.5M announces - today, 4k flooded, and 3.5k with registries, whose relays held 63 records - on average against 94. -- Liveness is the split's dominant cost at scale: flooding every link repeats - each report once per neighbour. At 1020 relays (mean degree 35), a link - loss and restore plus a relay loss and restart cost about 290 MiB of - liveness flooding and 54 MiB of session-up digests against under 1 MiB of - existence for twenty publishes, while a publish costs exactly one message - per relay. A reduced flooding topology - ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)) is the known fix for - the flooding. -- Failure detection, not routing, sets every outage window: a silent link or - relay loss is noticed after the 30 s QUIC idle timeout in every candidate, - and subscribes through it go nowhere until then. Cluster sessions need a - short idle timeout; a keepalive only keeps a quiet session open. -- One registry per region and two cost about the same; two halves the - busiest registry's load. A registration sent on a dead registry session - that nobody has noticed yet waits for the failover. -- [#4399](https://github.com/moq-dev/moq/pull/4399) trades path hunting for - flapping. In its own full mesh of 8 it retracts each of 100 withdrawn - broadcasts exactly once per relay, as its tests show. On live's graph, with - each writer coalescing for 1 ms, ending three paths loops subscribes for - 9 s instead of 41 s and edges report the ended paths for 38 s summed - instead of 93, but it costs about the same 60k messages, and clients see - 17k updates instead of 12k, with ended paths re-announced 4185 times - instead of 163: each re-announce by a peer revives every route through it, - stale ones included. Written without coalescing, the revivals cascade, and - the same scenario costs 18.6M messages instead of 189k. Per-origin seqnos, - above, end both. - -### Open questions - -- Sharding registries by HRW over a prefix key once one registry cannot hold - everything, and what that key is. -- A mixed-version bridge, if a fleet cannot switch at once. -- How long a relay keeps an ended path's seqno. A new origin incarnation - clears it; within one, it must outlive every delayed copy of the start. -- How a push to a new tree child ends what the child missed within the same - incarnation. Its reset only marks a new incarnation, so the push may need a - watermark like the registry reconcile's: it ends only what the child holds - at or below it, and a delayed push cannot erase newer records. -- How long a relay keeps the records of an origin that never comes back. They - stop being reported once it is unreachable, but nothing removes them. -- How an edge routes a SUBSCRIBE for a path none of its clients asked to - announce. It holds no route for it, and asking a registry first adds a round - trip before the first byte. -- What a cold ANNOUNCE_REQUEST reports as live. Answering from the local view - keeps a relay from waiting on peers but reports an empty set until the - registry's replay lands, on every new prefix rather than in a rare race. -- What remains of announce compression's hop-tail half (`Hop Base` and - `Hop Keep` in the lite draft) once only cluster boundaries carry hops. -- What replaces `--hop` first-hop failover. Today two publishers sharing a Hop - ID are one source that relays fail over between at a group boundary - (`doc/bin/cli.md` "Redundant publishers", - `doc/concept/use-case/contribution.md`). Inside a cluster no announcement - carries a hop list, so two encoders on different ingest relays become two - origins. Keep the documented behavior or change the docs in the same PR. -- Whether equal-cost next hops should spread by a hash of the path. A fixed - tie-break sends every path through the same neighbour and its failure takes - them all. - -## Required - -- moq.pro workers stop electing on hop chains, reading the relay's local origin instead ([moq.pro voice-local-origin](https://github.com/moq-dev/moq.pro/blob/main/quest/m0/voice-local-origin.md)) -- [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity this selection builds on - -## Related - -- [Redundant ingest](/quest/m2/redundant-ingest.md) - builds on the `--hop` failover this must keep or replace -- [Routing cost domains](/quest/m2/routing-cost-domains.md) - cost across the cluster boundaries this keeps path vector -- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its #4349 report also shows closed broadcasts announced for up to 229 s and flapping between Retracted and Announced across nodes, evidence for per-incarnation seqnos diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md new file mode 100644 index 00000000000..386f8655e93 --- /dev/null +++ b/quest/m1/cluster-routing/README.md @@ -0,0 +1,131 @@ +# Cluster routing + +## Goal + +A cluster carries each broadcast into a region once and never exposes its +backbone to end users. Relays take an explicit edge or core role: edges +serve end users and spread paths over their region's cores, cores link to +the cores of other regions over configured links with static costs, and +routing between them stays path vector. A broadcast under overlapping +prefixes routes to one origin deterministically. Redundancy an operator +configures may deliver more than one copy. + +Non-goals: edges acting as each other's intermediates (it makes edges a +bigger DDoS target), cache-aware route switching, and a permanently +mixed-version cluster. + +## Plan + +### Decisions + +Settled in the 2026-09-30 wildcard audit (cache tiers), replacing the +link-state and existence-split design planned earlier that day: + +- Two roles, edge and core. Where a region has one edge, that edge is also + its core. A region may have several cores, which do not link to each other. + An edge dials every core in its region over qmux on TLS (intra-region links + are not congested) and picks one per path by rendezvous hashing, so a + broadcast crosses into a region once. An edge never re-advertises one + core's routes to another, so it is never transit. Cores dial the cores of + the regions they link to, only those with lower names, so each pair has one + connection. Cores are hidden from end users, which is the DDoS shield. See + [Edge and core](/quest/m1/cluster-routing/roles.md). +- Core links are configured and static, and may skip PoPs when the RTT is + short: Seattle pulls from San Jose directly rather than via Oregon. Nothing + switches routes on cache state, so Warm and Cold collapse to one route cost + ([One route cost](/quest/m1/route-cost.md)), and the wildcard line's route + upgrade quest is deleted. +- No link-state topology. With split-horizon edges and a sparse core graph, + path vector with hop lists stays loop-free, path hunting is confined to the + cores, liveness flooding (the simulator's dominant link-state cost) is never + paid, and failure detection sets the outage window either way. The parked + implementation is #4631. If stale paths remain on the tiered layout, the + fix is [Path hunting](/quest/m0/path-hunting.md), promoted to m0: a hold-down + on route updates, with no wire change. +- The line lands on `main`: its children are additive. The two breaking + changes left it for `dev` on their own: + [Remove `--hop`](/quest/m1/hop-removal.md) and + [One route cost](/quest/m1/route-cost.md). +- Cluster links are moq-lite only; moq-transport peers are plain clients + ([moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md)). +- An epoch-qualified concrete path (`foo/@`) is a source's identity: + origins that announce the same one are interchangeable, which is how a + redundant pair is expressed. A path a claim produces keeps Wildcard's + per-origin identity. See [Selection](/quest/m1/cluster-routing/selection.md). +- Between clusters, announcements stay path vector with cluster ids as hops, + in the last child. +- Anything specific to moq.pro's deployment (generating peer lists and roles + from its inventory, its simulator) is planned in moq.pro, not here. + +### Simulator findings + +Measured on the earlier flat mesh; they motivated the link-state design the +tiers decision replaced, and still bound what path vector costs. + +The report is moq.pro's `just rs sim` (every scenario on live's graph) and +`just rs sim sweep` (synthetic regional graphs of 34, 340, and 1020 relays). +It carries messages and bytes by kind, per relay and cross-region, +convergence, loop, stall, and failover windows, and state per relay and per +registry. + +- Existence costs about one message per relay per event flooded, and one per + interested relay plus one per remote registry with registries. On live, a + wide customer prefix with `.stats` from every relay cost 2.5M announces + today, 4k flooded, and 3.5k with registries, whose relays held 63 records + on average against 94. +- Liveness is the split's dominant cost at scale: flooding every link repeats + each report once per neighbour. At 1020 relays (mean degree 35), a link + loss and restore plus a relay loss and restart cost about 290 MiB of + liveness flooding and 54 MiB of session-up digests against under 1 MiB of + existence for twenty publishes, while a publish costs exactly one message + per relay. +- Unbatched, one relay restart at 340 relays sent half a million liveness + messages; batched for 50 ms, 27k. +- Failure detection, not routing, sets every outage window: a silent link or + relay loss is noticed after the 30 s QUIC idle timeout in every candidate, + and subscribes through it go nowhere until then. +- The simulator saw no loop while views agreed, and HRW split an equal-cost + pool 63/49 where a hash of the announced prefix sent all of it to one + sibling (Wildcard has since keyed the tie on the requested path). On live's graph no disagreement looped across 20 seeds of link, + cost, and relay churn. +- One registry per region and two cost about the same; two halves the + busiest registry's load. A registration sent on a dead registry session + that nobody has noticed yet waits for the failover. +- [#4399](https://github.com/moq-dev/moq/pull/4399) trades path hunting for + flapping. In its own full mesh of 8 it retracts each of 100 withdrawn + broadcasts exactly once per relay, as its tests show. On live's graph, with + each writer coalescing for 1 ms, ending three paths loops subscribes for + 9 s instead of 41 s and edges report the ended paths for 38 s summed + instead of 93, but it costs about the same 60k messages, and clients see + 17k updates instead of 12k, with ended paths re-announced 4185 times + instead of 163: each re-announce by a peer revives every route through it, + stale ones included. Written without coalescing, the revivals cascade, and + the same scenario costs 18.6M messages instead of 189k. Per-origin seqnos, + above, end both. + +### Remaining work + +Once every child has landed: + +- An end-to-end test: a two-region cluster in `rs/moq-relay/tests` where a + publish, an end, a core loss, and a redundant-pair failover each reach a + subscriber on a far edge, with time mocked. +- Rewrite `doc/bin/relay/cluster.md` into the operator's view (edge and core + layout, dial rules, TLS edge links, link costs, idle timeout, redundant + pairs), and add a routing page under `doc/concept`. + +## Required + +- [Edge and core](/quest/m1/cluster-routing/roles.md) - relays take an explicit edge or core role; edges spread paths over their region's cores and are never transit +- [Selection](/quest/m1/cluster-routing/selection.md) - a broadcast under overlapping prefixes routes to one origin deterministically, and same-epoch origins are one source +- [Between clusters](/quest/m1/cluster-routing/inter-cluster.md) - announcements crossing a cluster boundary stay path vector with cluster ids as hops + +## Related + +- [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity Selection builds on +- [Remove `--hop`](/quest/m1/hop-removal.md) - on `dev`: redundant publishers share an explicit `@` +- [One route cost](/quest/m1/route-cost.md) - on `dev`: Warm and Cold collapse to one static cost +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - the importer half of a redundant pair; `--hop` removal re-keys it to a shared epoch +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch +- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its #4349 report shows closed broadcasts announced for up to 229 s, evidence for per-origin seqnos +- [Routing cost domains](/quest/m3/routing-cost-domains.md) - cost across the cluster boundaries this keeps path vector diff --git a/quest/m1/cluster-routing/inter-cluster.md b/quest/m1/cluster-routing/inter-cluster.md new file mode 100644 index 00000000000..7bc07c072fa --- /dev/null +++ b/quest/m1/cluster-routing/inter-cluster.md @@ -0,0 +1,36 @@ +# [M] Routing between clusters + +## Goal + +Announcements crossing a cluster boundary stay path vector with cluster ids +as the hops, like BGP between autonomous systems. A customer's on-prem +cluster is one hop, and an announcement naming the receiving cluster is +dropped. Inside a cluster, hop lists name relays; across a boundary they name +clusters. + +## Plan + +- A boundary is a configured link to a relay of another cluster; decide how + a relay knows its own cluster id and its peer's. +- What crosses a boundary is a cluster's announcement, plus its cluster-id + list. An imported record keeps that list as provenance, so + whichever boundary relay exports it appends its own cluster id to the full + list; stripping it on import would let A → B → C → A re-enter A. +- The remote origin is outside the receiving cluster, so the + importing boundary relay announces the record inside its cluster as the + origin, with the boundary link's cost added. The serving origin's identity + still rides the reply, so re-originating does not merge two sources. +- Cluster-id lists are short, so they need no `Hop Base`/`Hop Keep` + compression. +- Cost across the boundary is plain configured link cost; business policy + and incomparable costs are + [Routing cost domains](/quest/m3/routing-cost-domains.md)'s. + +Wire: the boundary announcement in the current wip lite version, with the +draft updated in the same PR. Tests: two clusters with two boundary links +and an origin that is not a boundary relay, and three clusters in a cycle with different ingress and egress relays, where +an announcement neither loops nor re-enters its origin cluster. + +## Related + +- [Routing cost domains](/quest/m3/routing-cost-domains.md) - designs policy on this path vector diff --git a/quest/m1/cluster-routing/roles.md b/quest/m1/cluster-routing/roles.md new file mode 100644 index 00000000000..c6e2f9628e9 --- /dev/null +++ b/quest/m1/cluster-routing/roles.md @@ -0,0 +1,54 @@ +# [M] Edge and core relays + +## Goal + +A relay runs as an edge or a core, and a cluster built from them carries +each broadcast into a region once. An edge serves end users, dials every core +in its region, spreads paths over those cores by rendezvous hashing, and is +never transit between cores. A core serves only cluster peers, dials the +cores of the regions it links to, and never dials an edge. + +## Plan + +Decided in the 2026-09-30 wildcard audit (cache tiers): + +- The role is the node's own `cluster.role`, explicit, from config or + alongside the peer list the connect API returns. A relay whose links + contradict its role (an edge linked to another edge, a core dialing an + edge) fails at startup. Where a region has one edge, that edge is its core. +- A relay with no role is a legacy peer and links any peer, as before roles. + A core accepts and dials a legacy peer as a core-grade link, and an edge + never links one. This is what lets an operator migrate one region at a + time: a migrated region's cores bridge to the unmigrated mesh. A + permanently mixed cluster stays a non-goal. +- A core refuses a session that is not a cluster peer, loudly, so a + misrouted client fails instead of silently exposing the shield. +- Cores dial only cores with lower names, so each pair has one connection; + cores in one region do not link to each other. This is configuration: the + relay follows its peer list, and whatever generates the list applies the + rule. +- Edge links run qmux over TLS on TCP, not WebSocket and not QUIC: + intra-region links are not congested. qmux over TCP exists today only in + plaintext (`tcp://`); add `tls://`, wired to qmux's existing `tls` module. + (Scheme name decided 2026-09-30.) +- An edge never re-advertises a route learned from one core to another core: + its cluster dials publish only what entered locally + (`origin::Consumer::local()`), so no core routes through an edge. +- An edge picks a core per path with the path-keyed rendezvous hash the + wildcard line gave `route_order`, so every edge in a region sends a path to + the same core, and failover moves only the paths the lost core served. The + per-path spread across equally ranked cores is + [Selection](/quest/m1/cluster-routing/selection.md)'s. + +Test: a two-region cluster (two edges and two cores in one region, one core +in the other) in `rs/moq-relay/tests`, where subscribers on both edges of a +region cause one cross-region subscription per broadcast, a route from one +core never reaches another through an edge, a client dialing a core is +refused, and losing a core moves only its paths. + +Public API: a relay config field for the role and a TLS qmux URL scheme. +Wire: none expected. + +## Related + +- [moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md) - cluster links are lite-only diff --git a/quest/m1/cluster-routing/selection.md b/quest/m1/cluster-routing/selection.md new file mode 100644 index 00000000000..8cb3b0cbd50 --- /dev/null +++ b/quest/m1/cluster-routing/selection.md @@ -0,0 +1,62 @@ +# [L] Deterministic origin selection + +## Goal + +A broadcast under overlapping announcements routes to one origin chosen +deterministically, and an edge spreads paths over its region's cores so +every edge sends a given path the same way. +Origins that announce the same epoch-qualified concrete path are one source, +so a subscriber moves between them at a group boundary when the incumbent +ends or becomes unreachable. + +## Plan + +Decided: + +- The longest covering prefix ranks first, per + [Wildcard](/quest/m0/wildcard/README.md), and origin choice is + per broadcast, not per announced prefix. +- An epoch-qualified concrete path (`foo/@`) is a source's identity: + every origin announcing it is interchangeable, which is how a redundant + pair works without `--hop`. The first relay fails over between them at a + group boundary. A path with no epoch, or one a claim produces, keeps + Wildcard's per-origin identity (the origin SUBSCRIBE_OK names), since two + workers' groups differ. That includes a claim worker's derived output once + it is announced concretely: it mirrors the input's epoch + (`.pro/transcode//foo.hang/@e`), so after a double claim two workers + announce the same epoch-qualified path and must not pool. This extends + Wildcard's resume rule to concrete same-epoch origins. + +Candidate mechanics (re-scoped to path vector by the 2026-09-30 tiers +decision; there is no topology to forward by): + +- Route selection stays `route_order` over the routes a relay holds: longest + prefix, then cost, then a rendezvous hash (HRW) of the requested path and + the route's origin. At an edge that spreads paths over the region's cores + and makes every edge pick the same core for a path; failover moves only the + paths the lost core won. +- A refusal follows Wildcard's refusal rule: every refusal is terminal, and + an origin sheds load by withdrawing or re-pricing its route instead. +- The serving origin's identity rides the Origin field of the reply, per + Wildcard's resume rule. + +Open: + +- How a relay tells claim output from a redundant pair. One candidate: a + concrete path an origin announces under its own claim keeps per-origin + identity, since a redundant publisher claims nothing. + +Wire: none expected; if one is needed it goes in the current wip lite +version with the draft. Tests cover an HRW split across an equal-cost +pool, refusal and reselection, a same-epoch pair failing over mid-track +with no timestamp rewind, and a concrete double claim whose loser's +subscribers end and resubscribe rather than splice. + +## Required + +- [Edge and core](/quest/m1/cluster-routing/roles.md) - the edges and cores this spreads over +- [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity this builds on + +## Related + +- [Epoch primitive](/quest/m1/epoch.md) - parses the `@` segment that makes a path a source identity diff --git a/quest/m1/cmaf-opus-surround.md b/quest/m1/cmaf-opus-surround.md index da3ae24b669..ab6b86e93c6 100644 --- a/quest/m1/cmaf-opus-surround.md +++ b/quest/m1/cmaf-opus-surround.md @@ -19,4 +19,3 @@ its table intact. ## Required - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - `Dops` carries the mapping family and table -- [Audio codecs](/quest/m1/audio-codecs/README.md) - `opus::Mapping` and a `Config::encode` that writes any family's table diff --git a/quest/m1/coding-reader-cap.md b/quest/m1/coding-reader-cap.md deleted file mode 100644 index 68b22a6a797..00000000000 --- a/quest/m1/coding-reader-cap.md +++ /dev/null @@ -1,21 +0,0 @@ -# [XS] Rust decoders cap a bare byte or string read - -## Goal - -Every Rust decode path that allocates from a peer-supplied length has an -upper bound. #4373 fixed a JS size-cap bypass; the lite and IETF message -decoders in Rust already check every length prefix, but `coding/reader.rs` -has no overall cap for a bare `Vec` or `String` decode. - -## Plan - -- Audit `rs/moq-net/src/coding/` for decodes that allocate from a length - prefix without a bound, and list which call sites reach them from the - wire. -- Where one is reachable, bound it by the message's size limit and refuse - anything larger with a decode error. If none is reachable, add the bound - anyway only if it's one line; otherwise delete this quest with the audit - in the PR. - -Public API: none. Wire: oversized fields are refused, which they already -should be. diff --git a/quest/m1/color-model.md b/quest/m1/color-model.md index cf39b1ed8be..45fed149ab4 100644 --- a/quest/m1/color-model.md +++ b/quest/m1/color-model.md @@ -1,11 +1,11 @@ -# [M] Catalog colour model +# [M] Encoders signal the colour they produce ## Goal -The Hang catalog describes a video rendition's colour: primaries, transfer -characteristics, matrix coefficients, range, and the HDR10 mastering display and -content light levels. A renderer can set up its pipeline from the catalog -instead of guessing or reparsing the bitstream. +Every moq-video encode path signals the colour its output pixels actually +have. The CUDA, D3D, and Android paths preserve primaries, transfer, matrix, +and range through conversion, and a path that cannot honour the requested +colour converts correctly or refuses instead of mislabelling. ## Plan @@ -15,45 +15,13 @@ warn about a known color mismatch and then label unchanged pixels as the requested color: convert correctly or refuse. Preserve color information through CUDA, D3D, and Android paths and test the signaled VUI against pixels. -`rs/hang/src/catalog/video/mod.rs` has carried a bare `// TODO color space` since -the config was written. Two codecs already expose colour per their own syntax: -`VP9` carries primaries, transfer characteristics, matrix coefficients, and -range inside its codec string, and `AV1` has the same fields, which -`rs/moq-mux/src/codec/av1/import.rs` fills from the sequence header. They only -round-trip through muxers (the fMP4 exporter writes VP9's into `vpcC`); no -renderer consumes either, H.264 and H.265 have no equivalent, and there is no HDR10, -mastering display, or content light handling in `rs/` or `js/` at all. So an -HDR broadcast is delivered today and rendered as if it were SDR, whatever the -source signalled. - -Model the codec-neutral properties rather than one codec's syntax, so H.264 and -H.265 VUI, AV1 colour config, and a container's `colr` box all populate the same -fields. Generalize the existing VP9 and AV1 fields into that model rather than -adding a second colour source beside them: the codec-specific fields keep their -wire meaning (the VP9 codec string is defined by its spec) and feed the neutral -fields at import, so a renderer reads one place. Fill them at import from -whichever source the rendition provides, and emit them on export. - -Settle the precedence before adding the fields, because these sources disagree -in real files and a renderer must not see a different answer per import path. -Prefer the bitstream over the container: VUI and the AV1 colour config are what -the encoder actually signalled and travel with the elementary stream, while a -`colr` box is added by a muxer that may be wrong or stale. Record which source -won so a conflict is diagnosable rather than invisible, and treat an -unspecified value as absent rather than as a signalled default, so a partial -container box does not override a complete bitstream. - -Static display properties belong here rather than in a timed track, which is -also where the HDR10 metadata that lives in H.26x SEI should land once it can be -read. That is the one seam with the SEI line, and it runs in one direction: -this quest gives display metadata a home, and does not depend on SEI work. - -Test each source of truth in isolation, a source that signals nothing, a -conflict between VUI and container resolving to the bitstream, a container box -that fills a gap the bitstream left unspecified, and an SDR round trip that -stays byte-identical. +Decided in the 2026-09-30 audit: split from the catalog colour model, which +moved to [Catalog colour](/quest/m2/color-catalog.md) because no renderer +consumes colour from the catalog today. Encoder correctness stays in m1 +because a mislabelled stream is wrong for every consumer. ## Related -- [SEI sidecars](/quest/m2/sei/README.md) - moves SEI out of the video track; +- [Catalog colour](/quest/m2/color-catalog.md) - the catalog describes a rendition's colour and HDR properties +- [SEI sidecars](/quest/m2/sei.md) - moves SEI out of the video track; the display metadata inside it needs the home this quest builds diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index da3e51f2625..92bdb368985 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -2,7 +2,7 @@ ## Goal -A C++ developer adds one registry line or one tarball, includes ``, +A C++ developer adds one release tarball, includes ``, and holds the whole moq-ffi surface (session, origin, broadcast, track, group, media, audio and video) as RAII objects whose async operations return cancellable futures, with no `user_data` plumbing, no handle integers, and no @@ -41,11 +41,12 @@ One library, C++17 floor (OBS's baseline), feature-gated extras: `co_await` on a future under `__cpp_impl_coroutine`, `std::expected` under `__cpp_lib_expected`. Never a second library per standard. -Distribution is all of: a release tarball with a CMake package config and -pkg-config file (mirroring `moq-c.yml`), a vcpkg registry we own, and a Conan -remote we own, the latter two fetching the prebuilt tarball so consumers never -need a Rust toolchain or the bindgen fork. vcpkg lands first; the Conan recipe -reads the same release manifest so a release bumps both. +Distribution is a release tarball with a CMake package config and pkg-config +file (mirroring `moq-c.yml`), so consumers never need a Rust toolchain or the +bindgen fork. Decided in the 2026-09-30 audit: this line promises the tarball +only. A [vcpkg registry](/quest/m2/cpp-vcpkg.md) (m2) and a +[Conan remote](/quest/m3/cpp-conan.md) (m3) fetch the same tarball later and +stay deferred. Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): @@ -74,7 +75,7 @@ Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): ## Related -- [C# through moq-ffi](/quest/m2/cs/README.md) - the same recipe with NordSecurity's C# generator -- [Unreal prototype](/quest/m2/unreal.md) - a UE5 module consumes the package with exceptions disabled - [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests -- [Conan remote](/quest/m2/cpp-conan.md) - a remote we own serves the same tarball to `conan install` +- [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the prebuilt package to Conan +- [C# through moq-ffi](/quest/m3/cs/README.md) - the same recipe with NordSecurity's C# generator +- [Unreal prototype](/quest/m3/unreal.md) - a UE5 module consumes the package with exceptions disabled diff --git a/quest/m1/cpp/generator.md b/quest/m1/cpp/generator.md index 1a3c917d0dc..66dc7d8be83 100644 --- a/quest/m1/cpp/generator.md +++ b/quest/m1/cpp/generator.md @@ -44,4 +44,4 @@ stop here and write down why. ## Related -- [C# generator](/quest/m2/cs/generator.md) - the same 0.32 port against NordSecurity's C# generator +- [C# generator](/quest/m3/cs/generator.md) - the same 0.32 port against NordSecurity's C# generator diff --git a/quest/m1/cross-relay-bursts.md b/quest/m1/cross-relay-bursts.md index 25607b1be82..a7a31241d4a 100644 --- a/quest/m1/cross-relay-bursts.md +++ b/quest/m1/cross-relay-bursts.md @@ -14,21 +14,17 @@ node, or one self-hosted relay, loses nothing. Reproduce first, on a local two-relay cluster with the reporter's harness (offered in the issue) and the relay build cdn.moq.pro ran. Then fix what the repro shows. Suspects: `Old` expiry or newest-first dropping on the relay hop, -and FETCH not forwarded or answered upstream. Re-measure the stalls after -[FIN wait expiry](/quest/m1/fin-wait-expiry.md), a candidate cause. Keep the -repro as a regression test in the cluster tests. +and FETCH not forwarded or answered upstream. A group awaiting its FIN ack +now expires and follows priority updates, which removed one candidate cause. +Keep the repro as a regression test in the cluster tests. The issue's stale and flapping announcements after a clean close are cluster-routing evidence, not this quest's scope. -## Required - -- [FIN wait expiry](/quest/m1/fin-wait-expiry.md) - removes one candidate cause of the stalls before measuring - ## Closes - [#4349](https://github.com/moq-dev/moq/issues/4349) - close this issue when the quest finishes ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - owns the stale and flapping announcements from the same report +- [Cluster routing](/quest/m1/cluster-routing/README.md) - owns the stale and flapping announcements from the same report diff --git a/quest/m1/csp-assets.md b/quest/m1/csp-assets.md new file mode 100644 index 00000000000..ad9a46bcbc3 --- /dev/null +++ b/quest/m1/csp-assets.md @@ -0,0 +1,81 @@ +# [M] Watch and publish under a strict CSP + +## Goal + +By default, watch and publish keep working on every bundler with no hosted +files: the worklets and the capture worker load from `blob:` URLs, as today. +An app whose CSP refuses `blob:` (`script-src 'self'`, `worker-src 'self'`) +opts in by copying the worker and worklet files out of `node_modules`, +hosting them, and giving each package their base URL. It then plays and +publishes audio with no CSP violations. + +Covers the watch render worklet, the publish capture worklet, and the +publish capture worker (`?worker&inline`). Today a strict CSP refuses all +three, and the only symptom is a console "spawn error". + +## Plan + +Why not `new URL(..., import.meta.url)`: [#4485](https://github.com/moq-dev/moq/pull/4485) +emitted the worklets as assets behind that pattern. Built consumers probed +in Chromium on 2026-09-29 gave these results. Vite build, Vite dev +(prebundled), webpack 5, Rspack, Parcel, and import maps copied the file. +esbuild ESM, Rollup, and Bun left it behind (a 404, so no audio). esbuild +IIFE threw `Invalid URL` at module load, which broke the whole player. A +library can't require every consumer to host its files. And a strict CSP +can't avoid a same-origin file, because `addModule` and `new Worker` need a +URL, and only `blob:`/`data:` URLs come without hosting. + +Decided in planning: + +- One set of entry points, with the hosted mode set at runtime. No second + entry tree and no export condition. +- The blob code sits behind a dynamic `import()` that only runs when no base + is set. So the default loads it lazily, and hosted mode on a code-splitting + bundler never downloads it. Single-file builds (esbuild without splitting, + Bun, IIFE) inline it, which is about 12 KB minified of dead weight in hosted + mode only. Accepted over doubling the exports. +- Hosted-mode files load from `new URL(, base)`, with the base + first resolved against `document.baseURI`, so a root-relative `/moq/` + works (`new URL(name, "/moq/")` alone throws). Never `import.meta.url`: + the default path must not reference an asset that some bundlers drop. +- API: one global base URL per package, set once before playback (e.g. + `Watch.assets("/moq/")` and `Publish.assets("/moq/")`; the exact name is for + review). Assets are app-wide, so nothing threads through `Player`, the + decoder, or the elements. room and moq-boy set nothing of their own; their + docs say to set both. +- Files: stable, unhashed names under each package's `dist/assets/` (e.g. + `@moq/watch/assets/render-worklet.js`), also listed in `package.json` + `exports` so copy plugins and `import.meta.resolve` can find them. The + worklet messages can change between versions, so the docs say to recopy on + every upgrade. +- `vite serve` in this repo keeps blob URLs. +- Docs: an inline section in `doc/lib/js/watch.md` and + `doc/lib/js/publish.md` (not a shared page). Each covers the base URL, the + files to copy, and the CSP directives. The capture worker needs + `worker-src`, the worklets `script-src`. +- Tests: + - A `js/common` unit test in `just js test`, with no browser. It asserts + the built default dist has no `new URL(..., import.meta.url)` asset + reference and that the blob code is only reached through `import()`. + - A manual bundler-matrix script, not wired into CI or nightly. This is the + maintainer's call, an exception to the repo's CI rule. It builds a + consumer with Vite, webpack, esbuild IIFE, and Bun, then loads each in + Chromium, in default mode (no CSP) and hosted mode (strict CSP). The page + loads all three assets directly (both worklets through `addModule`, and + the capture worker through a spawn and a message round trip). Chromium's + publish path uses the main-thread `MediaStreamTrackProcessor` and never + spawns the worker, and the worker path silently falls back when the + spawn fails. Report the results in the PR. + +Reuse from #4485 where it fits: the `resolveFileUrl`/`emitFile` plumbing in +`js/common/vite-plugin-worklet.ts` and its Playwright CSP page, minus the +interop CI step. + +## Closes + +- [#4323](https://github.com/moq-dev/moq/issues/4323) - close this issue when the quest finishes + +## Related + +- [JS bundle trims](/quest/m1/js-bundle-trims.md) - minifies worklets through the same plugin +- [Plan: watch worker](/quest/m1/plan-watch-worker.md) - a new watch worker joins the same assets base diff --git a/quest/m1/dart-codecs.md b/quest/m1/dart-codecs.md index a0563a2791b..b302fdee481 100644 --- a/quest/m1/dart-codecs.md +++ b/quest/m1/dart-codecs.md @@ -32,3 +32,10 @@ This quest owns Dart integration of the already-landed `MoqVideoConsumer`: expose it through the Dart wrapper, ship codec-enabled artifacts, and test subscribed video decoding from Dart in CI. Update the capability docs in the same change. Do not finish with codecs enabled but the consumer unexposed. + +Decided in the 2026-09-30 audit: wait for the codec namespaces, so the Dart +wrapper exposes encoders and decoders in their final shape once. + +## Required + +- [Codec](/quest/m1/ffi-shape/codec.md) - audio and video codecs get their own namespaces in moq-ffi diff --git a/quest/m1/dart-publish.md b/quest/m1/dart-publish.md index f51a9d4f83f..f634f082147 100644 --- a/quest/m1/dart-publish.md +++ b/quest/m1/dart-publish.md @@ -39,11 +39,15 @@ hand-edited before tagging. Verify the published `moq_ffi` resolves its native asset from a clean machine with no monorepo checkout, since that download path is the one CI never exercises. -The blocker below is about not publishing a claim we cannot support: the +The iOS blocker is about not publishing a claim we cannot support: the first release is the one that reaches strangers, and pub.dev packages generally cannot be unpublished or deleted. A version may be retracted within seven days, but retraction does not erase it. +Decided in the 2026-09-30 audit: publishing also waits on FFI shape, which +relies on Dart being unpublished so its breaking renames are free. + ## Required - [Dart on iOS](/quest/m1/dart-ios.md) - the package advertises iOS, which nobody has run +- [FFI shape](/quest/m1/ffi-shape/README.md) - its breaking renames are free only while Dart is unpublished diff --git a/quest/m1/data-capture-bindings.md b/quest/m1/data-capture-bindings.md deleted file mode 100644 index 90f1f008ea3..00000000000 --- a/quest/m1/data-capture-bindings.md +++ /dev/null @@ -1,55 +0,0 @@ -# [M] Bindings stamp data frames with a capture time - -## Goal - -A moq-ffi publisher, and every wrapper over it (Python, Swift, Kotlin, Go, -Dart), can pass a capture time with a JSON or binary snapshot `update` or -stream `append`, so its data tracks advertise `delay` and `jitter` like a Rust -publisher's. Leaving it out keeps today's behaviour. The Go and Python -wrappers gain the binary snapshot and stream producers they lack. `moq-json`'s `window` -producer takes a capture time too. Settled scope: moq-ffi and its wrappers, -not moq-c. - -## Plan - -- #4270 gives the Rust producers `moq_net::Timed`, built with - `Timed::from(value).at(t)`. The `moq-mux` data producers take - `Timed<_, Instant>`, map it onto the broadcast clock, and refuse one ahead of - now (`Error::InvalidCapture`). The moq-ffi producers in - `rs/moq-ffi/src/{json,flate}.rs` pass bare values. -- Settled: the capture time is a media timestamp on the broadcast's - timeline. moq-ffi exposes the broadcast clock's `now()` as a timestamp; - callers stamp payloads with values taken from it, and moq refuses one ahead - of now. That keeps a device or process clock out, as the Rust `Instant` - mapping does. The `moq-mux` producers take an `Instant` today, so either - map the timestamp back through the clock inside moq-ffi or give the clock a - typed timestamp moq-mux accepts; keep a raw `Timestamp` from compiling - there. Make it optional on the existing methods, never a `_with_capture` - twin. -- `moq-json` window: `window::Producer::push` stamps `Timestamp::now()` - (`rs/moq-json/src/window/producer.rs`). Accept `Timed` as the snapshot and - stream producers do. Nothing in `moq-mux` publishes window mode, so there is - no estimator to feed. -- Wrappers follow per the cross-package sync table, each with a test that a - past capture time is accepted and a future one refused. -- Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON - producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added - `publish_binary_snapshot` / `publish_binary_stream` (now - `publish_flate_*`) to moq-ffi without them. Add hand-written flate wrappers there, capture time included, so - the capture tests cover binary too. The maintainer asked for this. Update - `doc/lib/{py,swift,kt,go,dart}`. - -Public API: breaking, so it lands on `dev`. A new parameter on the generated -`update` and `append` breaks every published binding caller (Go, for one, has -no optional arguments), and a `_with_x` twin is ruled out. The broadcast clock -`now()` and the Go and Python binary producers are additive; -`window::Producer::push` accepts `Timed`, source-compatible. -Wire: none. - -## Required - -- [JSON and flate namespaces](/quest/m1/ffi-shape/json.md) - moves the data producers this changes, so the two breaks land in order rather than colliding - -## Related - -- [Generated C bindings](/quest/m1/c/README.md) - replaces libmoq, so C inherits this from moq-ffi diff --git a/quest/m1/data-config-nesting.md b/quest/m1/data-config-nesting.md new file mode 100644 index 00000000000..95c7ab5a9ed --- /dev/null +++ b/quest/m1/data-config-nesting.md @@ -0,0 +1,40 @@ +# [XS] Docs nest a data config instead of flattening it + +## Goal + +The docs and doctests for application data sections nest `BinaryConfig` or +`JsonConfig` in a `config` field instead of `#[serde(flatten)]`ing it, so a +field added to either config later can never collide with an application's own +fields. + +```rust +struct Mavlink { + config: BinaryConfig, + sysid: u8, +} +``` + +## Plan + +Requested by an external consumer (OneTooMany, Discord). No code flattens +these configs today; only docs and tests do. The built-in `json`/`binary` +sections serialize the config directly as the map value, so their wire shape +is unchanged. An application section becomes +`{"config":{"mode":...},"sysid":1}`. + +Update: + +- `doc/lib/rs/moq-mux.md` (the `Mavlink` example, its `AsMut` impl returning + `&mut self.config`, and the `catalog::Entry::new(name, &entry.config)` line) +- `doc/concept/hang.md` (the "flattening the JSON or binary entry" prose) +- the `RenditionConfig` doctest in `rs/moq-mux/src/catalog/tracks.rs` +- `a_data_config_flattens_into_an_application_entry` in + `rs/hang/src/catalog/root.rs` (rename; the `extra` assertion no longer + applies) and `mod section` in `rs/moq-mux/src/binary.rs` + +`doc/lib/rs/hang.md`'s flatten of a whole extension into `Catalog` is a +different pattern and stays. + +## Related + +- [Robot teleoperation](/quest/m2/teleop/robot.md) - decides where robot fields ride in the catalog diff --git a/quest/m1/data-consumer-timestamps.md b/quest/m1/data-consumer-timestamps.md new file mode 100644 index 00000000000..3ac4aebdbe3 --- /dev/null +++ b/quest/m1/data-consumer-timestamps.md @@ -0,0 +1,38 @@ +# [M] Data consumers return each value's timestamp + +## Goal + +A JSON or binary data consumer returns each value with its frame's timestamp, +so an application can carry data onto another track, or sync it with video, +at the exact time it was published. Covers moq-json, moq-flate, the moq-mux +wrappers, moq-ffi, and every binding wrapper. + +## Plan + +Requested by an external consumer (OneTooMany, Discord), who translates +MAVLink into application telemetry and must keep its timestamps to stay in +sync with video. + +Every `moq_net::Frame` has a timestamp, but the consumers decode only +`frame.payload` and drop it: `moq_mux::{json,binary}::Consumer::next` and the +moq-json and moq-flate snapshot and stream consumers they wrap. A snapshot +consumer returns the timestamp of the frame it decoded last. + +Decided: `next()` and `poll_next()` return `Timed`, the type the producers +take, whose `at` becomes required in +[Publishing requires a timestamp](/quest/m1/publish-timestamp.md). The +timestamp is the frame's media timestamp on the track's timescale. +[Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) decides +whether a peer can deliver a frame without one; if it can, `at` becomes an +`Option` here, so this waits for it and breaks once. + +moq-ffi's json/flate consumers return the timestamp too, and the py, swift, +kt, go, and dart wrappers and `doc/lib/*` follow. JS readers stay with +[Data sync in watch](/quest/m3/watch-data-sync.md). + +Public API: breaking, on `dev`. Wire: none. + +## Required + +- [Publishing requires a timestamp](/quest/m1/publish-timestamp.md) - makes `Timed.at` required, the type this returns +- [Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) - decides whether the returned timestamp can be absent diff --git a/quest/m1/data-track-clock.md b/quest/m1/data-track-clock.md new file mode 100644 index 00000000000..fcb277566b4 --- /dev/null +++ b/quest/m1/data-track-clock.md @@ -0,0 +1,18 @@ +# [XS] Data tracks stamp on the catalog's current clock + +## Goal + +A JSON or binary data track publishes timestamps on the same clock mapping as +the media next to it, however early it was created. Today a data track copies +the catalog clock when it's created. An importer sets that clock from its +first frame (remove-live, #4543), so a data track created before that frame +maps its timestamps to a different clock than the media. + +## Plan + +Remove live() (#4543) is done on `dev`, and the first-frame clock anchor +exists only there, so this targets `dev`. + +Have data tracks read the catalog's clock when they stamp, not a copy made +when they were created. Keep it crate-private if possible. Test: a data track +created before an importer's first frame stamps on the anchored clock. diff --git a/quest/m1/datagram-unfetchable.md b/quest/m1/datagram-unfetchable.md new file mode 100644 index 00000000000..76fa052c69d --- /dev/null +++ b/quest/m1/datagram-unfetchable.md @@ -0,0 +1,55 @@ +# [S] Datagrams are live-only + +## Goal + +A datagram group is delivered only to subscribers present when it is sent. +FETCH never returns one, a new subscription never replays buffered datagrams, +and a relay fills no cache miss with one. Anything that needs reliable or +late-joiner delivery should use a stream group instead. + +## Plan + +Decided in planning (09-29), after the moxygen fetch-fill agent found that the +relay's group-fetch decoder refuses a draft-16+ fetch object that carries the +datagram flag, and reports it as "unsupported": + +- Keep the existing 64-datagram send buffer per track + (`rs/moq-net/src/model/track.rs`, `MAX_DATAGRAMS`). An age bound was + considered and dropped. +- A new subscription starts at the next datagram sent, not at the buffered + backlog. This covers Rust and `@moq/net`, lite and IETF. +- FETCH never serves a datagram group. A publisher answers a FETCH for one the + way it answers any group it won't deliver (dropped or does not exist), + never with its payload. +- A received fetch object with the datagram flag is refused as not fetchable. + It fails only that fetch or fill, not the session, because draft-16+ allows + the flag (maintainer, 09-29, on Codex's review). That covers the relay's group + fill (`recv_group_fetch_objects`) and the joining-fetch + fill (`run_fill_objects`). +- Update `drafts/draft-lcurley-moq-lite.md` to say datagrams are neither + cached nor fetchable, and `doc/concept/`. Run `just drafts check` and + `just test interop --all`. + +Not planned: reliable or cached datagrams. If they are ever wanted, the way to +get them is back-pressure in the QUIC library and treating each datagram like +a one-shot stream, not a cache. + +The subscription's range bounds datagrams the way it bounds groups, fixed in +the model rather than filtered per session. Decided in the 2026-09-30 audit: +the moxygen line's datagram-range quest merged here, since it duplicated this +late-join rule. Its edge cases: + +- a datagram at the start group when a frame offset skips object 0; +- SUBSCRIBE_UPDATE moving the range while datagrams are in flight; +- a datagram that lands before the subscription's alias or id is known. + +Tests: a subscriber joining after datagrams were sent receives only later +ones. A FETCH covering a datagram group gets no payload. A fetch stream +carrying a datagram-flagged object fails that fetch and leaves the session up. +Each edge case above gets one, and a test tells a datagram filtered by the +range apart from one dropped for any other reason. + +## Related + +- [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - JS datagram send and receive over moq-transport +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - datagram groups stay best effort there too diff --git a/quest/m1/doc-samples-go-dart.md b/quest/m1/doc-samples-go-dart.md index 6680e0a0345..50a05e0ec98 100644 --- a/quest/m1/doc-samples-go-dart.md +++ b/quest/m1/doc-samples-go-dart.md @@ -21,7 +21,7 @@ knows neither language. adjusting a sample so it reads naturally and still compiles over growing the extractor. - Wire each into its language's check script, `sh/go/check.sh` and - `sh/dart/check.sh` on the tooling line, the way `sh/kt/check.sh` and + `sh/dart/check.sh`, the way `sh/kt/check.sh` and `sh/py/samples.sh` call `samples.sh`. Add `doc/lib/go/`, `doc/lib/dart/`, and `doc/lib/samples.sh` to the `go` and `dart` patterns of the impact map in `sh/dispatch.sh`, as the `py`, `kt`, and `swift` ones already have. @@ -29,7 +29,3 @@ knows neither language. fail on the doc sample. Public API: none. Wire: none. - -## Required - -- [Tooling](/quest/m1/tooling/README.md) - the `sh//` check scripts and the impact map this extends diff --git a/quest/m1/drain/README.md b/quest/m1/drain/README.md index 786b65f1065..f1195be9dfa 100644 --- a/quest/m1/drain/README.md +++ b/quest/m1/drain/README.md @@ -58,4 +58,4 @@ by the stop deadline and encoder reconnect. ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - the configured topology and link costs a second relay per PoP joins +- [Cluster routing](/quest/m1/cluster-routing/README.md) - the configured topology and link costs a second relay per PoP joins diff --git a/quest/m1/e2ee/README.md b/quest/m1/e2ee/README.md index 07e41ce3c9c..0dcb75b674d 100644 --- a/quest/m1/e2ee/README.md +++ b/quest/m1/e2ee/README.md @@ -40,7 +40,7 @@ The Rust and TypeScript cores expose the same surface, and nothing else: - Deterministic secret-derived physical names hide catalog, codec, role, quality, timeline, and custom-track semantics. Authorized clients derive the encrypted catalog track name, then learn the remaining opaque names from its decrypted contents. Every catalog representation is encrypted; Rust publishers must not emit a plaintext MSF catalog. - A platform that forwards and meters protected bytes must never preview, record, archive, transmux, transcode, transcribe, compose, or inspect them, rejecting those paths before opening a processing session or writing product state. Applications needing those operations terminate E2EE outside the platform. A platform classifies protected broadcasts by its own credential or product state, never by name; the moq.pro (downstream) exclusion classifier and dashboard work stay downstream. -- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams; MoQ Transport has no datagram delivery. +- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams; JavaScript has no MoQ Transport datagram delivery yet. ## Required diff --git a/quest/m1/error-display.md b/quest/m1/error-display.md deleted file mode 100644 index 894f3581d0d..00000000000 --- a/quest/m1/error-display.md +++ /dev/null @@ -1,34 +0,0 @@ -# [M] Every binding prints MoqError's message - -## Goal - -Python's `str(err)`, Go's `err.Error()`, and Dart's `toString()` on a -`MoqError` return the message from moq-ffi's exported `Display`, as Kotlin's -`toString()` and Swift's `description` already do. No hand-written -per-variant strings and no extra message function. - -## Plan - -- #4292 adds `#[uniffi::export(Display)]` on `MoqError` in - `rs/moq-ffi/src/error.rs`, on the C++ line. If it has not reached `main` - when this starts, add the same attribute here; it is additive. -- Go and Dart are fixed in their generators; Python in its wrapper: - - Go: the `kixelated/uniffi-bindgen-go` fork. The generated `Error()` prints - `MoqError: `. Render the exported `Display` for errors, tag, and - bump every pin site the `flake.nix` comment lists. - - Dart: the `kixelated/uniffi-dart` fork. The regenerated bindings already - carry the unused extern; wire it to `toString()`, tag, bump `flake.nix`, - and regenerate `dart/moq_ffi`. - - Python: upstream `mozilla/uniffi-rs` (0.32.2 here) renders no uniffi - traits on errors (`ErrorTemplate.py`). Settled: no upstream PR. The - hand-written `py/moq-rs` package defines `__str__` on `MoqError` by - calling the exported `Display`, so the message still comes from Rust. -- A test per binding that a known error prints Rust's text (`Closed` prints - `closed`), and `doc/lib/{py,go,dart}` updated where they show error output. - -Public API: the string form of `MoqError` changes in Python, Go, and Dart. -Wire: none. - -## Related - -- [C++ through moq-ffi](/quest/m1/cpp/README.md) - where #4292 adds the export and C++ `to_string()` diff --git a/quest/m1/exact-scope.md b/quest/m1/exact-scope.md deleted file mode 100644 index 3e20a7b7067..00000000000 --- a/quest/m1/exact-scope.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] An exact broadcast outside a reader's scope stays hidden - -## Goal - -A reader scoped to `/a/b` never sees an exact broadcast at `/a`, in Rust or -JS. A prefix advertisement at or above the scope still presents as the empty -path, because it may serve paths under the scope; an exact broadcast cannot. - -## Plan - -Decided 2026-09-28: exact match everywhere, aligning on the JS local view. - -- Rust: `sync_cursor` in `rs/moq-net/src/model/origin.rs` admits an exact - entry by prefix overlap. Match exact entries against the reader's patterns - instead. `cursor_keeps_an_overlapping_prefix_above_its_scope` covers a - prefix route and stays. -- JS wire view: `Scope.projectRoutes` in `js/net/src/origin.ts` treats every - entry above the root as covering. Skip exact entries there, as `#listed` - already does with `candidate.exact ? pattern.matches(path)`. -- Add the same case to both languages' tests: an exact broadcast at `/a` and - a prefix route at `/a`, read through a `/a/b` scope, yield only the prefix. - -Public API: none. Wire: a narrower reader receives fewer announcements; no -message changes. diff --git a/quest/m1/export-linger.md b/quest/m1/export-linger.md deleted file mode 100644 index 7c590f12a89..00000000000 --- a/quest/m1/export-linger.md +++ /dev/null @@ -1,39 +0,0 @@ -# [M] moq export: a linger rides out a broadcast that leaves and returns - -## Goal - -Every `moq export ` can outlive a session bounce or a publisher -restart. `--linger ` (default 0) is how long the exporter waits for -the broadcast to be announced again after it goes away; when it returns, the -output resumes after a discontinuity, and while it is gone the output simply -stops (no stuffing, so carrier and content liveness stay one event). The exit -code says how the broadcast ended: 0 when the catalog track finished cleanly, -1 when it was dropped or anything else failed. Today every export subscribes -once and exits 1 with `json: dropped`, even while `moq_tokio` is mid-reconnect -(#3926). - -## Plan - -- A catalog FIN and a drop both wait out the linger, so a planned publisher - restart is covered; when the wait expires, the exit code reflects the last - end. With the default of 0, a FIN exits 0 and a drop exits 1 immediately. -- One implementation in the shared export path: `run_stdout` in - `rs/moq-cli/src/main.rs` and `moq_mux::Source`, not per format. Re-resolve - with `origin::Consumer::routed_broadcast` after the old broadcast ends; the - origin already outlives each session. -- A return is a new catalog on the same exporter: each format writes it the - way it already writes a catalog change or discontinuity (TS sets the - discontinuity indicator and re-emits PSI). A format that cannot express a - restart refuses a non-zero `--linger` at startup. -- `drive()` currently maps every clean task end and every error the same way; - thread the FIN versus drop distinction through to the exit code. -- The fixed-layout exporters report a track that finished before the catalog - as removed: TS as `TS track layout changed ... removed` (reproducible with - `test/ts/run.sh --pair`), FLV as `FLV track ... removed mid-stream`. A clean - end can exit 1 before linger applies. A finished track is not a removed - one; tell them apart in both, with a regression test each (#3926). -- `doc/bin/cli.md`: document `--linger` and the exit codes next to - `export --max-age`. -- Tests: a relay-backed CLI test that restarts the publisher within the linger - and sees output resume, one that lets it expire and checks exit 1, and a - clean FIN that exits 0. diff --git a/quest/m1/ffi-frame-duration-default.md b/quest/m1/ffi-frame-duration-default.md new file mode 100644 index 00000000000..56496f8c79b --- /dev/null +++ b/quest/m1/ffi-frame-duration-default.md @@ -0,0 +1,22 @@ +# [XS] FFI audio encoder takes the codec's own frame by default + +## Goal + +On `dev`, `MoqAudioEncoderOutput::frame_duration_us` defaults to 0, the +codec's own frame, so `MoqAudioCodec::aac()` works without an explicit 0 in +every binding. Opus still encodes 20 ms frames by default. + +## Plan + +- Decided in [#4183](https://github.com/moq-dev/moq/pull/4183): the uniffi + default moves from 20000 to 0. Changing a published binding default is a + break, so this targets `dev`. Split from AudioToolbox encode on 2026-09-30, + since a child of a `main`-bound line cannot land on `dev`. +- `rs/moq-ffi/src/audio.rs` already treats 0 as the codec's frame; the + `default_frame_duration_matches_moq_audio` test that pins 20000 to + moq-audio's default goes away with the literal. +- Update the wrappers and docs that restate 20000: the Python test asserting + the default, `py/moq-rs/README.md`, and `doc/lib/{py,swift,kt,go,dart}`. + libmoq already reads 0 as the default. + +Public API: breaking default in moq-ffi and every binding. Wire: none. diff --git a/quest/m1/ffi-shape/codec.md b/quest/m1/ffi-shape/codec.md index a5668cfc195..629f7b96264 100644 --- a/quest/m1/ffi-shape/codec.md +++ b/quest/m1/ffi-shape/codec.md @@ -22,7 +22,7 @@ The video encoder's output mirrors moq-video's `encode::Gop`: `Keyframe { interval }` variant, defaulting to keyframes at two seconds, and documented as non-exhaustive like the core. The wrappers expose it as an enum their callers construct, not one they are asked to match, so -[intra-refresh bindings](/quest/m2/intra-refresh/bindings.md) adds the refresh +[intra-refresh bindings](/quest/m3/intra-refresh-bindings.md) adds the refresh variant additively instead of breaking `gop` a second time. Go gets no uniffi default, so its zero value must read as keyframe mode. diff --git a/quest/m1/ffi-shape/net.md b/quest/m1/ffi-shape/net.md index 83f99cc8af7..dd45e3ea408 100644 --- a/quest/m1/ffi-shape/net.md +++ b/quest/m1/ffi-shape/net.md @@ -14,10 +14,16 @@ are renamed. nested TLS, QUIC, and backoff records. Validate in `new`. Resolve defaults in Rust, since Go gets none; Option fields keep additions additive. This also retires Kotlin `Moq.connect`'s twelve named parameters. -- The client config carries the protocol versions to offer, as moq-c's - `moq_client_config.versions` already does (`rs/moq-c/src/api.rs`), so every - binding can pin or restrict versions. moq-ffi has no version setter today. -- Objects that are only getters become records. +- The client config carries the protocol versions to offer, as libmoq's + `moq_client_config.versions` already does (`rs/moq-c/src/client.rs:37`), so + every binding can pin or restrict versions. moq-ffi has no version setter + today. +- The cpp line's client-config quest (`quest/m1/cpp/client-config.md` on + branch `quest/m1/cpp/README`) ships this same `MoqClientConfig` record + additively on `main`. Decided in the 2026-09-30 audit: this quest then only + removes the fallible setters on `dev`, rather than designing the record + twice. +- Objects that are only getters become records (`AnnounceUpdate` today). Handles with verbs (`Request`, `TrackRequest`, `GroupRequest`) stay objects. - An enum whose variants a wrapper must name spells each variant `` (`AnnounceEventStart`, `AnnounceEventEnd`) in Go, diff --git a/quest/m1/fin-wait-expiry.md b/quest/m1/fin-wait-expiry.md deleted file mode 100644 index eb163fa6fe6..00000000000 --- a/quest/m1/fin-wait-expiry.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] A group awaiting its FIN ack still expires - -## Goal - -A group whose FIN is written but not yet acknowledged still expires with -`Old` and still follows priority updates, on lite and IETF. Today the -`Closed` arm only awaits `writer.poll_close`, so a stale group keeps its -queued bytes and its old send order, which can stall newer groups behind it. - -## Plan - -The issue ships four failing tests, a `with_fin_gate` test hook, and a fix: - -- lite: poll priority above the state match, not only in `Serve`. -- lite and IETF: in `Closed`, poll `poll_expired_while_pending` and abort with - `Old`. -- moq-tokio: `set_priority` in `Closing` fires the existing interrupt so the - new order applies, instead of only storing it. - -Each priority update rebuilds the `closed()` watch; check the publisher -benchmarks for a regression. The flaky -`subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` -the reporter hit is tracked in [More tests under load](/quest/m1/test-flakes-2.md). - -## Closes - -- [#4332](https://github.com/moq-dev/moq/issues/4332) - close this issue when the quest finishes - -## Related - -- [Starvation](/quest/m1/qos/starvation.md) - its frontier relies on FIN acks, which can now end in `Old` diff --git a/quest/m1/flv-export-delay.md b/quest/m1/flv-export-delay.md new file mode 100644 index 00000000000..4496cb2e952 --- /dev/null +++ b/quest/m1/flv-export-delay.md @@ -0,0 +1,22 @@ +# [S] FLV export releases frames on a fixed delay + +## Goal + +`moq export flv --delay ` interleaves tracks through the shared +fixed-delay release stage, so its tag order is a function of the media, not +of arrival, as the TS export's is. + +## Plan + +Today `pick_next_track` (`rs/moq-mux/src/container/flv/export.rs`) takes the +smallest *pending* timestamp, so which track goes first depends on which frame +has arrived. Replace it with the release stage from +[fixed-delay release](/quest/m1/tstd/delay.md), with the same `--delay` flag +and the same late-frame drop. Update `doc/bin/cli.md`. + +Public API: the exporter gains a delay setting; breaking only if it replaces +an existing one. Wire: none. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - builds the shared release stage diff --git a/quest/m1/flv-rebind.md b/quest/m1/flv-rebind.md deleted file mode 100644 index 4aacafda746..00000000000 --- a/quest/m1/flv-rebind.md +++ /dev/null @@ -1,14 +0,0 @@ -# [XS] FLV rebind before header - -## Goal - -A single-track FLV export whose first catalog snapshot lacks the best -rendition switches to it if it appears before the stream header goes out, so -the pick doesn't depend on catalog timing. - -## Plan - -`flv::Export` binds from the first snapshot and ignores later ones in -single-track mode. Before the header, a better-ranked rendition could replace -the bound one; after it, FLV can't introduce a new config, so the current track -stays. Mock time in the test. diff --git a/quest/m1/frame-slot-charge.md b/quest/m1/frame-slot-charge.md index d7c199e5aab..4b61d31b08a 100644 --- a/quest/m1/frame-slot-charge.md +++ b/quest/m1/frame-slot-charge.md @@ -48,6 +48,6 @@ that was OOM-killing relays serving chat, and deliberately left out of it. Public API: none, unless `MAX_CACHE_BYTES` is restated. Wire: none. -## Related +## Required -- [Relay memory](/quest/m1/relay-memory.md) - the per-announcement half of the same question, whose figures also predate the current accounting +- [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - edits the same group cache charge; land it first diff --git a/quest/m1/gpu-ci.md b/quest/m1/gpu-ci.md index 64bacaeeec2..b3b0d6175df 100644 --- a/quest/m1/gpu-ci.md +++ b/quest/m1/gpu-ci.md @@ -26,8 +26,7 @@ skipping inside the Nix shell. tests (Android, D3D11, PipeWire). Inside that selection a missing GPU fails the test instead of returning early. Keep the no-driver tests (`missing_driver_errors_instead_of_panicking`) outside it. -- `just rs nvidia`, a one-line recipe over `sh/rs/nvidia.sh` in the tooling - line's `sh//` layout: symlink only those three libraries (by +- `just rs nvidia`, a one-line recipe over `sh/rs/nvidia.sh`: symlink only those three libraries (by soname) from `/usr/lib/x86_64-linux-gnu` into a private directory, put that on `LD_LIBRARY_PATH`, and run that selection. Fail when a library is missing instead of skipping. `just rs vulkan-cuda` (`sh/rs/vulkan-cuda.sh`) puts the @@ -52,10 +51,8 @@ Public API: none. Wire: none. ## Required -- [Tooling](/quest/m1/tooling/README.md) - the `sh/` script layout and recipe-only workflows this follows - A self-hosted runner is registered for moq-dev/moq on the maintainer's host, with the NVIDIA driver ## Related - [Video hardware validation](/quest/m3/video-hardware.md) - hardware paths nothing runs yet -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - on-demand jobs on hardware hosts, a broader contract than a nightly diff --git a/quest/m1/gst-opus-surround.md b/quest/m1/gst-opus-surround.md new file mode 100644 index 00000000000..8b7a195ebcf --- /dev/null +++ b/quest/m1/gst-opus-surround.md @@ -0,0 +1,21 @@ +# [S] Surround Opus from GStreamer + +## Goal + +`moq-gst`'s sink publishes a 3 to 8 channel `audio/x-opus` stream with the +OpusHead its caps describe, so surround Opus from `opusenc` plays natively like +the same stream from Matroska or MPEG-TS. + +## Plan + +- The sink refuses more than two channels because it builds the head from + `channels` and `rate` alone. Multichannel Opus caps also carry + `channel-mapping-family`, `stream-count`, `coupled-count`, and + `channel-mapping`; build the mapping with `opus::Mapping::new`, which + validates them, and refuse caps that omit or contradict them. +- Prefer a `streamheader` OpusHead when the caps carry one, if that path is + simpler and covers the same streams. +- Regression: an `opusenc` 5.1 pipeline publishes a family 1 description that + `moq-audio` decodes to six channels. + +Public API: none. Wire: none. diff --git a/quest/m1/he-aac-catalog-output.md b/quest/m1/he-aac-catalog-output.md new file mode 100644 index 00000000000..9032995d6e9 --- /dev/null +++ b/quest/m1/he-aac-catalog-output.md @@ -0,0 +1,29 @@ +# [S] HE-AAC catalog entries describe the output + +## Goal + +A catalog entry for HE-AAC or HE-AACv2 names what the stream plays as, for +example 48 kHz stereo, not its AAC-LC core (24 kHz, and mono for v2). Players +and gateways that size buffers or pick a decoder from the catalog see the real +output. + +## Plan + +- `Config::parse` reports the core rate and channel count because those lead + an explicit SBR or PS AudioSpecificConfig. The FLV and MKV importers copy + them into the catalog; fMP4 takes the sample entry instead, so the importers + disagree for the same stream. +- Derive the output from the config: the extension rate under SBR, two + channels under PS. Implicit SBR, found only in band, cannot be known from the + config; keep the documented half-rate behavior for it. +- Consumers that rebuild a config from catalog fields (description synthesis in + `moq-audio`, the MSF path) must not then mistake the output rate for the core. +- Regression: the `fdkaacenc` HE-AAC and HE-AACv2 FLV fixtures under + `rs/moq-mux/src/container/ts/test_data` import as 48 kHz stereo, matching + ffprobe. + +Public API: possibly `Config` fields. Wire: catalog values change for HE-AAC. + +## Related + +- [#4283](https://github.com/moq-dev/moq/pull/4283) - found while labeling HE-AAC for ADTS diff --git a/quest/m1/hls-linger.md b/quest/m1/hls-linger.md deleted file mode 100644 index 9da2c54d1c4..00000000000 --- a/quest/m1/hls-linger.md +++ /dev/null @@ -1,41 +0,0 @@ -# [S] moq-hls keeps an ended broadcast for its playlist window - -## Goal - -A player polling `moq_hls::Server` can finish the last segments of a broadcast -that just ended, and a republish of the same name takes over cleanly. Today -`Server` evicts a broadcaster as soon as its broadcast closes, so the playlist -404s mid-window. The moq.pro edge works around it with its own pool on top of -`Broadcaster` that holds an ended broadcast for the playlist window plus a -grace period and checks for a republish -([#3964](https://github.com/moq-dev/moq/pull/3964)). Once moq-hls owns this, -the edge deletes its pool. - -## Plan - -Decided: moq-hls owns the retention through an `export::Config` field (the -playlist window plus a grace period), so every embedder gets it and the edge -has nothing to duplicate. `Config` is `#[non_exhaustive]`, so the field is -additive on `main`. - -Guidance: - -- The eviction lives in `server/mod.rs` (`evict_closed` and the - `is_closed` checks in `Server::broadcaster`). An ended broadcaster keeps - serving its final playlist, marked ended if the renditions know it, until - the linger expires. -- A republish during the linger replaces the ended broadcaster. Decide - whether a request for the name resolves the new broadcast first and falls - back to the ended one only when nothing is announced; match what the edge - pool does today. -- Segments are fetched from the relay cache on request, so the linger is only - useful within the cache's retention; say so on the field, as `window` does. -- A zero linger keeps today's behavior. Pick the default with the edge's - current value in mind. -- Tests: a request inside the linger after close still gets the playlist and - a cached segment; after it expires the name 404s; a republish inside the - linger is served. - -## Related - -- [Export linger](/quest/m1/export-linger.md) - the CLI exporter's wait for a broadcast to return; same idea, separate code diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index a322d4200eb..56ec73b95bc 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -13,7 +13,11 @@ exits (#4354). ## Plan Decided: same-hop publishers MUST publish the same broadcasts and tracks. -Keep `--hop`, and make every container importer (ts, fmp4, flv, mkv, and the +Keep `--hop` for now: the users' bugs are on one relay today. Cluster +routing replaces it with a shared explicit epoch on `dev` (decided +2026-09-30), and its [`--hop` removal](/quest/m1/hop-removal.md) +re-keys this quest's docs and tests. The importer work holds under either +key. Make every container importer (ts, fmp4, flv, mkv, and the SRT, RTMP, and HLS gateways that reuse them) meet the contract when fed one encoded stream. Capture is out: two encoders never align. @@ -40,5 +44,5 @@ survives the standby joining and the incumbent stopping. ## Related -- [Redundant ingest](/quest/m2/redundant-ingest.md) - splicing across first hops and two encoders, which this does not attempt +- [Remove `--hop`](/quest/m1/hop-removal.md) - on dev, a redundant pair shares an explicit epoch instead, and this quest's docs and tests are re-keyed to it - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch diff --git a/quest/m1/hop-removal.md b/quest/m1/hop-removal.md new file mode 100644 index 00000000000..7000837b894 --- /dev/null +++ b/quest/m1/hop-removal.md @@ -0,0 +1,45 @@ +# [M] Redundant publishers share an epoch, not a hop + +## Goal + +Redundant publishers share an explicit `@` instead of a `--hop`, and +the publisher-facing Hop ID is gone: `moq`'s `--hop` / `MOQ_HOP` and the +deprecated `--origin` spelling, and the Hop setup parameter a publisher +sends. An epoch is strictly better, since a Hop ID is per session: one +connection cannot publish several broadcasts with different identities. + +## Plan + +- The pool semantics already live in + [Selection](/quest/m1/cluster-routing/selection.md): origins announcing the + same epoch-qualified concrete path are one source. This quest deletes what + that makes dead, including `Pin::Publisher(Hop)` in + `rs/moq-net/src/model/front.rs` and `RouteEntry::qualifies`. +- A redundant pair passes one explicit epoch; the broadcast-publish path keeps + an epoch a caller supplies ([Broadcast epochs](/quest/m1/broadcast-epoch/README.md)). + Give `moq` a flag for it if Broadcast epochs has not. +- Relays keep `cluster.id` as their identity; `--hop` fills it today + (`rs/moq-cli/src/args.rs`), so split that coupling. Decide whether relays + still need the Hop setup parameter or learn identity from topology. +- Re-key [Same-hop importers](/quest/m1/hop-aligned-import.md)'s docs and 1+1 + tests to a shared epoch. +- Docs: rewrite "Redundant publishers" in `doc/bin/cli.md` and + `doc/concept/use-case/contribution.md`, then search the repo for `--hop`, + `MOQ_HOP`, and `--cluster-id` examples, including demo recipes. + +Open: whether anything declares an incumbent dead faster than the cluster +idle timeout (a failover service that retracts it, or active-active delivery +to the relay). Neither is required to land this. + +Public API and wire: removes a CLI flag and the publisher's Hop setup +parameter; lands on `dev`, outside the cluster routing line (which lands on `main`). + +## Required + +- [Selection](/quest/m1/cluster-routing/selection.md) - owns the same-epoch pool this relies on +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a restart is a new path, not a splice +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - the importer fixes this re-keys + +## Related + +- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - bounds how long a dead incumbent holds its pair diff --git a/quest/m1/ietf-cluster-off.md b/quest/m1/ietf-cluster-off.md new file mode 100644 index 00000000000..4c8bd4be470 --- /dev/null +++ b/quest/m1/ietf-cluster-off.md @@ -0,0 +1,40 @@ +# [S] moq-transport peers are plain clients + +## Goal + +No moq-transport session negotiates the MoQ Cluster extension +(`draft-lcurley-moq-cluster`). A moq-transport peer is always served as a +plain client: it never receives Hop IDs or relay costs and never acts as a +cluster link. Cluster links are moq-lite only. moq-transport end users stay +fully supported. + +## Plan + +Why now: the Wildcard line spreads a pool's paths behind one route, and names +the serving member only in lite-07's reply Origin. The cluster extension has +no such field, so a moq-transport downstream relay pins failover to the +advertisement's first Hop ID, which labels the pool rather than the member, +and can splice one member's objects onto another's. A peer that never learns +Hop IDs cannot make that mistake. Decided in the 2026-09-30 wildcard audit, +matching the topology decision that cluster links are lite-only. + +- Stop offering and accepting the cluster Setup Options in Rust + (`rs/moq-net/src/ietf/cluster.rs`, `parameters.rs`, `publish_namespace.rs`) + and JS (`js/net/src/ietf/cluster.ts` and its callers). A peer that offers + them is served as if it had not. +- Delete what becomes dead, in both languages. The draft stays: + [moq-transport cluster peers](/quest/m2/ietf-cluster-peers.md) extends it + and brings the code back. +- Update `doc/bin/relay/cluster.md` and `doc/concept` wherever they say + moq-transport relays can join a cluster. +- Test: a moq-transport 17+ peer that offers the extension gets a session + with no cluster parameters, and an announcement reaches it with no Hop IDs. + +Lands on `main`: extension negotiation is optional, so a peer that offered it +still gets a working session. Public API: none expected. Wire: we stop +negotiating an optional extension. + +## Related + +- [Edge and core](/quest/m1/cluster-routing/roles.md) - cluster links are lite-only +- [Wildcard](/quest/m0/wildcard/README.md) - the pool spread that makes a Hop ID label unsafe to splice on diff --git a/quest/m2/ietf-drain-before-close.md b/quest/m1/ietf-drain-before-close.md similarity index 100% rename from quest/m2/ietf-drain-before-close.md rename to quest/m1/ietf-drain-before-close.md diff --git a/quest/m1/ietf-fetch-location.md b/quest/m1/ietf-fetch-location.md new file mode 100644 index 00000000000..54daf01a6a2 --- /dev/null +++ b/quest/m1/ietf-fetch-location.md @@ -0,0 +1,23 @@ +# [S] Draft-20 FETCH + +## Goal + +On drafts 20 and later, a FETCH whose LOCATION_FILTER stays within one group +is answered the way drafts 14 to 19 answer a standalone FETCH: from cache, with +a miss fetched upstream, and an upstream refusal passed through. A range +touching several groups is refused `NOT_SUPPORTED`, as on older drafts. + +## Plan + +Today both sides refuse FETCH on draft-20+ `NOT_SUPPORTED`: the publisher in +`run_fetch_stream`, and the relay's upstream group fill in `run_group_fetch`, +because the codec still carries the removed Fetch Type field. +[Legal IETF input](/quest/m0/ietf-legal-input.md) fixes the codec. Then drop +both refusals, and flip `fetch_moq_transport_20` in `rs/moq-tokio/tests` back +to a served fetch. + +Update the draft-20 note in `doc/concept/standard.md`. + +## Required + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - decodes the draft-20 FETCH this serves diff --git a/quest/m1/ietf-fetch-only.md b/quest/m1/ietf-fetch-only.md new file mode 100644 index 00000000000..a7bdc908e66 --- /dev/null +++ b/quest/m1/ietf-fetch-only.md @@ -0,0 +1,29 @@ +# [M] Fetch without SUBSCRIBE + +## Goal + +A relay serves a FETCH-only demand for an IETF upstream track without +SUBSCRIBE upstream. A finished upstream track can still be fetched, and a +FETCH_OK that reaches the end of the track says so every time. + +## Plan + +The origin splices a route only once the track's info is known. moq-lite gets +it from TRACK_INFO, so its fetch-only demand never subscribes. IETF has no +TRACK_INFO, so today fetch-only demand still makes the relay SUBSCRIBE upstream. +Two symptoms follow: + +- A finished upstream track refuses the SUBSCRIBE, so its groups cannot be + fetched either. +- The live subscription races the group FETCHes. End of Track is known only + once an upstream FETCH_OK reports it, so a downstream FETCH that runs to the + end can answer before that and leave End of Track unset. moxygen's "FETCH + with large objects" case flakes on this. + +TRACK_STATUS is the likely source of the info. The publisher refuses it today, +so both sides are in scope. Keep the SUBSCRIBE path for real subscription +demand. + +## Related + +- [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher answers these fetches diff --git a/quest/m1/ietf-hidden-default.md b/quest/m1/ietf-hidden-default.md deleted file mode 100644 index 0004b8c584c..00000000000 --- a/quest/m1/ietf-hidden-default.md +++ /dev/null @@ -1,53 +0,0 @@ -# [S] IETF peers without MoQ Hidden see hidden namespaces - -## Goal - -A moq-transport peer that did not declare the MoQ Hidden setup option is -advertised every namespace, hidden ones included. A peer that declared it -keeps today's behavior: hidden namespaces are left out unless its -SUBSCRIBE_NAMESPACE opts in. Rust and JS publishers agree, and -`drafts/draft-lcurley-moq-hidden.md` says so. - -Today the rule applies whether or not the peer declared the option, so a -third-party IETF client can never see a hidden namespace except by naming its -dot segment in the prefix. - -## Plan - -Maintainer decisions: - -- Hiding exists to keep existing moq-lite customers (lite-06 and older) from - seeing new `.pro/` broadcasts. None of them use an IETF client, and the - extension will not be adopted by the IETF draft, so an IETF peer that - never heard of it gets everything. A peer that declares it chooses per - subscription whether to filter on the wire. -- Our own IETF clients already declare the option and filter locally when a - reader does not ask for hidden, so their behavior does not change. -- moq-lite is unchanged: lite-06 and older never see hidden paths, and lite-07 - opts in. - -Guidance: - -- Both publishers, both the SUBSCRIBE_NAMESPACE path and the unsolicited - PUBLISH_NAMESPACE path, and draft-14/15 (PUBLISH_NAMESPACE requests) as well - as 16+ (inline NAMESPACE entries). -- Rewrite the draft's "applies whether or not the peer declared the option" - rule and keep `just drafts check` green. `doc/concept/moq-lite.md` also - says a peer without the extension never discovers hidden routes, as do the - module docs in `rs/moq-net/src/ietf/hidden.rs` and `js/net/src/ietf/hidden.ts`; - update them in the same change. -- It is a wire behavior change in both languages, so run - `just test interop --all` before landing. -- Tests: an undeclared peer sees hidden namespaces, a declared peer without - the parameter does not, on at least one pre-16 and one 16+ draft. Also fill - the gaps where nothing is tested today: draft-14/15 with hidden, JS IETF - without solicitation, and local filtering when a peer sends hidden paths the - reader did not ask for. -- Hiddenness is measured from the requested prefix, as the draft already - defines it and JS already does. Rust measures from the publish origin's - scope heads instead, so a publish scope like `.stats/**` exposes - `.stats/node` to a request for the empty prefix; bring Rust in line and test - that case in both languages. - -Public API: none. Wire: behavior change for IETF peers that did not declare -MoQ Hidden. diff --git a/quest/m1/ietf-timestamp-units.md b/quest/m1/ietf-timestamp-units.md new file mode 100644 index 00000000000..cb9343378e2 --- /dev/null +++ b/quest/m1/ietf-timestamp-units.md @@ -0,0 +1,27 @@ +# [XS] IETF drafts 14-16 send no timestamps without units + +## Goal + +On moq-transport drafts 14 through 16, where TIMESCALE can't be sent, the Rust +and JS publishers write no Timestamp object property, as +`drafts/draft-lcurley-moq-timestamp.md` requires ("A publisher that emits +Timestamps MUST send TIMESCALE"). + +## Plan + +Rust sets `has_extensions: self.timescale.is_some()` +(`rs/moq-net/src/ietf/publisher.rs`), but `Properties::encode` never writes +the TIMESCALE block before draft-17 (`rs/moq-net/src/ietf/properties.rs`), so +drafts 14-16 carry timestamps without units. The Rust subscriber ignores them. +Gate the Timestamp property on a timescale actually sent. Check js/net's +`stamped` flag (`js/net/src/ietf/publisher.ts`) for the same gap. + +Before landing, check whether an interop peer on draft-14 reads the Timestamp +property without TIMESCALE. If one does, ask whether to keep it. + +Fix the stale `track::Info::timescale` doc (`rs/moq-net/src/model/track.rs`), +which says IETF always falls back to local milliseconds; draft-17 and later +carry TIMESCALE. + +Wire: stops sending a property peers can't interpret, on published drafts. +Public API: none. Lands on `main`. diff --git a/quest/m1/interop-audio-cold-start.md b/quest/m1/interop-audio-cold-start.md deleted file mode 100644 index 78c2522dd06..00000000000 --- a/quest/m1/interop-audio-cold-start.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Interop audio tone survives a cold start - -## Goal - -The interop "Media output and lifecycle" step stops failing the audio tone -check on cold start. The 2026-09-28 nightly on `main` failed with -`FAIL audio tone: cold start: 55/64 samples carried the fixture tone above the -noise floor`, against a 90% agreement floor. - -## Plan - -- Reproduce it: run the interop media step in a loop on a loaded machine - until the cold-start row fails, and capture which samples miss (the first - ones, or scattered). -- Find the cause before touching the check: the likely suspects are decoder - or playout warm-up after the context resumes. [Publish channel count](/quest/m1/publish-audio-channel-count.md) - saw the same symptom, but `test/interop/clients/js/src/fixture.ts` already - dropped the `channelCount` override, so that's not it. -- Fix it at the source. The cold-start window deliberately starts once the - context runs, without waiting for a tone, so a slow start has to fail - there. Keep that window: if the misses are the first samples, find what - delays the first audible output instead of moving the window. Don't lower - `AGREEMENT` (`test/interop/clients/js/media.ts`) without a measured reason. - -Public API: none. Wire: none. - -## Related - -- [More tests under load](/quest/m1/test-flakes-2.md) - the other load-only failures diff --git a/quest/m1/iroh-lite-wip.md b/quest/m1/iroh-lite-wip.md deleted file mode 100644 index f6be7e23dc7..00000000000 --- a/quest/m1/iroh-lite-wip.md +++ /dev/null @@ -1,31 +0,0 @@ -# [XS] iroh honors the configured versions - -## Goal - -An `iroh://` client or listener configured with `moq-lite-07-wip` negotiates -it, as `https://`, `moqt://`, TCP, and Unix sockets already do. A version -list that iroh cannot offer is refused at startup, never silently replaced. - -## Plan - -https://github.com/moq-dev/moq/pull/4148 took `moq-lite-07-wip` out of -`moq_net::ALPNS` so it is opt-in only, but `rs/moq-tokio/src/iroh.rs` builds -its listener ALPNs, its dial offers, and its H3 subprotocols from that -constant rather than the configured `Versions` (`versions.alpns()`, which -`noq.rs`, `server.rs`, and `client.rs` use). So the opt-in is accepted by -config and then ignored on iroh. Thread the configured versions through -instead. - -`moq-ffi`'s transport (`rs/moq-ffi/src/transport.rs`) also offers -`moq_net::ALPNS` directly; fix it here too. The relay's WebSocket listener -already honors the configured versions. Scope is those two files. - -Decided by the maintainer: the finalized lite-07 ALPN stays `moq-lite-07`, -as `drafts/draft-lcurley-moq-lite.md` already says. Peers from the yanked -0.3.2 / 0.15.3 releases advertise `moq-lite-07` with an older framing, and -could land on it with a finalized peer; the maintainer accepts that risk -rather than burn the identifier. Nothing in this quest changes the ALPN. - -## Related - -- [iroh opt-in for moq-relay](/quest/m1/relay-iroh-opt-in.md) - a separate change: whether the relay builds iroh at all diff --git a/quest/m1/js-dops-pre-skip.md b/quest/m1/js-dops-pre-skip.md deleted file mode 100644 index 273669a0f91..00000000000 --- a/quest/m1/js-dops-pre-skip.md +++ /dev/null @@ -1,12 +0,0 @@ -# [XS] js/hang dOps without an invented pre-skip - -## Goal - -`js/hang` CMAF encoding stops writing a hard-coded 312-sample pre-skip into -`dOps` when the track has no description, so a remuxed track never trims audio -its encoder did not ask to trim. - -## Plan - -Without an OpusHead there is no known pre-skip; write 0 or refuse, whichever -matches how the Rust exporter (`synthesize_audio_trak`) handles the same case. diff --git a/quest/m1/js-fetch-cancel.md b/quest/m1/js-fetch-cancel.md deleted file mode 100644 index e7371fb4fd5..00000000000 --- a/quest/m1/js-fetch-cancel.md +++ /dev/null @@ -1,25 +0,0 @@ -# [S] A JS fetch can be cancelled - -## Goal - -A `@moq/net` caller can abandon one pending group fetch without closing the -track or session, the follow-up #4357 left. - -## Plan - -Decided 2026-09-28: `FetchGroupOptions` (`js/net/src/track.ts`) gains -`signal?: AbortSignal`, the standard JS idiom, and additive. - -- Thread it through `js/net/src/broadcast.ts` and `lite/subscriber.ts`. - `ietf/subscriber.ts` rejects `fetchGroup` today (moq-transport has no - one-shot group fetch), so it stays unchanged. -- Fetches for the same group share one stream (`lite/subscriber.ts`), so an - abort releases this caller's share and rejects its promise with the - signal's reason. The stream is cancelled only when the last sharer leaves. -- An already-aborted signal rejects before anything is sent. -- Tests: one of two sharers aborts and the other still receives the group; - the last sharer aborting cancels the stream. -- Document the option where fetch is documented under `doc/`. - -Public API: additive `FetchGroupOptions.signal`. Wire: none new; the -existing cancel path. diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index a02da35c4ce..50ac6349eb8 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -43,4 +43,4 @@ A published API break, if the chosen shape requires one, goes through dev. ## Related -- [Browser archive](/quest/m1/archive/browser.md) - supplies memory or OPFS archive data through this generic request surface +- [Browser archive](/quest/m2/archive-browser.md) - supplies memory or OPFS archive data through this generic request surface diff --git a/quest/m1/js-ietf-datagram.md b/quest/m1/js-ietf-datagram.md index db210e7b25a..7ecfb8faabc 100644 --- a/quest/m1/js-ietf-datagram.md +++ b/quest/m1/js-ietf-datagram.md @@ -1,29 +1,21 @@ -# [M] @moq/net datagrams over moq-transport +# [M] JavaScript moq-transport datagrams ## Goal -A `@moq/net` session on moq-transport sends and receives datagram groups as -`OBJECT_DATAGRAM`, one object per group with its sequence kept, as Rust does. -A datagram track crosses IETF between Rust and JS in both directions in -`just test interop`. +`@moq/net` sends and receives datagrams over moq-transport as +`OBJECT_DATAGRAM`, matching Rust: one Object at ID 0 is a single-frame group +whose Group ID is the sequence. A JavaScript publisher's datagrams reach a Rust +subscriber, and a Rust publisher's reach a JavaScript one. ## Plan -- JS routes datagrams on moq-lite only (`js/net/src/lite/datagram.ts`, - `runDatagrams` from lite-05); `js/net/src/ietf/` reads and writes none. - Mirror the lite path on the IETF session and the Rust mapping from #4274: - receive decodes `OBJECT_DATAGRAM` and inserts on the aliased subscription's - track; send writes object 0 with END_OF_GROUP, the explicit publisher - priority, and the timestamp property when the track has a timescale. -- Keep Rust's edges: an Object ID other than 0, a non-Normal status, or an - unbound alias is dropped; a malformed Type closes the session. Rust covers - drafts 14 and later, whose Type flags differ between 14 and 15+; decide - what draft 07, which JS also speaks, does. -- Add IETF datagram cases beside the lite ones in the interop harness. +Port `rs/moq-net/src/ietf/datagram.rs` and the session's send and receive +loops. Decode every draft's Type flags, drop what the model cannot carry the +same way Rust does, and close the session on a malformed Type. -Public API: none expected. Wire: `@moq/net` moq-transport sessions send and -accept `OBJECT_DATAGRAM` as the drafts define; no project draft changes. +The integration test `ietf does not deliver datagrams` flips to delivery on +every supported draft, and `just test interop --all` covers both directions. -## Required +## Related -- [moxygen interop](/quest/m1/moxygen/README.md) - its datagram groups quest (done on the line) is the Rust side this mirrors and interops with +- [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - the subscribe range for datagrams, settled on both protocols diff --git a/quest/m1/js-ietf-reprice.md b/quest/m1/js-ietf-reprice.md deleted file mode 100644 index 9378a100add..00000000000 --- a/quest/m1/js-ietf-reprice.md +++ /dev/null @@ -1,19 +0,0 @@ -# [S] JS IETF reprices a namespace in place - -## Goal - -When a route's price changes but its original publisher does not, `@moq/net`'s IETF publisher reprices the namespace the peer already holds in place, as Rust does, instead of withdrawing it and advertising it again. A subscriber never sees a namespace briefly vanish because its cost or hop chain moved, unless the peer refuses or ignores the update. - -## Plan - -Rust already does this in `rs/moq-net/src/ietf/publisher.rs` (`sync_namespace`, `update_namespace`). `js/net/src/ietf/publisher.ts` withdraws first on both paths, so that "a republish or re-price reads as withdraw-then-advertise". Match Rust: - -- PUBLISH_NAMESPACE: send REQUEST_UPDATE on the request that carries the namespace, with only the changed parameters, and wait for its answer so one update is outstanding per stream (which satisfies MAX_REQUEST_UPDATES). A REQUEST_ERROR withdraws it and an unanswered update drops the request; the retry re-offers it fresh, honoring a REQUEST_ERROR's retry interval as Rust's `refusal` does (from draft-16, 0 means never). -- Inline (a solicited SUBSCRIBE_NAMESPACE, draft-16+): re-send NAMESPACE on the response stream, which the receiver treats as a replacement, without NAMESPACE_DONE first. -- A different broadcast still withdraws and advertises again. A different original publisher (first hop) still withdraws too, as the draft requires today; [cluster publisher in place](/quest/m1/cluster-publisher-in-place.md) builds on this quest to update it in place (decided 2026-09-28). - -The wire-visible comparison from the announce-dedupe work decides whether anything is sent at all. - -Found while landing the announce update dedupe (#4423). No wire change: REQUEST_UPDATE is already in the IETF drafts the tree negotiates. - -Tests: a price change on a held namespace sends one REQUEST_UPDATE and no PUBLISH_NAMESPACE_DONE; a nonzero cost repriced to 0 carries an explicit cost 0, since REQUEST_UPDATE keeps an omitted parameter; a hop path change behind the same first hop sends one REQUEST_UPDATE carrying HOP_PATH and no withdrawal; a solicited namespace is repriced with one NAMESPACE and no NAMESPACE_DONE; a republish still withdraws on both paths (inline: NAMESPACE_DONE, then NAMESPACE), as does a first-hop change until the cluster quest; a REQUEST_ERROR withdraws, and its retry interval holds the re-offer back (never, for 0 from draft-16); with mocked time, a second change while an update is unanswered sends nothing until it resolves, and an update that times out drops the request and re-offers the namespace on a fresh one. diff --git a/quest/m1/js-prune-cache-window.md b/quest/m1/js-prune-cache-window.md new file mode 100644 index 00000000000..c955c2244e1 --- /dev/null +++ b/quest/m1/js-prune-cache-window.md @@ -0,0 +1,28 @@ +# [S] js/net ages cached groups on a cache window, not max_age + +## Goal + +js/net retains cached groups the way Rust does. A wall-clock idle window +bounds memory, and `max_age` is only the media-time staleness budget, so a +congestion stall can't age content out of a JS publisher's cache. + +## Plan + +`#prune` (`js/net/src/track.ts`) evicts a group after `info.maxAge` of +wall-clock idleness, measured on the group's `activity`. Rust keeps those +apart: `track::Info::max_age` is measured in media timestamps, and the cache +pool's `expiry` is the separate wall-clock bound +(`rs/moq-net/src/model/cache.rs`). Give js/net a cache window of its own for +idle eviction, as Rust's pool has, and leave `maxAge` to `#drift` / +`#isStale`. Add a test with mocked time where a stalled track keeps its groups +past `maxAge`. + +[Generated @moq/net](/quest/m1/rs2ts/README.md) will replace this code with +Rust's model; the maintainer chose to fix it by hand first. + +Public API: none unless the window is configurable (keep it private). Wire: +none. + +## Related + +- [Generated @moq/net](/quest/m1/rs2ts/README.md) - retires js/net's hand-written model diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md new file mode 100644 index 00000000000..40fbc836a1b --- /dev/null +++ b/quest/m1/js-publish-timestamp.md @@ -0,0 +1,18 @@ +# [M] JS publishing requires a timestamp + +## Goal + +`@moq/json`, `@moq/flate`, and `@moq/net` publish APIs take a timestamp and +never fill in `Timestamp.now()` for the caller, mirroring +[Publishing requires a timestamp](/quest/m1/publish-timestamp.md). + +## Plan + +Today the json and flate snapshot and stream producers default +`at = Timestamp.now()`, the json window producer always uses now, and js/net's +`writeString`, `writeJson`, and `writeBool` stamp now. Make the timestamp a +required argument on each, with the same shape as Rust's `Timed`. Callers in +the repository (js/hang catalog, js/publish, js/room) pass their clock's now +explicitly. Update `doc/lib/js/{json,binary,net}.md`. + +Public API: breaking, on `dev`. Wire: none. diff --git a/quest/m1/js-track-close-end.md b/quest/m1/js-track-close-end.md deleted file mode 100644 index c86f3e16610..00000000000 --- a/quest/m1/js-track-close-end.md +++ /dev/null @@ -1,20 +0,0 @@ -# [XS] A JS track's clean close ends at its own last group - -## Goal - -`close()` on a JS track producer declares the final sequence from the groups -that track actually produced, like Rust's `finish()` uses its own -`max_sequence`. A sibling producer on the same broadcast and name can no -longer push the end past groups this track will ever send. - -## Plan - -- `close()` in `js/net/src/track.ts` calls `#declareFinal(this.#sequence.next)`, - and `#sequence` is shared per broadcast and track name (`bindProducer`). - Use the track's own `#received` high-water mark instead, which #4385 added - and only `#settled` reads today. -- Re-check `finishAt` for the same shared-counter assumption. -- Regression test: two producers on one name, the sibling creates later - groups, and the closed track's final sequence is its own last group + 1. - -Public API: none. Wire: none. diff --git a/quest/m1/json-compressed-gate-rs.md b/quest/m1/json-compressed-gate-rs.md deleted file mode 100644 index 0e84456b811..00000000000 --- a/quest/m1/json-compressed-gate-rs.md +++ /dev/null @@ -1,17 +0,0 @@ -# [XS] Rust test for the compressed snapshot gate - -## Goal - -`rs/moq-json`'s snapshot encoder has a test proving that a delta is admitted -by its encoded size, not its plaintext: a sync-flushed DEFLATE frame can come -out larger than its input, so a plaintext gate lets a patch overflow the -group and evict the snapshot a late joiner needs. The JS encoder gained this -test in the PR that retired `quest/m1/test-flakes.md`. - -## Plan - -- The gate compares against `moq_net::group::MAX_CACHE_BYTES`, which is too - large to reach cheaply. Mirror the JS approach: a crate-private budget the - test can shrink, so it measures real frames and sets a budget between the - patch's plaintext and encoded sizes. -- Confirm the test fails when the gate measures the plaintext. diff --git a/quest/m1/json-rolls-snapshot-test.md b/quest/m1/json-rolls-snapshot-test.md deleted file mode 100644 index 653d9eba4c2..00000000000 --- a/quest/m1/json-rolls-snapshot-test.md +++ /dev/null @@ -1,14 +0,0 @@ -# [XS] Shrink the JS snapshot overflow test - -## Goal - -The `js/json` test "a delta that would overflow the snapshot rolls a new one -instead" stops building two ~19 MiB values (about 1 s idle, several under -load) and exercises the same roll with a few bytes, through the encoder's -internal `maxGroupBytes` budget. - -## Plan - -- Keep one assertion that the default budget is moq-net's group cache limit, - so the shrunk test doesn't hide a drift between the two. -- Confirm the test fails when the gate is removed. diff --git a/quest/m1/legacy-end-overshoot.md b/quest/m1/legacy-end-overshoot.md index 5c83b136f8b..6fdd917ab48 100644 --- a/quest/m1/legacy-end-overshoot.md +++ b/quest/m1/legacy-end-overshoot.md @@ -30,14 +30,15 @@ keyframes included, may dip below the previous group's content (B-frames, or a keyframe overlapping its last frame), so an estimated end is never a hard edge. A group may start at the same timestamp as the previous one; strictly increasing starts are not enforced. Group IDs never move backwards. A group -starting before the previous group's start is a restart, a new broadcast. The Rust `moq-mux` producer and -consumer enforce this since #4543. +starting before the previous group's start is a restart, a new broadcast. +The Rust `moq-mux` producer and consumer enforce this on `dev` since #4543. - Reproduce with a mocked clock: cut a group, then resume with a keyframe between the last frame and the estimated end. - Align `js/hang/src/container/consumer.ts` (and the JS producer, if it differs) to "group starts monotonic", matching `rs/moq-mux/src/container`. +- Target `dev`, where the #4543 rule lives. ## Related -- [More tests under load](/quest/m1/test-flakes-2.md) - other load-only failures, fixed at the cause +- [More tests under load](/quest/m1/test-flakes-2/README.md) - other load-only failures, fixed at the cause diff --git a/quest/m1/lite-late-lower-group.md b/quest/m1/lite-late-lower-group.md new file mode 100644 index 00000000000..451ed6ec016 --- /dev/null +++ b/quest/m1/lite-late-lower-group.md @@ -0,0 +1,63 @@ +# [S] moq-lite delivers a late group above the subscriber's floor + +## Goal + +A moq-lite subscriber with an explicit floor receives every group at or above +that floor that its `max_age` still considers fresh, whatever order the +publisher created them in, as moq-transport already does. Today the lite +publisher silently drops a group created below the first group it served: the +publisher's `create_group` and `write_frame` succeed, and the subscriber sees a +clean end without it. + +## Plan + +`TrackRun::start` (`rs/moq-net/src/lite/publisher.rs`) sends `SUBSCRIBE_START` +for the first served group and then calls `raise_start_to(start)`, which +suppresses every lower group regardless of the subscription's floor and +budget. #4387 added it to resolve a relayed subscription's start from its +source; keep that fix (see the note in +[Track tail interop](/quest/m1/track-tail-interop.md)) while honoring an +explicit floor. + +Decided: + +- An explicit floor delivers late lower groups within `max_age`, matching + moq-transport, draft-ietf-moq-transport ("subscriptions without a filter pass + all Objects"), and moq-mux's floor handling (#3258). +- `start: None` joins where the publisher starts: the first served group + becomes the floor, so a group created below it is dropped by design. This is + what moq-mux's `container::Consumer` and the IETF publisher already assume. + Fix the `Subscription::start` docs in moq-net (which say `None` equals a + floor of group 0) and the matching js/net docs. +- `raise_start_to` applies only when the subscription has no explicit floor + (`start.is_none()`). With an explicit floor, `SUBSCRIBE_START` still reports + the first served group, but nothing below it is suppressed. +- Aggregation follows: `Subscription::poll_combined` + (`rs/moq-net/src/model/subscription.rs`) lets any `None` clear another + subscriber's explicit floor, so a relay forwards "join at the start" upstream + and the explicit-floor subscriber still loses group 0. An explicit floor + survives mixing with `None`; the loosest explicit floor wins. Each + subscriber's own cursor still filters what it sees. +- `start_floor_suppresses_late_lower_arrivals` stays as the `None` case: it + subscribes with `None`, receives group 7, raises the start to 7 as + `SUBSCRIBE_START` does, and group 5 is still suppressed. Add its explicit-floor + twin, which delivers group 5. + +If `drafts/draft-lcurley-moq-lite.md` describes `SUBSCRIBE_START` as an +implicit drop below the start regardless of the floor, update it in the same +PR. + +Test: port the reporter's deterministic repro +(`rs/moq-net/tests/late_lower_group.rs` on kidq330's fork, paused time and the +mock transport) for lite-05, lite-06, and lite-07-wip, direct and through a +relay, with the in-process and moq-transport controls. Add a mixed case through +a relay: a `None` subscriber already receiving group 1, then one with a floor +of group 0, and a fresh group 0 reaches only the second. + +## Closes + +- [#4595](https://github.com/moq-dev/moq/issues/4595) - moq-lite: a group created below the first served group is silently dropped + +## Related + +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - once publishers name every undelivered group, a group dropped under the None floor can be named instead of vanishing diff --git a/quest/m1/loc-duration-marker.md b/quest/m1/loc-duration-marker.md deleted file mode 100644 index 1151d244873..00000000000 --- a/quest/m1/loc-duration-marker.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] LOC producers write the duration marker - -## Goal - -LOC video groups end with the empty frame that closes their last frame's -duration, the same contract the legacy container carries. - -## Plan - -The consumer-side skip has landed in `rs/moq-mux/src/container/loc` and -`js/loc`, and shipped in `moq-mux` 0.10.3 and `@moq/loc` 0.2.3. Endpoint -recognition is configured for media tracks, so empty data frames remain data. -Have the LOC producers write the marker at `cut` and `finish` exactly as the -legacy producer does (`Container::finish_group` on `loc::Wire(Kind::Video)`), -and extend the same tests. diff --git a/quest/m1/merge-queue.md b/quest/m1/merge-queue.md index d84f2cee103..308d0f59bf3 100644 --- a/quest/m1/merge-queue.md +++ b/quest/m1/merge-queue.md @@ -17,9 +17,9 @@ and there is no merge queue, so nothing re-runs them on the combined tree. queue tests the combination once, at merge time. - Make the workflows ready: every workflow providing a required check (today `Check` and `Test` in `.github/workflows/check.yml`) also runs on - `merge_group`. `just ci check|test` runs `sh/dispatch.sh`, which scopes - by diffing against its `BASE` argument, else `origin/$GITHUB_BASE_REF`. A - merge group sets no `GITHUB_BASE_REF`, so pass the group's base + `merge_group`. `just ci $JOB $BASE` (`justfile`) scopes by diffing + against its `BASE` argument, else `origin/$GITHUB_BASE_REF`. A merge group + sets no `GITHUB_BASE_REF`, so pass the group's base (`github.event.merge_group.base_sha`) as `BASE`. Check the concurrency group and the `closed`-only skip still behave for queue refs. - Document it in `CONTRIBUTING.md`: PRs merge through the queue, a @@ -30,7 +30,3 @@ and there is no merge queue, so nothing re-runs them on the combined tree. settings to use rather than changing it. Public API: none. Wire: none. - -## Required - -- [Tooling](/quest/m1/tooling/README.md) - `just ci` and `sh/dispatch.sh`, the entry point the queue runs diff --git a/quest/m1/mkv-export-delay.md b/quest/m1/mkv-export-delay.md new file mode 100644 index 00000000000..4fb5d5fcf67 --- /dev/null +++ b/quest/m1/mkv-export-delay.md @@ -0,0 +1,22 @@ +# [S] MKV export releases frames on a fixed delay + +## Goal + +`moq export mkv --delay ` interleaves tracks through the shared +fixed-delay release stage, so its tag order is a function of the media, not +of arrival, as the TS export's is. + +## Plan + +Today `pick_next_track` (`rs/moq-mux/src/container/mkv/export.rs`) takes the +smallest *pending* timestamp, so which track goes first depends on which frame +has arrived. Replace it with the release stage from +[fixed-delay release](/quest/m1/tstd/delay.md), with the same `--delay` flag +and the same late-frame drop. Update `doc/bin/cli.md`. + +Public API: the exporter gains a delay setting; breaking only if it replaces +an existing one. Wire: none. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - builds the shared release stage diff --git a/quest/m1/mobile-ownership.md b/quest/m1/mobile-ownership.md new file mode 100644 index 00000000000..abfee2ab29d --- /dev/null +++ b/quest/m1/mobile-ownership.md @@ -0,0 +1,22 @@ +# [XS] Rust owns codecs on mobile + +## Goal + +The mobile media boundary is written down: Rust owns capture, codecs, and +rendering, and `moq-ffi` bridges native surfaces (`CVPixelBuffer` on iOS, +Android `HardwareBuffer`/`Surface`) as opaque handles. Swift and Kotlin do not +grow a parallel platform codec stack. + +## Plan + +Decided in the 2026-09-30 audit: option 2 from #700, Rust owns codecs. The +tree already shipped it. `moq-ffi` defaults to the `audio` and `video` +features (`rs/moq-ffi/Cargo.toml:27`), so the Kotlin and Swift packages already +carry the Rust codecs, and #4094 added the `CVPixelBuffer` bridge +(`MoqVideoSurface::PixelBuffer` on `dev`). Option 1 would add a second media +stack beside one that exists. + +What remains is recording the verdict in `rs/moq-ffi/AGENTS.md` (a maintainer +edit) and in [Android capture](/quest/m2/mobile-capture-android.md) and +[iOS capture](/quest/m2/mobile-capture-ios.md), which target `moq-video` as +written and no longer wait on this. diff --git a/quest/m1/moq-installer.md b/quest/m1/moq-installer.md deleted file mode 100644 index 78b023d5145..00000000000 --- a/quest/m1/moq-installer.md +++ /dev/null @@ -1,84 +0,0 @@ -# [M] One-command moq installation and upgrades - -## Goal - -A canonical Bash installer installs the released `moq` binary on supported -macOS and Linux machines without Rust or sudo. Running it again upgrades -the same installation; selecting a version supports -reproducible installs and deliberate downgrades. - -Install only `moq` from the `moq-cli` release. Token and relay functionality -belong to its subcommands, not separate installer choices. This work does -not implement those subcommands, automatic updates, a self-update command, -service setup, Windows support, or new release targets. - -## Plan - -- Default to the latest stable `moq-cli` release, with an explicit version - option. Resolve that product's tags, not the repository-wide latest - release: this repository publishes multiple independently versioned crates. - Refuse missing versions, malformed input, and incomplete releases clearly. -- Reuse the release archives and `SHA256SUMS`. Verify the selected archive - before extracting and installing its expected executable. Stage and check - the replacement before modifying the destination. Commit the executable and - ownership record as one recoverable transaction on the destination - filesystem: stage the new pair, retain the validated prior pair, and write a - durable journal before either rename. Record distinct phases after the - executable rename and after the ownership-record rename. On a handled - failure, roll back both files. After interruption, the next run must use the - journal to complete the new pair when both staged objects validate together. - If both renames completed, validate the installed pair and finish cleanup; - otherwise restore the prior pair, or remove every transaction file for an - initial install. Recovery must not misclassify a partial transaction as an - unmanaged installation. - Flush staged files, journal updates, renames, and their directory entries at - the required commit boundaries. Remove the journal and backups only after the - matching pair is durable. This is the atomic installation contract: recovery - exposes either the complete old pair or the complete new pair, never a mixed - pair. A failed initial install leaves no destination, while a failed upgrade - leaves the prior executable and ownership record usable. Clean up temporary - files after commit or rollback. -- Support the existing targets: macOS ARM64 and Linux x86_64/ARM64 with - glibc 2.34 or newer. Refuse unsupported operating systems, architectures, - and libc variants with actionable diagnostics. Intel macOS and musl/Alpine - require separate release work. -- Default to `~/.local/bin` with an explicit directory override. Do not invoke - sudo or edit shell profiles. Print the installed version and path, and - shell-appropriate PATH instructions when needed. Detect when another - `moq` on PATH would take precedence so success does not imply the wrong - binary will run. Do not follow an existing destination symlink into a - package manager's installation or overwrite a conflicting unmanaged file. - Keep a durable ownership record bound to the destination and installed - binary digest. Refuse replacement when the record is missing, malformed, - or mismatched, including a record copied from another destination. A valid - prior installation can be replaced; failed upgrades must preserve both its - binary and usable ownership record. -- Keep the canonical script and its tests in this repository. Publish a - usable HTTPS source for the dependent website quest; that quest exposes - `https://moq.dev/install.sh` without duplicating installer logic. -- Document first install, latest-version upgrade, explicit version selection, - directory override, PATH setup, and removal in `doc/setup/install.md`. - Use the working canonical URL until the website quest switches the example. - Package-manager installations continue to use their package manager for - upgrades. Describe only the subcommands the selected release actually ships. -- Wire installer tests into `just check` and CI. Cover initial - install, repeat install, upgrade, explicit downgrade, product-specific latest - selection, unsupported hosts, corrupt/missing assets, destination conflicts, - and failure preserving an existing executable. Use controlled fixtures for - failure cases, including interruption before and after every journal, rename, - durability, and cleanup boundary. Explicitly cover the post-second-rename, - pre-cleanup state. Assert that each case completes the new pair or restores - the old pair, and that an initial-install failure leaves neither file. Add - native macOS/Linux smoke coverage for executable startup. - Exercise the canonical script with real release assets in a temporary - install directory and run the installed `moq --version`. The dependent - website quest owns verification of the final public URL. - -## Related - -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - reuse its - artifacts without requiring workflow consolidation -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - relay functionality joins - the same executable independently of its installation method -- [Install URL](/quest/m1/moq-install-url.md) - exposes this installer through - the moq.dev website after it is published diff --git a/quest/m1/moqsink-keyframe-latch.md b/quest/m1/moqsink-keyframe-latch.md deleted file mode 100644 index 5cb8205681b..00000000000 --- a/quest/m1/moqsink-keyframe-latch.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] moqsink drops frames on recoverable importer errors - -## Goal - -A `moqsink` pad survives the importer errors moq-mux documents as -recoverable: it drops frames until the next keyframe instead of calling -`self.fail()` and losing the rendition for good. Two paths reach that -failure in `Media::write` (`rs/moq-gst/src/sink/pad.rs`) today: - -- A new pad starts unlatched (`keyframe: false`), so a first buffer that is a - delta frame fails it. -- A `TimestampRewind` with no signalled break (an rtspsrc jitterbuffer - re-anchoring) has no guard at all. - -## Plan - -The header-only buffer after a break was fixed in -https://github.com/moq-dev/moq/pull/4356: the latch stays armed after a -successful decode. Reuse that latch here. - -Decided: a video pad starts latched. On `TimestampRewind`, set the latch and -drop until a keyframe lands above the producer's live edge, losing up to one -GOP per re-anchor. Mapping a rewound timeline forward instead belongs to -[#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md). -The reporter offered the guard they run in production. - -Regression tests beside `video_pause_drops_deltas_until_the_next_keyframe`: - -- A new pad's first buffer is a delta: it drops. -- A rewind without a break: deltas drop until a keyframe above the edge. - -## Closes - -- [#4366](https://github.com/moq-dev/moq/issues/4366) - close this issue when the quest finishes diff --git a/quest/m1/moxygen/README.md b/quest/m1/moxygen/README.md deleted file mode 100644 index e478e9d0308..00000000000 --- a/quest/m1/moxygen/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Moxygen compatibility - -## Goal - -More compatibility with moxygen's moq-test suite, never a full pass. A peer -that speaks one subgroup per group, FETCH of whole groups, and one datagram -per group gets those through the relay. - -## Plan - -`conformance_test.sh` on draft-16 scored 0/76 against moq-relay 0.15.1. -Subgroup subscribes did return objects. The relay decodes IETF into the -moq-lite track and writes a new subgroup. A green run of all 76 cases is not -the exit test. - -Out of scope, so they are not reopened as bugs: - -- PUBLISH. The relay refuses it. Routing stays SUBSCRIBE per namespace. -- Subgroups. A non-zero subgroup id is dropped. One stream per group. -- Per-group priority. `track::Info` has one priority. A 200/201 split by - group parity stays a gap. -- Foreign object extensions. Dropped. A timestamp we add is ours. -- The end-of-group bit. Optional in draft-16. The group's one stream FINs - at the end, so the bit adds nothing this line will do. -- Several datagram objects in one group. -- A peer that answers SUBSCRIBE_NAMESPACE with unimplemented. The session - already continues. - -Docs stay inline in the change that makes them stale. No new guide. - -## Required - -- [Default track priority](/quest/m1/moxygen/priority.md) - an unset track priority is the midpoint on moq-lite and on IETF, not the least urgent value -- [Group FETCH](/quest/m1/moxygen/fetch.md) - an IETF FETCH of whole groups is served from cache or fetched upstream, one group at a time -- [Datagram groups](/quest/m1/moxygen/datagram.md) - an IETF datagram that is one object in a group arrives as a moq-lite datagram group - -## Related - -- [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher answers a FETCH this relay forwards -- [Track priority scope](/quest/m1/track-priority-scope.md) - send-order fairness, not the default value diff --git a/quest/m1/moxygen/datagram.md b/quest/m1/moxygen/datagram.md deleted file mode 100644 index c794b5e57d8..00000000000 --- a/quest/m1/moxygen/datagram.md +++ /dev/null @@ -1,23 +0,0 @@ -# [M] Datagram groups - -## Goal - -An IETF datagram that carries one object for a group is delivered as a -moq-lite datagram: one single-frame group, sequence preserved. Several -objects in one datagram group stay unsupported. - -## Plan - -moq-lite already does this. A datagram is a subscribe id, a group sequence, a -timestamp, and a payload. `insert_datagram` keeps the sequence so a relay -does not renumber it. - -The IETF session does not read or write QUIC datagrams, so a datagram -subscribe delivers nothing. Copy the lite path onto that session. Do not -invent a second object list inside the group. - -The moxygen cases with one object per group are the ones this can pass. - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to diff --git a/quest/m1/moxygen/fetch.md b/quest/m1/moxygen/fetch.md deleted file mode 100644 index f236d1751f0..00000000000 --- a/quest/m1/moxygen/fetch.md +++ /dev/null @@ -1,26 +0,0 @@ -# [L] Group FETCH - -## Goal - -An IETF FETCH that asks for whole groups is answered. A group already in -cache is served from there. A miss fetches that group upstream. Subscribers -still FETCH one group at a time. A publisher may be asked for a range, which -the relay walks one group at a time. A publisher refusal is what the -subscriber sees. - -## Plan - -Standalone FETCH and a non-zero joining FETCH are refused today with -"not supported". Walk `track::Consumer::fetch_group`, one group, then the -next. Do not add an archive. - -A joining FETCH is the same walk for the groups it names. A form the walk -cannot express is still an explicit refusal, not a hang. - -The moxygen FETCH cases that ask for whole groups are the check. The rest of -that suite is not. - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to -- [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher that fills an upstream miss diff --git a/quest/m1/moxygen/priority.md b/quest/m1/moxygen/priority.md deleted file mode 100644 index 6efd6aaa5af..00000000000 --- a/quest/m1/moxygen/priority.md +++ /dev/null @@ -1,28 +0,0 @@ -# [S] Default track priority - -## Goal - -A track that never set a priority is the midpoint on both wires. moq-lite -TRACK_INFO carries that midpoint as written. An IETF subgroup header carries -128. A track that set `track::Info.priority` still uses that value. Per-group -priority stays unsupported. - -## Plan - -`track::Info.priority` defaults to 0, higher-first. moq-lite writes it -verbatim, so the wire byte is 0. IETF flips it, so 0 goes out as 255. The -draft's usual publisher priority is 128. - -One model default serves both. 127 is the higher-first midpoint: lite writes -127, IETF writes 128. Do not special-case each wire to the byte 128. That -would make the two encodings different urgencies. - -Rust and JavaScript both pin the old default TRACK_INFO bytes -(`0x06, 0x00, ...`). Update those fixtures with the new default. - -The moxygen 200 versus 201 split by group parity is out of scope. - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to -- [Track priority scope](/quest/m1/track-priority-scope.md) - fairness across owners, not this default diff --git a/quest/m1/obs-moq-video/README.md b/quest/m1/obs-moq-video/README.md index 430136b781e..f44a2582416 100644 --- a/quest/m1/obs-moq-video/README.md +++ b/quest/m1/obs-moq-video/README.md @@ -8,34 +8,37 @@ Remove the MoQ OBS plugin's dependency on OBS/system FFmpeg ABI versions by deco Portability and FFmpeg removal lead. The current MoQ source decodes video with libavcodec, libavutil, and libswscale, and audio with libavcodec (`moq_source_decode_audio_frame` in `cpp/obs/src/moq-source.cpp`). Its swresample linkage is unused. FFmpeg linkage goes away only once both the video source replacement and the audio decode replacement land. The stranded audio branch (#3498, merged only into `codex/obs-audio-receive-base`) is abandoned; the audio playback quest replans it on the generated C++. The plugin reaches codecs through the generated C++ package over moq-ffi (the migration quest linked below lands first); build `libmoq_ffi` statically with only the codec features needed here; OS frameworks and runtime GPU drivers remain valid dependencies. Verify plugin imports instead of promising a completely static OBS plugin. -Attempt GPU delivery immediately, starting on macOS. Windows and Linux can ship independently. Prefer direct surface reuse, allow GPU conversion/blits, and automatically fall back to CPU delivery when import is unavailable or fails. Stats must show the actual decoder/encoder, delivery path, and fallback reason. Retaining a texture handle is insufficient unless pool ownership and synchronization also prevent reuse while work is in flight. +Attempt GPU delivery immediately on macOS decode; other platforms keep the CPU path here. Prefer direct surface reuse, allow GPU conversion/blits, and automatically fall back to CPU delivery when import is unavailable or fails. Stats must show the actual decoder/encoder, delivery path, and fallback reason. Retaining a texture handle is insufficient unless pool ownership and synchronization also prevent reuse while work is in flight. Initial video decoding covers H.264, HEVC, and AV1 where moq-video has an available backend. Unsupported codecs produce an actionable error; do not retain an FFmpeg fallback. VP8/VP9 return through their own follow-up quest. Audio playback covers Opus, AAC-LC, and PCM. Publishing remains opt-in, with one **Use MoQ encoders** choice for video and audio. Keep the existing OBS encoder mode. Internal OBS encoder adapters call moq-video/moq-audio, preserving OBS's A/V handling and the existing encoded MoQ output. The combined choice is enabled only when both adapters are present. Start with H.264, supported HEVC, and Opus; defer AV1/AAC encoding and PCM publishing UI. Keep bitrate separate from **Low latency**, **Balanced** (default), and **Quality** presets. Presets describe supported buffering/compression controls, not an end-to-end delay promise. -The quests separate portable decoding, platform GPU delivery, audio, and publishing so each can land and be validated independently. moq-ffi's decoded frames own their surface and convert to CPU pixels only on request (#4094, on `dev`); a native decode exposes the platform surface as a borrowed view, which each platform quest extends to its own surface type. +The quests separate portable decoding, audio, and publishing so each can land and be validated independently. moq-ffi's decoded frames own their surface and convert to CPU pixels only on request (#4094, on `dev`); a surface decode exposes the platform surface as a borrowed view, which each platform GPU quest extends to its own surface type. + +Decided in the 2026-09-30 audit: the Windows and Linux GPU decode paths and the macOS and Windows GPU encoder inputs moved to m2 (listed under Related), because each needs physical-hardware proof, and Linux GPU input is already m2/m3. ## Required - [Video source replacement](/quest/m1/obs-moq-video/source.md) - remove the FFmpeg video decode and attempt macOS GPU delivery immediately, with a working CPU fallback on other platforms - [Audio playback](/quest/m1/obs-moq-video/audio-playback.md) - replace the FFmpeg audio decode with moq-audio -- [Windows decoded frames](/quest/m1/obs-moq-video/decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback -- [Linux decoded frames](/quest/m1/obs-moq-video/decode-linux.md) - present supported native decoded surfaces with visible CPU fallback - [Linux bundle](/quest/m1/obs-moq-video/linux-bundle.md) - attach a portable Linux x86_64 tarball to every obs-moq release once FFmpeg is gone - [Encoder presets](/quest/m1/obs-moq-video/presets.md) - define and measure shared low-latency, balanced, and quality policies - [Preset parity](/quest/m1/obs-moq-video/preset-parity.md) - audio stores and reports its preset like video, defaults to Balanced, and the preset claims hold - [Audio publishing](/quest/m1/obs-moq-video/audio-publish.md) - back an internal OBS Opus encoder with moq-audio - [Video publishing](/quest/m1/obs-moq-video/adapter.md) - back an internal OBS video encoder with moq-video and expose the combined opt-in mode - [Rate control](/quest/m1/obs-moq-video/rate-control.md) - the plugin reserves its bitrate and retunes the OBS encoder to the grant -- [macOS GPU input](/quest/m1/obs-moq-video/macos.md) - feed the encoder from the OBS compositor without CPU readback -- [Windows GPU input](/quest/m1/obs-moq-video/windows.md) - import or blit OBS D3D11 textures with explicit synchronization - [VP8/VP9 decoding](/quest/m1/obs-moq-video/vpx.md) - restore those playback codecs without an FFmpeg ABI dependency ## Related -- [OBS migration](/quest/m1/cpp/obs.md) - every quest here starts from the plugin on the generated C++, so codec surface is designed in moq-ffi and reaches moq-c and the other wrappers through the Cross-Package Sync table, not as OBS-only C symbols -- [Linux GPU input](/quest/m2/obs-linux-gpu.md) - allocation-export feasibility and its dependent implementation are deferred -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - owns Linux backend decode/import capabilities; reconcile its older dependency assumptions against current code +- [OBS migration](/quest/m1/cpp/obs.md) - every quest here starts from the plugin on the generated C++, so codec surface is designed in moq-ffi and reaches the other bindings through the Cross-Package Sync table, not as OBS-only C symbols +- [Linux GPU decode](/quest/m2/obs-decode-linux.md) - present hardware-decoded frames without CPU readback; needs physical-hardware proof +- [Windows GPU decode](/quest/m2/obs-decode-windows.md) - present D3D11 decoded textures without CPU readback; needs physical-hardware proof +- [macOS GPU input](/quest/m2/obs-macos.md) - feed compositor frames to VideoToolbox without a CPU round trip; needs physical-hardware proof +- [Windows GPU input](/quest/m2/obs-windows.md) - feed D3D11 compositor frames to the encoder without CPU staging; needs physical-hardware proof - [Video hardware validation](/quest/m3/video-hardware.md) - physical hardware evidence is required for each claimed GPU path -- [Audio codecs](/quest/m1/audio-codecs/README.md) - HE-AAC, multichannel, and native AAC encode reach the OBS source and encoder adapters through moq-ffi +- [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - HE-AAC and multichannel AAC reach the OBS source on macOS through moq-ffi +- [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - native AAC encode reaches the OBS encoder adapter on macOS through moq-ffi +- [Linux GPU input](/quest/m3/obs-linux-gpu.md) - allocation-export feasibility and its dependent implementation are deferred +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - owns Linux backend decode/import capabilities; reconcile its older dependency assumptions against current code diff --git a/quest/m1/obs-moq-video/audio-playback.md b/quest/m1/obs-moq-video/audio-playback.md index d9b258ea04f..c5f74b42a48 100644 --- a/quest/m1/obs-moq-video/audio-playback.md +++ b/quest/m1/obs-moq-video/audio-playback.md @@ -23,4 +23,4 @@ Decided: the earlier receive branch (#3498, merged only into the stranded `codex ## Related - [Video source replacement](/quest/m1/obs-moq-video/source.md) - coordinate the shared timestamp and source lifecycle without blocking audio rollout -- [Channel layouts](/quest/m1/audio-codecs/layout.md) - the moq-audio layouts this mapping mirrors +- [Channel layouts](https://github.com/moq-dev/moq/pull/4119) - the moq-audio layouts this mapping mirrors diff --git a/quest/m1/obs-moq-video/audio-publish.md b/quest/m1/obs-moq-video/audio-publish.md index ae2543cd356..3b7cf9981a5 100644 --- a/quest/m1/obs-moq-video/audio-publish.md +++ b/quest/m1/obs-moq-video/audio-publish.md @@ -8,7 +8,7 @@ MoQ publishing can encode OBS's mixed audio with moq-audio Opus while preserving - Expose `moq_audio::encode::Encoder` through a codec-only moq-ffi type with owned encoder/packet handles, so every binding gets it. The existing raw audio producer combines encoding and publication and must not create a second publication alongside the OBS encoded output. Reuse frame sizing, bitrate updates, catalog configuration, and finish/padding behavior. - Implement the OBS audio encoder interface, including fixed input frame size, mono/stereo PCM conversion, timestamps, codec headers, final padding, and packet release. Ask OBS for the input layout the encoder supports; moq-audio does not implement arbitrary channel remapping. Keep capture/mixing/device ownership in OBS. -- Publish Opus initially. Leave AAC with the existing OBS mode and defer PCM publishing UI, since the output currently declares AAC/Opus. Correct stale binding documentation that describes the raw codec parser as Opus-only if that API is touched. +- Publish Opus initially. `encode::Codec::Aac` lets the adapter offer AAC where a platform encoder exists; until then leave AAC with the existing OBS mode and defer PCM publishing UI, since the output currently declares AAC/Opus. Correct stale binding documentation that describes the raw codec parser as Opus-only if that API is touched. - Apply the shared presets and independent audio bitrate. Test 10/20 ms packetization, frame-size changes at stream boundaries, partial final frames, silence, reconnect, saturation, and stop with pending output. Verify decoded audio and A/V timestamps with a real subscriber. - Land the internal adapter independently; the combined Use MoQ encoders UI becomes available when the video adapter also lands. Do not expose a temporary video/audio mix-and-match product UI. @@ -16,7 +16,3 @@ MoQ publishing can encode OBS's mixed audio with moq-audio Opus while preserving - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ first - [Encoder presets](/quest/m1/obs-moq-video/presets.md) - shared policy and truthful reporting - -## Related - -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - `Codec::Aac` lets the adapter offer AAC instead of leaving it to the OBS encoder mode diff --git a/quest/m1/obs-moq-video/linux-bundle.md b/quest/m1/obs-moq-video/linux-bundle.md index c15a4b68d3b..5d05ad8498a 100644 --- a/quest/m1/obs-moq-video/linux-bundle.md +++ b/quest/m1/obs-moq-video/linux-bundle.md @@ -9,7 +9,7 @@ Every `obs-moq-v*` release attaches a Linux x86_64 tarball that loads into a sto - The only reason `obs-build` in `.github/workflows/moq-c.yml` skips Linux is FFmpeg: the source links nix/distro libavcodec for both video and audio, which is not portable. The FFmpeg removal (video source replacement plus audio playback) is the blocker; once the plugin is C++ over moq-ffi plus libobs and Qt6, a Linux build has no extra runtime dependency that OBS itself does not already carry. - Build on `ubuntu-24.04` (glibc 2.39, the floor OBS's own Linux packages target) against the libobs and Qt6 headers OBS's plugin template uses; the template's `.deb` recipe is the reference. Ship the plain archive layout the other platforms use (`obs-moq-*-x86_64-unknown-linux-gnu.tar.gz` with `bin/64bit/obs-moq.so` and `data/`), extractable into `~/.config/obs-studio/plugins/obs-moq/`. A `.deb` is optional and separate. - Flatpak OBS cannot load a plugin from the host filesystem. Verify a real Flatpak install and support it only if the sandbox's runtime ABI matches, documenting the `~/.var/app/com.obsproject.Studio/config/obs-studio/plugins/` path. Otherwise, state plainly that Flatpak is unsupported. -- `cpp/obs/build.sh --target x86_64-unknown-linux-gnu` produces the tarball, and the matrix in `obs-build` gains the row; nothing else in the release pipeline changes. Keep the nightly `just obs ci` compile as the PR gate; #4370 (open) compiles the OBS plugin on every PR, which covers the Linux compile if it lands first. +- `cpp/obs/build.sh --target x86_64-unknown-linux-gnu` produces the tarball, and the matrix in `obs-build` gains the row; nothing else in the release pipeline changes. The Linux compile gate already exists: #4370 (merged) compiles the OBS plugin on every PR. - Verify by loading the tarball into the oldest supported OBS 32 release and current stable on Ubuntu 24.04 and one non-Debian distro (Fedora), publishing and subscribing against a relay, and inspecting the `.so` with `ldd` for nothing beyond libobs, Qt6, glibc, and OS libraries. ## Required @@ -19,4 +19,4 @@ Every `obs-moq-v*` release attaches a Linux x86_64 tarball that loads into a sto ## Related -- [Linux decoded frames](/quest/m1/obs-moq-video/decode-linux.md) - native surface delivery lands on top of the portable CPU path this bundle ships +- [Linux decoded frames](/quest/m2/obs-decode-linux.md) - native surface delivery lands on top of the portable CPU path this bundle ships diff --git a/quest/m1/obs-moq-video/preset-parity.md b/quest/m1/obs-moq-video/preset-parity.md index d2c2cd86239..42a87504b3e 100644 --- a/quest/m1/obs-moq-video/preset-parity.md +++ b/quest/m1/obs-moq-video/preset-parity.md @@ -40,8 +40,8 @@ The shape is settled; this finishes it: - Known gap: VAAPI reports `LowLatency` whatever was asked, and V4L2 and MediaCodec report unconfirmed; no quest owns measuring and mapping presets for them. Media Foundation and VideoToolbox are owned by - [Windows GPU input](/quest/m1/obs-moq-video/windows.md) and - [macOS GPU input](/quest/m1/obs-moq-video/macos.md). + [Windows GPU input](/quest/m2/obs-windows.md) and + [macOS GPU input](/quest/m2/obs-macos.md). Public API: additive on moq-audio (the stored preset and its `Applied` report); the unpublished audio `Preset` default changes. Wire: none. diff --git a/quest/m1/obs-moq-video/source.md b/quest/m1/obs-moq-video/source.md index db53b3af20d..e7bf0fd977e 100644 --- a/quest/m1/obs-moq-video/source.md +++ b/quest/m1/obs-moq-video/source.md @@ -7,7 +7,7 @@ The MoQ source loads and plays supported video without FFmpeg's video libraries ## Plan - Replace `cpp/obs/src/moq-source.cpp` video decode and conversion with moq-video through the generated C++ package: the moq-ffi video consumer for the CPU path, including frame ownership and cancellation semantics. Support H.264, HEVC, and available AV1 decoding; report unsupported VP8/VP9 explicitly until their follow-up lands. -- Decode with `MoqVideoDecoderOutput.surface` set: each `MoqVideoDecodedFrame` retains the decoder's surface, `surface()` borrows it (`PixelBuffer` on macOS) for as long as the frame lives, and `pixels(format)` is the CPU fallback. Hold the frame until OBS's GPU work reading it completes; held frames hold decoder pool slots. This surface landed on `dev` (#4094). +- Decode with `MoqVideoDecoderOutput.surface` set: each `MoqVideoDecodedFrame` retains the decoder's surface, `surface()` borrows it (`MoqVideoSurface::PixelBuffer` on macOS) for as long as the frame lives, and `pixels(format)` is the CPU fallback. A platform with no `MoqVideoSurface` variant refuses the opt-in. Hold the frame until OBS's GPU work reading it completes; held frames hold decoder pool slots. This surface is on `dev` only (#4094, renamed in 97575f002). - Implement the macOS presentation probe immediately: retain VideoToolbox PixelBuffer/IOSurface storage, inspect OBS graphics import and rendering support, and convert to OBS's expected color format on the GPU if necessary. Adapt the source render path to import textures on the graphics thread; preserve source timing instead of simply drawing the newest frame. An asynchronous CPU source API alone does not prove native GPU delivery. - Bound decoded frames retained by the render thread. On import failure, switch to the existing I420 delivery path and show the reason in Stats. Keep fallback stable for the stream/device configuration rather than retrying every frame; re-probe on a relevant configuration change or restart. Device loss and resize must retire old surfaces only after rendering completes. - Preserve timestamps, range/primaries, stride and plane layout, catalog/rendition changes, reconnect, visibility/deactivation behavior, and existing source settings. Carry frame-generation identity so late callbacks cannot display frames from a replaced source. @@ -17,6 +17,7 @@ The MoQ source loads and plays supported video without FFmpeg's video libraries ## Required - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ before decode changes +- dev's decoded-frame surface (#4094, 97575f002) reaches main ## Related diff --git a/quest/m1/obs-moq-video/vpx.md b/quest/m1/obs-moq-video/vpx.md index 528d73b1243..6dbc9ed8a9b 100644 --- a/quest/m1/obs-moq-video/vpx.md +++ b/quest/m1/obs-moq-video/vpx.md @@ -14,4 +14,4 @@ MoQ consumers, including the OBS source, decode VP8 and VP9 without depending on ## Related - [Video source replacement](/quest/m1/obs-moq-video/source.md) - consumer integration, not a blocker for codec implementation -- [Color model](/quest/m1/color-model.md) - share codec-neutral color metadata rather than introducing VP9-only conversions +- [Catalog colour model](/quest/m2/color-catalog.md) - share codec-neutral color metadata rather than introducing VP9-only conversions diff --git a/quest/m1/open-gop-leading-pictures.md b/quest/m1/open-gop-leading-pictures.md index c1f84922ea4..0dc7c0af266 100644 --- a/quest/m1/open-gop-leading-pictures.md +++ b/quest/m1/open-gop-leading-pictures.md @@ -21,6 +21,22 @@ drop belongs on the consumer: ingest cannot know whether a given viewer has the previous GOP, and dropping at ingest would degrade continuous playback for everyone. +Measured through `` in Chromium 153 on macOS, on the clip +`just test ts --open-gop` generates (three leading pictures per recovery +point) stretched to 120 s. Continuous playback decoded every leading picture +on both decoder paths, with no errors, and the two paths' frames were +identical. At a cold join the paths differ. VideoToolbox (the default there) +outputs nothing for the orphaned leading pictures and raises no error, and +every frame it does output matches the continuous decode, so a viewer merely +starts at the keyframe. The software decoder (`prefer-software`, the path a +browser without hardware H.264 takes; Linux was not measured) raises +`EncodingError` in every join, and the watch then closes its decoder, so video +stops. The same joins with the leading pictures removed from the stream decode +cleanly in software, so the error is the leading pictures, not the non-IDR +keyframe. A latency skip ("skipping slow group") orphans the next group's +leading pictures in the same way. The trim therefore has to happen before +decode, and the JS test should drive the software decoder. + - In the JS consumer (`js/hang/src/container/consumer.ts` forces the first sample of a group to `keyframe`, and `js/watch/src/video/decoder.ts` submits it as `"key"`): for the first group after any non-continuous transition, @@ -48,10 +64,6 @@ everyone. group's leading pictures trimmed too, so an implementation that only trims the initial group fails. Both cases in both languages. -## Required - -- [#2067](/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md) - decides whether the glitch is dropped frames, corrupt frames, or a decoder error, which sets what this has to prove - ## Related - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - the `recovery_frame_cnt > 0` case this rule does not cover diff --git a/quest/m1/opus-catalog-rate.md b/quest/m1/opus-catalog-rate.md deleted file mode 100644 index d6ba6bdd842..00000000000 --- a/quest/m1/opus-catalog-rate.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] Opus catalog rate matches the decoder - -## Goal - -MKV Opus import publishes the codec rate (48 kHz) as the catalog sample rate, -not the OpusHead input rate, which is informational. The catalog describes -what the decoder outputs. - -## Plan - -fMP4 import already does this. Check the other importers that build the -catalog from an OpusHead (FLV and the raw Opus import look similar) and align -them in the same PR. The OpusHead description keeps the input rate. - -Regression: a 44.1 kHz-input OpusHead imports with a 48 kHz catalog rate. diff --git a/quest/m1/opus-conceal.md b/quest/m1/opus-conceal.md deleted file mode 100644 index cac6f8255ed..00000000000 --- a/quest/m1/opus-conceal.md +++ /dev/null @@ -1,33 +0,0 @@ -# [XS] Opus concealment length - -## Goal - -`moq_audio` `Decoder::decode(&[])` conceals one Opus packet, the length of the -last real one, instead of 120 ms. The API is unchanged and lands on main. - -## Plan - -- `rs/moq-audio/src/decode/decoder.rs` passes `max_frame_size` (120 ms) as - libopus's `frame_size` on every call, and libopus conceals exactly that many - samples. Record the last packet's sample count (`opus_packet_get_nb_samples`) - and pass it for an empty packet; it is always a multiple of 2.5 ms. -- The audio-codecs line branch moves this code to - `rs/moq-audio/src/decode/backend/libopus.rs` (same `max_frame_size`); - land the fix wherever the code lives when this starts, and port it on the - line's next merge from main otherwise. -- Refuse loss before any packet has decoded, rather than surfacing libopus's - `BUFFER_TOO_SMALL`. -- Document on `decode` how much an empty packet conceals. -- Regression from the issue's repro: one lost 20 ms packet yields 20 ms. -- A `conceal(duration)` method and `decode(Option<&[u8]>)` were rejected: no - consumer needs a caller-chosen length, and the latter breaks the common case. - How platform backends signal loss belongs to the decode-backend seam. - -## Closes - -- [#4248](https://github.com/moq-dev/moq/issues/4248) - `Decoder::decode(&[])` conceals 120 ms of Opus audio for one lost packet - -## Related - -- [Audio loss recovery](/quest/m2/audio-loss-recovery.md) - the FEC versus concealment policy study -- [Decode backend](/quest/m1/audio-codecs/decode-backend.md) - where platform decoders signal loss diff --git a/quest/m1/opus-mapping-family.md b/quest/m1/opus-mapping-family.md index f2dec437cd4..9bd243a1ddf 100644 --- a/quest/m1/opus-mapping-family.md +++ b/quest/m1/opus-mapping-family.md @@ -2,14 +2,10 @@ ## Goal -On dev, `moq_mux::codec::opus::Config` stores the channel mapping family in one place: the audio-codecs line's `mapping: Option`. The `mapping_family: u8` field that #4130 shipped in moq-mux 0.10.8 is removed, and every reader takes the family from `mapping`. +On dev, `moq_mux::codec::opus::Config` stores the channel mapping family in one place: `mapping: Option`. The `mapping_family: u8` field that #4130 shipped in moq-mux 0.10.8 is removed, and every reader takes the family from `mapping`. ## Plan -Decided 2026-09-28 while merging main into the audio-codecs line: that sync keeps both fields so the line stays additive on main, and `encode` refuses a `mapping_family` that disagrees with `mapping`. Removing the duplicate breaks the published moq-mux API, so it lands on dev once the line has merged. Update main's fMP4 and MSF paths that read `mapping_family`, plus the TS importer, which sets both fields. +Decided 2026-09-28 while merging main into the audio-codecs line: that sync keeps both fields so the line stays additive on main, and `encode` refuses a `mapping_family` that disagrees with `mapping`. Removing the duplicate breaks the published moq-mux API, so it lands on dev. Update main's fMP4 and MSF paths that read `mapping_family`, plus the TS importer, which sets both fields. Public API: breaking in moq-mux (field removed). Wire: none. - -## Required - -- [Audio codecs](/quest/m1/audio-codecs/README.md) - the line that introduces `mapping` diff --git a/quest/m1/origin-front-parks.md b/quest/m1/origin-front-parks.md index e31c28fa4e5..729c9c1d825 100644 --- a/quest/m1/origin-front-parks.md +++ b/quest/m1/origin-front-parks.md @@ -28,3 +28,11 @@ show the replacement is cheaper. Public API: no signature change expected. `routed_broadcast` and `request_broadcast` keep their contracts; only where the waiting happens changes. + +Decided in the 2026-09-30 audit: this lands after shared fronts, which +reworks the same `model/origin.rs` fronts, and may move to m2 if shared +fronts' benchmark shows the retry loop's re-mint is noise. + +## Required + +- [Shared fronts](/quest/m0/shared-fronts.md) - reworks the same fronts, and its benchmark decides whether this stays in m1 diff --git a/quest/m1/p2p/transit.md b/quest/m1/p2p/transit.md deleted file mode 100644 index 20a8f23d9d4..00000000000 --- a/quest/m1/p2p/transit.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] Transit in the JS origin - -## Goal - -A tab forwards the routes it receives on one session to the sessions it -serves, so a watcher can re-serve a broadcast to a peer and a room of -watchers can cost the relay one egress stream. Split horizon holds: a route -is never announced back to the session it arrived on, and every forwarded -chain carries the tab's hop id. - -## Plan - -The JS origin keeps two tables so a received entry can never be announced -back to a peer; that separation stays. Transit adds the forwarding step: a -route received on session A is announced on every other attached session -with the tab's hop id appended to `hops`, the receiving link's cost added -per [cost across scopes](/quest/m1/p2p/cost-scopes.md) once it exists and -`Cost::UNKNOWN` semantics until then, and dropped when the chain reaches -`MAX_HOPS` or already contains the tab's id. A retraction forwards the same -way. - -Serving a forwarded route means the tab subscribes upstream once and fans out -from its own origin, which is what the Rust origin already does with -`with_publisher` and `with_subscriber`; the JS origin gains the same -splice-and-share behavior for remote routes it serves onward. - -The hop id must be one per origin, not per session, so the roster id from -[signaling](/quest/m1/p2p/signal.md) and the id in forwarded chains agree. - -Tests with the mock transport pair: a route received on A appears on B with -the id appended and never on A; a chain already containing the id is dropped; -a retraction on A retracts on B; two watchers of one tab share one upstream -subscription. - -## Related - -- [Watch opts in](/quest/m1/p2p/watch.md) - the first topology that needs a forwarding tab diff --git a/quest/m1/parked-read-wakes.md b/quest/m1/parked-read-wakes.md new file mode 100644 index 00000000000..3e403f8b261 --- /dev/null +++ b/quest/m1/parked-read-wakes.md @@ -0,0 +1,33 @@ +# [S] Parked reads wake + +## Goal + +A read parked on a group that is evicted or aborted always wakes and +re-judges, for resume successors and plain tracks alike, pinned by mock-time +regression tests. + +## Plan + +Follow-ups from [#4484](https://github.com/moq-dev/moq/pull/4484), which made +`resume::Successor` recompute its answer on every judgment: + +- Its regression tests cover an aborted unstamped successor only. Eviction + wakes through a different path, so add a resume-level test where the + successor is evicted before its first frame. If it already passes, this + item lands as a test. +- A stamped group that is aborted without being evicted wakes no parked + reader, on a plain track as well as a successor. It only matters under a + timestamp rewind. Reproduce it first, then wake the waiters at the source. + +Settled: one quest, since both are the same wakeup invariant in +`rs/moq-net/src/model/track.rs` and `resume.rs`. + +Land after [resume latest](/quest/m1/resume-latest.md) (#4491), which edits +the same `resume.rs` wakeups, and rebase onto it. + +Public API: none. Wire: none. + +## Related + +- [Resume latest](/quest/m1/resume-latest.md) - edits the same `resume.rs` wakeups; lands first (#4491) +- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - extends the `resume.rs` takeover tests diff --git a/quest/m1/path-patterns.md b/quest/m1/path-patterns.md deleted file mode 100644 index 691bcf1dc30..00000000000 --- a/quest/m1/path-patterns.md +++ /dev/null @@ -1,102 +0,0 @@ -# [M] Path patterns - -## Goal - -Every predicate over a MoQ broadcast path uses one matcher. Tokens, -origin scopes, announce interests, and public access rules can express -`pid/*/chat` and `**/*.hang` without maintaining competing glob dialects. -Routing is not a predicate here: advertisements stay prefixes. - -Literal paths remain coordinates, not sets. Roots, joins, exact broadcast -names, URL paths, filesystem paths, and object-store keys keep their own -types. The relay's `/announced/*prefix` debug endpoint remains a prefix-only -exception. - -## Plan - -### Dialect - -A v1 pattern is canonical `/`-separated segments: - -- a literal; -- `*`, matching one complete segment; -- `lit*lit`, with one `*` matching bytes inside one segment (`*.hang`, `foo*`, - `foo.*.hang`); -- `**`, matching zero or more complete segments, at most once per pattern. - -Patterns are exact by default. `foo` matches only `foo`, `foo/**` matches its -subtree including `foo`, `**` matches every path, and the empty pattern matches -only the current root. Reject leading, trailing, or repeated `/`, more than one -`*` in a segment, `**` mixed with literal bytes, and more than one `**`. A -second star in a segment stays reserved: matching it is still linear, but -containment stops being two string compares. Literal `*` needs no escape: new -path construction and publication reject it, while decoders tolerate it on -legacy protocol versions during rollout. - -Construction moves `**` before adjacent `*` segments: `*/**` becomes -`**/*`. Equivalent wildcard placements therefore share one text and identity. - -A pattern list is an unordered union reduced by containment. The shared -algebra supplies matching, overlap, containment, a literal head, and exact -set-valued rebasing. The set-valued result is load-bearing: rebasing `**/a` at -`a` must preserve both the root match and deeper paths ending in `a`. Union -containment is per member: a candidate covered only jointly by several members -(`a/**` against `a`, `a/*`, `a/*/**`) is refused, so the check stays linear and -a grant that means a subtree writes `a/**`. Pattern precedence uses one total -structural specificity everywhere rules overlap, ordered by literal segments, -then no `**`, then `lit*lit` segments, then `*` segments, then literal bytes -pinned inside `lit*lit` segments, then literal head length. That order agrees -with containment (a strict superset always ranks lower); equal patterns form -the same tier. - -### Ownership and compatibility - -`moq-pattern` and `@moq/pattern` own the grammar and algebra; `moq-net`, -`moq-auth`, `@moq/net`, and `@moq/auth` re-export them. Literal `Path` types -stay in `moq-net` / `@moq/net`. Golden cross-language vectors -(`rs/moq-pattern/tests/pattern.json`), exhaustive small cases, randomized round -trips, and the moq-net fuzz harness's `pattern` target prevent semantic drift at -the authorization boundary. Matching is linear and inherits `Path::MAX_PARTS` -(32), which also bounds residual expansion. - -Grants and claims carry no version. `moq-auth` grants are patterns: `foo` -means exactly `foo` and a subtree is `foo/**`. The published `put`/`get` -prefix encoding stays readable as subtrees, and subtree-only grants are still -written in it so older verifiers keep working. A wire message that carried -prefixes keeps them on the protocol versions that defined them; only new -versions carry patterns. - -The syntax follows Ant-style path patterns without `?`, classes, or braces. -NATS subjects motivate segment wildcards and reserved wildcard bytes; Vault -ACLs motivate structural specificity. Common Access -Token and `draft-ietf-moq-c4m-01` provide exact, prefix, and suffix matches per -namespace field, including exact depth with a trailing `nil`. Document the -exact common subset and keep the richer MoQ forms explicit rather than claiming -CAT cannot represent `pid/*/chat`. - -### Grants on the wire - -AUTH grants on moq-lite-06 carry the shared pattern semantics, without -changing older protocol versions. Interest stays a prefix: [#3770](https://github.com/moq-dev/moq/pull/3770) -keeps patterns off the announce wire, so ANNOUNCE_REQUEST and -SUBSCRIBE_NAMESPACE carry the prefix the caller asked for and a wildcard is -an optional filter on the consume side. - -Replace lite-06 AUTH grant prefixes with patterns in Rust and JavaScript in -the same change. Update the lite draft and version-gated fixtures together. -Authorize by exact containment in the subscriber's v1 grant. Older moq-lite -versions keep their existing prefix wire and behavior; a grant they cannot -represent is refused, not narrowed. Cluster peers adopt nothing as a side -effect of this wire work. - -Test Rust and JavaScript interop, leading wildcards, `**` zero-segment -matches, containment refusal, and old-version behavior. - -## Required - -- [Lite auth](/quest/m1/auth/lite.md) - establish the AUTH exchange before upgrading its grants to patterns - -## Related - -- [Wildcard advertisements](/quest/m0/wildcard/README.md) - routes on prefix - claims; the matcher only filters them against consume-side interest diff --git a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md index a5fccaa027a..4d9317643df 100644 --- a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md +++ b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md @@ -35,7 +35,7 @@ Where the reads are: `close` (rs/moq-uring/src/quic/noq/connection.rs:239), `handle_timeout` (:671), and `poll_transmit` (:786). The last one runs once per GSO train, since `flush` stages one train per turn (see - [Egress requeue](/quest/m1/perf/egress-requeue.md)). + [Run to quiescence](/quest/m1/perf/uring-quiescence.md)). The same profile shows the timer heap at ~1.6%: `::set` 0.92% plus diff --git a/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md b/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md deleted file mode 100644 index 5cce493345b..00000000000 --- a/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] moq-uring: add opt-in NAPI busy polling - -## Goal - -A worker can opt into io_uring NAPI busy polling from relay configuration, -off by default, reported honestly when unsupported, with bare-metal latency -and idle-cost numbers recorded before it is recommended anywhere. - -## Plan - -Follow-up to #2875. - -The relay already pins one worker and one ring per core. io_uring NAPI busy polling can keep a worker close to the NIC receive path and reduce wakeup latency, at the cost of continuously consuming CPU and power while it polls. - -#### Proposal - -- Add an explicit worker-level NAPI configuration with disabled as the default. -- Start with dynamic NAPI-ID tracking through `register_napi`. Add static IDs only if deployment can discover and maintain the correct queue IDs reliably. -- Make busy-poll duration and preferred-busy-poll behavior observable in relay configuration and stats. -- Report unsupported registration clearly. Do not silently claim the mode is active. -- Ensure unregister and worker teardown are safe. -- Document that this mode is for dedicated, latency-sensitive cores, not general self-hosting. - -#### Acceptance - -Measure on bare metal with the deployment NIC and queue affinity configured, not loopback. Compare disabled and several busy-poll durations under low, medium, and saturated load. Record p50, p99, and p999 packet latency, relay CPU, CPU idle residency, interrupts, drops, goodput, and power if available. Ship only as opt-in unless fleet-level data shows an acceptable idle-cost tradeoff. - -## Closes - -- [#3203](https://github.com/moq-dev/moq/issues/3203) - close this issue when the quest finishes diff --git a/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md b/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md deleted file mode 100644 index 904e0547ed2..00000000000 --- a/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] moq-uring: register reusable io_uring_enter wait arguments - -## Goal - -Timed parking reuses one registered `io_uring_reg_wait` entry per worker via -`IORING_ENTER_EXT_ARG_REG` on Linux 6.13+, keeping today's `SubmitArgs` -path (rs/moq-uring/src/worker.rs:305, :410) as the 6.12 fallback, retained -only if cycles per enter measurably drop. - -## Plan - -Follow-up to #2875 and the CQ batching experiment in #3200. - -Timed parking currently builds a `Timespec` and `SubmitArgs` for each wait, then asks the kernel to copy the extended enter arguments. Linux 6.13 added registered wait regions and `IORING_ENTER_EXT_ARG_REG`, allowing a ring to reuse kernel-known wait storage. - -#### Proposal - -- After #3200 fixes the wait shape, register one stable `io_uring_reg_wait` entry per worker. -- Update its absolute deadline, batch target, and minimum wait before each enter, then use `IORING_ENTER_EXT_ARG_REG`. -- Keep the current extended-argument path as the Linux 6.12 fallback. Do not raise the kernel floor for this micro-optimization without benchmark evidence. -- Prefer safe upstream support in the `io-uring` crate. If the current release lacks the registration API, contribute or upgrade that support instead of spreading raw ABI calls through the worker. -- Keep registration ownership and unregistration in one worker-owned type. -- Test repeated deadline changes, no-deadline waits, interrupted enters, and teardown. - -#### Acceptance - -Measure this after the winning #3200 configuration, where enter frequency and argument shape are known. Record cycles and instructions per enter, enters per second, relay CPU, and latency. Retain the 6.13 fast path only if the end-to-end CPU change is measurable. - -## Required - -- [#3200: moq-uring: batch completion wakeups with MIN_TIMEOUT](/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - complete the prerequisite issue first - -## Closes - -- [#3205](https://github.com/moq-dev/moq/issues/3205) - close this issue when the quest finishes diff --git a/quest/m1/perf/README.md b/quest/m1/perf/README.md index 95ae136cdd0..dc7aa2ce62a 100644 --- a/quest/m1/perf/README.md +++ b/quest/m1/perf/README.md @@ -23,7 +23,7 @@ hot-path survey, so quests don't re-litigate them: - `moq-uring`'s only backend is noq. Every profile names its backend. The historical quiche-flavor numbers cited in - [Egress requeue](/quest/m1/perf/egress-requeue.md) and + [Run to quiescence](/quest/m1/perf/uring-quiescence.md) and [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) are re-measured on noq. - Cross-thread wakeups are already cheap: one futex word per worker, at most @@ -43,32 +43,27 @@ The relay's `/metrics` endpoint already carries the ring-level counters (enters, park/wake, batch effectiveness) several quests want as evidence, one row per io_uring worker. -## Required +Decided in the 2026-09-30 audit: io_uring is off by default and ships in no +package, and none of the uring micro-opts is measured on noq. The unmeasured +ones moved out (3129, 3200, 3202, the open contract, and cache shard to m2; +3201 and 3204 to m3), and NAPI busy polling (3203), registered wait +arguments (3205), and the priority `set_track` wakes were dropped. Egress +requeue folded into Run to quiescence; egress keep-alive and owned decode +copies folded into Group cost. The benchmark noise estimate and the noq +re-profile come first, since every quest here accepts "within noise". Lock +wait and One enter per turn rank next: they produce the numbers that decide +the rest. -- [Open contract](/quest/m1/perf/uring-open-contract.md) - plan concurrent WebTransport opening and cancellation +## Required -- [Announce replay](/quest/m1/perf/announce-replay.md) - the initial announce set replays in linear time, so joins don't slow with the route count -- [Group cost](/quest/m1/perf/group-cost.md) - count and cut the allocations and time spent relaying one small group to one viewer -- [One enter per turn](/quest/m1/perf/uring-one-enter.md) - a parking turn pays one io_uring_enter, submits flush deferred completions, and SQEs per enter is a counter -- [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - a received packet's reply is staged in the same turn, under a pass budget that keeps the fairness rule +- [Performance comparisons](/quest/m1/performance-comparisons.md) - the noise estimate every "within noise" verdict here depends on +- [Performance profiles](/quest/m1/performance-profiles.md) - the reproducible noq profile the quests below re-measure on - [Lock wait](/quest/m1/perf/lock-wait.md) - each worker reports time blocked on cross-worker locks, deciding whether the shared model needs work +- [One enter per turn](/quest/m1/perf/uring-one-enter.md) - a parking turn pays one io_uring_enter, submits flush deferred completions, and SQEs per enter is a counter +- [Group cost](/quest/m1/perf/group-cost.md) - count and cut the allocations and time spent relaying one small group to one viewer +- [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - a received packet's reply is staged in the same turn, under a pass and train budget that keeps the fairness rule +- [Announce replay](/quest/m1/perf/announce-replay.md) - the initial announce set replays in linear time, so joins don't slow with the route count - [Ingest batch](/quest/m1/perf/ingest-batch.md) - relay ingest pays one lock, wake, and clock read per chunk burst instead of per chunk -- [Egress cache refresh](/quest/m1/perf/egress-keepalive.md) - measure refresh costs while preserving slow-reader retention -- [Owned decoding copies](/quest/m1/perf/coding-decode.md) - measure and reduce owned decode allocations and copies - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - moq-uring: ~2.5% of relay CPU is vdso clock reads; the drive loop and its callers each re-read Instant::now() -- [Cache shard](/quest/m1/perf/cache-shard.md) - stop hammering one process-global cache line from every worker - [#3199](/quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup -- [#3200](/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - moq-uring: batch completion wakeups with MIN_TIMEOUT -- [#3129](/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring: write the WebTransport stream header at open time, so finish() never owes one -- [Egress requeue](/quest/m1/perf/egress-requeue.md) - trains per turn on the egress driver becomes a measured budget instead of a hardcoded one -- [#3201](/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - moq-uring: use SENDMSG_ZC for large UDP GSO trains -- [#3202](/quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: use fixed-file slots for worker UDP sockets -- [#3204](/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends -- [Priority set_track wakes](/quest/m1/perf/priority-set-track-wakes.md) - a track priority change stops waking groups that end up where they started -- [#3203](/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md) - moq-uring: add opt-in NAPI busy polling -- [#3205](/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md) - moq-uring: register reusable io_uring_enter wait arguments - -## Related - -- [Send buffer pools](/quest/m2/quic-buffer-pool.md) - the stream-send - allocation question, measured on the same shapes +- [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - egress, stream send and receive, and datagram receive stop copying where the QUIC core already allows it, on `dev` after the fork diff --git a/quest/m1/perf/coding-decode.md b/quest/m1/perf/coding-decode.md deleted file mode 100644 index 1e9e7af9301..00000000000 --- a/quest/m1/perf/coding-decode.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] Reduce owned path and byte-string decode copies - -## Goal - -Reduce measured allocation and payload-copy costs for owned byte strings, -strings, and paths without changing decoded values, errors, or wire bytes. - -## Plan - -`rs/moq-net/src/coding/decode.rs` decodes `Vec` through -`Buf::copy_to_bytes` followed by `to_vec`; `String` consumes that vector. -The first operation can return a shared view for a contiguous `Bytes` input, -but may allocate and copy for another `Buf`. Do not count every call as a -payload copy or assume a twofold improvement on production readers. - -Benchmark the actual reader input types, contiguous and chained buffers, -lengths 8 B through 1 KiB, and representative announcement messages. Compare -safe copying into an initialized vector with the current implementation. -Preserve bounds checks before allocation and UTF-8 validation. Keep owned -return types; borrowed decoding and new public APIs are outside this quest. - -Register a Criterion target in `moq-net` for discovery by `just bench`. -Report allocations, copied bytes, and throughput with paired base/current -runs. Retain the current implementation if no useful win is measured. -Add normal-CI regressions for fragmented input, truncated lengths/payloads, -invalid UTF-8, empty values, and path normalization; run the existing net -fuzz targets with `just rs fuzz path` and commit any regression inputs. - -## Related - -- [Benchmark comparisons](/quest/m1/performance-comparisons.md) - measurement conventions diff --git a/quest/m1/perf/egress-keepalive.md b/quest/m1/perf/egress-keepalive.md deleted file mode 100644 index 208b9efa9c4..00000000000 --- a/quest/m1/perf/egress-keepalive.md +++ /dev/null @@ -1,35 +0,0 @@ -# [S] Measure and reduce egress cache-refresh overhead - -## Goal - -Reduce measured cache-refresh overhead during batched delivery without -expiring a group while a slow subscriber or FETCH reader is draining it. -Retain the current behavior if the improvement is within measurement noise. - -## Plan - -`group::Consumer::keep_alive` takes a state read guard and calls -`Charge::refresh`. Both lite and IETF publishers call it between completed -frame writes. This protects a drain that spans longer than `latency_max`; -a stamp only at batch fill is insufficient. `Charge::touch` already skips -population accounting when the coarse timestamp has not advanced. - -Measure read-guard, clock, and atomic costs separately for fast fanout and -flow-controlled readers, including SUBSCRIBE and FETCH. Preserve per-frame -liveness refresh unless an alternative proves the same retention behavior. -Do not introduce another clock or pool-accounting mechanism: those belong to -[Cache shard](/quest/m1/perf/cache-shard.md). Recheck its implementation -before optimizing the remaining publisher overhead. - -Extend the existing group and track Criterion targets and add a bounded -session regression to normal CI. Keep -`slow_prefetch_reader_survives_expiry` (`rs/moq-net/src/model/track.rs`), and cover expiry scans -while a batch drains, cancellation, and eventual expiry after reads stop. -Report delivered bytes, refresh cost, CPU, and throughput for paired runs; -fewer refresh calls alone are not evidence of a win. - -## Related - -- [Cache shard](/quest/m1/perf/cache-shard.md) - owns shared accounting and clock costs -- [Ingest batch](/quest/m1/perf/ingest-batch.md) - ingest batching -- [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - runtime clock costs diff --git a/quest/m1/perf/egress-requeue.md b/quest/m1/perf/egress-requeue.md deleted file mode 100644 index 90ba3987178..00000000000 --- a/quest/m1/perf/egress-requeue.md +++ /dev/null @@ -1,31 +0,0 @@ -# [XS] Trains per turn on the egress driver becomes a measured budget - -## Goal - -The io_uring QUIC driver stages one GSO train per turn and then wakes -itself (`Driver::flush`, rs/moq-uring/src/quic/noq/connection.rs:744), so a -deep backlog on one connection pays a whole driver turn per train of -`TRAIN_SEGMENTS = 63` segments (noq/connection.rs:23; `MAX_GSO_SEGMENTS = -64` at udp.rs:56 is the kernel cap). That cadence is a hardcoded fairness choice. -Make it a measured budget. - -## Plan - -The re-walk half of #3120 landed in #3134 (e6962b20e) on the since-deleted -quiche driver; the noq driver drains an event queue instead of walking -iterators (noq/connection.rs:697) and never had that shape. What is left is -the budget. - -- Add a trains-per-turn budget to `flush`. One train then - requeue is deliberate fairness across connections sharing a socket; keep - fairness by bounding the budget, and sweep 1, 2, and 4 trains per turn - under the fanout and single-heavy-connection shapes to see whether the - extra turn latency is real. -- Re-profile on noq; the numbers in #3120 are the quiche driver's. - -Acceptance: CPU per Gbps and throughput ceiling via `just bench BASE` on -Linux. Latency must not regress at the chosen budget. A no-win keeps 1. - -The [quiescence quest](/quest/m1/perf/uring-quiescence.md) sweeps this -budget together with its pass budget; land whichever runs first and fold the -other's sweep in. diff --git a/quest/m1/perf/group-cost.md b/quest/m1/perf/group-cost.md index a716f8889ef..9dea750f034 100644 --- a/quest/m1/perf/group-cost.md +++ b/quest/m1/perf/group-cost.md @@ -25,6 +25,17 @@ keeps that waiter and skips re-registering on lists that still hold it the next largest source from there. A measured no-win abandons the quest, per this line's rules. -## Related +Decided in the 2026-09-30 audit: two suspected per-group costs merged here +as candidates to measure with `SESSION_ALLOCS`, not separate quests. -- [Owned decoding copies](/quest/m1/perf/coding-decode.md) - decode-side copies are part of the same per-group cost +- Egress cache refresh: `group::Consumer::keep_alive` takes a state read + guard and calls `Charge::refresh` between completed frame writes on both + the lite and IETF publishers. It protects a drain longer than + `latency_max`, so keep per-frame liveness and + `slow_prefetch_reader_survives_expiry` (rs/moq-net/src/model/track.rs); + fewer refresh calls alone are not a win. +- Owned decode copies: `rs/moq-net/src/coding/decode.rs` decodes `Vec` + through `Buf::copy_to_bytes` then `to_vec`, and `String` consumes that + vector. Measure on the real reader input types (contiguous and chained) + before assuming a copy; keep the owned return types, bounds checks, and + UTF-8 validation. diff --git a/quest/m1/perf/lock-wait.md b/quest/m1/perf/lock-wait.md index 2fb63d7918b..e4e922bf7c7 100644 --- a/quest/m1/perf/lock-wait.md +++ b/quest/m1/perf/lock-wait.md @@ -27,7 +27,6 @@ Below one percent, record it and close the quest. Above, open a quest with the measured hot locks named, and only then decide between submitting staged SQEs before a blocking acquire and shrinking the lock in the model. -## Related - -- [Cache shard](/quest/m1/perf/cache-shard.md) - one of the shared cells the - wait would point at +Decided in the 2026-09-30 audit: [Cache shard](/quest/m2/cache-shard.md) +stays in m2 and is taken up only if this shows more than 1% contention on +the pool line. diff --git a/quest/m1/perf/priority-set-track-wakes.md b/quest/m1/perf/priority-set-track-wakes.md deleted file mode 100644 index b830630139c..00000000000 --- a/quest/m1/perf/priority-set-track-wakes.md +++ /dev/null @@ -1,42 +0,0 @@ -# [S] Stop set_track waking groups that end up where they started - -## Goal - -`lite::priority`'s `set_track` (rs/moq-net/src/lite/priority.rs:342) re-ranks -an item as `extract` (:322) then `place` (:261). The extract shifts every following vec entry up one and the place shifts them back -down, so an entry whose rank does not net-change is still woken: the shift up -takes its parked waker, and the shift back finds nothing left to restore. - -A track priority change should wake only the groups whose rank actually moved. - -## Plan - -The insert and remove paths are already exact, because each performs a single -monotone shift where every touched entry genuinely moves by one. Only the -double mutation in `set_track` can cancel itself out. - -Two shapes, cheapest first: - -- Defer the reconcile. Have `update_location` (:236) record the touched id and - leave `PriorityEntry::rank` (:185) holding the last *published* rank, then compare once at - the end of the mutation and wake only the net movers. Simple and total, but it - adds a second slab lookup per shifted entry to the insert hot path, so measure - it against `priority_queue_insert_front` (rs/moq-net/benches/priority.rs:25) - before taking it. -- Rotate instead of remove-and-reinsert. Moving an item within the sorted vec - only shifts the entries strictly between its old and new index, so computing - that range directly is both exact and less work than the two full shifts. It - has to keep the vec/overflow boundary in `place` intact, including the case - where the re-ranked item crosses it. - -The queue rework in #3298 left the wake count on this path as it was. It is a -cold path (a SUBSCRIBE_UPDATE -priority change), never group open or close. - -Acceptance: a test that parks each handle on its own waiter, calls `set_track` -on the front entry within a range where it stays first, and asserts no other -handle woke. No regression on the `priority_queue_insert_front` benches. - -## Related - -- [Hierarchical scheduling](/quest/m1/quic/scheduler.md) - removes this queue where the new scheduler replaces it diff --git a/quest/m1/perf/uring-copies.md b/quest/m1/perf/uring-copies.md new file mode 100644 index 00000000000..591596afc0b --- /dev/null +++ b/quest/m1/perf/uring-copies.md @@ -0,0 +1,31 @@ +# [S] Remove moq-uring's avoidable copies + +## Goal + +moq-uring stops copying and allocating on paths where the QUIC core already +supports zero-copy, with a measured before/after. + +## Plan + +Found in the 2026-09-30 fork planning; none needs a QUIC API change: + +- Egress: `quic/noq/connection.rs` copies each GSO train from `scratch` into + the TX buffer. Hand the TX pool's `Vec` to `poll_transmit` directly; it + encrypts in place and only reserves when capacity is short. +- Stream send: moq-net's `write_chunk(Bytes)` falls back to the trait's + default `poll_write_buf`, which copies through `poll_write(&[u8])`. Route + it to the core's `write_chunks` so large chunks are kept by reference. +- Stream receive: moq-uring uses the trait's default `poll_read_chunk`, which + allocates an 8 KiB `BytesMut` and copies each read. Return the core's + `Bytes` directly. +- Datagram receive: `endpoint.rs` allocates a `BytesMut` per GRO segment. + Copy once per completion and split it into segments. + +The clock-read fix stays in +[#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md). +Measure with the echo benches and `just bench`. This branches from `dev`, +where the fork lands; paths above are pre-fork names. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the copies are removed on `moq-quic`, not the frozen fork diff --git a/quest/m1/perf/uring-one-enter.md b/quest/m1/perf/uring-one-enter.md index 5ff2baf3de9..c6238cdf53c 100644 --- a/quest/m1/perf/uring-one-enter.md +++ b/quest/m1/perf/uring-one-enter.md @@ -42,7 +42,7 @@ fails without the flag. Latency must not regress. ## Related -- [#3200](/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - - the wait side of the same enter - [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - fewer turns per packet, which multiplies this saving +- [#3200](/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - + the wait side of the same enter diff --git a/quest/m1/perf/uring-quiescence.md b/quest/m1/perf/uring-quiescence.md index 88b48797225..ba226bd7291 100644 --- a/quest/m1/perf/uring-quiescence.md +++ b/quest/m1/perf/uring-quiescence.md @@ -29,11 +29,17 @@ must not starve the socket. dispatch, then tasks to quiescence, then submit or park. That removes the stale first pass a park-returning turn runs today (worker.rs:180 polls on readiness the previous turn already consumed). -- The egress driver's one-train-then-self-wake shape - (rs/moq-uring/src/quic/noq/connection.rs:743-751) interacts with the - budget: a deep backlog would consume every pass. Fold the - [egress requeue](/quest/m1/perf/egress-requeue.md) train budget into the - same sweep so trains per turn and passes per turn are measured together. +- The egress driver stages one GSO train of `TRAIN_SEGMENTS = 63` segments + per turn and then wakes itself (`Driver::flush`, + rs/moq-uring/src/quic/noq/connection.rs:743-751), so a deep backlog pays a + whole turn per train and would consume every pass. That cadence is a + hardcoded fairness choice across connections sharing a socket. Make it a + trains-per-turn budget on `flush` and sweep 1, 2, and 4 together with the + pass budget, under the fanout and single-heavy-connection shapes, so trains + per turn and passes per turn are measured together. A no-win keeps 1 train. + The #3120 numbers are the deleted quiche driver's; re-profile on noq. + Decided in the 2026-09-30 audit: the egress requeue quest merged here, since + both budgets need the same sweep. - Add `passes` per turn to the metrics beside `turns`. Acceptance: turns and enters per received datagram on the chat shape @@ -45,8 +51,3 @@ meaning with a budget of 1 and gains a sibling proving the budget bound. - [One enter per turn](/quest/m1/perf/uring-one-enter.md) - the metrics and the submit placement this sweep is measured with - -## Related - -- [Egress requeue](/quest/m1/perf/egress-requeue.md) - the train budget - measured in the same sweep diff --git a/quest/m1/performance-comparisons.md b/quest/m1/performance-comparisons.md index ab8a640e72a..e6e5a01f8a6 100644 --- a/quest/m1/performance-comparisons.md +++ b/quest/m1/performance-comparisons.md @@ -7,14 +7,17 @@ estimate and preserved evidence, so a small reported speedup can be evaluated. ## Plan -`bench/run.sh` runs each relay workload once as base then current, -without repeated rounds or alternating execution order. `cleanup` deletes the run +`bench/run.sh --runtime` already repeats rounds (`MOQ_BENCH_RUNTIME_ROUNDS`, +default 3) and reports the median (`bench/run.sh:15`, `:322`), but the +`just bench BASE` comparison still runs each relay workload once as base then +current, without alternating execution order. `cleanup` deletes the run directory, including Criterion estimates, load/host JSONL, relay logs, and -summaries. Preserve the existing default command -while extending this harness rather than creating another benchmark runner. +summaries. Preserve the existing default command while extending this harness +rather than creating another benchmark runner. -- Add configurable repeated paired rounds, alternate base/current order, and - perform warmup outside the measured window. Keep the current load generator, +- Reuse the runtime mode's rounds and median for the BASE comparison, as + paired rounds that alternate base/current order, and perform warmup outside + the measured window. Keep the current load generator, workload, backend, and resolved settings identical for both revisions. - Save individual paired results and report median paired deltas plus a documented dispersion/confidence estimate. Flag insufficient or noisy samples instead of @@ -36,10 +39,6 @@ while extending this harness rather than creating another benchmark runner. samples. Validate an unchanged-revision A/A run and a deliberately degraded fixture; keep normal machine timing informational rather than a flaky CI gate. -## Required - -- [Tooling](/quest/m1/tooling/README.md) - the recipe and script layout `just bench` runs under - ## Related - [Windowed latency](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - owns histogram/window semantics diff --git a/quest/m1/performance-profiles.md b/quest/m1/performance-profiles.md index e0c5da304c0..b9817b837bb 100644 --- a/quest/m1/performance-profiles.md +++ b/quest/m1/performance-profiles.md @@ -45,5 +45,4 @@ verify current supported versions and pin any newly installed tools. ## Related - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - repeatable results and artifact metadata -- [Relay memory](/quest/m1/relay-memory.md) - retained route and announcement memory - [Release profile](/quest/m1/release-profile.md) - also changes `[profile.profiling]`; land one, then rebase the other diff --git a/quest/m1/pipewire-dup-cameras.md b/quest/m1/pipewire-dup-cameras.md deleted file mode 100644 index c9ad2a46fc6..00000000000 --- a/quest/m1/pipewire-dup-cameras.md +++ /dev/null @@ -1,24 +0,0 @@ -# [XS] A webcam lists once with PipeWire enabled - -## Goal - -`moq_video::capture::cameras()` on Linux with the `pipewire` feature lists a -webcam once. Today a UVC webcam appears as its V4L2 device and again as the -PipeWire node that wraps it ([#4022](https://github.com/moq-dev/moq/pull/4022)). - -## Plan - -Decided: hide PipeWire camera nodes with `device.api = v4l2` whose device the -V4L2 backend already listed, keeping the shorter list over exposing the -backend choice. Nodes V4L2 cannot see stay: libcamera cameras (a Raspberry Pi -CSI camera) and everything inside a sandbox, where V4L2 lists nothing. - -Guidance: - -- Match on the node's V4L2 device path property (`api.v4l2.path`), not the - description, so two identical webcams stay distinct. -- Only the listing changes. `pipewire:` still opens a hidden node, and - the `pipewire` default keeps resolving by priority. -- Update the `cameras()` doc that currently says a webcam appears once per - backend, and cover the filter with a unit test over scanned node - properties. diff --git a/quest/m1/plan-max-delay.md b/quest/m1/plan-max-delay.md new file mode 100644 index 00000000000..a8c700c497f --- /dev/null +++ b/quest/m1/plan-max-delay.md @@ -0,0 +1,27 @@ +# [S] Plan: rename max-age to max-delay + +## Goal + +Decide whether the staleness budget is renamed from `max_age` to `max_delay` +everywhere: the CLI flags (publish and import retention, rtmp, subscribe), the +moq-net `Subscription::max_age` and `track::Info::max_age`, js/net's `maxAge`, +and the bindings. Then rewrite this quest into implementation quests, or +delete it. + +## Plan + +The maintainer finds "delay" clearer than "age" for how far a group may fall +behind before it's skipped. `moq play --delay` and `moq export ts --delay` +(planned in [fixed-delay release](/quest/m1/tstd/delay.md)) use one delay +knob for presentation and staleness; only `moq play`'s exists today. + +To weigh: + +- Publisher retention (`track::Info::max_age`) really is an age of cached + content, while the subscriber budget is a delay. They may deserve different + names rather than one rename. +- The wire fields are `Publisher Max Age` and `Subscriber Max Age` in + `drafts/draft-lcurley-moq-lite.md`. + Renaming the draft's field is free on the wire, but it churns the spec. +- A rename breaks every published API and binding, so it lands on `dev`, + mirrored across Rust, JS, and the bindings in one release. diff --git a/quest/m1/plan-untimed-objects.md b/quest/m1/plan-untimed-objects.md new file mode 100644 index 00000000000..33344c05b2e --- /dev/null +++ b/quest/m1/plan-untimed-objects.md @@ -0,0 +1,46 @@ +# [S] Plan: untimed peer objects + +## Goal + +Decide what a frame's timestamp is when a peer sends none, and rewrite this +quest into implementation quests. That covers IETF objects on a track without +TIMESCALE or without a Timestamp property, and lite-01 to lite-04, which have +no timestamp on the wire. The decision must not invent a timeline that +changes with the relay path. + +## Plan + +Today every receiver fills local arrival time (`Timestamp::from(runtime.now())` +in `rs/moq-net/src/{lite,ietf}/subscriber.rs`, `?? Timestamp.now()` in js/net), +as `drafts/draft-lcurley-moq-timestamp.md` mandates. On lite-05 and later, a +relay then forwards those stamps as if they were real. A failover to another +first hop changes them, so the timeline jumps, and they break the "one clock +per broadcast" property. The maintainer dislikes this. + +Settled elsewhere: publishing always requires a timestamp +([Publishing requires a timestamp](/quest/m1/publish-timestamp.md)), and +lite-05 and lite-06 (published) can't encode an absent one. + +Candidates: + +- Faithful absence (leaning): the model and consumers carry + `Option` so a relay forwards "none" as none. lite-07-wip encodes + it by shifting the FRAME Timestamp Delta and the DATAGRAM Timestamp by one + (0 = absent); an absent frame doesn't move the delta baseline. A lite-05/06 + encoder writes its send time. Untimed groups are never media-stale; the + pool's wall-clock expiry still reclaims them, and start resolution picks the + latest group instead of replaying the cache. +- First-hop arrival, documented: no change, but the failover jump stays. +- 0 as a sentinel: rejected. It collides with a real pts of 0. +- `max_age` on max(wall, pts): the maintainer asked. Rust keeps `max_age` as + media-time staleness so a congestion stall can't age content out, with the + pool's expiry as the wall-clock bound (`rs/moq-net/src/model/cache.rs`). + +Facts to gather: which IETF implementations send TIMESCALE and Timestamp +(moxygen, the interop matrix), and every model decision that reads a +timestamp (`track.rs` staleness and `GroupExpiry`, `resume.rs` successors, +`group.rs` `poll_timestamp`, which treats "has a timestamp" as "has a frame"). + +Output: implementation quests, and updates to +[Data consumer timestamps](/quest/m1/data-consumer-timestamps.md), whose +return type depends on this, and to the timestamp and lite drafts. diff --git a/quest/m1/plan-watch-worker.md b/quest/m1/plan-watch-worker.md index f2bd4e21535..baf471e1771 100644 --- a/quest/m1/plan-watch-worker.md +++ b/quest/m1/plan-watch-worker.md @@ -35,9 +35,14 @@ Prototype both models on the same pipeline and measure them against each other: Settled constraints either way: - `AudioContext` and the render worklet stay on main. The worklet's ring - endpoint (the `SharedArrayBuffer` ring, or a `MessagePort` straight to the - worklet on the postMessage path) is handed to the worker so decoded PCM - never transits main, and the playhead reaches `Sync` the same way. + endpoint is handed to the worker so decoded PCM never transits main, and + the playhead reaches `Sync` the same way. With `SharedArrayBuffer` that is + the shared ring. Without it, main creates a `MessageChannel` and transfers + one port to the worker and the other to the worklet (over `node.port`); PCM + and playhead state then flow worker to worklet and back on that channel. + This keeps the non-isolated path immune to main-thread jank without + COOP/COEP. A transferred `ReadableStream` is not an alternative: it is + postMessage underneath, and the worklet would still drain it into its ring. - `Sync` lives in the worker. Main-thread readers (captions, UI) observe it through the bridge. - `IntersectionObserver`, `visibilitychange`, and the element's size stay on @@ -60,11 +65,14 @@ browser harness pieces instead of starting another. The rewritten implementation quest names the chosen model, the public handle shape of `Player` and ``, what happens to the composable classes, the worker bundling (the publish capture worker's `?worker&inline` is the -precedent; note the CSP `worker-src blob:` consequence), and the follow-up -quest for moving publish onto the same worker if the handle model wins. +precedent; like it, the worker ships a lazy blob plus a hostable file under +the package's assets base, per [strict CSP](/quest/m1/csp-assets.md)), and the follow-up +quest for moving publish onto the same worker if the handle model wins. That +follow-up wires the capture worklet to the encoder worker with a +`MessageChannel` too, so captured PCM also skips main. ## Related - [Watch worker](/quest/m1/watch-worker.md) - the implementation this rewrites - [Browser benchmarks](/quest/m1/browser-benchmarks.md) - artifact conventions; may absorb the harness later -- [A/V clock](/quest/m0/plan-av-clock.md) - the `Sync` shape the implementation moves; the prototype can pace against today's +- [A/V clock](/quest/m1/av-clock.md) - the `Sync` shape the implementation moves; the prototype can pace against today's diff --git a/quest/m2/play-drain-tail.md b/quest/m1/play-drain-tail.md similarity index 100% rename from quest/m2/play-drain-tail.md rename to quest/m1/play-drain-tail.md diff --git a/quest/m1/publish-codec-string.md b/quest/m1/publish-codec-string.md deleted file mode 100644 index 291cbe6ca15..00000000000 --- a/quest/m1/publish-codec-string.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] js/publish advertises the full codec string - -## Goal - -Every video rendition `@moq/publish` puts in the catalog carries a full -RFC 6381 codec string, so native players can decode what browsers publish. -Today the encoder probe in `js/publish/src/video/encoder.ts` falls back to the -bare hints `vp09`, `avc1`, `av01`, and `hev1` when no specific string is -supported, and the catalog publishes the hint as the codec. Rust `hang` parses -those as `VideoCodec::Unknown`, so moq-video and the other native consumers -refuse the track ([#4095](https://github.com/moq-dev/moq/pull/4095)). - -## Plan - -Decided: advertise the codec string from the encoder's own output, -`EncodedVideoChunkMetadata.decoderConfig.codec`, rather than the probe input. -Rust keeps refusing bare hints: the decoder gate needs the profile before it -subscribes. - -Guidance: - -- The catalog is built from the resolved config today, before any frame is - encoded. Either hold the rendition out of the catalog until the first - output reports its `decoderConfig`, or update it then; keep the stall and - jitter reporting working either way. `` holds its first - announce until every captured encoder settles, so holding the rendition out - keeps the whole broadcast unannounced; and since the encoder only runs - while the track is subscribed, holding it until the first output deadlocks - unless the encoder runs without demand until then. -- Check what each browser returns for a bare hint. If one echoes the hint - back, derive the string from the bitstream (SPS for H.264/H.265, the - sequence header for AV1, the uncompressed header for VP9), or fail loud - rather than publish a string no native player accepts. -- A reconfigure (resolution or codec change) can change the string; the - catalog follows it. -- Tests with the fake `VideoEncoder`: a bare-hint probe whose output reports - a full string publishes the full string. diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md new file mode 100644 index 00000000000..0c4aa6b8b09 --- /dev/null +++ b/quest/m1/publish-timestamp.md @@ -0,0 +1,62 @@ +# [L] Publishing requires a timestamp + +## Goal + +Every publish API takes a timestamp, and nothing below it invents one. A +frame's timestamp is the publisher's statement of when the content happened. +A library never fills in "now" on the caller's behalf. Covers moq-net, +moq-json, moq-flate, moq-mux, moq-ffi, and every binding wrapper (Python, +Swift, Kotlin, Go, Dart). Not libmoq, which the +[Generated C bindings](/quest/m1/c/README.md) replace. + +## Plan + +Decided (2026-09-30): the wire timestamp stays required, so the publish side +must be too. Today `Timed.at: None` means "stamp when written": moq-json and +moq-flate fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and +moq-mux's `Clock::stamp` fills the broadcast clock's `now()`. The FFI raw +`MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` default to 0. + +- `moq_net::Timed` keeps its name and gets a required `at: T`, with no + `From`. The json/flate consumers return the same type (see + [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md)). +- moq-json (snapshot, stream, and window, whose `push` always stamps now) and + moq-flate producers take `Timed<_, Timestamp>`. The moq-mux data producers + take `Timed<_, Instant>` and map it onto the broadcast clock, refusing one + ahead of now (`Error::InvalidCapture`), as today; `Clock::stamp` stops + filling `None`. `catalog::data::Listing::record` then always has a capture + time for `delay` and `jitter`. +- Publishers inside the repository (hang catalog snapshots, MSF, stats, room + chat, examples) pass their clock's now explicitly. +- moq-ffi: the + capture time is a media timestamp on the broadcast's timeline. moq-ffi + exposes the broadcast clock's `now()` as a timestamp; callers stamp payloads + with values taken from it, and moq refuses one ahead of now. That keeps a + device or process clock out, as the Rust `Instant` mapping does. Either map + the timestamp back through the clock inside moq-ffi or give the clock a + typed timestamp moq-mux accepts; keep a raw `Timestamp` from compiling + there. The json/flate `update` and `append` take it as a required + argument, and the raw frame and datagram records lose their `default = 0`. +- Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON + producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added + `publish_binary_snapshot` / `publish_binary_stream` (now + `publish_flate_*`) to moq-ffi without them. Add hand-written flate wrappers + there. The maintainer asked for this. + Each wrapper gets a test that a past capture time is accepted and a future + one refused. +- Docs: "stamped when written" in `doc/lib/rs/{moq-json,moq-flate}.md` and + `rs/moq-net/src/model/timed.rs`, plus `doc/lib/{py,swift,kt,go,dart}`. + +What a receiver fills in when a peer sends no timestamp is out of scope: +[Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md). + +Public API: breaking, on `dev`. Wire: none. + +## Required + +- [JSON and flate namespaces](/quest/m1/ffi-shape/json.md) - moves the data producers this changes, so the two breaks land in order rather than colliding + +## Related + +- [Data track clock](/quest/m1/data-track-clock.md) - the moq-mux mapping this keeps reads the catalog's clock at write time +- [JS publishing requires a timestamp](/quest/m1/js-publish-timestamp.md) - the same change in the JS packages diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md index 3bf61cf0617..96e59d38cd3 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -5,8 +5,8 @@ Publishers, relays, and viewers report the telemetry that broadcast health and congestion views need: how far behind viewers are according to what the network has acknowledged, how timely publishers are against their own media -clock, and what publishers and viewers report for themselves in their own -stats broadcasts. Together they can drive an +clock, and what publishers and viewers report for themselves through +[media stats](/quest/m1/stats/README.md). Together they can drive an unknown/healthy/degraded/unhealthy verdict per broadcast with congestion visible for viewers in aggregate, the way CMSD does for HLS. @@ -23,19 +23,17 @@ Everything the relay reports is distilled per broadcast on the existing `moq-stats` keys. No per-subscriber or per-session row reaches the wire from the relay: many subscriptions collapse into byte-weighted cumulative histograms, which stay monotonic and merge-patch friendly, and which any -consumer can diff into a distribution. Clients report for themselves, each in -its own `.stats` broadcast on the same layout, so viewer feedback costs -bandwidth only where a publisher or dashboard chose to read it. +consumer can diff into a distribution. Clients report for themselves through +hang stats and `.echo` feedback tracks, planned in their own line on `main`. The counters and channels land here. The moq.pro (downstream) dashboard work, including the health badge, connection-health drill-down, and stream preflight, consumes them downstream. -Decided (2026-09-28): the whole line, including the client stats line, targets -`dev`. The moq-stats schema change -([#4145](https://github.com/moq-dev/moq/pull/4145)) breaks the published -`moq-stats` crate, and a line cannot close with part of it on `main` and part -on `dev`. +Decided (2026-09-28): the whole line targets `dev`, because its moq-stats +changes break the published crate. Client stats left the line (2026-09-29) +when media stats moved out of moq-stats onto hang tracks, which are additive +on `main`. ## Required @@ -46,12 +44,11 @@ on `dev`. subscription records its last partial interval instead of losing it - [Lag dashboard](/quest/m1/qos/lag-dashboard.md) - the demo stats dashboard shows viewer lag percentiles and dropped media -- [Starvation at frame granularity](/quest/m1/qos/starvation-frames.md) - the - acknowledged frontier moves at every frame boundary through `poll_acked`, - with a delivery-delay histogram for jitter - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - per broadcast, how late media arrives at the relay against the track's own clock, and whether timestamps stay monotonic -- [Client stats](/quest/m1/qos/stats/README.md) - publishers and viewers - report their own media, transport, and playback health in `.stats` - broadcasts on the moq-stats layout, and a Rust encoder adapts to its viewers + +## Related + +- [Media stats](/quest/m1/stats/README.md) - publishers and viewers report + their own media, transport, and playback health, the media half of a verdict diff --git a/quest/m1/qos/lag-dashboard.md b/quest/m1/qos/lag-dashboard.md index c89e45f38f1..4a2d5f01ae7 100644 --- a/quest/m1/qos/lag-dashboard.md +++ b/quest/m1/qos/lag-dashboard.md @@ -21,10 +21,8 @@ and per node like the existing counters. bucket, and say which. - Skip `.`-prefixed system broadcasts, as the existing aggregate does. Lag is per broadcast, so a per-broadcast view is worth adding if it stays cheap. -- The [browser stats quest](/quest/m1/qos/stats/js.md) moves the dashboard - onto `@moq/stats` on the same line. If it has landed, read `lag` and - `dropped` through its schemas; otherwise extend the existing interfaces and - let whichever lands second reconcile. +- Extend the dashboard's existing relay-stats interfaces; no `@moq/stats` + package is planned. Public API: none. Wire: none. diff --git a/quest/m1/qos/publisher-timeliness.md b/quest/m1/qos/publisher-timeliness.md index 8fd16bf480d..682ae47d869 100644 --- a/quest/m1/qos/publisher-timeliness.md +++ b/quest/m1/qos/publisher-timeliness.md @@ -53,5 +53,5 @@ excluded. - [Starvation](/quest/m1/qos/starvation.md) - the egress half, same histogram shape -- [Client stats](/quest/m1/qos/stats/schema.md) - the publisher's own view - of the same uplink, in the transport section of its stats broadcast +- [Media stats](/quest/m1/stats/schema.md) - the publisher's own view + of the same uplink, in the transport section of its stats track diff --git a/quest/m1/qos/starvation.md b/quest/m1/qos/starvation.md index 829af00b10c..9e6c21d5520 100644 --- a/quest/m1/qos/starvation.md +++ b/quest/m1/qos/starvation.md @@ -37,7 +37,7 @@ sample keeps it climbing the buckets while its frontier stands still. While the source is paused nothing is produced, so a tick carries no weight and the histogram does not move; a viewer's lag stays whatever it was until its frontier catches up, and reappears in the buckets once production resumes. This slice moves the frontier once per group; -the [frame-granularity quest](/quest/m1/qos/starvation-frames.md) moves it +the [frame-granularity quest](/quest/m2/starvation-frames.md) moves it per frame without changing the wire shape or the sampler, so fix both here. Aggregate as a byte-weighted cumulative histogram on `Traffic`, on the @@ -81,9 +81,7 @@ sum into one row; the aggregate consumer sums two nodes bucket by bucket. ## Related -- [Starvation at frame granularity](/quest/m1/qos/starvation-frames.md) - - moves the frontier at every frame end once `poll_acked` is released - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - the ingress mirror on the `Role::Subscriber` rows -- [Client stats](/quest/m1/qos/stats/README.md) - receiver-side evidence +- [Media stats](/quest/m1/stats/README.md) - receiver-side evidence for the same lag, reported by the viewers themselves diff --git a/quest/m1/qos/stats/README.md b/quest/m1/qos/stats/README.md deleted file mode 100644 index b74ec7f73f9..00000000000 --- a/quest/m1/qos/stats/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# Client stats - -## Goal - -Any MoQ client can publish its own stats as a broadcast the way the relay -does: a publisher reports what it sends, a subscriber reports what it received -and played, and a consumer authorized to see them, a dashboard or the publisher -itself, reads them per broadcast. The same `moq-stats` layout carries the -relay's delivery counters and a media client's media counters, so one consumer -reads both, and a broadcast name ending in `.stats` is how a dashboard tells -telemetry from content. Encoders close the loop: a Rust publisher can adapt its -bitrate to what its viewers report. Not here: no wire change, no clock -synchronization, no requirement that any client report, and no relay -involvement beyond routing. - -## Plan - -Decisions settled while planning: - -- **Reuse moq-stats.** `moq_stats::Producer` and `Consumer` take an - extension flattened next to `Traffic` in every per-broadcast entry, the way - `hang::timeline::Record` does; `()` is the relay, `hang::Stats` is a - media client. Old consumers ignore the extra fields; a consumer that knows - the extension reads both halves. A client's `Traffic` comes from the same - registry the relay uses, attached through `Client::with_stats`. -- **One broadcast per client at a path its token allows, ending in - `.stats`**: `pilot/feedback.stats`, `room/alice.stats`. The relay's - `.stats/node/` prefix convention stays; moq-stats documents both. - Reporting is opt-in because reading is: a publisher subscribes to a prefix - it chose, never to every viewer. -- **`publisher.json` and `subscriber.json` stay the everything entry points**, - keyed by broadcast path as the client sees it, so a transcoder's report - attributes each rung to its broadcast. A consumer that wants one broadcast - requests `/subscriber.json` or `/publisher.json` (plus `.z`) - and the producer serves it on demand, the way tier tracks are served - today. On a tiered relay the name is `//...`, matched against - the producer's tier labels longest first; a default-tier broadcast whose - path starts with another tier's label is refused rather than guessed. -- **Counters are cumulative**, like `Traffic`, so `.z` merge-patch deltas stay - small and the aggregate can sum across clients. Gauges, a latency or a - target bitrate, are carried but never summed. -- **Publisher transport rides here.** The publisher role carries a - `transport` section sampled from `ConnectionStats` for the connection the - broadcast is published over, replacing the connection-scoped channel the - QoS line planned. Self-reports are diagnostics: never billing, - authorization, or route-selection input. -- **A published break goes through dev**, because `moq-stats` is a published crate and the generic - producer is a breaking change, and the moq-json rework there is what the - producers build on. The parent QoS line targets `dev` with it (#4145), so - every quest here does too. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - moq-stats takes an - extension, serves per-broadcast tracks, and hang defines the media stats -- [Rust reporters](/quest/m1/qos/stats/rust.md) - the CLI, players, and - encoders publish and read `.stats` broadcasts -- [Browser reporters](/quest/m1/qos/stats/js.md) - `@moq/stats` mirrors the - crate, and the browser publisher and player report through it -- [Encoder feedback](/quest/m1/qos/stats/encoder-feedback.md) - a Rust - encoder subscribes to its viewers' stats and adapts its bitrate diff --git a/quest/m1/qos/stats/encoder-feedback.md b/quest/m1/qos/stats/encoder-feedback.md deleted file mode 100644 index f6391b0b7ca..00000000000 --- a/quest/m1/qos/stats/encoder-feedback.md +++ /dev/null @@ -1,52 +0,0 @@ -# [M] A Rust encoder adapts its bitrate to what its viewers report - -## Goal - -A `moq-video` or `moq-audio` encode producer given a feedback prefix -subscribes to the `.stats` broadcasts announced under it, reads the -per-broadcast subscriber track for the broadcast it publishes, and lowers its -bitrate while viewers report stalls and late frames, beside the congestion -estimate it already follows. Which viewers count is the publisher's choice of -prefix. Keyframe requests stay out. - -## Plan - -- `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer - options, beside `bandwidth`) gains `feedback: Option`, - a handle built from an - `origin::Consumer` and a prefix: it consumes announcements under the - prefix, keeps one `moq_stats::Consumer` per `.stats` broadcast - requesting `/subscriber.json`, and folds the reports into one - signal, the share of viewers stalled over the last interval and their late - frame rate, weighted equally per viewer. The counters are cumulative, so - the handle keeps the previous snapshot per viewer and diffs it; a counter - that goes backwards is a restarted viewer and resets that baseline. Viewers - that stop reporting age out on the stats interval, so one stall long ago - never lowers the target forever. -- `moq_mux::rate::Control` takes that signal beside the bandwidth estimate: - a stalled share - above a threshold steps the target down like a bandwidth drop, recovery - follows the existing attack curve, and the estimate stays the ceiling. - Audio does not follow its grant today (`Options::bandwidth` in - `rs/moq-audio/src/encode/producer.rs` reserves only), so it follows this - signal only once the grant quest lands; until then the loop drives video. -- `moq import --feedback ` and `moq transcode --feedback ` - wire it; each rung of the ladder reads its own broadcast's track. -- Test with the CLI publishing to a relay and two `moq play --stats` viewers - under the prefix, one throttled through the impairment profile: the target - bitrate drops within two intervals of the throttled viewer reporting stalls - and recovers after it stops. Document the flag in `doc/bin/cli.md` and the - loop in the moq-video README. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the feedback it reads -- [Rust reporters](/quest/m1/qos/stats/rust.md) - the viewers that report and - the CLI it wires - -## Related - -- [Ladder](/quest/m1/ladder/README.md) - the transcode ladder that adapts to - its uplink today -- [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - - the audio rate follow this signal would feed diff --git a/quest/m1/qos/stats/js.md b/quest/m1/qos/stats/js.md deleted file mode 100644 index 280092e32c2..00000000000 --- a/quest/m1/qos/stats/js.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] The browser publisher and player report stats - -## Goal - -`@moq/stats` mirrors `moq-stats`: the frame schemas, `Producer`, -`Consumer`, the aggregate, and the `.stats` naming. `@moq/hang` defines the -media stats schema, `` publishes subscriber stats and -`` publisher stats when given a stats path, and the demo -dashboard reads relay stats through the package instead of its own copies. - -## Plan - -- `js/stats`: zod schemas for `Traffic`, `Presence`, and `Stats` with the - extension flattened; snapshot-mode producer pairs (`.json` and `.z`) with - the same delta and compression settings as Rust; the per-broadcast track - served on request through the broadcast's requested-track handle; a - consumer keyed by tier, role, and path; and the aggregate. Fixtures are the - Rust crate's, shared through `js/test`, so the two encoders stay wire - identical. -- `@moq/hang` adds `Stats` in `js/hang/src/stats.ts`, mirroring - `rs/hang/src/stats.rs` field for field. -- `js/watch`: the decoder `Stats` signals grow the counters the schema needs - (late, stalled duration, underruns from the worklet's count, decode errors, - newest timestamp) and a `stats` attribute names the broadcast to publish - at; `js/publish` does the same for the encoder counters, with the - connection's `WebTransport.getStats()` as the transport section. The - existing UI stats panels read the same signals. -- `demo/web/src/stats.ts` drops its hand-written interfaces and - `STATS_PREFIX` for the package, and the demo gains a stats path on both - elements so the media test reads a browser viewer's report through - `moq export stats`. -- `doc/lib/js` documents the package. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the wire shape this - mirrors diff --git a/quest/m1/qos/stats/rust.md b/quest/m1/qos/stats/rust.md deleted file mode 100644 index 2a9f7ebb07c..00000000000 --- a/quest/m1/qos/stats/rust.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] The Rust CLI, players, and encoders report stats - -## Goal - -`moq import --stats ` publishes a `.stats` broadcast reporting what the -import sends, `moq export --stats ` and `moq play --stats ` report -what the player received and played, and `moq export stats ` prints any -stats broadcast, the relay's `.stats/node/` included, as JSON lines. A -publisher of a `.hang` broadcast can learn whether its viewers played it. - -## Plan - -- Counters at the source, in the crates that own the event: the `moq-video` - and `moq-audio` encode producers count frames, bytes, keyframes, and drops; - the decode and render paths count decoded, late, stalled, underruns, and - errors, where `underruns` in `rs/moq-audio/src/playback` is already counted - privately. Each exposes a `stats()` snapshot of cumulative counters; no - callback, no per-frame lock. -- `moq-cli` attaches a `moq_net::stats::Session` to its client through - `Client::with_stats`, folds the codec counters into `hang::Stats` per - broadcast on the stats interval, and publishes through - `moq_stats::Producer` in exact-path mode at the flag's path. - A path that does not end in `.stats` is refused at parse time. The transport section comes from - the connection's `ConnectionStats`. -- `moq export stats ` is a new sink: subscribe the stats broadcast and - print each `publisher.json`, `subscriber.json`, and `sessions.json` frame - as one JSON line tagged with its track, with `--track` selecting one and - `--compressed` reading the `.z` twins. It is the one sink that does not go - through `.hang` catalog discovery, so route it around `catalog_format`. -- `doc/bin/cli.md` documents the flag and the sink. The media test - publishes with `--stats`, plays with `--stats`, and reads both with - `moq export stats`, asserting the subscriber's liveness advances and the - publisher's frame count matches what was sent. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the producer and the - media types diff --git a/quest/m1/qos/stats/schema.md b/quest/m1/qos/stats/schema.md deleted file mode 100644 index 2a60d265ece..00000000000 --- a/quest/m1/qos/stats/schema.md +++ /dev/null @@ -1,71 +0,0 @@ -# [L] moq-stats takes an extension and hang defines the media stats - -## Goal - -`moq_stats::Producer` publishes a stats broadcast whose per-broadcast -entries are `Traffic` plus an extension `E`, `Consumer` and the aggregate -read it back, any consumer can request one broadcast's entry as its own -track, and `hang::Stats` is the media extension: what a publisher sent and -what a subscriber received and played, per audio and video. The relay is -`Producer<()>` and its wire output does not change. - -## Plan - -- `moq_stats::Ext`: `Serialize + DeserializeOwned + Default + Clone + Merge`, - implemented for `()`. `Merge` is the aggregate's private `Mergeable` made - public with the `Copy` bound dropped; `Traffic` and `Presence` implement it - as they do today. A frame is `BTreeMap>`, where `Stats` - is `Traffic` with `E` flattened beside it; `TrafficFrame` becomes that - alias for `()`. `sessions.json` stays a core track outside the extension: - `[/]sessions.json[.z]`, a `BTreeMap` keyed by auth - root, read through `Consumer::sessions` whatever `E` is; a client publishes - it only when it holds sessions worth counting. -- An exact-path mode. `produce::Config` treats its path as a prefix and - advertises `/node[/]`, so a client asking for - `room/alice.stats` would publish `room/alice.stats/node`, which no longer - ends in `.stats`. `produce::Config::at(path)` publishes the broadcast at - exactly that path with no category segment, refusing a path that does not - end in `.stats`; the relay keeps the prefix layout. Test the advertised - path for both modes. -- Per-broadcast tracks: `requested_track_shape` in - `rs/moq-stats/src/produce.rs` accepts - `[/]/{publisher,subscriber}.json[.z]` by matching the - producer's tier labels longest first, and refuses a default-tier path that - starts with another tier's label. The track is a snapshot of that one - entry, emitted on the same interval, and lives while requested under the - existing quotas. `Consumer` gains `traffic_for(tier, role, path)`. -- `hang::Stats { audio, video, transport }` in `rs/hang/src/stats.rs`, one - struct per role folded into sections, every field defaulted and unknown - fields ignored: - - subscriber, per audio and video: bytes and frames received, frames - decoded, frames dropped as late, stalls and stalled duration, audio - underruns, decode errors, the newest media timestamp received and the - wall time it arrived (liveness: exact in media time, as good as the - clock in wall time), and the current playout latency as a gauge; - - publisher, per audio and video: frames, bytes, keyframes, frames dropped - before encode, and the target bitrate as a gauge; - - publisher `transport`: rtt, estimated send rate, bytes and packets lost, - and sample age from `ConnectionStats`, repeated across the broadcasts one - connection carries. - `Merge` sums counters, leaves gauges out of the sum, and keeps the newest - liveness pair. -- Naming: `.stats` as a broadcast suffix, documented in the `moq-stats` - crate docs and `doc/lib/rs/index.md` beside the relay's prefix convention, - with `moq_stats::is_stats(path)` so a dashboard filters telemetry from - content. -- The relay keeps `Producer<()>`; the `[stats]` section of - `doc/bin/relay/config.md` gains the per-broadcast track and its refusal - rule. Fixtures: a relay frame parses as `Stats<()>` and as - `Stats` with the extension defaulted; a media frame parses - under the old `Traffic` with the extension ignored; the aggregate sums two - clients' counters and leaves gauges alone; the per-broadcast track for a - tiered name and a refused ambiguous one. -- Drop the legacy `announced` / bare-plural / `*_closed` spellings from the - `Traffic` and `Presence` serializers once a moq-stats release carrying both - has shipped and the demo dashboard (and any moq.pro consumer) reads the - `*_started` / `*_ended` names. Deserialize keeps accepting them. Wire only. - -## Related - -- [Starvation](/quest/m1/qos/starvation.md) - the relay's delivery counters, - the other half of a health verdict diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index 36c4c19aa23..856696ec7b1 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -2,45 +2,42 @@ ## Goal -MoQ owns the QUIC features it needs. noq, the Quinn-derived stack n0 -maintains for Iroh, is the parent; the moq-dev fork carries what MoQ needs on -MoQ's schedule and offers it upstream when it is general. One core serves the -tokio backend, the thread-per-core `moq-uring` backend, iroh, and qmux. The -features are per-stream acknowledgment progress, reliable stream resets, -hierarchical stream scheduling with per-broadcast fairness, the shared stream -state machine used by qmux, per-stream deadlines, and wider limits for relay -peers. The experiments that may join them (GCC, FEC, receive timestamps, -kernel pacing, buffer pools, media probing, L4S, careful resume, deadline -keep-alive) live in [m2](/quest/m2/README.md) and do not gate this line. +MoQ owns the QUIC features it needs in an in-tree stack, `moq-quic`, hard +forked from quinn (see [the fork](/quest/m1/quic/fork/README.md) for why +quinn and not noq). One core serves the tokio backend, the thread-per-core +`moq-uring` backend, and qmux; iroh stays on upstream noq. The features are +BBR correctness, reliable stream resets, hierarchical stream scheduling with +per-broadcast fairness, wider limits for relay peers, and endpoint sharding. +Per-stream acknowledgment progress, per-stream deadlines, qmux on the shared +stream state machine, and the experiments (GCC, receive timestamps, the egress +profile, media probing, L4S, careful resume, deadline keep-alive) live in +[m2](/quest/m2/README.md) and do not gate this line. ## Plan -Everything here ships from moq-dev/noq, the fork MoQ publishes as `moq-noq*`. -One stack carries every change on MoQ's own QUIC paths; a build with the `iroh` -feature also compiles upstream noq, and iroh connections are outside what these -quests reach. +Decided in the 2026-09-30 plan: the moq-dev/noq soft fork is replaced by a +hard fork of quinn in `rs/`, so every QUIC change here waits for +[the fork](/quest/m1/quic/fork/README.md) and lands on `dev`. Retarget this +line's PR (#3975) to `dev` when the fork starts. moq-dev/noq is frozen to +security patches for `main`. -The seven BBR correctness fixes shipped in moq-noq 1.3.1 (#4206). The -remaining BBR quests here and [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) -all edit `bbr3/mod.rs`, so one owner should work there at a time. -Controller-level regressions extend the shared test `Sim` in `bbr3/mod.rs` -with only what each needs, rather than adding another simulation loop; a fix -at the transport boundary still needs a transport test through the real -callbacks. The existing loops stay, since the fork merges upstream weekly and -a port would conflict. Each BBR fix ships in a fork patch release without -waiting for the remaining transport features. The -[Google comparison](/quest/m2/quic-bbr-google.md) is a separate study. +Older quests say "the fork" or "noq"; read that as `moq-quic`. Their steps to +publish a fork release, pin it, or offer a change upstream are superseded: +a change lands in-tree with its consumer, and upstreaming is optional. -Rules the line keeps: +The seven BBR correctness fixes shipped in moq-noq 1.3.1 (#4206) and move to +`moq-quic` with the [BBR3 port](/quest/m1/quic/fork/bbr3.md). The remaining +BBR quests here and [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) all edit +`bbr3/mod.rs`, so one owner should work there at a time. Controller-level +regressions extend the shared test `Sim` in `bbr3/mod.rs` with only what each +needs, rather than adding another simulation loop; a fix at the transport +boundary still needs a transport test through the real callbacks. The +comparison against Google's BBR is part of the separate +[natural drain study](/quest/m2/quic-bbr-natural-drain.md). -- a carried change lists its upstream PR or the reason it has none; -- the fork's packages are `moq-noq-proto`, `moq-noq`, and `moq-noq-udp`, - never a crate that impersonates the parent; -- published MoQ crates depend on crates.io releases of the fork, never a - workspace-only Cargo patch or a mutable branch; -- MoQ's config names congestion families (`Loss`, `Delay`, and `RealTime` - once GCC ships), never algorithms; noq's public `Controller` trait is the - seam experiments plug into, and MoQ owns which algorithm each family means. +MoQ's config names congestion families (`Loss`, `Delay`, and `RealTime` once +GCC ships), never algorithms; the `Controller` trait is the seam experiments +plug into, and MoQ owns which algorithm each family means. The scheduling contract has three levels: strict subscription priority, byte-fair service between send groups at the same priority, then the @@ -49,20 +46,17 @@ session with fairness enabled, the send group is the broadcast. The default MoQ order is newest group first; an ordered subscription keeps oldest first. This is a transport API change, not a MoQ wire change. +Decided in the 2026-09-30 audit: deadlines, qmux, BBR loss parity, ECN +measurement, ACK progress, and the ACK hook moved to m2, since no m1 quest +consumes them. + ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - quinn in-tree as `moq-quic`, with BBR3 and lazy stream slots, and MoQ switched onto it - [BBR idle burst](/quest/m1/quic/bbr-app-limited.md) - a fork regression proves a burst after a long idle is paced at the learned bandwidth, closing #4219 -- [Align BBR loss handling with draft-06](/quest/m1/quic/bbr-loss-parity.md) - losses use their own sample and undo re-enters ProbeUp through Refill - [Mark BBR starvation wherever the source runs dry](/quest/m1/quic/bbr-app-limited-edges.md) - partial polls count, local send caps do not, receiver credit is pinned - [Deliver the application close before io_uring teardown](/quest/m1/quic/uring-close.md) - the peer receives the final close when the client immediately stops its worker -- [Measure ECN on the backbone](/quest/m1/quic/ecn-measure.md) - a written - verdict on marking versus dropping, and whether Linode and OVH keep marks -- [Per-stream ACK progress](/quest/m1/quic/ack-progress.md) - the fork reports - how far a send stream has been acknowledged and when -- [poll_acked in web-transport](/quest/m1/quic/ack-hook.md) - the - backend-neutral hook that awaits an acknowledged stream offset, implemented - for noq and released - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - `RESET_STREAM_AT`, so a reset WebTransport stream still delivers its header - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - strict @@ -70,14 +64,9 @@ This is a transport API change, not a MoQ wire change. the lossy scalar; retransmits follow the same order - [Relay peers get wider limits](/quest/m1/quic/peer-limits.md) - MAX_STREAMS and MAX_DATA are raised after SETUP identifies a cluster peer -- [Per-stream deadlines](/quest/m1/quic/deadline.md) - hopeless retransmits - become resets, and a tail loss probe fires early while there is still time -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - qmux is a - first-class crate in the fork over the shared stream state machine -- [Release the stack](/quest/m1/quic/release.md) - publish immutable, - consumable versions of the fork and its adapters -- [Upstream the fork](/quest/m1/quic/upstream.md) - every general carried - change is offered to n0-computer/noq once its shape has settled +- [Shard the endpoint](/quest/m1/quic/shard.md) - the library shards a + server endpoint across cores by default, replacing the `--workers` group +- [Surface UDP send errors](/quest/m1/quic/send-errors.md) - a client drops a QUIC attempt the moment its address family is unreachable ## Related @@ -85,18 +74,11 @@ This is a transport API change, not a MoQ wire change. per-broadcast fairness policy on cluster sessions - [Starvation](/quest/m1/qos/starvation.md) - the first consumer of ACK progress: how far behind viewers are, from the relay's point of view -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - per-packet arrival - times for GCC and deadlines -- [GCC egress experiment](/quest/m2/quic-gcc.md) - a measured verdict on - WebRTC-style delay control -- [FEC experiment](/quest/m2/quic-fec.md) - a measured verdict on transport - redundancy -- [Kernel pacing](/quest/m2/quic-kernel-pacing.md), [Send batching](/quest/m2/quic-send-batching.md), - [Send buffer pools](/quest/m2/quic-buffer-pool.md), [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - - the syscall, allocation, and controller spikes -- [Multipath spike](/quest/m2/multipath-spike.md) - a noq capability that - MoQ does not use yet - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - per-packet arrival + times for GCC and deadlines +- [GCC egress experiment](/quest/m3/quic-gcc.md) - a measured verdict on + WebRTC-style delay control diff --git a/quest/m1/quic/bbr-app-limited-edges.md b/quest/m1/quic/bbr-app-limited-edges.md index fc47d4d2556..fdcc2b07b2d 100644 --- a/quest/m1/quic/bbr-app-limited-edges.md +++ b/quest/m1/quic/bbr-app-limited-edges.md @@ -32,6 +32,10 @@ drains, a sender blocked only by `send_window`, and a stream blocked by receiver credit. Builds on the seven fixes released in moq-noq 1.3.1. No public API or wire change is intended. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Related - [BBR idle burst](/quest/m1/quic/bbr-app-limited.md) - the first app-limited fix this extends diff --git a/quest/m1/quic/bbr-app-limited.md b/quest/m1/quic/bbr-app-limited.md index f0ea70c90ce..47c10053ad0 100644 --- a/quest/m1/quic/bbr-app-limited.md +++ b/quest/m1/quic/bbr-app-limited.md @@ -27,13 +27,12 @@ minutes, send 250 KB, and assert the pacing rate stays at or above about If it still stalls, find the remaining cause, such as ProbeRTT entered during the idle or a stale `bw_shortterm`, and fix it in the fork. Dropping the estimate after a long idle is a policy change for the m2 study, not this -quest. The `iroh` feature uses upstream noq, which lacks #5; offering it -there belongs to the upstream quest. +quest. -## Closes +## Required -- [#4219](https://github.com/moq-dev/moq/issues/4219) - the first send after an idle period is paced at a trickle +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork -## Related +## Closes -- [Upstream the fork](/quest/m1/quic/upstream.md) - offer the starvation fix upstream +- [#4219](https://github.com/moq-dev/moq/issues/4219) - the first send after an idle period is paced at a trickle diff --git a/quest/m1/quic/fork/README.md b/quest/m1/quic/fork/README.md new file mode 100644 index 00000000000..c016b0574ec --- /dev/null +++ b/quest/m1/quic/fork/README.md @@ -0,0 +1,72 @@ +# Hard-fork quinn into the monorepo as moq-quic + +## Goal + +MoQ's QUIC stack lives in `rs/` as `moq-quic` (the sans-IO core), +`moq-quic-udp`, `moq-quic-tokio`, and `web-transport-moq`, forked from +quinn-rs/quinn `main`. Every MoQ QUIC path (moq-tokio and moq-uring) runs on +it, the `moq-noq*` dependencies are gone, and a QUIC change lands in the same +PR as the MoQ code that needs it. + +Out of scope: iroh keeps upstream noq (the `iroh` feature still compiles it for +iroh's controller factory), and multipath, NAT traversal, and QAD are not +carried. + +## Plan + +Decided in the 2026-09-30 plan, with reasons, so later sessions don't reopen +them: + +- **Hard fork, no merges.** The moq-dev/noq soft fork never merged upstream + (its weekly sync job failed on a workflow-permission error), n0-computer/noq + slowed to 5-7 commits a month in Aug-Sep, and n0's strict semver limits + what we can upstream, not what a fork can change. Upstream fixes are + cherry-picked by hand; offering our changes upstream is optional courtesy, + not tracked work. +- **Base on quinn, not noq.** quinn-proto is 32.9k lines against noq-proto's + 58.5k, about 15k of which is multipath, NAT traversal, and QAD that MoQ + never negotiates. Stripping those from noq was estimated at 2-3 weeks with + loss-recovery risk, and would leave every quinn fix a hand port. quinn ships + security fixes the day the advisory publishes (11 in 2026), and staying + close to its code keeps those cherry-picks cheap. The cost is re-porting + BBR3, the controller callbacks, and lazy stream slots, which is why MoQ + moved to noq in the first place (#1706, #3342, #3789). +- **Multipath is deleted**, and with it the multipath spike. +- **In-tree**, so `just check` and CI cover the stack, one PR spans the core + and its consumers, and `main` and `dev` each carry their own copy instead of + double-landing fixes on the 1.3 and 2.0 fork lines. +- **Named by role**: `moq-quic`, `moq-quic-udp`, `moq-quic-tokio`; + `web-transport-moq` keeps its name. Each crate's README and license credit + quinn and noq. +- **Lands on `dev`.** moq-tokio exposes `noq::Endpoint`, + `noq::TransportConfig`, and `noq::Incoming` publicly, so the crate swap is + a break. +- **Security folds into the fork.** Rebasing on quinn picks up the 2026 + advisories noq is missing; `main` stays on `moq-noq` until `dev` releases. + [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) still finishes on the + old fork for `main`. +- **moq-dev/noq is frozen**: security patches for `main` only, archived once + no released MoQ crate depends on it. The other + [QUIC quests](/quest/m1/quic/README.md) wait for this line and land + in-tree on `dev`. + +This README's own work: delete moq-dev/noq's `moq-sync.yml`, mark its README +frozen, and document advisory triage in `rs/moq-quic/README.md`. `cargo audit` +cannot match renamed crates, so the triage is: watch quinn-rs/quinn's security +advisories and releases, check each fix against `moq-quic`, and port it with +its regression test. Every carried change in moq-dev/noq's `CHANGELOG-MOQ.md` +is either ported by a child quest or recorded as not applicable in the +[switch](/quest/m1/quic/fork/switch.md) PR. + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) - quinn's three crates build and test in-tree as `moq-quic*`, verbatim at a recorded commit, with no consumer yet +- [Port BBR3](/quest/m1/quic/fork/bbr3.md) - the fork's corrected BBR3 and controller callbacks run on `moq-quic` as the default controller +- [Lazy stream slots](/quest/m1/quic/fork/stream-slots.md) - relay memory on `moq-quic` matches `moq-noq` +- [Switch](/quest/m1/quic/fork/switch.md) - `web-transport-moq`, moq-tokio, and moq-uring run on `moq-quic`, and `moq-noq*` is gone + +## Related + +- [Shard the endpoint](/quest/m1/quic/shard.md) - the first feature the fork makes possible +- [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - cheap copy removals on the new core +- [Redesign the QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - the breaking perf rewrite, gated on a profile diff --git a/quest/m1/quic/fork/bbr3.md b/quest/m1/quic/fork/bbr3.md new file mode 100644 index 00000000000..45d81cbcc16 --- /dev/null +++ b/quest/m1/quic/fork/bbr3.md @@ -0,0 +1,37 @@ +# [L] Port BBR3 and the controller callbacks + +## Goal + +`moq-quic` carries the BBR3 controller from moq-dev/noq, with every +correctness fix the fork has shipped, and it is the default controller. The +fork's BBR regressions pass on `moq-quic`. + +## Plan + +Move moq-dev/noq's `congestion/bbr3/` over as a unit rather than starting from +quinn#2481: the fork's copy already descends from #2481 and carries the seven +BBR fixes (#4206), the app-limited fix, and the classic ECN CE response +(moq-dev/noq#12). Port the `Controller` extensions it depends on (`PacketId` +and packet-space callbacks, app-limited, cwnd-limited, ACK frequency) by hand; +they are about 350 lines in `connection/mod.rs` and `pacing.rs`. + +The fork's roughly 580 lines of regression tests are written against noq's +test harness; rework them onto quinn's rather than porting the harness. Keep +MoQ's config naming controller families (`Loss`, `Delay`), never algorithms. + +BBR3 must fill in `ControllerMetrics::bandwidth_estimate` (quinn#2802, merged), +which the [switch](/quest/m1/quic/fork/switch.md) reads for +`web-transport-moq`'s bandwidth stat. + +Verify with the fork's BBR tests and the benchmark matrix against `moq-noq` +1.3.x on the same workloads; report any throughput or latency difference. + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) + +## Related + +- [noq#819](https://github.com/n0-computer/noq/issues/819) - BBR3 as the default, proposed to n0; their sims often favor Cubic +- [noq#475](https://github.com/n0-computer/noq/issues/475) - the original BBR ask +- [noq#768](https://github.com/n0-computer/noq/issues/768) - the `inflight_at_loss` underflow the fork fixed with `saturating_sub`; keep that regression diff --git a/quest/m1/quic/fork/import.md b/quest/m1/quic/fork/import.md new file mode 100644 index 00000000000..b0f6c03b3d2 --- /dev/null +++ b/quest/m1/quic/fork/import.md @@ -0,0 +1,31 @@ +# [M] Import quinn as moq-quic + +## Goal + +`rs/moq-quic`, `rs/moq-quic-udp`, and `rs/moq-quic-tokio` are quinn-proto, +quinn-udp, and quinn from quinn-rs/quinn `main`, and they build and pass their +own tests in `just check` and CI. Nothing consumes them yet. + +## Plan + +Keep the first commit verbatim at a recorded quinn commit so a reviewer can +diff it against upstream; renames, workspace lints, and edition fixes go in +separate commits. Record the parent commit in `rs/moq-quic/README.md` with the +advisory triage process the [questline](/quest/m1/quic/fork/README.md) +describes. + +Carry [quinn#2724](https://github.com/quinn-rs/quinn/pull/2724) as its own +cherry-pick commit (the same fix as noq#746, decided 2026-09-30): when the +kernel rejects a GSO batch with EIO or EINVAL, quinn-udp disables GSO and +drops the batch, so an Android client's Initial waits a full RTO and the +WebSocket fallback wins the race. Resend the batch instead. List it as carried +in `rs/moq-quic/README.md`; drop it if upstream lands +[quinn#2748](https://github.com/quinn-rs/quinn/pull/2748) and we cherry-pick +that. moq-uring's own UDP path (`rs/moq-uring/src/udp.rs`) submits GSO +trains itself, so check whether it drops a rejected train the same way, and +fix it here if so. + +Keep quinn's own features (qlog, rustls providers, runtimes) as they are; +pruning waits until the [switch](/quest/m1/quic/fork/switch.md) shows what MoQ +uses. Wire the crates into release-plz like the other `rs/` crates, and check +that the added test time fits CI. diff --git a/quest/m1/quic/fork/stream-slots.md b/quest/m1/quic/fork/stream-slots.md new file mode 100644 index 00000000000..4956c768bd8 --- /dev/null +++ b/quest/m1/quic/fork/stream-slots.md @@ -0,0 +1,26 @@ +# [S] Lazy stream slots on moq-quic + +## Goal + +`moq-quic` allocates stream state lazily, so relay memory on it matches +`moq-noq` on the bulk and fanout workloads. + +## Plan + +Cherry-pick the approved commits of quinn#2601 (the same change noq took as +noq#667); decided 2026-09-30 not to rebase the upstream PR first. #3342 measured the +difference it makes: 75 vs 141 MiB relay memory on bulk and 31 vs 97 MiB on +fanout. Re-run those workloads on `moq-quic` with and without the change. + +Check the port against quinn's 2026 MAX_STREAM_DATA advisory fix: noq's lazy +stream code was not exploitable there because it checks the limit itself, so +make sure the combined code keeps exactly one check. + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) + +## Related + +- [quinn#2601](https://github.com/quinn-rs/quinn/pull/2601) - the approved upstream PR this cherry-picks +- [noq#667](https://github.com/n0-computer/noq/pull/667) - the same change merged into noq diff --git a/quest/m1/quic/fork/switch.md b/quest/m1/quic/fork/switch.md new file mode 100644 index 00000000000..e69eedff6b5 --- /dev/null +++ b/quest/m1/quic/fork/switch.md @@ -0,0 +1,32 @@ +# [M] Switch MoQ onto moq-quic + +## Goal + +`web-transport-moq` lives in `rs/` on `moq-quic-tokio`, moq-tokio and +moq-uring run on `moq-quic`, and no workspace crate depends on `moq-noq*`. +Upstream `noq-proto` remains only for the `iroh` feature. + +## Plan + +Move `web-transport-moq` from moq-dev/noq. It derives from +web-transport-quinn; its noq-only parts are `PathId::ZERO` and `path_stats`. +Report bandwidth from quinn's `PathStats::bandwidth_estimate` instead of the +current cwnd/rtt guess. + +moq-uring built against both quinn-proto and noq-proto until #3811, behind +about 20 `cfg` lines (stats fields, CID generator, qlog, BBR). Rename +`rs/moq-uring/src/quic/noq` by role and use that history as the map. Keep +moq-uring's `qlog` feature working on quinn's qlog. + +Rename the `noq` cargo features by role (`quic` is the recommendation); +confirm the name with the maintainer in the PR. Update every doc and example +that names noq, and run `just test interop --all`. + +In the PR, list each carried change from moq-dev/noq's `CHANGELOG-MOQ.md` as +ported (with its quest) or not applicable (with the reason). + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) +- [Port BBR3](/quest/m1/quic/fork/bbr3.md) +- [Lazy stream slots](/quest/m1/quic/fork/stream-slots.md) diff --git a/quest/m1/quic/peer-limits.md b/quest/m1/quic/peer-limits.md index 7c36f74bc25..2646f5a6ff5 100644 --- a/quest/m1/quic/peer-limits.md +++ b/quest/m1/quic/peer-limits.md @@ -32,6 +32,7 @@ viewer session does not; the io_uring path applies the same values; a ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork - [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the io_uring workers hardcode their windows today, so the peer values have nothing to raise there until the static windows reach them diff --git a/quest/m1/quic/qmux.md b/quest/m1/quic/qmux.md deleted file mode 100644 index aaf405fdb3f..00000000000 --- a/quest/m1/quic/qmux.md +++ /dev/null @@ -1,56 +0,0 @@ -# [L] Run qmux on the QUIC stream state machine - -## Goal - -qmux uses noq-proto for stream lifecycle, flow -control, datagram buffering, priority scheduling, and transport parameters. -It owns only record framing and the semantics that differ from QUIC, instead -of maintaining a parallel stream implementation. - -## Plan - -Start from the green -[kixelated/quinn#2](https://github.com/kixelated/quinn/pull/2) prototype. Rebase -it onto noq and preserve its central invariant: drive the -existing stream state machine through the same receive and write entry points -as QUIC, then treat serialization to the reliable underlying transport as the -acknowledgment. Do not copy the stream maps, flow-control accounting, reset -state, or datagram queues into a qmux-specific implementation. - -Keep the shared-core patch narrow. The prototype needs only module wiring, a -receive-offset accessor, frame-iterator access, and limited datagram helper -visibility. Review each exposure as a reusable internal boundary rather than -making the whole QUIC connection public. - -`RESET_STREAM_AT` is a QUIC extension, not a qmux-specific frame. Once the -reliable-reset quest lands, make qmux drive that shared send and receive state -instead of retaining the prototype's local parsing and transitions. - -Carry the hierarchical send groups from the scheduler quest into qmux's -record writer. Qmux over TCP, TLS, WebSocket, Unix sockets, and in-memory -duplex transports must produce the same subscription fairness and intra-group -ordering as raw QUIC. This quest owns qmux integration of the scheduler's -reusable acceptance fixtures, including byte fairness, strict priority, -newest/oldest group ordering, cancellation, and blocked-stream behavior. -The native scheduler does not wait for this dependent proof. - -Add the missing wire evidence before release: golden draft-02 vectors, -bidirectional interoperability against the published `qmux` 0.5.x crate, and -the TypeScript qmux/WebSocket peer used by `js/net`. Preserve rejection of -prohibited QUIC frames, params-first setup, record-size validation, close and -reset semantics (the first recorded close wins, which moq-tokio's -`close_code` test checks end to end), keep-alive behavior, and bounded -flow-control tests. - -The crate lives in the fork's workspace as `moq-noq-qmux`, so the stream -state machine internals it drives stay crate-private there; `moq-dev/web-transport`'s -`qmux` becomes a thin re-export or is retired. There must be one stream -state machine in the dependency graph, and the accessors qmux needs are -`pub(crate)` to that workspace, never part of `moq-noq-proto`'s public API. - -## Required - -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - qmux reuses the - extension's stream state rather than implementing reset locally -- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - qmux must - expose the same scheduling contract as native QUIC diff --git a/quest/m1/quic/release.md b/quest/m1/quic/release.md deleted file mode 100644 index fee1d41bdfc..00000000000 --- a/quest/m1/quic/release.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Release the QUIC stack - -## Goal - -Immutable releases of `moq-noq-proto`, `moq-noq`, `moq-noq-udp`, -`web-transport-moq`, and the qmux crate are available to every published MoQ -crate. The workspace lockfile identifies exact released sources, with no -root-only Cargo patch or mutable git branch, and a consumer can tell from any -release which parent commit it carries. - -## Plan - -Release the dependency chain from the bottom up: the fork's crates, which one -tag releases together, then `web-transport-trait` if its surface moved, then -qmux. Pin each released version in this repository's workspace dependencies -and regenerate `Cargo.lock`. Verify minimal, default, and all-feature builds so -enabling iroh, qmux, or the uring runtime cannot unify two incompatible copies -of the protocol state. - -Each fork release documents the parent commit, the carried patches with their -upstream PR or the reason there is none, and the security-update procedure. A -release is incomplete if a consumer cannot tell whether an advisory against -the parent applies. - -## Required - -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - the - WebTransport-required transport extension -- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - the new - transport API -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - the - shared qmux implementation diff --git a/quest/m1/quic/reliable-reset.md b/quest/m1/quic/reliable-reset.md index 10746d214fa..eca1feab383 100644 --- a/quest/m1/quic/reliable-reset.md +++ b/quest/m1/quic/reliable-reset.md @@ -64,11 +64,16 @@ Track the unversioned draft during implementation. The planning baseline is draft 10, with transport parameter `0x1d` and frame type `0x24`; do not freeze provisional codepoints if the document changes before release. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Related - moq-net (`rs/moq-net/src/tail.rs`) and `@moq/net` (`js/net/src/tail.ts`) wait a grace for a group whose reset lost its header until this lands -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - consumes - the same reset state without a parallel implementation - The removed quiche backend was the one stack that had this, so it is the known browser-compliance gap. +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - consumes + the same reset state without a parallel implementation +- [noq#809](https://github.com/n0-computer/noq/issues/809) - the RESET_STREAM_AT ask to n0 diff --git a/quest/m1/quic/scheduler.md b/quest/m1/quic/scheduler.md index a2d95db74d8..9b2748bd7d0 100644 --- a/quest/m1/quic/scheduler.md +++ b/quest/m1/quic/scheduler.md @@ -96,12 +96,16 @@ prove byte fairness over a bounded window, strict preemption by a higher priority, newest-first backlog shedding, dynamic priority updates, blocked-stream handling, sequence wrap and sparse sequence values, and cleanup on reset. This quest owns native QUIC proof and -reusable scheduling fixtures. [qmux](/quest/m1/quic/qmux.md) owns running those +reusable scheduling fixtures. [qmux](/quest/m2/quic-qmux.md) owns running those fixtures through its record writer after adopting the scheduler; native scheduler completion must not wait for that dependent integration. Preserve working behavior on backends not yet migrated, and remove queue code only where the new implementation makes it redundant. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Closes - [#699](https://github.com/moq-dev/moq/issues/699) - close this issue when the @@ -112,8 +116,12 @@ where the new implementation makes it redundant. - [moq#3320](https://github.com/moq-dev/moq/pull/3320) - removes the current dense-rank queue from the wide scalar path and records why a scalar cannot provide this fairness level -- [Ladder controller](/quest/m1/ladder/controller.md) - rendition priority is +- [Ladder controller](/quest/m2/ladder/controller.md) - rendition priority is a policy consumer of the same hierarchy - [Scope track priority](/quest/m1/track-priority-scope.md) - owns the priority semantics this mechanism realizes, including the scheduling-domain scope +- [Signed priority](/quest/m2/signed-priority.md) - changes the priority type + this orders on; keep the ordering, not just the type +- [noq#816](https://github.com/n0-computer/noq/issues/816) - the send-group proposal to n0; this quest supersedes it +- [noq#817](https://github.com/n0-computer/noq/issues/817) - the 64-bit priority ask; send groups replace the scalar, but the per-stream order within a group must still hold a 64-bit group sequence diff --git a/quest/m1/quic/send-errors.md b/quest/m1/quic/send-errors.md new file mode 100644 index 00000000000..429ad578aca --- /dev/null +++ b/quest/m1/quic/send-errors.md @@ -0,0 +1,29 @@ +# [S] Surface UDP send errors so the client can fall back + +## Goal + +When a UDP send fails because the address family is unreachable (for +example an IPv6 target on a host without IPv6 routing), `moq-quic-tokio` +reports the error instead of swallowing it, and moq-tokio's dial race drops +that QUIC attempt at once rather than waiting out the handshake timeout. + +## Plan + +Rebase [kixelated/quinn#3](https://github.com/kixelated/quinn/pull/3) onto +`moq-quic-udp` and `moq-quic-tokio`. It is 154 commits behind quinn main and +never went upstream; it touches only the udp and tokio crates, not the +sans-IO core. Decided 2026-09-30: an m1 quest after the switch, since the +client connect path is user-facing. + +Only fatal, destination-specific errors end the attempt; transient ones +(`ENOBUFS`, `EAGAIN`) stay handled as packet loss, as today. Test the fallback with a dial +against an unroutable family, and check that moq-uring maps the same errors +through its ring. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic-udp` and `moq-quic-tokio` + +## Related + +- [quinn#2766](https://github.com/quinn-rs/quinn/issues/2766) - the upstream issue diff --git a/quest/m1/quic/shard.md b/quest/m1/quic/shard.md new file mode 100644 index 00000000000..b62bd345223 --- /dev/null +++ b/quest/m1/quic/shard.md @@ -0,0 +1,45 @@ +# [M] Shard the QUIC endpoint across cores + +## Goal + +A `moq-quic` server endpoint shards across cores by default where the +platform can steer (Linux): the library +forms the steered `SO_REUSEPORT` group and issues connection IDs that name +their shard, and each runtime (moq-tokio and moq-uring) only drives the +shards it is handed on threads of its own. The relay's `--workers` flag +becomes an optional count override, and the two copies of the group logic +are gone. + +## Plan + +Decided in the 2026-09-30 plan: the library shards and the runtime drives. +The library does not own threads, so embedders (libmoq, moq-ffi) keep their +own threading model. + +- `moq-quic-udp` absorbs `moq-sock::shard` (the group, claims, and steering + filter); `moq-sock` keeps binding and CPU helpers. +- `moq-quic` issues shard-prefixed connection IDs itself, replacing the + custom CID generators in moq-tokio and moq-uring. +- moq-tokio's `worker/group.rs` shrinks to spawning one pinned + `current_thread` runtime per shard; moq-uring's `udp::Bound` group code is + replaced by the library's. +- A server endpoint defaults to one shard per core only where + `SO_REUSEPORT` steering works, which today is Linux: `moq-sock` returns + `Unsupported` for both load balancing and steering elsewhere. macOS and + Windows keep a genuine single-socket endpoint, and an explicit count above + one is refused there rather than silently ignored. +- Before flipping the default, add a benchmark sweeping shard count against + concurrent session load (publishers and subscribers), so steering, + dispatch, and per-shard overhead show up as slopes. A single + default-versus-one-socket run cannot show a cost that grows with either + axis. + +Update `doc/bin/relay/` for the flag change. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the stack has to be in-tree before the library can own sharding + +## Related + +- [UDP demux](/quest/m2/one-port/udp-demux.md) - demuxes each shard's socket; keep the demux over whatever the library hands out diff --git a/quest/m1/quic/upstream.md b/quest/m1/quic/upstream.md deleted file mode 100644 index 294e9c0e44b..00000000000 --- a/quest/m1/quic/upstream.md +++ /dev/null @@ -1,75 +0,0 @@ -# [M] Upstream the fork - -## Goal - -Every general change the fork carries has been offered to n0-computer/noq as -a reviewable pull request, and the fork's carried set is only what upstream -declined or what is MoQ-specific. The noq maintainers have seen this roadmap -before the first proposal lands, so nothing arrives as a surprise. - -## Plan - -Fork now, upstream opportunistically: this quest is the "opportunistically" -half, and it completes the line rather than gating it. Each feature quest -lands in the fork on MoQ's schedule; once a feature has shipped in a MoQ -release and its shape has stopped moving, split it into an upstream PR with -the tests it landed with. - -Offer the seven BBR correctness fixes (moq-noq 1.3.1, #4206) and -their [loss](/quest/m1/quic/bbr-loss-parity.md) and -[starvation](/quest/m1/quic/bbr-app-limited-edges.md) follow-ups with their -regressions before promoting BBR as the default. Reuse existing -upstream work, particularly [PR #802](https://github.com/n0-computer/noq/pull/802), -and preserve attribution; the fork found that #802's `has_sample()` check -fires one ACK late under noq's callback order and that its 1-ms floor keeps -sub-millisecond paths at the placeholder rate, so offer both back there. The -additive `PacketId` callbacks answer upstream's TODO on the `Controller` -impl. Fixes can be offered as their shapes settle; upstream acceptance never -gates the fork's corrected release. - -Then the feature proposal order, each linked to its producing quest: - -0. BBR3 as `TransportConfig`'s default controller (noq-proto 1.2.0 defaults - to Cubic, `config/transport.rs:586`, while MoQ has run BBR3 by default - since it adopted noq): a one-line change whose point is that every noq - and iroh user, the maintainers included, runs the controller MoQ depends - on, so its regressions are found upstream and not only here; -1. per-stream acknowledgment progress ([ACK progress](/quest/m1/quic/ack-progress.md)); -2. `RESET_STREAM_AT` ([reliable reset](/quest/m1/quic/reliable-reset.md)); -3. hierarchical send groups ([scheduler](/quest/m1/quic/scheduler.md)); -4. per-stream deadlines ([deadlines](/quest/m1/quic/deadline.md)); -5. the qmux crate over the shared stream state machine ([qmux](/quest/m1/quic/qmux.md)). - -The m2 features (keep-alive by deadline, careful resume as a `Controller` -wrapper, ECT(1) marking, the media-headroom mechanism) are offered when they -land, but do not gate this quest: an m1 quest must not wait on m2 work. The -next experiments (receive timestamps, GCC, FEC, kernel pacing, send -batching, buffer pools, the natural-drain check) join the list only with a -positive verdict. - -Record in this quest what upstream accepted, what it asked to see as an -extension crate, and what it declined; a declined change stays in the fork -with the link beside it. The quest completes when the list above has been -offered and answered. - -## Required - -- [Align BBR loss handling with draft-06](/quest/m1/quic/bbr-loss-parity.md) -- [Mark BBR starvation wherever the source runs dry](/quest/m1/quic/bbr-app-limited-edges.md) - -- [Per-stream ACK progress](/quest/m1/quic/ack-progress.md) -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) -- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) -- [Per-stream deadlines](/quest/m1/quic/deadline.md) -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - -## Related - -- [Receive timestamps](/quest/m2/quic-receive-ts.md), [GCC](/quest/m2/quic-gcc.md), - [FEC](/quest/m2/quic-fec.md), [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - - experiments that join the list with a positive verdict -- [Keep-alive by deadline](/quest/m2/quic-keep-alive.md), - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md), - [L4S on the backbone](/quest/m2/quic-ecn.md), - [Discover media headroom](/quest/m2/quic-probe.md) - m2 features offered - upstream when they land diff --git a/quest/m1/quic/uring-close.md b/quest/m1/quic/uring-close.md index f3ac2ab58f1..68971a73f69 100644 --- a/quest/m1/quic/uring-close.md +++ b/quest/m1/quic/uring-close.md @@ -16,3 +16,9 @@ Reproduce on a Linux kernel supporting the io_uring worker, both in isolation and alongside the full test suite. Determine where the final close is lost between QUIC output, UDP submission, and worker teardown. Preserve the existing close contract; do not mask the failure with a retry or a longer timeout. + +## Plan + +#4431 (2f4b78581) fixed the same root cause, a paced CONNECTION_CLOSE lost +at teardown. Re-run this test under the #4431 stress setup (8 stress-ng hogs +on one CPU); if it passes, delete this quest. diff --git a/quest/m1/raw-stream-codes.md b/quest/m1/raw-stream-codes.md index 0d9309002a5..7ddf9891e32 100644 --- a/quest/m1/raw-stream-codes.md +++ b/quest/m1/raw-stream-codes.md @@ -15,8 +15,9 @@ on stream errors. WebTransport sessions keep the mapping they need. `web-transport-iroh` and `web-transport-quinn` (moq-dev/web-transport) do the same. A raw peer's code 5 reads as `None` or another value, and ours reaches it as a large HTTP/3 code. -- #4262 fixed the same mix-up for `ApplicationClosed` on `dev`, on - web-transport-trait 0.5, so this follows it there. Let each stream know whether its +- Close codes (#4262, merged on `dev` 09-28) fixed the same mix-up for + `ApplicationClosed` and brought `web-transport-trait` 0.5, which exists + only on `dev`, so this targets `dev`. Let each stream know whether its session is raw and skip the mapping there, in all three adapters, with a round-trip test per adapter against a plain QUIC peer. - Release the fixed crates and bump the pins here in the same quest; published @@ -32,7 +33,7 @@ on stream errors. WebTransport sessions keep the mapping they need. a legacy-sender test per adapter. The other direction has no fix at the receiver: an older peer misreads a fixed peer's raw codes. Check which codes moq-net acts on (group stream resets, subscribe STOP_SENDING): if any drives - behaviour beyond reporting, this is a wire break and retargets to `dev`. + behaviour beyond reporting, this is a wire break as well. Public API: none expected. Wire: raw QUIC stream error codes become the application's own values; compatible only if older peers merely report them. diff --git a/quest/m1/reader-end-parity.md b/quest/m1/reader-end-parity.md new file mode 100644 index 00000000000..dbceda77167 --- /dev/null +++ b/quest/m1/reader-end-parity.md @@ -0,0 +1,32 @@ +# [S] Readers see a track's end at the same moment in Rust and JS + +## Goal + +A track reader in `@moq/net` sees the end as soon as the newest group reaches +the declared end, as Rust readers already do, instead of waiting for the track +to close after the tail settles. The same subscription ends for a reader at +the same point in both languages. + +## Plan + +Found in [#4533](https://github.com/moq-dev/moq/pull/4533): the tails agree +on when a subscription settles, but the reader-facing end differs. The Rust +track model ends for readers once the newest group reaches the declared end, +so a hole waiting out the grace never delays a reader. JS readers wait for the +track to close, grace included. + +Decided with the maintainer: adopt Rust's behavior in JS. A reader isn't held +for the grace over groups it would skip anyway; the tail still settles +separately for accounting. Keep a clean end that has not settled distinct from +an abort, as #4120 and #4116 require. + +Tests: the same scenario in both languages (a declared end with a missing +group in the grace window) reports the end to readers without waiting out the +grace. Consider asserting it across languages in [Track tail +interop](/quest/m1/track-tail-interop.md). + +Public API: none expected; a JS behavior change. Wire: none. + +## Related + +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - names every missing group, so fewer holes reach the grace at all diff --git a/quest/m1/relay-auth-client-ca.md b/quest/m1/relay-auth-client-ca.md index 34623934296..3dec1299618 100644 --- a/quest/m1/relay-auth-client-ca.md +++ b/quest/m1/relay-auth-client-ca.md @@ -10,7 +10,8 @@ config instead of quietly refusing every session. ## Plan -- [#4364](https://github.com/moq-dev/moq/pull/4364) adds an additive +- [#4364](https://github.com/moq-dev/moq/pull/4364) (merged 09-28, and + `dev` has merged `main` since) added an additive `Config::validate_client_ca(&self, client_ca: bool)` that `Relay::load` and the CLI must each remember to call; the CLI missing the original check is the bug it fixes. Fold it into `validate(&self, client_ca: bool)` so every @@ -34,8 +35,3 @@ config instead of quietly refusing every session. Public API: breaks `moq_relay::auth::Config::validate` and `init`, removes `validate_client_ca`, so this targets `dev`. Wire: none. - -## Required - -- #4364 merged to `main` -- `dev` has merged `main` after #4364 lands diff --git a/quest/m1/relay-iroh-opt-in.md b/quest/m1/relay-iroh-opt-in.md index 51e2fa9b54e..522796d96f4 100644 --- a/quest/m1/relay-iroh-opt-in.md +++ b/quest/m1/relay-iroh-opt-in.md @@ -26,5 +26,5 @@ Guidance: ## Related -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - forwards the relay's features from moq-cli's -- [P2P](/quest/m1/p2p/README.md) - why moq-cli keeps iroh +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - forwards the relay's features from moq-cli's +- [P2P](/quest/m2/p2p/README.md) - why moq-cli keeps iroh diff --git a/quest/m1/relay-late-joiner-history.md b/quest/m1/relay-late-joiner-history.md deleted file mode 100644 index bd041dc43ce..00000000000 --- a/quest/m1/relay-late-joiner-history.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Late joiner history - -## Goal - -A second subscriber that joins a relay's track from group 0 while a first -subscriber still holds it receives every group the relay has cached, -including a finished group older than the open live one. A regression test -that joins late through a relay fails before the fix. - -## Plan - -Found downstream on moq.pro: its billing rollup tracks replay a finished -history group followed by an open live group, and a second browser opening -the Cost page on the same edge intermittently loses the older group, so -prior-period usage rows are missing. Production dashboards are affected, -not just tests. #4387 fixed the first viewer's version of this; what it -leaves is the viewer that joins later. - -What we saw: - -- With #4387 applied, moq.pro's `e2e/tests/rollup-history.spec.ts - --repeat-each 12` still fails about a quarter of runs, always on the - second viewer. The edge logs `serving group` only for the newer group on - that viewer's subscription, while the first viewer got both. -- A late-joiner variant of `rs/moq-net/tests/history_groups.rs` showed the - relay's late cursor spliced across two segments with its floor at the - newer group, so the cached older group sat below it. The segment churn - comes through `Action::Query`, `Splice`, `Park`, and `Release` in - `rs/moq-net/src/model/origin.rs`, triggered by the TRACK_INFO request that - precedes each subscription and then goes idle. -- That variant is not a faithful reproduction yet: under paused time the - origin's linger timers fire during the test's idle waits, so it also failed - for lite-03 and the IETF drafts, which the real stack does not. A - reproduction needs to keep the relay's track warm without auto-advancing - past the linger, or drive the timers explicitly. - -Start from how a newly spliced or parked segment derives its floor for a -subscriber that asked for group 0, and whether a warm copy's cached groups -below the new segment's first group stay reachable. The -[splice edge cases](/quest/m1/splice-edges.md) touch the same code. - -## Related - -- [Splice edge cases](/quest/m1/splice-edges.md) - other spliced-track cases that lose or mis-judge groups diff --git a/quest/m1/relay-memory.md b/quest/m1/relay-memory.md deleted file mode 100644 index b4d90377025..00000000000 --- a/quest/m1/relay-memory.md +++ /dev/null @@ -1,41 +0,0 @@ -# [S] Relay memory per announcement - -## Goal - -A relay's memory scales with what it serves, not with what the mesh knows, -and the numbers behind that claim are current. Two costs to keep apart when -measuring: the route table and per-announcement state (`RouteEntry` plus -`ServeState`) scale with announcements and routes, while the served-content -cache a `ServeState` materializes scales with demand. - -## Plan - -Every published figure predates two changes and is untrustworthy: - -- [moq#2989](https://github.com/moq-dev/moq/pull/2989) cut `kio`'s inline - waiter slots from 32 to 4, so a `kio::State<()>` went from 896 B to about - 200 B. Going lower trades memory for an allocation per wake, which - `kio`'s `tests/waiter_allocs.rs` pins; that lever is spent. -- [moq#3225](https://github.com/moq-dev/moq/pull/3225) made a received - announcement a `RouteEntry` plus one `ServeState` whose cache materializes - a broadcast only when something requests a path. A standby route is a - table entry, not an object graph, so degree stopped being a multiplier. - -The old baseline was 8.8 KB per announced broadcast plus 4.3 KB per extra -route on `adad52b`, measured with two throwaway `moq-net` examples driving an -origin under a counting allocator and reading `/proc/self/statm`. Neither is -committed, since they need `#[doc(hidden)]` size probes on private types. -Rebuild them from this description and restate the per-broadcast and -per-route cost, the per-peer session bookkeeping (`announce_ids`, `held`, -`watched`), and the shed threshold on a degree-5, 1 GB node, before anyone -quotes a number again. Chat-shaped traffic (one broadcast per channel or -per chatter) depends on the answer. - -On-demand announcements are now [Cluster routing](/quest/m1/cluster-routing.md)'s -plan: a relay learns only the prefixes its own clients request, which bounds -the table by demand. These numbers size that saving. - -## Related - -- [Cluster routing](/quest/m1/cluster-routing.md) - on-demand announcements shrink the table this measures -- [Perf](/quest/m1/perf/README.md) - the hot-path work that owns the remaining per-cell cost diff --git a/quest/m1/request-stream-serve.md b/quest/m1/request-stream-serve.md new file mode 100644 index 00000000000..287deadb3db --- /dev/null +++ b/quest/m1/request-stream-serve.md @@ -0,0 +1,43 @@ +# [M] Lite request streams stop when the requester leaves + +## Goal + +A lite publisher stops resolving a SUBSCRIBE or FETCH as soon as the +requester closes its send direction, by FIN or reset, as TRACK already does +since #4494 (the draft ends a transaction when either side closes), so an +abandoned request releases its upstream lookup along the whole mesh. Serving +a request stream can't forget that watch: the handlers for TRACK, SUBSCRIBE, +and FETCH never hold the reader while they wait. + +## Plan + +`TrackInfoServe`, `SubscribeServe`, and `FetchServe` in +`rs/moq-net/src/lite/publisher.rs` each repeat the same decode, origin, and +broadcast steps, the same error classification and `abort`, and only +`TrackInfoServe` watches the reader for a FIN or reset. SUBSCRIBE waiting in +`Request` or `Confirm`, and FETCH waiting in `Request` or `Fetch`, pin the +upstream lookup for a requester that already left. + +Share one request-stream wrapper that owns the reader: it decodes the +message, then drives a per-kind handler that gets only the writer, watching +the reader for a FIN or reset for the whole wait. Pending data is not a close: +SUBSCRIBE forwards each SUBSCRIBE_UPDATE to its handler, and only a FIN or a +read error ends the handler. Fold the origin and broadcast steps into one shared +resolve step, so each state enum loses its `Hop` and `Request` variants. + +Rejected: a generic `kio::until(task, scope)`. The interest signal is owned +by the task itself (the reader, a `track::Request`), it covers one phase +rather than the whole task, and cancelling a track is a commit that can lose +to returning demand (`reject_unused`). Those are moq-net concerns, so the +guarantee comes from ownership in moq-net, not a kio combinator. The lite and +IETF subscribers keep their inline `poll_unused` checks. + +Tests: a SUBSCRIBE and a FETCH whose requester FINs or resets while the publisher +waits on the broadcast leave the upstream request unused, over real lite-05 +and lite-06 sessions like `tests/track_info_cancel.rs`. + +Public API: none. Wire: none. + +## Related + +- [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - unanswered FETCHes across relays, where an abandoned request pinning its lookup would show up diff --git a/quest/m1/resume-latest.md b/quest/m1/resume-latest.md index f594bfc566c..3949bfec69e 100644 --- a/quest/m1/resume-latest.md +++ b/quest/m1/resume-latest.md @@ -71,4 +71,5 @@ Regression tests, on a paused clock (`#[tokio::test(start_paused = true)]`): ## Related - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - tells a resumed latest group when the new copy dropped it -- [Splice edge cases](/quest/m1/splice-edges.md) - the same splice code and test harness +- [Parked reads wake](/quest/m1/parked-read-wakes.md) - edits the same `resume.rs` wakeups; lands after this quest's #4491 +- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - extends the same `resume.rs` takeover tests diff --git a/quest/m1/route-cost.md b/quest/m1/route-cost.md new file mode 100644 index 00000000000..e058957d870 --- /dev/null +++ b/quest/m1/route-cost.md @@ -0,0 +1,29 @@ +# [M] One route cost + +## Goal + +A route carries one static cost. Warm and Cold Route Cost, and the +cache-state accounting behind Warm, are gone from the next wip lite version +and from moq-net's model. lite-06 peers keep working. + +## Plan + +Decided in the 2026-09-30 wildcard audit (cache tiers): with configured edge +and core tiers and static core links, nothing switches routes on cache +state, so Warm has no job. + +- The next wip lite version (`moq-lite-07-wip` while it is unpublished) + carries a single route cost in ANNOUNCE_START and ANNOUNCE_UPDATE. Update + `drafts/draft-lcurley-moq-lite.md` in the same PR. +- lite-06 sessions keep parsing both fields: read Warm as the cost and + ignore Cold, and write the one cost as Warm with Cold at the saturation + ceiling. +- The single cost still prices a standby claim above a live one, per the + wildcard line's standby floor. Update that text in + `quest/m0/wildcard/README.md` and anything else naming `Cost { warm, cold }`. +- Replace `Cost { warm, cold }` in `rs/moq-net/src/model/origin.rs` and its + JS mirror, and delete what computes Warm from cache state. +- The moq-transport cluster extension already carries one cost. + +Public API: `Cost` changes shape (a break, so it lands on `dev`). Wire: the +wip version drops a field; lite-06 is unchanged. diff --git a/quest/m1/rs2ts/README.md b/quest/m1/rs2ts/README.md index e37edf9eb0b..b89bcd59c4e 100644 --- a/quest/m1/rs2ts/README.md +++ b/quest/m1/rs2ts/README.md @@ -5,7 +5,7 @@ moq-net is the single implementation of the MoQ protocol and model layer. The browser runs it as TypeScript generated from the Rust source, retiring js/net's hand-written equivalent with no regression in bundle size, CPU, or -usability. Lite comes first, IETF after. Transport glue (the WebTransport and +usability. Lite is this line; IETF follows in m2. Transport glue (the WebTransport and WebSocket pumps, timers) stays hand-written TypeScript. ## Plan @@ -48,18 +48,29 @@ Decided in planning (2026-09-27), with the spike data in - Hand-written js/net fixes keep landing until the generated path replaces them; it is months out. +Decided in the 2026-09-30 audit: the lite half stays in m1 with an explicit +go/no-go after the no-downgrade report below; a no-go stops the line before +anything else is generated. The IETF half (the sans-IO IETF session, +generated IETF, and the IETF parameters quest on this line's branch) moved to +m2 and waits on that go. + +PR #4455 (branch `quest/m1/rs2ts/lite-leading-ones`) changes the lite-07 +varint wire and no quest tracks it; it coordinates with +[subscribe drop](/quest/m1/subscribe-drop.md)'s lite-07 edits. + This README's own work is the no-downgrade report once generated lite ships: bundle size, per-frame CPU, and first-frame latency against the hand-written js/net it replaces, measured with the [browser benchmarks](/quest/m1/browser-benchmarks.md). ## Required +- [Browser benchmarks](/quest/m1/browser-benchmarks.md) - the harness the no-downgrade report uses + - [VarInt codec](/quest/m1/rs2ts/varint-codec.md) - moq-net encodes through a `VarInt` newtype and a concrete slice-based codec, not generic traits on primitives - [rs2ts](/quest/m1/rs2ts/translator.md) - a Charon-based translator emits readable TypeScript for moq-net's lite codec, committed and checked for drift in CI - [Sans-IO moq-net](/quest/m1/rs2ts/sans-io/README.md) - moq-net builds and runs without a runtime; async helpers sit behind an `async` feature - [Mock-clock tests](/quest/m1/rs2ts/mock-clock.md) - moq-net's tests run on the sans-IO clock instead of tokio, so they translate with the code - [Generated lite](/quest/m1/rs2ts/lite.md) - @moq/net's lite session and model layer are generated from moq-net -- [Generated IETF](/quest/m1/rs2ts/ietf.md) - @moq/net's moq-transport session is generated too - [Remove moq-wasm](/quest/m1/rs2ts/remove-wasm.md) - the WASM experiment is deleted once generated lite ships ## Closes @@ -68,10 +79,7 @@ js/net it replaces, measured with the [browser benchmarks](/quest/m1/browser-ben - [#2822](https://github.com/moq-dev/moq/issues/2822) - close this issue when the quest finishes - [#2835](https://github.com/moq-dev/moq/issues/2835) - close this issue when the quest finishes -## Required - -- [Browser benchmarks](/quest/m1/browser-benchmarks.md) - the harness the no-downgrade report uses - ## Related -- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - the same synchronous decode shape, in hand-written js/net today +- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - caps hand-written js/net's subscription controls; generated lite replaces the rest +- [Generated IETF](/quest/m2/rs2ts-ietf.md) - the IETF half, deferred to m2 until the lite go/no-go diff --git a/quest/m1/rs2ts/sans-io/README.md b/quest/m1/rs2ts/sans-io/README.md index 03a4cfb82be..a74c9af8bb6 100644 --- a/quest/m1/rs2ts/sans-io/README.md +++ b/quest/m1/rs2ts/sans-io/README.md @@ -13,11 +13,16 @@ reimplements the async helpers natively with Promises, so the translator reads the crate without the `async` feature. Split by layer so each lands on `dev` independently. -The line has no work of its own beyond its children. +The line has no work of its own beyond its children. Decided in the +2026-09-30 audit: the IETF session moved to m2 with the rest of the IETF +half; this line is lite and the model only. ## Required - [Sans-IO lite session](/quest/m1/rs2ts/sans-io/lite.md) - the lite session is driven by bytes, stream events, and `tick(now)` - [Sans-IO model](/quest/m1/rs2ts/sans-io/model.md) - origin, broadcast, track, and group handles run without a runtime, with time supplied by the caller - [The async feature](/quest/m1/rs2ts/sans-io/async-feature.md) - the async helpers sit behind an `async` feature and a CI lane builds and tests moq-net without it -- [Sans-IO IETF session](/quest/m1/rs2ts/sans-io/ietf.md) - the moq-transport session is driven the same way as lite + +## Related + +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the moq-transport session, deferred to m2 diff --git a/quest/m1/rs2ts/sans-io/async-feature.md b/quest/m1/rs2ts/sans-io/async-feature.md index f7b7e350465..586cc5309e3 100644 --- a/quest/m1/rs2ts/sans-io/async-feature.md +++ b/quest/m1/rs2ts/sans-io/async-feature.md @@ -11,7 +11,7 @@ crate that [Generated lite](/quest/m1/rs2ts/lite.md) translates. - The feature is on by default, so Rust callers see no change. JS reimplements the helpers with Promises over the poll API. - Generated lite needs the lite session and the model without the feature, - not IETF. Until the [Sans-IO IETF session](/quest/m1/rs2ts/sans-io/ietf.md) + not IETF. Until the [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) lands, the IETF session can sit behind the feature too; that quest then moves it out. - The lane runs at least the tests that do not exercise the helpers; tests diff --git a/quest/m1/rs2ts/varint-codec.md b/quest/m1/rs2ts/varint-codec.md index 39557cb31b4..cda246b8ba8 100644 --- a/quest/m1/rs2ts/varint-codec.md +++ b/quest/m1/rs2ts/varint-codec.md @@ -17,7 +17,12 @@ WASM against 6 KB for a hand-carved one. Guidance: -- Keep the 62-bit range; the wire is not bounded to 2^53. +- Widen `VarInt` to the full 64 bits that leading-ones carries on moq-lite-07 + and moq-transport draft-17+, and never bound it to 2^53. QUIC varints still + refuse to encode past 2^62-1. On lite-07 this lets Rust delete the + `BoundsExceeded` arm in the lite dispatch and flips `lite_varint_interop` from + refusal to a round trip. Also revisit `MAX_COST`: costs saturate at 2^62-1 on + every version, but the draft caps them at the largest value a varint carries. - Message types keep a local trait; the primitives become inherent methods on concrete reader and writer types (`varint`, `string`, `bytes`, ...). Make the version a concrete type rather than a generic `V` where possible. diff --git a/quest/m1/rtmp-tls-only.md b/quest/m1/rtmp-tls-only.md deleted file mode 100644 index e281f2021a1..00000000000 --- a/quest/m1/rtmp-tls-only.md +++ /dev/null @@ -1,32 +0,0 @@ -# [XS] RTMP listener can refuse plaintext - -## Goal - -An operator who configures TLS on the RTMP ingest listener can require it. -Today a TLS-configured listener sniffs the first byte and serves any -non-ClientHello connection as plaintext `rtmp://` on the same port -(`rs/moq-rtmp/src/listen.rs`), so setting `tls` silently keeps accepting -unencrypted stream keys. The sniffing behavior stays available; it is just no -longer the only choice. - -## Plan - -Decided by the maintainer during the merged-PR audit: add a mode rather than -drop the sniffing. #3964 shipped mixed mode after a bot review, not a human -one, and nobody chose it for operators who want TLS only. - -- Model it so a TLS-only listener without a TLS config cannot be expressed, - for example an enum carrying the `ServerConfig` (plaintext, TLS required, - TLS or plaintext) instead of a bool beside the `Option`. Keep today's - behavior as the default for an existing `tls` config unless that reads - wrong once written; say which in the PR. -- A plaintext connection to a TLS-only listener is refused at the first byte, - with a log line naming the peer, not left to time out. -- Thread the choice through the relay and gateway configs that build this - listener, and update `doc/bin/rtmp.md` and any relay config docs that - describe RTMPS. -- Test both modes: a plaintext client is refused by TLS-only and served by - mixed. - -Public API: additive on moq-rtmp's listen config if the default holds; a -published break (dev) if the field's type changes. Wire: none. diff --git a/quest/m1/session-death.md b/quest/m1/session-death.md index fbd1ef4ac28..2d848eebcf1 100644 --- a/quest/m1/session-death.md +++ b/quest/m1/session-death.md @@ -40,7 +40,3 @@ Extend the existing session-death tests (Rust integration cases) with a local close and with a group reader, on lite and IETF. Behavior change, no signature change on either side unless the Rust clean end needs a public method. - -## Related - -- [Track tail hardening](/quest/m1/track-tail-hardening.md) - the tail rules this must not mask diff --git a/quest/m1/size-report.md b/quest/m1/size-report.md index 8b1140915c1..9dfb5ffe1cb 100644 --- a/quest/m1/size-report.md +++ b/quest/m1/size-report.md @@ -39,8 +39,8 @@ Decided in planning: visible without a local rebuild. `cargo bloat` needs symbols, so build that pass with `CARGO_PROFILE_RELEASE_STRIP=none` and report stripped sizes separately. -- Following the tooling questline, the work lives in a `sh/` script behind a - `just` recipe, and `nightly.yml` calls the recipe. +- The work lives in a `sh/` script behind a `just` recipe, and `nightly.yml` + calls the recipe. Considered and declined (do not re-ask): diff --git a/quest/m1/slow-group-log.md b/quest/m1/slow-group-log.md deleted file mode 100644 index 91aa5d576fc..00000000000 --- a/quest/m1/slow-group-log.md +++ /dev/null @@ -1,24 +0,0 @@ -# [XS] A starved viewer reports skipped groups once - -## Goal - -When `@moq/watch` falls behind and skips groups past the max age, it logs one -summary per catch-up instead of one warning per skipped group, so a starved -page does not spend its remaining CPU on console traffic. - -## Plan - -`#checkMaxAge` in `js/hang/src/container/consumer.ts` calls `console.warn` -for every group it drops. A 2.5 ms Opus track is one group per frame, so a -page behind on it warns hundreds of times a second. In an interop `go -> js` -cell at load average 182, the subscriber logged 7151 `skipping slow group: -track=tone` lines in 149 s, and Playwright could not resolve the Pause button -for 30 s. Starvation was the cause; the warnings, each forwarded over CDP, -made it deeper. - -Report the skipped range and count once per `#checkMaxAge` call, the way -`watch/src/sync.ts` summarizes late frames. - -## Related - -- [More tests under load](/quest/m1/test-flakes-2.md) - other load-only failures, fixed at the cause diff --git a/quest/m1/source-map-removal.md b/quest/m1/source-map-removal.md new file mode 100644 index 00000000000..f4eddc12de4 --- /dev/null +++ b/quest/m1/source-map-removal.md @@ -0,0 +1,17 @@ +# [XS] Delete SourceMap + +## Goal + +On `dev`, `moq_mux::SourceMap` and `Clock::source` are gone, so an `Anchor` +with its `Lane`s is the one way to map a source onto the broadcast clock. + +## Plan + +`SourceMap` is an `Anchor` plus one `Lane`, and nothing in the repository uses +it. A single-track source uses `Anchor` with one `Lane`. Migrate the +`SourceMap` tests in `rs/moq-mux/src/clock.rs` onto `Anchor`, and update +`doc/lib/rs/moq-mux.md`. + +## Required + +- [Public clock anchor](/quest/m1/clock-anchor-public.md) - `Anchor` and `Lane` must be public first diff --git a/quest/m1/splice-edges.md b/quest/m1/splice-edges.md deleted file mode 100644 index aa0d904500f..00000000000 --- a/quest/m1/splice-edges.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] Splice edge cases - -## Goal - -Three spliced-track cases in `rs/moq-net` stop losing or mis-judging groups, -each with a regression test that fails before its fix: - -- A group whose successor segment's first servable group is still unstamped - keeps an unbounded reach, instead of borrowing a later segment's start and - being skipped or ended with `Error::Old`. -- A reader still draining a pruned segment has its boundary group judged - against the later segments, so a stale boundary group is skipped like any - other. -- A reader draining a warm head keeps it when the upstream fails over again - before the track parks. - -## Plan - -Codex raised all three on https://github.com/moq-dev/moq/pull/4103 and -https://github.com/moq-dev/moq/pull/4104 after the fixes there landed; none -was answered. - -- `served_start` in `rs/moq-net/src/model/resume.rs` says an unstamped group - stops the search, but `find_map` reads a segment's `None` (no group, or its - first group has no frame yet) as a miss and moves on. The two cases need - to be distinguishable, as the per-track `served_start` in - `rs/moq-net/src/model/track.rs` already treats them. -- `ResumeState::successor` finds the cursor's segment by id, so a segment - `prune` removed while a reader still drains it yields no successor at all. - Resolve it from the boundary and the remaining later segments instead. -- An ordinary takeover in `rs/moq-net/src/model/origin.rs` (`Action::Splice` - with no warm copy) overwrites `io.head` with `None`. Dropping the - `WarmGroup` aborts the cached head that a reader resumed from an earlier - park may still be reading, and the next park cannot rebuild the full group. - Keep the existing head when the splice has no new one to take. - -These are independent; one PR is fine since they share the splice tests. diff --git a/quest/m1/srt-import-stats.md b/quest/m1/srt-import-stats.md deleted file mode 100644 index 3460586d8be..00000000000 --- a/quest/m1/srt-import-stats.md +++ /dev/null @@ -1,21 +0,0 @@ -# [S] moq-srt reports the same import stats as moq import ts - -## Goal - -An operator running the SRT gateway sees the TS importer's per-stream -counters (access units, quiet gap, resyncs) the way `moq import ts` logs -them, instead of nothing. SRT contribution is where a silent PID matters -most, and today `rs/moq-srt/src/ts.rs` only calls `decode`. - -## Plan - -- Poll `self.importer.stats()` on the SRT publisher's existing - `ts::Import` at the same cadence as the CLI. -- Share the logging presentation with `rs/moq-cli/src/publish.rs` where - needed so the two front doors report the same rows. -- Test: the SRT harness feeds the suppressed-PID stimulus from the TS - liveness quest and asserts the gateway reports the stalled row. - -## Required - -- [#3489](/quest/m1/3489-ts-import-stream-liveness.md) - the rows this forwards diff --git a/quest/m1/stats-producer-bench.md b/quest/m1/stats-producer-bench.md deleted file mode 100644 index 869404f06b3..00000000000 --- a/quest/m1/stats-producer-bench.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] Stats producer fan-out benchmark - -## Goal - -A `moq-stats` benchmark measures what one relay pays per stats tick to drain -its registry and encode the traffic tracks, swept over held paths and tiers, -so a cost that grows with the whole table instead of the paths that changed -shows up as a slope. It runs at least nightly. - -## Plan - -- [#4299](https://github.com/moq-dev/moq/pull/4299) keeps an idle path in - every frame while the registry holds its counters, adding about 430 B per - idle path to each plain frame (maintainer's note on the PR). Nothing - measures what that, or the per-tick drain, costs as held paths grow. - `rs/moq-stats/benches/decode.rs` covers only the reader. -- Sweep held paths (for example 100 to 50k) against tiers, and the share of - paths that are idle versus changed this tick. Report time and allocations - per tick, and plain and compressed bytes per frame, the way `decode.rs` - reports its table. Include the point where a plain frame nears its size - cap, since a frame that is too large leaves stale counters behind. -- Drive the real producer path (`process_slot`, the snapshot encoders) over - a synthetic `Registry`, not a re-implementation of it. Exposing a bench - hook is fine if it stays out of the public API. -- `decode.rs` is not in CI either. Run both targets once in the nightly - benchmark smoke, as `moq-net`'s are. - -Public API: none. Wire: none. - -## Related - -- [Binary delta stats flavor](/quest/m2/stats-delta.md) - its gate needs the encode baseline this measures -- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - compares these targets across PRs once it lands diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md new file mode 100644 index 00000000000..3bd008a5b29 --- /dev/null +++ b/quest/m1/stats/README.md @@ -0,0 +1,116 @@ +# Media stats and viewer feedback + +## Goal + +A hang publisher can announce a stats track in its catalog, and a publisher +that wants to hear from its viewers can solicit feedback there too. The +publisher's `stats` track is one snapshot of what it sent, per rendition and +for its connection. A viewer publishes one `.echo` broadcast per soliciting +catalog it reads, carrying what it received and played, per rendition, and +its own connection. A dashboard reads both the same way a publisher does. Stats and +feedback cost nothing on the network unless someone subscribes. Not here: the +relay's `moq-stats` layout, which stays as it is; clock synchronization; any +requirement that a client report; and feedback as an input to billing, +authorization, or route selection. + +## Plan + +Decided while planning. This supersedes the moq-stats extension design of +[#4145](https://github.com/moq-dev/moq/pull/4145), revives +[moq#2734](https://github.com/moq-dev/moq/issues/2734) in a reshaped form, and +answers the per-track stats question raised in +[#4496](https://github.com/moq-dev/moq/pull/4496): one snapshot track per +catalog keyed by rendition, not a stats track per rendition and not a sum per +kind. + +- **Media stats leave moq-stats.** The relay is media-agnostic and keeps + `Traffic`, `Presence`, and `.stats/node/` unchanged. Media stats are + hang tracks, discovered through the catalog, so no `Producer` + extension, `Merge` wrapper, or flattened generic is needed. One layout for + relay and clients is given up on purpose. +- **Publisher: `stats: { track }` in the catalog.** A root section naming one + snapshot track: `{ transport, renditions: { : stats::Track } }`, + plus container sections flattened in the way `Catalog` flattens + `ts::Ext`. The stats stay off the catalog track, which would otherwise churn + for every viewer on each interval. +- **Keyed by rendition alias** (2026-09-29). Both snapshots key by the + catalog's rendition keys, which [catalog track + alias](/quest/m1/catalog-track-alias.md) makes aliases unique within a + catalog. Nothing repeats the catalog's `video`/`audio` nesting; the kind + comes from the catalog entry. A viewer reports a rendition that references + another broadcast to the catalog that lists it, under its alias there. The + publisher's own snapshot covers only renditions it writes and omits + referenced ones, whose sender reports them in its own catalog. + Reason: a track name alone collides once a catalog lists renditions from + several broadcasts. +- **Viewer: feedback only when solicited.** Most publishers do not read + feedback, so a publisher solicits it with a root `echo: { path }` section; + absent means none. The section is an object so later fields stay additive. + Root key collisions with application extensions are accepted, not guarded. +- **Echo path in the catalog** (2026-09-29). `path` is relative to the + broadcast serving the catalog and resolves like a rendition's `broadcast` + (URL-style, so from `room/live`, `viewers` is `room/viewers` and + `live/viewers` is `room/live/viewers`). A viewer publishes its `.echo` + broadcast under the resolved prefix at a name the application gives it. The + application issues tokens to match. Reason: applications control the + layout and the token rights, and the publisher reads exactly that prefix. +- **One `.echo` broadcast per catalog** (2026-09-29). A viewer announces it + only after reading the soliciting catalog, and it carries one feedback + track at a fixed name hang defines. It is not a hang broadcast and has no + catalog, so no player lists it as content, and the suffix lets a reader + filter at announce time. The name is generic so keyframe requests and + bandwidth estimates can join later. Reason: a shared `.echo` serving a + track per publisher needed accept-any-name serving, claims, refusals, and + an unclaimed cap to survive name collisions and a publisher subscribing + before the viewer read the catalog; one broadcast per catalog removes the + collisions, the race, and the cap with less code, and needs no JS track + request API. +- **Trust is the token prefix** (2026-09-29). Whoever the application's + tokens let publish under the echo path may report, and no report is + authenticated beyond that. +- **Feedback track: one snapshot**, `{ transport, renditions: { : + echo::Track } }`, so the publisher looks up its own renditions directly. +- **One type per role, shared across kinds.** + - `stats::Track`: sent frames and bytes, keyframes, skipped frames, target + bitrate. + - `echo::Track`: received, decoded, late, decode errors, stalls, + stalled duration, underruns, newest arrival, latency. + - A kind's unused fields are omitted. + - `transport` is one type at both roles: rtt, rate, loss, sample age. A + browser has only PROBE rtt until + [#2733](https://github.com/moq-dev/moq/issues/2733)-style counters land. +- **Encoding**: cumulative counters about once a second through + `moq_json::snapshot`, with the `.z` merge-patch sibling, produced whenever + stats are enabled. An unsubscribed stats track never leaves the process. + Gauges are carried but never summed. +- **On main.** Every change is additive: optional sections on + `#[non_exhaustive]` catalog types, and new types. The line left the + [QoS](/quest/m1/qos/README.md) line, which stays on `dev` for the relay's + moq-stats changes. +- **No `@moq/stats` package.** Media types live in `@moq/hang`, and the + demo dashboard's relay-stats reader stays where it is. +- Docs stay inline: `doc/concept/hang.md` documents both catalog sections, + `doc/concept/stats.md` gains a media section beside the relay's, and + `drafts/draft-lcurley-moq-hang.md` specs the wire. + +Decided in the 2026-09-30 audit: a Rust encoder adapting its bitrate to viewer +feedback moved to [encoder feedback](/quest/m2/stats-encoder-feedback.md) (m2), +along with its open questions. This line only publishes and reads the reports. + +## Required + +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - rendition keys + become aliases, the key both snapshots use +- [Schema](/quest/m1/stats/schema.md) - hang defines the `stats` and + `echo` catalog sections, their snapshot types, and the draft text +- [Rust reporters](/quest/m1/stats/rust.md) - the CLI, players, encoders, and + moq-mux remuxes publish stats and feedback +- [Browser reporters](/quest/m1/stats/js.md) - `` publishes + stats and `` publishes feedback + +## Related + +- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other + half of a health verdict +- [Encoder feedback](/quest/m2/stats-encoder-feedback.md) - a Rust encoder + adapts its bitrate to what its viewers report diff --git a/quest/m1/stats/js.md b/quest/m1/stats/js.md new file mode 100644 index 00000000000..01d5c23531b --- /dev/null +++ b/quest/m1/stats/js.md @@ -0,0 +1,38 @@ +# [M] The browser publisher and player report stats and feedback + +## Goal + +`` announces a stats track in its catalog and fills it. +``, given an echo name, publishes an `.echo` broadcast under the +echo path of a catalog soliciting feedback. Both use the `@moq/hang` schemas. + +## Plan + +- `js/publish`: + - The encoder `Stats` signals are already per rendition (`frames`, + `bytes`, `keyframes`). Add drops and the target bitrate. + - Fold them into the stats snapshot keyed by rendition alias, and write it + through the `moq-json` snapshot producer with its `.z` sibling. A `stats` + attribute enables it. + - `transport` carries PROBE rtt only, because `WebTransport.getStats()` + returns nothing useful in Chromium or Firefox today. +- `js/watch`: + - The decoder `Stats` signals grow late frames, stalls and stalled + duration, underruns from the worklet's count, decode errors, and the + newest arrival. + - An `echo` attribute names the viewer, refused unless it is one path + segment, as in Rust. Once a watched catalog carries an + `echo` section, the element resolves the echo path against the broadcast, + appends `.echo`, and publishes there with the fixed feedback track, keyed by rendition alias, the same rule as + Rust, and reconciles it on each catalog update like Rust. + - Watch elements on one connection watching the same catalog under one + name share its producer, because a second `createBroadcast` at a path + closes the first. +- The existing UI stats panels read the same signals. +- The demo sets both attributes, so the media test can read a browser + viewer's feedback through `moq export echo`. +- `doc/lib/js` documents the attributes. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the zod schemas this fills diff --git a/quest/m1/stats/rust.md b/quest/m1/stats/rust.md new file mode 100644 index 00000000000..6afa565ed05 --- /dev/null +++ b/quest/m1/stats/rust.md @@ -0,0 +1,47 @@ +# [M] The Rust CLI, players, encoders, and remuxes report stats and feedback + +## Goal + +- `moq import --stats` and `moq publish --stats` announce a stats track in + the catalog and fill it with what they send. +- `moq play` and `moq export`, given `--echo `, publish an `.echo` + broadcast under each watched catalog's echo path and fill its feedback + track. +- `moq export stats ` prints a broadcast's stats snapshots, and + `moq export echo ` prints the feedback of every `.echo` broadcast + under a prefix, as JSON lines. + +## Plan + +- Counters come from the source, per track, as cumulative `stats()` + snapshots: no callback, no per-frame lock. + - Publisher: the `moq-video` and `moq-audio` encode producers count frames, + bytes, keyframes, and drops. The `moq-mux` importers count the frames and + bytes they write per track. A remux never encodes, so without them the + CLI would have nothing to report for `moq import`. + - Viewer: the decode and render paths count received, decoded, late, + stalled, underruns, and errors. The `moq-mux` exporters count the frames + and bytes they receive per track, so `moq export --echo` reports a row + for each rendition it remuxes. `underruns` in + `rs/moq-audio/src/playback` is already counted privately. +- `moq-cli` folds the counters into `hang::stats::Snapshot` on the stats + interval and writes it through `moq_json::snapshot`, with the `.z` sibling. + A TS import flattens `ts::Stats` in as `mpegts`. `transport` comes from + the connection's `ConnectionStats`. +- Feedback: after reading a catalog with an `echo` section, the player + resolves the echo path against the broadcast, appends `.echo`, and + publishes there with the fixed feedback + track, keyed by the catalog's rendition aliases. Each catalog update + reconciles it: a removed `echo` section, a changed path, or no longer + watching unannounces the old broadcast. A name that is not a single path segment is refused at + parse time. +- `moq export stats` and `moq export echo` are sinks that skip `.hang` media + discovery, so they route around `catalog_format`. +- `doc/bin/cli.md` documents the flags and sinks. +- The media test publishes with `--stats` and plays with `--echo` against a + publisher that solicits feedback. It asserts that the publisher's frame + count matches what was sent and that the viewer's newest arrival advances. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the sections and snapshot types diff --git a/quest/m1/stats/schema.md b/quest/m1/stats/schema.md new file mode 100644 index 00000000000..31d56e4481e --- /dev/null +++ b/quest/m1/stats/schema.md @@ -0,0 +1,67 @@ +# [M] hang defines the stats and echo sections and their snapshots + +## Goal + +`hang::Catalog` carries two optional root sections, `stats: { track }` and +`echo: { path }`. hang defines the snapshot types those tracks carry: the +publisher's per-rendition and transport counters, and a viewer's +per-rendition and transport feedback. Rust and JS parse the same fixtures, +and the hang draft specs both. Nothing produces them yet. + +## Plan + +- `rs/hang/src/catalog`: `Stats { track }` and `Echo { path }`, both + `#[non_exhaustive]`, as `Option` fields on `Catalog` that are omitted from + the wire when absent. `path` is relative to the broadcast serving the + catalog and resolves through `try_resolve`, like a rendition's + `broadcast`; `.echo` is appended to the result. A path that escapes + the root refuses the catalog. Shared fixtures pin both in both languages. Additive on main. +- `rs/hang/src/stats.rs`: the publisher snapshot, + `Snapshot { transport, renditions: BTreeMap, #[serde(flatten)] ext: E }`. + The generic lets moq-mux flatten `{ mpegts: ts::Stats }` in beside it, the + way `Catalog` takes `ts::Ext`. `Track` holds sent frames, sent bytes, + keyframes, skipped frames, and the target bitrate as a gauge. +- `rs/hang/src/echo.rs`: + `Snapshot { transport, renditions: BTreeMap }`. `Track` + holds: + - received frames and bytes, decoded, late, and decode errors; + - stalls, stalled duration, and underruns; + - the newest media timestamp received, with the wall time it arrived; + - the playout latency, as a gauge. +- Both snapshots key by the catalog's rendition alias. Feedback covers a + rendition that references another broadcast under its alias in the catalog + that lists it; the publisher snapshot omits referenced renditions (decided + in the [README](/quest/m1/stats/README.md)). +- `Transport` is shared: rtt, estimated rate, bytes and packets lost, and + sample age. Every field is optional, because a browser has only PROBE rtt. +- Every field is defaulted, zero and `None` are omitted, unknown fields are + ignored, and each type is `#[non_exhaustive]`. Durations are milliseconds + and rates bits per second, as in `moq-stats`. +- hang names the `.echo` suffix and the feedback track (a helper such as + `hang::echo::is_echo(path)`), so a reader filters at announce time and a + publisher subscribes by a known name. +- `js/hang`: zod schemas mirroring both sections and all three snapshot + types, field for field. Fixtures are shared through `js/test`. +- `drafts/draft-lcurley-moq-hang.md` specs the two sections, the snapshot + schemas, and the `.echo` convention: one broadcast per soliciting catalog, + under the catalog's echo path, announced after the viewer reads the + catalog. Validate with `just drafts check`. +- Open: the MSF catalog conversion in `rs/moq-mux` copies only the media + sections and `ext`, so `stats` and `echo` drop silently under + `--catalog-format msf`. Candidates: carry them through MSF with a + round-trip test, or refuse `--stats` and `--echo` with MSF. +- Docs: `doc/concept/hang.md`, and a media section in `doc/concept/stats.md`. +- Tests: + - fixtures round-trip in both languages; + - an old catalog without the sections parses unchanged; + - a snapshot with an unknown field parses. + +## Required + +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - the rendition + alias both snapshots key by + +## Related + +- [#4145](https://github.com/moq-dev/moq/pull/4145) - the closed moq-stats + extension design; salvage its field docs and serde helpers diff --git a/quest/m1/subscribe-drop.md b/quest/m1/subscribe-drop.md index 3f93210d63d..a74d3596df7 100644 --- a/quest/m1/subscribe-drop.md +++ b/quest/m1/subscribe-drop.md @@ -34,6 +34,9 @@ Decided: grace, as today. - A resumed group ([Resumed groups](/quest/m1/resume-latest.md)) that is the new copy's latest ends with the DROP's error when the copy drops it. +- A dropped or aborted group is visible to readers, not silently skipped. + #4533 found the Rust model releases an aborted group's sequence and skips it, + so a truncated first object is indistinguishable from a group never sent. Update `drafts/draft-lcurley-moq-lite.md` (SUBSCRIBE_DROP, SUBSCRIBE_END, the lite-07 changelog), `doc/concept/moq-lite.md`, and the Rust and JS lite @@ -44,7 +47,17 @@ Regression tests: a publisher that expires a group, skips a sequence, and resets a stream before its header; on each version the subscriber settles without waiting out the grace. +Add the lite-07 drop case to the tail interop harness from +[track tail interop](/quest/m1/track-tail-interop.md): Rust and JS +subscribers both settle on SUBSCRIBE_DROP through the relay, so a group the +publisher skipped or never opened ends the track without waiting out the +grace. Decided in the 2026-09-30 audit: the case moved here so the basic +tail interop could land first. + +PR #4455 (`quest/m1/rs2ts/lite-leading-ones`) also edits the lite-07 wire +(varints) and no quest tracks it; coordinate the draft's lite-07 changelog +with it. + ## Related -- [Track tail hardening](/quest/m1/track-tail-hardening.md) - the same tail accounting, in both languages -- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS proof of the lite-07 drop case +- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS tail harness the lite-07 drop case extends diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index fdc80654421..7da5d132bb0 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -44,7 +44,7 @@ relay bounds a sparse FETCH only if the model can request ranges: - Ranges are frame-precise (`Position`), not whole groups. The IETF joining FETCH for a mid-group SUBSCRIBE's uncached prefix stays, because today's bridge relies on it (maintainer, 09-29). -- The relay half of [fetch-span](/quest/m1/moxygen/README.md) (#4558) moves +- The relay half of fetch-span (#4558, from the finished Moxygen line) moves here; #4558 lands only the no-handler skip. This line owns the end-to-end test: a relay with a sparse cache answers a diff --git a/quest/m1/test-flakes-2.md b/quest/m1/test-flakes-2.md deleted file mode 100644 index 44fbc2ad56c..00000000000 --- a/quest/m1/test-flakes-2.md +++ /dev/null @@ -1,84 +0,0 @@ -# [S] More tests hold up under load - -## Goal - -A second round after [#4286](https://github.com/moq-dev/moq/pull/4286): -tests that pass alone but have failed under a loaded `just check` pass -reliably, each fixed at its cause, never by raising a timeout or adding a -retry. - -- moq-cli `fetch::tests::a_frame_read_times_out` asserts on a 500 ms wall - deadline ([#4084](https://github.com/moq-dev/moq/pull/4084)). The cause - (#4431): `rs/moq-cli/src/fetch.rs` wraps the whole run in one - `timeout_at(deadline, ...)`, so connect, TLS, announce, and subscribe share - the budget with the read, and under load setup alone can spend it. -- moq-cli `complete::tests::a_stage_broadcast_picks_the_catalog_to_read` - ([#4084](https://github.com/moq-dev/moq/pull/4084)), - `the_catalog_format_on_the_line_is_honored` - ([#4089](https://github.com/moq-dev/moq/pull/4089)), and - `a_relay_on_the_line_answers_broadcast`: both of the latter pair came back - empty after the fixed 1.5 s `CEILING` on a loaded runner - ([#4404](https://github.com/moq-dev/moq/pull/4404)). -- moq-net `model::group::test::drop_unfinished_warns` counts WARNs through a - global tracing capture, so another test's WARN, or a missed one, changes - the count ([#4104](https://github.com/moq-dev/moq/pull/4104)). The - `model::track` test of the same name uses the same helper. -- moq-tokio `broadcast_race_quic_wins` binds TCP `:0` and then UDP on the - same number, which nothing reserves: the collision - [#4084](https://github.com/moq-dev/moq/pull/4084) removed from its sibling - after [#4055](https://github.com/moq-dev/moq/pull/4055) papered over it with - a retry. -- moq-tokio - `subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` - ends `Ok(None)` with 10 of 20 frames in 3 of 8 full-suite runs on a clean - tree, and passes alone (#4332). -- `just test media` late join failed once after - [#4181](https://github.com/moq-dev/moq/pull/4181): "joined at frame 111, 16 - frames behind 127", against a budget of one GOP (15). -- js/publish audio encoder test "a rendition trailing the broadcast's - earliest advertises delay" reads the real clock, so it fails when its file - runs alone (timestamps go negative early in the process) (#4414). Mock time. -- moq-mux `container::ts::export_test::debounce_opens_without_a_media_clock` - died with SIGTERM once in a combined run. It is marked - `start_paused = true` but sleeps 1.2 s of real time, because the debounce - reads `crate::Clock`, which uses `std::time::Instant`, so the paused tokio - clock never reaches it. - -## Plan - -- Timing tests: prefer a paused clock over wall time (`moq-cli`'s - subscribe tests already use `#[tokio::test(start_paused = true)]`), or - assert on an event instead of a deadline. If a test is slow under load - because the code under test is slow, fix that. -- Fetch timeout: test on a paused clock (maintainer decision, 2026-09-28). - The fixture runs real sockets against an in-process relay, where a paused - clock fires QUIC timers while packets are in flight, so first make the - timers mockable: run the fixture over an in-memory transport, or drive - noq's timers from the test clock, whichever is smaller. Keep the one - absolute 30 s deadline, matching the relay's `/fetch`; on a paused clock - setup costs no time, so it can't spend the read's budget. -- moq-mux debounce: let the test drive `crate::Clock`'s time (a tokio - `Instant` under test, or an injected source) so the window passes on the - paused clock, and drop the real sleep. -- WARN counting: capture per test (a scoped subscriber or a filter on the - test's own span) instead of a process-global count. -- The race test shares one port only so both transports sit behind one URL. - Separate `:0` ports fix the bind collision but not the race itself: with - `websocket.delay = 0` either arm can legitimately win under load. Make the - order deterministic the way #4084 did, holding the WebSocket arm until QUIC - has connected, rather than asserting on a real race; no retry. #4084's follow-ups - (`tests/reconnect.rs` `spawn_server`, `tests/worker.rs` `free_udp_port`) - are the same probe-and-rebind pattern; fix them here if cheap. -- Media late join: first decide whether 16 frames is a real regression (the - player joining at the previous GOP's keyframe) or an off-by-one in how the - fixture samples the live edge. Fix whichever it is; don't widen the - budget without a reason. -- Prove it by running `just check --all` several times on a loaded machine, - as the first round did. - -Public API: none. Wire: none. - -## Related - -- [Archive enrollment](/quest/m1/archive/enrollment-flake.md) - the same - kind of flake on the archive line, where its test lives diff --git a/quest/m1/test-flakes-2/README.md b/quest/m1/test-flakes-2/README.md new file mode 100644 index 00000000000..c48c60452bf --- /dev/null +++ b/quest/m1/test-flakes-2/README.md @@ -0,0 +1,46 @@ +# More tests hold up under load + +## Goal + +A second round after [#4286](https://github.com/moq-dev/moq/pull/4286): +tests that pass alone but have failed under a loaded `just check` pass +reliably, each fixed at its cause, never by raising a timeout or adding a +retry. + +## Plan + +Decided in the 2026-09-30 audit: the round held independent flakes in one +quest, so it split into one child per flake, grouping only those that share +a fixture. Each child lands on its own. + +Rules every child keeps: + +- Prefer a paused clock over wall time (`moq-cli`'s subscribe tests already + use `#[tokio::test(start_paused = true)]`), or assert on an event instead + of a deadline. If a test is slow under load because the code under test is + slow, fix that. +- A paused clock auto-advances while the runtime idles, so it can fire a + timer before a real socket delivers. Where real sockets fight the paused + clock, make the timers mockable or move the test off real sockets. + +This README's own work, after the children: run `just check --all` several +times on a loaded machine, as the first round did. + +Public API: none. Wire: none. + +## Required + +- [moq-cli tests on a paused clock](/quest/m1/test-flakes-2/cli-paused-clock.md) - the fetch timeout and completion tests stop racing wall-clock budgets +- [Subscription cut by disconnect](/quest/m1/test-flakes-2/subscription-cut.md) - a publisher disconnect never ends a subscription clean +- [Broadcast race](/quest/m1/test-flakes-2/broadcast-race.md) - the QUIC-wins race test binds no shared port and has a deterministic winner +- [Media late join](/quest/m1/test-flakes-2/media-late-join.md) - `just test media` late join stays within one GOP, or the regression is fixed +- [Shaper virtual time](/quest/m1/test-flakes-2/shaper-virtual-time.md) - `moq-shaper` tests judge seeded decisions on paused time, not on wall-clock delivery under load +- [Scoped WARN capture](/quest/m1/test-flakes-2/warn-capture.md) - the drop-unfinished tests count only their own WARNs +- [moq-mux debounce clock](/quest/m1/test-flakes-2/mux-debounce-clock.md) - the TS export debounce test advances on the paused clock +- [js/publish audio clock](/quest/m1/test-flakes-2/publish-audio-clock.md) - the audio encoder delay test runs on mock time +- [WebSocket paused TLS dial](/quest/m1/test-flakes-2/websocket-paused-tls.md) - the fixed-address WebSocket tests stop pausing the clock over a real dial + +## Related + +- [Archive enrollment](/quest/m1/archive/enrollment-flake.md) - the same + kind of flake on the archive line, where its test lives diff --git a/quest/m1/test-flakes-2/broadcast-race.md b/quest/m1/test-flakes-2/broadcast-race.md new file mode 100644 index 00000000000..36b0ddf1850 --- /dev/null +++ b/quest/m1/test-flakes-2/broadcast-race.md @@ -0,0 +1,22 @@ +# [S] Broadcast race without a shared port + +## Goal + +moq-tokio `broadcast_race_quic_wins` binds no port it didn't reserve and +has a deterministic winner. + +## Plan + +It binds TCP `:0` and then UDP on the same number, which nothing reserves: +the collision [#4084](https://github.com/moq-dev/moq/pull/4084) removed from +its sibling after [#4055](https://github.com/moq-dev/moq/pull/4055) papered +over it with a retry. + +The test shares one port only so both transports sit behind one URL. +Separate `:0` ports fix the bind collision but not the race itself: with +`websocket.delay = 0` either arm can legitimately win under load. Make the +order deterministic the way #4084 did, holding the WebSocket arm until QUIC +has connected, rather than asserting on a real race; no retry. #4084's +follow-ups (`tests/reconnect.rs` `spawn_server`, `tests/worker.rs` +`free_udp_port`) are the same probe-and-rebind pattern; fix them here if +cheap. diff --git a/quest/m1/test-flakes-2/cli-paused-clock.md b/quest/m1/test-flakes-2/cli-paused-clock.md new file mode 100644 index 00000000000..f29e8ab11c5 --- /dev/null +++ b/quest/m1/test-flakes-2/cli-paused-clock.md @@ -0,0 +1,30 @@ +# [M] moq-cli tests on a paused clock + +## Goal + +The moq-cli fetch and completion tests pass under any host load: none of +them races a wall-clock budget against connect, TLS, announce, and +subscribe. + +## Plan + +- `fetch::tests::a_frame_read_times_out` asserts on a 500 ms wall deadline + ([#4084](https://github.com/moq-dev/moq/pull/4084)). + `rs/moq-cli/src/fetch.rs` wraps the whole run in one + `timeout_at(deadline, ...)`, so setup shares the budget with the read, and + under load setup alone can spend it. +- `complete::tests::a_stage_broadcast_picks_the_catalog_to_read` + ([#4084](https://github.com/moq-dev/moq/pull/4084)), + `the_catalog_format_on_the_line_is_honored` + ([#4089](https://github.com/moq-dev/moq/pull/4089)), and + `a_relay_on_the_line_answers_broadcast`: the latter pair came back empty + after the fixed 1.5 s `CEILING` on a loaded runner + ([#4404](https://github.com/moq-dev/moq/pull/4404)). + +Test on a paused clock (maintainer decision, 2026-09-28). The fixture runs +real sockets against an in-process relay, where a paused clock fires QUIC +timers while packets are in flight, so first make the timers mockable: run +the fixture over an in-memory transport, or drive noq's timers from the test +clock, whichever is smaller. Keep fetch's one absolute 30 s deadline, +matching the relay's `/fetch`; on a paused clock setup costs no time, so it +can't spend the read's budget. The completion tests reuse the same fixture. diff --git a/quest/m1/test-flakes-2/media-late-join.md b/quest/m1/test-flakes-2/media-late-join.md new file mode 100644 index 00000000000..c795da647c8 --- /dev/null +++ b/quest/m1/test-flakes-2/media-late-join.md @@ -0,0 +1,15 @@ +# [S] Media late join within one GOP + +## Goal + +`just test media` late join holds its one-GOP budget under load, or the +regression behind it is fixed. + +## Plan + +It failed once after [#4181](https://github.com/moq-dev/moq/pull/4181): +"joined at frame 111, 16 frames behind 127", against a budget of one GOP +(15). First decide whether 16 frames is a real regression (the player +joining at the previous GOP's keyframe) or an off-by-one in how the fixture +samples the live edge. Fix whichever it is; don't widen the budget without a +reason. diff --git a/quest/m1/test-flakes-2/mux-debounce-clock.md b/quest/m1/test-flakes-2/mux-debounce-clock.md new file mode 100644 index 00000000000..e29f84934b2 --- /dev/null +++ b/quest/m1/test-flakes-2/mux-debounce-clock.md @@ -0,0 +1,15 @@ +# [XS] moq-mux debounce test on the paused clock + +## Goal + +moq-mux `container::ts::export_test::debounce_opens_without_a_media_clock` +advances on the paused clock and sleeps no real time. + +## Plan + +It died with SIGTERM once in a combined run. It is marked +`start_paused = true` but sleeps 1.2 s of real time, because the debounce +reads `crate::Clock`, which uses `std::time::Instant`, so the paused tokio +clock never reaches it. Let the test drive `crate::Clock`'s time (a tokio +`Instant` under test, or an injected source) so the window passes on the +paused clock, and drop the real sleep. diff --git a/quest/m1/test-flakes-2/publish-audio-clock.md b/quest/m1/test-flakes-2/publish-audio-clock.md new file mode 100644 index 00000000000..ccc4becaadf --- /dev/null +++ b/quest/m1/test-flakes-2/publish-audio-clock.md @@ -0,0 +1,11 @@ +# [XS] js/publish audio delay test on mock time + +## Goal + +The js/publish audio encoder test "a rendition trailing the broadcast's +earliest advertises delay" passes when its file runs alone. + +## Plan + +It reads the real clock, so timestamps go negative early in the process and +it fails when run alone (#4414). Run it on mock time. diff --git a/quest/m1/shaper-virtual-time.md b/quest/m1/test-flakes-2/shaper-virtual-time.md similarity index 100% rename from quest/m1/shaper-virtual-time.md rename to quest/m1/test-flakes-2/shaper-virtual-time.md diff --git a/quest/m1/test-flakes-2/subscription-cut.md b/quest/m1/test-flakes-2/subscription-cut.md new file mode 100644 index 00000000000..8819c67ed95 --- /dev/null +++ b/quest/m1/test-flakes-2/subscription-cut.md @@ -0,0 +1,14 @@ +# [S] Subscription cut by publisher disconnect + +## Goal + +moq-tokio +`subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` +passes in every full-suite run. + +## Plan + +It ends `Ok(None)` with 10 of 20 frames in 3 of 8 full-suite runs on a clean +tree, and passes alone (#4332). A clean end after a publisher disconnect is a +real bug if the code can produce it, not only a test race: reproduce under +load first, find which path reports the cut as a clean end, and fix it there. diff --git a/quest/m1/test-flakes-2/warn-capture.md b/quest/m1/test-flakes-2/warn-capture.md new file mode 100644 index 00000000000..d6f928e0c43 --- /dev/null +++ b/quest/m1/test-flakes-2/warn-capture.md @@ -0,0 +1,14 @@ +# [XS] Scoped WARN capture + +## Goal + +moq-net `model::group::test::drop_unfinished_warns` and the `model::track` +test of the same name count only the WARNs their own code emits. + +## Plan + +Both count WARNs through a global tracing capture, so another test's WARN, +or a missed one, changes the count +([#4104](https://github.com/moq-dev/moq/pull/4104)). Capture per test, with a +scoped subscriber or a filter on the test's own span, instead of a +process-global count. diff --git a/quest/m1/test-flakes-2/websocket-paused-tls.md b/quest/m1/test-flakes-2/websocket-paused-tls.md new file mode 100644 index 00000000000..d92b724882a --- /dev/null +++ b/quest/m1/test-flakes-2/websocket-paused-tls.md @@ -0,0 +1,14 @@ +# [XS] WebSocket fixed-address tests off the paused clock + +## Goal + +moq-tokio websocket `fixed_addresses_keep_tls_name_and_request_host` and +`ipv6_literal_fixed_addresses` no longer pause the clock over a real TLS +dial. + +## Plan + +They pass today, but they pause the clock over a real TLS dial on loopback. +Once a timeout lands on that path, the paused clock can fire it before +loopback delivers, the race [#4527](https://github.com/moq-dev/moq/pull/4527) +removed from the auth outage tests. Remove it the same way. diff --git a/quest/m1/timestamp-rewind-detail.md b/quest/m1/timestamp-rewind-detail.md new file mode 100644 index 00000000000..d10328975d8 --- /dev/null +++ b/quest/m1/timestamp-rewind-detail.md @@ -0,0 +1,29 @@ +# [XS] A timestamp rewind names the frame and the edge + +## Goal + +When `container::Producer::write` refuses a frame below the live edge, the +error says which timestamp it refused and where the edge was, so a report like +#4635 diagnoses itself from the error text alone. + +## Plan + +`container::TimestampRewind` (`rs/moq-mux/src/container/mod.rs`) is a unit +struct, raised at `rs/moq-mux/src/container/producer.rs` when +`frame.timestamp < live_edge`, and also constructed on the consumer side +(`rs/moq-mux/src/container/consumer.rs`); give those the same detail. Give it `timestamp` and `edge` fields and put +both, in microseconds, in its message, for example "frame timestamp 1790802494898431 +µs is below the live edge 1790802494898432 µs". moq-ffi surfaces the message +unchanged. + +#4635 could not be reproduced: FLAC and AAC share this path, and strictly +increasing timestamps with a cut per frame pass. A cut per frame makes every +frame a group start, so it refuses any backward step, while a dip inside an +open group is tolerated. Test: a FLAC `import::Track` with `cut(None)` per +frame and one frame 1 µs back reports both values. + +Public API: a unit struct gains fields, so breaking, on `dev`. Wire: none. + +## Related + +- [#4635](https://github.com/moq-dev/moq/issues/4635) - the report this makes diagnosable; it stays open until the reporter's sequence is known diff --git a/quest/m1/tooling/README.md b/quest/m1/tooling/README.md deleted file mode 100644 index 5f3055bfc07..00000000000 --- a/quest/m1/tooling/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Tooling: thin justfiles and CI that calls them - -## Goal - -A month of merges left the command surface bloated: 873 lines of root -`justfile`, seven self-tests of the tooling itself on every pull request, -three metadata guards, recipes nothing calls, and release workflows that are -the same file with a binary name swapped. The result is a `just` tree that is -a menu, not a language: every recipe is one line, every script lives under -`sh/`, the diff is resolved once by one impact map, and every workflow step -runs a recipe rather than a script path. - -## Plan - -`just` stays as the entry point because the vocabulary (`just check`, `just -fix`) is in every doc, skill, and workflow. Its cost was -self-inflicted: logic inside recipes. The quests below are ordered and each -requires the one before it, so they land as one line of pull requests. - -## Required - -- [Thin justfiles](/quest/m1/tooling/justfiles.md) - recipe bodies move to `sh/`, one impact map scopes check/fix/test, self-tests and guards are deleted -- [Workflows call just](/quest/m1/tooling/workflows-call-just.md) - no workflow `run:` step names a `.sh`; every script a workflow needs has a recipe -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - moq-cli and moq-relay share one reusable workflow behind two thin callers -- [FFI release workflow](/quest/m1/tooling/release-ffi.md) - the five `release-*-ffi.yml` share the moq-ffi target matrix and artifact staging diff --git a/quest/m1/tooling/justfiles.md b/quest/m1/tooling/justfiles.md deleted file mode 100644 index 429dedb4325..00000000000 --- a/quest/m1/tooling/justfiles.md +++ /dev/null @@ -1,102 +0,0 @@ -# [L] Thin justfiles with one impact map - -## Goal - -Every justfile is a menu: each recipe is a single line that runs a tool or a -script under `sh/`, `just --list` shows each recipe once, and no recipe body -is bash. The scoped `check`, `fix`, and `test` resolve the branch diff once, -in one impact map, instead of a scope regex per language justfile plus a -mirror of them in the strict-tools preflight. Nothing that tests the tooling -itself runs on a pull request. A recipe that no workflow, doc, skill, or other -recipe invokes is gone, except the hand-run demo and infra ops recipes, which -stay as they are. - -## Plan - -Layout: - -- New root `sh/`. Root helpers sit at the top (`sh/dispatch.sh`, - `sh/markdown.sh`, `sh/shell.sh`, `sh/clean.sh`); per-area tooling moves - under `sh//`: `rs/scripts` to `sh/rs`, `.github/scripts` to `sh/gh`, - `go/scripts` to `sh/go`, `kt/scripts` to `sh/kt`, `swift/scripts` to - `sh/swift`, `dart/scripts` to `sh/dart`, and the OBS recipe bodies to - `sh/obs`. Workflow references to moved paths are updated mechanically here; - the next quest replaces them with recipes. -- Package build scripts that nix, CMake, gradle, and the dart build hook - point at stay put: `rs/*/build.sh`, `rs/moq-gst/{package,scrub,smoke}.sh`, - `cpp/obs/build.sh`, `infra/*/publish.sh`. The harness under `test/` is - harness code, not tooling; it stays too. -- `shfmt -f .` already enumerates `sh/`, so the shell lint covers everything - the justfiles stop containing. - -Dispatch: - -- `just check [BASE]`, `just fix [BASE]`, and `just ci check|test [BASE]` are - one line each: `sh/dispatch.sh check|fix|ci-check|ci-test "$BASE"`. The script resolves BASE - (arg, `GITHUB_BASE_REF`, upstream, `origin/main`), lists changed files into - a temp file, and applies one impact map: which language modules run, which - tools `MOQ_STRICT` demands, and whether the root orchestration changed and - everything runs. The map lives in one place; the `scope` variables in the - js, py, kt, swift, go, and dart justfiles and the regex table in `_tools` - are deleted with it. -- Per-language `check`, `fix`, and `test` lose their `$FILES` parameter and - skip logic. Only rs still receives the list: `just rs check-changed - ` (and `fix-changed`, `test-changed`) hand the path to - `sh/rs/select.sh`, which does the crate selection today spread over - `_select`, `_names`, and `_wants-wasm`. -- Passing a path instead of the list kills the argv budget: - `changed_max`, `_changed-cap`, `_changed-test`, `_echo`, and the E2BIG - commentary go. -- `check --all`, `fix --all`, and `ci check|test --all` keep their names; cache.yml, - nightly.yml, and the docs call them. - -Delete: - -- Self-tests: `_changed-test`, `_markdown-test`, `_select-test`, - `_doc-names-test`, `_publish-test`, `sh/rs/package-nfpm.test.sh`, - `sh/gh/package-binary.test.sh`. -- Guards: `_doc-names` and `doc-names.jq`, and the publish lower-bound - check. This is a deliberate trade: the guards were incidents' worth of - bash plus their self-tests on every pull request. Where each surfaces - instead: a doc-directory collision shows up as an intermittent `failed to - remove directory` in the `cargo doc` step of whichever pull request selects - both crates, not deterministically (resolve with `doc = false` as before); - a stale internal lower bound fails release-plz's publish. `_fuzz-lock` is - already gone: #3543 folded the fuzz harness into the workspace so the root - lockfile and `--locked` cover it. `alert.sh check-coverage` stays: it is a - lint of alert.yml, not of a recipe. -- The `worktree` recipe and its 170 lines, plus the Worktrees section of - `test/README.md`; keep `_base` folded into `sh/dispatch.sh`. -- `rs bump` and `rs semver`. `rs release` stays for release-rs.yml. -- The `mod` lines in `demo/justfile`: `just pub`, `just relay`, `just boy`, - `just sub`, `just web` are the only spelling, and `--list` stops showing - each twice. `just demo` remains the default recipe and `just dev` its - documented alias. - -Rename: - -- Root `wasm` becomes `js wasm`: it emits `js/wasm/dist`, so it is a JS - package build. `rs wasm` stays the compile gate and `test wasm` the browser - run. Update wasm.yml, root `build`, `test/wasm/run.sh` (which runs `just - wasm` to build the package under test), and the four doc references. - -Keep, moved into scripts unchanged in behavior: the remark mirror-and-diff in -`sh/markdown.sh` (remark-cli has no check mode and the lint presets are -wanted), `_shell`, `_flake` as its one-liner, `clean`, the rs `package` and -`fuzz` bodies, and the OBS `compile`, `_includes`, `_unit`, `test`, `check`, -and `preset` bodies. - -Arguments reach tools intact: `just rs test`, `check-test`, and -`capture-test` interpolate `{{ args }}` today, so a quoted nextest filterset -becomes a shell syntax error (#4342). Recipes that forward arguments use -`[positional-arguments]` and `"$@"`. No self-test for it, per the rule above. - -Docs: `doc/setup/dev.md`, `CONTRIBUTING.md`, `test/README.md`, and the -`AGENTS.md` mentions of `just wasm` follow the survivors. Verify with `just -check`, `just ci test`, and `just check --all`, and confirm every recipe name -check.yml, cache.yml, nightly.yml, interop.yml, wasm.yml, obs.yml, swift.yml, -and release-*.yml invoke still resolves. - -## Closes - -- [#4342](https://github.com/moq-dev/moq/issues/4342) - close this issue when the quest finishes diff --git a/quest/m1/tooling/release-binary.md b/quest/m1/tooling/release-binary.md deleted file mode 100644 index 95eecf91f16..00000000000 --- a/quest/m1/tooling/release-binary.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] One reusable workflow for the binary releases - -## Goal - -`moq-cli.yml` and `moq-relay.yml` are two copies of the same workflow (226 -and 225 lines) with the binary name swapped. They become one reusable -`release-binary.yml` taking `crate` and `bin` inputs, and two callers of a -dozen lines each that keep their tag trigger -and workflow name, so `alert.yml`, `release-brew.yml`, and -`release-winget.yml` keep matching on the names they match today. - -## Plan - -- `release-binary.yml` on `workflow_call` with inputs `crate` (the cargo - package) and `bin` (the executable name; `moq-cli` ships `moq`). It holds the Linux native-runner matrix, - the macOS tarball job, the Windows job, the `.deb` and `.rpm` packaging, the - release creation, and the repo-publish trigger, all as `just` recipes per - the preceding quest. -- Each caller keeps `name:` and `on.push.tags` exactly as they are and does - nothing but `uses: ./.github/workflows/release-binary.yml` with the two - inputs and the secrets it forwards. `workflow_run` consumers trigger off - the caller's name, so nothing downstream changes. -- The one text difference between the three today (a comment and a step name - about the glibc floor) belongs in the reusable file. -- Verify with `just gh check` and by diffing the rendered job list of each - caller against its predecessor with `gh workflow view`. The next tagged - release is the end-to-end check; say so in the PR. - -## Required - -- [Workflows call just](/quest/m1/tooling/workflows-call-just.md) - the reusable workflow is written in the recipe style from the start diff --git a/quest/m1/tooling/release-ffi.md b/quest/m1/tooling/release-ffi.md deleted file mode 100644 index 1627f981c8a..00000000000 --- a/quest/m1/tooling/release-ffi.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] One reusable workflow for the moq-ffi releases - -## Goal - -`release-dart-ffi.yml`, `release-go-ffi.yml`, `release-kt-ffi.yml`, -`release-swift-ffi.yml`, and `release-py-ffi.yml` share half to two thirds of -their lines: the moq-ffi cross-target build matrix and the artifact staging. -That shared half becomes one reusable `release-ffi.yml`; each language keeps -only its packaging and publish steps. - -## Plan - -- Measure the shared lines first (`comm` over the sorted files shows 74 to - 176 common lines per pair) and confirm the matrix targets agree. Where a - language needs a different target set (iOS simulator for swift, Android - ABIs for kt and dart), make the target list an input rather than forcing - one matrix. -- `release-ffi.yml` on `workflow_call`: builds `rs/moq-ffi` for the requested - targets, uploads one artifact per target, and outputs the version parsed - from the tag. Callers download the artifacts and run their `just - package` and publish recipes. -- `release-dart-ffi.yml` and `release-go-ffi.yml` also run on `pull_request`, - where `GITHUB_REF` is not a `moq-ffi-v*` tag and `parse-version` fails; they - read the version from `rs/moq-ffi/Cargo.toml` instead. The reusable - workflow keeps that fallback (an input or a ref check), or those PR runs die - before building. -- Callers keep their `name:` and triggers, as the binary quest did, so - `alert.yml` and the `workflow_run` chains (`release-go.yml`, - `release-py.yml`, `release-swift-lib.yml`) are untouched. -- Verify with `just gh check`; the next tagged `moq-ffi-v*` release is the - end-to-end check. - -## Required - -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - proves the reusable-plus-callers pattern before it is applied to five files diff --git a/quest/m1/tooling/workflows-call-just.md b/quest/m1/tooling/workflows-call-just.md deleted file mode 100644 index 4d6c79c4e8e..00000000000 --- a/quest/m1/tooling/workflows-call-just.md +++ /dev/null @@ -1,45 +0,0 @@ -# [M] Every workflow step runs a recipe - -## Goal - -No `run:` line in `.github/workflows` names a `.sh` file. Every script a -workflow needs has a `just` recipe, so the menu is the whole command surface -and a script can move or change its arguments without touching twenty -workflows. The same recipes work locally for a dry run. - -## Plan - -Today the workflows call scripts directly at roughly ninety sites: -`sh/gh/release.sh` (54 calls as a helper library: `parse-version`, -`prev-tag`, `create`, registry existence checks), `sh/rs/package-nfpm.sh`, -`sh/rs/package-binary.sh`, `sh/rs/package-windows.sh`, -`sh/gh/trigger-repo-publish.sh`, `sh/gh/render-formula.sh`, `sh/gh/alert.sh`, -the swift `package`, `package-ffi`, `publish`, `publish-ffi`, `verify`, -`verify-ffi`, and `check` scripts, the go `package-ffi`, `package-wrapper`, -`publish-ffi`, `publish-wrapper` scripts, `sh/dart/package.sh`, -`sh/kt/package.sh`, and `infra/*/publish.sh`. - -- Add pass-through recipes where none exist, named by role under the area - module: `just gh release ...`, `just gh alert ...`, - `just gh formula ...`, `just gh trigger-repo-publish ...`, - `just rs package-binary ...`, `just rs package-nfpm ...`, - `just rs package-windows ...`, `just swift publish|verify|package-ffi|...`, - `just go publish-ffi|publish-wrapper`, `just dart package`, - `just infra apt publish` and `just infra rpm publish` (the recipes exist). - Existing wrappers (`kt package`, `swift package`, `go package-ffi`, - `go package-wrapper`, `py package`) are used as they are. -- Rewrite every `run:` step to the recipe. Where a workflow runs outside the - nix dev shell (Windows and macOS runners, AlmaLinux containers), `just` is - already installed or installable the way nightly.yml does it; keep that - pattern rather than falling back to a path. -- Record the rule in the CI section of `CONTRIBUTING.md` in one line, and - have `just gh check` enforce it: fail on any workflow `run:` line matching - `\.sh\b`. -- Verify with `actionlint` via `just gh check`, and with a manual - `workflow_dispatch` of apt-repo.yml, rpm-repo.yml, and release-winget.yml - where the inputs allow a dry run. The tag-triggered release workflows are - verified by the next release; say so in the PR. - -## Required - -- [Thin justfiles](/quest/m1/tooling/justfiles.md) - establishes `sh/` and the module recipes the workflows will call diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index ff15c46b39c..171f37a2993 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -57,6 +57,11 @@ Direction to settle in the draft first, then the code: or narrow the goal to subscription delivery. - Keep the current ranking: track priority, then subscription, then newest group; do not reintroduce a group-order direction knob. +- Decide whether the publisher's `track::Info::priority` breaks a tie + between equal subscriber priorities in `Priority::cmp` + (`rs/moq-net/src/lite/priority.rs:48`). The + [ladder controller](/quest/m2/ladder/controller.md), now in m2, wants that + tiebreak; this quest owns the answer so the controller only consumes it. - A per-session cap on distinct ranks is a scheduling detail; whatever replaces the 255-entry sort must stay O(log n) per group under chat-shaped churn. @@ -77,3 +82,5 @@ change. - [Starvation](/quest/m1/qos/starvation.md) - the relay-side signal that shows a starved subscription +- [Signed priority](/quest/m2/signed-priority.md) - changes the priority type, + not which streams it competes with diff --git a/quest/m1/track-tail-hardening.md b/quest/m1/track-tail-hardening.md deleted file mode 100644 index 74d412bd042..00000000000 --- a/quest/m1/track-tail-hardening.md +++ /dev/null @@ -1,79 +0,0 @@ -# [M] Track tail hardening - -## Goal - -moq-net and `@moq/net` wait out a subscription's tail by the same rules, and -the known holes in those rules are closed. A finished IETF subscription never -hangs its request task or under-reports its stream count, a group whose -header arrived is never silently dropped from a clean end, the grace never -cuts off a stream still being read, and tail bookkeeping stays bounded on a -lossy track. - -## Plan - -Track tail landed in https://github.com/moq-dev/moq/pull/4086 (JS) and -https://github.com/moq-dev/moq/pull/4116 (Rust), and Codex's findings on both -were left for this pass. Fix each in the language named and check whether -the other has the same hole. - -Bugs: - -- **Rust IETF publisher, END_OF_TRACK not cancellable.** After the group - streams drain, `write_end_of_track` in `rs/moq-net/src/ietf/publisher.rs` - runs outside the race against `stream.reader.poll_closed` and the session, - so with uni-stream credit exhausted an unsubscribe leaves the request task - parked forever, never sending PUBLISH_DONE. -- **Rust IETF publisher, stream count.** END_OF_TRACK is counted only if the - whole write succeeds, while every other stream counts once opened. A reset - END_OF_TRACK whose header still arrives can then land after the subscriber - met the count and retired the alias. -- **Rust IETF subscriber, truncated first object.** `open_group` peeks the - first object with `?` before creating the group, so a stream reset or - truncated after its header drops that group, and since the stream still - counts, the track can end clean without it. Keep the END_OF_TRACK peek, but - create and abort the named group on any other peek failure. -- **Rust grace cuts off an arrived stream.** `Settle::poll` in - `rs/moq-net/src/tail.rs` returns when the grace fires even if an - END_OF_TRACK stream is mid-read, so the track finishes at the live edge and - the later marker is ignored. JS's `Tail.settle` already waits for active - streams; do the same. -- **JS lite floor.** `Math.max(entry.start, bounds.start)` in - `js/net/src/lite/subscriber.ts` ignores a SUBSCRIBE_UPDATE that lowered the - floor after SUBSCRIBE_START, so a newly requested lower group reordered - behind the FIN is dropped. `bounds.start` alone is wrong too: a subscriber - that asked below the announced start would wait for groups never promised. - The owed start has to remember the floor each request was answered at. - Check whether Rust's `SubStream::owed` has the same shape. - -Open questions. The maintainer chose to plan these without settling them; -decide in the PR, applying the choice to both languages: - -- **Are lost datagrams owed before a track ends?** Both `Tail`s account a - datagram only when it arrives, so a lost one leaves a hole in the owed span - and the end waits out the whole grace (JS was reported to wait and Rust - not, but Rust's `covers(owed)` reads the same way despite the comment in - `route_datagram`; confirm with a test first). Recommendation: no, datagrams - are best effort. [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) decided - the same: datagram groups are not owed, so an uncovered hole waits out the - grace on every version. -- **Does a group at or past the declared end abort the track, or only that - group?** Rust aborts the track with `ProtocolViolation`; JS aborts the group - and ends clean. Recommendation: abort the track in both. The peer - contradicted its own end, and the repo fails loud on malformed input. -- **How is tail memory bounded?** Rust `Tail.accounted` gains a range per - permanent gap for the life of the subscription, and so does JS's. A gap - older than the grace can no longer be waited for, so folding it in as - accounted loses nothing. Recommendation: that, which bounds the ranges by - the gaps inside the grace window. Once publishers send SUBSCRIBE_DROP for - every gap, only datagram holes remain. - -Regression tests go in `rs/moq-net/tests/track_tail.rs` (its `hold_unis` -mock makes the reorder deterministic) and the JS tail tests. Wire output only -changes if the stream-count fix does, and that is a correction to what the -drafts already require. - -## Related - -- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS check that both sides now agree -- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every group is a stream or a drop, replacing lite-07's stream count -- [Session death](/quest/m1/session-death.md) - how a tail ends when the session dies under it diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index 01b0a683388..9450e353d04 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -19,30 +19,23 @@ What stood in the way when the Rust half landed: - `moq import` exits the moment stdin ends, closing its session with the tail still in flight, so a finite CLI publisher cannot end a track cleanly. The fix is a publisher that waits for its subscriptions to drain before it - closes; `moq export`'s linger ([Export linger](/quest/m1/export-linger.md)) is - the reader-side cousin. + closes; `moq export ts --linger` is the reader-side cousin. - The native JS subscriber (`test/interop/clients/js-native`) returns on the first frame. It needs a mode that reads a track to its end and reports how it ended and which groups it saw. -Also cover the drop case: +The harness exposed a relay start-floor defect: when a newer group arrives +first, earlier in-flight groups can be lost. #4387 fixed it (merged 09-28). -- On moq-lite-07 add a drop case: both subscribers settle on SUBSCRIBE_DROP, - so a group the publisher skipped or never opened ends the track without - waiting out the grace. lite-07 replaces the SUBSCRIBE_END stream count - (#4224) with it. -- The harness exposed a relay start-floor defect: when a newer group arrives - first, earlier in-flight groups can be lost. #4387 fixes it, so the drop - proof waits on it. +Decided in the 2026-09-30 audit: the lite-07 drop case moved into +[SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md)'s tests, so the basic Rust and +JS tail interop lands now instead of waiting on that [L] quest. QUIC on localhost rarely reorders, so this is a smoke check that the end is delivered and clean. The ordering race itself stays in the unit tests. -## Required - -- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver, which the lite-07 case checks -- #4387 merges: a relayed subscription resolves its start from its source, so earlier in-flight groups are not lost (it adds quest/m1/relay-late-joiner-history.md) - ## Related +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - owns the lite-07 drop case on top of this harness - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - keeps a reset stream's header, so the reset acts as a one-group drop +- [Close waits for the tail](/quest/m1/close-tail.md) - the publisher-side fix this test proves across a real relay diff --git a/quest/m1/transport-upgrade/README.md b/quest/m1/transport-upgrade/README.md index 094817c6e0e..25a197bed54 100644 --- a/quest/m1/transport-upgrade/README.md +++ b/quest/m1/transport-upgrade/README.md @@ -45,7 +45,7 @@ Shared decisions: `moq-tokio`, `websocketWon` in `js/net`) forgets the URL: QUIC works on this network, so the head start comes back. Otherwise a network where WebSocket narrowly beats QUIC would open two connections on every reconnect. -- The old session gets `Goaway::same()` with the configured handover cap before +- The old session gets `Goaway::new()` with the configured handover cap before it enters draining. The relay refuses new requests on it from then on; the splice ends its subscriptions at the boundary. - One-shot `connect()` returns one session and never upgrades; every diff --git a/quest/m1/ts-aac-pce-join.md b/quest/m1/ts-aac-pce-join.md new file mode 100644 index 00000000000..e31f2e1ff99 --- /dev/null +++ b/quest/m1/ts-aac-pce-join.md @@ -0,0 +1,31 @@ +# [S] TS AAC program config survives joins and resumes + +## Goal + +AAC whose layout lives in a program config element (ADTS `channel_config` 0) +plays over MPEG-TS for a receiver that joins mid-stream or after a resume. A +missing PCE silences that one track instead of failing the whole program. + +## Plan + +Found in review of the audio-codecs line (#4081), 2026-09-30. + +- Import: `aac::in_band_config` returns `ProgramConfigMissing` when the first + frame seen has no leading PCE, and `?` ends the whole TS import, video + included (`rs/moq-mux/src/container/ts/import.rs`). Instead, keep the + reservation, drop frames on that track until one leads with a PCE, and log + once. ffmpeg's ADTS muxer writes the PCE only in the first frame, so a late + join of an ffmpeg source stays silent; say so in the docs. +- Export: `mux` takes the PCE on the first frame only + (`rs/moq-mux/src/container/ts/export.rs`), so `resume()`/`rewind()` and any + mid-stream receiver never see it. Repeat it, either on every frame or with + each PAT/PMT, and pick whichever ffmpeg and the import side accept. +- Regression: an export resumed before its first span re-emits the PCE, and an + import that starts on a PCE-less frame publishes the track once a PCE + arrives, while the other tracks keep flowing. + +Public API: none. Wire: none; TS output gains repeated PCEs. + +## Related + +- [TS Opus channel codes](/quest/m1/ts-opus-channel-codes.md) - the same per-track refusal principle for Opus descriptors diff --git a/quest/m1/ts-damaged-units.md b/quest/m1/ts-damaged-units.md new file mode 100644 index 00000000000..8de2efbd990 --- /dev/null +++ b/quest/m1/ts-damaged-units.md @@ -0,0 +1,60 @@ +# [M] TS import drops a damaged unit instead of ending the ingest + +## Goal + +`moq import ts`, and `moq-srt` through the same importer, survive a packet, +PES, or access unit they cannot parse: a malformed PES header or media-PID +adaptation field with `transport_error_indicator` clear, or a codec error such +as an H.264 NAL with `forbidden_zero_bit` set. The damaged unit is dropped and +counted, its track waits for its next keyframe, and the ingest carries on. +Today the first such error ends the import, and the gateway hangs up. + +## Plan + +Today `decode` in `rs/moq-mux/src/container/ts/import.rs` runs +`while let Some(packet) = self.reader.read_ts_packet()? { self.handle_packet(packet)?; }`, +so any PES-header error from the reader and any codec error from `flush` ends +the import. The `transport_error_indicator` branch already drops a flagged +packet (clears `pending[pid]` and calls `stream.desync()`), and it is the model. + +Decided (maintainer, 2026-09-30): + +- Fail-loud holds at unit granularity, as [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) + holds it at section granularity: a damaged unit is refused whole, never half + published, and counted, and nothing else about the feed changes. PSI damage + stays that quest's. +- Drop the unit the way the TEI branch does: clear the PID's pending PES and + desync its stream, so a codec that needs one waits for the next keyframe. + Make sure the scratch buffer still advances past the packet on this path + (today an error skips `self.scratch.drain(..off)`). +- Count each drop in a new cumulative per-PID `damaged` counter on the stream's + stats row, beside `resyncs` and `discarded`, reported by `ts::stats::Log`. + It names what happened; no TR 101 290 check matches a codec error, and + [TS import health](/quest/m2/ts-import-health.md) keeps the ETSI names. + The rows are `#[non_exhaustive]`, so the field is additive; follow + [TS stats module](/quest/m1/ts-stats-module.md)'s names if it has landed. +- Errors that are not confined to one unit (the producer refusing a rewind, + origin or catalog failures) stay fatal. +- Built on the demux TS PSI reassembly owns, since that quest moves PES header + parsing into moq-mux. + +Tests, from [#4581](https://github.com/moq-dev/moq/issues/4581)'s stimuli on a +fixture: a video PES header with its flag and timestamp bytes zeroed (TEI +clear), and one H.264 NAL with `forbidden_zero_bit` set. Each import carries +on, counts exactly one `damaged` on that PID and none elsewhere, and publishes +again from the next keyframe; a clean fixture counts zero. Document the counter +wherever the TS stats fields are described. + +Public API: additive, one stats field. Wire: none. + +## Required + +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - moq-mux owns the demux and PES header parsing this drops through + +## Closes + +- [#4581](https://github.com/moq-dev/moq/issues/4581) - one malformed packet ends the TS import + +## Related + +- [TS import health](/quest/m2/ts-import-health.md) - the TR 101 290 counters for the same feed diff --git a/quest/m1/ts-export-jitter.md b/quest/m1/ts-export-jitter.md deleted file mode 100644 index 5e0b138748d..00000000000 --- a/quest/m1/ts-export-jitter.md +++ /dev/null @@ -1,57 +0,0 @@ -# [S] moq export ts: video reorder bound follows the stream - -## Goal - -Two `moq export ts` legs of one broadcast interleave video and audio -identically even when a B-frame arrives late. Today the media-time interleave -from [#4001](https://github.com/moq-dev/moq/pull/4001) treats a video track as -advanced past a candidate once its high-water mark, less its DTS reserve, -passes it. Without catalog `jitter` that reserve is the 16-tick -`DEFAULT_DTS_RESERVE`, so a B-frame presenting below the mark can still land -after audio it should precede, and the order depends on arrival again. A -`jitter` that shows up in a later catalog is ignored too: `update_catalog` -returns early once the PAT/PMT is built, before the per-track refresh. - -## Plan - -Decided: - -- Keep refreshing a video track's reserve from catalog `jitter` after the PMT - is emitted. The early return exists to lock the track layout, not the - per-track timing, and the importer often fills `jitter` only once it has - seen reordering. -- When `jitter` is absent, derive the reserve from the stream rather than - refuse it. The bitstream's reorder depth (H.264 VUI - `max_num_reorder_frames`, HEVC `sps_max_num_reorder_pics`) counts - pictures, not time, so it becomes a deterministic 90 kHz bound only with - fixed timing: the VUI `fixed_frame_rate_flag` with its tick, or the - catalog framerate. With both, the reserve is depth times frame duration, - known from the first keyframe before any frame is emitted. AV1 and VP9 - present in decode order and need no reserve. Otherwise (variable frame - rate, or nothing declared), grow the reserve from the reordering actually - observed (how far a frame's PTS falls below the track's high-water mark); - it only grows, so a stream that never reorders keeps today's tiny reserve. -- Refusing to export video without `jitter` was rejected as too extreme. -- Treating unknown jitter as unbounded was tried in #4001 and rejected: the - stall never clears when video leads, breaking - `quiet_track_is_emitted_around_then_rejoins`. - -Guidance: - -- The same reserve feeds `author_dts`, so growing it mid-stream shifts DTS - further behind PTS. The existing monotonic clamp keeps DTS from stepping - back; check the PCR, which backs off by the largest reserve, stays ahead of - every DTS written. -- Only the observed fallback is nondeterministic: a B-frame deeper than any - seen before can reorder output once per new maximum (Codex on #4307). - Refusing such streams was ruled out by the maintainer. Say - so in a comment and log each growth, so an undeclared stream is visible - rather than silently misordered. -- Tests in `export_test.rs`: two exporters with a late B-frame, no `jitter`, - and a declared reorder depth at a fixed frame rate produce byte-identical - output from the first frame; an undeclared stream converges after its deepest reorder; and a - `jitter` arriving in a catalog after the PMT raises the reserve. - -## Related - -- [TS export byte schedule](/quest/m1/ts-export-byte-schedule.md) - also reshapes PCR placement in `export.rs` diff --git a/quest/m1/ts-opus-channel-codes.md b/quest/m1/ts-opus-channel-codes.md new file mode 100644 index 00000000000..221cc675592 --- /dev/null +++ b/quest/m1/ts-opus-channel-codes.md @@ -0,0 +1,27 @@ +# [S] TS Opus import refuses or parses extended channel codes + +## Goal + +An MPEG-TS Opus stream whose extension descriptor carries a +`channel_config_code` of 0x81 or above imports with its real OpusHead or is +refused. It never decodes as a guessed stereo stream, which misreads every +multistream packet. + +## Plan + +- The importer falls back to stereo for codes it does not know. 0x81 is + specified as an explicitly coded layout (channel count, mapping family, stream + counts, and table in the descriptor), and ffmpeg's muxer also writes + `0x80 | channels` for an alternate table its own demuxer does not read. Check + the Opus-in-TS spec and ffmpeg before deciding which codes to parse. +- Build parsed layouts with the public `opus::Mapping::new`, which validates + the table; refuse any code that is reserved or does not parse, per stream, + without failing the rest of the program. +- Fixtures from a real muxer where one exists; a hand-built descriptor + otherwise, noted as such. + +Public API: none. Wire: none. + +## Related + +- [TS Opus export refusals](/quest/m1/ts-opus-export-refusals.md) - the exporter side of the same descriptor diff --git a/quest/m1/ts-opus-export-refusals.md b/quest/m1/ts-opus-export-refusals.md new file mode 100644 index 00000000000..b376124fbf3 --- /dev/null +++ b/quest/m1/ts-opus-export-refusals.md @@ -0,0 +1,23 @@ +# [S] TS Opus export refuses what it cannot label + +## Goal + +`moq-mux`'s MPEG-TS exporter never labels an Opus track with a channel +configuration its packets do not have. A track whose OpusHead the Opus +extension descriptor can describe exports as today; anything else is refused, +not written with a guessed `channel_config_code`. + +## Plan + +- The exporter derives `channel_config_code` from the catalog channel count + alone, clamped to 1..=8, so a family 255 or ambisonics head, a family 1 head + with a non-Vorbis table, or more than eight channels exports mislabeled. + Decide from the parsed description: family 0, and family 1 with the Vorbis + default mapping, keep the plain code; refuse the rest, or write the explicit + layout if the import side of + [TS Opus channel codes](/quest/m1/ts-opus-channel-codes.md) settles + one both sides agree on. +- A track with no description stays mono or stereo only. +- Tests with real heads, checked against ffprobe where ffmpeg reads the result. + +Public API: none. Wire: none; TS output changes only for inputs it mislabeled. diff --git a/quest/m1/ts-programs.md b/quest/m1/ts-programs.md deleted file mode 100644 index 2baad24005d..00000000000 --- a/quest/m1/ts-programs.md +++ /dev/null @@ -1,33 +0,0 @@ -# [L] moq import ts: select programs - -## Goal - -A multi-program transport stream is never silently merged. Today `import ts` -keeps the first program's identity, adds every PMT's streams to one broadcast -on one clock, and loses content; `export ts` rebuilds one program. After -this quest `import ts` refuses a multi-program input by default, naming the -programs, and `--program` chooses what to import. - -## Plan - -Decided: - -- Default: error before publishing when the initial PAT lists more than one - non-zero program, naming each program and pointing at `--program`. A later - PAT that adds a program ends the import with the same error; media already - published stays. -- `--program ` imports program `n` only. -- `--program all` publishes one broadcast per program, each with its own clock - and catalog. The catalog suffix stays last so discovery and format detection - still see it: `--broadcast event.hang` publishes `event/1.hang` and - `event/2.hang`. -- `export ts` stays one program per broadcast. - -Tests: a synthetic two-program input with far-apart clocks fails naming both -programs; `--program 2` publishes only program 2's streams on program 2's -clock; `--program all` publishes both broadcasts, each timed correctly. Update -`doc/bin/cli.md` and the `--help` text. - -## Closes - -- [#4353](https://github.com/moq-dev/moq/issues/4353) - close this issue when the quest finishes diff --git a/quest/m1/ts-psi-reassembly.md b/quest/m1/ts-psi-reassembly.md new file mode 100644 index 00000000000..d5fa4556ed3 --- /dev/null +++ b/quest/m1/ts-psi-reassembly.md @@ -0,0 +1,69 @@ +# [L] TS PSI reassembly + +## Goal + +The MPEG-TS importer reads a PAT or PMT whose section spans several packets or +starts after a nonzero `pointer_field`, instead of aborting the import. Today +the `mpeg2ts` 0.6.1 reader parses PSI from a single packet and rejects a nonzero +`pointer_field`, and its error ends the whole import, so a valid long PMT (many +audio languages, long descriptors) or a PAT with more than about 40 programs +cannot be imported. `ts::Programs` finds such a PAT too. + +## Plan + +Settled decisions: + +- moq-mux owns the packet demux, and the import stops using + `mpeg2ts::ts::TsPacketReader`. It can't be fixed from outside: the reader's + PAT and PMT parsers are private to the crate, and it learns PES PIDs only + from PMTs it parsed itself. Feeding it a synthesized one-packet PMT to + register PIDs was rejected as fragile coupling, and fixing it upstream in + sile/mpeg2ts was rejected as slower and outside this repository. Switching to + `mpeg2ts-reader` was rejected too: it is a callback-driven demux framework + (last release January 2025), and moq-mux already owns the hard part in + `SectionReassembler`. Owning the demux also deletes the importer's + workarounds for the reader: the `Feed` mutex it reads through, and the + `pmt_pids`/`streams` gate that keeps unknown PIDs away from it. `mpeg2ts` + stays for export, tests, and plain types such as `StreamType`. +- PID 0 and every PMT PID go through the existing `SectionReassembler`, which + already handles `pointer_field`, split headers, and continuity gaps. The + PAT (`transport_stream_id`, version, program loop, possibly several sections) + and the PMT (program number, PCR PID, program descriptors, and the + elementary-stream loop with descriptors) are parsed in moq-mux. PES is + routed by the PIDs of the parsed PMT, and its header (PTS/DTS) is also parsed + in moq-mux. +- Each reassembled section's CRC-32/MPEG-2 is checked with the `crc` crate. + [Per-program SI](/quest/m2/ts-program-si.md) needs the same dependency, and + whichever change lands first adds it. A section with a bad CRC is dropped and + the last good table stays in force, so the import continues; it no longer + aborts as the `mpeg2ts` reader does. The section is refused whole, never + half-applied, so fail-loud holds at section granularity. A malformed + adaptation field on the PAT or a PMT PID, which ends the import today too, + costs that section the same way. A feed that never delivers a good PAT and + PMT still publishes nothing. Line noise on a live feed then costs one + repetition (0.5 s at most), not the broadcast; today one flipped CRC byte on + `bbb.ts` makes `decode` return `CRC32 mismatch` and `moq import ts` exit. +- Each section dropped for a CRC mismatch is counted in `Import::stats` as a + cumulative `crc_error`, so a corrupt feed is visible rather than silently + held on a stale table. It is stream-wide on `Stats`, since the PAT and PMT + PIDs have no elementary-stream row, and named for the TR 101 290 check that + [TS import health](/quest/m2/ts-import-health.md) adopts. A section dropped + for another reason (a malformed adaptation field, a parse failure) is not a + `crc_error`; that quest counts it under `PAT_error` or `PMT_error`. `Stats` + is `#[non_exhaustive]`, so the new field is additive; its docs (today per + elementary stream) and `is_empty` widen to cover it, and `ts::stats::Log` + reports it. +- `ts::Programs` reads through the same PAT path, so a PAT spanning packets + is found before any program publishes. +- One quest, because the demux refactor alone changes nothing observable. + +Keep every existing TS import test and fixture passing unchanged. Add tests for +a PMT spanning two packets, a PAT behind a nonzero `pointer_field`, a +multi-packet PAT with enough programs to need it (read by `ts::Programs` and +by `with_program`), and a PAT and a PMT with a corrupt CRC, each between good +repetitions, that is dropped and counted once while the import keeps its +previous layout and a later good PMT revision still applies. A positive +control: a feed whose only PAT is corrupt publishes nothing and counts it. + +Folded in from `ts-import-psi-crc` while landing the TR 101 290 plan (#4496): +that quest duplicated this one's bad-CRC drop and `CRC_error` count. diff --git a/quest/m1/ts-publish-muxdelay.md b/quest/m1/ts-publish-muxdelay.md deleted file mode 100644 index 688904da4d3..00000000000 --- a/quest/m1/ts-publish-muxdelay.md +++ /dev/null @@ -1,27 +0,0 @@ -# [XS] Documented ffmpeg line flushes audio - -## Goal - -The documented `ffmpeg ... -f mpegts -pes_payload_size 0 -` publish line stops -holding small audio frames in ffmpeg's muxer for up to 0.35 s. Those clumps -raise the importer's catalog `jitter` for the life of the track, and watch -adds about 230 ms of playout delay to match. - -## Plan - -Decided: add `-muxdelay 0` everywhere the line appears -(`demo/pub/justfile`, `doc/bin/cli.md`, `doc/concept/standard.md`, -`rs/moq-cli/README.md`). `import ts` needs no PCR lead. The reporter's patch -is ready. Verify by re-measuring the catalog jitter on a quiet-audio source; -there is no automated test for a docs line. - -The importer's jitter estimate keeping its maximum forever is a separate -problem; the player side is covered by the audio jitter target. - -## Closes - -- [#4347](https://github.com/moq-dev/moq/issues/4347) - close this issue when the quest finishes - -## Related - -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - a decaying playout estimate softens a transient burst diff --git a/quest/m1/ts-stats-module.md b/quest/m1/ts-stats-module.md new file mode 100644 index 00000000000..a68a4203fbd --- /dev/null +++ b/quest/m1/ts-stats-module.md @@ -0,0 +1,45 @@ +# [S] TS stats module + +## Goal + +On `dev`, every moq-mux TS stats type lives in the `container::ts::stats` +module beside `stats::Log`: `ts::Stats` becomes `ts::stats::Snapshot` and +`ts::StreamStats` becomes `ts::stats::Stream`. `StreamStats.track` becomes an +owned `String`, and `ts::MultipleProgramsError` becomes `#[non_exhaustive]`. +No new fields and no behavior change. + +## Plan + +Decided while planning the follow-ups of +[#4505](https://github.com/moq-dev/moq/pull/4505) and +[#4506](https://github.com/moq-dev/moq/pull/4506): + +- **Breaking, so `dev`.** `Stats` and `StreamStats` have been published since + moq-mux 0.9.14. #4506 kept them at `ts::` on `main` for that reason. +- **Names: `stats::Snapshot` and `stats::Stream`.** `Snapshot` matches + `moq_net::stats::Snapshot`. `stats::Import` was rejected because it reads + like `ts::Import`, and `stats::Pid` because the row is a stream's liveness, + not the PID itself. +- **`StreamStats.track` becomes `String`.** This is batched here so there is + one break, not two. [TS health stats](/quest/m2/ts-health-stats.md) needs + it so the type deserializes. +- **`MultipleProgramsError` gets `#[non_exhaustive]`.** Callers keep + recovering it by downcast (`moq-cli` hints `--program` from it) and keep + reading `programs`. It can gain fields without another break. A `ts::Error` + enum was rejected: the importer returns `anyhow`, so callers would still + downcast. +- Update moq-cli's `publish.rs`, the only consumer that names these types. + moq-srt only uses `stats::Log`. +- Main quests still add fields under the old names: + [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md), + [TS import health](/quest/m2/ts-import-health.md) and + [TS export liveness](/quest/m2/ts-export-liveness.md). The rename carries + those fields at merge time. Update the type names in the quests still open + when this lands, including [media stats schema](/quest/m1/stats/schema.md) + and [Rust reporters](/quest/m1/stats/rust.md). + +Public API: breaking renames in moq-mux. Wire: none. + +## Required + +- `main` merged into `dev`, carrying #4506's `ts::stats` module (dev has none yet) diff --git a/quest/m1/tstd/README.md b/quest/m1/tstd/README.md new file mode 100644 index 00000000000..ec8f9dc2cff --- /dev/null +++ b/quest/m1/tstd/README.md @@ -0,0 +1,27 @@ +# T-STD compliant TS export + +## Goal + +`moq export ts` output passes a full ISO 13818-1 T-STD buffer-model check +(transport, multiplex, and elementary buffers, with every access unit decoded +at its DTS without overflow or underflow), on a clean path and under +sustained loss. That is the bar for the media-aware lane to carry primary +distribution. Without it, only the passthrough lane can. + +## Plan + +Decided (2026-09-30), from a discussion with t0ms and Gwendal's email: a +TS export has to be a proper remux, not an interleave of demuxed tracks. +Padding, pacing, and muxing all assume a fixed delay, so the export gets one +first. t0ms is testing whether T-STD compliance is feasible at all; record +the result here. If it isn't, re-plan this line. + +This README owns the end-to-end proof: the #4613 netem rig (10% loss, a real +~10 Mb/s broadcast TS) passes the strict T-STD check, and the recipe runs +nightly. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - frames go out at media time plus a fixed `--delay`, in one order under loss +- [T-STD check](/quest/m1/tstd/check.md) - the harness grades the full buffer model instead of the transport buffer alone +- [TS byte schedule](/quest/m1/tstd/byte-schedule.md) - PCRs sit on the byte grid the mux rate implies, paced against the fixed delay diff --git a/quest/m1/ts-export-byte-schedule.md b/quest/m1/tstd/byte-schedule.md similarity index 61% rename from quest/m1/ts-export-byte-schedule.md rename to quest/m1/tstd/byte-schedule.md index 8427325a68e..5ff8a268bd6 100644 --- a/quest/m1/ts-export-byte-schedule.md +++ b/quest/m1/tstd/byte-schedule.md @@ -16,14 +16,20 @@ UDP sink is out of scope; delivery stays with an external tool. `rs/moq-mux/src/container/ts/export.rs` (`advance`, `emit`, `stuff`): a PCR's value follows its byte position at the mux rate, and a keyframe burst is spread over the slots before its DTS instead of landing between two PCRs. -- That makes the mux run ahead of decode by a buffer delay. The delay grows to - fit the largest burst seen and is capped by `--max-age`, which already bounds - the pacer's lead; no new flag. Say what happens when a burst does not fit the - cap (fail loud, or drop to VBR with a warning) and record the choice here. +- That makes the mux run ahead of decode by a buffer delay. Decided + (2026-09-30): the delay is the fixed `--delay` from + [fixed-delay release](/quest/m1/tstd/delay.md), not one that grows + to fit bursts. Say what happens when a burst does not fit the delay (fail + loud, or drop to VBR with a warning) and record the choice here. - The CLI `Delivery` pacer releases one slice per PCR interval; confirm it still writes on the schedule the PCRs describe. -- Grade the distribution of bytes between consecutive PCRs, not only - adjacency: extend `test/ts/pcr-timing.py` (or add a check beside it) and run - it in the existing TS test recipe against a CBR fixture. +- `test/ts/pcr-timing.py`'s `pcr-schedule` grades the bytes between + consecutive PCRs, report-only in the TS recipe. Once the schedule lands, gate + it there with `--schedule-pct-min`, against a fixture whose keyframes outgrow + a PCR slot; the generated clip mostly pads and passes already. - `doc/bin/cli.md`: say that export pads to `mpegts.muxRate` on a constant-rate schedule and what latency that adds. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - the delay this schedule paces against diff --git a/quest/m1/tstd/check.md b/quest/m1/tstd/check.md new file mode 100644 index 00000000000..a7c42f511f8 --- /dev/null +++ b/quest/m1/tstd/check.md @@ -0,0 +1,25 @@ +# [M] The TS harness grades the full T-STD buffer model + +## Goal + +`test/ts/compliance.py` models every T-STD buffer an elementary stream passes +through, not only the transport buffer. It fails a stream where any buffer +overflows or where an access unit hasn't fully arrived by its DTS, and the TS +recipe runs it strictly against `moq export ts` output in CI. + +## Plan + +Today the `tstd` check models only the transport-buffer (TB) smoothing stage. +It's a shape check that warns unless `--strict` is set (`test/ts/README.md`). +Extend it to the multiplex buffer (MB, for video) and elementary buffer (EB) +with the ISO 13818-1 leak rates and sizes for each stream type and level, and +remove each access unit at its DTS. Timing stays on the stream's own PCR +clock, so the result is deterministic for a file. + +Validate the model before gating: a known-compliant reference TS passes, and +a deliberately bursty one fails. Where TSDuck or another maintained tool +already implements T-STD, prefer it over hand-rolled math. + +Gate: strict `tstd` in the TS recipe for export output. Until +[fixed-delay release](/quest/m1/tstd/delay.md) lands, the check will likely +fail, so land it report-only and flip the gate in that PR. diff --git a/quest/m1/tstd/delay.md b/quest/m1/tstd/delay.md new file mode 100644 index 00000000000..e07d26616e6 --- /dev/null +++ b/quest/m1/tstd/delay.md @@ -0,0 +1,74 @@ +# [M] Muxing exports release frames on a fixed delay + +## Goal + +`moq export ts --delay ` works like an SRT receiver's TSBPD, through a +release stage in moq-mux that the FLV and MKV exports adopt next. Each frame +goes out at its media time plus a fixed delay, measured from when the first +frame arrived, and in `(pts, pid)` order across tracks. A frame that misses its +deadline is dropped and counted. Output order is then a function of the media +alone, even under sustained loss, and the output runs at the source's pace +instead of bursting after a stall. + +## Plan + +Decided (2026-09-30): + +- Why: TS assumes a constant end-to-end delay. Its tracks share one PCR clock, + and a receiver's T-STD buffers are sized for access units that arrive a fixed + time before their DTS, which is what SRT and UDP sinks deliver. +- The release stage is shared, not TS-specific: it takes each track's + frames, releases them in `(pts, track)` order at anchor + pts + delay, and + drops and counts late ones. TS adopts it here; FLV and MKV follow in their + own quests. fMP4 stays out: it deliberately skips cross-track ordering, + because its demuxers index by track (`fmp4/export.rs`). The fixed delay is + needed only at the final receiver; relays stay hop-by-hop. + Open for the PR: the stage's name and module. Ask the maintainer. +- One mode. Fixed-delay release replaces the stall/hold interleave in + `rs/moq-mux/src/container/ts/export.rs` (`stall`, `hold`, and the wait in + `pick_next_track`), which is deleted. #4618 is the interim fix for #4613 + until this lands. The hold can't stay deterministic under loss, because a + rewind clears every track's `timeline`, so the mux falls back to arrival + order until a quiet track shows. +- The release clock is anchored at the first frame's local arrival. A rewind + (a new program generation) re-anchors it. Publisher clock drift slowly + grows or shrinks the buffer; correct it only if measured. +- The flag is `--delay`, like `moq play`'s: one knob sets both the release + delay and the sources' staleness budget, and it replaces `--max-age` on + `moq export ts` (`moq play` already dropped `--max-age` for the same reason). + moq-srt egress passes its SRT latency (`rs/moq-srt/src/ts.rs`, which feeds + it to the muxer as the skip budget today). +- Deadlines are on decode time, not PTS. Reordered video reaches the muxer in + decode order (PTS 0, 120, 40, 80 ms), so a PTS deadline would either strand + a B-frame behind its reference or send it first. Each frame's deadline is + anchor + its authored DTS + delay, each track keeps its decode order, and + tracks interleave by `(DTS, pid)`, which is also the order T-STD removes + access units in. +- Late frames are dropped, as SRT's too-late drop does. A dropped video frame + leaves its track waiting for the next keyframe. + +Open: a backlogged or finished source (a file sink, an archive replay) would +come out at real-time pace from the first frame's arrival. Decide whether +release only gates drops and ordering, with pacing left to the CLI's +`Delivery` pacer, or whether file sinks skip it. + +Test with mocked time: two exporters fed the same frames with different +arrival skew, every frame inside its deadline in both, emit identical packet +order. Separately, a frame arriving after its deadline is dropped and counted, +and the rest still go out in `(DTS, pid)` order. A B-frame fixture (decode +order PTS 0, 120, 40, 80) loses nothing on a clean path. It must pass before +the hold is deleted. Rerun the #4613 netem rig (10% loss, 120 s) and +compare with #4618's numbers. + +Update `doc/bin/cli.md` and the `moq export ts` examples. + +Public API: `ts::Export` takes the delay in place of its max age and loses the +hold; breaking, on `dev`. Wire: +none. + +## Related + +- [FLV export delay](/quest/m1/flv-export-delay.md) - adopts the release stage +- [MKV export delay](/quest/m1/mkv-export-delay.md) - adopts the release stage +- [TS byte schedule](/quest/m1/tstd/byte-schedule.md) - uses this delay as its mux-ahead buffer delay +- [Plan: max-delay](/quest/m1/plan-max-delay.md) - whether `max_age` becomes `max_delay` everywhere else diff --git a/quest/m1/unknown-session-logs.md b/quest/m1/unknown-session-logs.md deleted file mode 100644 index aac062052a2..00000000000 --- a/quest/m1/unknown-session-logs.md +++ /dev/null @@ -1,46 +0,0 @@ -# [S] UnknownSession log flood - -## Goal - -moq.pro relays stop logging -`web_transport_moq::session: failed to decode unidirectional stream err=WebTransportError(UnknownSession)` -for streams that were simply reset or cut off before their WebTransport -header arrived. A stream that really names another session is still reported -as `UnknownSession`, and the error a caller sees says what happened. - -## Plan - -Seen in production at a rate like the old-group warnings -https://github.com/moq-dev/moq/pull/4208 fixed, on the same hosts. - -Root cause, confirmed by a test: `decode_uni` and `decode_bi` in -`web-transport-moq`'s `session.rs` map every failure to read the stream type -or session ID to `UnknownSession`, and a peer reset before those bytes -arrive is one. moq resets a group's stream when the group is superseded or -expires, and without reliable reset the header is discarded with it. - -The fix keeps the read's cause as `WebTransportError::ReadError`, keeps -`UnknownSession` for a session-ID mismatch, and logs a reset or lost -connection at debug: - -- [moq-dev/noq#19](https://github.com/moq-dev/noq/pull/19) for 2.x (`dev`) - and its backport [moq-dev/noq#20](https://github.com/moq-dev/noq/pull/20) - for 1.3.x (`main`). -- [moq-dev/web-transport#405](https://github.com/moq-dev/web-transport/pull/405) - for `web-transport-quinn`, `web-transport-noq`, and `web-transport-iroh`, - which carry the same code. `main` pins `web-transport-iroh` 0.7, so it - gets the iroh fix when `dev` merges. - -Remaining: bump `web-transport-moq` to the 1.3.3 release on `main` (and -2.0.1 on `dev` if it lands first). Then confirm on a moq.pro relay that the -rate drops, and that any remaining `UnknownSession` lines are real -mismatches. - -## Required - -- `web-transport-moq` 1.3.3 released from moq-dev/noq#20 - -## Related - -- #4262 - the close-code fix in the same crate, on `dev` -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - keeps a reset stream's header, which removes most of these diff --git a/quest/m1/uring-ietf.md b/quest/m1/uring-ietf.md index c9f9cbcb31a..c860ec359de 100644 --- a/quest/m1/uring-ietf.md +++ b/quest/m1/uring-ietf.md @@ -31,5 +31,5 @@ ring requires the release carrying it. ## Related -- [Stream sessions](/quest/m1/uring-tcp/README.md) - the other protocol gap - on the ring, WebSocket and HTTP +- [Stream sessions](/quest/m2/uring-tcp/README.md) - the other protocol gap + on the ring, WebSocket and HTTP, deferred to m2 diff --git a/quest/m1/watch-audio-time-stretch.md b/quest/m1/watch-audio-time-stretch.md index 0ceb0850b6f..34134a7e210 100644 --- a/quest/m1/watch-audio-time-stretch.md +++ b/quest/m1/watch-audio-time-stretch.md @@ -12,7 +12,7 @@ Boundaries: no packet loss concealment; an underrun still renders a ramped gap. The target estimator and the ring's slack and re-stall are the [audio jitter target](/quest/m0/audio-jitter-target/README.md) line (#3517 was closed in favor of it); the clock the stretch converges toward is -[Plan: A/V clock](/quest/m0/plan-av-clock.md). +[Plan: A/V clock](/quest/m1/av-clock.md). ## Plan @@ -28,5 +28,4 @@ was closed in favor of it); the clock the stretch converges toward is ## Required -- [Plan: A/V clock](/quest/m0/plan-av-clock.md) - stretching against a free-running ring only moves the drift - [Watch](/quest/m0/audio-jitter-target/watch.md) - the recorded traces this replays, and the JS target it converges toward diff --git a/quest/m1/watch-decoder-recovery.md b/quest/m1/watch-decoder-recovery.md deleted file mode 100644 index f4e208676d3..00000000000 --- a/quest/m1/watch-decoder-recovery.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Watch decoders recover from an error - -## Goal - -One malformed packet no longer ends audio or video for the rest of a -subscription. Today a WebCodecs error closes the decoder, both audio loops -`break` (added in #2415 to stop an `InvalidStateError` loop), and video calls -`effect.close()`; nothing rebuilds the decoder, and playback silently stops. - -## Plan - -Decided: rebuild inside the loop, for audio and video alike. On a decoder -error, rebuild through one shared `build()` helper, skip to the next keyframe, -and give up after three rebuilds in a row with no output. A rebuilt legacy -audio decoder re-runs its warmup priming. Cover the legacy and CMAF loops. - -Tests: a corrupt packet mid-stream is followed by decoded output from the next -keyframe; a stream of only corrupt packets gives up after three rebuilds -instead of spinning. - -## Closes - -- [#4324](https://github.com/moq-dev/moq/issues/4324) - close this issue when the quest finishes - -## Related - -- [Audio warmup](/quest/m1/audio-warmup.md) - the same audio loops and priming -- [Watch video guards](/quest/m1/watch-video-guards.md) - keeps bad input from reaching the video codec diff --git a/quest/m1/watch-video-guards.md b/quest/m1/watch-video-guards.md deleted file mode 100644 index 765b652fc77..00000000000 --- a/quest/m1/watch-video-guards.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] Watch video holds its picture and its order - -## Goal - -Two `js/watch/src/video/decoder.ts` defects stop reaching the viewer: - -- Promoting a video track when none is active (after pause, scrolling back - into view, or a hidden rendition returning) holds the last picture instead - of painting black for a round trip plus a keyframe. -- An older finished group accepted behind the live group is never fed to the - codec between live deltas. - -## Plan - -Decided: - -- `#runActive` ignores the new track's initial `undefined` frame; clearing - stays with `#clearCurrentFrame` and `close()`. The held timestamp stays - with the held frame, so the outputs describe what is on screen. -- The guard lives in both video decode loops (legacy and CMAF): skip a frame - whose group is older than the newest group already fed, and reset on a - discontinuity. The consumer keeps serving older groups, since audio's - timestamp-indexed ring needs them. Fix the consumer comment claiming video - drops a late frame at render; that only holds after decode. - -Tests: a promote from nothing keeps the previous frame and timestamp; an older -group arriving after a newer one never reaches the decoder. - -## Closes - -- [#4338](https://github.com/moq-dev/moq/issues/4338) - close this issue when the quest finishes -- [#4339](https://github.com/moq-dev/moq/issues/4339) - close this issue when the quest finishes - -## Related - -- [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - another fix in the same decoder -- [Watch decoder recovery](/quest/m1/watch-decoder-recovery.md) - a bad feed today ends video for the subscription diff --git a/quest/m1/watch-worker.md b/quest/m1/watch-worker.md index ccbbc14bc72..527a11c7471 100644 --- a/quest/m1/watch-worker.md +++ b/quest/m1/watch-worker.md @@ -31,7 +31,7 @@ Gate on the plan's jank harness and N-player sweep, both nightly. ## Required - [Plan: watch worker](/quest/m1/plan-watch-worker.md) - picks the worker model and rewrites this quest -- [A/V clock](/quest/m0/plan-av-clock.md) - reshapes `Sync` and the worklet playhead, so the move to the worker happens once +- [A/V clock](/quest/m1/av-clock.md) - reshapes `Sync` and the worklet playhead, so the move to the worker happens once ## Related diff --git a/quest/m1/watch-worklet-file.md b/quest/m1/watch-worklet-file.md deleted file mode 100644 index b6a778364a6..00000000000 --- a/quest/m1/watch-worklet-file.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Watch audio under a strict CSP - -## Goal - -A page with CSP `script-src 'self'` plays watch audio. Today -`js/common/vite-plugin-worklet.ts` always exports the render worklet as a -`blob:` URL, so `addModule` is refused and audio never starts, with only a -console "spawn error". - -## Plan - -Decided: in `vite build`, emit the worklet as its own file and export -`new URL(".js", import.meta.url)`; keep the blob URL only in -`vite serve`. Vite, webpack 5, and esbuild (with a plugin) resolve that -pattern inside a dependency. This applies to the publish capture worklet too -and deletes the runtime blob code. Document the consumer-bundler requirement. -The publish capture worker (`?worker&inline`) is out of scope. - -Verify in a browser under `script-src 'self'` (Chromium and Firefox) and -from a Vite consumer app. - -## Closes - -- [#4323](https://github.com/moq-dev/moq/issues/4323) - close this issue when the quest finishes - -## Related - -- [JS bundle trims](/quest/m1/js-bundle-trims.md) - minifies worklets through the same plugin -- [Plan: watch worker](/quest/m1/plan-watch-worker.md) - notes the capture worker's `worker-src blob:` need diff --git a/quest/m1/wt-close-upstream.md b/quest/m1/wt-close-upstream.md index 4a0b39f6cff..ac4b763988a 100644 --- a/quest/m1/wt-close-upstream.md +++ b/quest/m1/wt-close-upstream.md @@ -1,4 +1,4 @@ -# [S] WebTransport close delivers its capsule upstream +# [XS] WebTransport close delivers its capsule upstream ## Goal @@ -20,22 +20,37 @@ detached task until `closed()` resolves, capped at a 10s `CLOSE_LINGER`. Decided 2026-09-29: fix it at the source and remove the timeout workaround. -- In moq-dev/noq, the close path keeps whatever the capsule needs alive until - it is delivered, without the caller's help. Its regression test drops the - session right after `close()` and asserts the peer reads the capsule - before the H3 control stream ends; it must fail on 1.3.2. A Rust peer - alone proves nothing: `session_close_surfaces_a_rejection_code` in - `rs/moq-tokio/tests/broadcast.rs` passed on 1.3.2 without the linger, - because only Chromium treats the control stream's end as fatal. Add a - browser check too if the playwright harness makes it cheap. -- Release `web-transport-moq` 1.3.x and bump the pin on `main` (2.x on `dev` - if it has moved). +The upstream fix makes the close task own a clone of the whole session: +[moq-dev/noq#23](https://github.com/moq-dev/noq/pull/23) for 2.x (`dev`) and +its backport [moq-dev/noq#24](https://github.com/moq-dev/noq/pull/24) for +1.3.x (`main`). Their `web-transport-moq/tests/close_capsule.rs` drops the +session right after `close()` against a hand-rolled HTTP/3 peer and fails on +1.3.2 and 2.0.0. + +Remaining, once the releases carrying them are published: + +- Bump the `web-transport-moq` pin on `main` (and on `dev` if 2.0.x lands + first). - Delete `CLOSE_LINGER`, its task, and its mock-session tests from - moq-tokio. + moq-tokio. They are exactly what #4429 added, so reverting it is enough. + +A browser check is left to +[Browser close code](/quest/m1/browser-close-code.md): the playwright harness +has no close-code scenario, so it is not cheap to add here. Public API: none. Wire: none. +Decided in the 2026-09-30 audit: the UnknownSession log flood quest merged +here, since the same `web-transport-moq` release carries its fix. +`decode_uni` and `decode_bi` mapped a stream reset before its WebTransport +header to `UnknownSession`, flooding relay logs with WARNs; the fork now +keeps the read's cause and logs a reset at debug. After the bump, confirm on +a moq.pro relay that the flood stops. + +## Required + +- A `web-transport-moq` 1.3.x release that carries moq-dev/noq#24 + ## Related -- [#4262](https://github.com/moq-dev/moq/pull/4262) - fixed the same symptom over qmux and raw QUIC, on `dev` -- [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - another `web-transport-moq` release and pin bump +- [Browser close code](/quest/m1/browser-close-code.md) - the playwright case that proves Chromium reads the code this quest unblocks diff --git a/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md b/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md deleted file mode 100644 index f77cafbf261..00000000000 --- a/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md +++ /dev/null @@ -1,44 +0,0 @@ -# [S] Plan TR 101 290 monitoring - -## Goal - -The TR 101 290 stream-health requirements in -[#1838](https://github.com/moq-dev/moq/issues/1838) become scoped -implementation quests with the open questions answered. This quest writes -quests, not code. - -## Plan - -Run `/quest-plan` against the issue and the current tree. The issue is a -requirements list (ETSI P1/P2/P3 checks, per-check counters, a per-stream -health roll-up) and asks for agreement before any skeleton; its parent -proposal #1799 is closed. - -Settled by the issue, carry over: - -- TS-level checks run at the TS edges (`moq import ts`, `moq export ts`, - `moq-srt`), never in the media-agnostic relay. -- In today's media-aware lane our muxer regenerates PAT, PMT, PCR, and CC, - so egress checks validate our own output and SI checks are not applicable. - Full P1 to P3 conformance only means something for an opaque whole-mux - lane, which nothing plans yet. -- Results surface through the existing stats plumbing (`moq-stats`), not a new - transport. No remediation (FEC, 2022-7) and no GUI. - -Questions the planning session must answer: - -1. Where the checks live: a new crate, or beside the TS container in - `rs/moq-mux/src/container/ts`. -2. The MVP subset: P1 plus the PCR, CC, and PTS parts of P2 is the issue's - suggestion. -3. The configuration surface (thresholds, PIDs, sampling) and how the - counters map onto `moq-stats` tracks. -4. Whether the opaque whole-mux lane is wanted at all; without it, P3 is out. - -## Closes - -- [#1838](https://github.com/moq-dev/moq/issues/1838) - close this issue when the quest finishes - -## Related - -- [TS import liveness](/quest/m1/3489-ts-import-stream-liveness.md) - the stream-stall case this model names `PID_error` diff --git a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md b/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md index 384a5f33b78..532a8543e66 100644 --- a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md +++ b/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md @@ -1,29 +1,29 @@ -# [L] Complete NVIDIA Main10 and AV1 encoding support +# [M] Complete NVIDIA Main10 encoding support ## Goal -Implement and verify the remaining 10-bit HEVC and AV1 encoding work tracked -in [#2147](https://github.com/moq-dev/moq/issues/2147). NVDEC AV1 decoding and +Implement and verify the remaining 10-bit HEVC encoding work tracked in +[#2147](https://github.com/moq-dev/moq/issues/2147). NVDEC AV1 decoding and catalog AV1 types already exist; do not reimplement them. ## Plan +Decided in the 2026-09-30 audit: AV1 encoding split out to +[NVENC AV1](/quest/m3/nvenc-av1.md), because it needs an Ada GPU and the only +GPU CI host is an RTX 3070 Ti. Main10 stays here since that host can verify it. + Extend the settled frame and NVENC contracts with Main10 surfaces, profile selection, and accurate codec metadata. Audit byte pitch, plane layout, CPU download, and P016 input/output together; a codec enum alone does not establish 10-bit support. Preserve color metadata and refuse unsupported conversions. Do not imply that OpenH264 can decode HEVC or tonemap HDR. -Add AV1 encoding only where the queried NVIDIA device/driver supports it. -Preserve OBU framing and accurate catalog configuration through transcode. Use existing extensible codec enums; no replacement of the 0.1 core API is planned. Keep the NVIDIA backend optional and loaded at runtime. -Split Main10 and AV1 implementation into independent PRs if hardware or review -scope warrants it. Validate decoded pixels, bit depth, profile, framing, -resource lifetime, drain, and refusal on unsupported devices. Wire fixtures -and contract tests into CI, and record actual hardware execution separately. -Lack of suitable hardware leaves that implementation unverified, not complete. +Validate decoded pixels, bit depth, profile, resource lifetime, drain, and +refusal on unsupported devices. Wire fixtures and contract tests into CI, and +run the hardware tests on the [GPU CI](/quest/m1/gpu-ci.md) host. Public API: additive capabilities on the extension points settled on main. Wire: existing codec signaling, with cross-language fixtures for any metadata change. @@ -34,4 +34,6 @@ codec signaling, with cross-language fixtures for any metadata change. ## Related +- [GPU CI](/quest/m1/gpu-ci.md) - the RTX 3070 Ti host that verifies Main10 +- [NVENC AV1](/quest/m3/nvenc-av1.md) - the AV1 half of #2147, hardware-gated - [Codec coverage study](/quest/m2/video-codec-coverage.md) - measure optional software and other native backends separately diff --git a/quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md similarity index 90% rename from quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md rename to quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md index 65fd5ba4cbd..0ddef060e66 100644 --- a/quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ b/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md @@ -9,7 +9,9 @@ exporter understands. Server-side ad insertion is a separate future quest. ## Plan -Use the shared event contract [emsg](/quest/m1/emsg.md) settles. Deliver cues immediately, including when splice_time is in the +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + +Use the shared event contract [emsg](/quest/m2/emsg.md) settles. Deliver cues immediately, including when splice_time is in the future; consumers need advance notification. Metadata group sequences are independent of media GOPs. @@ -40,14 +42,10 @@ schema: the draft is the normative spec, and a section Rust and JS emit must be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, `rs/moq-mux`, `doc/concept`. -## Required - -- [fMP4 emsg](/quest/m1/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Closes - [#2279](https://github.com/moq-dev/moq/issues/2279) - close this issue when the quest finishes ## Related -- [ID3 catalog section](/quest/m1/id3.md) - the other typed timed-metadata section, same rule +- [ID3 catalog section](/quest/m2/id3.md) - the other typed timed-metadata section, same rule diff --git a/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md b/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md index d72e102a55f..d479c5efcac 100644 --- a/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md +++ b/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md @@ -4,7 +4,7 @@ The Linux zero-copy spine from [#2819](https://github.com/moq-dev/moq/issues/2819), `PipeWire DMA-BUF -> Surface::DmaBuf -> Vulkan import -> render shader`, is -proven on real hardware, and a V4L2 camera feeds `Surface::DmaBuf` too. +proven on real hardware. ## Plan @@ -26,9 +26,11 @@ What remains: driver will not import, and re-tiles nothing. A VA-API VPP re-tile is only worth adding if a measured capture source lands on such a modifier; record the modifiers seen and decide. -- V4L2 capture still converts to I420 on the CPU. Export its buffers with - `VIDIOC_EXPBUF` (the ioctl is in `moq-v4l`, unused) as a `Surface::DmaBuf` - so a camera reaches VA-API or NVENC without a copy. + +Decided in the 2026-09-30 audit: V4L2 `VIDIOC_EXPBUF` export is dropped. +V4L2 capture only takes YUYV and MJPEG (`rs/moq-video/src/capture/v4l2.rs`), +both of which need a CPU conversion or decode anyway, so exporting the buffer +saves no copy. Revisit only if NV12 camera capture lands. Refs #2481, #1837. @@ -39,4 +41,3 @@ Refs #2481, #1837. ## Related - [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate memory blocks from a camera, the capture offer rather than this import -- [#2893: video: validate PipeWire DMA-BUF capture on KDE hardware](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - the KDE portal capture that timed out diff --git a/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md b/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md similarity index 90% rename from quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md rename to quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md index 67e260a184d..c6f9e783364 100644 --- a/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md +++ b/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md @@ -31,9 +31,13 @@ The reason it is not a small change: `poll_open_uni` would have to hold a half-o Worth confirming the trade too: making `open` block on credit moves the backpressure earlier, which is more correct but changes when a caller learns about it. +Decided in the 2026-09-30 audit: moved to m2. No in-tree caller hits the +wart (moq-net always pairs `finish()` with `poll_closed`), and io_uring +ships in no package. + ## Required -- [Open contract](/quest/m1/perf/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation +- [Open contract](/quest/m2/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation ## Closes diff --git a/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md b/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md similarity index 93% rename from quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md rename to quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md index 9dd02084d06..3bf50216a67 100644 --- a/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md +++ b/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md @@ -35,6 +35,9 @@ The kernel returns when `N` CQEs arrive, when `t` expires after partial progress Benchmark chat, 1:1 video, and fanout workloads with `N = 1/4/8/16` and `t = 0/5/10/20 us`. Record CQEs per wake, enters per second, CPU per message, p50, p99, and p999 latency. Pick no production default until the latency budget and CPU win are both demonstrated. +Decided in the 2026-09-30 audit: moved to m2. It trades latency for CPU, +the win is unmeasured on noq, and io_uring ships in no package. + ## Closes - [#3200](https://github.com/moq-dev/moq/issues/3200) - close this issue when the quest finishes diff --git a/quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md b/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md similarity index 93% rename from quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md rename to quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md index bb9a3d65b71..67f44fde701 100644 --- a/quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md +++ b/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md @@ -30,6 +30,9 @@ Registered files let SQEs address a stable table slot with `types::Fixed`. This Benchmark steady-state send/receive traffic and high socket-churn workloads. Record CPU, cycles, instructions, throughput, and socket lifetime cost. Keep the implementation only if the hot-path win justifies the slot-lifecycle complexity. +Decided in the 2026-09-30 audit: moved to m2. The hot-path win is +unmeasured on noq, and io_uring ships in no package. + ## Closes - [#3202](https://github.com/moq-dev/moq/issues/3202) - close this issue when the quest finishes diff --git a/quest/m2/README.md b/quest/m2/README.md index 249d01e62e2..867c989db8e 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -10,83 +10,109 @@ Nothing here blocks a release. Promote a quest into [m1](/quest/m1/README.md) when it joins the next wave, including planning work whose decisions are worth settling now; deferral does not abandon a feature. A study may end with a measured no-go. Work gated on hardware, a -partner, or a provider waits in [m3](/quest/m3/README.md); work waiting on an -upstream release waits in [m4](/quest/m4/README.md). +partner, a consumer, or a provider waits in [m3](/quest/m3/README.md); work +waiting on an upstream release waits in [m4](/quest/m4/README.md). ## Required +- [P2P](/quest/m2/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy +- [One port](/quest/m2/one-port/README.md) - a relay speaks QUIC and STUN on one UDP port and HTTP, RTMP, and RTMPS on one TCP port; WebRTC media is an embedder hook +- [Ladder](/quest/m2/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling +- [Processor](/quest/m2/processor/README.md) - a customer-run worker publishes an on-demand contribution under its own service prefix with scoped access +- [Stream sessions](/quest/m2/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most +- [fMP4 emsg](/quest/m2/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them +- [ID3 catalog section](/quest/m2/id3.md) - timed ID3 as a first-class container-neutral catalog section +- [FLV script tags](/quest/m2/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import +- [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition +- [CEA-608/708](/quest/m2/captions-cea.md) - captions carried inside video SEI become a real text rendition at import +- [Browser archive](/quest/m2/archive-browser.md) - the same contract for browser-published broadcasts +- [Paced replay](/quest/m2/archive-paced-replay.md) - a replay pushes its groups to live subscribers on one shared clock, so any live player plays it +- [Install moq](/quest/m2/moq-installer.md) - one command installs or upgrades the released CLI on macOS and Linux +- [Install URL](/quest/m2/moq-install-url.md) - moq.dev serves the canonical installer at /install.sh +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the relay runs under a `moq` verb with its own flags and TOML, while `moq-relay` stays a minimal binary +- [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback +- [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback +- [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback +- [Windows GPU input](/quest/m2/obs-windows.md) - import or blit OBS D3D11 textures with explicit synchronization +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the session shape it translates +- [Generated IETF](/quest/m2/rs2ts-ietf.md) - @moq/net's moq-transport session is generated too +- [Per-stream deadlines](/quest/m2/quic-deadline.md) - hopeless retransmits + become resets, and a tail loss probe fires early while there is still time +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - qmux is a + first-class crate in the fork over the shared stream state machine +- [Align BBR loss handling with draft-06](/quest/m2/quic-bbr-loss-parity.md) - losses use their own sample and undo re-enters ProbeUp through Refill +- [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - a written + verdict on marking versus dropping, and whether Linode and OVH keep marks +- [Starvation at frame granularity](/quest/m2/starvation-frames.md) - the + acknowledged frontier moves at every frame boundary through `poll_acked`, + with a delivery-delay histogram for jitter +- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - `moq-quic` reports + how far a send stream has been acknowledged and when +- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the + backend-neutral hook that awaits an acknowledged stream offset, implemented + for noq and released +- [#3200](/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - moq-uring: batch completion wakeups with MIN_TIMEOUT +- [#3202](/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: use fixed-file slots for worker UDP sockets +- [Open contract](/quest/m2/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation +- [#3129](/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring: write the WebTransport stream header at open time, so finish() never owes one +- [Cache shard](/quest/m2/cache-shard.md) - stop hammering one process-global cache line from every worker +- [Encoder feedback](/quest/m2/stats-encoder-feedback.md) - a Rust encoder + reads its viewers' feedback and adapts its bitrate +- [Text availability](/quest/m2/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline +- [Closure counters](/quest/m2/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw +- [Bench coverage](/quest/m2/bench-coverage.md) - Criterion targets for moq-pattern matching first, then the stats producer, moq-mux containers, the hang catalog, and moq-auth +- [Signed priority](/quest/m2/signed-priority.md) - on dev, every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it - [AV1 metadata separation](/quest/m2/av1-metadata.md) - retain metadata OBUs inline while evaluating separate delivery -- [SEI separation](/quest/m2/sei/README.md) - retain inline SEI until measured savings or a metadata-only consumer justify a split -- [Catalog track identity](/quest/m2/catalog-tracks.md) - compare immutable track definitions with explicit catalog-to-group binding +- [Catalog track identity](/quest/m2/catalog-tracks.md) - a changed track configuration becomes a new track name or epoch, never a mutated definition +- [Catalog colour model](/quest/m2/color-catalog.md) - the catalog describes a rendition's colour and HDR properties once a renderer consumes them - [Archive recovery listing](/quest/m2/archive-recovery-listing.md) - a resumed DVR lists what changed since its checkpoint, not every stored group -- [Archive backward timestamps](/quest/m2/archive-backward-timestamps.md) - a resumed recording refuses a track whose timestamps go backward -- [IETF drain before close](/quest/m2/ietf-drain-before-close.md) - moq-transport sessions deliver finished tracks before a graceful close, as moq-lite does -- [moq play drain tail](/quest/m2/play-drain-tail.md) - retired renditions and finite tracks play their last 10 ms of audio - [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - Linux relay packages ship io_uring once the ring is on par with tokio -- [Mobile ownership](/quest/m2/mobile-ownership.md) - decide whether Rust or platform code owns mobile capture, codecs, and rendering - [iOS capture](/quest/m2/mobile-capture-ios.md) - camera and screen capture if the mobile ownership decision selects Rust - [Android capture](/quest/m2/mobile-capture-android.md) - NDK/JNI capture using the existing codecs if mobile ownership selects Rust - [Mobile completion](/quest/m2/mobile-completion.md) - verify the selected native/mobile path before closing #700 -- [Linux OBS GPU input](/quest/m2/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination -- [LiveKit client shim](/quest/m2/livekit-shim.md) - a media compatibility facade over the room SDK -- [Audio loss recovery](/quest/m2/audio-loss-recovery.md) - prove a useful Opus recovery policy before exposing another option -- [Opus implementation](/quest/m2/audio-opus-backend.md) - compare current codec quality, CPU, and optional build costs +- [Opus implementation](/quest/m2/audio-opus-backend.md) - compare Opus codec quality, CPU, build cost, and the loss recovery each backend offers - [Latency ledger](/quest/m2/latency-ledger.md) - a session reports where its end-to-end audio delay went, stage by stage - [JS LOC duration marker](/quest/m2/js-loc-duration-marker.md) - `@moq/loc`'s producer ends each video group with the empty duration frame, as moq-mux does -- [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer - [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - Android decodes HE-AAC, multichannel AAC, and what else the device offers - [MediaCodec encode](/quest/m2/audio-encode-mediacodec.md) - Android encodes AAC-LC - [Video codec coverage](/quest/m2/video-codec-coverage.md) - prioritize remaining native AV1 and portable decoder gaps -- [#2147](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - moq-video: 10-bit HEVC and AV1 support in the NVIDIA codec path +- [#2147](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - moq-video: 10-bit HEVC in the NVIDIA codec path; AV1 is m3 - [NVENC buffer pool](/quest/m2/nvenc-pool.md) - NVENC reuses input and output buffers instead of allocating per frame, if a benchmark shows it wins - [NVENC held frames](/quest/m2/nvenc-held-frames.md) - moq-nvenc refuses or drives configurations whose frames the driver holds back - [Direct3D11 render import](/quest/m2/render-d3d11.md) - Windows presents without downloading every frame to system memory - [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - video with periodic intra refresh publishes, imports, and tunes in cleanly with one group per sweep and a catalog `warmup` - [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane - [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - moq-video: validate PipeWire DMA-BUFs into the Vulkan renderer on hardware, and export V4L2 buffers as DMA-BUFs -- [Unreal prototype](/quest/m2/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture -- [Unity prototype](/quest/m2/unity.md) - the C# package under IL2CPP, playing subscribed audio -- [C# through moq-ffi](/quest/m2/cs/README.md) - generated C# over moq-ffi as a NuGet package with native runtimes - [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests -- [Conan remote](/quest/m2/cpp-conan.md) - a remote we own serves the same tarball to `conan install` -- [Compressed tracks](/quest/m2/flate/README.md) - the hand-written binding wrappers expose flate tracks - [Binary delta stats](/quest/m2/stats-delta.md) - an on-demand varint delta flavor of every stats track, if relay encode CPU still matters after the JSON fixes - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation -- [Redundant ingest](/quest/m2/redundant-ingest.md) - decide whether two publishers sharing one epoch may splice, and who declares the incumbent dead before the keep-alive does -- [Multipath spike](/quest/m2/multipath-spike.md) - whether bonded contribution over multipath QUIC is worth building, given it needs noq on both ends -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - per-packet arrival times in ACKs, the feedback GCC and deadlines need -- [QUIC GCC](/quest/m2/quic-gcc.md) - a measured verdict on delay-based congestion control for media egress, shipping as `RealTime` -- [QUIC FEC](/quest/m2/quic-fec.md) - a measured verdict on transport-level FEC vs retransmission -- [Google BBR comparison](/quest/m2/quic-bbr-google.md) - measure growth detection and precautionary probing after the correctness fixes -- [WHEP ABR](/quest/m2/whep-abr.md) - a WHEP viewer switches renditions from its own congestion feedback -- [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference +- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - moq-uring receives from the buffer ring and transmits into registered buffers with no copy, once a profile says where +- [BBR media study](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference, and where our BBR differs from Google's - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer -- [noq socket close](/quest/m2/noq-socket-close.md) - noq releases an endpoint's socket on close, so moq-tokio drops its wrapper -- [Drop the hidden cluster exemption](/quest/m2/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire -- [Routing cost domains](/quest/m2/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs -- [Kernel pacing](/quest/m2/quic-kernel-pacing.md) - whether SO_TXTIME pacing beats a userspace pacer the io_uring driver ignores today -- [Send batching](/quest/m2/quic-send-batching.md) - whether sendmmsg across connections pays on the tokio path -- [Send buffer pools](/quest/m2/quic-buffer-pool.md) - whether pooled send buffers beat Bytes in the stream send path -- [AF_XDP UDP path](/quest/m2/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK +- [Socket close](/quest/m2/noq-socket-close.md) - `moq-quic` releases an endpoint's socket on close, so moq-tokio drops its wrapper - [GOP overhead](/quest/m2/gop-overhead.md) - price the I-frames a short GOP pays for, deciding whether a long GOP plus a keyframe request is worth designing -- [#1838](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - plan TR 101 290 stream-health monitoring into implementation quests +- [Per-program SI](/quest/m2/ts-program-si.md) - a selected TS program's broadcast carries only its own service's SDT and EIT +- [TS import health](/quest/m2/ts-import-health.md) - `moq import ts` counts the TR 101 290 errors of the feed it receives, PCR and PTS graded on its own values +- [TS export liveness](/quest/m2/ts-export-liveness.md) - `moq export ts` reports each elementary stream's access units and quiet time, catching a per-track stall +- [TS health stats](/quest/m2/ts-health-stats.md) - the TS counters ride the stats plumbing beside the media counters - [Teleoperation](/quest/m2/teleop/README.md) - MoQ carries robot video down and control up on one session as a library capability -- [SIP media stack](/quest/m2/sip-stack.md) - terminate one inbound SIP audio call leg and expose it as Opus frames -- [Carrier voice](/quest/m2/carrier-voice/README.md) - determine whether MoQ should be the call fabric for programmable carrier voice -- [LiveKit WebRTC bridge](/quest/m2/livekit-webrtc-bridge.md) - a go/no-go verdict, backed by a spike, on per-track LiveKit-to-MoQ bridging -- [Common Access Tokens](/quest/m2/cat/README.md) - a moq-transport client presents a CAT in SETUP and `moq auth serve` admits it with the scope its `moqt` claim names -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - run exact source snapshots on accessible Linux and device hosts with retrievable debug evidence - [Media QA on other engines](/quest/m2/browser-media-qa-engines.md) - the media harness measures a Firefox or WebKit player over the fallback and names what each engine lacks - [Firefox 155 WebTransport](/quest/m2/firefox-155-webtransport.md) - Firefox negotiates the version by subprotocol, and the other new WebTransport features stay unused on purpose -- [Windows capture parity](/quest/m2/capture-windows.md) - system audio and screen cursor capture with a settled app-capture policy +- [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - one WGC backend for display and window capture with the cursor, replacing Desktop Duplication and GDI +- [Windows capture parity](/quest/m2/capture-windows.md) - system audio and a settled app-capture policy - [Linux capture parity](/quest/m2/capture-linux.md) - Wayland window/system-audio capture with explicit display-selection and app-capture limits -- [Plan capture ergonomics](/quest/m2/capture-ergonomics.md) - scope independent crop and audio mixing quests - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it - [X11 capture transport](/quest/m2/x11-capture-shm.md) - move X11 capture to shared memory and RandR events instead of a per-frame socket copy -- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - stop rebuilding a full-frame buffer every tick in the X11 and Windows backends - [Interop graceful close](/quest/m2/interop-graceful-close.md) - successful runner publications withdraw before disconnecting; external repository approval required +- [Egress profile](/quest/m2/quic-egress-profile.md) - measure relay send-path syscalls, pacing bursts, and allocations before optimizing any of them +- [SEI separation study](/quest/m2/sei.md) - measure whether separating SEI saves enough, or has a metadata-only consumer, to justify a split +- [Compressed tracks](/quest/m2/flate.md) - moq-ffi and every wrapper expose flate tracks through a `flate` namespace like `json` +- [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table +- [moq-transport cluster peers](/quest/m2/ietf-cluster-peers.md) - an extended cluster draft lets moq-transport relays peer again, stitching failover on the reply's origin +- [MSFTS convergence](/quest/m2/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where the two still differ: program tables and the ES payload unit +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 encode and decode, pre-generated bindings, and pooled resize surfaces, including the moq-dev/vaapi release that carries them diff --git a/quest/m2/announce-shapes.md b/quest/m2/announce-shapes.md new file mode 100644 index 00000000000..db1263cce2f --- /dev/null +++ b/quest/m2/announce-shapes.md @@ -0,0 +1,110 @@ +# [XL] Announcement shapes in moq-lite + +## Goal + +A moq-lite announcement carries its shape, prefix, exact, suffix, or +prefix+suffix, and relays preserve it across hops. A subscriber can request +announcements by any shape (`**/transcode.pro`), and a publisher can +advertise one, so a fleet-wide service claims every matching path once +instead of per prefix. An exact broadcast at `/a` stays hidden from a reader +scoped to `/a/b` on every hop, not only on the origin holding it. + +moq-lite only: IETF sessions stay prefix-only. Routing only: token claim +patterns keep their suffix support unchanged. + +## Plan + +Decided 2026-09-29 (quest-plan interview): + +- [#4479](https://github.com/moq-dev/moq/pull/4479) does not land. It hid an + exact broadcast from a narrower reader only on the origin holding it: no + wire carries exactness, so relays install forwarded announcements through + `Producer::dynamic` as prefix routes and the broadcast's existence leaks to + narrower readers downstream. Exactness and suffixes are one problem, a + route's shape on the wire, so they are one quest. +- IETF stays prefix-only: moq-transport will not support exact or suffix + announcements (PUBLISH_NAMESPACE and NAMESPACE are prefix routes), so a + session negotiated as IETF never carries a shape and there is no draft to + converge with. +- The quest grew from the suffix-announce quest rather than a new m1 quest, + because that quest already holds the benchmark-first plan and the + version-gated wire approach both shapes need. +- Moved from m3 to m2 in the 2026-09-30 audit: it has no external gate, and + the exact-scope leak is a real bug. +- The old gate ("a deployment needs a suffix claim a service prefix cannot + express") is removed: the exact-scope leak is reason enough. + +### Wire + +The shape rides on both ANNOUNCE_REQUEST (interest) and ANNOUNCE_START +(advertisement), version- or setup-gated like `hidden`. A new announce Type is +not an option: an old receiver skips an unknown type without assigning it an +id (`rs/moq-net/src/lite/announce.rs`), so the id streams diverge. An older +peer gets prefix-only behavior; decide per shape whether downgrading it to a +prefix is safe (an exact route widened to a prefix still leaks) or whether the +route is withheld. Update `js/net` and `drafts/draft-lcurley-moq-lite.md` in +the same PR. + +Today ANNOUNCE_START carries a path relative to the requested prefix, which +the receiver joins back on (`rs/moq-net/src/lite/subscriber.rs`). A suffix +interest (`**/transcode.pro`) has no literal prefix to join, and a matching +route is not its suffix, so the draft must define how each advertisement is +anchored and rebased for each interest shape, with the cross-shape overlap +cases as vectors both languages test. + +Only these four shapes go on the wire. A richer interest pattern +(`pid/*/chat`) stays a consume-side filter over the widest shape that covers +it. Path patterns already shipped for that filtering and for token claims +(`moq-pattern`, `@moq/pattern`, +[#3746](https://github.com/moq-dev/moq/pull/3746), and the +[auth line](/quest/m1/auth/README.md)). + +### Model + +The origin model needs an `exact` route kind distinct from `source`: today +only a local broadcast (`source` set) is exact, and a forwarded route is +always a prefix. Carrying the kind also tightens `serves()` for a remote exact +route. An exact and a prefix route can share a path, but `sync_cursor` +presents one best entry per path and the lite announce state +(`AnnounceRun.live`, pending updates) is keyed by path alone, so today one +shape hides the other on the wire. Shape likely joins that identity. The +known exact-scope spots: + +- Rust: `sync_cursor` in `rs/moq-net/src/model/origin.rs` admits an exact + entry by prefix overlap; match it against the reader's patterns instead. + `cursor_keeps_an_overlapping_prefix_above_its_scope` covers a prefix route + and stays. +- JS: `Scope.projectRoutes` in `js/net/src/origin.ts` treats every entry + above the root as covering, and `Candidate.exact` is local-only today. +- Test in both languages, locally and across a relay hop: an exact broadcast + at `/a` and a prefix route at `/a` both survive a root-scoped hop, and read + through a `/a/b` scope yield only the prefix. #4479's regressions and + benchmark are a starting point. + +### Benchmark first + +The route table is a trie keyed by path segment (`rs/moq-net/benches/origin.rs`). +A suffix cannot walk it, so a naive match costs the whole announce table on +every announcement and every new cursor. Requests hit the same wall: +`request_broadcast` resolves through `best_route`, which walks the prefix trie +for the longest covering claim, so a suffix advertisement must also be found +by SUBSCRIBE and FETCH resolution. Longest prefix cannot rank `a/**` against +`**/z` for `a/x/z`, so define one total cross-shape precedence and tie rule +that Rust, JS, and relays share; path patterns' structural specificity is the +natural starting point. + +Extend `rs/moq-net/benches/origin.rs` with suffix and exact cursors and route +lookups, each swept over publishers and subscribers, and extend +`js/net/bench/forward.ts` the same way, since `Scope.projectRoutes` scans +routes independently of Rust. The slopes decide between a reversed-segment +index and dropping suffix shapes from the quest. + +A non-prefix advertisement needs authorizing: +[advertise auth](/quest/m2/processor/advertise-auth.md) scopes are prefix-only +today, and this quest extends them to the new shapes. Token patterns +(`moq-pattern`, `moq_auth::Claims`) already match suffixes and do not change. + +## Related + +- [Wildcard](/quest/m0/wildcard/README.md) - prefix-only advertisements and the service-prefix layout this extends +- [Cluster routing](/quest/m1/cluster-routing/README.md) - forwards announcements between relays, which must keep their shape diff --git a/quest/m2/archive-backward-timestamps.md b/quest/m2/archive-backward-timestamps.md deleted file mode 100644 index c5175e4c41a..00000000000 --- a/quest/m2/archive-backward-timestamps.md +++ /dev/null @@ -1,16 +0,0 @@ -# [XS] Archive refuses backward timestamps - -## Goal - -A resumed recording refuses a track whose timestamps go backward past the -recovered timeline, failing loud like the group-ID check, instead of writing -overlapping media time. The caller starts a new prefix. - -## Plan - -Check the first group's timestamp against the recovered track's last recorded -timestamp at enrollment, and test both a backward and a forward restart. - -## Required - -- [Archive](/quest/m1/archive/README.md) - the recovery this hardens ships with the line diff --git a/quest/m1/archive/browser.md b/quest/m2/archive-browser.md similarity index 91% rename from quest/m1/archive/browser.md rename to quest/m2/archive-browser.md index 520a5cb09e0..1a6d5bc935f 100644 --- a/quest/m1/archive/browser.md +++ b/quest/m2/archive-browser.md @@ -31,8 +31,10 @@ the supported drafts without duplicating transport dispatch or codecs here. Ship the contract in the `@moq/*` packages. A dashboard browser-to-HLS proof remains downstream (moq.pro) work. +Deferred to m2 in the 2026-09-30 audit: no named consumer; the native archive +lands first. + ## Required - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH support - -- [Recording writer](/quest/m1/archive/writer.md) +- [Archive](/quest/m1/archive/README.md) - the native writer, reader, and DVR contract this ports diff --git a/quest/m1/archive/paced-replay.md b/quest/m2/archive-paced-replay.md similarity index 86% rename from quest/m1/archive/paced-replay.md rename to quest/m2/archive-paced-replay.md index c17cd658e67..9286a610169 100644 --- a/quest/m1/archive/paced-replay.md +++ b/quest/m2/archive-paced-replay.md @@ -25,3 +25,9 @@ who joins late joins mid-replay. - Test with paused time: record, replay paced, and assert a plain subscriber gets every group in order at media pace, that a late subscriber starts at the current group, and that two tracks stay aligned. +- Deferred to m2 in the 2026-09-30 audit: no named consumer; FETCH replay + already serves DVR and HLS. + +## Required + +- [Recording reader](/quest/m1/archive/reader.md) - the FETCH reader this adds live publishing to diff --git a/quest/m2/audio-decode-mediacodec.md b/quest/m2/audio-decode-mediacodec.md index 936bc13a325..5158823f91d 100644 --- a/quest/m2/audio-decode-mediacodec.md +++ b/quest/m2/audio-decode-mediacodec.md @@ -25,8 +25,7 @@ behind a new optional audio `mediacodec` feature and the decode seam, on `target ## Required -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as +- [Mobile ownership](/quest/m1/mobile-ownership.md) - if Kotlin owns platform codecs, this backend is moot ## Related diff --git a/quest/m2/audio-decode-mediafoundation.md b/quest/m2/audio-decode-mediafoundation.md index 6fae6be4fae..e480e5b00ce 100644 --- a/quest/m2/audio-decode-mediafoundation.md +++ b/quest/m2/audio-decode-mediafoundation.md @@ -22,12 +22,6 @@ ones. Behind the decode seam as the first candidate on `target_os = - Verification runs on a Windows host; the per-PR CI only compiles the platform code (`just rs windows`). -## Required - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as - ## Related -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where the Windows run happens -- [Windows decoded frames](/quest/m1/obs-moq-video/decode-windows.md) - the OBS Windows line this feeds +- [Windows decoded frames](/quest/m2/obs-decode-windows.md) - the OBS Windows line this feeds diff --git a/quest/m2/audio-encode-mediacodec.md b/quest/m2/audio-encode-mediacodec.md index 7bb26674eaf..52ead7973e8 100644 --- a/quest/m2/audio-encode-mediacodec.md +++ b/quest/m2/audio-encode-mediacodec.md @@ -13,6 +13,9 @@ behind the `mediacodec` feature and the encode seam. - `audio/mp4a-latm` with `KEY_AAC_PROFILE` = LC. The catalog ASC is synthesized at construction per the encode seam, since `csd-0` only arrives with the first output buffer; assert the two match. +- MediaCodec pipelines output, which the one-packet-per-frame seam does not + allow yet: add a `flush` and a zero-or-more return, a change to + `Encoder::encode` that targets `dev`, unless the AudioToolbox quest already did. - Multichannel is device-dependent; probe the encoder's capabilities at open and refuse a layout it does not list. - Round-trip regression through the MediaCodec decoder; runtime proof on a @@ -20,6 +23,5 @@ behind the `mediacodec` feature and the encode seam. ## Required -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts +- [Mobile ownership](/quest/m1/mobile-ownership.md) - if Kotlin owns platform codecs, this backend is moot - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - the round-trip regression decodes through it diff --git a/quest/m2/audio-encode-mediafoundation.md b/quest/m2/audio-encode-mediafoundation.md index b1c3440f6bc..97b0d3b62b0 100644 --- a/quest/m2/audio-encode-mediafoundation.md +++ b/quest/m2/audio-encode-mediafoundation.md @@ -20,10 +20,4 @@ behind the encode seam on Windows. ## Required -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - the round-trip regression decodes through it - -## Related - -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where the Windows run happens diff --git a/quest/m2/audio-loss-recovery.md b/quest/m2/audio-loss-recovery.md deleted file mode 100644 index 9be8b40dc08..00000000000 --- a/quest/m2/audio-loss-recovery.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Decide a tested Opus loss-recovery policy - -## Goal - -Decide whether a concrete MoQ audio consumer benefits from in-band Opus FEC, -with a tested loss/latency policy before exposing any additive option on -`encode::Settings`. -This does not block 0.1. - -## Plan - -The old boolean supplied no expected-loss percentage and our decoder never -requested FEC recovery. Treat source loss, late-group abandonment, and DTX as -different cases. Define sequencing, expected loss, playout lookahead, recovery -versus concealment, and behavior when the next packet is unavailable. - -Use deterministic dropped-packet fixtures to prove redundancy is emitted and -used, compare audible quality and delay against concealment, and name the -transport scenario where it helps. End with a measured go/no-go and a small -additive policy if justified; do not reintroduce an enable flag tested only by -reading the codec's control value. Implementation fixtures belong in CI. - -Public API: no change during the study; any later policy must fit the extensible -audio settings. Existing wire compatibility must be demonstrated. - -## Related - -- [Audio quality](/quest/m0/audio-quality-harness/README.md) - quality and latency measurements diff --git a/quest/m2/audio-opus-backend.md b/quest/m2/audio-opus-backend.md index a981f0e0070..0a5ccf0e6fc 100644 --- a/quest/m2/audio-opus-backend.md +++ b/quest/m2/audio-opus-backend.md @@ -1,9 +1,10 @@ -# [M] Compare current Opus implementations +# [M] Compare Opus implementations and loss recovery ## Goal -Determine whether an optional newer Opus backend improves quality or CPU enough -to justify its build and maintenance cost while retaining the simple Rust path. +Determine whether an optional newer Opus backend improves quality, CPU, or +loss recovery enough to justify its build and maintenance cost while retaining +the simple Rust path, and settle a tested loss-recovery policy. ## Plan @@ -18,6 +19,24 @@ CPU, and package/toolchain cost. Keep native compilation optional and use the existing private backend seam; do not add another public configuration surface just to expose one implementation's controls. A no-go is a valid outcome. +### Loss recovery + +Decided in the 2026-09-30 audit: the loss-recovery policy study folds in here, +because the options depend on the backend. DRED and deep PLC need libopus 1.5+, +while the current 1.3.1 port only offers in-band LBRR FEC and classic +concealment. + +Decide whether a concrete MoQ audio consumer benefits from FEC, DRED, or deep +PLC over concealment. The old FEC boolean supplied no expected-loss percentage +and our decoder never requested FEC recovery. Treat source loss, late-group +abandonment, and DTX as different cases. Define sequencing, expected loss, +playout lookahead, recovery versus concealment, and behavior when the next +packet is unavailable. Use deterministic dropped-packet fixtures to prove +redundancy is emitted and used, compare audible quality and delay, and name +the transport scenario where it helps. Any resulting policy is small and +additive on the extensible audio settings; do not reintroduce an enable flag +tested only by reading the codec's control value. + Retain fixtures and repeatable measurements in the existing CI/nightly audio harness. Public API and wire: no change for the study; validate compatibility before a separately scoped backend implementation. diff --git a/quest/m2/av1-metadata.md b/quest/m2/av1-metadata.md index 475794e8dee..afc4bec8343 100644 --- a/quest/m2/av1-metadata.md +++ b/quest/m2/av1-metadata.md @@ -29,12 +29,8 @@ Preserve `metadata_type`, the payload bytes, and ordering within the temporal unit. Test HDR10+ T.35 metadata, timecode, an unknown metadata type, several OBUs in one temporal unit, and a byte-identical round trip. -## Required - -- [Metadata association contract](/quest/m2/sei/sei.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Related -- [SEI sidecars](/quest/m2/sei/README.md) - the H.26x contract this should +- [SEI sidecars](/quest/m2/sei.md) - the H.26x contract this should follow rather than duplicate -- [fMP4 emsg carriage](/quest/m1/emsg.md) - independent carriage of container metadata, not a prerequisite for codec extraction +- [fMP4 emsg carriage](/quest/m2/emsg.md) - independent carriage of container metadata, not a prerequisite for codec extraction diff --git a/quest/m2/bench-coverage.md b/quest/m2/bench-coverage.md new file mode 100644 index 00000000000..9e78d0cd71a --- /dev/null +++ b/quest/m2/bench-coverage.md @@ -0,0 +1,50 @@ +# [M] Benchmarks for patterns, stats, containers, catalog, and auth + +## Goal + +Hot paths that have no benchmark get Criterion targets, so CI tracks them: +`moq-pattern` path matching, the `moq-stats` producer per tick, `moq-mux` +container import and export per frame, `hang` catalog encode, decode, and +update, and `moq-auth` token verification. + +## Plan + +Deferred to m2 in the 2026-09-30 audit. The `moq-pattern` benchmark is the +one worth doing first, and could return to m1 as its own quest. + +- `moq-pattern`: matching swept over pattern count and path depth. Patterns + shipped as `rs/moq-pattern` and `js/pattern`, so the matcher gets one bench + here, not a second one elsewhere. +- `moq-stats` producer (folded in from the stats producer benchmark): measure + what one relay pays per stats tick to drain its registry and encode the + traffic tracks. #4299 keeps an idle path in every frame while the registry + holds its counters (about 430 B per idle path per plain frame), and nothing + measures that or the per-tick drain as held paths grow. Sweep held paths + (for example 100 to 50k) against tiers and the share of idle versus changed + paths. Report time and allocations per tick, and plain and compressed bytes + per frame the way `rs/moq-stats/benches/decode.rs` reports its table, + including the point where a plain frame nears its size cap. Drive the real + producer path (`process_slot`, the snapshot encoders) over a synthetic + `Registry`; a bench hook is fine if it stays out of the public API. This is + the moq-json snapshot encoder profile + [Binary delta stats](/quest/m2/stats-delta.md) gates on. `decode.rs` is not + in CI either; run both targets in the nightly benchmark smoke, as + `moq-net`'s are. +- `moq-mux`: fMP4/CMAF and Annex-B import and export over checked-in or + generated fixtures, with throughput in frames and bytes. Keep fixture + generation out of the timed region. +- `hang`: catalog encode and decode swept over rendition count, plus the + per-update cost a publisher pays. +- `moq-auth`: JWT verification per connection, swept over algorithm and claim + size. The in-band token path gets its bench with + [In-band token](/quest/m1/auth/token-in-band.md), not here. + +Anything that fans out gets a sweep over both axes. Name each target after +what it measures, so the CI comment reads without opening the file. + +Public API: none. Wire: none. + +## Related + +- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - tracks these targets on PRs and nightly +- [Binary delta stats](/quest/m2/stats-delta.md) - its gate needs the stats encode baseline this measures diff --git a/quest/m2/browser-media-qa-engines.md b/quest/m2/browser-media-qa-engines.md index 343d8cb478e..2cf1adce000 100644 --- a/quest/m2/browser-media-qa-engines.md +++ b/quest/m2/browser-media-qa-engines.md @@ -18,8 +18,10 @@ WebCodecs encode and decode, AudioWorklet, `MediaStreamTrackProcessor`, Neither Playwright Firefox nor Playwright WebKit ships WebTransport, and WebKit also lacks the WebCodecs encoder, so neither can publish and neither -can play over QUIC. What they can do is play over the WebSocket fallback, -which is the path a real Firefox viewer takes today. +can play over QUIC. What they can do is play over the WebSocket fallback. +Real Firefox does use WebTransport; only Playwright's build lacks it, so a +fallback run covers the player, not Firefox's transport path (see open PR +[#4460](https://github.com/moq-dev/moq/pull/4460)). - Split the harness's publisher and subscriber roles so an engine can take one side: a Chromium fixture with a Firefox or WebKit player over the @@ -34,4 +36,4 @@ which is the path a real Firefox viewer takes today. ## Related -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where an engine that will not run on the CI image runs +- [Firefox 155 WebTransport](/quest/m2/firefox-155-webtransport.md) - the real Firefox transport path, verified by hand diff --git a/quest/m1/perf/cache-shard.md b/quest/m2/cache-shard.md similarity index 90% rename from quest/m1/perf/cache-shard.md rename to quest/m2/cache-shard.md index 3be996a5ae1..65d7a28d554 100644 --- a/quest/m1/perf/cache-shard.md +++ b/quest/m2/cache-shard.md @@ -58,6 +58,11 @@ where available), relay CPU and RSS at the fanout shape via behavior covered by the existing cache tests plus new ones for the staleness bound. +Decided in the 2026-09-30 audit: moved to m2 because the contention is +unmeasured on noq. [Lock wait](/quest/m1/perf/lock-wait.md) decides it; take +this up only if that shows more than 1% contention on the pool line. + ## Related +- [Lock wait](/quest/m1/perf/lock-wait.md) - measures whether the pool line is contended enough to justify this - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - the remaining clock reads one layer down; a pool epoch driven by its per-turn timestamp is the way to drop the last per-frame read, and the model should drink from that cup rather than grow a second clock diff --git a/quest/m1/captions-cea.md b/quest/m2/captions-cea.md similarity index 92% rename from quest/m1/captions-cea.md rename to quest/m2/captions-cea.md index 909fa7e97b6..e7f3be5cde3 100644 --- a/quest/m1/captions-cea.md +++ b/quest/m2/captions-cea.md @@ -8,6 +8,8 @@ without extraction those broadcasts have no captions in MoQ at all. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + Parse the `user_data_registered_itu_t_t35` SEI payloads that carry CEA-708 (with 608 compatibility bytes inside) out of H.264 and H.265 access units at import, and publish the decoded cues as a `text` rendition beside the video. @@ -34,6 +36,6 @@ exists to prevent, so cover the ordering with a test rather than a comment. ## Related -- [SEI](/quest/m2/sei/README.md) - carries SEI byte-faithfully as a sidecar; if +- [SEI](/quest/m2/sei.md) - carries SEI byte-faithfully as a sidecar; if that line lands, this parser is a candidate to move onto it rather than walking the access unit itself diff --git a/quest/m2/capture-ergonomics.md b/quest/m2/capture-ergonomics.md deleted file mode 100644 index 0584416ba73..00000000000 --- a/quest/m2/capture-ergonomics.md +++ /dev/null @@ -1,27 +0,0 @@ -# [S] Plan capture ergonomics - -## Goal - -Two papercuts in the capture surface, none blocking but each visible the -first time someone hits it. - -This is a planning dispatch. Verify each current limitation against source, -then replace this quest with independently completable crop and audio mixing -quests. Each needs a chosen public API, ownership -boundary, supported/refused cases, and CI acceptance tests. Ask the maintainer -about unsettled crop coordinates and audio clock/mixing policy before coding. -Keep additions compatible with the settled main capture contracts. Identify any -published API break for a separate maintainer decision; independent format -validation already has its own quest. - -## Plan - -- **Region and crop capture.** No knob exists anywhere; `capture::Config` - carries source, device, width, height, and framerate. Cropping a region of a - display is the common screen-share case that currently requires capturing - the whole thing. -- **Mixing multiple audio devices.** One device, one track. A screen share - wanting microphone plus system audio has no way to say so, which is exactly - the combination the `System` source makes newly reachable. - Preserve exclusive AEC microphone ownership and define clock alignment - before sharing processed microphone input. diff --git a/quest/m2/capture-frame-buffers.md b/quest/m2/capture-frame-buffers.md deleted file mode 100644 index 156a3e5fe8d..00000000000 --- a/quest/m2/capture-frame-buffers.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] moq-video: X11 and Windows capture rebuild their frame buffers every tick - -## Goal - -Neither native screen-capture backend allocates a full-frame buffer per frame. -Steady-state capture reuses the same scratch memory and GDI objects. - -## Plan - -Both backends added in the native screen-capture work allocate the whole frame, -every frame, on the pump thread. - -`capture/window.rs`'s `snapshot` creates a memory DC, a compatible bitmap, and a -`vec![0u8; w * h * 4]` per call, then destroys them. At 1080p60 that is roughly -500 MB/s of allocation plus GDI object churn for pixels whose size never changes -while the stream is open. All three belong in `Capture`, built once at open: the -pump thread owns the struct, so the `!Send` handles are fine where they are. - -`capture/x11.rs`'s `PixelFormat::rgb` allocates a `w * h * 3` `Vec` and fills it -with three `push` calls per pixel, and `I420::from_rgb` then walks it again into -a third buffer. Take an `&mut Vec` the `Capture` owns and `clear()` it, so -the allocation happens once. - -Neither is a correctness bug, so this is a steady-state cost question: measure -before and after rather than assuming. The X11 half compiles on Linux CI; the -Windows half needs a Windows host (`just rs windows`). - -## Related - -- [X11 capture transport](/quest/m2/x11-capture-shm.md) - the larger X11 cost, in the same read path diff --git a/quest/m2/capture-wgc.md b/quest/m2/capture-wgc.md new file mode 100644 index 00000000000..80302d8254a --- /dev/null +++ b/quest/m2/capture-wgc.md @@ -0,0 +1,97 @@ +# [L] Windows.Graphics.Capture backend for display and window capture + +## Goal + +One Windows.Graphics.Capture (WGC) backend serves `Source::Display` and +`Source::Window` on Windows and honors `config.cursor` through +`IsCursorCaptureEnabled`. It replaces both current backends: DXGI Desktop +Duplication (`capture/desktopduplication.rs`, which ignores `config.cursor`) +and GDI window capture (`capture/window.rs`, whose `PrintWindow` runs on the +target's UI thread). Frames stay on the GPU as NV12 `Surface::Texture`. + +Out of scope: application capture and system audio, which stay in +[Windows capture parity](/quest/m2/capture-windows.md). WGC captures one +monitor or one window per item and has no per-process source, so it does not +answer app capture. + +## Plan + +Decided in planning (09-30): + +- **Replace, no fallback.** Delete `desktopduplication.rs` and the GDI capture + path. Keeping DD as a fallback means two backends for Windows builds that + are out of support anyway. +- **Mirror `capture/screencapture.rs`.** `CreateForMonitor` or + `CreateForWindow` (through `IGraphicsCaptureItemInterop`) builds the + `GraphicsCaptureItem`. Everything after that is shared: one session, a + free-threaded frame pool, a first frame to learn the size, and a guard that + closes the session on drop. `GraphicsCaptureItem.Closed` ends the stream. +- **GPU NV12 output.** Each BGRA pool frame goes through an + `ID3D11VideoProcessor` blit into an owned NV12 `d3d11::Texture` on the + capture device, so it can reach the Media Foundation hardware encoder + zero-copy, just as camera frames do. Pool frames are recycled, so copying out + is required. Generalize the existing NV12 `Scaler` in `frame.rs` to take BGRA + input instead of writing a second processor. openh264 already downloads a + `Texture` through `to_i420`. The existing scaler copies its input color + space to its output, which is right for resizing but wrong for converting. + Set the RGB range and the output YCbCr matrix explicitly so they match what + the encoder signals. Otherwise HD frames get converted with BT.601 while the + stream advertises BT.709. NV12 also needs even dimensions, and a window's + size is often odd. Keep the BGRA pool at its native size, and crop the NV12 + texture and the stream geometry down to even, as both current backends do. +- **The `windows` crate directly** (0.62, already a public re-export), not + `windows-capture` or another wrapper. We need our own D3D11 device, so it can + be shared with the encoder, and one `windows` version. This adds WinRT + features (`Graphics_Capture`, `Graphics_DirectX_Direct3D11`, + `Win32_System_WinRT_Graphics_Capture`, `Win32_System_WinRT_Direct3D11`, + `Win32_Graphics_Dwm`, and whatever else they pull in). Adding features is + additive. +- **Minimum Windows 10 2004 (build 19041).** That is where + `IsCursorCaptureEnabled` appears. Refuse loud below it with + `Error::Unsupported`, never silently drop the cursor. Set + `IsBorderRequired = false` where the property exists (build 20348+), but + request `GraphicsCaptureAccessKind::Borderless` first: without that access, + setting the property can fail with `E_ACCESSDENIED`. If access is denied, + keep the border rather than failing the capture. Older builds keep the + yellow capture border. Document the minimum in + `doc/lib/rs/moq-video.md`. +- **Resize ends the stream.** When `ContentSize` changes, debounce with + `Settle` and then return `Read::Done` so the caller reopens, the way + `window.rs` does today. The encoder's geometry is fixed. This also removes + DD's stale-size bug, where it keeps converting at the old width and height + after a mode change. +- **Displays enumerate across every adapter.** Use `EnumDisplayMonitors` + rather than adapter 0's DXGI outputs, which miss monitors attached to the + other GPU on hybrid laptops. Keep the user-visible `display:N` ids and names. +- **Windows skip DWM-cloaked entries.** Filter on `DWMWA_CLOAKED` (hidden UWP + windows and other virtual desktops), and size windows from + `DWMWA_EXTENDED_FRAME_BOUNDS` rather than `GetWindowRect`, which includes the + invisible borders. Enumeration never opens a capture: `ContentSize` belongs + to a frame, so it is only used for resize detection on the selected + capture. Keep the `window:{hwnd}` ids. + +Public API: no Rust signature changes. `config.cursor` starts working for +displays. Windows builds older than 19041 go from working to refused. + +Verification: Windows CI only runs `cargo check`, and hosted runners have no +real desktop. Add `#[ignore]` display and window tests, run them by hand on +real Windows hardware, and record this checklist in the PR: + +- cursor on and off +- an odd-sized window +- color on an SD and an HD source, from BGRA through NV12 to the encoder, on + both the Media Foundation path and the openh264 readback path +- window resize, close, and minimize +- multi-monitor +- one Windows 10 2004+ machine, showing that the yellow border appears there + +Fix the docs this makes stale in the same PR: `rs/moq-video/README.md`, +`doc/lib/rs/moq-video.md`, `doc/bin/cli.md`, the `capture/mod.rs` module doc, +the Cargo feature comment, and the `frame.rs` docs on which producers make a +`Texture`. + +## Related + +- [Windows capture parity](/quest/m2/capture-windows.md) - app capture and system audio, which WGC does not answer +- [X11 capture transport](/quest/m2/x11-capture-shm.md) - owns the X11 frame-buffer reuse; the GDI half disappears with `window.rs` +- [Direct3D11 render import](/quest/m2/render-d3d11.md) - the other end of keeping Windows frames on the GPU diff --git a/quest/m2/capture-windows.md b/quest/m2/capture-windows.md index c52a3ae046b..5e3f4a14043 100644 --- a/quest/m2/capture-windows.md +++ b/quest/m2/capture-windows.md @@ -1,18 +1,13 @@ -# [L] Windows capture parity +# [M] Windows capture parity ## Goal -App capture, system audio, and whole-screen cursor capture work on Windows. -Window capture landed with the native screen capture work; these are what it -left behind. +App capture and system audio work on Windows. Display and window capture, +including the cursor, move to +[Windows.Graphics.Capture](/quest/m2/capture-wgc.md). ## Plan -Window capture and its cursor now exist: `capture/window.rs` enumerates -top-level windows, captures the selected one through GDI, composites the cursor -when `config.cursor` asks for it, and surfaces the ids through `moq devices`. -What remains: - - **Applications** (every window of a process, including ones that open later) are still `Unsupported` outside macOS, where `SCShareableContent` gives it almost free. Windows has no direct equivalent, so this needs per-window @@ -22,21 +17,13 @@ What remains: exists but is macOS-only and returns `Unsupported` elsewhere. Unlike macOS this does not go through the screen-capture API, so it is an independent path and does not inherit the Screen Recording permission coupling. -- **The cursor on whole-screen capture** is still missing: the Desktop - Duplication backend handles neither `PointerShape` nor `PointerPosition`, so - `config.cursor` controls nothing there. Window capture and both other - platforms honor it, which makes this the odd one out. -Note that the window capture that landed is GDI. It now reaches -DirectComposition content through `PrintWindow(PW_RENDERFULLCONTENT)`, but that -call runs on the target window's UI thread, so the backend probes the window for -responsiveness every frame and skips one that is hung, and it still round-trips -BGRA through the CPU on its way to I420. Windows.Graphics.Capture has neither -coupling and delivers `IDirect3DSurface` frames the existing D3D11 path could -take zero-copy. WGC would also answer app capture and the cursor, so weigh -these three against doing that once. +WGC does not answer app capture. It captures one monitor or one window per +item and has no per-process source, so the per-window-composition or +window-only decision still stands after that backend lands. ## Related +- [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - display and window capture with the cursor, which this quest no longer owns - [Linux capture parity](/quest/m2/capture-linux.md) - the same gaps, through the portal and PipeWire diff --git a/quest/m2/carrier-voice/README.md b/quest/m2/carrier-voice/README.md deleted file mode 100644 index 4be5cad6d13..00000000000 --- a/quest/m2/carrier-voice/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Programmable carrier voice - -## Goal - -Determine whether MoQ should be the programmable call fabric between developer -clients, carrier gateways, and auxiliary call services. The design covers -developer-to-gateway and gateway-to-gateway calls; the first lab proves only a -developer client calling a SIP endpoint. - -Stock phones remain on IMS/SIP/RTP. MoQ begins at a carrier-controlled gateway -or developer client, where publish/subscribe can make a live call available to -recorders, agents, transcription, translation, and conferencing without a -bespoke media fork for each service. - -## Plan - -- Use one role-based call model for both topologies. A developer client and a - SIP/IMS gateway are authenticated call legs; internal gateway-to-gateway - transport is the same protocol with two gateway legs, not a second design. -- Calling is an application protocol carried by ordinary - [MOQT](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/). A leg - publishes a short-lived offer and call-state objects plus its Opus audio; the - other leg subscribes and publishes its own state and audio. - `PUBLISH_NAMESPACE` and `SUBSCRIBE_NAMESPACE` provide discovery only. Do not - add call semantics to MOQT or treat namespace publication itself as ringing. -- Scope offers below an opaque line and random call id, never a raw phone - number or caller-asserted identity. The E.164 destination is authenticated - offer metadata, the usable source line comes from the credential, and the - gateway is authoritative for routing and telephone state. -- Offers are live session state, not an offline inbox. Withdrawing the offer or - losing its publisher cancels an unanswered call. Durable notifications, - voicemail, retries after disconnect, and webhook delivery remain separate - product surfaces. -- Keep IMS registration, native handset integration, roaming, emergency - calling, lawful intercept, number provisioning, SMS/MMS/RCS, and carrier - compliance outside the experiment. The SIP adapter is the boundary to that - world. - -## Required - -- [Call fabric protocol](/quest/m2/carrier-voice/protocol.md) - versioned - namespaces, roles, state transitions, authorization, and both topologies -- [SIP call origination](/quest/m2/carrier-voice/sip-originate.md) - the shared - SIP stack originates one outbound audio call for the lab -- [Developer-to-SIP proof](/quest/m2/carrier-voice/proof.md) - a developer - publishes a call that reaches a SIP endpoint, with a passive second consumer -- [Carrier-voice verdict](/quest/m2/carrier-voice/verdict.md) - compare MoQ, - RTP, and RoQ, then record the smallest justified product surface - -## Related - -- [SIP media stack](/quest/m2/sip-stack.md) - the telephone-network adapter - this lab extends; the inbound-call product built on it is moq.pro - (downstream) work -- `@moq/room` - conferencing may eventually reuse its participant model, but is - not required by this experiment diff --git a/quest/m2/carrier-voice/proof.md b/quest/m2/carrier-voice/proof.md deleted file mode 100644 index df3b8b7f90d..00000000000 --- a/quest/m2/carrier-voice/proof.md +++ /dev/null @@ -1,35 +0,0 @@ -# [L] Developer-to-SIP proof - -## Goal - -A reproducible lab call starts when a developer client publishes a MoQ offer, -rings and answers at a real SIP endpoint, and carries bidirectional Opus audio. -A recorder or mock agent subscribes to the live call without either endpoint -creating a separate media connection. - -## Plan - -- Build the smallest standalone gateway beside the protocol and `moq-sip`: - subscribe to the configured line prefix, authorize the offer, originate the - SIP dialog, publish authoritative call state and received audio, then - subscribe to the developer leg and send that audio as RTP. Do not wire the - experiment into the moq.pro (downstream) edge or dashboard. -- Drive it with a Rust or TypeScript developer client and a scripted SIP - endpoint or interoperable softphone. One command starts the relay, gateway, - endpoint, client, and auxiliary subscriber; retained artifacts include state - transitions, synchronized audio timestamps, and packet captures. -- Prove happy-path ringing/answer/audio and the failure paths that define the - contract: rejection, caller cancellation, remote hangup, publisher loss, - unauthorized line use, spoofed source identity, and an auxiliary subscriber - without recording permission. -- Keep the second consumer passive so the proof measures MoQ's programmable - fanout rather than designing conferencing. The gateway-to-gateway topology - receives an architecture-level walkthrough using the same roles and wire, - but no second gateway implementation. - -## Required - -- [Call fabric protocol](/quest/m2/carrier-voice/protocol.md) - fixes the wire, - authority, and lifecycle the lab implements -- [SIP call origination](/quest/m2/carrier-voice/sip-originate.md) - supplies - the outbound telephone leg diff --git a/quest/m2/carrier-voice/protocol.md b/quest/m2/carrier-voice/protocol.md deleted file mode 100644 index 1ea89aaa437..00000000000 --- a/quest/m2/carrier-voice/protocol.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Call fabric protocol - -## Goal - -A versioned experimental protocol defines how authenticated call legs offer, -accept, carry, and end an audio call over ordinary MoQ. It describes both -developer-to-gateway and gateway-to-gateway calls without exposing phone -numbers in namespaces or trusting caller-supplied identity. - -## Plan - -- Define a project-scoped line inbox and opaque call/leg hierarchy. The shape - starts at `voice/lines//calls//legs/`; each leg - publishes only its own broadcast, containing an Opus audio track and a - versioned state track. The exact wire lives beside the Rust and TypeScript - implementations, not only in this quest. -- The first caller-leg state is an offer. For outbound telephone calls it - carries the E.164 destination and requested capabilities. Gateway-authored - states report routing, ringing, answer, rejection, and termination. Define - ordering, duplicate/replay handling, terminal-state behavior, cancellation - on withdrawal, and simultaneous teardown so reconnects cannot resurrect a - call. -- Authorization assigns roles rather than trusting path text: a caller may - publish its leg and request use of a configured line, the carrier gateway - validates that line and publishes authoritative telephone state, the remote - leg publishes its media, and an auxiliary consumer receives a least-privilege - subscription to the call. A source number is derived from the credential and - line configuration, never accepted from offer metadata. -- Use standard namespace discovery to notice new calls under an authorized - line prefix. Do not extend MOQT. Bound offer lifetime, state-object size, - call count, and per-line concurrency, and specify what is observable to a - relay even when media objects are encrypted. -- Include sequence diagrams for developer-to-SIP and gateway-to-gateway calls, - plus a threat model covering number enumeration, caller-ID spoofing, path - injection, unauthorized recording, replay, abandoned offers, and confused - deputy use of a carrier trunk. -- Land shared schema/types and state-machine tests in this repository. Keep - HTTP/webhooks out of the wire; the verdict may recommend them later as a - durable product-control surface without changing the live media model. - -## Related - -- [SIP call origination](/quest/m2/carrier-voice/sip-originate.md) - adapts the - telephone leg to the protocol diff --git a/quest/m2/carrier-voice/sip-originate.md b/quest/m2/carrier-voice/sip-originate.md deleted file mode 100644 index c973fbbac2a..00000000000 --- a/quest/m2/carrier-voice/sip-originate.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] SIP call origination - -## Goal - -The `moq-sip` stack can originate one audio-only SIP call and expose the -resulting dialog as Opus frames in and out. The first consumer is the -programmable carrier-voice lab, not a production outbound-calling product. - -## Plan - -- Extend the selected SIP stack rather than building a second SIP adapter. The - embedder supplies the request URI, asserted line identity, credentials, and - Opus source/sink; the crate owns INVITE transactions, SDP offer/answer, - provisional and final responses, RTP/SRTP, cancellation, and BYE. -- Reuse the inbound stack's Opus/G.711 negotiation, transcoding, RTP clock - normalization, and teardown. Exercise ringing, answer, rejection, caller - cancellation, remote hangup, and timeout against a real softphone or test - PBX. -- Keep PSTN routing, number ownership, caller-ID policy, emergency calling, - registrar support, DTMF, billing, and production trunk credentials outside - this quest. The lab gateway decides whether an authenticated caller may use - a line before it asks `moq-sip` to originate. - -## Required - -- [SIP media stack](/quest/m2/sip-stack.md) - origination extends the same - dialog, codec, and RTP implementation - -## Related - -- [Developer-to-SIP proof](/quest/m2/carrier-voice/proof.md) - the first - end-to-end consumer diff --git a/quest/m2/carrier-voice/verdict.md b/quest/m2/carrier-voice/verdict.md deleted file mode 100644 index f80046a1876..00000000000 --- a/quest/m2/carrier-voice/verdict.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Carrier-voice verdict - -## Goal - -A measured go/no-go verdict decides whether MoQ earns a maintained role in -programmable carrier voice, and if so whether that role is developer-facing, -an internal gateway fabric, or both. An inconclusive result creates no product -commitment. - -## Plan - -- Replay the same Opus source through direct RTP, the MoQ lab path, and - [RTP over QUIC](https://datatracker.ietf.org/doc/draft-ietf-avtcore-rtp-over-quic/) - (RoQ). Its current Internet-Draft is expired prior art, not an assumed - adoption target: use a credible implementation if one remains runnable; - otherwise record why that arm cannot support a product decision instead of - building a second production stack just for the comparison. -- Use fixed clean, constrained-cellular, random-loss, burst-loss, and simulated - Wi-Fi/cellular path-change profiles. Record call setup time, one-way audio - latency and jitter, late/lost frames, recovery gaps, wire overhead, gateway - CPU, and connection continuity. Keep codec, packetization, source audio, - network trace, and hardware fixed across arms. -- Measure the proposed advantage directly: attach the auxiliary subscriber and - report its incremental setup work, latency, bandwidth, and gateway CPU. Also - document the equivalent RTP media-fork implementation so "programmable" is - compared against a real alternative rather than asserted. -- A go requires the full call lifecycle and mobility profiles to complete - without a protocol workaround, and MoQ's p99 one-way latency to stay within - 50 ms of direct RTP while the auxiliary subscriber remains an ordinary - authorized subscription. Treat the threshold as a rejection bound, not a - claim that a 50 ms regression is desirable. -- The verdict separately answers: whether in-band MoQ call control is simpler - than HTTP plus media streams, whether QUIC path migration helps in the - implementations we can actually ship, whether object overhead is acceptable - for 20 ms audio, and whether gateway-to-gateway transport adds value beyond - the developer-facing API. Recommend only the smallest surface supported by - the evidence and create implementation quests only for that surface. -- The conventional inbound SIP gateway product is moq.pro (downstream) work - and remains the standing telephone path regardless of this verdict. - -## Required - -- [Developer-to-SIP proof](/quest/m2/carrier-voice/proof.md) - provides the - working MoQ path and reproducible harness diff --git a/quest/m2/catalog-tracks.md b/quest/m2/catalog-tracks.md index 4726ec7c408..d301e2dd904 100644 --- a/quest/m2/catalog-tracks.md +++ b/quest/m2/catalog-tracks.md @@ -2,42 +2,32 @@ ## Goal -Choose how a catalog describes a track over its lifetime so live playback and -recorded playback do not guess which configuration applies to a media group. -Explore immutable track definitions as an alternative to correlating catalog -updates with groups. This is independent of DVR and does not gate archives. +A track's catalog definition never changes for its name, so live and recorded +playback never guess which configuration applies to a group. A publisher whose +track configuration changes either refuses the change or publishes it under a +new track name or a new broadcast epoch. This is independent of DVR and does +not gate archives. ## Plan -There is no explicit catalog-update-to-group binding. Timestamps alone do not -establish one. Audit publishers, consumers, and catalog composition in Rust and -JS to identify which track properties change today and why: codec/config bytes, -resolution, audio layout, rendition metadata, and broadcast references. - -Compare two approaches with concrete publish and playback examples: - -- Make each track definition immutable for its identity. A configuration change - creates a new track identity instead of changing the meaning of existing - groups. This is the preferred direction to investigate, not a settled API. -- Keep mutable definitions with an explicit configuration identity or update - boundary that groups can reference. Measure the protocol and lifecycle cost - against immutable definitions rather than assuming version binding is needed. - -Distinguish immutable track definitions from a completely immutable catalog. -Decide whether catalogs may add/remove tracks or change presentation metadata, -what happens to removed track identities, and whether a name can be reused. -Cover codec changes, rendition switches, reconnects, late joiners, reordered -catalog/media delivery, and readers seeking older groups. Evaluate what catalog -state must remain discoverable when media outlives the publishing session; -retaining snapshots alone cannot establish which configuration a group uses. - -Present the recommendation and migration costs for maintainer agreement before -changing public APIs or wire semantics. Produce focused implementation quests -for the chosen design, including Rust/JS and binding synchronization, HLS/watch -behavior, draft changes, and CI regression coverage. Target any published API -break at dev. Do not add an archive-only version index or change DVR retention -as a substitute for deciding track identity. +Decided in the 2026-09-30 audit: track identity is immutable. Mutable +definitions with a configuration identity that groups reference (the old +option 2) are out, because they contradict the rule that a track name always +means the same content, and MoQ has no ETag-style invalidation. + +Audit publishers in Rust and JS for the properties that change mid-track +today (codec/config bytes, resolution, audio layout, rendition metadata) and +make each one either refuse the change or mint a new identity: a new track +name through a [catalog alias](/quest/m1/catalog-track-alias.md) when the +catalog can keep both, or a new [broadcast epoch](/quest/m1/broadcast-epoch/README.md) +when the whole broadcast restarts. The catalog may still add and remove +tracks; a removed name is never reused for different content. + +Cover codec changes, rendition switches, reconnects, and late joiners in Rust, +JS, and HLS/watch tests. Target any published API break at `dev`. ## Related -- [Archive](/quest/m1/archive/README.md) - storage and replay consume the eventual identity contract +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - lets a catalog list a new track name for a changed rendition +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a restart is a new epoch rather than a changed track +- [Archive](/quest/m1/archive/README.md) - storage and replay consume the identity contract diff --git a/quest/m1/closure-counters.md b/quest/m2/closure-counters.md similarity index 92% rename from quest/m1/closure-counters.md rename to quest/m2/closure-counters.md index 7d209f9b90b..347c37f708d 100644 --- a/quest/m1/closure-counters.md +++ b/quest/m2/closure-counters.md @@ -9,6 +9,8 @@ explicit fresh segment. The rule is documented as a consumer-facing contract. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer. + The stickiness fix ([moq#3625](https://github.com/moq-dev/moq/pull/3625)) keeps a departed node's last `Traffic` contribution and drops `Presence` immediately. Its review raised an open P2: retiring the gauges advances the @@ -26,8 +28,3 @@ Settle which counters must be monotonic and over what lifetime, and whether the fresh-segment contract already permits a per-node closure reset or only a cumulative traffic regression. The answer is a consumer-facing contract, so document it in `moq-stats` rather than leaving it as an aggregate detail. - -## Related - -- [Client stats](/quest/m1/qos/stats/README.md) - publishes the same counters - to consumers diff --git a/quest/m2/color-catalog.md b/quest/m2/color-catalog.md new file mode 100644 index 00000000000..15318849d29 --- /dev/null +++ b/quest/m2/color-catalog.md @@ -0,0 +1,56 @@ +# [M] Catalog colour model + +## Goal + +The Hang catalog describes a video rendition's colour: primaries, transfer +characteristics, matrix coefficients, range, and the HDR10 mastering display and +content light levels. A renderer can set up its pipeline from the catalog +instead of guessing or reparsing the bitstream. + +## Plan + +Deferred to m2 in the 2026-09-30 audit: no renderer consumes colour today, so +the model waits for one. Encoder colour correctness stays in m1 as +[Encoder colour](/quest/m1/color-model.md). + +`rs/hang/src/catalog/video/mod.rs` has carried a bare `// TODO color space` since +the config was written. Two codecs already expose colour per their own syntax: +`VP9` carries primaries, transfer characteristics, matrix coefficients, and +range inside its codec string, and `AV1` has the same fields, which +`rs/moq-mux/src/codec/av1/import.rs` fills from the sequence header. They only +round-trip through muxers (the fMP4 exporter writes VP9's into `vpcC`); no +renderer consumes either, H.264 and H.265 have no equivalent, and there is no HDR10, +mastering display, or content light handling in `rs/` or `js/` at all. So an +HDR broadcast is delivered today and rendered as if it were SDR, whatever the +source signalled. + +Model the codec-neutral properties rather than one codec's syntax, so H.264 and +H.265 VUI, AV1 colour config, and a container's `colr` box all populate the same +fields. Generalize the existing VP9 and AV1 fields into that model rather than +adding a second colour source beside them: the codec-specific fields keep their +wire meaning (the VP9 codec string is defined by its spec) and feed the neutral +fields at import, so a renderer reads one place. Fill them at import from +whichever source the rendition provides, and emit them on export. + +Settle the precedence before adding the fields, because these sources disagree +in real files and a renderer must not see a different answer per import path. +Prefer the bitstream over the container: VUI and the AV1 colour config are what +the encoder actually signalled and travel with the elementary stream, while a +`colr` box is added by a muxer that may be wrong or stale. Record which source +won so a conflict is diagnosable rather than invisible, and treat an +unspecified value as absent rather than as a signalled default, so a partial +container box does not override a complete bitstream. + +Static display properties belong here rather than in a timed track, which is +also where the HDR10 metadata that lives in H.26x SEI should land once it can be +read. That is the one seam with the SEI line, and it runs in one direction: +this quest gives display metadata a home, and does not depend on SEI work. + +Test each source of truth in isolation, a source that signals nothing, a +conflict between VUI and container resolving to the bitstream, a container box +that fills a gap the bitstream left unspecified, and an SDR round trip that +stays byte-identical. + +## Related + +- [Encoder colour](/quest/m1/color-model.md) - encoders signal the colour they actually produce diff --git a/quest/m2/cpp-vcpkg.md b/quest/m2/cpp-vcpkg.md index 36ffc7427f0..646839fbbe3 100644 --- a/quest/m2/cpp-vcpkg.md +++ b/quest/m2/cpp-vcpkg.md @@ -30,4 +30,4 @@ CI on Windows, macOS, and Linux. ## Related -- [Conan remote](/quest/m2/cpp-conan.md) - the same tarball through Conan +- [Conan remote](/quest/m3/cpp-conan.md) - the same tarball through Conan diff --git a/quest/m1/emsg.md b/quest/m2/emsg.md similarity index 93% rename from quest/m1/emsg.md rename to quest/m2/emsg.md index 505d9c3f7b4..77af76c5813 100644 --- a/quest/m1/emsg.md +++ b/quest/m2/emsg.md @@ -13,6 +13,8 @@ it rather than restating it. Deferred SEI extraction is not a prerequisite. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + The shared contract, recorded here and mirrored in the Hang draft: - Publish an event as soon as it is received, on its own group sequence; never @@ -55,8 +57,8 @@ byte-identical. ## Related -- [ID3 catalog section](/quest/m1/id3.md) - gives one payload type carried here a - typed contract - [AV1 metadata OBUs](/quest/m2/av1-metadata.md) - the same silent drop in a different layer -- [FLV script tags](/quest/m1/flv-script.md) - likewise +- [ID3 catalog section](/quest/m2/id3.md) - gives one payload type carried here a + typed contract +- [FLV script tags](/quest/m2/flv-script.md) - likewise diff --git a/quest/m2/flate.md b/quest/m2/flate.md new file mode 100644 index 00000000000..04d30073a51 --- /dev/null +++ b/quest/m2/flate.md @@ -0,0 +1,40 @@ +# [M] Flate tracks in every binding + +## Goal + +Opaque tracks, compressed per group or not, are published and consumed the +same way from every language, not only Rust and JS, and the bytes on the wire +are identical across all of them. A track published from a wrapper decodes in +the browser with `@moq/flate` and vice versa. + +## Plan + +Decided in the 2026-09-30 audit: collapse the line into this quest and follow +the `json` namespace pattern that [#4526](https://github.com/moq-dev/moq/pull/4526) +sets, rather than the per-wrapper siblings of the old bindings quest. + +`moq-flate` and `@moq/flate` absorb `moq-binary`'s snapshot and stream modes +in moq-binary's fold into moq-flate ([#4425](https://github.com/moq-dev/moq/pull/4425), on `dev`), so the crate +already owns the per-group window a caller could otherwise desynchronize. +Bind those track modes, not the bare codec: a `frame()` call across the FFI +boundary invites the window desync the track modes exist to prevent. + +#4526 removes moq-ffi's `publish_binary_*` and adds `MoqFlate*Producer::new` +constructed from a track producer, as `json` does. What remains: + +- moq-ffi has no consume side for flate tracks. Add consumers mirroring the + `json` ones so each wrapper can read what it writes. +- Each wrapper (Python, Swift, Kotlin, Go, Dart) gains a `flate` namespace in + the same place and shape as its `json` one. +- Document in `doc/lib/{py,swift,kt,go,dart}` beside the JSON entry. +- Tests: a round trip in each wrapper that has tests, and one cross-language + check that a wrapper-published group decodes with `@moq/flate`. Run + `just test interop --all`. + +Public API: additive on top of #4526. Wire, catalog, and relay: none. +Compression stays invisible to `moq-net`; a compressed track is announced, +routed, and cached like any other. + +## Required + +- [JSON](/quest/m1/ffi-shape/json.md) - sets the `json` and `flate` namespace pattern this follows diff --git a/quest/m2/flate/README.md b/quest/m2/flate/README.md deleted file mode 100644 index d685a057103..00000000000 --- a/quest/m2/flate/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Compressed tracks - -## Goal - -Opaque tracks, compressed per group or not, are published and consumed the -same way from every language, not only Rust and JS, and the bytes on the wire -are identical across all of them. - -## Plan - -`moq-flate` and `@moq/flate` own the opaque snapshot and stream modes, so the -crate already owns the per-group window a caller could otherwise desynchronize. The -track wrapper this line once planned was dropped for that reason. What -remains is reaching those tracks from the hand-written binding wrappers. - -No wire, catalog, or relay impact. Compression stays invisible to `moq-net`; -a compressed track is announced, routed, and cached like any other. - -## Required - -- [Bindings](/quest/m2/flate/bindings.md) - the hand-written wrappers expose flate tracks diff --git a/quest/m2/flate/bindings.md b/quest/m2/flate/bindings.md deleted file mode 100644 index 13c3c21db82..00000000000 --- a/quest/m2/flate/bindings.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Flate bindings - -## Goal - -The hand-written wrappers (Python, Swift, Kotlin, Go, Dart) expose flate -tracks, the snapshot and stream opaque tracks moq-ffi already generates, in -their own idiom beside the JSON entry. A track published from a wrapper -decodes in the browser with `@moq/flate` and vice versa. - -## Plan - -moq-ffi publishes opaque tracks today (`publish_flate_snapshot` and -`publish_flate_stream`). Only the generated bindings reach them; no wrapper does. This quest binds the existing -track modes, not the bare codec: a `frame()` call across the FFI boundary -invites the window desync the track modes exist to prevent. - -- moq-ffi has no consume side for these tracks. Add it next to the JSON - consumers so each wrapper can read what it writes. -- Wrappers per the Cross-Package Sync table: `go/wrapper/json.go`, - `py/moq-rs/moq/{publish,subscribe}.py`, `swift/Sources/Moq/Json.swift`, - `kt/moq`'s `Json.kt` with its `Aliases.kt` re-exports, and - `dart/moq/lib/src/aliases.dart` each gain a flate sibling. If - [FFI shape](/quest/m1/ffi-shape/README.md) has landed, follow its `flate` - namespace instead. -- Document in `doc/lib/{py,swift,kt,go,dart}` beside the JSON entry. -- Tests: a round trip in each wrapper that has tests, and one cross-language - check that a wrapper-published group decodes with `@moq/flate`. Run - `just test interop --all`. - -Public API: additive on moq-ffi and every wrapper. Wire: none. diff --git a/quest/m1/flv-script.md b/quest/m2/flv-script.md similarity index 82% rename from quest/m1/flv-script.md rename to quest/m2/flv-script.md index 27dc2919cd2..0d90021f9c3 100644 --- a/quest/m1/flv-script.md +++ b/quest/m2/flv-script.md @@ -7,6 +7,8 @@ FLV script tags survive RTMP and FLV import instead of being discarded, so ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + `rs/moq-mux/src/container/flv/import.rs` matches `TAG_SCRIPT => {}` and moves on, which drops every AMF data message an encoder sends. `onMetaData` is the one every RTMP publisher emits, and applications routinely push their own cues @@ -15,7 +17,7 @@ through the same channel. Carry raw tag payloads without decoding AMF into a fixed vocabulary. Publish when received on independently sequenced metadata groups, with event time on the broadcast clock and source placement per the contract -[emsg](/quest/m1/emsg.md) settles. Tags before media +[emsg](/quest/m2/emsg.md) settles. Tags before media are delivered immediately and retain explicit pre-media placement; audio-only and script-only input do not require a dummy video rendition. Where `onMetaData` duplicates something the catalog already models (dimensions, @@ -26,12 +28,6 @@ Export reproduces the tags on the FLV path. Test `onMetaData`, an application message with a custom name, AMF0 and AMF3 payloads, a tag before the first media tag, and a byte-identical round trip. -## Required - -- [fMP4 emsg](/quest/m1/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Related -- [fMP4 emsg carriage](/quest/m1/emsg.md) - the same silent drop in a different - layer - [AV1 metadata OBUs](/quest/m2/av1-metadata.md) - likewise diff --git a/quest/m2/gop-overhead.md b/quest/m2/gop-overhead.md index 9c9a8649b37..e19576e6d0e 100644 --- a/quest/m2/gop-overhead.md +++ b/quest/m2/gop-overhead.md @@ -36,3 +36,7 @@ this quest. ## Closes - [#2284](https://github.com/moq-dev/moq/issues/2284) - close this issue when the quest finishes + +## Related + +- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - refresh encoding is the flat-bitrate alternative this verdict prices diff --git a/quest/m1/id3.md b/quest/m2/id3.md similarity index 87% rename from quest/m1/id3.md rename to quest/m2/id3.md index 4d5f1d019f2..dcec002c744 100644 --- a/quest/m1/id3.md +++ b/quest/m2/id3.md @@ -10,8 +10,10 @@ stream. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + Define the catalog section and frame contract for complete ID3 tags on the -shared event contract [emsg](/quest/m1/emsg.md) settles. Publish tags when +shared event contract [emsg](/quest/m2/emsg.md) settles. Publish tags when received on independently sequenced groups, with their presentation time on the broadcast clock and an optional association to the program's rendition. ID3-only programs need no artificial media owner. Carry original tag bytes, @@ -35,11 +37,7 @@ large tags spanning PES packets, timestamp wrap, discontinuity, and an ID3-only program. Include non-ID3 and malformed stream type `0x15` fixtures that remain generic. -## Required - -- [fMP4 emsg](/quest/m1/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Related -- [SEI sidecars](/quest/m2/sei/README.md) - the separate codec metadata +- [SEI sidecars](/quest/m2/sei.md) - the separate codec metadata contract diff --git a/quest/m2/ietf-cluster-peers.md b/quest/m2/ietf-cluster-peers.md new file mode 100644 index 00000000000..24c9d708499 --- /dev/null +++ b/quest/m2/ietf-cluster-peers.md @@ -0,0 +1,32 @@ +# [L] moq-transport cluster peers + +## Goal + +A moq-transport relay can join a cluster as a peer again, through an +extended `draft-lcurley-moq-cluster`, and never splices one pool member's +content onto another's. + +## Plan + +Replaces the wildcard line's "Cluster origin reply" quest. Until this lands, +moq-transport peers are plain clients +([moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md)). + +The extension must carry what a lite cluster link carries by then: + +- The serving origin in the reply, mirroring lite-07's SUBSCRIBE_OK and + FETCH_OK Origin, so a downstream stitches failover on the member serving the + path rather than the advertisement's first Hop ID. The draft's "Several + Publishers of One Namespace" section changes with it. +- Whatever the [cluster routing line](/quest/m1/cluster-routing/README.md) + settles for topology and selection, since cluster links are lite-only there. + +Test: two workers behind a pool relay behind a moq-transport downstream relay; +killing the serving worker ends the downstream subscription rather than +splicing the survivor's objects. + +Wire: extends `draft-lcurley-moq-cluster`, updated in the same PR. + +## Required + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - settles what a cluster link carries diff --git a/quest/m2/intra-refresh/README.md b/quest/m2/intra-refresh/README.md index 3bfb94cd117..c606b28fe0e 100644 --- a/quest/m2/intra-refresh/README.md +++ b/quest/m2/intra-refresh/README.md @@ -5,9 +5,14 @@ Video encoded with periodic intra refresh has no keyframes. Each frame refreshes a stripe of the picture, so a decoder that starts at the beginning of a sweep is clean once the sweep completes, and the bitrate never spikes. This questline -makes such video a first-class hang broadcast at both ends: our encoders can -emit it, streams contributed that way import cleanly, and every viewer tunes in -without a visible glitch. +makes such video a first-class hang broadcast on import and playback: streams +contributed that way import cleanly, and every viewer tunes in without a +visible glitch. + +Decided in the 2026-09-30 audit: the encode side (shared config, NVENC, V4L2, +bindings) moved to m3 pending the [GOP overhead](/quest/m2/gop-overhead.md) +verdict. Import and playback stay here because contributed feeds already use +intra refresh regardless of what our encoders do. The motivations, in the order they settle tradeoffs: a flat bitrate at low latency, so a bandwidth grant holds; faster tune-in, since a short refresh cycle @@ -29,27 +34,20 @@ Decisions the quests share: mid-stream skip both decode everything and present nothing until recovery, freezing on the last good frame. A group that opens on a true IDR shows at once. -- The shared encode config extends the `Gop` contract settled in main, - and a cut in refresh mode starts a new sweep, never an IDR. - H.264 and H.265 only. AV1 and VP9 have no standard gradual refresh signal. - WebCodecs has no intra-refresh option, so js/publish is consumer-only here. - Backends without the knob refuse refresh mode; NVENC and V4L2 get it now, - Media Foundation and MediaCodec are follow-ups. + WebCodecs has no intra-refresh option, so js/publish is consumer-only. ## Required - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - JS and Rust viewers join `warmup` earlier and withhold display until recovery, except at a true IDR - [H.264 import](/quest/m2/intra-refresh/h264-import.md) - the splitter keeps `recovery_frame_cnt` and import publishes `warmup` from it - [H.265 import](/quest/m2/intra-refresh/h265-import.md) - the splitter reads the recovery-point SEI so an HEVC intra-refresh stream forms groups and publishes `warmup` -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - refresh mode extends the settled GOP contract; the producer cuts groups per sweep and publishes `warmup` -- [NVENC refresh](/quest/m2/intra-refresh/nvenc-refresh.md) - the NVENC backend encodes refresh mode for H.264 and HEVC -- [V4L2 refresh](/quest/m2/intra-refresh/v4l2-refresh.md) - the V4L2 backend encodes refresh mode -- [Bindings](/quest/m2/intra-refresh/bindings.md) - moq-ffi and every wrapper expose refresh mode, additive on the ffi-shape `Gop` enum - [Export sync flags](/quest/m2/intra-refresh/export-sync-flags.md) - fmp4, MKV, and HLS stop advertising a refresh group start as a sync sample ## Related - [Audio warmup](/quest/m1/audio-warmup.md) - Opus convergence after a mid-stream join uses the same `warmup` field -- [#2067](/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md) - the open-GOP fixture and cold tune-in measurement - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - frames stamped before the group's keyframe are the other tune-in trim - [Catalog warmup](/quest/m1/catalog-warmup.md) - the generic `warmup` field this line reads, kept in m1 for audio and open-GOP tune-in +- [GOP overhead](/quest/m2/gop-overhead.md) - the verdict that decides whether our encoders emit refresh mode +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - refresh-mode groups on the `Gop` contract, parked with NVENC, V4L2, and bindings behind it diff --git a/quest/m1/ladder/README.md b/quest/m2/ladder/README.md similarity index 94% rename from quest/m1/ladder/README.md rename to quest/m2/ladder/README.md index 0c242cc396d..ebb9027691c 100644 --- a/quest/m1/ladder/README.md +++ b/quest/m2/ladder/README.md @@ -15,6 +15,9 @@ state. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for the +publisher-side ladder. + The catalog and player half already shipped in [moq#2865](https://github.com/moq-dev/moq/pull/2865): the optional `stalled` state exists in `rs/hang`, `js/hang`, `rs/moq-msf`, `js/msf`, the HANG draft @@ -73,9 +76,9 @@ encoders on every target change. ## Required -- [Controller](/quest/m1/ladder/controller.md) - one controller owns every +- [Controller](/quest/m2/ladder/controller.md) - one controller owns every rung's share, target, stalled state, and send order -- [Fetch and catalog](/quest/m1/ladder/fetch.md) - uncached FETCH encodes at +- [Fetch and catalog](/quest/m2/ladder/fetch.md) - uncached FETCH encodes at the shared applied target, and rung state survives a source catalog refresh ## Closes diff --git a/quest/m1/ladder/controller.md b/quest/m2/ladder/controller.md similarity index 98% rename from quest/m1/ladder/controller.md rename to quest/m2/ladder/controller.md index 32ba4c18604..53015fe2171 100644 --- a/quest/m1/ladder/controller.md +++ b/quest/m2/ladder/controller.md @@ -18,7 +18,7 @@ today's fixed-rate behavior exactly and never publishes congestion-induced `stalled` state, which is what keeps this additive. The controller subdivides that estimate across the ladder and applies the -band boundary from the [questline](/quest/m1/ladder/README.md), including the +band boundary from the [questline](/quest/m2/ladder/README.md), including the lowest rung's `max / 3` case. `moq_transcode::Ladder` is ascending: `new` sorts by configured maximum (`rs/moq-transcode/src/ladder.rs:101`) and `rungs()` is lowest first (`:125-128`), so the next lower rendition the diff --git a/quest/m1/ladder/fetch.md b/quest/m2/ladder/fetch.md similarity index 95% rename from quest/m1/ladder/fetch.md rename to quest/m2/ladder/fetch.md index 54630fedcec..4e529ecc2a0 100644 --- a/quest/m1/ladder/fetch.md +++ b/quest/m2/ladder/fetch.md @@ -31,5 +31,5 @@ intact. ## Required -- [Controller](/quest/m1/ladder/controller.md) - there is no shared applied +- [Controller](/quest/m2/ladder/controller.md) - there is no shared applied target to read until the controller owns one diff --git a/quest/m2/latency-ledger.md b/quest/m2/latency-ledger.md index ed059c529ba..ad3cee94e8e 100644 --- a/quest/m2/latency-ledger.md +++ b/quest/m2/latency-ledger.md @@ -14,9 +14,9 @@ trade to get it running. This quest promotes them. - Take the stage schema the harness already defines (capture, encode, publish flush, network, jitter buffer, decode, render) and expose it as fields of - `hang::Stats`, the media extension the client stats schema adds to - `moq-stats` (`rs/hang/src/stats.rs`, and its `@moq/stats` mirror), rather - than a second readout: an observable value a `.stats` broadcast already + the hang stats and feedback snapshots (`rs/hang/src/stats.rs`, + `rs/hang/src/echo.rs`, and their `@moq/hang` mirrors), rather than a + second readout: an observable value a stats or `.echo` track already carries, not a callback. Decided so viewers report latency the same way they report stalls. - Both languages, matching names, per the repo's cross-language rule. Scrutinise @@ -34,7 +34,7 @@ trade to get it running. This quest promotes them. ## Required - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - defines the stage schema and lands the probes this promotes -- [Schema and library](/quest/m1/qos/stats/schema.md) - adds `hang::Stats`, which this extends +- [Media stats schema](/quest/m1/stats/schema.md) - adds the stats and feedback snapshots this extends ## Related diff --git a/quest/m2/livekit-webrtc-bridge.md b/quest/m2/livekit-webrtc-bridge.md deleted file mode 100644 index 3cc4f54ed7c..00000000000 --- a/quest/m2/livekit-webrtc-bridge.md +++ /dev/null @@ -1,27 +0,0 @@ -# [M] LiveKit WebRTC bridge evaluation - -## Goal - -A go/no-go verdict, backed by a working spike, on bridging LiveKit rooms to -MoQ per-track over WebRTC using LiveKit's Rust SDK: a native participant -joins the room and republishes its tracks into MoQ, optionally the reverse. -The verdict decides whether this becomes a maintained gateway. - -## Plan - -- The zero-code paths already exist and bound the value: LiveKit Egress - pushes RTMP/SRT into the existing gateways today (composited and - transcoded), and `moq export rtc --connect` publishes WHIP into LiveKit - Ingress. LiveKit has no WHIP/WHEP egress, so per-track LiveKit to MoQ - requires joining the room as a participant via livekit rust-sdks - (Apache 2.0, no Chrome/GStreamer). -- Spike it in-tree: a rust-sdks participant subscribes to all tracks and - republishes via moq-net + moq-mux, with codec passthrough where possible - (Opus/VP8/VP9; H.264 through the Annex-B importer). -- Assess dependency weight of the webrtc stack, per-track fidelity versus the - Egress paths, simulcast handling, and where a real gateway would live (edge - versus standalone). - -## Related - -- [LiveKit client shim](/quest/m2/livekit-shim.md) diff --git a/quest/m2/mobile-capture-android.md b/quest/m2/mobile-capture-android.md index 0c69542352f..7482917a804 100644 --- a/quest/m2/mobile-capture-android.md +++ b/quest/m2/mobile-capture-android.md @@ -23,7 +23,7 @@ so the mechanism exists. ## Required -- [Ownership boundary](/quest/m2/mobile-ownership.md) - decides whether an NDK/JNI backend family is worth building +- [Ownership boundary](/quest/m1/mobile-ownership.md) - decides whether an NDK/JNI backend family is worth building ## Related diff --git a/quest/m2/mobile-capture-ios.md b/quest/m2/mobile-capture-ios.md index 9583ed69d9e..9816b6a7d30 100644 --- a/quest/m2/mobile-capture-ios.md +++ b/quest/m2/mobile-capture-ios.md @@ -24,7 +24,7 @@ same everywhere. ## Required -- [Ownership boundary](/quest/m2/mobile-ownership.md) - decides whether Rust owns capture on mobile at all +- [Ownership boundary](/quest/m1/mobile-ownership.md) - decides whether Rust owns capture on mobile at all ## Related diff --git a/quest/m2/mobile-completion.md b/quest/m2/mobile-completion.md index 7770a0280f2..8490656ed71 100644 --- a/quest/m2/mobile-completion.md +++ b/quest/m2/mobile-completion.md @@ -24,9 +24,9 @@ Do not close #700 merely because its next subset or a design decision finished. - [Dart on iOS](/quest/m1/dart-ios.md) - the Dart iOS asset proof - [Dart codec parity](/quest/m1/dart-codecs.md) - codec-enabled artifacts and Dart video consumer integration -- [Mobile ownership](/quest/m2/mobile-ownership.md) - select and scope the mobile media architecture - [iOS capture](/quest/m2/mobile-capture-ios.md) - deliver the selected iOS capture path - [Android capture](/quest/m2/mobile-capture-android.md) - deliver the selected Android capture and codec path +- [Mobile ownership](/quest/m1/mobile-ownership.md) - select and scope the mobile media architecture ## Closes diff --git a/quest/m2/mobile-ownership.md b/quest/m2/mobile-ownership.md deleted file mode 100644 index 14e17f4c940..00000000000 --- a/quest/m2/mobile-ownership.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] Plan: who owns capture, codecs, and rendering on mobile - -## Goal - -A written decision, recorded in this tree, on the mobile media boundary: -either Swift and Kotlin own camera, platform codecs, and rendering while Rust -carries encoded access units through the existing media APIs, or Rust owns -capture, codecs, and rendering and `moq-ffi` grows opaque native surface -bridges for `CVPixelBuffer` and Android `HardwareBuffer`/`Surface`. The -capture quests in this questline start only once this is settled. - -## Plan - -- Option 1 is smaller and idiomatic for an app SDK; option 2 avoids two - parallel media stacks and matches the in-tree direction of moq-video, at - the cost of native-handle ownership across the FFI. #700 lays both out. -- Weigh with evidence rather than preference: what `moq-kit` already does in - Kotlin over `moq-ffi`, what the iroh-live reimplementation says about the - Rust-native audience, and the copy cost of byte-array frames measured on a - device. -- Record the verdict here and in `rs/moq-ffi/AGENTS.md`, and re-estimate - [Android capture](/quest/m2/mobile-capture-android.md) and - [iOS capture](/quest/m2/mobile-capture-ios.md) against it; both target - `moq-video`, so replace them with the required platform-owned implementation - quests if the answer is option 1. Update [mobile completion](/quest/m2/mobile-completion.md) - to require those replacements before abandoning the Rust capture quests. diff --git a/quest/m1/moq-install-url.md b/quest/m2/moq-install-url.md similarity index 91% rename from quest/m1/moq-install-url.md rename to quest/m2/moq-install-url.md index 86a1378ba94..bcda57218ef 100644 --- a/quest/m1/moq-install-url.md +++ b/quest/m2/moq-install-url.md @@ -8,6 +8,9 @@ maintaining another copy of the install logic. ## Plan +Deferred to m2 in the 2026-09-30 audit: it follows [the +installer](/quest/m2/moq-installer.md), which is m2. + - Implement the hosting change in **moq-dev/moq.dev**, which owns the root website, not moq.pro. Track this cross-repository work here beside its installer dependency; complete this quest only after the website change @@ -27,8 +30,3 @@ maintaining another copy of the install logic. working. Keep upgrade and version-selection examples aligned with the canonical installer's interface. Add route coverage to the site's normal checks for the shell response/redirect and error behavior. - -## Required - -- [Install moq](/quest/m1/moq-installer.md) - canonical installer, release - selection, upgrade behavior, and tests are published first diff --git a/quest/m2/moq-installer.md b/quest/m2/moq-installer.md new file mode 100644 index 00000000000..5a95a000dcb --- /dev/null +++ b/quest/m2/moq-installer.md @@ -0,0 +1,52 @@ +# [S] One-command moq installation and upgrades + +## Goal + +A canonical Bash installer installs the released `moq` binary on supported +macOS and Linux machines without Rust or sudo. Running it again upgrades +the same installation; selecting a version supports +reproducible installs and deliberate downgrades. + +Install only `moq` from the `moq-cli` release. Token and relay functionality +belong to its subcommands, not separate installer choices. This work does +not implement those subcommands, automatic updates, a self-update command, +service setup, Windows support, or new release targets. + +## Plan + +Deferred to m2 in the 2026-09-30 audit: no named consumer; `cargo install`, +Nix, Docker, and winget already install `moq`. + +- Download the archives `.github/workflows/release-binary.yml` already + publishes; the installer needs no workflow change. +- Default to the latest stable `moq-cli` release, with an explicit version + option. Resolve that product's tags, not the repository-wide latest + release: this repository publishes multiple independently versioned crates. + Refuse missing versions, malformed input, and incomplete releases clearly. +- Verify the selected archive against the release's `SHA256SUMS`, extract it + into a temporary file in the destination directory, then atomically rename + it over the destination. A failed install leaves the prior binary untouched. + Decided in the 2026-09-30 audit: no journaled transaction or ownership + record; that was out of proportion for one binary. +- Support the existing targets: macOS ARM64 and Linux x86_64/ARM64 with + glibc 2.34 or newer. Refuse unsupported operating systems, architectures, + and libc variants with actionable diagnostics. +- Default to `~/.local/bin` with an explicit directory override. Do not invoke + sudo or edit shell profiles. Print the installed version and path, and PATH + instructions when needed. Warn when another `moq` on PATH takes precedence. + Refuse a destination that is a symlink, so a package manager's install is + never overwritten. +- Keep the canonical script and its tests in this repository, and publish a + usable HTTPS source for [the install URL](/quest/m2/moq-install-url.md). +- Document install, upgrade, version selection, directory override, and + removal in `doc/setup/install.md`. +- Wire installer tests into `just check` and CI: initial install, upgrade, + explicit downgrade, product-specific latest selection, unsupported hosts, + corrupt or missing assets, and a failure preserving the existing binary. + Run the script against real release assets in a temporary directory and + run the installed `moq --version`. + +## Related + +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - relay functionality joins + the same executable independently of its installation method diff --git a/quest/m1/moq-relay-subcommand.md b/quest/m2/moq-relay-subcommand.md similarity index 93% rename from quest/m1/moq-relay-subcommand.md rename to quest/m2/moq-relay-subcommand.md index 0c0453d7048..88833abf60b 100644 --- a/quest/m1/moq-relay-subcommand.md +++ b/quest/m2/moq-relay-subcommand.md @@ -9,6 +9,9 @@ decode, and render stack. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer, and [`moq --listen` +admission](/quest/m1/cli-serve.md) no longer waits on it. + `moq-relay` is lib+bin (`rs/moq-relay/Cargo.toml`), with a 15-line `main.rs` that installs the aws-lc-rs provider, optionally jemalloc, and calls `Relay::load(Config::load()?).await?.run()`. diff --git a/quest/m2/msfts-convergence.md b/quest/m2/msfts-convergence.md new file mode 100644 index 00000000000..ac9a67dc4a3 --- /dev/null +++ b/quest/m2/msfts-convergence.md @@ -0,0 +1,26 @@ +# [M] MPEG-TS lane converges with MSFTS ES-level carriage + +## Goal + +A subscriber author can map this repository's demultiplexed TS lane +(access units, Hang catalog `mpegts` section) onto MSFTS ES-level carriage +without guessing. Transporting TS verbatim is a non-goal. + +## Plan + +Decided in the 2026-09-30 audit: moved from m4 and the msfts#33 gate removed. +msfts#33 closed on 2026-09-28, answered by msfts#36 (merged 2026-09-24), and +egress moved to msfts#37 (closed). Two differences remain: + +- **Program tables.** MSFTS carries them in tracks; here they live in the + Hang catalog's `mpegts` section. Decide whether to publish a mapping from + the catalog section to MSFTS's table tracks, or change either side. +- **ES units.** MSFTS es-units carry the whole PES packet; here they carry the + payload plus `stream_id`. Decide whether the PES header fields we drop + matter to a subscriber, and converge or document the mapping. + +Update `drafts/draft-lcurley-moq-mpegts.md` and `doc/concept` with whatever +lands. Open TS PRs [#4577](https://github.com/moq-dev/moq/pull/4577) (per-ES +access units at export), [#4579](https://github.com/moq-dev/moq/pull/4579) +(export on the mux rate), and [#4580](https://github.com/moq-dev/moq/pull/4580) +(per-program SI) touch the same area; land or rebase on them first. diff --git a/quest/m2/multipath-spike.md b/quest/m2/multipath-spike.md deleted file mode 100644 index 6e7646f68b0..00000000000 --- a/quest/m2/multipath-spike.md +++ /dev/null @@ -1,64 +0,0 @@ -# [M] Multipath spike - -## Goal - -A verdict on whether bonded contribution over multipath QUIC is worth -building, backed by two paths actually carrying one session. Bonding means -sending a broadcast over several links at once (cellular plus cellular plus -wifi) so a field encoder survives any one of them degrading, which is the -business LiveU and Peplink built on proprietary tech and SRT has no answer -for. - -## Plan - -The protocol work is done and unused. `noq` implements draft-ietf-quic-multipath -in full (`open_path`, `path_events`, `path_stats`, a `Path` type, and a -substantial test suite), but `apply_transport` never calls -`max_concurrent_multipath_paths`, whose default is `None`, so multipath is not -negotiated on any MoQ connection. - -The spike is small: call that setter, add a max-paths knob beside the other -transport settings, and open a second path from the connect side. It rides -entirely below the `web_transport_trait` line, because -`web_transport_moq::Session` derefs to `noq::Connection` and the trait requires -`Clone`, so the backend can hand one clone to moq-net and keep another to -drive paths on. No trait change, no moq-net change, and none belongs there: a -browser WebTransport backend could never implement it. - -**What the spike is really for is the constraint nobody has written down.** -`max_concurrent_multipath_paths` maps to the `initial_max_path_id` transport -parameter, which both peers negotiate, so a multipath session needs noq on -*both* ends. noq is the only native QUIC backend, while browser and qmux -transports have no such thing. So bonded contribution is not an opt-in client feature; it -constrains every relay and client on the path to run noq. Establish what that -actually costs before anyone builds a fan-out socket. - -Prove it on a multi-homed host, which is enough to negotiate and open a second -path and is not yet phone bonding. - -Then record what the rest would take, so a go verdict has something to plan -from and a no-go says why: - -- **One endpoint is one UDP socket.** `FourTuple` carries `local_ip` only, - because "we can only specify the `src_ip`, not the source port", and setting - a source IP does not choose an egress interface. Android needs - `Network.bindSocket` and iOS needs an interface bind to reach the cellular - radio at all. The escape hatch is `Endpoint::new_with_abstract_socket` with a - fan-out `AsyncUdpSocket` owning one interface-bound socket per radio, which - then has to answer for `local_addr`, and take the conservative minimum for - `max_receive_segments` and `may_fragment`. -- **Stats are single-path shaped.** `ConnectionStats` carries one `rtt` and one - `estimated_send_rate`, and per-path scheduling for contribution would need - both that and `web_transport_trait::Stats` reshaped. -- **Scheduling policy is unchosen**: duplicate every path for redundancy, or - stripe across them for capacity. - -Naming trap: `Path` in moq-net is the broadcast namespace path, and -`Client::with_path` is the MoQ SETUP resource path. A network path needs a -different name. - -Target `main`: `apply_transport` lives in `rs/moq-tokio/src/noq.rs` there -too, and the max-paths knob is additive. - -Public API: an additive transport setting in `moq-tokio`. Wire: none; multipath -is negotiated by QUIC transport parameters, below MoQ. diff --git a/quest/m2/noq-socket-close.md b/quest/m2/noq-socket-close.md index 3fa7a9621b8..a442d2121b6 100644 --- a/quest/m2/noq-socket-close.md +++ b/quest/m2/noq-socket-close.md @@ -1,21 +1,24 @@ -# [M] noq releases an endpoint's socket on close +# [M] moq-quic releases an endpoint's socket on close ## Goal -A noq endpoint can close its UDP socket, and report when it has, without +A `moq-quic` endpoint can close its UDP socket, and report when it has, without waiting for every connection handle to drop. moq-tokio then deletes the closable socket wrapper that #4087 added to make `Listener::close` release the port. ## Plan -In moq-dev/noq, add an endpoint operation that closes the endpoint, waits +In `moq-quic-tokio`, add an endpoint operation that closes the endpoint, waits until each connection has sent its close, and then releases the socket. Later -sends are dropped and receives end. Test it there. Cut a noq release, bump the -pin, and replace moq-tokio's wrapper with the upstream call. The Go +sends are dropped and receives end. Test it there and replace moq-tokio's wrapper with it in the same PR. The Go `TestReconnectAcrossRelayRestart` and moq-tokio's `close_releases_quic_socket` stay green. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the endpoint is in-tree + ## Related - [Listener close](https://github.com/moq-dev/moq/pull/4087) - the local wrapper this replaces diff --git a/quest/m2/nvenc-pool.md b/quest/m2/nvenc-pool.md index c1723df7283..bd6c851e7f8 100644 --- a/quest/m2/nvenc-pool.md +++ b/quest/m2/nvenc-pool.md @@ -15,4 +15,10 @@ quest and report the numbers. frames) on every `encode`, and frees them all at the end of the call. Keep a small pool sized by the frames in flight, which is one today since B-frames are off. Re-register a CUDA resource only when its pointer changes. Measure -with the `encode-presets` example from #4099. +with the `encode-presets` example from #4099, which so far exists only on the +[OBS moq-video](/quest/m1/obs-moq-video/README.md) line; if that line has not +merged, run it from that branch or add an encode benchmark on main instead. + +## Related + +- [OBS moq-video](/quest/m1/obs-moq-video/README.md) - carries the `encode-presets` example this measures with diff --git a/quest/m1/obs-moq-video/decode-linux.md b/quest/m2/obs-decode-linux.md similarity index 96% rename from quest/m1/obs-moq-video/decode-linux.md rename to quest/m2/obs-decode-linux.md index aa18cd45ef6..ccff322aa99 100644 --- a/quest/m1/obs-moq-video/decode-linux.md +++ b/quest/m2/obs-decode-linux.md @@ -17,4 +17,4 @@ At least one supported Linux hardware decoder delivers frames to OBS without CPU ## Related -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - owns remaining VAAPI decode and native surface gaps; avoid a duplicate backend implementation +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - owns remaining VAAPI decode and native surface gaps; avoid a duplicate backend implementation diff --git a/quest/m1/obs-moq-video/decode-windows.md b/quest/m2/obs-decode-windows.md similarity index 100% rename from quest/m1/obs-moq-video/decode-windows.md rename to quest/m2/obs-decode-windows.md diff --git a/quest/m1/obs-moq-video/macos.md b/quest/m2/obs-macos.md similarity index 100% rename from quest/m1/obs-moq-video/macos.md rename to quest/m2/obs-macos.md diff --git a/quest/m1/obs-moq-video/windows.md b/quest/m2/obs-windows.md similarity index 100% rename from quest/m1/obs-moq-video/windows.md rename to quest/m2/obs-windows.md diff --git a/quest/m1/one-port/README.md b/quest/m2/one-port/README.md similarity index 88% rename from quest/m1/one-port/README.md rename to quest/m2/one-port/README.md index 8e9fbe8e00c..d7c055b883a 100644 --- a/quest/m1/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -20,6 +20,9 @@ reuseport shard groups are a later consumer, not a blocker. ## Plan +Deferred to m2 in the 2026-09-30 audit: the consumer is moq.pro's edge, SRT is +blocked upstream on srt-tokio, and STUN's only consumer is P2P, also m2. + ### Classifying a datagram RFC 7983 already partitions the first byte: STUN is 0 to 3, DTLS 20 to 63, @@ -73,11 +76,11 @@ pre-accepted streams can stand behind. ## Required -- [UDP demux](/quest/m1/one-port/udp-demux.md) - one socket carries QUIC, STUN answers, and the WebRTC media path, with greasing off -- [TCP acceptor](/quest/m1/one-port/tcp-demux.md) - one listener carries TLS-terminated HTTP, RTMP, and RTMPS -- [SRT on the shared socket](/quest/m1/one-port/srt-demux.md) - srt-tokio accepts a virtual socket and the flow table pins its 4-tuples +- [UDP demux](/quest/m2/one-port/udp-demux.md) - one socket carries QUIC and STUN answers, with greasing off and a WebRTC hook for embedders +- [TCP acceptor](/quest/m2/one-port/tcp-demux.md) - one listener carries TLS-terminated HTTP, RTMP, and RTMPS +- [SRT on the shared socket](/quest/m2/one-port/srt-demux.md) - srt-tokio accepts a virtual socket and the flow table pins its 4-tuples ## Related -- [P2P](/quest/m1/p2p/README.md) - the client that names the relay as its STUN server -- [Stream sessions](/quest/m1/uring-tcp/README.md) - the io_uring workers that would host the same demux later +- [P2P](/quest/m2/p2p/README.md) - the client that names the relay as its STUN server +- [Stream sessions](/quest/m2/uring-tcp/README.md) - the io_uring workers that would host the same demux later diff --git a/quest/m1/one-port/srt-demux.md b/quest/m2/one-port/srt-demux.md similarity index 94% rename from quest/m1/one-port/srt-demux.md rename to quest/m2/one-port/srt-demux.md index 92b3da2d155..d12a4920833 100644 --- a/quest/m1/one-port/srt-demux.md +++ b/quest/m2/one-port/srt-demux.md @@ -16,7 +16,7 @@ socket. Fallback if refused: `srt-protocol` is sans-io, so `moq-srt` drives its `Listen` and `Connection` state machines directly on fed packets, which is more code but removes the dependency on `srt-tokio`'s socket handling. -The demux side is the flow table from [UDP demux](/quest/m1/one-port/udp-demux.md): +The demux side is the flow table from [UDP demux](/quest/m2/one-port/udp-demux.md): a 4-tuple already pinned to WebRTC (ICE succeeded) is never tested for SRT. An unknown 4-tuple whose full SRT handshake header matches (control bit, type 0, and the SRT magic, not merely `80 00`) pins to SRT provisionally: @@ -35,5 +35,5 @@ with a QUIC client active on the same port; a QUIC short header from a new ## Required -- [UDP demux](/quest/m1/one-port/udp-demux.md) +- [UDP demux](/quest/m2/one-port/udp-demux.md) - srt-tokio accepts a caller-supplied socket abstraction upstream, or the sans-io fallback is chosen diff --git a/quest/m1/one-port/tcp-demux.md b/quest/m2/one-port/tcp-demux.md similarity index 96% rename from quest/m1/one-port/tcp-demux.md rename to quest/m2/one-port/tcp-demux.md index cdc71480197..4b973b9584a 100644 --- a/quest/m1/one-port/tcp-demux.md +++ b/quest/m2/one-port/tcp-demux.md @@ -34,4 +34,4 @@ against one listener each land in the right arm. ## Related -- [UDP demux](/quest/m1/one-port/udp-demux.md) - the UDP half +- [UDP demux](/quest/m2/one-port/udp-demux.md) - the UDP half diff --git a/quest/m1/one-port/udp-demux.md b/quest/m2/one-port/udp-demux.md similarity index 59% rename from quest/m1/one-port/udp-demux.md rename to quest/m2/one-port/udp-demux.md index 017ea18ac88..9b44ff448ca 100644 --- a/quest/m1/one-port/udp-demux.md +++ b/quest/m2/one-port/udp-demux.md @@ -2,17 +2,18 @@ ## Goal -`moq-relay` reads one UDP socket and serves QUIC, STUN Binding answers, and -the WebRTC media path from it. A WHIP or WHEP client sees ICE candidates on -the QUIC port, a P2P client can list `stun::`, and every -backend config has QUIC-bit greasing off so a short header is always -recognizable. +`moq-relay` reads one UDP socket and serves QUIC and STUN Binding answers from +it. A P2P client can list `stun::`, and every backend config has +QUIC-bit greasing off so a short header is always recognizable. The WebRTC +media path is an embedder hook: the demux hands its class to a virtual socket +an embedder such as moq.pro's edge can feed to `moq-rtc`, since `moq-relay` +serves no WHIP or WHEP. ## Plan `moq-sock` gains the demux: a task owning the OS socket (or shard) that classifies each datagram by the rules in the -[questline README](/quest/m1/one-port/README.md) and hands it to the matching +[questline README](/quest/m2/one-port/README.md) and hands it to the matching virtual socket, plus the flow table keyed by 4-tuple that SRT will need, built now so its shape is settled. Each virtual socket implements `AsyncUdpSocket`: `poll_recv` drains its queue, `poll_send` writes through @@ -38,16 +39,19 @@ one is a public query and goes to the responder. Public STUN clients never send USERNAME and ICE agents always do. Off by default in `moq-relay`, on with `--stun`. -WebRTC: `moq_rtc::server::mux::Mux` gains `Mux::feed(src, bytes)` and a -constructor over a virtual socket, so it stops binding its own port; its -advertised candidates become the shared address. `Config.udp_bind` goes. -When ICE succeeds on a 4-tuple the mux reports it and the outer flow table -pins that tuple to WebRTC, so later RTP cannot be classified as SRT. +WebRTC: DTLS, RTP, and USERNAME-carrying STUN go to a `webrtc` virtual +socket that `moq-relay` leaves unconsumed and an embedder takes. Adapting +`moq_rtc::server::mux::Mux` to it (`Mux::feed`, a shared advertised address, +and pinning ICE 4-tuples in the flow table) is the embedder's work, not this +quest's. -Tests: a unit test per first-byte class routes to the right virtual socket; -an integration test runs a QUIC client, a STUN Binding round trip, and a WHIP -session against one bound port. `moq-relay` docs list the port once. +Decided in the 2026-09-30 audit: narrowed to QUIC plus STUN in the relay, +because `moq-relay` has no `moq-rtc` dependency and serves no WHIP or WHEP. + +Tests: a unit test per first-byte class routes to the right virtual socket, +including the WebRTC hook; an integration test runs a QUIC client and a STUN +Binding round trip against one bound port. `moq-relay` docs list the port once. ## Related -- [P2P](/quest/m1/p2p/README.md) - the client side of the STUN answer +- [P2P](/quest/m2/p2p/README.md) - the client side of the STUN answer diff --git a/quest/m1/p2p/README.md b/quest/m2/p2p/README.md similarity index 82% rename from quest/m1/p2p/README.md rename to quest/m2/p2p/README.md index b0817e23798..f6e40ddb044 100644 --- a/quest/m1/p2p/README.md +++ b/quest/m2/p2p/README.md @@ -28,13 +28,14 @@ under "One channel, qmux, ordered". ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer. + ### The relay is the rendezvous and the fallback Every opted-in peer already holds a session to the same relay, so discovery and signaling ride that session as ordinary moq broadcasts under a reserved -prefix (`.p2p/` by default, configurable), the same shape -[carrier voice](/quest/m2/carrier-voice/README.md) uses for call setup. The -relay learns nothing new; trust is its token scope. A peer that may publish +prefix (`.p2p/` by default, configurable). The relay learns nothing new; +trust is its token scope. A peer that may publish under the prefix is as trusted as any publisher the token admits, so this line needs no E2EE. @@ -44,7 +45,7 @@ the best remaining one and the subscription moves back. That is the whole fallback story; nothing TURN-shaped is built. A relay that also answers STUN on its QUIC port -([one port](/quest/m1/one-port/README.md)) is the lowest-RTT STUN server a +([one port](/quest/m2/one-port/README.md)) is the lowest-RTT STUN server a client can name, but this line takes ICE servers from the application and works with any. @@ -77,12 +78,12 @@ negotiated `maxMessageSize` (256 KiB in Chrome). The cost is head-of-line blocking: one lost chunk stalls every stream until SCTP retransmits it. qmux frames already carry stream offsets, so the follow-up is a qmux transport parameter that permits reordering plus receiver -reassembly, which [qmux on the QUIC core](/quest/m1/quic/qmux.md) provides +reassembly, which [qmux on the QUIC core](/quest/m2/quic-qmux.md) provides for free. Both sides advertise that capability in the roster before the channel is created so it can run `ordered: false`; a loss then stalls only the stream it hit. `RTCDataChannel.ordered` cannot change after the channel exists, so the first qmux record is too late to choose. The -[harness](/quest/m1/p2p/harness.md) supplies the numbers that decide when +[harness](/quest/m2/p2p/harness.md) supplies the numbers that decide when that follow-up is worth it. Channel-per-stream is not planned. moq opens a stream per group, so it churns @@ -101,13 +102,13 @@ already declares a random hop id, so browser hops are identified; the roster id is that hop id, held once per origin rather than once per session. Watcher-to-watcher offload needs a tab to forward what it receives, which the -JS origin does not do today: [transit](/quest/m1/p2p/transit.md). +JS origin does not do today: [transit](/quest/m2/p2p/transit.md). How a P2P route outranks the relay's is deliberately open. Costs today live in one scope, a relay mesh pricing its own links; a P2P link is neither free nor the CDN's egress, and `warm` only accumulates, so a tab forwarding the relay's route ties the relay and loses on chain length. -[Cost across scopes](/quest/m1/p2p/cost-scopes.md) writes the rule before +[Cost across scopes](/quest/m2/p2p/cost-scopes.md) writes the rule before the watcher depends on it. No Rust + WASM in-tab hop: [rs2ts](/quest/m1/rs2ts/remove-wasm.md) removes the @@ -127,20 +128,17 @@ WASM build, so the browser side stays TypeScript. ## Required -- [Data channel transport](/quest/m1/p2p/transport.md) - `@moq/p2p` speaks qmux over one ordered RTCDataChannel behind the WebTransport shape `@moq/net` consumes -- [Signaling and policy](/quest/m1/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used -- [Native data channel transport](/quest/m1/p2p/webrtc.md) - `moq-tokio` holds a moq-net session with a browser over str0m with a full ICE agent -- [moq-cli joins](/quest/m1/p2p/cli.md) - `--p2p` publishes a roster entry with its iroh endpoint, dials iroh between native peers, and serves browsers as a transit hop -- [Transit in the JS origin](/quest/m1/p2p/transit.md) - a tab forwards the routes it receives to its peers with split horizon and its hop id appended -- [Cost across scopes](/quest/m1/p2p/cost-scopes.md) - the written rule for how relay egress, mesh links, and P2P links compare, so a peer that already carries a broadcast wins -- [Watch opts in](/quest/m1/p2p/watch.md) - one attribute turns it on in the demo and the watcher migrates to the cheapest route -- [Harness](/quest/m1/p2p/harness.md) - the Playwright harness and the numbers behind every mapping decision -- [Unordered qmux](/quest/m1/p2p/unordered.md) - qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream +- [Data channel transport](/quest/m2/p2p/transport.md) - `@moq/p2p` speaks qmux over one ordered RTCDataChannel behind the WebTransport shape `@moq/net` consumes +- [Signaling and policy](/quest/m2/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used +- [Native data channel transport](/quest/m2/p2p/webrtc.md) - `moq-tokio` holds a moq-net session with a browser over str0m with a full ICE agent +- [moq-cli joins](/quest/m2/p2p/cli.md) - `--p2p` publishes a roster entry with its iroh endpoint, dials iroh between native peers, and serves browsers as a transit hop +- [Transit in the JS origin](/quest/m2/p2p/transit.md) - a tab forwards the routes it receives to its peers with split horizon and its hop id appended +- [Cost across scopes](/quest/m2/p2p/cost-scopes.md) - the written rule for how relay egress, mesh links, and P2P links compare, so a peer that already carries a broadcast wins +- [Watch opts in](/quest/m2/p2p/watch.md) - one attribute turns it on in the demo and the watcher migrates to the cheapest route +- [Harness](/quest/m2/p2p/harness.md) - the Playwright harness and the numbers behind every mapping decision +- [Unordered qmux](/quest/m2/p2p/unordered.md) - qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream ## Related - [Peer grants](/quest/m1/auth/peer-grant.md) - the hop-bound credential a direct session presents; HMAC keys issue none -- [One port](/quest/m1/one-port/README.md) - the relay answers STUN on its QUIC port - [E2EE](/quest/m1/e2ee/README.md) - what a peer would need if the token scope stopped being the trust boundary -- [qmux on the QUIC core](/quest/m1/quic/qmux.md) - the stream core the unordered follow-up rides -- [Carrier voice](/quest/m2/carrier-voice/README.md) - signaling as an application protocol over moq, the pattern reused here diff --git a/quest/m1/p2p/cli.md b/quest/m2/p2p/cli.md similarity index 89% rename from quest/m1/p2p/cli.md rename to quest/m2/p2p/cli.md index f0b28f71270..a5e3b161450 100644 --- a/quest/m1/p2p/cli.md +++ b/quest/m2/p2p/cli.md @@ -16,7 +16,7 @@ than adding startup checks. `--p2p-ice-server`, `Peers` takes; `select` is the CLI's built-in default of dialing everyone. The roster entry mirrors the `info.json` schema from -[signaling](/quest/m1/p2p/signal.md): the listener's LAN addresses as +[signaling](/quest/m2/p2p/signal.md): the listener's LAN addresses as WebTransport URLs, ordered the way `mdns::Peer::urls` orders them, with the listener's certificate fingerprint; the iroh endpoint id when `--iroh` is on, which is the first place an endpoint id appears in any roster; `webrtc: true`; @@ -35,5 +35,5 @@ Docs: a "P2P" section in `doc/bin/cli.md` beside the LAN cluster one. ## Required -- [Native data channel transport](/quest/m1/p2p/webrtc.md) -- [Signaling and policy](/quest/m1/p2p/signal.md) - the roster and offer schema this mirrors +- [Native data channel transport](/quest/m2/p2p/webrtc.md) +- [Signaling and policy](/quest/m2/p2p/signal.md) - the roster and offer schema this mirrors diff --git a/quest/m1/p2p/cost-scopes.md b/quest/m2/p2p/cost-scopes.md similarity index 89% rename from quest/m1/p2p/cost-scopes.md rename to quest/m2/p2p/cost-scopes.md index 1aecaa1c194..fd0a2e5b2ce 100644 --- a/quest/m1/p2p/cost-scopes.md +++ b/quest/m2/p2p/cost-scopes.md @@ -26,7 +26,7 @@ link is neither free (peer uplink, reliability) nor the CDN's egress, and nothing flattens `warm` when an origin already carries the content, so a tab forwarding the relay's route at the relay's price plus its own ties the relay and loses on chain length. Candidate rules to weigh, with the numbers from -the [harness](/quest/m1/p2p/harness.md) where they exist: +the [harness](/quest/m2/p2p/harness.md) where they exist: - a warm discount: an origin actively receiving a broadcast re-announces it at `warm` 0 and `cold` unchanged, over every session, in both languages, @@ -43,10 +43,10 @@ holds when the first hop is a publisher tab, and whether the warm discount belongs in the mesh too. Write the rule beside route selection in `doc/concept/transport.md`, mirror it in `draft-lcurley-moq-lite.md` and `draft-lcurley-moq-cluster.md` where the wire carries it, and pass -`just drafts check`. Then update [watch](/quest/m1/p2p/watch.md) and -[transit](/quest/m1/p2p/transit.md) with the chosen rule and open the +`just drafts check`. Then update [watch](/quest/m2/p2p/watch.md) and +[transit](/quest/m2/p2p/transit.md) with the chosen rule and open the implementation quest it needs. ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - the mesh-side use of cost +- [Cluster routing](/quest/m1/cluster-routing/README.md) - the mesh-side use of cost diff --git a/quest/m1/p2p/harness.md b/quest/m2/p2p/harness.md similarity index 90% rename from quest/m1/p2p/harness.md rename to quest/m2/p2p/harness.md index 9ecd76588ae..0863d93dd2d 100644 --- a/quest/m1/p2p/harness.md +++ b/quest/m2/p2p/harness.md @@ -36,6 +36,6 @@ points. ## Required -- [moq-cli joins](/quest/m1/p2p/cli.md) -- [Signaling and policy](/quest/m1/p2p/signal.md) -- [Transit in the JS origin](/quest/m1/p2p/transit.md) - the watcher-to-watcher row +- [moq-cli joins](/quest/m2/p2p/cli.md) +- [Signaling and policy](/quest/m2/p2p/signal.md) +- [Transit in the JS origin](/quest/m2/p2p/transit.md) - the watcher-to-watcher row diff --git a/quest/m1/p2p/signal.md b/quest/m2/p2p/signal.md similarity index 91% rename from quest/m1/p2p/signal.md rename to quest/m2/p2p/signal.md index a447ebc850f..c0884266119 100644 --- a/quest/m1/p2p/signal.md +++ b/quest/m2/p2p/signal.md @@ -11,7 +11,7 @@ size above which new negotiations stop using them. No new relay behavior. ## Plan `Peers` in `@moq/p2p` takes the shared origin and the policy knobs from the -[questline README](/quest/m1/p2p/README.md): `enabled`, `prefix`, +[questline README](/quest/m2/p2p/README.md): `enabled`, `prefix`, `iceServers`, `max`, `meta`, `select`. Publishing into the origin reaches the relay and the origin's announce stream is the roster. Tests inject a peer connection factory so `bun test` covers pairing, the roster gate, and @@ -28,9 +28,9 @@ the presenter public key that [peer grants](/quest/m1/auth/peer-grant.md) bind, the application's `meta`, and for native peers an optional `webtransport: { url, fingerprint }` and `iroh` endpoint id. The schema is shared with -[moq-cli](/quest/m1/p2p/cli.md). Unordered is advertised here so the dialer +[moq-cli](/quest/m2/p2p/cli.md). Unordered is advertised here so the dialer can set `RTCDataChannel.ordered` at create time; see -[unordered qmux](/quest/m1/p2p/unordered.md). +[unordered qmux](/quest/m2/p2p/unordered.md). Pairing is sparse: broadcasts exist only for pairs some `select` chose, so the cost is the dialed pairs, not the square of the roster. Whoever selects a @@ -59,7 +59,7 @@ failure is terminal for the pair until either side re-announces; no retry loop. Each established connection goes through `connect` with the supplied transport on the dialing side and `accept` on the answering side, both with `publish: origin.consume()` and `consume: origin`, so the tab serves what it -publishes and, once [transit](/quest/m1/p2p/transit.md) lands, what it +publishes and, once [transit](/quest/m2/p2p/transit.md) lands, what it receives. Trust: publishing under the prefix proves only that the relay admitted the @@ -81,9 +81,5 @@ there is no equal-scope shortcut. ## Required -- [Data channel transport](/quest/m1/p2p/transport.md) +- [Data channel transport](/quest/m2/p2p/transport.md) - [Peer grants](/quest/m1/auth/peer-grant.md) - the hop-bound, asymmetrically signed credential a direct session presents; HS256 keys issue none - -## Related - -- [Carrier voice protocol](/quest/m2/carrier-voice/README.md) - the same signaling-as-broadcasts shape diff --git a/quest/m2/p2p/transit.md b/quest/m2/p2p/transit.md new file mode 100644 index 00000000000..cde7482763c --- /dev/null +++ b/quest/m2/p2p/transit.md @@ -0,0 +1,35 @@ +# [S] Transit in the JS origin + +## Goal + +A test proves a tab forwards the routes it receives on one session to the +sessions it serves, so a watcher can re-serve a broadcast to a peer and a room +of watchers can cost the relay one egress stream. Split horizon holds: a route +is never announced back to the session it arrived on, and every forwarded +chain carries the tab's hop id. + +## Plan + +Decided in the 2026-09-30 audit: shrink to a test. The Rust origin already +does transit (`with_publisher` and `with_subscriber` splice and share remote +routes), and [Generated lite](/quest/m1/rs2ts/lite.md) replaces the +hand-written JS origin with one generated from it, so there is no JS +forwarding step to write by hand. + +The hop id must be one per origin, not per session, so the roster id from +[signaling](/quest/m2/p2p/signal.md) and the id in forwarded chains agree. + +Tests with the mock transport pair against the generated origin: a route +received on A appears on B with the id appended and never on A; a chain +already containing the id or at `MAX_HOPS` is dropped; a retraction on A +retracts on B; two watchers of one tab share one upstream subscription. If a +case fails, the fix goes in the Rust origin. + +## Required + +- [Generated lite](/quest/m1/rs2ts/lite.md) - the JS origin generated from moq-net, which already does transit + +## Related + +- [Watch opts in](/quest/m2/p2p/watch.md) - the first topology that needs a forwarding tab +- [Cost across scopes](/quest/m2/p2p/cost-scopes.md) - adds the receiving link's cost to forwarded routes diff --git a/quest/m1/p2p/transport.md b/quest/m2/p2p/transport.md similarity index 91% rename from quest/m1/p2p/transport.md rename to quest/m2/p2p/transport.md index 93ab5ab8371..4ba0a5931ea 100644 --- a/quest/m1/p2p/transport.md +++ b/quest/m2/p2p/transport.md @@ -26,7 +26,7 @@ clamped to the negotiated `maxMessageSize`; a record that would exceed it is split at a frame boundary, never chunked mid-frame. The channel is created with `ordered: true` and no retransmit limit unless signaling already agreed unordered; `ordered` is a constructor option so -[unordered qmux](/quest/m1/p2p/unordered.md) flips it without a second +[unordered qmux](/quest/m2/p2p/unordered.md) flips it without a second transport. The flip is decided from the roster before `createDataChannel`, never from the first qmux record. @@ -41,5 +41,5 @@ the sentence declaring P2P out of scope goes. `just drafts check` passes. ## Related -- [Signaling and policy](/quest/m1/p2p/signal.md) - supplies the peer connection and the agreed ALPN -- [Native data channel transport](/quest/m1/p2p/webrtc.md) - the same binding in Rust +- [Signaling and policy](/quest/m2/p2p/signal.md) - supplies the peer connection and the agreed ALPN +- [Native data channel transport](/quest/m2/p2p/webrtc.md) - the same binding in Rust diff --git a/quest/m1/p2p/unordered.md b/quest/m2/p2p/unordered.md similarity index 87% rename from quest/m1/p2p/unordered.md rename to quest/m2/p2p/unordered.md index 3a8433010c2..a4dc1ffbf76 100644 --- a/quest/m1/p2p/unordered.md +++ b/quest/m2/p2p/unordered.md @@ -13,7 +13,7 @@ qmux frames already carry stream offsets; the draft's in-order STREAM requirement exists so a receiver can deliver without reassembly. Add a transport parameter, `unordered`, that both sides must send for the relaxed rule to apply, and receiver-side reassembly by offset for STREAM frames when -it does. Once [qmux on the QUIC core](/quest/m1/quic/qmux.md) lands, that +it does. Once [qmux on the QUIC core](/quest/m2/quic-qmux.md) lands, that reassembly is QUIC's own receive buffer and this quest is the parameter plus the binding flip; before it, do not build a second reassembly buffer. One record is one SCTP message, so the unordered writer emits frames for only @@ -42,12 +42,11 @@ Draft: `draft-lcurley-qmux.md` gains the parameter and the relaxed rule; the data channel row in `draft-lcurley-moq-lite.md` says which mode it runs. `just drafts check` passes. -Measure with the [harness](/quest/m1/p2p/harness.md) before and after: stall +Measure with the [harness](/quest/m2/p2p/harness.md) before and after: stall duration after an induced loss is the number this quest exists to move, and throughput must not regress. ## Required -- [Harness](/quest/m1/p2p/harness.md) - the loss row this quest is measured against -- [qmux on the QUIC core](/quest/m1/quic/qmux.md) - the receive buffer that makes reassembly free -- [Signaling and policy](/quest/m1/p2p/signal.md) - the roster advertisement that decides ordered before the channel exists +- [Harness](/quest/m2/p2p/harness.md) - the loss row this quest is measured against +- [Signaling and policy](/quest/m2/p2p/signal.md) - the roster advertisement that decides ordered before the channel exists diff --git a/quest/m1/p2p/watch.md b/quest/m2/p2p/watch.md similarity index 74% rename from quest/m1/p2p/watch.md rename to quest/m2/p2p/watch.md index 476879b88da..8307f6c0649 100644 --- a/quest/m1/p2p/watch.md +++ b/quest/m2/p2p/watch.md @@ -13,17 +13,17 @@ goes away, with no visible interruption. `Peers` on the shared connection's origin with the demo's ICE servers and a `max` from the page; `demo/web` exposes the toggle. The route pick is the origin's, from its cost ranking (`compareRoutes` in `js/net/src/origin.ts`) under the rule from -[cost across scopes](/quest/m1/p2p/cost-scopes.md): a peer already carrying +[cost across scopes](/quest/m2/p2p/cost-scopes.md): a peer already carrying the broadcast wins, and its retraction falls back to the relay. Three topologies and the demo shows all of them: a publishing tab serving watcher tabs directly, watcher tabs pulling from a `moq-cli --p2p` hop, and a watcher tab re-serving to another watcher through -[transit](/quest/m1/p2p/transit.md). +[transit](/quest/m2/p2p/transit.md). ## Required -- [Signaling and policy](/quest/m1/p2p/signal.md) -- [moq-cli joins](/quest/m1/p2p/cli.md) - the native hop the second topology shows -- [Transit in the JS origin](/quest/m1/p2p/transit.md) -- [Cost across scopes](/quest/m1/p2p/cost-scopes.md) +- [Signaling and policy](/quest/m2/p2p/signal.md) +- [moq-cli joins](/quest/m2/p2p/cli.md) - the native hop the second topology shows +- [Transit in the JS origin](/quest/m2/p2p/transit.md) +- [Cost across scopes](/quest/m2/p2p/cost-scopes.md) diff --git a/quest/m1/p2p/webrtc.md b/quest/m2/p2p/webrtc.md similarity index 89% rename from quest/m1/p2p/webrtc.md rename to quest/m2/p2p/webrtc.md index 3b6ee88cb50..6dfe54fc1f4 100644 --- a/quest/m1/p2p/webrtc.md +++ b/quest/m2/p2p/webrtc.md @@ -32,7 +32,7 @@ reliable ordered str0m channel, the way `ws::Upgraded` does, and feed `qmux::Session` through `transport::Session` like `websocket.rs`. One record per message, `max_record_size` 16 KiB by default, clamped to the negotiated message size. `ordered` is a config knob for -[unordered qmux](/quest/m1/p2p/unordered.md), set from the roster before +[unordered qmux](/quest/m2/p2p/unordered.md), set from the roster before the channel is created, never from the first qmux record. Tests: an in-process str0m pair over loopback runs moq-net's session tests; @@ -41,6 +41,6 @@ candidate is offered and selected. Browser interop is the harness's job. ## Related -- [Data channel transport](/quest/m1/p2p/transport.md) - the browser side of the same binding -- [moq-cli joins](/quest/m1/p2p/cli.md) - the first consumer -- [One port](/quest/m1/one-port/README.md) - the relay-side STUN answer this client can be pointed at +- [Data channel transport](/quest/m2/p2p/transport.md) - the browser side of the same binding +- [moq-cli joins](/quest/m2/p2p/cli.md) - the first consumer +- [One port](/quest/m2/one-port/README.md) - the relay-side STUN answer this client can be pointed at diff --git a/quest/m2/pipewire-camera-planes.md b/quest/m2/pipewire-camera-planes.md index 5cc58a94f85..c8cda797532 100644 --- a/quest/m2/pipewire-camera-planes.md +++ b/quest/m2/pipewire-camera-planes.md @@ -12,5 +12,4 @@ Unit-test the offer, a multi-block NV12 buffer, and a multi-block I420 buffer, w ## Related -- [Validate PipeWire cameras on a portal and a Pi](/quest/m3/pipewire-camera-hardware.md) - the pass that shows whether a real Pi or portal camera delivers separate planes - [PipeWire DMA-BUFs into Vulkan](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the hardware validation of the DMA-BUF path diff --git a/quest/m1/processor/README.md b/quest/m2/processor/README.md similarity index 80% rename from quest/m1/processor/README.md rename to quest/m2/processor/README.md index 2adda569162..401ddba58f4 100644 --- a/quest/m1/processor/README.md +++ b/quest/m2/processor/README.md @@ -24,24 +24,24 @@ service-prefix layout, not `/.pro`. Suffix routing is dropped everywhere, and a prefix claim needs the variable part of the path trailing, so the processor claims its prefix and mirrors the source path beneath it. The source's catalog reaches the output through a -cross-broadcast reference ([media contract](/quest/m1/processor/media-contract.md)). +cross-broadcast reference ([media contract](/quest/m2/processor/media-contract.md)). + +Deferred to m2 in the 2026-09-30 audit: no processor customer is committed, +and its end-to-end proof (processor-vision) was deleted. ## Required -- [Processor media contract](/quest/m1/processor/media-contract.md) - define +- [Processor media contract](/quest/m2/processor/media-contract.md) - define contribution references, source relations, and correlation in the Hang catalog -- [Advertise-only authorization](/quest/m1/processor/advertise-auth.md) - a +- [Advertise-only authorization](/quest/m2/processor/advertise-auth.md) - a worker may advertise its service prefix without receiving permission to publish arbitrary paths under it -- [Expiring media grants](/quest/m1/processor/grant-lease.md) - enforce +- [Expiring media grants](/quest/m2/processor/grant-lease.md) - enforce short-lived exact grants on already-open consumer and producer handles ## Related -- [Reference vision worker](/quest/m3/processor-vision.md) - a runnable worker - publishes frame-correlated detections and proves demand, reconnect, - failover, and teardown end to end - [Wildcard advertisements](/quest/m0/wildcard/README.md) - lets a dormant processor advertise what it could serve without enumerating live sources, and sets the service-prefix layout diff --git a/quest/m1/processor/advertise-auth.md b/quest/m2/processor/advertise-auth.md similarity index 87% rename from quest/m1/processor/advertise-auth.md rename to quest/m2/processor/advertise-auth.md index d3dc514541f..3b9d5198700 100644 --- a/quest/m1/processor/advertise-auth.md +++ b/quest/m2/processor/advertise-auth.md @@ -17,8 +17,9 @@ announcement or publish request still requires publish permission, so an advertise-only worker cannot bypass the demand exchange. Decided: the advertise scope is prefix-only. Advertising is prefix-only on -every wire (Wildcard's decision) and suffix routing is dropped, so leading-star -and suffix advertise patterns have nothing to authorize. Token claim patterns +every wire (Wildcard's decision) until [announcement shapes](/quest/m2/announce-shapes.md) +adds exact and suffix shapes to moq-lite, so leading-star and suffix advertise +patterns have nothing to authorize yet; that quest extends this scope. Token claim patterns keep their suffix support for publish and subscribe. Decided: an advertised prefix must overlap the advertise scope, not sit diff --git a/quest/m1/processor/grant-lease.md b/quest/m2/processor/grant-lease.md similarity index 92% rename from quest/m1/processor/grant-lease.md rename to quest/m2/processor/grant-lease.md index 66ee0bf16ac..b28462b6c43 100644 --- a/quest/m1/processor/grant-lease.md +++ b/quest/m2/processor/grant-lease.md @@ -22,8 +22,8 @@ cooperative worker timer. Build on what exists: `Grant::deadline` (`rs/moq-auth/src/grant.rs`, #4237) already pins an accepted grant to a fixed deadline, and dev's `moq_auth::lease` (#3943) re-checks a session on cadence and reports why it ended. Extend those to the handles a grant opened rather -than adding a second timer. No clock-skew grace: open #4368 makes expiry -exact and drops `CLOCK_SKEW`, so a deadline in the past is expired. +than adding a second timer. No clock-skew grace: #4368 (merged) made expiry +exact and dropped `CLOCK_SKEW`, so a deadline in the past is expired. Cover an idle open handle, active source reads, active publication, refresh before expiry, refresh after demand ends, disconnect races, HTTP and HLS rejection of diff --git a/quest/m1/processor/media-contract.md b/quest/m2/processor/media-contract.md similarity index 89% rename from quest/m1/processor/media-contract.md rename to quest/m2/processor/media-contract.md index 1bcf95eb5f7..27c4f3d8cd8 100644 --- a/quest/m1/processor/media-contract.md +++ b/quest/m2/processor/media-contract.md @@ -31,3 +31,7 @@ Land Rust and JavaScript catalog bindings, resolver behavior, and fixtures for video, audio, text, missing output, malformed relations, lazy resolution, and relative-path escape. The release and the moq.pro (downstream) pin rollout stay out of this quest. + +## Required + +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - renditions from a source and an output broadcast that share a track name would otherwise collide in one catalog diff --git a/quest/m1/quic/ack-hook.md b/quest/m2/quic-ack-hook.md similarity index 67% rename from quest/m1/quic/ack-hook.md rename to quest/m2/quic-ack-hook.md index 9939c630cc3..9dbb125ee1c 100644 --- a/quest/m1/quic/ack-hook.md +++ b/quest/m2/quic-ack-hook.md @@ -3,16 +3,15 @@ ## Goal A released `web-transport-trait` lets a sender await acknowledgment of a -named byte offset on a send stream, a released `web-transport-moq` implements +named byte offset on a send stream, `web-transport-moq` implements it, and every other backend reports that it cannot rather than returning a guess. ## Plan -The work lives in `moq-dev/web-transport`. This quest exists so the release -it produces is one condition dependents wait on; it supersedes the design in -moq-dev/web-transport#368, whose snapshot-counter shape loses the wakeups a -latency sample needs. +The trait method lives in `moq-dev/web-transport`. The `web-transport-moq` +adapter is in-tree after [the fork](/quest/m1/quic/fork/README.md). This quest supersedes the design in moq-dev/web-transport#368, +whose snapshot-counter shape loses the wakeups a latency sample needs. Add one method to `SendStream`, in the trait's poll style: @@ -30,7 +29,7 @@ use. A default body cannot construct a backend's own `Self::Error`, so unsupported has to live in the return type rather than the error, and a consumer must treat `None` as unknown, never as delivered. -Implement it in `web-transport-moq` over the fork's accessor. Leave +Implement it in `web-transport-moq` over `moq-quic`'s accessor. Leave `web-transport-wasm` on the default; the browser's `WebTransportSendStream.getStats()` is unimplemented in shipping Chrome and its `bytesAcknowledged` is at risk in the W3C draft. qmux over a reliable transport may treat serialization as @@ -42,17 +41,19 @@ the middle of an in-flight frame, several waiters on one stream in offset order, a waiter whose offset lies beyond the final size, reset by sender, STOP_SENDING by the receiver, and session close. -Cut releases of `web-transport-trait` and `web-transport-moq`. The quest -completes when both are on crates.io. +Cut a `web-transport-trait` release; the adapter lands in-tree against it. + +Decided in the 2026-09-30 audit: moved to m2 with its only consumer, +[frame-granularity starvation](/quest/m2/starvation-frames.md). ## Required -- [Per-stream ACK progress in noq](/quest/m1/quic/ack-progress.md) - the - noq-proto accessor the adapter reads +- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - the + `moq-quic` accessor the adapter reads ## Related -- [Starvation at frame granularity](/quest/m1/qos/starvation-frames.md) - the +- [Starvation at frame granularity](/quest/m2/starvation-frames.md) - the moq-net consumer -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - decides +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - decides what acknowledgment means over a reliable transport diff --git a/quest/m1/quic/ack-progress.md b/quest/m2/quic-ack-progress.md similarity index 62% rename from quest/m1/quic/ack-progress.md rename to quest/m2/quic-ack-progress.md index 747f63d6497..cca026beb77 100644 --- a/quest/m1/quic/ack-progress.md +++ b/quest/m2/quic-ack-progress.md @@ -1,17 +1,16 @@ -# [S] noq-proto reports per-stream acknowledgment progress +# [S] moq-quic reports per-stream acknowledgment progress ## Goal -A released noq-proto lets a sender ask how much of a send stream the peer has +`moq-quic` lets a sender ask how much of a send stream the peer has acknowledged and when each acknowledgment was received, corrected for the peer's reported ACK delay. Nothing MoQ builds on top needs private state. ## Plan -The work lives in the moq-dev/noq fork. This quest exists so the release it -produces is one condition dependents wait on. +The work lives in `moq-quic`, in-tree after [the fork](/quest/m1/quic/fork/README.md). -noq-proto already tracks everything needed in `SendBuffer`: the acknowledged +noq-proto (and so quinn-proto; check on the fork) already tracks everything needed in `SendBuffer`: the acknowledged range set, `fully_acked_offset()`, and the unacked length. `Connection` also computes the peer's `ack_delay` per ACK frame when it updates the RTT estimator. Expose that state through the public `SendStream` handle without @@ -33,11 +32,18 @@ stream teardown: the accessor must not return a prefix that includes bytes the peer will never acknowledge, and a waiter for an offset beyond the final size must resolve with the reset instead of hanging. -Land it in the fork and offer it upstream once it is stable. The quest -completes when a `moq-noq-proto` release carries the accessor and -`Cargo.lock` here can name it. +The `web-transport-moq` half of [the ACK hook](/quest/m2/quic-ack-hook.md) +is in-tree too and can land in the same PR. + +Decided in the 2026-09-30 audit: moved to m2 with its consumers, the ACK +hook and [frame-granularity starvation](/quest/m2/starvation-frames.md). + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the accessor lands in `moq-quic` ## Related -- [poll_acked in web-transport](/quest/m1/quic/ack-hook.md) - the first +- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the first consumer of the accessor +- [noq#808](https://github.com/n0-computer/noq/issues/808) - the acked-offset ask to n0 diff --git a/quest/m2/quic-bbr-google.md b/quest/m2/quic-bbr-google.md deleted file mode 100644 index 63c90992fe8..00000000000 --- a/quest/m2/quic-bbr-google.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Measure the remaining Google BBR differences - -## Goal - -A measured decision on two remaining differences from Google's public BBR: -recognizing bandwidth growth within a round and precautionary bandwidth -probing. Each gets an adopt, retain, or investigate-further verdict; Google -parity is not assumed to be an improvement and does not gate correctness fixes. - -## Plan - -Use the corrected fork as the baseline. The 2026-09-21 audit compared -noq-proto 1.3.0 / upstream `1a26a8b` with Google Linux BBRv3 `90210de4` -and Google QUICHE `535a2730`. Recheck current upstream sources before testing. -Use QUICHE's actual `bbr3_sender.cc` with its shared `bbr2_*` model; -the older BBR2 sender is not a substitute for its BBR3 state machine. - -- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1924) recognizes growth on any ACK and increments - the plateau counter only at a round boundary. Noq follows - [draft-06](https://www.ietf.org/archive/id/draft-ietf-ccwg-bbr-06.html#section-5.3.1.2)'s earlier round-start gate. QUICHE - instead checks its bandwidth maximum at round boundaries. Test bursty and - aggregated ACKs and changing bottleneck capacity for premature plateau exits. -- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1803) and - [Google QUICHE](https://github.com/google/quiche/blob/535a2730e77d47e0dc03746555cc9c34b17bc9e9/quiche/quic/core/congestion_control/bbr3_sender.cc#L1079) stop precautionarily when - probing reaches a previously lossy inflight bound, then accelerate a later - probe if feedback is clean. Noq lacks this state and transition. Compare - shallow queues, capacity increases, random loss, and competing flows. - -Report throughput, queue delay, loss, convergence time, and fairness with -pinned code and configurations. Keep transport differences and QUICHE flags -explicit; compare each algorithm change separately. A simulation result is -not an end-to-end network measurement. Persist a reproducible harness in CI -(at least nightly) and the verdict with the quest's completion. Create a -separate implementation quest for any adopted change rather than silently -expanding this study into a controller rewrite. - -## Related - -- [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - reuse media profiles and measurements -- [Upstream the fork](/quest/m1/quic/upstream.md) - share useful findings with upstream diff --git a/quest/m1/quic/bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md similarity index 85% rename from quest/m1/quic/bbr-loss-parity.md rename to quest/m2/quic-bbr-loss-parity.md index 7b36bf4f537..1b6d118264f 100644 --- a/quest/m1/quic/bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -31,6 +31,10 @@ first ACK sample, and a loss between ACKs that must not alter the next ACK's sample. Retain the spurious-loss undo coverage through Refill. Internal only; no `Controller` or wire change. -## Related +Decided in the 2026-09-30 audit: moved to m2. The seven correctness fixes +already shipped, and this remaining gap has no observed impact on MoQ +traffic yet. -- [Upstream the fork](/quest/m1/quic/upstream.md) - offers this fix alongside the seven +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork diff --git a/quest/m2/quic-bbr-natural-drain.md b/quest/m2/quic-bbr-natural-drain.md index 561b4bea8bf..a6dd11bde91 100644 --- a/quest/m2/quic-bbr-natural-drain.md +++ b/quest/m2/quic-bbr-natural-drain.md @@ -1,14 +1,22 @@ -# [M] Measure natural draining before BBR ProbeRTT +# [L] BBR media study ## Goal -A measured adopt-or-retain decision on allowing natural media drains to -satisfy ProbeRTT. Reduce demonstrated frame deadline interference without +Measured adopt, retain, or investigate-further decisions on three BBR +behaviors under media traffic: allowing natural media drains to satisfy +ProbeRTT, recognizing bandwidth growth within a round, and precautionary +bandwidth probing. Reduce demonstrated frame deadline interference without stale minimum RTT, persistent queues, or unfairness. Application limitation -alone is not evidence that the path drained. +alone is not evidence that the path drained, and Google parity is not +assumed to be an improvement. ## Plan +Decided in the 2026-09-30 audit: the Google BBR comparison merged here as +one study, since both reuse the same media profiles, harness, and baseline. + +### Natural drains + Use the corrected released fork as baseline. ProbeRTT targets half the estimated BDP, floored at the minimum pipe window; entering the mode need not withhold useful bytes. First locate actual cwnd stalls and deadline @@ -40,7 +48,37 @@ harness in CI, with broader network cases at least nightly, and a verdict with pinned sources/configurations. Any adopted production policy gets a separate implementation quest; this study does not silently change defaults. +### Google differences + +The 2026-09-21 audit compared noq-proto 1.3.0 / upstream `1a26a8b` with +Google Linux BBRv3 `90210de4` and Google QUICHE `535a2730`. Recheck current +upstream sources before testing. Use QUICHE's actual `bbr3_sender.cc` with +its shared `bbr2_*` model; the older BBR2 sender is not a substitute for its +BBR3 state machine. + +- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1924) + recognizes growth on any ACK and increments the plateau counter only at a + round boundary. Noq follows + [draft-06](https://www.ietf.org/archive/id/draft-ietf-ccwg-bbr-06.html#section-5.3.1.2)'s + earlier round-start gate. QUICHE instead checks its bandwidth maximum at + round boundaries. Test bursty and aggregated ACKs and changing bottleneck + capacity for premature plateau exits. +- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1803) + and [Google QUICHE](https://github.com/google/quiche/blob/535a2730e77d47e0dc03746555cc9c34b17bc9e9/quiche/quic/core/congestion_control/bbr3_sender.cc#L1079) + stop precautionarily when probing reaches a previously lossy inflight + bound, then accelerate a later probe if feedback is clean. Noq lacks this + state and transition. Compare shallow queues, capacity increases, random + loss, and competing flows. + +Report throughput, queue delay, loss, convergence time, and fairness with +pinned code and configurations. Keep transport differences and QUICHE flags +explicit and compare each algorithm change separately. A simulation result +is not an end-to-end network measurement. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related - [Discover media headroom](/quest/m2/quic-probe.md) - preserving an estimate and discovering spare capacity are separate problems -- [Google BBR comparison](/quest/m2/quic-bbr-google.md) - separate growth and precautionary-probing decisions diff --git a/quest/m2/quic-buffer-pool.md b/quest/m2/quic-buffer-pool.md deleted file mode 100644 index b5e34f03ef7..00000000000 --- a/quest/m2/quic-buffer-pool.md +++ /dev/null @@ -1,27 +0,0 @@ -# [S] Send buffer pools - -## Goal - -A measured verdict on pooled send buffers versus `Bytes` in the stream send -path. noq's `SendBuffer` keeps a write above 1452 bytes as the caller's -`Bytes` without copying and coalesces smaller writes into a `BytesMut`; -moq-net hands it frames as `Bytes` from its own allocation. Either a pool of -fixed-size buffers recycled after acknowledgment measurably cuts allocation -and cache misses on the relay's egress, or `Bytes` is shown to be within -noise and the idea is closed. - -## Plan - -- Count allocations and bytes copied per frame on the fanout and video - shapes with the existing profiling captures, split by frame size, so the - share of sub-threshold copies is known before anything is built. -- Prototype in the fork: a `BufFactory`-style seam on `SendBuffer` that takes - buffers from a pool and returns them on ACK, with the pool sized per - connection from the send window. -- `just bench BASE` on Linux: CPU per Gbps, RSS, and p99 latency. Ship only a - measured win. - -## Related - -- [#3204](/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - - the UDP-side pool the same buffers could feed diff --git a/quest/m2/quic-careful-resume.md b/quest/m2/quic-careful-resume.md index 30d906eb0ac..d00d185ebd0 100644 --- a/quest/m2/quic-careful-resume.md +++ b/quest/m2/quic-careful-resume.md @@ -30,8 +30,13 @@ Measure time to the encoder's target rate after a reconnect on the impaired path profile, plus loss and latency during the jump. Ship it on by default only when the jump never makes the first second worse than slow start. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - one of the reconnects this speeds up - [Drain](/quest/m1/drain/README.md) - GOAWAY redials are the other +- [noq#815](https://github.com/n0-computer/noq/issues/815) - the careful-resume proposal to n0 diff --git a/quest/m1/quic/deadline.md b/quest/m2/quic-deadline.md similarity index 87% rename from quest/m1/quic/deadline.md rename to quest/m2/quic-deadline.md index 8450cadfa4c..a644a87043b 100644 --- a/quest/m1/quic/deadline.md +++ b/quest/m2/quic-deadline.md @@ -21,7 +21,7 @@ Implement in the fork. - On loss detection, before queueing a retransmission for a stream with a deadline, estimate the arrival instant as now plus the forward one-way delay. Start with `min_rtt / 2`, corrected by the peer's reported ACK delay; - the [receive-timestamps spike](/quest/m2/quic-receive-ts.md) replaces that + the [receive-timestamps spike](/quest/m3/quic-receive-ts.md) replaces that guess with a measured forward delay. If the estimate is past the deadline, reset the stream with a dedicated error code and drop its retransmit ranges, including bytes already lost, so flow control is returned in one step. @@ -42,14 +42,18 @@ retransmitted past their deadline (must be zero), spurious resets under reordering, and probe overhead versus the default PTO. A proactive probe that raises loss or latency under any profile stays off by default. +Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. + ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - the scheduler decides which stream's data a probe carries ## Related -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - a measured forward +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - a measured forward delay replaces the half-RTT estimate - [Discover media headroom](/quest/m2/quic-probe.md) - can reuse retransmission machinery if redundant capacity probes prove worthwhile +- [noq#813](https://github.com/n0-computer/noq/issues/813) - the per-stream deadline proposal to n0 diff --git a/quest/m1/quic/ecn-measure.md b/quest/m2/quic-ecn-measure.md similarity index 89% rename from quest/m1/quic/ecn-measure.md rename to quest/m2/quic-ecn-measure.md index 2745829780d..32657baf08d 100644 --- a/quest/m1/quic/ecn-measure.md +++ b/quest/m2/quic-ecn-measure.md @@ -36,3 +36,10 @@ from 1.3.1 is a defective baseline, not evidence that classic ECN cannot help. and the tcpdump summaries beside the numbers in the L4S quest's Plan. If neither provider preserves the marks, say so there: L4S stays off and the marking response is only a lab result. + +Decided in the 2026-09-30 audit: moved to m2 with its only consumer, +[L4S on the backbone](/quest/m2/quic-ecn.md). + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork diff --git a/quest/m2/quic-ecn.md b/quest/m2/quic-ecn.md index 3d8e415b83d..8e6db1d0df6 100644 --- a/quest/m2/quic-ecn.md +++ b/quest/m2/quic-ecn.md @@ -24,7 +24,7 @@ need the fork. default (today's behavior on tokio), and `doc/bin/relay/config.md` documents it in the same PR. - Measure on the netem bottleneck from the - [ECN study](/quest/m1/quic/ecn-measure.md) with `dualpi2` marking against + [ECN study](/quest/m2/quic-ecn-measure.md) with `dualpi2` marking against the same bottleneck dropping: queueing delay, goodput, loss. The study's provider verdict decides whether the result matters outside the lab; if neither Linode nor OVH preserves the marks, L4S stays off and the @@ -35,5 +35,10 @@ need the fork. ## Required -- [Measure ECN on the backbone](/quest/m1/quic/ecn-measure.md) - the +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork +- [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - the provider verdict this quest acts on + +## Related + +- [noq#814](https://github.com/n0-computer/noq/issues/814) - the L4S proposal to n0 diff --git a/quest/m2/quic-egress-profile.md b/quest/m2/quic-egress-profile.md new file mode 100644 index 00000000000..71c75e9d178 --- /dev/null +++ b/quest/m2/quic-egress-profile.md @@ -0,0 +1,60 @@ +# [M] Relay egress syscall and allocation profile + +## Goal + +A measured verdict on the relay's egress costs below moq-net: syscalls per +train, allocations and copies per frame, and whether a released GSO train +bursts at the bottleneck. Each lever below is built only if the profile +shows its cost; a lever measured within noise is recorded and closed. + +## Plan + +Decided in the 2026-09-30 audit: send batching, kernel pacing, and send +buffer pools merged into this one measure-first quest, since all three are +questions about the same egress path and share one profile. + +Measure first, on the chat and fanout shapes with many connections, tokio +workers versus io_uring workers, with the existing profiling captures: + +- Syscalls: the tokio path sends one `sendmsg` per GSO train per connection; + the io_uring path queues one SQE per train and submits them together. Count + syscalls per second and CPU per Gbps, and confirm from the io_uring + worker's `enters` counter that the ring already amortizes. +- Allocations: noq's `SendBuffer` keeps a write above 1452 bytes as the + caller's `Bytes` and coalesces smaller writes into a `BytesMut`. Count + allocations and bytes copied per frame, split by frame size, so the share + of sub-threshold copies is known. +- Bursts: noq paces inside `poll_transmit` on both runtimes (#4400, + rs/moq-uring/src/quic/noq/connection.rs:814-817), so the only open question + is whether a released GSO train leaves the NIC as a burst the bottleneck + cannot absorb. On a netem bottleneck, compare inter-packet gaps and queue + occupancy for a 64-segment train against the same bytes paced at the + controller's rate. + +Then, only where the profile shows a cost: + +- `sendmmsg` in `moq-noq-udp` behind the existing GSO path, submitting every + train ready across connections in one call, falling back to per-train + `sendmsg` on partial failure the way the GSO fallback does. +- A `BufFactory`-style seam on `SendBuffer` in the fork that takes buffers + from a pool sized from the send window and returns them on ACK. +- `SCM_TXTIME` stamps, one per train, at the time noq's pacer would have + released it, tested under both `etf` and `fq`. The socket is shared across + connections per worker, so `SO_MAX_PACING_RATE` cannot express + per-connection pacing. Measure on a real NIC as well as loopback, since + `etf` needs hardware offload to be exact. + +Report CPU per Gbps, RSS, loss, and p99 latency via `just bench BASE` on +Linux. The verdict names which levers ship and which qdisc, if any, relay +hosts need. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + +## Related + +- [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - + zero-copy on the same trains +- [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - + the UDP-side pool the same buffers could feed diff --git a/quest/m2/quic-fec.md b/quest/m2/quic-fec.md deleted file mode 100644 index 5b2f32f0983..00000000000 --- a/quest/m2/quic-fec.md +++ /dev/null @@ -1,30 +0,0 @@ -# [L] QUIC FEC experiment - -## Goal - -Record a measured verdict on transport-level forward error correction: whether -spending redundancy before loss beats retransmission on delivery latency, and -at what loss regime it pays. Scope is fork-controlled native peers because -browsers and vanilla WebTransport peers cannot consume custom frames. Ship -nothing by default; abandonment is a valid result. - -## Plan - -Measure the production loss distribution before building. If losses are too -rare or bursty for the candidate codes to recover inside a group's lifetime, -record that result and stop. - -Try the cheapest bounded shapes first: parity across a group's tail packets, -datagram-level parity, then stream-data FEC frames. Keep all framing in the -selected QUIC fork; the MoQ wire does not change. - -Compare against [early retransmission](/quest/m2/quic-probe.md), not only plain -ARQ. Both spend the same spare-bandwidth budget on redundancy. Use the same -netem and real-NIC limits as the -[GCC experiment](/quest/m2/quic-gcc.md), and report delivery latency, goodput, -redundancy cost, and unrecovered group loss. - -## Required - -- [Probe capacity by early retransmission](/quest/m2/quic-probe.md) - supplies - the baseline this experiment must beat diff --git a/quest/m2/quic-io-boundary.md b/quest/m2/quic-io-boundary.md new file mode 100644 index 00000000000..69b8beef509 --- /dev/null +++ b/quest/m2/quic-io-boundary.md @@ -0,0 +1,34 @@ +# [L] Redesign the QUIC I/O boundary around io_uring + +## Goal + +`moq-quic`'s sans-IO boundary lets moq-uring receive from the kernel's +buffer ring and transmit into registered buffers, with no copy between the +kernel and the crypto. The API may break; it is in-tree. + +## Plan + +Decided in the 2026-09-30 plan: commit to the redesign, but start only after +a noq or `moq-quic` profile shows where ingress and egress spend their time. +No current profile is from noq, and every other copy is removed without an +API change by [Remove moq-uring copies](/quest/m1/perf/uring-copies.md). + +Candidates, to be ranked by the profile: + +- `Endpoint::handle` accepts a foreign-owned buffer (a buffer-ring slot), and + stream frames keep references to it instead of requiring an owned + `BytesMut`. +- `poll_transmit` writes into a caller slice or registered buffer as a + contract, not by relying on `Vec` capacity. +- One `handle` call takes a whole GRO batch. + +Registered TX buffers ([#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md)) +and `SENDMSG_ZC` ([#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md)) +build on the transmit contract. Report relay CPU per Gbps before and after on +the same workloads. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the redesign breaks `moq-quic`'s API +- [Relay profiles](/quest/m1/performance-profiles.md) - the redesign targets measured costs +- [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - the cheap wins land first, so the profile shows what is left diff --git a/quest/m2/quic-keep-alive.md b/quest/m2/quic-keep-alive.md index f4ebdf65303..609172872f4 100644 --- a/quest/m2/quic-keep-alive.md +++ b/quest/m2/quic-keep-alive.md @@ -5,7 +5,9 @@ A connection sends a PING only when its idle deadline is near, never on a fixed clock. An idle connection with a 30 s idle timeout costs one packet per roughly 30 s minus a few PTOs; a busy connection costs none. The -`keep_alive` interval knob on `quic::Client` and `quic::Server` goes away. +`keep_alive` setting on `quic::Client` and `quic::Server` becomes an optional +maximum, default none. Redefining it is a config and CLI break, so this +targets `dev`. ## Plan @@ -22,13 +24,20 @@ timeout by hand. Replace it in the fork: - Keep `keep_alive_interval` as a maximum: `None` means "as late as possible"; a value means "no later than this", for a NAT binding with a shorter life than the idle timeout. That is the only knob. -- The multipath per-path keep-alive follows the same rule per path. -moq-tokio drops `keep_alive` from the `[quic]` sections, CLI flags, and env -vars; NAT-sensitive deployments keep it as the new maximum, documented in -`doc/bin/relay/config.md`. The qmux WebSocket keep-alive (`qmux::ws::KeepAlive`, +moq-tokio's `quic.keep_alive` (`rs/moq-tokio/src/quic.rs`) in the `[quic]` +sections, CLI flags, and env vars becomes that optional maximum, default none, +documented in `doc/bin/relay/config.md` for NAT-sensitive deployments. The qmux WebSocket keep-alive (`qmux::ws::KeepAlive`, 5 s ping and 30 s deadline) already has this shape; make its wording match. Tests: an idle connection survives an idle timeout with exactly one PING per period; a busy connection sends none; a lost PING is probed before the deadline; the maximum knob shortens the period. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + +## Related + +- [noq#810](https://github.com/n0-computer/noq/issues/810) - the proposal to n0; flub and matheus23 asked to keep a cap for NAT bindings, which the optional maximum covers diff --git a/quest/m2/quic-kernel-pacing.md b/quest/m2/quic-kernel-pacing.md deleted file mode 100644 index f8d3b329153..00000000000 --- a/quest/m2/quic-kernel-pacing.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Kernel pacing - -## Goal - -A measured verdict on handing packet pacing to the kernel. Today noq's pacer -is a userspace token bucket on both runtimes: `poll_transmit` holds a train -until the pacing timer fires, which the io_uring driver arms through -`poll_timeout` like the tokio driver does, but a released GSO train still -leaves the NIC as one burst. The `flush_one` comment in -`rs/moq-uring/src/quic/noq/connection.rs` saying the driver ignores the hint -is stale from quiche. Either the kernel paces each train (`SO_TXTIME` with the `etf` or -`fq` qdisc, per-packet transmit times in the cmsg the driver already builds) -and burstiness at the bottleneck drops without costing CPU, or the burst is -shown not to matter on the fleet's paths. - -## Plan - -- Measure first: on a netem bottleneck, compare inter-packet gaps and queue - occupancy for a 64-segment GSO train against the same bytes paced at the - controller's rate. If the bottleneck absorbs the burst without loss or - delay at the fleet's typical rates, record it and stop. -- Then the io_uring path: stamp each GSO train with `SCM_TXTIME` at the time - noq's pacer would have released it, one timestamp per train (the kernel - spreads segments only with `fq`'s pacing, so test both qdiscs). The socket - is shared across connections per worker, so per-socket rate limits - (`SO_MAX_PACING_RATE`) cannot express per-connection pacing; only - per-packet times can. -- Report CPU per Gbps, loss, and p99 latency against the userspace pacer on - the tokio path and the unpaced io_uring path, on a real NIC as well as - loopback, since `etf` needs hardware offload to be exact. - -The verdict names which qdisc the relay hosts need, or that none is worth -configuring. - -## Related - -- [Send batching](/quest/m2/quic-send-batching.md) - the other syscall-side - lever on the same path -- [#3201](/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - - zero-copy on the same trains diff --git a/quest/m2/quic-probe.md b/quest/m2/quic-probe.md index f1e8ef3e065..ffe83c091c6 100644 --- a/quest/m2/quic-probe.md +++ b/quest/m2/quic-probe.md @@ -44,8 +44,13 @@ is not proof of full path capacity. Persist regressions in CI and broader network scenarios at least nightly. A measured no-go is a valid outcome; retain the baseline and record why before exposing an ineffective option. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related - [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - separate ProbeRTT policy experiment -- [FEC experiment](/quest/m2/quic-fec.md) - repetition competes for the redundancy budget -- [GCC egress experiment](/quest/m2/quic-gcc.md) - delay control changes what headroom means +- [GCC egress experiment](/quest/m3/quic-gcc.md) - delay control changes what headroom means +- [noq#811](https://github.com/n0-computer/noq/issues/811) - probing while app-limited, proposed to n0 +- [noq#476](https://github.com/n0-computer/noq/issues/476) - the earlier bitrate-probing ask diff --git a/quest/m2/quic-qmux.md b/quest/m2/quic-qmux.md new file mode 100644 index 00000000000..a131cdfb01b --- /dev/null +++ b/quest/m2/quic-qmux.md @@ -0,0 +1,84 @@ +# [XL] Run qmux on the QUIC stream state machine + +## Goal + +qmux lives in the monorepo and uses `moq-quic`'s stream state machine for +stream lifecycle, flow control, datagram buffering, priority scheduling, and +transport parameters. It owns only record framing, its transport adapters, +and the semantics that differ from QUIC, instead of maintaining a parallel +stream implementation. moq-tokio and moq-relay depend on the in-tree crate, +and moq-dev/web-transport no longer carries a Rust qmux. + +## Plan + +Decided in the 2026-09-30 plan: + +- **Scope is the Rust core plus adapters.** Port the prototype core and + moq-dev/web-transport's TCP, TLS, WebSocket, and UDS adapters, ALPN + negotiation, byte-stream framing, and socket stats (about 2.3k lines) onto + it, along with the `web-transport-trait` impl. The TypeScript `@moq/qmux` + and `@moq/web-socket-stream` stay in moq-dev/web-transport with their own + state machine and become the interop reference. +- **All four wire versions stay**: draft-02, draft-01, draft-00, and the + legacy `webtransport` format, since published clients (and the TS peer) + negotiate them. They differ only in record framing, so they share the one + state machine. +- **Shape**: the sans-IO part is `moq_quic::mux`, a module behind a feature, + so it reaches the stream state without widening `moq-quic`'s public API. + The tokio session, adapters, and trait impl are the `qmux` crate, published + from the monorepo under the existing crates.io name as its next breaking + version. moq-dev/web-transport removes its copy; the external dependents + (atmoq-moq-native, web-transport-ws) can move to the new release on their own schedule. + +Start from the green +[kixelated/quinn#2](https://github.com/kixelated/quinn/pull/2) prototype, +which is already quinn-based. Rebase it onto `moq-quic` and preserve its +central invariant: drive the +existing stream state machine through the same receive and write entry points +as QUIC, then treat serialization to the reliable underlying transport as the +acknowledgment. Do not copy the stream maps, flow-control accounting, reset +state, or datagram queues into a qmux-specific implementation. + +Keep the shared-core patch narrow. The prototype needs only module wiring, a +receive-offset accessor, frame-iterator access, and limited datagram helper +visibility. Review each exposure as a reusable internal boundary rather than +making the whole QUIC connection public. + +`RESET_STREAM_AT` is a QUIC extension, not a qmux-specific frame. Once the +reliable-reset quest lands, make qmux drive that shared send and receive state +instead of retaining the prototype's local parsing and transitions. + +Carry the hierarchical send groups from the scheduler quest into qmux's +record writer. Qmux over TCP, TLS, WebSocket, Unix sockets, and in-memory +duplex transports must produce the same subscription fairness and intra-group +ordering as raw QUIC. This quest owns qmux integration of the scheduler's +reusable acceptance fixtures, including byte fairness, strict priority, +newest/oldest group ordering, cancellation, and blocked-stream behavior. +The native scheduler does not wait for this dependent proof. + +Add the missing wire evidence before release: golden vectors for each of the four versions, +bidirectional interoperability against the last web-transport `qmux` release (0.6.x), and +the TypeScript qmux/WebSocket peer used by `js/net`. Preserve rejection of +prohibited QUIC frames, params-first setup, record-size validation, close and +reset semantics (the first recorded close wins, as close codes #4262 +settled on dev), keep-alive behavior, and bounded flow-control tests. + +There must be one stream state machine in the dependency graph. + +Verify minimal, default, and all-feature builds so enabling iroh, qmux, or +the uring runtime never unifies two copies of the stream state. + +Decided in the 2026-09-30 audit: moved to m2, since no m1 quest consumes it; +the fork plan the same day kept it there. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - qmux drives `moq-quic` +- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - qmux reuses the + extension's stream state rather than implementing reset locally +- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - qmux must + expose the same scheduling contract as native QUIC + +## Related + +- [noq#812](https://github.com/n0-computer/noq/issues/812) - the qmux proposal to n0 diff --git a/quest/m2/quic-send-batching.md b/quest/m2/quic-send-batching.md deleted file mode 100644 index e33dea0d726..00000000000 --- a/quest/m2/quic-send-batching.md +++ /dev/null @@ -1,28 +0,0 @@ -# [S] Send batching across connections - -## Goal - -A measured verdict on batching sends across connections. The tokio path sends -one `sendmsg` per GSO train per connection; a worker flushing many small -connections pays a syscall each. `sendmmsg` submits every ready train in one -call. The io_uring path already queues one SQE per train and submits them -together, so the question there is whether it already gets the benefit. - -## Plan - -- Add `sendmmsg` to `moq-noq-udp` behind the existing GSO path: the runtime - collects the trains ready across connections in one poll and submits them - together, falling back to per-train `sendmsg` on partial failure the way - the GSO fallback does. -- Measure syscalls per second and CPU per Gbps on the chat and fanout shapes - with many connections, tokio workers versus io_uring workers, before and - after. Confirm from the io_uring worker's `enters` counter that the ring - already amortizes the same way. - -A measured no-win abandons the tokio change; the io_uring result is recorded -either way. - -## Related - -- [Kernel pacing](/quest/m2/quic-kernel-pacing.md) - pacing per train - changes what a batch can contain diff --git a/quest/m2/redundant-ingest.md b/quest/m2/redundant-ingest.md deleted file mode 100644 index 241fe5bb33b..00000000000 --- a/quest/m2/redundant-ingest.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Redundant ingest under one epoch - -## Goal - -Decide whether and how two live publishers of identical content share one -broadcast, so viewers survive losing one faster than the QUIC keep-alive. -The study may end in a no-go. - -## Plan - -Start from what is documented today (`doc/bin/cli.md` "Redundant -publishers"): two encoders sharing a Hop ID (`--hop 42`) are one first hop, -so relays hold both routes and fail over at a group boundary under the #3312 -same-first-hop rule, provided the tracks are identical with aligned groups. - -Open questions: how that maps onto epochs (the pair claiming one -`@`), what enforces the alignment the docs only ask for (group -sequences, a matching catalog), and who declares the incumbent dead early: a -failover service that retracts it, or active-active delivery to the relay. -[Cluster routing](/quest/m1/cluster-routing.md) drops hop lists inside a -cluster and must decide what replaces this failover; follow its answer. -Weigh them against the moq-transport rule that multiple publishers of a -namespace must each be asked (#3697) and the cluster draft. Output: a -decision, with a quest for the chosen mechanism. - -## Related - -- [Same-hop importers](/quest/m1/hop-aligned-import.md) - identical tracks from one encoded stream under one first hop, the case this generalizes -- [Cluster routing](/quest/m1/cluster-routing.md) - decides what replaces first-hop failover inside a cluster -- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - explicit epochs are what a redundant pair would share diff --git a/quest/m2/relay-io-uring-package.md b/quest/m2/relay-io-uring-package.md index 23dc0e46d91..7e82c06e82a 100644 --- a/quest/m2/relay-io-uring-package.md +++ b/quest/m2/relay-io-uring-package.md @@ -38,4 +38,6 @@ Public API: none. Wire: none. - [Flow-control windows](/quest/m1/uring-flow-control-windows.md) - the `[quic]` section must not be refused at startup on the ring - [Close before teardown](/quest/m1/quic/uring-close.md) - sessions on the - ring must end with their application close + ring must end with their application close; probably fixed by + [#4431](https://github.com/moq-dev/moq/pull/4431), so re-run its repro + before starting and drop this blocker if it passes diff --git a/quest/m1/rs2ts/ietf.md b/quest/m2/rs2ts-ietf.md similarity index 71% rename from quest/m1/rs2ts/ietf.md rename to quest/m2/rs2ts-ietf.md index b72b735753e..75390d156e1 100644 --- a/quest/m1/rs2ts/ietf.md +++ b/quest/m2/rs2ts-ietf.md @@ -14,7 +14,10 @@ they stay exact as `U64` and only fail where code converts them to Public API: breaks `@moq/net`; retargets to `dev`. Wire: none. +Decided in the 2026-09-30 audit: deferred to m2 until generated lite passes +its no-downgrade go/no-go in the [rs2ts line](/quest/m1/rs2ts/README.md). + ## Required - [Generated lite](/quest/m1/rs2ts/lite.md) - the pipeline this reuses -- [Sans-IO IETF session](/quest/m1/rs2ts/sans-io/ietf.md) - the session shape it translates +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the session shape it translates diff --git a/quest/m1/rs2ts/sans-io/ietf.md b/quest/m2/rs2ts-sans-io-ietf.md similarity index 85% rename from quest/m1/rs2ts/sans-io/ietf.md rename to quest/m2/rs2ts-sans-io-ietf.md index 542c1965a11..a6d764f4e3d 100644 --- a/quest/m1/rs2ts/sans-io/ietf.md +++ b/quest/m2/rs2ts-sans-io-ietf.md @@ -16,6 +16,9 @@ first with the IETF session behind it, move the session out. Public API: breaks moq-net's IETF session API; retargets to `dev`. Wire: none. +Decided in the 2026-09-30 audit: deferred to m2 with generated IETF, its only +consumer, until generated lite passes its go/no-go. + ## Required - [Sans-IO lite session](/quest/m1/rs2ts/sans-io/lite.md) - sets the driver shape diff --git a/quest/m2/runtime-qa-hosts.md b/quest/m2/runtime-qa-hosts.md deleted file mode 100644 index 983c22443c1..00000000000 --- a/quest/m2/runtime-qa-hosts.md +++ /dev/null @@ -1,43 +0,0 @@ -# [L] On-demand runtime QA hosts - -## Goal - -An agent can submit an exact checkout to an available Linux or hardware test -host and retrieve results, logs, and symbols through a repeatable command. -Unsupported or inaccessible environments remain explicit verification gaps. - -## Plan - -Hosted Windows/macOS recipes compile platform code, while -`quest/m3/video-hardware.md` and `quest/m1/dart-ios.md` already own physical -validation work. This quest supplies the reusable access and execution contract, -not another list of codec or device bugs. - -- Inventory existing authorized hosts and devices first: OS/architecture, - kernel/io_uring capability, GPU/driver, media devices, display/session access, - and debugger/packet-capture permissions. Installed SSH or LLDB is not proof - that a suitable target is reachable. Do not provision paid infrastructure. -- Implement a host-side job runner plus a local submit/status/cancel/artifacts - recipe. Address an immutable source snapshot and record its digest; do not - test whichever branch the remote directory happens to contain. -- Start with one disposable Linux CPU runner for transport/runtime tests. Give - jobs isolated directories, resource limits, leases, and bounded cleanup. - Run untrusted PR code without production credentials or persistent access to - other jobs. Use existing CI or SSH access rather than adding a public service. -- Add one available device profile as proof of extensibility. Keep camera, - microphone, portal, signing, and interactive-session authorization explicit; - report unavailable devices rather than silently using a software fallback. -- Support test-owned stack capture and read-only log/metrics/artifact retrieval. - A separate debug session may retain a failed process with an expiring lease. - Document the human handoff when a permission prompt or device action is needed. - -Acceptance: submit a known SHA, recover its complete evidence, cancel a hung -job, and verify no child process or device lease remains. A mismatched source -digest or absent required backend must fail capability validation. Demonstrate -one real Linux runtime scenario and one available device scenario; if no device -is available, split that rollout into an explicit externally blocked follow-up. - -## Related - -- [Video hardware validation](/quest/m3/video-hardware.md) - owns real encoder/capture/zero-copy verdicts -- [Dart on iOS](/quest/m1/dart-ios.md) - owns simulator/device packaging validation diff --git a/quest/m2/sei.md b/quest/m2/sei.md new file mode 100644 index 00000000000..369c8d583b8 --- /dev/null +++ b/quest/m2/sei.md @@ -0,0 +1,39 @@ +# [S] Measure whether SEI separation is worthwhile + +## Goal + +Record enough evidence to decide whether a separate SEI track is worth its +framing and reassembly cost. Keep H.264 and HEVC SEI inline while this is +unresolved; a no-go verdict is a valid outcome. + +## Plan + +Decided in the 2026-09-30 audit: collapse the line into this study. The +schema, Rust, and web reinsertion quests were deleted; they only make sense +after a positive verdict, and would be re-scoped from it. + +Measure SEI payload types, bytes, and cadence on representative H.264 and HEVC +inputs. Separate small timing/display metadata, captions, encoder information, +and arbitrary vendor data. Identify a concrete metadata-only consumer if one +motivates the feature. Do not infer typical savings from a synthetic large +payload or from the codec permitting one. + +Compare current inline delivery with the bytes a video-only subscriber could +avoid, including any marker/sidecar overhead. Report total storage separately: +putting the same bytes in two tracks does not itself reduce a complete archive. + +Account for recovery points, display metadata, captions, and unknown payloads; +identify what must remain inline or be restored for each supported receiver. +A deadline bounds waiting but cannot prove absent metadata never existed. +Include loss, late arrival, and consumer compatibility in the tradeoff. + +Return a recommendation for maintainer agreement. A positive verdict scopes +which payloads move, whether extraction is opt-in, and the association and +latency contract, then files the follow-on quests. A negative verdict ends the +line without affecting captions or unrelated timed-metadata carriage. + +## Related + +- [Catalog colour model](/quest/m2/color-catalog.md) - preserves display metadata semantics +- [fMP4 emsg](/quest/m2/emsg.md) - independently settles carriage for metadata already outside video +- [CEA-608/708](/quest/m2/captions-cea.md) - can read inline caption SEI without waiting for this experiment diff --git a/quest/m2/sei/README.md b/quest/m2/sei/README.md deleted file mode 100644 index da44b7e4f84..00000000000 --- a/quest/m2/sei/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# SEI separation evaluation - -## Goal - -Keep H.264 and HEVC SEI inline unless measured savings or a concrete -metadata-only consumer justify separate delivery. Evaluate that tradeoff before -committing a catalog, marker, or reassembly format. - -## Plan - -SEI separation is deferred. Existing metadata consumers may inspect the inline -bitstream; this line does not block captions or unrelated timed-metadata -carriage. The schema and implementation quests are conditional follow-ons, -not permission to strip by default. A no-go verdict abandons them. - -Preserve decoder, display, recovery-point, and caption behavior. Raw vendor -payloads may be large, but that does not establish typical bandwidth savings. -Total storage and bytes delivered to a video-only subscriber are different -measurements. Any future split must state which payloads move and how missing -metadata is handled; do not promise byte-faithful export after a deadline miss. - -## Required - -- [SEI evidence](/quest/m2/sei/evidence.md) - measure savings and identify a consumer before deciding whether to split -- [SEI section](/quest/m2/sei/sei.md) - define a format only after a positive verdict and settled association policy -- [Rust split and reinsert](/quest/m2/sei/sei-rust.md) - implement the approved split and bounded export behavior -- [Web access](/quest/m2/sei/sei-web.md) - expose approved sidecar samples independently of video - -## Related - -- [fMP4 emsg](/quest/m1/emsg.md) - independently settles carriage for metadata already outside video -- [Colour model](/quest/m1/color-model.md) - preserves display metadata semantics -- [CEA-608/708](/quest/m1/captions-cea.md) - can read inline caption SEI without waiting for this experiment diff --git a/quest/m2/sei/evidence.md b/quest/m2/sei/evidence.md deleted file mode 100644 index 259915fdac5..00000000000 --- a/quest/m2/sei/evidence.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] Measure whether SEI separation is worthwhile - -## Goal - -Record enough evidence to decide whether a separate SEI track is worth its -framing and reassembly cost. Keep SEI inline while this is unresolved; a no-go -verdict is a valid outcome. - -## Plan - -Measure SEI payload types, bytes, and cadence on representative H.264 and HEVC -inputs. Separate small timing/display metadata, captions, encoder information, -and arbitrary vendor data. Identify a concrete metadata-only consumer if one -motivates the feature. Do not infer typical savings from a synthetic large -payload or from the codec permitting one. - -Compare current inline delivery with the bytes a video-only subscriber could -avoid, including any marker/sidecar overhead. Report total storage separately: -putting the same bytes in two tracks does not itself reduce a complete archive. - -Account for recovery points, display metadata, captions, and unknown payloads; -identify what must remain inline or be restored for each supported receiver. -Compare inline markers, sidecar coverage, and bounded best-effort joining only -if the use case justifies pursuing a split. A deadline bounds waiting but -cannot prove absent metadata never existed. Include loss, late arrival, and -consumer compatibility in the tradeoff. - -Return a recommendation for maintainer agreement. A positive verdict scopes -which payloads to move, whether extraction is opt-in, and the association and -latency contract before the schema or implementation quests start. A negative -verdict abandons the remaining separation quests without affecting unrelated -timed-metadata carriage. diff --git a/quest/m2/sei/sei-rust.md b/quest/m2/sei/sei-rust.md deleted file mode 100644 index b8df34ff0e0..00000000000 --- a/quest/m2/sei/sei-rust.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] Rust SEI split and reinsert - -## Goal - -Rust importers strip H.264/H.265 SEI out of the access unit into the Hang `sei` -sidecar, and Rust exporters put it back byte-faithfully. A round trip through -any supported container reproduces the original bitstream. - -## Plan - -Implement one codec-aware split and reinsert primitive in `moq-mux` and reuse it -from every container gateway rather than creating gateway-local copies. -Apply the split policy selected by the section quest. Preserve inline -payloads that it excludes from splitting, and do not assume arbitrary SEI -can be removed without affecting receiver behavior. - -The exporter joins by group sequence and frame ordinal and restores prefix and -suffix placement and ordering. Placement is exact or it is a loss; there is no -useful approximate reinsertion. - -Export is a live consumer of two independently scheduled tracks, so state its -join budget rather than assuming the sidecar is already there. Reinsert within -the mux buffer the exporter already holds for its audio and video interleave, -and past that budget report the gap using the section's presence signal and -continue. No delivery guarantee is needed, only a stated deadline and an -honest account of what missed it: a silent drop would let export claim a -byte-faithful bitstream it did not produce. - -Round-trip exact NAL bytes through Annex B, length-prefixed samples, MPEG-TS, -and fMP4. Exercise a video-only subscription, a sidecar-only subscription, -a sidecar arriving after its video frame, reconnect at a group boundary, and -bounded cleanup of sidecar samples whose video frame never arrives. - -## Required - -- [SEI section](/quest/m2/sei/sei.md) - defines the catalog and correlation - contract diff --git a/quest/m2/sei/sei-web.md b/quest/m2/sei/sei-web.md deleted file mode 100644 index 0c21839431a..00000000000 --- a/quest/m2/sei/sei-web.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Web SEI access - -## Goal - -The web Hang stack discovers `sei` sidecars and exposes their samples to -applications, so a browser can read timecode, ad markers, or telemetry without -subscribing to the video track at all. - -## Plan - -Add typed catalog bindings for the section and a subscriber that yields raw SEI -samples keyed by the video group sequence and frame ordinal they came from, the -exact identity the section defines, with the frame timestamp carried as data -for presentation-time sync. Keep it independent -of the decode path: this quest exposes raw sidecar samples. The section -contract must separately establish which payloads can be moved without -requiring restoration before decoding or display. - -Applications parse the NAL payloads themselves with whatever vocabulary they -need, so a new payload type requires no change here. - -Test a sidecar-only subscriber with the video track never requested, a -subscriber that takes both, late join, and reconnect. Prove that a backgrounded -tab consuming only the sidecar draws no video bandwidth. - -## Required - -- [SEI section](/quest/m2/sei/sei.md) - defines the catalog and correlation - contract diff --git a/quest/m2/sei/sei.md b/quest/m2/sei/sei.md deleted file mode 100644 index 5dd18fd98d5..00000000000 --- a/quest/m2/sei/sei.md +++ /dev/null @@ -1,54 +0,0 @@ -# [S] SEI catalog section - -## Goal - -Hang defines a top-level `sei` section that relates raw H.264 and H.265 SEI NAL -units to the video access unit they were stripped from. The contract is -sufficient for byte-faithful reinsertion on export and for an application that -subscribes to the sidecar alone. - -## Plan - -The framing below is provisional pending the split-policy and association -decision. Do not treat per-access-unit coverage as settled. - -This is a candidate codec-sidecar contract, not the prerequisite for unrelated -ID3, SCTE-35, emsg, or FLV metadata carriage: a metadata track belongs to exactly one -rendition, uses that rendition's group sequence, stamps each frame with the -wire timestamp of the media it accompanies, and carries raw bytes. A 1080p and -a 360p rendition carry different SEI, so there is one sidecar per video -rendition, and group 7 of the sidecar holds the SEI for group 7 of its video. - -Within a group the frame's wire timestamp is the key, so an application -syncing to presentation time reads it directly instead of joining against the -video track it deliberately did not subscribe to. Several access units can -share a timestamp on the raw Annex B path (`h264::Split::decode` resolves one -clock value per call and gives it to every access unit in that chunk), so the -frame's ordinal within the group disambiguates those; it is a tie-break, not -the identity. - -Preserve prefix or suffix placement, original NAL bytes, and order when -several SEI units accompany one access unit. The codec is the mapped video -rendition's, not serialized again in the sidecar. Placement has to be exact, not -approximate: `recovery_point` on the wrong access unit misdirects a receiver's -tune-in, `pic_timing` breaks field cadence and pulldown, and reordered -CEA-608/708 byte pairs garble a stateful caption decoder. - -Represent whether an access unit had SEI, so a consumer can tell "there was -none" from "lost, pruned, or not yet arrived". Missing SEI is common and valid, -but an exporter cannot claim a byte-faithful reinsertion it did not make, and -without this signal that loss is unreportable. - -Nothing in the video framing changes: the presence signal lives in the sidecar -track's own coverage, not as a flag on video frames, because no consumer blocks -on a sidecar to release a video frame. - -Version the schema so a later semantic view can be added without rewriting the -raw contract. Include fixtures for H.264 and H.265 prefix and suffix SEI, -multiple NAL units on one access unit, frames with no SEI, several access units -sharing one timestamp, and group boundaries. - -## Required - -- [SEI evidence](/quest/m2/sei/evidence.md) - positive evidence is needed before committing the format -- Maintainer approval of a positive split verdict, eligible payloads, and the association and latency policy. diff --git a/quest/m1/signed-priority.md b/quest/m2/signed-priority.md similarity index 78% rename from quest/m1/signed-priority.md rename to quest/m2/signed-priority.md index 756dd4bf0d1..fd520e1960b 100644 --- a/quest/m1/signed-priority.md +++ b/quest/m2/signed-priority.md @@ -19,11 +19,10 @@ Decided with the maintainer: range, with no saturation. An unset priority goes out as IETF 127, not the draft's usual 128, and an absent IETF priority decodes to 0, the unset default. Pin both ends in tests. -- Invariant, kept from the [moxygen line](/quest/m1/moxygen/README.md)'s - default-priority quest (#4273): one urgency on both wires, so the IETF byte - is always `255 -` the lite byte. Mapping IETF as `128 - p` to hit the - draft's 128 would break it, which is why the default is one step off the - draft there. +- Invariant, kept from the default-priority change (#4273): one urgency on + both wires, so the IETF byte is always `255 -` the lite byte. Mapping IETF + as `128 - p` to hit the draft's 128 would break it, which is why the + default is one step off the draft there. - hang's built-in priorities move above 0, so hang media outranks a track that never set one. Something like catalog 40, text 30, audio 20, video 10; the spacing is the implementer's call. Rust and JS keep matching values. @@ -44,10 +43,11 @@ moq-archive's `Info::priority` follows. Its version-1 `.info` stores the Report the wire impact in the PR: none in format, but the default byte moves again, from 127 to 128 on moq-lite and from 128 to 127 on IETF. -## Required - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - ships the 127 default and the one-urgency invariant this re-maps +Decided in the 2026-09-30 audit: moved to m2. It stays deferred unless it +ships in the same `dev` release as the moxygen default change, so the default +byte moves once instead of twice. ## Related - [Scope track priority](/quest/m1/track-priority-scope.md) - which streams a priority competes with, not its type +- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - reworks the same priority arithmetic in the transport diff --git a/quest/m2/sip-stack.md b/quest/m2/sip-stack.md deleted file mode 100644 index da2df3dabbb..00000000000 --- a/quest/m2/sip-stack.md +++ /dev/null @@ -1,34 +0,0 @@ -# [L] SIP media stack - -## Goal - -A `moq-sip` crate that terminates one inbound audio call leg: INVITE-only SIP -over UDP/TCP/TLS, SDP offer/answer for Opus and G.711 (SRTP when offered), and -a plain RTP media leg exposed to the embedder as Opus frames in and out. -Registrar, outbound, video, and DTMF are out of scope; REGISTER gets 405 and -RFC 4733 telephone-events are ignored. This quest completes when the crate is -consumable by an embedder. - -## Plan - -- Open with an evaluation, spike-backed like the - [WebRTC bridge verdict](/quest/m2/livekit-webrtc-bridge.md): drive a real - inbound call through the candidate full Rust SIP stacks (ezk-sip, rvoip, - and whatever else is current) and adopt the one that holds up. Fallback if - none do: an existing parser crate (e.g. rsip) for message/SDP syntax plus a - minimal own INVITE-only transaction and dialog engine - the surface is - small once registrar, proxy, and outbound are out. -- The media leg is plain negotiated RTP: `moq-rtc`/str0m is ICE/DTLS-first - and its reusable session internals are crate-private, so it is precedent, - not a base. Consider publicizing moq-rtc's codec bridges rather than - duplicating the RTP-to-hang mapping, and reuse `moq-audio`'s Opus codec - for the G.711<->Opus transcode, with rate conversion through - `decode::Output` and `encode::Input` since the resampler is private (mono - 8 kHz; G.711 companding is new code, nothing in the repository has it). -- RTP wall-clock normalization off RTCP sender reports, as moq-rtc does. -- The embedder decides paths and auth; the crate's API is - "answer this INVITE, give me the caller as Opus, take Opus to play" plus - call teardown. Silence generation until playback audio exists lives here, - so every embedder gets answer-with-silence for free. -- The SIP edge gateway and line provisioning that consume this crate as an - inbound-call product are moq.pro (downstream) work. diff --git a/quest/m1/qos/starvation-frames.md b/quest/m2/starvation-frames.md similarity index 92% rename from quest/m1/qos/starvation-frames.md rename to quest/m2/starvation-frames.md index 34ab0a1adf3..bb71aa27221 100644 --- a/quest/m1/qos/starvation-frames.md +++ b/quest/m2/starvation-frames.md @@ -41,6 +41,10 @@ Backends that return unsupported from `poll_acked` keep the group-granularity sampling from the parent quest, so the histogram never disappears over qmux or a browser transport; document which resolution a node offers. +Decided in the 2026-09-30 audit: moved to m2. The group-granularity sampler +from the parent quest answers the m1 question, and this waits on the m2 ACK +hook. + Tests: the frontier tracking frame ends under a peer that acknowledges in bursts, with interval samples landing one bucket lower than group-granularity tracking of the same run; a reset mid-group attributing only the @@ -52,5 +56,5 @@ unsupported. - [Starvation](/quest/m1/qos/starvation.md) - fixes the wire shape and the group-granularity fallback -- [poll_acked in web-transport](/quest/m1/quic/ack-hook.md) - the released +- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the released hook this samples through diff --git a/quest/m2/stats-delta.md b/quest/m2/stats-delta.md index 475e7c65322..04e757a8af7 100644 --- a/quest/m2/stats-delta.md +++ b/quest/m2/stats-delta.md @@ -76,10 +76,9 @@ Design points left open for the implementer: - Extensibility: if every field is a varint, a reader can skip mask bits it does not know, so fields append without breaking old readers. Decide that or refuse unknown bits loudly, and say which. -- Gauges: the [client stats](/quest/m1/qos/stats/README.md) extension adds - non-monotonic gauges (a latency, a target bitrate). Encode them absolute or - zigzag, or have a producer with a non-`()` extension refuse this flavor, and - document the contract. +- Gauges: none today. Media stats, with their latency and bitrate gauges, + ride hang tracks rather than a moq-stats extension, so this flavor encodes + relay frames only. - Measure `sessions` (`Presence`) too; the benchmark skipped it. - Sweep the aggregate over node publishers x entries per node, for both flavors; the benchmark above only varied one relay's stream, so it cannot @@ -95,8 +94,7 @@ which is a published API break and goes to `dev` unless additive. `TrafficFrame` / `SessionsFrame`. The JS decoder is about 120 lines and dependency-free apart from inflate (`@moq/flate`); read varints through `BigInt` or split 32-bit halves, since counters exceed 2^53. It belongs with -the JS stats reader, `@moq/stats` if [browser reporters](/quest/m1/qos/stats/js.md) -has landed by then. Share fixtures between Rust and JS so the two stay wire +the demo dashboard's relay-stats reader. Share fixtures between Rust and JS so the two stay wire identical, and keep the benchmark in-tree, wired into CI at least nightly. **Docs and spec.** No IETF draft covers stats today. Write the format into @@ -108,8 +106,11 @@ maintainer's call; ask before writing one. Public API impact: additive on moq-stats unless the helpers change. Wire impact: new on-demand tracks; existing tracks unchanged. +## Required + +- [Bench coverage](/quest/m2/bench-coverage.md) - its stats producer benchmark is the moq-json snapshot encoder profile the gate needs + ## Related - [Stats format page](/doc/concept/stats.md) - where the new flavor is documented -- [Client stats](/quest/m1/qos/stats/README.md) - the extension and gauges the format must carry or refuse -- [Compressed tracks](/quest/m2/flate/README.md) - group-scoped DEFLATE tracks, whose group-window discipline this flavor repeats +- [Compressed tracks](/quest/m2/flate.md) - group-scoped DEFLATE tracks, whose group-window discipline this flavor repeats diff --git a/quest/m2/stats-encoder-feedback.md b/quest/m2/stats-encoder-feedback.md new file mode 100644 index 00000000000..7a160a3e948 --- /dev/null +++ b/quest/m2/stats-encoder-feedback.md @@ -0,0 +1,90 @@ +# [M] A Rust encoder adapts its bitrate to what its viewers report + +## Goal + +A `moq-video` or `moq-audio` encode producer given a feedback handle solicits +feedback in its catalog. It reads the feedback track from every `.echo` +broadcast announced under the catalog's echo path, and lowers its bitrate +while viewers report stalls and late frames, beside the congestion estimate +it already follows. Keyframe requests stay out. + +## Plan + +Deferred to m2 in the 2026-09-30 audit: no named consumer; the media stats it +reads land first in m1. + +- `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer + options, beside `bandwidth`) gains `echo: Option`. + - The handle is built from an `origin::Consumer` and the echo path, + resolved against the publisher's broadcast. + - It consumes `.echo` announcements under that path, subscribes to the + feedback track on each, and reads its own renditions by alias. + - It folds the reports into one signal: the share of viewers stalled over + the last interval and their late frame rate, weighted equally per viewer. + - The counters are cumulative, so the handle keeps the previous snapshot + per viewer and diffs it. A counter that goes backwards means a restarted + viewer and resets that baseline. + - A viewer counts toward a rendition while its latest snapshot has a row + for that alias, so viewers of other rungs, or ones that switched away, + never dilute the share. The announcement, not the age of its last + report, keeps that snapshot current: an unchanged snapshot sends no frame, so a quiet healthy + viewer must not age out. Diffing already makes one stall long + ago contribute nothing to later intervals. +- Trust (2026-09-29): the token prefix is the boundary. Any viewer the + application's tokens let publish under the echo path counts. How far + viewers may move the target is application-specific (a simulcast ladder + suffers less from one viewer than a single rendition), so the step-down + policy is built in but takes a tunable config struct: a minimum viewer + count or quorum, a bitrate floor, and the stalled-share threshold, with a + way to disable it. Reason: a safe default without hard-coding one + application's policy. +- `moq_mux::rate::Control` takes that signal beside the bandwidth estimate. + A stalled share above the threshold steps the target down like a bandwidth + drop, never below the floor; recovery follows the existing decay ramp, + and the estimate stays the ceiling. Audio does not follow its grant today + (`Options::bandwidth` in `rs/moq-audio/src/encode/producer.rs` reserves + only). It follows this signal only once the grant quest lands; until then + the loop drives video. +- `moq import --echo ` and `moq transcode --echo ` set the + catalog's `echo` section and wire the handle. Each rung of the ladder + reads its own renditions. +- Test: the CLI publishes to a relay, and two `moq play --echo` viewers + report under the echo path, one of them throttled through the impairment + profile. The target bitrate drops within two intervals of the throttled + viewer reporting stalls, and recovers after it stops. A unit test on mocked + time checks that the quorum and floor bound one viewer's influence. +- A benchmark sweeps viewers and renditions per snapshot, runs at least + nightly, and shows one interval's fold growing with the rows it reads, not + a full-table scan per rendition. +- Document the flag in `doc/bin/cli.md` and the loop and its config in the + moq-video README. + +Open, to settle before starting (moved from the +[media stats](/quest/m1/stats/README.md) line): + +- **Referenced-rendition feedback.** A derivative catalog (a `moq-transcode` + passthrough) collects feedback for a source rendition it lists, but owns + no encoder for it, and the source encoder reads only its own catalog's + prefix. Candidates: the derivative forwards those rows to the source's + echo path, or the source encoder also reads catalogs that reference it, + or referenced renditions stay report-only. +- **Shared echo prefixes.** Two catalogs can resolve their echo paths to one + prefix (`../viewers` from `room/a/live` and `room/b/live`). Then a viewer + using one name for both closes one `.echo` with the other, and each + publisher reads the other's reports under a shared alias. Candidates: + require each catalog's echo prefix to be its own, as application policy + like the token rights, or carry the catalog's broadcast in the snapshot + and ignore reports for another. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the `echo` section and feedback snapshot +- [Rust reporters](/quest/m1/stats/rust.md) - the viewers that report and + the CLI it wires + +## Related + +- [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - + the audio rate follow this signal would feed +- [Ladder](/quest/m2/ladder/README.md) - the transcode ladder that adapts to + its uplink today diff --git a/quest/m2/teleop/README.md b/quest/m2/teleop/README.md index 2f8062cec14..94353878040 100644 --- a/quest/m2/teleop/README.md +++ b/quest/m2/teleop/README.md @@ -5,12 +5,16 @@ MoQ carries a robot's video down and its control up on one session, as a library capability rather than a demo convention. -Generic in the library, integration-shaped in the proofs: Kyber is the first -transport replacement, while ArduPilot remains the first open protocol and -flight integration. The primitive is what any teleoperated machine needs. The -Kyber integration itself (replacing Kymux with moq-net and hang for Kyber's -media, input, feedback, and control) lives in Kyber's own repository, so it -has no quests here. +Generic in the library: the primitive is what any teleoperated machine needs, +and integrations are adapters on top of it. ArduPilot is the first open +protocol and flight integration, parked in m3 until a real ArduPilot user or +partner shows up. + +Decided in the 2026-09-30 audit: the ROS 2 bridge was deleted, cross-track +correlation folded into [robot](/quest/m2/teleop/robot.md), V4L2-M2M encoding +folded into [CLI packaging](/quest/m1/cli-packaging.md), and the MAVLink +bridge, SITL proof, and browser package moved to m3. Kyber is a competitor +with proprietary framing, not a transport we replace. ## Plan @@ -25,9 +29,9 @@ demo and private to it. Every integrator rebuilds the announce fan-in, the operator arbitration, and the latency instrumentation from scratch. The hang catalog is no longer a gap: it advertises data tracks in its `json` -and `binary` sections beside video and audio. What is genuinely missing is -`moq-video`'s V4L2-M2M encoder backend in a released `moq-cli`, so the boards -that fly have no native hardware-encode path anyone can install. +and `binary` sections beside video and audio. The other missing piece, +`moq-video`'s V4L2-M2M encoder in a released `moq-cli`, is tracked by +[CLI packaging](/quest/m1/cli-packaging.md). ### Two delivery classes, one session @@ -49,7 +53,7 @@ The split is a framing decision, not a subscription flag, and `moq-json` and modes. What that means for the primitive is in [robot](/quest/m2/teleop/robot.md), and what it means for a protocol multiplexing many message rates onto one link is in -[mavlink](/quest/m2/teleop/mavlink.md). +[mavlink](/quest/m3/teleop-mavlink.md). ### Who is already here @@ -86,33 +90,24 @@ stating plainly because it is what a builder is comparing against. - [Operator arbitration](/quest/m2/teleop/arbitration.md) - exactly one controller commands a vehicle at a time, with explicit handoff and a stated authorization boundary -- [MAVLink bridge](/quest/m2/teleop/mavlink.md) - a `moq-mavlink` gateway - replacing the VPN plus two unmanaged UDP flows, with QGroundControl and - friends unchanged -- [Browser teleoperation package](/quest/m2/teleop/browser-package.md) - `@moq/robot` - mirrors the Rust crate, so browser clients consume the catalog and delivery - classes -- [SITL proof and browser ground station](/quest/m2/teleop/proof.md) - ArduPilot - SITL and a synthetic camera flown from a browser ground station, reproducible - in five minutes -- [V4L2-M2M encoding](/quest/m2/teleop/v4l2-encode.md) - a released `moq-cli` - reaches `moq-video`'s hardware encoder on the boards that fly, and the boards - worth buying are written down - [Teleoperation use-case docs](/quest/m2/teleop/docs.md) - `doc/concept/use-case/` gains a teleoperation page, with a runnable non-media example beside it -- [ROS 2 bridge](/quest/m2/teleop/ros2.md) - a ROS 2 bridge sibling to the - MAVLink one, carrying topics over the same two delivery classes -- [Cross-track correlation](/quest/m2/teleop/correlation.md) - a command, the - telemetry it produced, and the video frame showing the result share one - timebase ## Related - [e2ee](/quest/m1/e2ee/README.md) - the answer for a protected control link -- [Text schema](/quest/m1/text-schema.md) - non-media tracks in a catalog, - arrived at from the media side -- [Client stats](/quest/m1/qos/stats/schema.md) - publisher-reported stats - as a `.stats` broadcast (moq#2734); teleop's latency instrumentation - extends that extension rather than adding a second stats surface +- [Media stats](/quest/m1/stats/schema.md) - publisher-reported stats + on a catalog-announced track (moq#2734); teleop's latency instrumentation + extends those types rather than adding a second stats surface - [Video hardware validation](/quest/m3/video-hardware.md) - the VAAPI run that covers Intel ground robots and NUC companions +- [CLI packaging](/quest/m1/cli-packaging.md) - ships the V4L2-M2M encoder the + boards that fly need +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway, + parked until a real ArduPilot user or partner +- [SITL proof and browser ground station](/quest/m3/teleop-proof.md) - ArduPilot + SITL flown from a browser, parked with the bridge +- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) - + `@moq/robot` mirroring the Rust crate, parked with the bridge +- [Text schema](/quest/m2/text-schema.md) - non-media tracks in a catalog, + arrived at from the media side diff --git a/quest/m2/teleop/correlation.md b/quest/m2/teleop/correlation.md deleted file mode 100644 index bb8e60ac914..00000000000 --- a/quest/m2/teleop/correlation.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Cross-track correlation - -## Goal - -A command, the telemetry sample it produced, and the video frame showing the -result share one timebase, so a teleoperation recording is usable as training -data and an operator can be shown what the machine actually saw. - -## Plan - -The two hosts' clocks are related by deployment assumption, not by the library: -a robot deployment already synchronizes both ends. Each broadcast's fixed -catalog-root `clock: { wall, timescale }` is the bridge. Media and command -tracks keep their own timescales; convert PTS explicitly into the broadcast -clock before joining samples. The robot's video and telemetry share a clock; -the operator's command broadcast supplies its own synchronized mapping. - -Source restarts preserve each broadcast's mapping. There are no per-record -anchors or mutable `set_wall` epochs. Report whether a mapping is present, -but never infer that hosts are synchronized from its presence. State the clock -assumption beside the API, since a join across unsynchronized hosts can look -valid while being wrong. The library provides no clock-sync mechanism; see -[#2278](/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md). - -This is also the answer to Kyber's headline claim of continuous drift -computation onto one unified timeline. Worth answering on the merits: -correlating sensor, command and video is the actual product need, and it is -the same property that makes an MCAP recording valuable. - -## Required - -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) diff --git a/quest/m2/teleop/robot.md b/quest/m2/teleop/robot.md index 7417c464327..1932eec47ef 100644 --- a/quest/m2/teleop/robot.md +++ b/quest/m2/teleop/robot.md @@ -74,13 +74,35 @@ The framing is where the guarantee lives, not the subscription flags: structure and `Info::max_age` each one needs: `moq-json`'s for JSON, and the opaque-bytes ones for binary frames (`moq-flate`). - Per-stage timestamp instrumentation, generalised from moq-boy's `status` - track. Check it against the publisher-reported stats broadcast - ([client stats](/quest/m1/qos/stats/schema.md), moq#2734) before adding a + track. Check it against the publisher-reported stats track + ([media stats](/quest/m1/stats/schema.md), moq#2734) before adding a second stats surface. Capability only: publishing a competitive benchmark is out of scope, because Transitive's breakdown puts camera plus USB at roughly 100 ms of a 130 ms glass-to-glass total, so we would mostly be measuring somebody's webcam. +### Cross-track correlation + +Decided in the 2026-09-30 audit: correlation folds in here rather than being +its own quest. A command, the telemetry sample it produced, and the video frame +showing the result share one timebase, so a recording is usable as training +data and an operator sees what the machine actually saw. + +The bridge is each broadcast's fixed catalog-root `clock: { wall, timescale }`, +documented in `doc/concept/hang.md` (#4461). Media and command tracks keep +their own timescales; convert PTS explicitly into the broadcast clock before +joining samples. The robot's video and telemetry share a clock; the operator's +command broadcast supplies its own mapping. + +The clock assumption: the two hosts' wall clocks are synchronized by the +deployment, not by the library. State this beside the API, since a join across +unsynchronized hosts looks valid while being wrong. Report whether a mapping is +present, but never infer synchronization from its presence. No per-record +anchors or clock-sync mechanism; see +[#2278](https://github.com/moq-dev/moq/issues/2278). + +### Port + Port `moq-boy` onto the crate in the same change, as the no-arbitration case. It is the only existing consumer, and if the abstraction cannot express crowd control then it is the wrong abstraction. diff --git a/quest/m2/teleop/ros2.md b/quest/m2/teleop/ros2.md deleted file mode 100644 index a7d6dfc919b..00000000000 --- a/quest/m2/teleop/ros2.md +++ /dev/null @@ -1,38 +0,0 @@ -# [L] ROS 2 bridge - -## Goal - -A ROS 2 bridge sibling to the MAVLink one, carrying topics over the same two -delivery classes. - -## Plan - -### It must land in MCAP - -Recordability is the axis this loses on if ignored. `rtsp_image_transport` -publishes a URL string, so rosbag2 records the URL and not the video; Foxglove's -`CompressedVideo` beat it despite banning B-frames and re-stapling parameter -sets to every keyframe, purely because it stays a recordable message. -Teleoperation video is training data, so a bridge that breaks the recording -loses regardless of latency. - -### Why not DDS - -Nobody runs RTPS over a WAN: discovery data grows quadratically, there is no -NAT traversal short of a port-forward rule per pair of communicating clients, -and reliable QoS on a lossy link produces latency spikes rather than delivery. -Every serious deployment already terminates DDS at the edge and -re-encapsulates. The competitors are the ones named in the questline README, -not the middleware. - -### Sizing - -Larger than the MAVLink bridge: type handling, QoS mapping, and the MCAP -requirement are each real work. Take it after the primitive has one integration -proving it, which is why it requires the MAVLink bridge rather than only the -crate. - -## Required - -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) -- [MAVLink bridge](/quest/m2/teleop/mavlink.md) diff --git a/quest/m2/teleop/v4l2-encode.md b/quest/m2/teleop/v4l2-encode.md deleted file mode 100644 index 222844d62b3..00000000000 --- a/quest/m2/teleop/v4l2-encode.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] V4L2-M2M encoding - -## Goal - -A released `moq-cli` encodes in hardware on the boards that fly, so a Raspberry -Pi needs no GStreamer detour, and the hardware worth buying is written down. - -## Plan - -The backend exists: `moq-video`'s opt-in `v4l2` feature drives the stateful -V4L2 M2M encoder and decoder through `rs/moq-video/src/v4l2.rs`, and both have -run on a Pi 4 (`bcm2835-codec`). What is left is getting it into people's -hands. - -Released `moq-cli` binaries are built with default features, so neither -`capture` nor `v4l2` is compiled in and the backend reaches nobody who installs -a release. A hardware encoder nobody can install is not a fix. [CLI -packaging](/quest/m1/cli-packaging.md) makes capture available; this quest must -also enable `v4l2` in the Linux ARM release build. It finishes once a released -binary on a Pi 4 publishes from `moq import capture` through the hardware -encoder. - -Write the hardware note down, in `doc/bin/cli.md` next to the capture build -instructions. Two landmines make it part of the deliverable: Raspberry Pi 5 has -no video encoder at all, and Jetson Orin Nano ships without NVENC. The boards -that still encode are Pi 4/CM4/Zero 2 W, Orin NX and above, and RK3588. -Rockchip stays excluded from the backend: RK3588 encoding goes through rkmpp in -a vendor kernel rather than V4L2, and the existing `moq-gst` route already ships -aarch64 packages for it. Adding an rkmpp backend is a separate decision. - -Validate what the Pi 4 run did not reach: `set_bitrate` on a running encoder -(congestion control retunes through it), resolutions past 640x360 where 1080p -codes as 1088 rows and the compose rectangle crops it back, and the other -`bcm2835-codec` boards (Zero 2 W, CM4). - -## Required - -- [CLI packaging](/quest/m1/cli-packaging.md) - the released binary has to - compile `capture` before a hardware encoder in it reaches anyone - -## Related - -- [Video hardware validation](/quest/m3/video-hardware.md) - the other unproven encoder backend, VAAPI diff --git a/quest/m1/text-schema.md b/quest/m2/text-schema.md similarity index 95% rename from quest/m1/text-schema.md rename to quest/m2/text-schema.md index d4fed133608..b7fd16f6c03 100644 --- a/quest/m1/text-schema.md +++ b/quest/m2/text-schema.md @@ -8,6 +8,8 @@ the audio or video timeline it transcribes. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer. + The `text` catalog section already carries the rest of the contract: relative `broadcast` references so a transcription can live in its own broadcast, cue timing on the shared media clock, and `jitter` for the publisher's flush diff --git a/quest/m2/ts-export-liveness.md b/quest/m2/ts-export-liveness.md new file mode 100644 index 00000000000..f8c2a92b03f --- /dev/null +++ b/quest/m2/ts-export-liveness.md @@ -0,0 +1,50 @@ +# [S] moq export ts reports each elementary stream's access units and how long it has been quiet + +## Goal + +`Export::stats` returns `ts::Stats` with the import's per-PID row (#4502) for +every elementary stream the exporter writes: `units`, the access-unit count, +and `quiet`, the time since the last, on the output's own PCR. An operator can tell that one track stalled +at the exporter while PSI and the other PIDs kept flowing. The other fields of +`ts::Stats` stay zero at egress. `moq export ts` logs a line when a row stops +advancing. + +## Plan + +Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): + +- **Liveness only, no ETSI counters at egress.** The media-aware lane + regenerates PAT, PMT, PCR and CC, so an egress check grades our muxer, never + the contribution feed. Sync, TEI, CRC, CC, PAT and PMT on bytes the muxer + constructs fail only on a code defect, which the `test/ts` hard checks catch + in CI, and `PAT_error` timed on the output's own PCR never fires on a whole + stall because that clock freezes too. `PCR_accuracy_error` would be + permanently in alarm: the exporter's PCR fails ±500 ns on every file sample + and the downstream groomer's output passes on every one + ([T33](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-33-gate2-preparation.md)). + PCR accuracy and wire timing belong to the groomer's monitoring of its own + output, outside this tree. +- **The runtime failure worth catching is a per-track stall.** #3533 stalled + video and primary audio at the exporter while PSI and the other PIDs + continued and the relay kept transmitting; only a per-PID liveness detector + on a subscriber found it + ([T27](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-27-liveness-detector.md)). +- **Same type as ingest.** `Export::stats` returns `ts::Stats`, so a + dashboard reads one schema at both edges. Additive on main. +- **No window in-tree.** The raw exporter delivers by group, with 102 + simultaneous media-time gaps over 0.3 s in 39 s on every PID, and thresholds + learned there differ from the groomed wire's for the same content (T27). A + window means something only with its monitoring point named, so the + consumer picks it. + +Implementation: + +- `rs/moq-mux/src/container/ts/export.rs`: count an access unit per PID when + its PES is written, and the quiet time on the output PCR. Fix the stale "TR 101 + 290 flags a gap over 40 ms" comment near `PCR_INTERVAL` (V1.4.1's limit is + 100 ms), and the matching 40 ms defaults and the "inserts no null packets, + and paces PCR once per media frame" sentence in `test/ts/README.md`. +- `rs/moq-cli/src/subscribe.rs` logs a stopped row the way `publish.rs` does. +- Tests in `export_test.rs`: a healthy export advances every row; a track that + stops mid-run grows its quiet time while PSI and the other PIDs continue, the + #3533 shape. diff --git a/quest/m2/ts-health-stats.md b/quest/m2/ts-health-stats.md new file mode 100644 index 00000000000..28e8fc6b9d3 --- /dev/null +++ b/quest/m2/ts-health-stats.md @@ -0,0 +1,46 @@ +# [S] TS health counters ride the stats plumbing + +## Goal + +`moq import ts --stats` and `moq export ts --stats` publish the `ts::Stats` +counters so a dashboard reads the TR 101 290 counters and per-PID liveness +beside the media and delivery counters, with no new transport. No health +roll-up in-tree: green, amber or red per priority is the consumer's reading of +counter rates and PID quiet times. + +## Plan + +Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): + +- **Surface through the stats plumbing**, as the issue settled. The + [media stats schema](/quest/m1/stats/schema.md) settles the shape: an + import flattens `ts::Stats` into the publisher's stats snapshot under the + catalog's `mpegts` key, the counters stay owned by moq-mux beside + `ts::Ext`, and `hang` stays TS-free. +- Open: an export is a viewer, which has no stats track and reports only + through a soliciting catalog's `.echo` feedback, so where `moq export ts + --stats` publishes its egress rows is unsettled. Candidates: extend the + solicited `.echo` snapshot with a flattened container section, give viewers + their own stats surface, or narrow this quest to import. Leaning toward + narrowing, since the other two widen the settled stats design. +- **Counters sum, gauges do not.** Every check is a cumulative counter, which + keeps `.z` deltas small and lets an aggregate sum; the PID's `quiet` is a gauge and + merges newest-wins. +- `ts::Stats` gains serde, every field defaulted and unknown fields ignored. + [TS stats module](/quest/m1/ts-stats-module.md) makes `track` owned so the + type deserializes. +- Docs: `doc/concept/stats.md` documents each counter's TR 101 290 check, its + monitoring point (ingest grades the feed, egress grades our muxer, and + neither is the groomed wire), the value domain of the PCR checks, and that + the per-PID rows cover `PID_error`; `doc/bin/cli.md` the flags. +- Test: publish a TS clip with `--stats`, read it back, and assert every ETSI + counter reads zero on a clean clip while every elementary stream's + access-unit count advances. + +## Required + +- [TS stats module](/quest/m1/ts-stats-module.md) - the owned `track` that lets the rows deserialize +- [Media stats schema](/quest/m1/stats/schema.md) - the snapshot the counters flatten into +- [Rust reporters](/quest/m1/stats/rust.md) - `moq import --stats` and the stats interval +- [TS import health](/quest/m2/ts-import-health.md) - the ingest counters +- [TS export liveness](/quest/m2/ts-export-liveness.md) - the egress rows diff --git a/quest/m2/ts-import-health.md b/quest/m2/ts-import-health.md new file mode 100644 index 00000000000..77188dc12b8 --- /dev/null +++ b/quest/m2/ts-import-health.md @@ -0,0 +1,115 @@ +# [M] moq import ts counts the TR 101 290 errors of the feed it receives + +## Goal + +An operator polling `moq import ts`, or `moq-srt` through the same importer, +reads cumulative counters for the TR 101 290 checks that grade a contribution +feed at ingest: `TS_sync_loss`, `Sync_byte_error`, `PAT_error`, +`Continuity_count_error`, `PMT_error`, `Transport_error`, `CRC_error` (on +PAT and PMT), `PCR_repetition_error`, `PCR_discontinuity_indicator_error` and `PTS_error`. +Counters only: ETSI's fixed limits, no configuration, no verdict, and nothing +changes in what is published. + +## Plan + +Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): + +- **The checks live beside the container**, in a private module under + `rs/moq-mux/src/container/ts` that takes 188-byte packets and keeps the + counters. No new crate: nothing outside the tree consumes one. The importer + already classifies sync, continuity and TEI for routing; routing reads the + module's classification rather than keeping a second. A packet with + `transport_error_indicator` set counts `Transport_error` and nothing else: + TR 101 290 derives no further error from it, so it feeds no continuity, + PCR, PTS or CRC check. +- **Counters are named for the ETSI check** in snake case + (`continuity_count_error`, ...), cumulative for the importer's life like + `resyncs`: stream-wide on `ts::Stats`, per PID on the PID's row. No + last-event timestamp and no green/amber/red roll-up; the rate is what an + operator alarms on, and the stats sample dates the event. +- **Limits are ETSI TR 101 290 V1.4.1's and fixed**: 0.5 s for PAT and PMT, + loss of sync after two or more consecutive corrupted sync bytes and + acquisition after five consecutive correct ones (ISO 13818-1 G.1), 100 ms + for PCR repetition (the 40 ms limit left TS 101 154 in 2005), 0 to 100 ms + for PCR discontinuity, 700 ms for PTS. The PMT names the PIDs, and every + packet is checked, so there is no sampling to configure. +- **No `PID_error` field.** ETSI defines it as a PMT-listed PID with no + packets for a user-specified period. The per-PID rows #3489 landed in + #4502 (`units`, access units delivered, and `quiet`, the time since the + last) cover it and are stricter: a dead video path behind a + live mux still sends adaptation-field-only PCR packets on its PID, which a + packet count reads as live + ([T27](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-27-liveness-detector.md)). + The rows keep #3489's names so no field claims the ETSI name for a different + measurement, and the consumer picks the window, as #3489 decided. The docs + map `PID_error` onto them. +- **`CRC_error` covers PAT and PMT only.** TR 101 290 names CAT, PAT, PMT, + NIT, EIT, BAT, SDT and TOT, and its table 5.1b cuts that to PAT and PMT for + systems with reduced SI, which a contribution feed is. The importer parses + only PAT and PMT, and [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) + already drops a bad-CRC section and counts it as `crc_error`; this quest + adopts that field. SI captured verbatim (NIT, SDT, EIT, BAT, TOT) is not + CRC-checked, and CAT is out with the scrambled services below. +- **Intervals run on the program clock** #4502 reads, accumulated step by + step with a jump bound: one corrupt PCR taken as an absolute distance + fabricated a 23,861 s outage on every PID in the campaign's detector (T27). + A clock that stops freezes every interval; the consumer sees that case as + every count standing still across two samples. +- **PCR and PTS are graded on values, and documented as such.** Repetition and + discontinuity compare consecutive PCR values on the PCR PID, not arrival + times: that grades the encoder's insertion, which is what ingest can speak + for, while the network in front of the importer (SRT, UDP, a pipe) re-times + arrival. The docs name the domain beside the counters, because a + value-domain pass is not a wire pass + ([evidence §3.2](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/docs/evidence.md)). + - A signalled jump is legal: the interval across a packet carrying + `discontinuity_indicator` on the PCR PID is dropped from both checks (ISO + 13818-1 2.4.3.4); the importer already reads it in `timebase_break`. The + 33-bit wrap is modular, not a jump. + - `PCR_discontinuity_indicator_error` is a consecutive difference outside 0 + to 100 ms without the flag, backwards included. On values alone a run of + missing PCRs and an unsignalled jump are the same difference, so one + forward difference over 100 ms counts under both checks; the docs say so + rather than guess which it was. + - `PTS_error` is per elementary stream on the transport clock. Verbatim + streams with no cadence (SCTE-35, DVB subtitles) are left ungraded rather + than watched against an invented number. +- **`PCR_accuracy_error` is out.** ±500 ns is graded either against a + constant-rate model of byte position, which holds only on a CBR feed, or + against arrival on the wire, which is an analyser measurement + ([T33](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-33-gate2-preparation.md)). +- **No opaque whole-mux lane**: + [#1861](https://github.com/moq-dev/moq/issues/1861) is closed not planned + and verbatim TS is a non-goal in + [MSFTS convergence](/quest/m2/msfts-convergence.md). P3 is out of this set; + `CAT_error` too, since the lane carries no scrambled service. A scrambled + PAT or PMT still counts under its own check. + +Implementation: + +- `rs/moq-mux/src/container/ts/import.rs`: `Stats` and `StreamStats` are + `#[non_exhaustive]`, so the fields are additive. A continuity break + declared by `discontinuity_indicator`, the one duplicate ISO 13818-1 + 2.4.3.3 permits, and a payload-less packet repeating its counter are not + errors. +- `ts::stats::Log` logs a line when a counter moves, as it does for + resyncs. +- Measure `decode` throughput on `test_data/kyrion_mpeg2av_ac3.ts` before and + after; the checks read header bytes the loop already reads, so a measurable + cost is a finding. +- Tests, one stimulus per check with a control each way: a clean capture + reads zero, the faulted one reads exactly the count injected. Feed at least + a pair of packets, since a single packet never routes. Timing arms: a + 150 ms PCR gap counts one repetition and one discontinuity error, an 80 ms + gap counts nothing, a signalled 500 ms jump counts nothing, a placed wrap + counts nothing, and a 1 s PTS gap on one PID counts one there and nowhere + else. A TEI packet that also jumps its continuity counter counts one + `Transport_error` and no `Continuity_count_error`. + +## Required + +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - the bad-CRC PAT or PMT the importer survives and counts as `crc_error` + +## Related + +- [TS health stats](/quest/m2/ts-health-stats.md) - where these counters are published diff --git a/quest/m2/ts-program-si.md b/quest/m2/ts-program-si.md new file mode 100644 index 00000000000..168022f0a11 --- /dev/null +++ b/quest/m2/ts-program-si.md @@ -0,0 +1,52 @@ +# [M] Per-program SI + +## Goal + +When an MPEG-TS import selects a program (`ts::Import::with_program`, so +`moq import ts --program ` and each broadcast of `--program all`), that +program's broadcast carries SI describing only its own service. Other services' +EIT sub-tables are dropped, and the SDT for this transport stream is rewritten +to list only the selected service. Network-wide tables (NIT, BAT, TDT/TOT, SDT +other, EIT other) pass through unchanged. An import without a selection does +no filtering by program and keeps today's capture behavior. + +## Plan + +Settled decisions: + +- Filter at import, in `si::Capture`, before a generation commits, so a + program's SI tracks never carry another service's bytes and exporters stay + unchanged. Filtering at export was rejected: every subscriber would still + receive the whole multiplex's schedule. +- Filter only under an explicit selection. A single-program input whose SDT + lists extra services is left alone, because default capture keeps the + sections it accepts verbatim. +- EIT actual (`table_id` 0x4E and 0x50..=0x5F): keep a sub-table only when its + `table_id_extension` (the service_id) is the selected program_number. Whole + sub-tables are dropped; nothing is rewritten. EIT other (0x4F and + 0x60..=0x6F) describes other transport streams and passes through. +- SDT actual (`table_id` 0x42 on PID 0x11): its one sub-table lists every + service, so once a generation is complete, rebuild it as a single section + (`section_number` and `last_section_number` 0) holding the selected service's + loop entry, wherever it sat in the source's sections. Keep the header fields + (transport_stream_id, version_number, original_network_id), recompute + `section_length`, and write a fresh CRC-32/MPEG-2 using the `crc` crate, which + is already in `Cargo.lock`, as a direct moq-mux dependency rather than a + hand-written table. [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) + needs it too, and whichever change lands first adds it. +- When the SDT has no entry for the selected service, carry no SDT actual rather + than fabricating a table the source never gave for this service. If a later + version drops the service, the next snapshot retires the SDT captured before + it, and its catalog entry goes too if nothing else is left on it. A later + version that lists the service again is captured normally. +- A `(PID, table_id)` whose every sub-table is filtered away gets no catalog + `mpegts.si` entry or track. +- The same change updates the program-selection paragraph in `doc/bin/cli.md` + and the `si.rs` module docs; no new page is needed. + +Test with a synthetic two-service multiplex whose SDT lists both services +across two sections, with EIT present/following for each. Each selected import +carries one SDT entry with a valid CRC and only its own EIT; an unselected +import keeps the sections verbatim; a selection missing from the SDT carries +none; an SDT version that drops the selected service retires the earlier one; +and the re-exported TS still parses. diff --git a/quest/m1/perf/uring-open-contract.md b/quest/m2/uring-open-contract.md similarity index 75% rename from quest/m1/perf/uring-open-contract.md rename to quest/m2/uring-open-contract.md index f49a4e3196a..39e37fa4c5e 100644 --- a/quest/m1/perf/uring-open-contract.md +++ b/quest/m2/uring-open-contract.md @@ -19,6 +19,10 @@ bounds, cancellation behavior, and regression cases for concurrent openers, credit starvation, dropped futures, and finish/drop. This quest ships the plan; it does not close #3129 or implement an unsettled public contract. +Decided in the 2026-09-30 audit: moved to m2 with #3129, which it plans. +io_uring ships in no package, and #3129 fixes an API wart no in-tree caller +hits. + ## Related -- [Write headers at open](/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - implementation after the contract is settled +- [Write headers at open](/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - implementation after the contract is settled diff --git a/quest/m1/uring-tcp/README.md b/quest/m2/uring-tcp/README.md similarity index 76% rename from quest/m1/uring-tcp/README.md rename to quest/m2/uring-tcp/README.md index f18fc505373..831e86655f7 100644 --- a/quest/m1/uring-tcp/README.md +++ b/quest/m2/uring-tcp/README.md @@ -19,10 +19,10 @@ The three quests below ship together as one capability, in order. The prerequisite that shapes the middle quest: **qmux sessions arrive through the axum router**. `web.rs` routes `/` and `/{*path}` to -`websocket::serve_ws` (rs/moq-relay/src/web.rs:256-259). The gate is +`websocket::serve_ws` (rs/moq-relay/src/web.rs:343-344). The gate is moq-relay's own `websocket` feature (rs/moq-relay/Cargo.toml:43, which is what turns on `axum/ws`) plus the runtime `resolved_ws()` check -(web.rs:257), so a WebSocket session is an HTTP upgrade before it is a media +(web.rs:342), so a WebSocket session is an HTTP upgrade before it is a media session. There is no moving qmux onto the ring without also running the HTTP server that upgrades it there. That is not a reason to rewrite axum: hyper is runtime-agnostic, so implementing `hyper::rt::{Read, Write, Executor}` over @@ -33,11 +33,16 @@ Measure before porting, the same way the echo bench (rs/moq-uring/benches/session_lite.rs) gated the UDP path. The ablation's number is what justifies the rest of the line. +Decided in the 2026-09-30 audit: moved to m2. The +[transport upgrade](/quest/m1/transport-upgrade/README.md) shrinks the +WebSocket hot path by moving clients to QUIC, and no fleet demand asks for +ring TCP. + ## Required -- [Ablation](/quest/m1/uring-tcp/ablation.md) - measure ring TCP against tokio +- [Ablation](/quest/m2/uring-tcp/ablation.md) - measure ring TCP against tokio TCP under the qmux workload before committing to the port -- [Stream](/quest/m1/uring-tcp/stream.md) - a `tcp` module in `moq-uring`, and +- [Stream](/quest/m2/uring-tcp/stream.md) - a `tcp` module in `moq-uring`, and the `hyper::rt` adapters that let axum run on it -- [Relay](/quest/m1/uring-tcp/relay.md) - serve the relay's WebSocket and +- [Relay](/quest/m2/uring-tcp/relay.md) - serve the relay's WebSocket and stream listeners from the io_uring workers diff --git a/quest/m1/uring-tcp/ablation.md b/quest/m2/uring-tcp/ablation.md similarity index 100% rename from quest/m1/uring-tcp/ablation.md rename to quest/m2/uring-tcp/ablation.md diff --git a/quest/m1/uring-tcp/relay.md b/quest/m2/uring-tcp/relay.md similarity index 92% rename from quest/m1/uring-tcp/relay.md rename to quest/m2/uring-tcp/relay.md index c9427116628..cfce78c5203 100644 --- a/quest/m1/uring-tcp/relay.md +++ b/quest/m2/uring-tcp/relay.md @@ -13,7 +13,7 @@ the operator at a separate `init_streams` tokio server (rs/moq-relay/src/uring.rs:116-120); the only thing it refuses is `tls.generate` (:126-128). Replace the silent skip with real support: each worker binds its own listener in the reuseport group and runs the router from -[stream](/quest/m1/uring-tcp/stream.md) on it. +[stream](/quest/m2/uring-tcp/stream.md) on it. The split of work stays what `uring.rs` already documents (:10-15): the worker owns everything transport-shaped, while authentication and session @@ -29,5 +29,5 @@ worker. ## Required -- [Stream](/quest/m1/uring-tcp/stream.md) - the module and adapters this +- [Stream](/quest/m2/uring-tcp/stream.md) - the module and adapters this serves from diff --git a/quest/m1/uring-tcp/stream.md b/quest/m2/uring-tcp/stream.md similarity index 96% rename from quest/m1/uring-tcp/stream.md rename to quest/m2/uring-tcp/stream.md index 780f6d9c325..c0ce1630d23 100644 --- a/quest/m1/uring-tcp/stream.md +++ b/quest/m2/uring-tcp/stream.md @@ -32,4 +32,4 @@ existing suite does. ## Required -- [Ring TCP ablation](/quest/m1/uring-tcp/ablation.md) - a positive verdict selects the mechanisms before the worker implementation starts +- [Ring TCP ablation](/quest/m2/uring-tcp/ablation.md) - a positive verdict selects the mechanisms before the worker implementation starts diff --git a/quest/m2/video-codec-coverage.md b/quest/m2/video-codec-coverage.md index 36b369303b5..423619c9ca3 100644 --- a/quest/m2/video-codec-coverage.md +++ b/quest/m2/video-codec-coverage.md @@ -30,5 +30,5 @@ Public API and wire: no changes during this study. ## Related - [NVIDIA formats](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - existing AV1 encode and 10-bit scope -- [VAAPI](/quest/m4/video-vaapi.md) - existing Linux codec expansion - [VP8/VP9](/quest/m1/obs-moq-video/vpx.md) - existing portable decoder scope +- [VAAPI](/quest/m2/video-vaapi.md) - existing Linux codec expansion diff --git a/quest/m4/video-vaapi.md b/quest/m2/video-vaapi.md similarity index 66% rename from quest/m4/video-vaapi.md rename to quest/m2/video-vaapi.md index 1f3ee5658a7..eb95c2e0a8a 100644 --- a/quest/m4/video-vaapi.md +++ b/quest/m2/video-vaapi.md @@ -4,12 +4,17 @@ VAAPI encodes H.264 and H.265 from a DMA-BUF without a download, decodes H.265 as well as H.264, and the `vaapi` feature costs a consumer nothing at -build time so it can return to default-on. Every piece needs a `moq-dev/vaapi` -release first. +build time so it can return to default-on. A resize reuses its output +surfaces. ## Plan -Three gaps, one external dependency. +Decided in the 2026-09-30 audit: moved from m4, and the "gated on a +`moq-dev/vaapi` release" blocker is gone. That crate is our own repo (last +release 0.1.0 on 2026-09-24), so this quest includes the crate work (HEVC +encode, H.265 decode, pre-generated bindings, the resize pool) and cutting the +release, then bumping the workspace requirement here. The resize-pool quest +folds in for the same reason. **Decode.** The H.264 decoder landed (moq-vaapi 0.0.4, `decode/backend/vaapi.rs`), with the default `decode::Config::output` of `Output::Native` handing out @@ -39,16 +44,15 @@ fixed-width types, `c_char` left symbolic), so one checked-in file serves every Linux target, as `moq-v4l` already does for `videodev2.h`. Then the feature can return to default-on here. +**Resize pool.** moq-vaapi's `Processor` allocates the blit output with +`ExportedFrame::from_surface` on every resize. Keep one surface per output +size; when the exported frame drops, the surface returns for the next blit of +that size. A frame the consumer still holds is not overwritten; the processor +allocates another. Keep at most one free surface per size and destroy any +returned past that, the decoder pool's rule. `Surface::resize` stays the same +call. The reuse test belongs in moq-vaapi; here, confirm a resize still returns +an NV12 DMA-BUF. + Note what is already fine: a host with libva present but no usable VA driver already falls back cleanly, since `Encoder::new` returns `Err` and `backend::open` drops to openh264. - -## Required - -- A `moq-dev/vaapi` release exposing an HEVC encoder (H.264 decode is in - 0.0.4; DMA-BUF encode and VPP shipped in 0.1.0) and pre-generated bindings - instead of a bindgen build script - -## Related - -- [Pool VAAPI resize surfaces](/quest/m4/vaapi-resize-pool.md) - reuse one VPP output surface per size, a separate moq-vaapi release diff --git a/quest/m2/x11-capture-shm.md b/quest/m2/x11-capture-shm.md index 15e21051fe9..dbf4f8b9840 100644 --- a/quest/m2/x11-capture-shm.md +++ b/quest/m2/x11-capture-shm.md @@ -24,9 +24,12 @@ capture does the same thing with a per-frame `get_geometry`; it already selects `StructureNotify` and drains that queue between frames, so `ConfigureNotify` is there to be consumed and the round trip dropped. -Both changes are contained to the one backend and are verifiable on a Linux +Decided in the 2026-09-30 audit: the X11 half of the frame-buffer quest folds +in here, since it is the same read path. `PixelFormat::rgb` allocates a +`w * h * 3` `Vec` per frame and fills it with three `push` calls per pixel, +then `I420::from_rgb` walks it again into a third buffer. Reuse an +`&mut Vec` the `Capture` owns and `clear()` it, so the allocation happens +once. Measure before and after rather than assuming. + +All of these changes are contained to the one backend and are verifiable on a Linux host with a real X session; CI compiles the file but cannot run it. - -## Related - -- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - the per-frame allocations in the same read path diff --git a/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md b/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md deleted file mode 100644 index a911c2f6558..00000000000 --- a/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md +++ /dev/null @@ -1,66 +0,0 @@ -# [M] video: validate PipeWire DMA-BUF capture on KDE hardware - -## Goal - -Implement and verify the behavior tracked in [#2893](https://github.com/moq-dev/moq/issues/2893) -within the issue's stated scope and boundaries. - -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -#### Problem - -Hardware validation for #2839 did not complete on a KDE/Wayland desktop. The screen source was selected in the portal, but the ignored PipeWire capture test never received a frame and timed out after 120 seconds. - -This is a focused follow-up to the broader Linux zero-copy tracker in #2819. - -#### Environment - -- KDE desktop on Wayland -- `XDG_CURRENT_DESKTOP=KDE` -- `WAYLAND_DISPLAY=wayland-0` -- `DISPLAY=:0` -- `XDG_RUNTIME_DIR=/run/user/1000` -- Active desktop D-Bus session - -#### Reproduction - -Run from the Nix development shell after #2839: - -```sh -cargo nextest run --profile ci -p moq-video --all-features --run-ignored ignored-only portal_captures_frames --no-capture -``` - -During review, a temporary assertion also required captured frames to be `Surface::DmaBuf`. The run reached the test, the portal source was selected, then nextest reported the test as slow after 60 seconds and terminated it at 120 seconds without receiving a frame. - -#### Expected - -- Portal selection completes. -- PipeWire format and buffer negotiation completes. -- The first frame arrives within the existing capture timeout. -- A DMA-BUF-capable compositor produces `Surface::DmaBuf`; shared memory remains a working fallback. - -#### Validation - -- \[ ] Reproduce the post-selection timeout on KDE/Wayland. -- \[ ] Add tracing around portal completion, PipeWire connection, format fixation, buffer allocation, and first-frame delivery to locate the stall. -- \[ ] Validate packed RGB DMA-BUF capture and Vulkan import on Intel or AMD hardware. -- \[ ] Validate the linear DMA-BUF CPU fallback. -- \[ ] Confirm shared-memory PipeWire capture still works when DMA-BUF is unavailable. -- \[ ] Hold multiple frames long enough to exercise buffer leasing without pool exhaustion or reused content. -- \[ ] Add or refine an ignored hardware test so the observed failure is distinguishable from a portal-selection timeout. - -Refs #2839 and #2819. - -## Closes - -- [#2893](https://github.com/moq-dev/moq/issues/2893) - close this issue when the quest finishes - -## Related - -- [#2819: moq-video: carry PipeWire DMA-BUFs safely into the Vulkan renderer](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - related open work diff --git a/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md b/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md similarity index 90% rename from quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md rename to quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md index 5315677c57f..9930a37408f 100644 --- a/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md +++ b/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md @@ -35,6 +35,14 @@ The UDP path already assembles up to 64 KiB GSO trains in stable pool buffers, t Sweep the threshold across realistic chat and media packet trains. Record relay CPU, goodput, CQEs per send, copy-fallback rate, TX-pool pressure, p99 latency, and memory residency at fixed offered load. Enable it by default only where the end-to-end result beats regular `SendMsg`. +Decided in the 2026-09-30 audit: moved to m3. The #3224 prototype was 6 to +9% slower, the win needs a physical-NIC sweep nobody has run, and io_uring +ships in no package. + +## Required + +- A physical-NIC remote peer to measure zero-copy sends against + ## Closes - [#3201](https://github.com/moq-dev/moq/issues/3201) - close this issue when the quest finishes diff --git a/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md b/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md similarity index 88% rename from quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md rename to quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md index 86f4ebb14ae..05aa724c3d3 100644 --- a/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md +++ b/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md @@ -34,9 +34,13 @@ The TX pool already owns stable `Box<[u8]>` allocations and grows lazily. If zer Compare #3201 with and without registered buffers using the same threshold and workload matrix. Record CPU, cycles, registration cost, locked memory, pool starvation, throughput, and latency. Do not add the complexity unless it improves the winning zero-copy range beyond ordinary `SendMsgZc`. +Decided in the 2026-09-30 audit: moved to m3. Fixed buffers on +`SENDMSG_ZC` need Linux 6.15, above the 6.12 floor, and the #3201 +experiment it builds on moved to m3 too. + ## Required -- [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first +- [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - the zero-copy send experiment this extends ## Closes diff --git a/quest/m3/README.md b/quest/m3/README.md index ac3b0631f5a..57d33620742 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -3,22 +3,48 @@ ## Goal Work whose first step is outside this repository: hardware nobody on the team -has, a partner or customer, or a hosting provider's offer. Nothing here can -start by opening an editor. +has, a partner or customer who asks for it, or a hosting provider's offer. +Nothing here should start by opening an editor. ## Plan -A quest lands here when its gate is the outside world, not its priority. Each -states the condition in prose or as a plain-text `Required` bullet. When the -condition clears, move the quest to the milestone its work belongs in. +A quest lands here when its gate is the outside world, not its priority. Its gate +is a plain-text `Required` bullet, re-checked as the root +[questline](/quest/README.md) describes. A +speculative feature with no consumer parks here rather than in m2, and is +deleted when it goes stale; git history keeps it. ## Required -- [DPDK](/quest/m3/dpdk.md) - a kernel-bypass UDP path for the relay, once a provider offers SR-IOV or bare metal -- [Video hardware validation](/quest/m3/video-hardware.md) - run the encode, capture, and zero-copy paths that were written but never run on real machines -- [Validate PipeWire cameras on a portal and a Pi](/quest/m3/pipewire-camera-hardware.md) - run the shipped PipeWire camera through the camera portal and a Pi CSI node -- [#2893](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - video: validate PipeWire DMA-BUF capture on KDE hardware +- [Video hardware validation](/quest/m3/video-hardware.md) - run the encode, capture, and zero-copy paths that were never run on real machines, including PipeWire on KDE, the camera portal, and a Pi +- [NVENC AV1](/quest/m3/nvenc-av1.md) - AV1 encode through NVENC, once an Ada-generation GPU is available - [Embedded video](/quest/m3/video-embedded.md) - EGL import in the renderer, so moq-video presents on a Pi -- [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract -- [Suffix announce](/quest/m3/suffix-announce.md) - moq-lite-only suffix announce and interest, benchmarked over the announce table, once a deployment needs a claim a service prefix cannot express -- [Upstream forks](/quest/m3/upstream-forks.md) - offer the uniffi generator fixes our cpp, dart, and Python forks carry upstream, lowest priority +- [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first +- [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - per-packet arrival times in ACKs, the feedback GCC and deadlines need +- [QUIC GCC](/quest/m3/quic-gcc.md) - a measured verdict on delay-based congestion control for media egress, shipping as `RealTime` +- [AF_XDP UDP path](/quest/m3/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK +- [C# through moq-ffi](/quest/m3/cs/README.md) - generated C# over moq-ffi as a NuGet package with native runtimes +- [Unity prototype](/quest/m3/unity.md) - the C# package under IL2CPP, playing subscribed audio +- [Unreal prototype](/quest/m3/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture +- [LiveKit client shim](/quest/m3/livekit-shim.md) - a media compatibility facade over the room SDK +- [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the same tarball to `conan install` +- [WHEP ABR](/quest/m3/whep-abr.md) - a WHEP viewer switches renditions from its own congestion feedback +- [Synced data playback](/quest/m3/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back +- [Linux OBS GPU input](/quest/m3/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination +- [Routing cost domains](/quest/m3/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs +- [Common Access Tokens](/quest/m3/cat/README.md) - a moq-transport client presents a CAT in SETUP and `moq auth serve` admits it with the scope its `moqt` claim names +- [Drop the hidden cluster exemption](/quest/m3/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway + replacing the VPN plus two unmanaged UDP flows, with QGroundControl and + friends unchanged +- [SITL proof and browser ground station](/quest/m3/teleop-proof.md) - ArduPilot + SITL and a synthetic camera flown from a browser ground station, reproducible + in five minutes +- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) - `@moq/robot` + mirrors the Rust crate, so browser clients consume the catalog and delivery + classes +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - refresh mode extends the settled GOP contract; the producer cuts groups per sweep and publishes `warmup` +- [NVENC refresh](/quest/m3/intra-refresh-nvenc.md) - the NVENC backend encodes refresh mode for H.264 and HEVC +- [V4L2 refresh](/quest/m3/intra-refresh-v4l2.md) - the V4L2 backend encodes refresh mode +- [Bindings](/quest/m3/intra-refresh-bindings.md) - moq-ffi and every wrapper expose refresh mode, additive on the ffi-shape `Gop` enum diff --git a/quest/m2/af-xdp.md b/quest/m3/af-xdp.md similarity index 65% rename from quest/m2/af-xdp.md rename to quest/m3/af-xdp.md index 775b7b34c63..9ae34da3b0a 100644 --- a/quest/m2/af-xdp.md +++ b/quest/m3/af-xdp.md @@ -6,7 +6,7 @@ A measured verdict on an AF_XDP socket as the io_uring worker's UDP path on the hosts the fleet runs today. virtio-net supports AF_XDP in copy mode on any Linode or OVH instance and zero-copy where the driver allows; if it lifts the per-worker packet ceiling or cuts CPU per Gbps materially against the -io_uring path, the DPDK question becomes concrete; if not, kernel bypass is +io_uring path, full kernel bypass becomes a concrete question; if not, it is closed until hardware changes. ## Plan @@ -17,10 +17,12 @@ closed until hardware changes. behind a feature; nothing ships. - Measure packets per second, CPU per Gbps, and p99 latency on one virtio host in copy mode, on the chat and fanout shapes, against the io_uring path - with the zero-copy and busy-poll quests' best settings. + with the zero-copy quests' best settings. -## Related +Decided in the 2026-09-30 audit: moved to m3. The relay packages don't ship +io_uring yet, so a bypass that competes with it has no deployment to +improve. -- [DPDK](/quest/m3/dpdk.md) - the full bypass this verdict gates -- [#3203](/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md) - - the in-kernel ceiling this competes with +## Required + +- [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - the io_uring path this is compared against ships first diff --git a/quest/m2/cat/README.md b/quest/m3/cat/README.md similarity index 90% rename from quest/m2/cat/README.md rename to quest/m3/cat/README.md index d68c4ec7d54..40871479531 100644 --- a/quest/m2/cat/README.md +++ b/quest/m3/cat/README.md @@ -41,6 +41,10 @@ Boundaries decided while planning: ## Plan +In m3 because nobody is asking for CAT yet and the claim keys are +unregistered; a consumer presenting CATs, or the draft registering the keys, +brings it back. + Order: the SETUP option already reaches the auth server as `moq_auth::Request.token`; verification comes first, then our clients present one. Everything rides `moq_auth::Request` and @@ -49,10 +53,11 @@ one. Everything rides `moq_auth::Request` and ## Required -- [Verify](/quest/m2/cat/verify.md) - `moq_auth::cat` turns a CAT into a +- draft-ietf-moq-c4m registers the moqt claim keys +- [Verify](/quest/m3/cat/verify.md) - `moq_auth::cat` turns a CAT into a grant and `moq auth serve` admits one; `moq auth sign|verify` mint and check the format -- [Present](/quest/m2/cat/present.md) - a CAT is one kind of configured +- [Present](/quest/m3/cat/present.md) - a CAT is one kind of configured token, riding the SETUP option the in-band token quest already writes ## Related diff --git a/quest/m2/cat/present.md b/quest/m3/cat/present.md similarity index 88% rename from quest/m2/cat/present.md rename to quest/m3/cat/present.md index 8fcd5185864..53b2a8f877e 100644 --- a/quest/m2/cat/present.md +++ b/quest/m3/cat/present.md @@ -13,9 +13,9 @@ the option fails loud instead of dropping the credential. - [Token in band](/quest/m1/auth/token-in-band.md) defines the client token configuration and writes the first configured token into the setup option - as type 0. This quest makes the kind explicit: each configured token is a - `moq_net::setup::Token { kind, value }`, a JWT keeps kind `0x0` and its - URL and AUTH stream behavior, and a CAT is kind `0x01`. `--connect-token` + as type 0. `moq_net::setup::Token { kind, value }` already carries the + kind, with CAT = `0x1` (#4278); a JWT keeps kind `0x0` and its URL and + AUTH stream behavior. `--connect-token` keeps taking a JWT; `--connect-cat ` (and `MOQ_CONNECT_CAT`) adds a CAT. One CAT per connection: it is the connection credential, so a configured CAT takes the setup option and the JWT that would have gone @@ -40,7 +40,7 @@ Public API: additive on `moq-tokio` and `js/net`. Wire: none. ## Required -- [Verify](/quest/m2/cat/verify.md) - the server that admits the token the +- [Verify](/quest/m3/cat/verify.md) - the server that admits the token the end-to-end test presents - [Token in band](/quest/m1/auth/token-in-band.md) - the token configuration and setup-option writer this adds a kind to diff --git a/quest/m2/cat/verify.md b/quest/m3/cat/verify.md similarity index 100% rename from quest/m2/cat/verify.md rename to quest/m3/cat/verify.md diff --git a/quest/m2/cpp-conan.md b/quest/m3/cpp-conan.md similarity index 91% rename from quest/m2/cpp-conan.md rename to quest/m3/cpp-conan.md index 19e36c2ac2c..9d7048dc7b3 100644 --- a/quest/m2/cpp-conan.md +++ b/quest/m3/cpp-conan.md @@ -9,6 +9,9 @@ Windows, macOS, and Linux. ## Plan +In m3 until a Conan consumer asks; vcpkg and the release tarball cover +C++ consumers first. + - A `moq-cpp` recipe, named after the package, on a moq-dev remote (Artifactory or a GitHub-hosted `conan` index) that packages the prebuilt release tarball per setting and exports the `moq::cpp` CMake target from diff --git a/quest/m2/cs/README.md b/quest/m3/cs/README.md similarity index 78% rename from quest/m2/cs/README.md rename to quest/m3/cs/README.md index 69c17b0a8dd..dca620bd43a 100644 --- a/quest/m2/cs/README.md +++ b/quest/m3/cs/README.md @@ -10,6 +10,9 @@ a mirror. Unity is a separate prototype. ## Plan +In m3 until a .NET or Unity consumer asks; the C++ line covers native +embedders first. + NordSecurity's `uniffi-bindgen-cs` (latest `v0.11.0+v0.31.0`) already emits async methods as `Task` and async callback interfaces; it needs the same uniffi 0.32 port the Go, Dart, and C++ generators got. Plain .NET first; the @@ -19,10 +22,10 @@ up front. ## Required -- [Generator](/quest/m2/cs/generator.md) - uniffi-bindgen-cs on uniffi 0.32, pinned and generating `cs/ffi` in CI -- [Package](/quest/m2/cs/package.md) - the `cs/moq` wrapper, NuGet package with native runtimes, interop client, and docs +- [Generator](/quest/m3/cs/generator.md) - uniffi-bindgen-cs on uniffi 0.32, pinned and generating `cs/ffi` in CI +- [Package](/quest/m3/cs/package.md) - the `cs/moq` wrapper, NuGet package with native runtimes, interop client, and docs ## Related - [C++ through moq-ffi](/quest/m1/cpp/README.md) - the sibling line this copies -- [Unity prototype](/quest/m2/unity.md) - the package under IL2CPP +- [Unity prototype](/quest/m3/unity.md) - the package under IL2CPP diff --git a/quest/m2/cs/generator.md b/quest/m3/cs/generator.md similarity index 100% rename from quest/m2/cs/generator.md rename to quest/m3/cs/generator.md diff --git a/quest/m2/cs/package.md b/quest/m3/cs/package.md similarity index 94% rename from quest/m2/cs/package.md rename to quest/m3/cs/package.md index d5472a13d05..66aecee5c5a 100644 --- a/quest/m2/cs/package.md +++ b/quest/m3/cs/package.md @@ -24,4 +24,4 @@ interop --all` and `doc/lib/cs` documents the package. ## Required -- [Generator](/quest/m2/cs/generator.md) - the pinned generator that emits `cs/ffi` +- [Generator](/quest/m3/cs/generator.md) - the pinned generator that emits `cs/ffi` diff --git a/quest/m3/dpdk.md b/quest/m3/dpdk.md deleted file mode 100644 index efaf48e21ca..00000000000 --- a/quest/m3/dpdk.md +++ /dev/null @@ -1,28 +0,0 @@ -# [XL] DPDK - -## Goal - -A relay build whose io_uring workers are replaced by DPDK poll-mode workers -owning a NIC queue each, measured against the kernel path on the same host. -Worth building only on hardware with SR-IOV virtual functions or a dedicated -NIC; neither Linode nor OVH VPS, where the fleet runs, offers either. - -## Plan - -Do not start until the [AF_XDP spike](/quest/m2/af-xdp.md) has a verdict: it -runs on today's hosts and bounds what bypass can buy. If it shows the kernel -path is within reach of line rate, this quest is abandoned. - -When a provider offers the hardware: a `moq-dpdk` worker crate mirroring -`moq-uring`'s worker contract (one QUIC endpoint per worker, connection-ID -steering by the NIC's RSS or a flow rule), userspace UDP/IP, and the noq -endpoint driven from the poll loop. Measure packets per second, CPU per -Gbps, and p99 latency against io_uring on the same box, then decide whether -a bare-metal tier is worth operating. - -## Required - -- [AF_XDP UDP path](/quest/m2/af-xdp.md) - the no-hardware verdict this waits - on; a kernel path within reach of line rate abandons this quest -- A moq.pro relay provider offers SR-IOV or bare-metal hosts the fleet can - run on diff --git a/quest/m2/hidden-exemption.md b/quest/m3/hidden-exemption.md similarity index 78% rename from quest/m2/hidden-exemption.md rename to quest/m3/hidden-exemption.md index 96ecf2afea6..97dc8acac6e 100644 --- a/quest/m2/hidden-exemption.md +++ b/quest/m3/hidden-exemption.md @@ -9,12 +9,15 @@ for peers that predate it. ## Plan +In m3 because it waits on a deployment, not on code; it comes back once +the mesh runs lite-07. + - Remove the `cluster_peer` argument from `connection::authorize` and its callers in `rs/moq-relay/src/{connection,uring,websocket}.rs`, and the forced `with_hidden(true)` on the outbound dial in `rs/moq-relay/src/cluster.rs`. - Replace `rs/moq-relay/tests/hidden_cluster.rs` with a lite-07 mesh test that - still sees `.internal/origins`. + still sees a `.`-prefixed hidden broadcast. ## Required -- Every deployed relay in the moq.pro mesh speaks a finalized moq-lite-07 or MoQ Hidden; `moq-lite-07-wip` is opt-in only. +- The moq.pro mesh deploys lite-07 diff --git a/quest/m2/intra-refresh/bindings.md b/quest/m3/intra-refresh-bindings.md similarity index 94% rename from quest/m2/intra-refresh/bindings.md rename to quest/m3/intra-refresh-bindings.md index 78bbc95863d..ea45a3093db 100644 --- a/quest/m2/intra-refresh/bindings.md +++ b/quest/m3/intra-refresh-bindings.md @@ -21,5 +21,5 @@ both modes. ## Required -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - the core refresh variant this mirrors +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - the core refresh variant this mirrors - [Codecs](/quest/m1/ffi-shape/codec.md) - the `MoqVideoGop` enum this extends diff --git a/quest/m2/intra-refresh/encode-config.md b/quest/m3/intra-refresh-encode-config.md similarity index 86% rename from quest/m2/intra-refresh/encode-config.md rename to quest/m3/intra-refresh-encode-config.md index ab4f51ead77..14de81adb48 100644 --- a/quest/m2/intra-refresh/encode-config.md +++ b/quest/m3/intra-refresh-encode-config.md @@ -14,6 +14,11 @@ without replacing an API after 0.1. ## Plan +Decided in the 2026-09-30 audit: the encode side moved to m3 pending the +[GOP overhead](/quest/m2/gop-overhead.md) verdict. If a short keyframe GOP +is cheap, a flat bitrate is not worth encoder work; imported refresh streams +are still handled by [the m2 line](/quest/m2/intra-refresh/README.md). + - Extend the non-exhaustive `Gop` contract from main with refresh mode. Keep the settled frame-count units and `cut()` operation; do not replace the public config or rename the operation again. A cut in refresh mode asks @@ -43,4 +48,5 @@ without replacing an API after 0.1. ## Required +- [GOP overhead](/quest/m2/gop-overhead.md) - the verdict on whether keyframe cost justifies refresh encoding - [Catalog warmup](/quest/m1/catalog-warmup.md) - the field the producer publishes diff --git a/quest/m2/intra-refresh/nvenc-refresh.md b/quest/m3/intra-refresh-nvenc.md similarity index 78% rename from quest/m2/intra-refresh/nvenc-refresh.md rename to quest/m3/intra-refresh-nvenc.md index 5040bc67a0d..e540a8c3e25 100644 --- a/quest/m2/intra-refresh/nvenc-refresh.md +++ b/quest/m3/intra-refresh-nvenc.md @@ -21,12 +21,16 @@ refuses the mode. producer's `warmup` matches the refreshed macroblocks, and translate a cut into a forced sweep restart instead of `FORCEIDR`. Check the capability at construction and refuse without it. -- Verification needs hardware: no CI runner has an NVIDIA GPU, so run the - probe by hand, feed the output through the H.264 and H.265 import quests' +- Verification needs hardware: run it on the [GPU CI](/quest/m1/gpu-ci.md) + host once it exists, else run the probe by hand, feed the output through the H.264 and H.265 import quests' splitters to confirm one group per sweep and the SEI count, and record the numbers in the PR. Any test that needs the GPU skips loudly rather than reporting success. ## Required -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - the `Gop` enum and cut semantics this implements +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - the `Gop` enum and cut semantics this implements + +## Related + +- [GPU CI](/quest/m1/gpu-ci.md) - the RTX 3070 Ti runner that can verify this without a hand run diff --git a/quest/m2/intra-refresh/v4l2-refresh.md b/quest/m3/intra-refresh-v4l2.md similarity index 96% rename from quest/m2/intra-refresh/v4l2-refresh.md rename to quest/m3/intra-refresh-v4l2.md index 20b3c1fb1d2..40e969ae202 100644 --- a/quest/m2/intra-refresh/v4l2-refresh.md +++ b/quest/m3/intra-refresh-v4l2.md @@ -34,4 +34,4 @@ claiming a boundary that was not encoded. ## Required -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - the `Gop` enum and cut semantics this implements +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - the `Gop` enum and cut semantics this implements diff --git a/quest/m2/livekit-shim.md b/quest/m3/livekit-shim.md similarity index 74% rename from quest/m2/livekit-shim.md rename to quest/m3/livekit-shim.md index 6e5697e38c7..74e35d14d41 100644 --- a/quest/m2/livekit-shim.md +++ b/quest/m3/livekit-shim.md @@ -13,10 +13,14 @@ and the connect URL/token changed. ## Plan +In m3 until a LiveKit user asks to migrate; `@moq/room` already serves +new rooms directly. + - The shim is a LiveKit-API facade over `@moq/room`, which carries hang.live's convention: the room is a path prefix in the connection URL and token root, participants are discovered from the bare announce stream, identity is the - next path segment, and each participant publishes `/camera` - (camera + mic, hd/sd renditions) and `/screen` (screenshare, + path before the broadcast name, and each participant publishes + `/camera.hang` (camera + mic, hd/sd renditions) and + `/screen.hang` (screenshare, whose announce/unannounce is the screenshare lifecycle). The shim groups the two paths per identity into one RemoteParticipant and maps catalog entries to TrackPublications. @@ -27,10 +31,10 @@ and the connect URL/token changed. state derives from catalog track presence. Names and coarse state are a follow-up wired to the room SDK's `hang/*.json` metadata, not a rival scheme. -- Recommend tokens scoped to `put: /` so participants cannot - publish at each other's paths (hang.live grants `put` on the whole room - subtree today). +- Mint tokens with `@moq/room`'s `claims(room, identity)`, which scopes the + `publish` claim to the identity's subtree so participants cannot publish at + each other's paths. -## Related +## Required -- [WebRTC bridge evaluation](/quest/m2/livekit-webrtc-bridge.md) +- A LiveKit user asks for a drop-in client diff --git a/quest/m3/nvenc-av1.md b/quest/m3/nvenc-av1.md new file mode 100644 index 00000000000..1715d6ed32e --- /dev/null +++ b/quest/m3/nvenc-av1.md @@ -0,0 +1,31 @@ +# [M] NVENC AV1 encoding + +## Goal + +The NVENC backend encodes AV1 where the queried NVIDIA device and driver +support it, with OBU framing and an accurate catalog configuration through +transcode, and refuses it elsewhere. + +## Plan + +Split from the Main10 quest in the 2026-09-30 audit. It sits in m3 because it +is hardware-gated: AV1 NVENC needs an Ada GPU, and the only GPU CI host is an +RTX 3070 Ti. An Ada GPU on a CI host, or a consumer asking for AV1 encode, +brings it back. + +Query the capability at construction and refuse without it. Use existing +extensible codec enums; keep the NVIDIA backend optional and loaded at +runtime. Validate decoded pixels, profile, framing, drain, and refusal on +unsupported devices. Lack of suitable hardware leaves this unverified, not +complete. + +Public API: additive. Wire: existing AV1 codec signaling. + +## Required + +- Ada or newer NVIDIA GPU available for verification + +## Related + +- [Main10](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - the other half of #2147 +- [GPU CI](/quest/m1/gpu-ci.md) - the current runner lacks AV1 NVENC diff --git a/quest/m2/obs-linux-gpu.md b/quest/m3/obs-linux-gpu.md similarity index 93% rename from quest/m2/obs-linux-gpu.md rename to quest/m3/obs-linux-gpu.md index 7d29c34ec7f..2af3bc1b293 100644 --- a/quest/m2/obs-linux-gpu.md +++ b/quest/m3/obs-linux-gpu.md @@ -6,6 +6,9 @@ A supported Linux OBS graphics/encoder combination publishes composited video wi ## Plan +In m3 until the OBS encoder ships and a Linux user reports CPU readback as +the bottleneck. + - Start with an API feasibility probe. OBS exposes DMA-BUF import in `graphics.h`; that is not proof its compositor textures can be exported. Determine whether EGL/GL allocation export is available, or whether an upstream OBS hook or an encoder-owned exportable render target is required. - moq-video encodes a `Surface::DmaBuf` on VAAPI without a download, and scales one through VPP (moq-vaapi 0.1.0). This quest still has to turn an OBS compositor texture into a DMA-BUF that import accepts. - Negotiate DRM device, fourcc, plane offsets/strides, modifiers, and synchronization. Reuse `Surface::DmaBuf` and the hardware encoder's real import path, retaining allocation ownership until completion. A borrowed fd or an importable packed RGB texture does not prove the encoder accepts NV12 on the same device. @@ -19,5 +22,5 @@ A supported Linux OBS graphics/encoder combination publishes composited video wi ## Related -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - H.265 and checked-in bindings. The DMA-BUF encoder import this quest needs is already on main (moq-vaapi 0.1.0). - [Video hardware validation](/quest/m3/video-hardware.md) - native input and encoder acceptance need hardware evidence +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 and checked-in bindings. The DMA-BUF encoder import this quest needs is already on main (moq-vaapi 0.1.0). diff --git a/quest/m3/pipewire-camera-hardware.md b/quest/m3/pipewire-camera-hardware.md deleted file mode 100644 index 29ac05026d6..00000000000 --- a/quest/m3/pipewire-camera-hardware.md +++ /dev/null @@ -1,23 +0,0 @@ -# [S] Validate PipeWire cameras on a portal and a Pi - -## Goal - -The xdg-desktop-portal Camera path and a Raspberry Pi CSI camera each capture frames through the PipeWire camera that already shipped, or this quest records what stopped the pass. There is no new capture API. - -## Plan - -Open `pipewire` and one `pipewire:` in a sandbox, where the portal raises its permission dialog, and on a Pi whose CSI camera is a PipeWire node (spa-libcamera). Record the mode that opened, whether frames arrived, and whether the producer used one memory block or one per plane. - -Fix only a defect the pass hits. A separate-plane producer belongs to the multi-plane quest. If that is why a Pi produces nothing, write that down and stop. `doc/lib/rs/moq-video.md` says both paths are reachable. If a path cannot capture, correct that sentence in the same change. - -A libcamera source stays out. Embedded video already leaves `rpicam-vid` to the application. This pass uses the PipeWire camera only. - -## Required - -- A sandbox that can show the camera portal dialog, and a Raspberry Pi whose CSI camera appears as a PipeWire node - -## Related - -- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the pass finds them -- [Video hardware validation](/quest/m3/video-hardware.md) - the other encode and capture runs that still need a machine -- [Embedded video path](/quest/m3/video-embedded.md) - presenting on a Pi, which is a different gap diff --git a/quest/m3/processor-vision.md b/quest/m3/processor-vision.md deleted file mode 100644 index 672181a336c..00000000000 --- a/quest/m3/processor-vision.md +++ /dev/null @@ -1,43 +0,0 @@ -# [L] Reference vision worker - -## Goal - -A documented customer-run worker connects to a relay with an external processor -credential, subscribes to a low-resolution video rendition only when demanded, -runs object detection, and publishes frame-correlated bounding boxes as a Hang -contribution. The selected rendition is carried by the source broadcast rather -than referenced from another broadcast. A browser renders the boxes over -uninterrupted source video. - -## Plan - -Build the reference in an integration repository or in-tree example, not as a -hosted moq.pro (downstream) runtime. Keep the model replaceable and the output -contract plain: class, confidence, normalized bounds, source video rendition, -group sequence, and frame ordinal. The proof is about transport and lifecycle, -not model accuracy. - -Provide a five minute local path with a synthetic or recorded source and a -second path against a deployed relay with a real publisher. Demonstrate no -source subscription before output demand, requested rendition selection, -bounded latest-frame processing, clean demand teardown, reconnect, two -interchangeable workers on one logical contribution, token rotation, -revocation, and source withdrawal. Use the processor media contract's source -relation and the current net first-hop identity rules for failover and -reconnect; do not introduce a separate epoch field. Republish at the same -source path with a new source identity and prove stale inference output cannot -attach to the new source. Slow inference must drop stale work rather than -build latency. A fixture with a cross-broadcast rendition reference fails as -unsupported without subscribing to its target. Define refusal of an -unverifiable source relation in the shared contract before implementing it -here, and keep ordinary source playback independent of that refusal. - -Publish deployment examples for a local process and one generic container -platform, without tying anything in-tree to either. Record CPU/GPU and traffic -measurements so a customer can size its own worker. - -## Required - -- [Processor media contract](/quest/m1/processor/media-contract.md) - supplies - the contribution and source-relation schema the example worker must publish -- moq.pro processor registration exists (downstream, external condition) diff --git a/quest/m2/quic-gcc.md b/quest/m3/quic-gcc.md similarity index 71% rename from quest/m2/quic-gcc.md rename to quest/m3/quic-gcc.md index be4ba72d15f..ff482bdd4d1 100644 --- a/quest/m2/quic-gcc.md +++ b/quest/m3/quic-gcc.md @@ -26,7 +26,17 @@ than loopback. State the experiment's boundary beside the result: netem cannot establish behavior against production cross traffic or real wifi and cellular loss. +Receive timestamps are native-only: browsers never negotiate the extension, +so GCC can only target native peers or relay-to-relay sessions, not browser +egress. Decided in the 2026-09-30 audit: parked in m3 until such a consumer +exists. + ## Required -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - the per-packet +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - the per-packet arrival times the delay filter runs on + +## Related + +- [noq#818](https://github.com/n0-computer/noq/issues/818) - the GCC proposal to n0; matheus23 asked for a non-breaking `Controller` trait diff --git a/quest/m2/quic-receive-ts.md b/quest/m3/quic-receive-ts.md similarity index 69% rename from quest/m2/quic-receive-ts.md rename to quest/m3/quic-receive-ts.md index d36d4c299dd..7cf17d9bd8f 100644 --- a/quest/m2/quic-receive-ts.md +++ b/quest/m3/quic-receive-ts.md @@ -17,7 +17,7 @@ written reason it does not pay. `Controller` that hands each acknowledged packet its receive instant. Both ends are ours; browsers never see it. - Compare the forward delay it measures against the half-RTT estimate the - [deadline quest](/quest/m1/quic/deadline.md) starts with, on the impaired + [deadline quest](/quest/m2/quic-deadline.md) starts with, on the impaired path profile with asymmetric delay. Report how often the half-RTT estimate would have kept a hopeless retransmission or reset a deliverable one. - Measure the ACK overhead the timestamps add on a fanout-shaped relay egress, @@ -26,7 +26,16 @@ written reason it does not pay. The GCC experiment requires this; a delay-based controller without per-packet arrival times is a different, weaker experiment. +Both ends must be ours, so this is native-only and serves native peers or +relay-to-relay sessions. Decided in the 2026-09-30 audit: parked in m3 with +GCC until such a consumer exists. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork +- A native-to-native consumer of receive timestamps (browsers never see them) + ## Related -- [QUIC GCC](/quest/m2/quic-gcc.md) - the controller that consumes it -- [Per-stream deadlines](/quest/m1/quic/deadline.md) - the other consumer +- [QUIC GCC](/quest/m3/quic-gcc.md) - the controller that consumes it +- [Per-stream deadlines](/quest/m2/quic-deadline.md) - the other consumer diff --git a/quest/m2/routing-cost-domains.md b/quest/m3/routing-cost-domains.md similarity index 93% rename from quest/m2/routing-cost-domains.md rename to quest/m3/routing-cost-domains.md index 58e0ab5f1f8..f32615b6aed 100644 --- a/quest/m2/routing-cost-domains.md +++ b/quest/m3/routing-cost-domains.md @@ -4,7 +4,7 @@ Settle how independently operated MoQ networks exchange reachability without adding incomparable costs, at the cluster boundaries where -[Cluster routing](/quest/m1/cluster-routing.md) keeps path vector with cluster +[Cluster routing](/quest/m1/cluster-routing/README.md) keeps path vector with cluster ids as hops. Cost inside one cluster is cluster-routing's. Produce a reviewed design and scoped implementation quests, not a protocol implementation. Cloudflare, moq.pro, and self-hosted relays can retain their @@ -54,9 +54,11 @@ a second peer-policy mechanism. Completion is a documented decision, worked counterexamples or model checks, and independently completable follow-up quests. Open wire/API choices belong to this design exercise. +## Required + +- [Routing between clusters](/quest/m1/cluster-routing/inter-cluster.md) - this designs on its inter-cluster path vector + ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - in-cluster topology and - cost; this designs only what crosses its boundaries - [#3769](https://github.com/moq-dev/moq/pull/3769) - measurement-based pricing prompted the separation of measurement, operator policy, and protocol diff --git a/quest/m3/suffix-announce.md b/quest/m3/suffix-announce.md deleted file mode 100644 index 5e061f3b39d..00000000000 --- a/quest/m3/suffix-announce.md +++ /dev/null @@ -1,42 +0,0 @@ -# [L] Suffix announce and interest in moq-lite - -## Goal - -A moq-lite subscriber can request announcements by suffix (`**/transcode.pro`) -and a publisher can advertise one, so a fleet-wide service claims every -matching path once instead of per prefix. moq-lite only: IETF sessions stay -prefix-only. Routing only: token claim patterns keep their suffix support -unchanged. - -## Plan - -Decided in the 2026-09-28 quest audit: suffix routing is dropped from every -other quest, which are prefix-only, and lives here as a moq-lite-only -extension. IETF MoQT refuses suffix matching, so a session negotiated as IETF -never carries it and there is no draft to converge with. - -Today `AnnounceRequest` (`rs/moq-net/src/lite/announce.rs`) carries only a -`prefix`, and the origin's route table is a trie keyed by path segment -(`rs/moq-net/benches/origin.rs`). A suffix cannot walk that trie, so a naive -match costs the whole announce table on every announcement and every new -cursor. Requests hit the same wall: `request_broadcast` resolves through -`best_route`, which walks the prefix trie for the longest covering claim, so -a suffix advertisement must also be inserted where SUBSCRIBE and FETCH -resolution find it, with the same specificity rules as prefix claims. -Benchmark first: extend `rs/moq-net/benches/origin.rs` with suffix cursors -and suffix route lookups, each swept over publishers and subscribers. The -slopes decide between a reversed-segment index and abandoning the quest. - -The wire field is version-gated like `hidden`. Update `js/net` and -`drafts/draft-lcurley-moq-lite.md` in the same PR. Token patterns -(`moq-pattern`, `moq_auth::Claims`) already match suffixes and do not change. - -## Required - -- A deployment needs a suffix claim that a service prefix (`./...`) - cannot express - -## Related - -- [Wildcard](/quest/m0/wildcard/README.md) - prefix-only advertisements and the service-prefix layout this would extend -- [Path patterns](/quest/m1/path-patterns.md) - owns the pattern dialect a suffix interest would reuse diff --git a/quest/m2/teleop/browser-package.md b/quest/m3/teleop-browser-package.md similarity index 93% rename from quest/m2/teleop/browser-package.md rename to quest/m3/teleop-browser-package.md index 56e4c29449d..ec5319449bf 100644 --- a/quest/m2/teleop/browser-package.md +++ b/quest/m3/teleop-browser-package.md @@ -7,6 +7,8 @@ and delivery classes rather than reimplementing them. ## Plan +Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). + Follow the existing split: `net`, `hang`, `json` and `auth` each have a Rust crate and a TypeScript package, with zod schemas mirroring the Rust types. There is no `@moq/mux`, so the catalog extension goes through the same seam diff --git a/quest/m2/teleop/mavlink.md b/quest/m3/teleop-mavlink.md similarity index 97% rename from quest/m2/teleop/mavlink.md rename to quest/m3/teleop-mavlink.md index 91a5098faf6..b78ced31e6e 100644 --- a/quest/m2/teleop/mavlink.md +++ b/quest/m3/teleop-mavlink.md @@ -8,6 +8,8 @@ and MAVProxy connect unchanged. ## Plan +Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). + ### Shape A library crate reached through `moq-cli`, the way `moq-srt` and `moq-rtmp` diff --git a/quest/m2/teleop/proof.md b/quest/m3/teleop-proof.md similarity index 82% rename from quest/m2/teleop/proof.md rename to quest/m3/teleop-proof.md index cf45e914415..82a903937da 100644 --- a/quest/m2/teleop/proof.md +++ b/quest/m3/teleop-proof.md @@ -8,6 +8,8 @@ five minutes. ## Plan +Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). + The browser client subscribes video and telemetry and publishes control, the shape Blue Robotics' Cockpit proves is viable. It is the demo and the end-to-end proof of the primitive, not a bid to out-feature QGroundControl: @@ -23,5 +25,5 @@ the maintenance. ## Required -- [MAVLink bridge](/quest/m2/teleop/mavlink.md) -- [Browser teleoperation package](/quest/m2/teleop/browser-package.md) +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) +- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) diff --git a/quest/m2/unity.md b/quest/m3/unity.md similarity index 89% rename from quest/m2/unity.md rename to quest/m3/unity.md index d2acb94f081..3c3e42cd7c4 100644 --- a/quest/m2/unity.md +++ b/quest/m3/unity.md @@ -10,6 +10,8 @@ target, subscribes to a broadcast, and plays decoded audio through an ## Plan +In m3 with the C# line; a Unity consumer asking brings both back. + - IL2CPP forbids dynamic callback marshaling: every reverse P/Invoke needs a static method with `[MonoPInvokeCallback]`. Audit what the generated `cs/ffi` emits for callback interfaces and futures, and whether the generator needs @@ -24,4 +26,4 @@ target, subscribes to a broadcast, and plays decoded audio through an ## Required -- [Package](/quest/m2/cs/package.md) - the NuGet whose contents Unity imports +- [Package](/quest/m3/cs/package.md) - the NuGet whose contents Unity imports diff --git a/quest/m2/unreal.md b/quest/m3/unreal.md similarity index 85% rename from quest/m2/unreal.md rename to quest/m3/unreal.md index 64b59128097..04df6f976a5 100644 --- a/quest/m2/unreal.md +++ b/quest/m3/unreal.md @@ -10,6 +10,8 @@ editor stability across a play-stop-play cycle. ## Plan +In m3 until an Unreal consumer asks; the C++ package it links already exists. + - Consume the release tarball through the module's `Build.cs` (`PublicAdditionalLibraries`, include paths); Unreal's build does not use vcpkg or CMake, which is why the tarball exists alongside the registries. @@ -25,4 +27,4 @@ editor stability across a play-stop-play cycle. ## Required -- [Package](/quest/m1/cpp/package.md) - the tarball the module links +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the package the module links landed on this line (#4187) and reaches main with it diff --git a/quest/m3/upstream-forks.md b/quest/m3/upstream-forks.md deleted file mode 100644 index 45856ec20ed..00000000000 --- a/quest/m3/upstream-forks.md +++ /dev/null @@ -1,59 +0,0 @@ -# [S] Offer the uniffi generator fixes upstream - -## Goal - -Every general fix our uniffi generator forks carry has been offered to its -upstream, or recorded as declined or MoQ-specific, so each fork shrinks -toward a pin on an upstream tag. Very low priority: the forks work, and the -first step is someone else's review. Every external post, issue, or PR needs -the maintainer's approval at the time it is made. - -One outcome per candidate: - -- **uniffi-bindgen-cpp** (`kixelated/uniffi-bindgen-cpp`, forked from - LiveKit's `uniffi-0.31-async`, PR #1; - [#4100](https://github.com/moq-dev/moq/pull/4100)): the two leak fixes (a - ready Rust future freed without `rust_future_complete`, and a dropped - foreign future that never completed its oneshot), the missing - `#include ` MSVC needs, the uniffi 0.32 port, and - `error_style = "expected"`. The bug fixes are the easy offer; the 0.32 port - and the expected style depend on LiveKit taking async at all. -- **uniffi-dart** (`kixelated/uniffi-dart`; - [#4072](https://github.com/moq-dev/moq/pull/4072)): the - `nix/uniffi-dart-record-error.patch` and the RustBuffer release fixes. Fix - the latent `lowerForeignBytes` leak first (borrowed `&[u8]` arguments - allocate a `ForeignBytes` nothing frees; the free belongs after the call, - not inside the lowering), and audit callback interfaces for the same - RustBuffer leak, so the upstream offer is complete. `moq_ffi` uses neither - today. -- **uniffi-rs Python typing** of data-carrying enum variants - ([#4049](https://github.com/moq-dev/moq/pull/4049)): the generated type - makes `moq.VideoEncoderKind.AUTO()` fail pyright, so - `doc/lib/py/index.md` carries a `pyright: ignore`. Fix it at the source - and drop the ignore once a release carries it. - -## Plan - -- Decided in #4100: fork tags keep upstream's `v+v` - scheme with a `-kixelated.N` pre-release, e.g. - `v0.11.0-kixelated.1+v0.32.2`, matching the Dart fork. It never collides - with an upstream tag. Under SemVer a pre-release sorts before its base, so - this only works because every pin names the exact tag; never let tooling - pick "the newest" fork tag (Codex on #4307). The Go fork (`v0.9.0+v0.32.0`) moves to it - at its next bump. -- Offer each fix with the regression test it landed with. When upstream - merges one, move the pin in `flake.nix` (and the places its comment lists) - and delete the carried patch. -- Record each outcome (merged, declined with the reason, or not offered - because it is MoQ-specific) in the PR that finishes this quest. - -Public API: none. Wire: none. - -## Required - -- The maintainer approves offering the fixes upstream, per post, issue, or PR - -## Related - -- [Upstream the fork](/quest/m1/quic/upstream.md) - the same practice for the noq fork -- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the line that forked the C++ generator diff --git a/quest/m3/video-hardware.md b/quest/m3/video-hardware.md index c8bf739fabd..d2f420a456d 100644 --- a/quest/m3/video-hardware.md +++ b/quest/m3/video-hardware.md @@ -1,4 +1,4 @@ -# [M] Video hardware validation +# [L] Video hardware validation ## Goal @@ -8,32 +8,76 @@ real hardware get run on it, and what breaks gets fixed. ## Plan Every item here is blocked on a physical machine rather than on code, which is -why they sit together and why they sit in m3. +why they sit together and why they sit in m3. Decided in the 2026-09-30 audit: +the KDE DMA-BUF capture and PipeWire camera validations fold in here, and the +V4L2 `VIDIOC_EXPBUF` source is dropped with the export itself (see +[#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md)). - **VAAPI low-power entrypoint and a second GPU.** H.264 encode, DMA-BUF input, and VPP resize ran on Intel Meteor Lake with iHD (moq-vaapi 0.1.0). Still unrun: the low-power encode entrypoint, which that device does not expose, and `MOQ_VAAPI_DEVICE` naming a node other than the first render node. -- **VAAPI input from V4L2 `VIDIOC_EXPBUF`.** DMA-BUF encode ran from a VA-API - decode and from PipeWire. A V4L2 export has not been the source. - **Windows Media Foundation capture**: on-demand open and close, so the camera LED is off when nobody is watching, and NV12 delivery from MJPEG and YUY2 cameras. - **A live camera run per platform**: capture needs device permission that a headless or agent process cannot grant itself. -Precedent for what this catches: NVENC validation on an RTX 3070 Ti found that -NVENC rejects stream-ordered pool memory, so buffers registered with it must -come from plain `cuMemAlloc`. That is not a bug any amount of review finds. +### PipeWire DMA-BUF capture on KDE + +Tracked in [#2893](https://github.com/moq-dev/moq/issues/2893). On a +KDE/Wayland desktop the portal source was selected, but the ignored +`portal_captures_frames` test never received a frame and timed out at 120 +seconds: + +```sh +cargo nextest run --profile ci -p moq-video --all-features --run-ignored ignored-only portal_captures_frames --no-capture +``` + +- Reproduce the post-selection timeout, then add tracing around portal + completion, PipeWire connection, format fixation, buffer allocation, and + first-frame delivery to locate the stall. +- A DMA-BUF-capable compositor produces `Surface::DmaBuf`; confirm the linear + DMA-BUF CPU fallback and shared-memory capture still work when DMA-BUF is + unavailable. +- Refine the ignored test so this failure is distinguishable from a + portal-selection timeout. + +### PipeWire cameras on a portal and a Pi + +Open `pipewire` and one `pipewire:` in a sandbox, where the portal +raises its permission dialog, and on a Raspberry Pi whose CSI camera is a +PipeWire node (spa-libcamera). Record the mode that opened, whether frames +arrived, and whether the producer used one memory block or one per plane. +No new capture API, and no libcamera source. + +A separate-plane producer belongs to +[multi-plane cameras](/quest/m2/pipewire-camera-planes.md); if that is why a +Pi produces nothing, write it down and stop. `doc/lib/rs/moq-video.md` says +both paths are reachable; correct that sentence if one cannot capture. + +### Fixes + +Fix only a defect a run hits. Precedent for what this catches: NVENC +validation on an RTX 3070 Ti found that NVENC rejects stream-ordered pool +memory, so buffers registered with it must come from plain `cuMemAlloc`. That +is not a bug any amount of review finds. ## Required - Someone with the hardware runs it: an Intel GPU exposing the VAAPI low-power - entrypoint, a second render node, a V4L2 capture device with DMA-BUF export, - a Windows machine with MJPEG and YUY2 cameras, and a live camera per platform + entrypoint, a second render node, a Windows machine with MJPEG and YUY2 + cameras, a live camera per platform, a KDE/Wayland desktop with an Intel or + AMD GPU, a sandbox that can show the camera portal dialog, and a Raspberry + Pi whose CSI camera appears as a PipeWire node + +## Closes + +- [#2893](https://github.com/moq-dev/moq/issues/2893) - close this issue when the quest finishes ## Related -- [Validate PipeWire cameras on a portal and a Pi](/quest/m3/pipewire-camera-hardware.md) - the camera portal and a Pi CSI node, which are a different machine from this list -- [PipeWire DMA-BUF on KDE](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - the same kind of gate, for screen capture +- [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the DMA-BUF import validation this capture feeds +- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the Pi pass finds them +- [Embedded video path](/quest/m3/video-embedded.md) - presenting on a Pi, which is a different gap diff --git a/quest/m2/watch-data-sync.md b/quest/m3/watch-data-sync.md similarity index 71% rename from quest/m2/watch-data-sync.md rename to quest/m3/watch-data-sync.md index a8afced6e0d..16a287344c3 100644 --- a/quest/m2/watch-data-sync.md +++ b/quest/m3/watch-data-sync.md @@ -16,9 +16,10 @@ releases it. `delay` and `jitter` with `Sync` like a media rendition. - Snapshot tracks release the newest value at or before the playhead; stream tracks release every record in order. -- Take this up when an application needs synchronized data playback; until - then, a raw consumer reads payloads as they arrive. +- In m3 until an application needs synchronized data playback, such as + teleop telemetry beside video; until then, a raw consumer reads payloads as + they arrive. -## Related +## Required -- [Cross-track correlation](/quest/m2/teleop/correlation.md) - joins recordings on the broadcast clock rather than live playout +- [Data track clock](/quest/m1/data-track-clock.md) - data timestamps share the media clock mapping, so the playhead can release them diff --git a/quest/m2/whep-abr.md b/quest/m3/whep-abr.md similarity index 77% rename from quest/m2/whep-abr.md rename to quest/m3/whep-abr.md index af2367d95aa..b91c396e618 100644 --- a/quest/m2/whep-abr.md +++ b/quest/m3/whep-abr.md @@ -8,9 +8,16 @@ over MoQ, so a weak link gets SD instead of stalling on HD. ## Plan +In m3 until a WHEP viewer needs adaptive quality; MoQ viewers already switch +renditions, and a WHEP viewer gets the best rendition today. + Open questions: whether to drive switching from str0m's bandwidth estimate (TWCC) or from loss and REMB, how to switch without a keyframe gap (subscribe the new rendition and splice at its next group, as the JS decoder does), and whether offering the renditions as WebRTC simulcast layers (RIDs) buys anything for a receive-only browser. Keep the best rendition (`hang::catalog::Video::ranked`) as the starting rendition. + +## Required + +- A WHEP viewer that needs rendition switching diff --git a/quest/m4/README.md b/quest/m4/README.md index 2dbf68dde3d..5ef8cbfb662 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -7,13 +7,9 @@ so it is not forgotten. ## Plan -Each quest states its gate as a plain-text `Required` bullet. Re-check the -gates periodically; when one clears, remove the bullet and promote the quest to -the milestone its priority belongs in. +Each quest states its gate as a plain-text `Required` bullet, re-checked as the +root [questline](/quest/README.md) describes. ## Required -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - H.265 encode and decode, and pre-generated bindings that remove the libclang build dependency, gated on a moq-dev/vaapi release -- [Pool VAAPI resize surfaces](/quest/m4/vaapi-resize-pool.md) - a resize reuses one output surface per size once moq-vaapi ships that pool - [Safari WebTransport](/quest/m4/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed -- [MSFTS convergence](/quest/m4/msfts-convergence.md) - the demultiplexed TS lane maps onto MSFTS ES-level carriage once msfts#33 settles the payload unit diff --git a/quest/m4/msfts-convergence.md b/quest/m4/msfts-convergence.md deleted file mode 100644 index fb344dd510d..00000000000 --- a/quest/m4/msfts-convergence.md +++ /dev/null @@ -1,22 +0,0 @@ -# [M] MPEG-TS lane converges with MSFTS ES-level carriage - -## Goal - -A subscriber author can map this repository's demultiplexed TS lane -(access units, Hang catalog `mpegts` section) onto MSFTS ES-level carriage -without guessing. #3731 settled four of six divergences (scope, group -alignment as a SHOULD, mux rate, egress timing); the payload unit (access units -versus filtered 188-octet packets) is MSFTS's call at msfts#33, and SI -repetition is now per `table_id` here versus a subscriber obligation there. -Transporting TS verbatim is a non-goal. - -## Plan - -Once msfts#33 settles, re-read the draft and decide what converges: a -published mapping from the `mpegts` catalog section to the `m2ts` fields, or a -change on either side. Update `drafts/draft-lcurley-moq-mpegts.md` and -`doc/concept` with whatever lands. - -## Required - -- msfts#33 (https://github.com/mondain/msfts/issues/33) settles the ES-level payload unit diff --git a/quest/m4/safari-webtransport.md b/quest/m4/safari-webtransport.md index df16c0f41eb..85b3a454a0f 100644 --- a/quest/m4/safari-webtransport.md +++ b/quest/m4/safari-webtransport.md @@ -13,7 +13,7 @@ this. - Name the exact Safari and iOS or iPadOS releases that ship the fix in the quest and in the `browser.ts` comment, then gate on them for Safari and for the iOS WebKit browsers, keeping older versions on the fallback. As of - 2026-09-08 the bug is still NEW with no fix released. + 2026-09-30 the bug is still NEW with no fix released. - Before flipping, rerun the raw WebTransport reproduction from #2388 (about 7,600 eleven-byte unidirectional streams, and about 16 MiB of data) on the fixed Safari, then a watch longer than two minutes in the QA harness on diff --git a/quest/m4/vaapi-resize-pool.md b/quest/m4/vaapi-resize-pool.md deleted file mode 100644 index 6041e66901f..00000000000 --- a/quest/m4/vaapi-resize-pool.md +++ /dev/null @@ -1,19 +0,0 @@ -# [S] Pool VAAPI resize surfaces - -## Goal - -A VAAPI resize reuses one output surface per destination size instead of allocating one per frame. `Surface::resize` stays the same call. The decoder pool is unchanged. - -## Plan - -`Processor` in moq-vaapi allocates the blit output with `ExportedFrame::from_surface` on every resize. Keep one surface per output size. When the exported frame drops, that surface returns and the next blit of the same size uses it. A frame the consumer still holds is not overwritten; the processor allocates another. The pool keeps one free surface per size and destroys any surface returned past that, so a burst of released frames cannot park them all. That is the decoder pool's rule, applied to resize outputs. - -moq-video already blits through `Processor` and exports the result. The reuse test belongs in moq-vaapi. Here, bump the workspace requirement and confirm a resize still returns an NV12 DMA-BUF. - -## Required - -- A `moq-vaapi` release whose `Processor` reuses one output surface per destination size and destroys free surfaces past one per size - -## Related - -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - H.265 and checked-in bindings, the other moq-vaapi gate diff --git a/rs/hang/CHANGELOG.md b/rs/hang/CHANGELOG.md index 9083efe9a85..29fd8b30c5b 100644 --- a/rs/hang/CHANGELOG.md +++ b/rs/hang/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.21.9](https://github.com/moq-dev/moq/compare/hang-v0.21.8...hang-v0.21.9) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net, moq-json + ## [0.21.8](https://github.com/moq-dev/moq/compare/hang-v0.21.7...hang-v0.21.8) - 2026-09-27 ### Added diff --git a/rs/hang/Cargo.toml b/rs/hang/Cargo.toml index 6f9733a8353..940ce9dea4c 100644 --- a/rs/hang/Cargo.toml +++ b/rs/hang/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.21.8" +version = "0.21.9" edition = "2024" rust-version.workspace = true diff --git a/rs/justfile b/rs/justfile index 80611a247c3..c583c4e7393 100644 --- a/rs/justfile +++ b/rs/justfile @@ -11,700 +11,145 @@ set working-directory := '..' # `moq-net-fuzz` is a workspace member only so it shares the root lockfile; libFuzzer # needs a nightly toolchain and sanitizer flags, so `just rs fuzz` is the one recipe -# that may compile it. Every `--workspace` below therefore carries this, and a new -# one that forgets it pays a vendored C++ libFuzzer build for nothing. The root -# justfile's `check --all` and `fix --all` spell it out, since a module cannot read this. +# that may compile it. Every `--workspace` below therefore carries this, as does +# sh/rs/select.sh, since it cannot read this. no_fuzz := "--exclude moq-net-fuzz" default: just check -# Default features for the selected workspace packages, here and in CI. The full -# workspace permutations (`--all-features`, `--no-default-features`) each cost a -# separate compile that shares almost nothing with this one, so `features` below -# covers them nightly. `check-changed` makes one scoped exception for moq-tokio, -# whose feature-gated transport surface must compile in isolation to avoid -# workspace feature unification hiding a broken configuration. -# -# No `cargo check` pass: clippy is a superset of it, and the two use different -# rustc wrappers, so running both means compiling the workspace twice. +# Default features for the selected packages. The full workspace permutations +# each cost a separate compile, so `features` covers them nightly. No `cargo +# check` pass: clippy is a superset of it, and the two use different rustc +# wrappers, so running both compiles the workspace twice. # # A bare `just rs check` is default-members, which skips moq-c, moq-ffi, -# moq-gst, and moq-wasm (they need cbindgen, a uniffi build, GStreamer, and a -# wasm32 target respectively, so they stay out of a casual local check). Every -# recipe that means "all of it" therefore passes `--workspace` explicitly, since -# `check` is the only gate now and nothing else would compile them. +# moq-gst, and moq-wasm; pass `--workspace` for all of it. # Compile, lint, format-check, doc-check, and verify dependency hygiene. +[positional-arguments] check *args: - cargo clippy --locked --all-targets {{ args }} -- -D warnings - just rs _lint {{ args }} + cargo clippy --locked --all-targets "$@" -- -D warnings + just rs _lint "$@" -# `check` with the clippy pass replaced by `test`, whose clippy-driver build -# reports the same findings. `build.warnings` turns them into errors without -# entering cargo's fingerprint, so a later plain `test` reuses the artifacts. -# `--no-tests=pass` because a selection can hold nothing testable (see -# `test-changed`). +# `check` with clippy replaced by the `test` build, whose clippy-driver reports +# the same findings. `build.warnings` turns them into errors without entering +# cargo's fingerprint, so a later plain `test` reuses the artifacts. A +# selection can hold nothing testable (moq-wasm has no host tests). # Compile, lint, and test in one build, plus everything else `check` verifies. +[positional-arguments] check-test *args: - #!/usr/bin/env bash - set -euo pipefail - if ! command -v clippy-driver >/dev/null 2>&1; then - echo "rs: check-test needs clippy-driver to lint" >&2 - exit 1 - fi - CARGO_BUILD_WARNINGS=deny just rs test --no-tests=pass {{ args }} - just rs _lint {{ args }} + CARGO_BUILD_WARNINGS=deny RUSTC_WORKSPACE_WRAPPER={{ require("clippy-driver") }} cargo nextest run --locked --all-targets --no-tests=pass "$@" + just rs _lint "$@" # Everything `check` verifies besides clippy. +[positional-arguments] _lint *args: - just rs _select-test - just rs _publish-test - just rs _doc-names-test - # A new MoqConnectionStats field has to reach every binding's doc page. - python3 rs/scripts/stats-docs.py - rs/scripts/package-nfpm.test.sh + python3 sh/rs/stats-docs.py cargo fmt --all --check - just rs _doc-names - RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps {{ args }} + RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps "$@" cargo shear cargo sort --workspace --check --no-format -# Two targets whose names differ only by `-` vs `_` render to the same -# `target/doc/`, and a `cargo doc` that selects both races to clean it: the -# collision warning escalates to `error: failed to remove directory` depending on -# which rustdoc process gets there first. That reads as a flake, and because the doc -# pass above is diff-scoped it surfaces on whichever unrelated PR happens to select -# both crates. Resolve a pair by setting `doc = false` on whichever target has no -# published API to render (usually the binary). -# -# Metadata only, so this costs no compilation and can sit in the PR gate. Takes an -# optional metadata file so `_doc-names-test` can feed it synthetic workspaces. -_doc-names metadata="": - #!/usr/bin/env bash - set -euo pipefail - - if [[ -n "{{ metadata }}" ]]; then - collisions=$(jq -r -f rs/scripts/doc-names.jq < "{{ metadata }}") - else - collisions=$(cargo metadata --locked --no-deps --format-version 1 | jq -r -f rs/scripts/doc-names.jq) - fi - - if [[ -n "$collisions" ]]; then - echo "rs: these targets render to the same doc directory:" >&2 - echo "$collisions" >&2 - echo "set doc = false on whichever has no published API." >&2 - exit 1 - fi - -# Both directions of `_doc-names`, since the interesting half is what it must NOT -# report: cargo documents only the library when a binary shares its own package's -# name, so flagging that would reject the conventional src/lib.rs + src/main.rs layout. -_doc-names-test: - #!/usr/bin/env bash - set -euo pipefail - - scratch=$(mktemp -d) - trap 'rm -rf "$scratch"' EXIT - - # Same package, same name: cargo suppresses the bin, so this must pass. - cat > "$scratch/ok.json" <<'JSON' - {"packages":[{"name":"solo","targets":[ - {"name":"solo","kind":["lib"],"doc":true}, - {"name":"solo","kind":["bin"],"doc":true}]}]} - JSON - just rs _doc-names "$scratch/ok.json" - - # Same package, differing only by `-` vs `_`: cargo folds before suppressing, so - # this must pass too. Comparing the names as spelled would report it. - cat > "$scratch/folded.json" <<'JSON' - {"packages":[{"name":"folded","targets":[ - {"name":"foo_bar","kind":["lib"],"doc":true}, - {"name":"foo-bar","kind":["bin"],"doc":true}]}]} - JSON - just rs _doc-names "$scratch/folded.json" - - # Different packages: a real collision, must be reported. - cat > "$scratch/bad.json" <<'JSON' - {"packages":[ - {"name":"a-lib","targets":[{"name":"shared_name","kind":["lib"],"doc":true}]}, - {"name":"b-cli","targets":[{"name":"shared-name","kind":["bin"],"doc":true}]}]} - JSON - if just rs _doc-names "$scratch/bad.json" 2>/dev/null; then - echo "rs: _doc-names missed a cross-package collision" >&2 - exit 1 - fi - - # `doc = false` is how a pair gets resolved, so it must stop being reported. - cat > "$scratch/fixed.json" <<'JSON' - {"packages":[ - {"name":"a-lib","targets":[{"name":"shared_name","kind":["lib"],"doc":true}]}, - {"name":"b-cli","targets":[{"name":"shared-name","kind":["bin"],"doc":false}]}]} - JSON - just rs _doc-names "$scratch/fixed.json" - - echo "rs: _doc-names ok" - # Auto-fix clippy/format/shear/sort. +[positional-arguments] fix *args: - cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets {{ args }} + cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets "$@" cargo fmt --all cargo shear --fix cargo sort --workspace --no-format -# Prints `ALL` when the diff hits something every crate depends on, and nothing -# when no crate is affected. -# -# FILES is an exported parameter, not `{{ FILES }}`: just interpolates the -# latter into the recipe source, where a filename like `$(...)` would run as a -# command. Git-derived paths are untrusted input, so they stay data. - -# Print `--package` flags for the crates a diff touches, plus their dependents. -[private] -_select $FILES: - #!/usr/bin/env bash - set -euo pipefail - - # Workspace-wide inputs affect every crate, so there is nothing to scope to. - # - # `rs/justfile` and the nextest config are in here because they define how - # every crate is checked and tested. They also match `^rs/` below while - # seeding no crate (the seed pattern needs `rs//...`), so without this - # a PR editing only the recipes would compile and test nothing at all, and a - # broken cargo flag would pass CI on a format check alone. - if [[ -z "$FILES" ]] || grep -qE '^(Cargo\.(toml|lock)|rust-toolchain\.toml|rs/justfile|\.config/nextest\.toml)$' <<< "$FILES"; then - echo ALL - exit 0 - fi - - grep -q '^rs/' <<< "$FILES" || exit 0 - - # `--no-deps` keeps this to workspace members and off the network. - metadata=$(cargo metadata --format-version 1 --no-deps) - - # A seed is the first path segment under `rs/`, so only a crate whose manifest - # sits directly at `rs//Cargo.toml` can ever be one. Drop the rest here: - # `moq-net-fuzz` lives at `rs/moq-net/fuzz`, so its seed is already `moq-net`, - # and leaving it in the graph would select it as a dependent of the crate it - # fuzzes and compile libFuzzer on every moq-net diff. - # - # `manifest_path` is a native path, so normalize the separator before splitting - # on it. Windows would otherwise match no segment, drop every package, and - # select nothing at all, where the assertion below fails safe to ALL. - metadata=$(jq '.packages |= map((.manifest_path |= gsub("\\\\"; "/")) | select(.manifest_path | split("/")[-3] == "rs"))' <<< "$metadata") - - # Every remaining crate directory is named after the crate it holds, which is - # what makes a changed path a seed below. Verify it rather than trust it: under- - # selecting silently checks nothing, so fall back to checking everything. - if jq -e '.packages[] | select((.manifest_path | split("/")[-2]) != .name)' <<< "$metadata" > /dev/null; then - echo "rs: a crate directory no longer matches its crate name; selecting everything." >&2 - echo ALL - exit 0 - fi - - seeds=$(sed -n 's|^rs/\([^/]*\)/.*|\1|p' <<< "$FILES" | sort -u) - - # Every workspace member, not just the default ones. `--no-deps` already - # limits this to the workspace. The non-default members (moq-c, moq-ffi, - # moq-gst, moq-wasm) have to participate as both seeds and dependents: they - # used to drop out here because `check` matched a bare `cargo check`, but - # `check` is the only gate now, and the `cargo clippy --workspace` in the - # deleted `just rs ci` is what used to cover them. Without them, a PR - # touching only rs/moq-c selects nothing and compiles nothing. - edges=$(jq -r ' - .packages[] - | .name as $name - | .dependencies[] - | "\($name) \(.name)" - ' <<< "$metadata") - - # A crate has to be rebuilt when anything it depends on changed, so walk the - # edges backwards until the selection stops growing. - selected=$(awk -v seeds="$seeds" ' - BEGIN { split(seeds, s, "\n"); for (i in s) want[s[i]] = 1 } - { pkg[NR] = $1; dep[NR] = $2 } - END { - do { - grew = 0 - for (i = 1; i <= NR; i++) - if (want[dep[i]] && !want[pkg[i]]) { want[pkg[i]] = 1; grew = 1 } - } while (grew) - # Every wanted crate, not just those that appear as an edge source: a - # crate with no dependencies of its own emits no edge, so keying the - # output on `pkg[i]` would drop it and select nothing for a direct - # change to it. Test the VALUE, not the key -- awk creates a key on - # every `want[dep[i]]` read above, so iterating keys alone would emit - # every crate the workspace mentions. The lookup below drops names that - # are not workspace crates, which is what keeps a seed like the - # non-crate `rs/scripts` from reaching cargo. - for (name in want) if (want[name]) print name - } - ' <<< "$edges" | sort -u) - - [[ -n "$selected" ]] || exit 0 - - # Emit cargo's own package ids, not bare names. A workspace crate we also - # publish collides with its crates.io copy as soon as any dependency pulls - # that copy in (the web-transport-* crates depend on a published `kio`), and - # `--package kio` is then ambiguous: cargo refuses during package selection, - # before compiling anything, so the whole gate fails. Ids from `cargo - # metadata` carry the source, so they are unambiguous by construction. - jq -r --arg selected "$selected" ' - ($selected | split("\n")) as $want - | .packages[] - | select(.name as $name | $want | index($name) != null) - | "--package \(.id)" - ' <<< "$metadata" | sort -u | tr '\n' ' ' - -# Bare crate names for the `--package ` flags `_select` emits, for log lines -# and for the wasm gate's alternation below. Matching names rather than the flag -# spelling keeps those call sites working whatever spec form `_select` uses; the -# previous alternation matched `--package ` literally and silently stopped -# firing the moment the spec form changed. Ids are `path+file://#` -# and `_select` only emits crates whose directory it has verified matches -# their crate name, so the last path segment is the name. - -# True when a selection includes a crate the wasm32 pass covers. One predicate -# rather than the same alternation in each gate, so the test below exercises what -# the gates actually run instead of a copy of it. -[private] -_wants-wasm $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qwE '(moq-wasm|moq-mux|moq-ffi)' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes moq-tokio, whose zero-feature build is hidden -# by workspace feature unification whenever any dependent enables a transport. -[private] -_wants-tokio-features $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qw 'moq-tokio' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes a crate with a `capture` feature. Selection -# pulls in dependents, so a diff to moq-mux or moq-net lands here too, which is -# how a rename in either reaches the device code that calls it. -[private] -_wants-capture $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qwE '(moq-video|moq-audio)' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes moq-cli, whose `play` media tasks are off the -# default feature set. Selection pulls in dependents, so a diff to anything the -# player is built from (moq-audio, moq-video, moq-mux) lands here too. -[private] -_wants-play $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qw 'moq-cli' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes moq-relay, whose io_uring listener is off the -# default feature set. Selection pulls in dependents, so a diff to any crate the -# relay is built from (moq-uring, moq-sock, moq-tokio) lands here too. -[private] -_wants-uring $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qw 'moq-relay' <<< "$(just rs _names "$PACKAGES")" +# Like `check`, but only the crates in a changed-file list plus their dependents. +check-changed $LIST: + sh/rs/select.sh check "$LIST" -# True when the media feature contracts have to run. The contract script is not -# a crate, so `_select` drops it; a diff that only edits the script must still -# reach the gate, or a broken command merges on shell lint alone. -[private] -_wants-media-features $PACKAGES $FILES: - #!/usr/bin/env bash - set -euo pipefail - grep -qwE '(moq-video|moq-audio|moq-transcode)' <<< "$(just rs _names "$PACKAGES")" \ - || grep -qx 'rs/scripts/media-features.sh' <<< "$FILES" +# Like `check-test`, but only the crates in a changed-file list plus their dependents. +check-test-changed $LIST: + sh/rs/select.sh check-test "$LIST" -# Print the crate names behind a list of `--package` flags. -[private] -_names $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - tr ' ' '\n' <<< "$PACKAGES" | sed -n 's|.*/\([^/#]*\)#.*|\1|p' | sort -u | tr '\n' ' ' +# Like `fix`, but only the crates in a changed-file list plus their dependents. +fix-changed $LIST: + sh/rs/select.sh fix "$LIST" -# Guards the two things about selection that fail SILENTLY rather than loudly: -# a `--package` spec cargo cannot resolve takes the gate down before it compiles -# anything, and a wasm gate that stops matching skips the only pass that ever -# looks at moq-wasm's code (its crate root is `#![cfg(target_arch = "wasm32")]`, -# so the host pass sees an empty crate and reports success). Both have happened. - -# Check that selection emits resolvable specs and still drives the wasm gate. -[private] -_select-test: - #!/usr/bin/env bash - set -euo pipefail - - fail() { echo "rs: _select-test: $1" >&2; exit 1; } - - # `kio` is published and pulled from crates.io by the web-transport-* crates, - # so the workspace copy and the registry copy share a name: a bare name is - # ambiguous and cargo refuses. Every emitted spec must name its source, and - # cargo must accept it. - packages=$(just rs _select "rs/kio/src/waiter.rs") - for spec in $(sed 's/--package //g' <<< "$packages"); do - [[ "$spec" == *"file://"* ]] || fail "expected a source-qualified id, got: $spec" - cargo pkgid --offline "$spec" > /dev/null 2>&1 || fail "cargo cannot resolve: $spec" - done - - # The wasm gate keys on names, so it survives whatever spec form the ids use. - just rs _wants-wasm "$packages" \ - || fail "a kio diff must still drive the wasm gate: $(just rs _names "$packages")" - - # ...and it must still be able to say no, or it is not a gate. - relay=$(just rs _select "rs/moq-relay/src/web.rs") - if just rs _wants-wasm "$relay"; then - fail "a moq-relay diff must not drive it: $(just rs _names "$relay")" - fi - - # The break the capture gate was added for: a moq-mux API change that missed - # its callers behind `capture`. A moq-mux diff has to reach it. - mux=$(just rs _select "rs/moq-mux/src/clock.rs") - just rs _wants-capture "$mux" \ - || fail "a moq-mux diff must drive the capture gate: $(just rs _names "$mux")" - if just rs _wants-capture "$relay"; then - fail "a moq-relay diff must not drive the capture gate: $(just rs _names "$relay")" - fi - - # The break the uring gate was added for: a change that breaks moq-relay's - # io_uring listener, which the default pass above never compiles. A moq-relay - # diff has to reach it, and a diff that cannot affect the relay must not. - just rs _wants-uring "$relay" \ - || fail "a moq-relay diff must drive the uring gate: $(just rs _names "$relay")" - hls=$(just rs _select "rs/moq-hls/src/lib.rs") - if just rs _wants-uring "$hls"; then - fail "a moq-hls diff must not drive the uring gate: $(just rs _names "$hls")" - fi - - tokio=$(just rs _select "rs/moq-tokio/src/lib.rs") - just rs _wants-tokio-features "$tokio" \ - || fail "a moq-tokio diff must drive its feature matrix: $(just rs _names "$tokio")" - if just rs _wants-tokio-features "$relay"; then - fail "a moq-relay-only selection must not drive the moq-tokio feature matrix" - fi - - # A non-crate directory under rs/ seeds a name that is not a package. It must - # select nothing rather than reach cargo as a bogus spec. - [[ -z "$(just rs _select "rs/scripts/package-binary.sh")" ]] \ - || fail "a non-crate seed must select nothing" - - # The contract script is that same kind of seed, so selection stays empty. - # The gate still has to run it: this is the diff that can break the commands. - [[ -z "$(just rs _select "rs/scripts/media-features.sh")" ]] \ - || fail "the media contract script must not select a crate" - just rs _wants-media-features "" "rs/scripts/media-features.sh" \ - || fail "a media-features.sh diff must drive the contract" - if just rs _wants-media-features "" "rs/scripts/package-binary.sh"; then - fail "an unrelated script must not drive the media contract" - fi - video=$(just rs _select "rs/moq-video/src/lib.rs") - just rs _wants-media-features "$video" "" \ - || fail "a moq-video diff must drive the media contract: $(just rs _names "$video")" - just rs _wants-media-features "--package file:///tmp/rs/moq-transcode#0" "" \ - || fail "moq-transcode alone must drive the media contract" - if just rs _wants-media-features "$relay" ""; then - fail "a moq-relay diff must not drive the media contract: $(just rs _names "$relay")" - fi - - # A crate nested inside another crate's directory is covered by its parent's - # seed. Selecting it directly would compile libFuzzer on every moq-net diff, - # and its directory name is not its crate name, so it would also mis-report. - fuzz=$(just rs _names "$(just rs _select "rs/moq-net/fuzz/fuzz_targets/lite.rs")") - grep -qw moq-net <<< "$fuzz" || fail "a fuzz diff must select moq-net: $fuzz" - ! grep -qw fuzz <<< "$fuzz" || fail "a fuzz diff must not select the harness: $fuzz" - - echo "rs: selection ok" - -# Published crates need the current workspace version as the lower bound for -# internal dependencies. The workspace only tests that version set, and a looser -# bound lets package verification combine incompatible older releases. -# -# Internal dev-dependencies must be path-only. `cargo publish` keeps a versioned -# dev-dependency and requires it on crates.io, but release-plz orders publishes -# by normal dependencies only, so a bumped dev-dependency is often not there yet. -[private] -_publish-test: - #!/usr/bin/env bash - set -euo pipefail - - metadata=$(cargo metadata --locked --format-version 1 --no-deps) - stale=$(jq -r ' - .packages as $packages - | $packages[] as $package - | select($package.publish != []) - | $package.dependencies[] - | select(.source == null and .path != null and .kind != "dev") - | . as $dependency - | ($packages[] | select(.name == $dependency.name)) as $current - | select($dependency.req != ("^" + $current.version)) - | "\($package.name): \($dependency.name) requires \($dependency.req), current is ^\($current.version)" - ' <<< "$metadata") - - if [[ -n "$stale" ]]; then - echo "rs: published workspace dependency lower bounds are stale:" >&2 - echo "$stale" >&2 - exit 1 - fi - - versioned=$(jq -r ' - .packages[] - | select(.publish != []) - | .name as $package - | .dependencies[] - | select(.source == null and .path != null and .kind == "dev" and .req != "*") - | "\($package): \(.name) \(.req)" - ' <<< "$metadata") - - if [[ -n "$versioned" ]]; then - echo "rs: published crates have versioned workspace dev-dependencies:" >&2 - echo "$versioned" >&2 - echo "use { path = \"../\" } instead of { workspace = true }." >&2 - exit 1 - fi - - echo "rs: published workspace dependencies current" - -# Takes a newline-separated list of changed files; skips when no crate is -# affected. The `just rs ...` calls below go through the root justfile's -# `mod rs` because these recipes run from the repo root, where a bare `check` -# would resolve to the root recipe of that name. - -# Like `check`, but only the crates a diff touches plus their dependents. -# TEST=true runs `check-test` in place of `check`. -check-changed $FILES $TEST="false": - #!/usr/bin/env bash - set -euo pipefail - recipe=check - [[ "$TEST" == true ]] && recipe=check-test - packages=$(just rs _select "$FILES") - case "$packages" in - "") echo "rs: no crates affected; skipping." ;; - ALL) just rs "$recipe" --workspace {{ no_fuzz }} ;; - *) echo "rs: checking $(just rs _names "$packages")"; just rs "$recipe" $packages ;; - esac - - if [[ "$packages" == "ALL" ]] || just rs _wants-tokio-features "$packages"; then - just rs tokio-features - fi - - # moq-wasm's crate root is entirely `#![cfg(target_arch = "wasm32")]`, so - # however it got selected the host-target pass above compiled it to nothing - # and saw no errors in it. This wasm32 pass is what actually checks it. - # - # The alternation must list every package `wasm` compiles, not just moq-wasm: - # nothing in the workspace depends on moq-ffi, so an moq-ffi-only diff selects - # only itself and would never reach the gate that exists to cover it. moq-mux - # is selected by its dependents, none of which are moq-wasm. - if [[ "$packages" == "ALL" ]] || just rs _wants-wasm "$packages"; then - just rs wasm - fi - - # moq-video's and moq-audio's device code is behind `capture`, which is off - # by default, so the pass above never compiles it. Only nightly's - # `--all-features` did, and a break there lands on main. With TEST=true the - # lint rides the test build, as in `check-test`. - if [[ "$packages" == "ALL" ]] || just rs _wants-capture "$packages"; then - if [[ "$TEST" == true ]]; then - CARGO_BUILD_WARNINGS=deny just rs capture-test - else - just rs capture - fi - fi - - # moq-cli's media tasks are behind `play`, off by default, so the test pass - # above never runs them. Only `check` tests, so the lint-only CI job skips it. - if [[ "$TEST" == true ]] && { [[ "$packages" == "ALL" ]] || just rs _wants-play "$packages"; }; then - just rs play - fi - - # moq-relay's io_uring listener is behind `io-uring`, off by default, so the - # pass above never compiles it. `check --all` reaches it through `bench - # check`, but only for a diff under `bench/`; a relay change would otherwise - # land on the nightly. - if [[ "$packages" == "ALL" ]] || just rs _wants-uring "$packages"; then - just rs uring-check - fi - - # Each media feature shape compiles on its own (see rs/scripts/media-features.sh), - # about two minutes, so only a diff that reaches the media crates, or the - # contract script itself, pays for it. - if [[ "$packages" == "ALL" ]] || just rs _wants-media-features "$packages" "$FILES"; then - just rs media-features - fi +# Like `test`, but only the crates in a changed-file list plus their dependents. +test-changed $LIST: + sh/rs/select.sh test "$LIST" # Compile moq-tokio by itself at the feature extremes and with each crypto provider. -# Its default-feature build is already part of the ordinary clippy pass above. tokio-features: - #!/usr/bin/env bash - set -euo pipefail - - cargo clippy --locked -p moq-tokio --no-default-features -- -D warnings - cargo clippy --locked -p moq-tokio --all-features -- -D warnings - cargo clippy --locked -p moq-tokio --no-default-features --features noq,aws-lc-rs -- -D warnings - cargo clippy --locked -p moq-tokio --no-default-features --features noq,ring -- -D warnings - - for feature in aws-lc-rs ring tcp uds websocket; do - cargo clippy --locked -p moq-tokio --no-default-features --features "$feature" -- -D warnings - done - - want='a rustls QUIC backend requires a crypto provider: enable either the `aws-lc-rs` or `ring` feature' - if output=$(cargo check --locked -p moq-tokio --no-default-features --features noq 2>&1); then - echo "rs: moq-tokio with only noq should reject its missing crypto provider" >&2 - exit 1 - fi - if ! grep -qF "$want" <<< "$output"; then - echo "rs: moq-tokio with only noq should fail on: $want" >&2 - echo "$output" | grep -E '^error' >&2 || true - exit 1 - fi + sh/rs/tokio-features.sh -# Same as `fix`, but scoped the same way as `check-changed`. -fix-changed $FILES: - #!/usr/bin/env bash - set -euo pipefail - packages=$(just rs _select "$FILES") - case "$packages" in - "") echo "rs: no crates affected; skipping." ;; - ALL) just rs fix --workspace {{ no_fuzz }} ;; - *) echo "rs: fixing $(just rs _names "$packages")"; just rs fix $packages ;; - esac +# Runs the `#[cfg(windows)]` code past the compiler, which the Linux gate +# skips; platform.yml runs it on a Windows runner, scoped like `check-changed` +# so a one-crate PR compiles one crate on these slow runners too. Default +# features, since jemalloc doesn't build on MSVC. - # Mirrors `check-changed`'s gate, alternation included: without this a wasm32 - # lint is never auto-fixed, and `check`'s wasm32 clippy pass fails on it later. - if [[ "$packages" == "ALL" ]] || just rs _wants-wasm "$packages"; then - just rs wasm-fix - fi - -# Runs the `#[cfg(windows)]` code past the compiler, which the Linux gate skips -# entirely: moq-video's Media Foundation capture/encode/decode and its D3D11 -# frames, moq-nvenc's Windows loader, and the Winsock paths in moq-tokio. A -# native host rather than a cross-compile, because openh264-sys2's vendored C++ -# needs an MSVC toolchain. platform.yml runs this on every pull request and -# every push to main and dev. -# -# Default features rather than `--all-features`: jemalloc doesn't build on -# MSVC, and the Linux-only features (vaapi, pipewire, io-uring) have nothing to -# compile here. moq-gst is excluded because it links GStreamer via pkg-config, -# which the runner doesn't have. -# -# `moq-cli/play` and `moq-cli/capture` are named explicitly because they are -# off by default, and they are what turns on the device and render code in -# moq-video, moq-audio, and the cli itself. - -# Compile the whole workspace on a Windows host. Must run ON Windows. -windows *args: - cargo check --locked --workspace --exclude moq-gst {{ no_fuzz }} --all-targets --features "moq-cli/play moq-cli/capture" {{ args }} +# Compile what the branch changed since BASE on a Windows host, or everything with `--all`. +windows $BASE="": + sh/rs/platform.sh "$BASE" # Compile and test the io_uring relay path, which is off the default feature set. # Linux-only, and the tests below the 6.12 kernel floor skip themselves. -# -# `qlog` is a second axis, and the traces are what a debugging run depends on, -# so it gets a separate pass. +[positional-arguments] uring *args: - just rs uring-check {{ args }} - cargo nextest run --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets {{ args }} - cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring,moq-relay/qlog --all-targets {{ args }} -- -D warnings - cargo nextest run --locked -p moq-uring --features qlog --all-targets {{ args }} + just rs uring-check "$@" + cargo nextest run --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets "$@" + cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring,moq-relay/qlog --all-targets "$@" -- -D warnings + cargo nextest run --locked -p moq-uring --features qlog --all-targets "$@" -# Compile the io_uring relay path, off the default feature set. `check-changed` -# runs this whenever moq-relay is selected, so a change that breaks the ring -# listener fails its own PR rather than landing on the nightly. +# Compile the io_uring relay path, off the default feature set. +[positional-arguments] uring-check *args: - cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets {{ args }} -- -D warnings - -# Runs the Apple-gated code past the compiler: moq-video's VideoToolbox -# encode/decode and its ScreenCaptureKit / AVFoundation capture, moq-audio's -# ScreenCaptureKit system audio and TCC permission pre-check, and moq-sock's -# BSD socket-buffer sysctl. platform.yml runs this alongside `windows`. -# -# The same workspace and features as `windows`, for the same reasons: moq-gst -# needs GStreamer, and the cli's `play` and `capture` features are what turn on -# the device and render code. + cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets "$@" -- -D warnings -# Compile the whole workspace on a macOS host. Must run ON macOS. -macos *args: - cargo check --locked --workspace --exclude moq-gst {{ no_fuzz }} --all-targets --features "moq-cli/play moq-cli/capture" {{ args }} +# The Apple-gated code in moq-video, moq-audio, and moq-sock, which +# platform.yml compiles on a Mac runner alongside `windows`. -# The Linux device code: moq-video's V4L2 and X11 capture and moq-audio's cpal -# capture, all behind the off-by-default `capture` feature. `check-changed` runs -# this whenever either crate is selected. The per-crate `--features` spelling -# keeps it to those two instead of widening what their dependencies compile. -# `--all-features` would also build the bindgen codecs, which nightly covers. +# Compile what the branch changed since BASE on a macOS host, or everything with `--all`. +macos $BASE="": + sh/rs/platform.sh "$BASE" # Compile and lint the capture feature, which the default check skips. +[positional-arguments] capture *args: - cargo clippy --locked -p moq-video -p moq-audio --all-targets --features moq-video/capture,moq-audio/capture {{ args }} -- -D warnings + cargo clippy --locked -p moq-video -p moq-audio --all-targets --features moq-video/capture,moq-audio/capture "$@" -- -D warnings -# The capture publishers' tests (the clock fixtures among them) drive synthetic -# devices, so they need no hardware and run with every PR that reaches either crate. +# The capture tests drive synthetic devices, so they need no hardware. # Test the capture feature, which the default test pass skips. +[positional-arguments] capture-test *args: - just rs test -p moq-video -p moq-audio --features moq-video/capture,moq-audio/capture {{ args }} + just rs test -p moq-video -p moq-audio --features moq-video/capture,moq-audio/capture "$@" -# Same idea as `windows`/`macos`, for Android: moq-video's MediaCodec encoder and -# decoder, its `Surface::HardwareBuffer` variant, and the `frame::android` module -# are all `#[cfg(target_os = "android")]`, so a host-target check compiles none of -# them and every error in them stays invisible. -# -# Unlike `windows` and `macos` this needs no special host: the Android targets -# cross-compile from Linux in about half a minute. It needs an NDK, which -# `cargo-ndk` finds through `ANDROID_NDK_HOME` or the standard SDK layout. The -# dev shell provides neither, so android.yml runs this outside Nix on a GitHub -# runner, whose image ships an NDK, for every PR that touches moq-video or -# anything it is built from. -# -# arm64-v8a alone: it is the only ABI anything here ships, and the code is not -# ABI-specific, so the other two would compile the same source twice more. -# -# `check` rather than a `-D warnings` clippy, matching `windows` and `macos`: -# the capture module's plumbing is dead on a target with no capture backend, so -# a denying lint would fail on code this recipe is not here to police. +# moq-video's MediaCodec code is `#[cfg(target_os = "android")]`. Needs an NDK, +# which the dev shell lacks, so android.yml runs it outside Nix. `check` rather +# than a denying clippy: the capture plumbing is dead on a target without a +# capture backend. # Compile the Android backends, which the host-target check skips. +[positional-arguments] android *args: - cargo ndk -t arm64-v8a --platform 26 check --locked -p moq-video --all-targets {{ args }} - -# Same idea as `windows`/`macos`, for the browser: moq-wasm's whole crate root is -# `#![cfg(target_arch = "wasm32")]`, so a host-target `cargo check --workspace` -# compiles an empty crate and every error in it stays invisible. Only a wasm32 -# build sees the code. -# -# Unlike those two this needs no special host, so `ci` runs it on every Rust PR. -# The wasm32 target and the `getrandom`/`web-sys` cfg flags come from the Nix dev -# shell and `.cargo/config.toml`. Not to be confused with the root `just wasm`, -# which builds the shippable `@moq/wasm` package (wasm-bindgen, release profile); -# this is the compile gate. + cargo ndk -t arm64-v8a --platform 26 check --locked -p moq-video --all-targets "$@" -# `moq-mux` and `moq-ffi` ride along in the same invocation on purpose: `moq-mux` -# needs `getrandom`'s `wasm_js` backend that only its siblings declare, and feature -# unification only happens within one cargo invocation. Splitting them fails on -# getrandom. `--lib` rather than `--all-targets` because moq-mux's tests use tokio's -# native timers and moq-ffi's drive a native relay; moq-wasm has no test targets, so -# it loses no coverage. +# moq-wasm's crate root is `#![cfg(target_arch = "wasm32")]`, so only a wasm32 +# build sees the code. Not to be confused with `just js wasm`, which builds the +# shippable `@moq/wasm` package. `moq-mux` and `moq-ffi` share the invocation +# because moq-mux needs the getrandom backend only its siblings declare, and +# features unify only within one cargo invocation. # Compile and lint the browser/WASM bindings, which the host-target check skips. +[positional-arguments] wasm *args: - cargo clippy --locked -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib {{ args }} -- -D warnings - -# The `fix` counterpart to `wasm`. `cargo fmt` is scoped rather than `--all` -# because this runs alongside `fix`, which already formats everything else. + cargo clippy --locked -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib "$@" -- -D warnings # Auto-fix the browser/WASM bindings. +[positional-arguments] wasm-fix *args: - cargo clippy --locked --fix --allow-staged --allow-dirty -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib {{ args }} + cargo clippy --locked --fix --allow-staged --allow-dirty -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib "$@" cargo fmt -p moq-wasm -p moq-mux -p moq-ffi -# Dependency advisories plus the license/ban policy. Time-based rather than -# diff-based: an advisory lands without this repo changing, so a per-PR run both -# fires on PRs that cannot affect it and stays silent on the days nobody pushes. -# Runs nightly instead (.github/workflows/nightly.yml), which also keeps a fresh -# advisory from blocking an unrelated PR mid-review. - -# Audit dependencies against deny.toml. +# Audit dependencies against deny.toml. Nightly: advisories land without a diff. audit: cargo deny check --show-stats @@ -712,109 +157,16 @@ audit: relay-minimal: cargo nextest run --locked -p moq-relay --no-default-features --lib -E 'test(workers_require_a_quic_backend)' -# moq-c's C fixtures (`rs/moq-c/c-tests/*.c`) link `libmoq.a` the way an -# embedder does: an external `cc` against the generated `moq.h`, plus the native -# libraries from `rs/moq-c/native-libs` that cargo can't inject into a link it -# doesn't drive. Each fixture pins part of the C ABI at compile time and -# exercises it at runtime, so it has to run, not just compile. -# -# Outside nextest on purpose. The staticlib link alone takes ~2 minutes, past the -# hang budget in `.config/nextest.toml` once the rest of the workspace builds -# beside it, and `rs/AGENTS.md` says to make a slow test fast, not to raise the -# ceiling. obs.yml runs this on every PR that touches rs/moq-c, right after it -# has built the same debug libmoq.a for the plugin, and nightly.yml covers the -# paths that filter misses. -# -# Unix only: linking a Rust staticlib from MSVC spells the flags and the -# archive (`moq.lib`) differently, and this recipe doesn't model that. +# Outside nextest because the staticlib link alone outlasts its hang budget. # Compile and run moq-c's C fixtures, and the C doc samples, against libmoq.a. Must run on Unix. c-tests: - #!/usr/bin/env bash - set -euo pipefail - cc="${CC:-cc}" - if ! command -v "$cc" >/dev/null; then - echo "no C compiler at '$cc'" >&2 - exit 1 - fi - - cargo build --locked -p moq-c - - # Ask cargo where it put the staticlib and the header rather than assuming - # target/debug: CARGO_TARGET_DIR and a configured build target - # (`target//debug`) both move them, and guessing wrong would link a - # stale copy or nothing. Replays the build above from cache, so it costs a - # process, not a compile. - log=$(cargo build --locked -p moq-c --message-format=json) - lib=$(jq -r 'select(.reason == "compiler-artifact") | .filenames[] | select(endswith("/libmoq.a"))' <<<"$log" | tail -1) - if [ -z "$lib" ]; then - echo "cargo reported no libmoq.a for moq-c" >&2 - exit 1 - fi - profile=$(dirname "$lib") - # rs/moq-c/build.rs writes the header into its OUT_DIR. - out_dir=$(jq -r 'select(.reason == "build-script-executed") | select(.package_id | test("/moq-c#")) | .out_dir' <<<"$log" | tail -1) - include="$out_dir/include" - if [ -z "$out_dir" ] || [ ! -f "$include/moq.h" ]; then - echo "$include/moq.h missing after 'cargo build --locked -p moq-c'" >&2 - exit 1 - fi - - # Same list nix/overlay.nix (moq-c.pc), CMakeLists.txt, and test/interop/interop.sh read: - # `framework:Foo` is a linker framework flag, anything else a plain library. - case "$(uname -s)" in - Darwin) native_libs=rs/moq-c/native-libs/apple.txt ;; - *) native_libs=rs/moq-c/native-libs/linux.txt ;; - esac - libs=() - while read -r entry; do - case "$entry" in - '' | '#'*) continue ;; - framework:*) libs+=(-framework "${entry#framework:}") ;; - *) libs+=("-l$entry") ;; - esac - done <"$native_libs" + sh/rs/c-tests.sh - out=$(mktemp -d) - trap 'rm -rf "$out"' EXIT - - # The C docs compile against this header too: each sample beside the inputs - # doc-samples.h declares, and every name the prose cites. A `moq_decode_*` - # wildcard ends in `_` and is skipped. - bash doc/lib/samples.sh c doc/lib/c/index.md >"$out/doc-samples.c" - "$cc" -fsyntax-only -Werror=implicit-function-declaration -include rs/moq-c/c-tests/doc-samples.h -I"$include" "$out/doc-samples.c" - for name in $(grep -oE '\b(moq|MOQ)_[A-Za-z0-9_]*' doc/lib/c/index.md | grep -v '_$' | sort -u); do - if ! grep -qw "$name" "$include/moq.h"; then - echo "doc/lib/c/index.md cites $name, which moq.h does not declare" >&2 - exit 1 - fi - done - - for source in rs/moq-c/c-tests/*.c; do - bin="$out/$(basename "$source" .c)" - "$cc" "$source" -I"$include" -L"$profile" -lmoq "${libs[@]}" -o "$bin" - echo "running $source" - "$bin" - done - -# The feature permutations `check` leaves out. Each is a full workspace compile -# at a feature set that shares almost no artifacts with the default one (~6min -# for the all-features clippy alone), which is why this is nightly rather than -# part of the per-PR gate. -# -# `--all-features` is the only thing that compiles moq-cli's play/capture, the -# moq-video and moq-audio device features, the Linux bindgen codecs (vaapi, -# v4l2), PipeWire, and jemalloc. `--no-default-features` is -# the only thing that compiles the `#[cfg(not(feature = ...))]` arms. -# -# Cargo unifies features across a workspace selection. Check each package alone -# to catch missing dependencies in minimal builds. The nightly sweep adds each -# feature to aws-lc-rs; tokio-features checks provider-free transports, standalone -# providers, and the intentional refusal of rustls QUIC without a provider. -# -# Both carry `--all-targets`. A `#[cfg(test)]` module leans on whatever the -# default features happened to import, so a test that only compiles by accident -# is invisible to a lib-only check. +# The feature permutations `check` leaves out, nightly. `--all-features` is the +# only thing that compiles moq-cli's play/capture, the device features, the +# Linux bindgen codecs, PipeWire, and jemalloc; `--no-default-features` the only +# thing that compiles the `#[cfg(not(feature = ...))]` arms. # Compile the workspace at the feature extremes. features: @@ -833,258 +185,120 @@ features: # Compile the media crates at supported feature boundaries and prove expensive # native/render dependencies are absent when their features are excluded. media-features: - rs/scripts/media-features.sh + sh/rs/media-features.sh -# nextest, not `cargo test`, so a wedged test is killed instead of pinning a core -# until someone notices (`.config/nextest.toml` sets the timeout). The trade is -# doctests, which nextest does not execute; `just rs doctest` covers those. -# -# Takes cargo arguments, so `just rs test -p moq-net` works. `test-changed` is -# the diff-scoped variant that `just ci 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 is what -# lets `check-test` (and so the root `just check`) compile Rust once. -# -# 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-test` is the gate (it sets -# `build.warnings=deny`), 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. +# nextest kills a wedged test (`.config/nextest.toml` sets the timeout), but +# skips doctests; `just rs doctest` covers those. clippy-driver as the workspace +# wrapper reports lint findings from the same compile, as warnings: `check-test` +# is the gate. It is part of cargo's fingerprint, and RUSTFLAGS would split the +# artifact cache, which is why neither is set any other way. # Run the test suite, reporting clippy findings from the same compile. +[positional-arguments] test *args: - RUSTC_WORKSPACE_WRAPPER="$(command -v clippy-driver || true)" cargo nextest run --locked --all-targets {{ args }} + RUSTC_WORKSPACE_WRAPPER="$(command -v clippy-driver || true)" cargo nextest run --locked --all-targets "$@" -# Exercise the Vulkan producer -> CUDA image contract, the GPU color conversion -# and resize, and NVENC encoding of the result on Linux/NVIDIA hardware. The -# driver directory is added explicitly because the Nix shell's dynamic loader -# path does not include Ubuntu's host driver directory. +# Exercise Vulkan -> CUDA -> NVENC on Linux/NVIDIA hardware. vulkan-cuda: - #!/usr/bin/env bash - set -euo pipefail - driver=$(/usr/sbin/ldconfig -p | awk '/libcuda\.so\.1/{print $NF; exit}') - if [[ -z "$driver" ]]; then - echo "libcuda.so.1 is not installed" >&2 - exit 1 - fi - driver_dir=$(dirname "$driver") - export LD_LIBRARY_PATH="$driver_dir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" - cargo nextest run --locked -p moq-video --run-ignored only -E 'test(/^frame::(vulkan|cuda)::tests::vulkan_cuda_/)' - -# 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. -# -# `--no-tests=pass` only on the scoped branch. A selection can legitimately hold -# nothing testable (moq-wasm has no host-target tests, since its crate root is -# `#![cfg(target_arch = "wasm32")]`), and nextest exits 4 on that by default. -# The unscoped branch keeps the default, where finding no tests really is wrong. - -# Like `test`, but only the crates a diff touches plus their dependents. -test-changed $FILES: - #!/usr/bin/env bash - set -euo pipefail - packages=$(just rs _select "$FILES") - case "$packages" in - "") echo "rs: no crates affected; skipping tests." ;; - ALL) just rs test --workspace {{ no_fuzz }} ;; - *) echo "rs: testing $(just rs _names "$packages")"; just rs test --no-tests=pass $packages ;; - esac - - # Mirrors `check-changed`: the capture tests are off the default feature set. - if [[ "$packages" == "ALL" ]] || just rs _wants-capture "$packages"; then - just rs capture-test - fi - - if [[ "$packages" == "ALL" ]] || just rs _wants-play "$packages"; then - just rs play - fi + sh/rs/vulkan-cuda.sh # The media tasks run against a recorder rather than a device (see -# `rs/moq-cli/src/play/fake.rs`), so this needs no speaker or display, only the -# device crates' build dependencies, which the dev shell carries. +# `rs/moq-cli/src/play/fake.rs`), so this needs no speaker or display. # Test moq-cli's `play` feature, which default features leave out. +[positional-arguments] play *args: - just rs test -p moq-cli --features play {{ args }} + just rs test -p moq-cli --features play "$@" # Compile and run the `/// ```` examples, which nextest skips. +[positional-arguments] doctest *args: - cargo test --locked --doc {{ args }} + cargo test --locked --doc "$@" + +# `--cfg loom` swaps kio's primitives for loom's, so it rebuilds the world and +# stays out of `check`. `--release` because a model check runs the body once +# per interleaving (411s -> 51s); the assertions are plain `assert!`. kio's +# models search every interleaving; moq-net's cap preemptions (see +# `tests/loom.rs`, `LOOM_MAX_PREEMPTIONS`). kio's own unit tests are +# `cfg(not(loom))`. # Permutation-test the concurrent handoffs with loom. -# -# `--cfg loom` swaps kio's Mutex/atomics for loom's instrumented ones, so it -# rebuilds the world and can't share artifacts with a normal `cargo test`, so -# it stays separate from `check`/`ci`. -# -# `--release` because a model check runs the body once per interleaving, so the -# optimizer pays for itself many times over: 411s -> 51s across the two suites. -# Our assertions are plain `assert!`, not `debug_assert!`, so nothing is -# compiled out (verified by re-running the mutation check in release). -# -# kio's models search every interleaving. moq-net's compose far more operations -# per path, so they cap preemptions (see `tests/loom.rs`) to stop the search -# growing exponentially with each lock the model layer adds. Set -# `LOOM_MAX_PREEMPTIONS` to search deeper. -# -# kio's own unit tests are `cfg(not(loom))`: they'd construct loom primitives -# outside `loom::model`, which panics. +[positional-arguments] loom *args: - RUSTFLAGS="--cfg loom" cargo test --locked --release -p kio --lib loom:: {{ args }} - RUSTFLAGS="--cfg loom" cargo test --locked --release -p moq-net --test loom {{ args }} - -# Coverage-guided fuzzing of the moq-net wire codecs (libFuzzer, via cargo-fuzz). -# -# The one recipe that steps off the pinned toolchain: libFuzzer needs `-Zsanitizer`, -# which is nightly-only, so this stays out of `check` and `test` the same way `loom` -# does. What CI gets instead is the replay: the target bodies live in moq-net's hidden -# `fuzz` module, and its own tests run the generated corpus plus everything committed -# under `fuzz/regressions/` on stable. A crash found here becomes a regression test -# nobody has to install cargo-fuzz to run. -# -# Seeds are regenerated first so the corpus follows the dispatch rather than a stale -# run, and libFuzzer writes what it discovers to the FIRST corpus directory, which is -# why the generated seeds are passed second and stay read-only. -# -# TARGET is lite, announce, ietf, varint, path, or pattern. Arguments pass through, so -# `just rs fuzz lite -- -max_total_time=300` bounds a run. See rs/moq-net/fuzz/README.md. -fuzz target *args: - #!/usr/bin/env bash - set -euo pipefail + RUSTFLAGS="--cfg loom" cargo test --locked --release -p kio --lib loom:: "$@" + RUSTFLAGS="--cfg loom" cargo test --locked --release -p moq-net --test loom "$@" - if ! command -v cargo-fuzz > /dev/null 2>&1; then - echo "rs: cargo-fuzz is missing: cargo install --locked cargo-fuzz" >&2 - exit 1 - fi +# Needs nightly and cargo-fuzz; CI replays the corpus on stable through +# moq-net's own tests instead. See rs/moq-net/fuzz/README.md. - if ! rustup run nightly rustc --version > /dev/null 2>&1; then - echo "rs: the nightly toolchain is missing: rustup toolchain install nightly" >&2 - exit 1 - fi - - cargo run --locked -q -p moq-net --features fuzz --example fuzz-seeds -- rs/moq-net/fuzz/seeds - mkdir -p rs/moq-net/fuzz/corpus/{{ target }} - - # Nightly by PATH rather than by `cargo +nightly`: the dev shell puts a - # Nix-provided cargo ahead of the rustup shim, so the `+` form is not - # understood, and cargo-fuzz shells out to a bare `cargo` and `rustc` anyway. - # Both have to be the nightly ones or the sanitizer flags are rejected. - export PATH="$(rustup run nightly rustc --print sysroot)/bin:$PATH" - - cargo fuzz run --fuzz-dir rs/moq-net/fuzz {{ target }} \ - rs/moq-net/fuzz/corpus/{{ target }} rs/moq-net/fuzz/seeds/{{ target }} {{ args }} +# Fuzz the moq-net wire codecs: `just rs fuzz lite -- -max_total_time=300`. +[positional-arguments] +fuzz target *args: + sh/rs/fuzz.sh "$@" +# Build the default workspace members. build: cargo build --locked -# Run a moq-bench preset against a relay, e.g. `just rs bench chat https://relay.example.com`. -# Extra args pass through, so `--connections 500 --output stats.jsonl` work as-is. -bench preset url *args: - cargo run --release -p moq-bench -- --file 'rs/moq-bench/config/{{ preset }}.toml' --connect '{{ url }}' {{ args }} - -# Measure the Linux Tokio/epoll UDP syscall path. Extra args pass to Criterion, -# e.g. `just rs bench-udp-tokio --quick`. -bench-udp-tokio *args: - cargo bench -p moq-uring --bench udp_tokio -- {{ args }} - -# Measure the Linux io_uring UDP completion path with multishot recvmsg. -bench-udp-uring *args: - cargo bench -p moq-uring --bench udp_uring -- {{ args }} - # Run the comparable epoll and io_uring UDP matrices. +[positional-arguments] bench-udp *args: - cargo bench -p moq-uring --bench udp_tokio -- {{ args }} - cargo bench -p moq-uring --bench udp_uring -- {{ args }} + cargo bench -p moq-uring --bench udp_tokio -- "$@" + cargo bench -p moq-uring --bench udp_uring -- "$@" # Measure a noq echo through the io_uring worker, ablating receive # batching, GRO, and GSO one at a time. Linux 6.12+ (skips loudly otherwise). +[positional-arguments] bench-echo *args: - cargo bench -p moq-uring --bench echo_noq -- {{ args }} + cargo bench -p moq-uring --bench echo_noq -- "$@" # Measure a full moq-lite session (publisher to subscriber) through the # io_uring worker, same ablations and per-iteration unit as bench-echo. # Linux 6.12+ (skips loudly otherwise). +[positional-arguments] bench-session *args: - cargo bench -p moq-uring --bench session_lite -- {{ args }} - -# Sample a process's CPU/memory/context switches on this host (run it where the -# relay runs; it only reads /proc). E.g. `just rs bench-host --name moq-relay`. -bench-host *args: - cargo run --release -p moq-bench --bin moq-bench-host -- {{ args }} - -# Remove the Rust target directory. -clean: - cargo clean - -# Check semver compatibility against crates.io (default-members only). -semver: - cargo semver-checks check-release - -# Update versions and changelogs via release-plz. -bump: - release-plz update + cargo bench -p moq-uring --bench session_lite -- "$@" # Create release PRs and publish crates via release-plz. release: release-plz release-pr --git-token "$GITHUB_TOKEN" release-plz release --git-token "$GITHUB_TOKEN" -update: - cargo update - cargo upgrade --incompatible - -# Build a .deb or .rpm for one of the Rust binaries locally. nfpm comes -# from the flake's dev shell (`nix develop`). For .rpm produced this way, -# the linkage matches the host's glibc; CI uses an AlmaLinux 9 container -# to produce broadly compatible artifacts instead. -# -# Examples: -# just rs package moq-relay deb - -# just rs package moq-cli rpm +# Build a .deb or .rpm locally: `just rs package moq-relay deb`. package crate packager: - #!/usr/bin/env bash - set -euo pipefail - case "{{ crate }}" in - moq-relay) bin=moq-relay ;; - moq-cli) bin=moq ;; - *) echo "Unknown crate: {{ crate }} (use moq-relay or moq-cli)" >&2; exit 1 ;; - esac - case "{{ packager }}" in - deb) - if command -v dpkg >/dev/null 2>&1; then - arch=$(dpkg --print-architecture) - else - case "$(uname -m)" in - x86_64) arch=amd64 ;; - aarch64|arm64) arch=arm64 ;; - *) echo "Cannot infer deb arch from host $(uname -m)" >&2; exit 1 ;; - esac - fi - ;; - rpm) arch=$(uname -m) ;; - *) echo "Unknown packager: {{ packager }} (use deb or rpm)" >&2; exit 1 ;; - esac - version=$(grep -m1 '^version' rs/{{ crate }}/Cargo.toml | sed 's/.*"\(.*\)".*/\1/') - cargo build --locked --release -p {{ crate }} - mkdir -p dist - VERSION="$version" ARCH="$arch" BINARY_PATH="target/release/$bin" \ - rs/scripts/package-nfpm.sh packaging/{{ crate }}/nfpm.yaml {{ packager }} dist/ - if [[ "{{ packager }}" == deb && -f "packaging/{{ crate }}/transition.yaml" ]]; then - VERSION="$version" ARCH="$arch" \ - rs/scripts/package-nfpm.sh packaging/{{ crate }}/transition.yaml deb dist/ - fi - ls -1 dist/ + sh/rs/package.sh {{ crate }} {{ packager }} + +# Build and package a workspace binary as a release tarball. +[positional-arguments] +package-binary *args: + sh/rs/package-binary.sh "$@" + +# Build and package a workspace binary as a Windows .zip. +[positional-arguments] +package-windows *args: + sh/rs/package-windows.sh "$@" + +# Render an nfpm config from the environment and build a .deb or .rpm: CONFIG PACKAGER OUTPUT. +[positional-arguments] +package-nfpm *args: + sh/rs/package-nfpm.sh "$@" + +# Build and package the moq-ffi native libraries, or only its bindings. +[positional-arguments] +package-ffi *args: + rs/moq-ffi/build.sh "$@" + +# Build and package moq-c. +[positional-arguments] +package-moq-c *args: + rs/moq-c/build.sh "$@" + +# Build and package the moq-gst GStreamer plugin. +[positional-arguments] +package-gst *args: + rs/moq-gst/build.sh "$@" + +# Load a packaged moq-gst plugin into the host's GStreamer and find its elements. +[positional-arguments] +gst-smoke *args: + rs/moq-gst/smoke.sh "$@" diff --git a/rs/kio/CHANGELOG.md b/rs/kio/CHANGELOG.md index 7ddc2611bba..bb0877821c0 100644 --- a/rs/kio/CHANGELOG.md +++ b/rs/kio/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.2](https://github.com/moq-dev/moq/compare/kio-v0.6.1...kio-v0.6.2) - 2026-09-30 + +### Fixed + +- *(kio)* keep a lost waiter's recorded lists idempotent ([#4422](https://github.com/moq-dev/moq/pull/4422)) +- *(net)* keep an aborted track's finished groups, expire ended tracks ([#4378](https://github.com/moq-dev/moq/pull/4378)) + ## [0.6.1](https://github.com/moq-dev/moq/compare/kio-v0.6.0...kio-v0.6.1) - 2026-09-26 ### Fixed diff --git a/rs/kio/Cargo.toml b/rs/kio/Cargo.toml index 9ad60223b50..0bee6842597 100644 --- a/rs/kio/Cargo.toml +++ b/rs/kio/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.6.1" +version = "0.6.2" edition = "2024" rust-version.workspace = true diff --git a/rs/libmoq/Cargo.toml b/rs/libmoq/Cargo.toml index 8e88f964483..41e248732bb 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.6.8" +version = "0.6.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-archive/CHANGELOG.md b/rs/moq-archive/CHANGELOG.md index 45bbe508b01..882e455a773 100644 --- a/rs/moq-archive/CHANGELOG.md +++ b/rs/moq-archive/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.9](https://github.com/moq-dev/moq/compare/moq-archive-v0.0.8...moq-archive-v0.0.9) - 2026-09-30 + +### Other + +- updated the following local packages: moq-net + ## [0.0.8](https://github.com/moq-dev/moq/compare/moq-archive-v0.0.7...moq-archive-v0.0.8) - 2026-09-27 ### Other diff --git a/rs/moq-archive/Cargo.toml b/rs/moq-archive/Cargo.toml index 6aaee0878b5..67c7a6431fe 100644 --- a/rs/moq-archive/Cargo.toml +++ b/rs/moq-archive/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.8" +version = "0.0.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-audio/CHANGELOG.md b/rs/moq-audio/CHANGELOG.md index 6d63a2edf1f..6171b073ea2 100644 --- a/rs/moq-audio/CHANGELOG.md +++ b/rs/moq-audio/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.8](https://github.com/moq-dev/moq/compare/moq-audio-v0.1.7...moq-audio-v0.1.8) - 2026-09-30 + +### Fixed + +- *(audio)* conceal one Opus packet's length for a lost packet, not 120 ms ([#4442](https://github.com/moq-dev/moq/pull/4442)) + +### Other + +- compile the Windows, macOS, and OBS plugin code on every PR ([#4370](https://github.com/moq-dev/moq/pull/4370)) + ## [0.1.7](https://github.com/moq-dev/moq/compare/moq-audio-v0.1.6...moq-audio-v0.1.7) - 2026-09-27 ### Other diff --git a/rs/moq-audio/Cargo.toml b/rs/moq-audio/Cargo.toml index b0bdca9aaf8..5fe9bc27161 100644 --- a/rs/moq-audio/Cargo.toml +++ b/rs/moq-audio/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.7" +version = "0.1.8" edition = "2024" rust-version.workspace = true @@ -27,7 +27,7 @@ default = ["aac"] # AAC-LC decode via symphonia. Pure Rust, so it costs no toolchain: the trade # this crate already refused for Opus. Only a subscriber to an ingest-sourced # broadcast needs it (RTMP, SRT/TS, fmp4, and gstreamer all publish AAC, while -# everything this crate encodes is Opus or PCM), so a publish-only build can +# this crate encodes in software is Opus or PCM), so a publish-only build can # drop it and the two crates it pulls. aac = ["dep:symphonia-codec-aac", "dep:symphonia-core"] # Device capture. Microphones go through cpal (pure-Rust: CoreAudio / WASAPI / diff --git a/rs/moq-audio/src/aac.rs b/rs/moq-audio/src/aac.rs index 7c8b9482334..52fb66e3dd3 100644 --- a/rs/moq-audio/src/aac.rs +++ b/rs/moq-audio/src/aac.rs @@ -1,7 +1,7 @@ //! AAC constraints, the sibling of the `opus` and `pcm` modules. //! -//! Only the decode side exists: there is no Rust AAC encoder, so this crate -//! publishes Opus or PCM and reads AAC that a gateway produced. +//! The decode side. There is no Rust AAC encoder, so `encode` produces AAC only +//! through a platform backend and otherwise reads AAC that a gateway produced. use crate::Error; diff --git a/rs/moq-audio/src/aec.rs b/rs/moq-audio/src/aec.rs index 607d0111cae..da24dda60a1 100644 --- a/rs/moq-audio/src/aec.rs +++ b/rs/moq-audio/src/aec.rs @@ -40,7 +40,7 @@ use sonora::config::{EchoCanceller, GainController2, NoiseSuppression, NoiseSupp use sonora::{AudioProcessing, StreamConfig}; use crate::Error; -use crate::playback::{self, BUS_CHANNELS}; +use crate::playback::{self, REFERENCE_CHANNELS}; /// Sample rate the echo reference is resampled to on its way out of the mixer. /// @@ -187,7 +187,7 @@ impl Control { "echo cancellation needs a microphone between 8 and 384 kHz (got {sample_rate})" ))); } - if channels == 0 || channels > BUS_CHANNELS as u32 { + if channels == 0 || channels > REFERENCE_CHANNELS as u32 { return Err(Error::Unsupported(format!( "echo cancellation accepts a mono or stereo microphone (got {channels} channels)" ))); @@ -381,9 +381,9 @@ impl State { self.pending = Vec::with_capacity(headroom); self.processed = Vec::with_capacity(headroom); - self.reference_frame = vec![0.0; REFERENCE_FRAME * BUS_CHANNELS]; - self.render_in = vec![0.0; REFERENCE_FRAME * BUS_CHANNELS]; - self.render_out = vec![0.0; REFERENCE_FRAME * BUS_CHANNELS]; + self.reference_frame = vec![0.0; REFERENCE_FRAME * REFERENCE_CHANNELS]; + self.render_in = vec![0.0; REFERENCE_FRAME * REFERENCE_CHANNELS]; + self.render_out = vec![0.0; REFERENCE_FRAME * REFERENCE_CHANNELS]; self.capture_in = vec![0.0; frame * channels]; self.capture_out = vec![0.0; frame * channels]; @@ -453,7 +453,7 @@ impl State { if let Some(reference) = reference { while reference.available_frames() >= REFERENCE_FRAME { reference.read_interleaved(reference_frame, false); - deinterleave(reference_frame, render_in, BUS_CHANNELS); + deinterleave(reference_frame, render_in, REFERENCE_CHANNELS); let _ = process_render(processor, render_in, render_out); } } @@ -484,7 +484,7 @@ impl State { /// The format the mixer's reference tap arrives in. fn reference_config() -> StreamConfig { - StreamConfig::new(REFERENCE_RATE, BUS_CHANNELS as u16) + StreamConfig::new(REFERENCE_RATE, REFERENCE_CHANNELS as u16) } /// Feed one reference frame to the echo model. @@ -602,7 +602,7 @@ impl Reference { /// canceller reads it back at [`REFERENCE_RATE`]. fn channel(rate: u32) -> (ResamplingProd, ResamplingCons) { resampling_channel::( - BUS_CHANNELS, + REFERENCE_CHANNELS, rate, REFERENCE_RATE, true, @@ -652,7 +652,7 @@ mod tests { /// Push one 10 ms stereo frame of `value` into the tap. fn play(prod: &mut ResamplingProd, value: f32) { - prod.push_interleaved(&vec![value; REFERENCE_FRAME * BUS_CHANNELS]); + prod.push_interleaved(&vec![value; REFERENCE_FRAME * REFERENCE_CHANNELS]); } #[test] @@ -976,10 +976,10 @@ mod tests { fn round(&mut self) -> (f64, f64) { let played: Vec = (0..self.frame).map(|_| self.noise.next()).collect(); - let mut reference = vec![0.0f32; self.frame * BUS_CHANNELS]; + let mut reference = vec![0.0f32; self.frame * REFERENCE_CHANNELS]; for (i, sample) in played.iter().enumerate() { - reference[i * BUS_CHANNELS] = *sample; - reference[i * BUS_CHANNELS + 1] = *sample; + reference[i * REFERENCE_CHANNELS] = *sample; + reference[i * REFERENCE_CHANNELS + 1] = *sample; } self.prod.push_interleaved(&reference); @@ -1112,13 +1112,13 @@ mod tests { let mut tone = Vec::with_capacity(frames * 2 * 4); for frame in 0..frames { let value = (std::f32::consts::TAU * 440.0 * frame as f32 / 48_000.0).sin() * 0.5; - for _ in 0..BUS_CHANNELS { + for _ in 0..REFERENCE_CHANNELS { tone.extend_from_slice(&value.to_le_bytes()); } } let mut energy = 0.0f64; - let mut buf = vec![0.0f32; REFERENCE_FRAME * BUS_CHANNELS]; + let mut buf = vec![0.0f32; REFERENCE_FRAME * REFERENCE_CHANNELS]; for _ in 0..20 { let _ = sink.write(&tone).expect("write"); diff --git a/rs/moq-audio/src/decode/backend/libopus.rs b/rs/moq-audio/src/decode/backend/libopus.rs new file mode 100644 index 00000000000..07b03607b05 --- /dev/null +++ b/rs/moq-audio/src/decode/backend/libopus.rs @@ -0,0 +1,440 @@ +//! Opus through libopus, the software decoder for every host. +//! +//! Every stream goes through the multistream decoder, which is also how a +//! family 0 (mono/stereo) stream decodes: one stream, coupled when stereo. + +use unsafe_libopus::{ + OPUS_OK, OPUS_RESET_STATE, OPUS_SET_GAIN_REQUEST, OpusMSDecoder, opus_multistream_decode_float, + opus_multistream_decoder_create, opus_multistream_decoder_ctl_impl, opus_multistream_decoder_destroy, varargs, +}; + +use super::Backend; +use crate::decode::Decoded; +use crate::{Error, Layout, opus}; + +pub(super) const NAME: &str = "libopus"; + +/// Opus packets cap at 120 ms (RFC 6716 §2.1.4). +const MAX_FRAME_MS: usize = 120; + +/// The family 0 streams: one stream, coupled when stereo, decoded in order. +const MONO: &[u8] = &[0]; +const STEREO: &[u8] = &[0, 1]; + +pub(super) struct Libopus { + inner: *mut OpusMSDecoder, + layout: Layout, + /// For each canonical channel, the Vorbis-order channel it comes from, when they differ. + reorder: Option<&'static [usize]>, + /// Opus streams in one packet. Family 0 is one; the rest come from the mapping. + streams: u8, + pre_skip: usize, + max_frame_size: usize, + /// Frames per channel in the last packet that decoded, which is what a lost + /// packet most likely carried. `None` until one has. + last_frame_size: Option, + in_dtx: bool, +} + +// SAFETY: the decoder is owned exclusively and libopus keeps no thread-local state. +unsafe impl Send for Libopus {} + +impl Libopus { + /// Decodes at 48 kHz with the pre-skip and output gain the OpusHead + /// `description` declares; its input rate is metadata. A missing description + /// falls back to the catalog's channel count, which must then be mono or + /// stereo. A description that does not parse is refused: guessing family 0 + /// would decode those packets with the wrong stream layout. + /// + /// Channel mapping family 1 decodes up to 7.1 in the canonical [`Layout`] + /// order; every other family is refused, since none declares speakers. + pub(super) fn open(catalog: &hang::catalog::AudioConfig) -> Result, Error> { + let head = opus::head(catalog)?; + let channel_count = head.channel_count; + + let (streams, coupled, table, layout, reorder) = match &head.mapping { + None => { + let table = match opus::validate_channels(channel_count)? { + 1 => MONO, + _ => STEREO, + }; + let layout = Layout::from_channels(channel_count)?; + (1, table.len() as i32 - 1, table, layout, None) + } + Some(mapping) if mapping.family() == 1 => { + let (layout, reorder) = vorbis(channel_count)?; + let (streams, coupled) = (mapping.streams() as i32, mapping.coupled() as i32); + (streams, coupled, mapping.table(), layout, reorder) + } + Some(mapping) => { + return Err(Error::Unsupported(format!( + "opus channel mapping family {} declares no speaker positions", + mapping.family() + ))); + } + }; + + let mut err = 0i32; + // SAFETY: `table` holds one entry per output channel, the count we pass, + // and the out-pointer is valid; inner is checked for null below. + let inner = unsafe { + opus_multistream_decoder_create( + opus::DECODE_RATE as i32, + table.len() as i32, + streams, + coupled, + table.as_ptr(), + &mut err, + ) + }; + if err != OPUS_OK || inner.is_null() { + return Err(opus::error(err, "opus_multistream_decoder_create")); + } + + // Owned before the gain ctl so a failure there still destroys the decoder. + let decoder = Self { + inner, + layout, + reorder, + streams: streams as u8, + pre_skip: head.pre_skip as usize, + max_frame_size: (opus::DECODE_RATE as usize * MAX_FRAME_MS) / 1000, + last_frame_size: None, + in_dtx: false, + }; + + // Same Q7.8 dB units as OpusHead, and it survives OPUS_RESET_STATE. + // SAFETY: `inner` owns a live decoder and OPUS_SET_GAIN takes one i32. + let rc = unsafe { + opus_multistream_decoder_ctl_impl(decoder.inner, OPUS_SET_GAIN_REQUEST, varargs![head.output_gain as i32]) + }; + if rc != OPUS_OK { + return Err(opus::error(rc, "OPUS_SET_GAIN")); + } + + Ok(Box::new(decoder)) + } +} + +/// The layout a family 1 stream of `channels` declares (RFC 7845 §5.1.1.2), and +/// how to reorder its Vorbis channel order into that layout's canonical one. +/// +/// Vorbis puts the center between the fronts and the LFE last. Its "rear" +/// pair in 5.0 and 5.1 is the surround pair, which is side in the canonical +/// layouts, while 7.1 has distinct side and rear pairs. +fn vorbis(channels: u32) -> Result<(Layout, Option<&'static [usize]>), Error> { + Ok(match channels { + 1 => (Layout::Mono, None), + 2 => (Layout::Stereo, None), + // L, C, R. + 3 => (Layout::ThreePointZero, Some(&[0, 2, 1])), + // FL, FR, RL, RR. + 4 => (Layout::Quad, None), + // FL, C, FR, RL, RR. + 5 => (Layout::FivePointZero, Some(&[0, 2, 1, 3, 4])), + // FL, C, FR, RL, RR, LFE. + 6 => (Layout::FivePointOne, Some(&[0, 2, 1, 5, 3, 4])), + // FL, C, FR, SL, SR, RC, LFE. + 7 => (Layout::SixPointOne, Some(&[0, 2, 1, 6, 5, 3, 4])), + // FL, C, FR, SL, SR, RL, RR, LFE. + 8 => (Layout::SevenPointOne, Some(&[0, 2, 1, 7, 5, 6, 3, 4])), + other => { + return Err(Error::Unsupported(format!( + "opus channel mapping family 1 has no {other}-channel layout" + ))); + } + }) +} + +impl Backend for Libopus { + /// An empty packet conceals as much audio as the last packet that decoded + /// held, and is refused before any has. Loss during DTX remains classified + /// as DTX, while loss during active audio remains active. + fn decode(&mut self, packet: &[u8]) -> Result { + let channels = self.layout.channels() as usize; + // libopus conceals exactly `frame_size` samples for a lost packet, and + // the decoder can't know how long it was, so assume the last one's length. + // A real packet decodes into the most it can hold. + let frame_size = if packet.is_empty() { + self.last_frame_size.ok_or_else(|| { + Error::Decode("opus packet lost before any packet decoded, so no length to conceal".into()) + })? + } else { + self.max_frame_size + }; + let mut out = vec![0.0f32; frame_size * channels]; + // SAFETY: `inner` owns a live OpusMSDecoder; packet/out slices are bounded by + // the lengths we pass. + let samples = unsafe { + opus_multistream_decode_float( + self.inner, + packet.as_ptr(), + packet.len() as i32, + out.as_mut_ptr(), + frame_size as i32, + 0, + ) + }; + if samples < 0 { + return Err(opus::decode_error(samples)); + } + if !packet.is_empty() { + self.last_frame_size = Some(samples as usize); + } + out.truncate(samples as usize * channels); + + if let Some(order) = self.reorder { + let mut vorbis = [0.0f32; 8]; + for frame in out.chunks_exact_mut(channels) { + vorbis[..channels].copy_from_slice(frame); + for (sample, &from) in frame.iter_mut().zip(order) { + *sample = vorbis[from]; + } + } + } + + let activity = opus::multistream_activity(packet, self.streams, self.in_dtx); + self.in_dtx = activity.is_dtx(); + Ok(Decoded { samples: out, activity }) + } + + fn reset(&mut self) -> Result<(), Error> { + // SAFETY: `inner` owns a live decoder and OPUS_RESET_STATE takes no arguments. + let rc = unsafe { opus_multistream_decoder_ctl_impl(self.inner, OPUS_RESET_STATE, varargs![]) }; + if rc != OPUS_OK { + return Err(opus::error(rc, "OPUS_RESET_STATE")); + } + self.in_dtx = false; + Ok(()) + } + + fn sample_rate(&self) -> u32 { + opus::DECODE_RATE + } + + fn layout(&self) -> Layout { + self.layout + } + + fn delay(&self) -> usize { + self.pre_skip + } + + fn name(&self) -> &str { + NAME + } +} + +impl Drop for Libopus { + fn drop(&mut self) { + // SAFETY: `inner` is a live OpusMSDecoder that nothing else aliases. + unsafe { opus_multistream_decoder_destroy(self.inner) }; + } +} + +#[cfg(test)] +mod tests { + use unsafe_libopus::{ + OPUS_APPLICATION_AUDIO, opus_multistream_encode_float, opus_multistream_encoder_destroy, + opus_multistream_surround_encoder_create, + }; + + use crate::Error; + use crate::decode::{Config, Decoder}; + use crate::layout::Speaker::{self, *}; + + /// Speakers in Vorbis channel order for each family 1 channel count (RFC 7845 §5.1.1.2). + const VORBIS: [&[Speaker]; 8] = [ + &[FrontCenter], + &[FrontLeft, FrontRight], + &[FrontLeft, FrontCenter, FrontRight], + &[FrontLeft, FrontRight, BackLeft, BackRight], + &[FrontLeft, FrontCenter, FrontRight, SideLeft, SideRight], + &[FrontLeft, FrontCenter, FrontRight, SideLeft, SideRight, Lfe], + &[FrontLeft, FrontCenter, FrontRight, SideLeft, SideRight, BackCenter, Lfe], + &[ + FrontLeft, + FrontCenter, + FrontRight, + SideLeft, + SideRight, + BackLeft, + BackRight, + Lfe, + ], + ]; + + const RATE: usize = 48_000; + const FRAME: usize = 960; + const PACKETS: usize = 15; + + /// A distinct tone per speaker, low for the LFE, which libopus band-limits. + fn tone(speaker: Speaker) -> f32 { + match speaker { + Lfe => 80.0, + other => 400.0 + 300.0 * other as u8 as f32, + } + } + + /// Encode `channels` of Vorbis-ordered tones as a family 1 stream, returning + /// its OpusHead and packets. + fn surround(channels: usize) -> (bytes::Bytes, Vec>) { + let speakers = VORBIS[channels - 1]; + let (mut streams, mut coupled, mut mapping) = (0i32, 0i32, [0u8; 8]); + let mut err = 0i32; + // SAFETY: every out-pointer is valid and `mapping` holds `channels` entries. + let encoder = unsafe { + opus_multistream_surround_encoder_create( + RATE as i32, + channels as i32, + 1, + &mut streams, + &mut coupled, + mapping.as_mut_ptr(), + OPUS_APPLICATION_AUDIO, + &mut err, + ) + }; + assert!(err == 0 && !encoder.is_null(), "encoder create failed: {err}"); + + let packets = (0..PACKETS) + .map(|packet| { + let mut pcm = Vec::with_capacity(FRAME * channels); + for i in packet * FRAME..(packet + 1) * FRAME { + for &speaker in speakers { + let phase = std::f32::consts::TAU * tone(speaker) * i as f32 / RATE as f32; + pcm.push(phase.sin() * 0.5); + } + } + let mut out = vec![0u8; 4000]; + // SAFETY: `encoder` is live, `pcm` holds FRAME frames, and `out` is as long as we say. + let len = unsafe { + opus_multistream_encode_float(encoder, pcm.as_ptr(), FRAME as i32, out.as_mut_ptr(), 4000) + }; + assert!(len > 0, "encode failed: {len}"); + out.truncate(len as usize); + out + }) + .collect(); + // SAFETY: `encoder` is live and not used again. + unsafe { opus_multistream_encoder_destroy(encoder) }; + + let mut head = moq_mux::codec::opus::Config::new(RATE as u32, 2) + .encode() + .unwrap() + .to_vec(); + head[9] = channels as u8; + head[18] = 1; + head.extend_from_slice(&[streams as u8, coupled as u8]); + head.extend_from_slice(&mapping[..channels]); + (head.into(), packets) + } + + fn catalog(head: bytes::Bytes, channels: u32) -> hang::catalog::AudioConfig { + let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, channels); + catalog.description = Some(head); + catalog + } + + /// Energy of `samples` at `freq`, by the Goertzel recurrence. + fn power(samples: &[f32], freq: f32) -> f32 { + let coeff = 2.0 * (std::f32::consts::TAU * freq / RATE as f32).cos(); + let (mut s1, mut s2) = (0.0f32, 0.0f32); + for &x in samples { + let s = x + coeff * s1 - s2; + s2 = s1; + s1 = s; + } + s1 * s1 + s2 * s2 - coeff * s1 * s2 + } + + /// Every family 1 layout decodes with each canonical channel carrying its + /// own speaker's tone, which pins the Vorbis reorder independently of it. + #[test] + fn family_one_decodes_in_canonical_order() { + for channels in 1..=8 { + let (head, packets) = surround(channels); + let mut decoder = Decoder::new(&catalog(head, channels as u32), &Config::default()).unwrap(); + let layout = decoder.layout(); + // The layout has exactly the Vorbis speakers, which canonical order sorts. + let mut speakers = VORBIS[channels - 1].to_vec(); + speakers.sort_by_key(|&speaker| speaker as u8); + assert_eq!(layout.speakers().unwrap(), speakers, "{channels} channels"); + + let mut pcm = Vec::new(); + for packet in &packets { + pcm.extend(decoder.decode(packet).unwrap().samples); + } + // Skip the encoder's warmup. + let pcm = &pcm[pcm.len() / 2..]; + + let tones: Vec = VORBIS[channels - 1].iter().copied().map(tone).collect(); + for (index, &speaker) in layout.speakers().unwrap().iter().enumerate() { + let channel: Vec = pcm.iter().skip(index).step_by(channels).copied().collect(); + let loudest = tones + .iter() + .copied() + .max_by(|a, b| power(&channel, *a).total_cmp(&power(&channel, *b))) + .unwrap(); + assert_eq!(loudest, tone(speaker), "{channels} channels, {speaker:?} at {index}"); + } + } + } + + /// An all-DTX surround packet is one empty Opus packet per stream. Read as a + /// single stream, the later subpackets look like payload and the span is lost. + #[test] + fn surround_silence_is_dtx() { + let (head, packets) = surround(6); + let mut decoder = Decoder::new(&catalog(head.clone(), 6), &Config::default()).unwrap(); + let mid = decoder.decode(&packets[PACKETS / 2]).unwrap(); + assert!(mid.activity.is_active(), "a coded surround frame must stay active"); + + // Two coupled streams, then two mono, each a 20 ms empty frame. + let dtx = [0xfc, 0x00, 0xfc, 0x00, 0xf8, 0x00, 0xf8]; + let mut decoder = Decoder::new(&catalog(head, 6), &Config::default()).unwrap(); + let decoded = decoder.decode(&dtx).expect("empty multistream packet"); + assert!(decoded.activity.is_dtx(), "all-DTX surround packet read as active"); + assert_eq!(decoded.samples.len() % 6, 0); + } + + /// A description that is present but truncated used to be dropped, and a + /// stereo catalog then opened a family 0 decoder for a family 1 or 255 head. + #[test] + fn malformed_description_is_refused() { + for family in [1u8, 255] { + let mut head = moq_mux::codec::opus::Config::new(48_000, 2).encode().unwrap().to_vec(); + head[18] = family; + let err = Decoder::new(&catalog(head.into(), 2), &Config::default()) + .err() + .expect("refused"); + assert!( + matches!(&err, Error::Unsupported(message) if message.contains("opus description")), + "family {family}: {err}" + ); + } + + let plain = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + assert!(Decoder::new(&plain, &Config::default()).is_ok()); + } + + /// Families other than 0 and 1 carry no speaker positions, so there is + /// nothing to put in a layout: refused, not passed through as discrete. + #[test] + fn other_families_are_refused() { + for (family, channels, table) in [(255u8, 2u8, &[2, 0, 0, 1][..]), (2, 4, &[4, 0, 0, 1, 2, 3])] { + let mut head = moq_mux::codec::opus::Config::new(48_000, 2).encode().unwrap().to_vec(); + head[9] = channels; + head[18] = family; + head.extend_from_slice(table); + + let err = Decoder::new(&catalog(head.into(), channels.into()), &Config::default()) + .err() + .expect("refused"); + assert!( + matches!(&err, Error::Unsupported(message) if message.contains("no speaker positions")), + "family {family}: {err}" + ); + } + } +} diff --git a/rs/moq-audio/src/decode/backend/mod.rs b/rs/moq-audio/src/decode/backend/mod.rs new file mode 100644 index 00000000000..45d76b3e6f2 --- /dev/null +++ b/rs/moq-audio/src/decode/backend/mod.rs @@ -0,0 +1,289 @@ +//! Pluggable audio decoder backends. +//! +//! The audio mirror of `moq-video`'s decode backends. [`Backend`] is the seam +//! between the codec and the [`Decoder`](super::Decoder) front end, which owns +//! what every codec shares: trimming the startup delay a backend reports. +//! +//! [`open`] tries the platform decoders before the software ones, skipping any +//! that does not advertise the catalog codec, and refuses when none opens the +//! track. [`Kind::Named`] names the codec, not a backend, so which backend +//! decodes it stays the library's choice. The software tier is libopus for Opus, a passthrough for PCM, and +//! symphonia for AAC-LC mono and stereo (behind the `aac` feature). No platform +//! decoder is wired in yet. + +use hang::catalog::{AudioCodec, AudioConfig}; + +use super::Decoded; +use super::decoder::{Config, Kind}; +use crate::{Error, Layout}; + +mod libopus; +mod pcm; +#[cfg(feature = "aac")] +mod symphonia; + +/// An opened decoder: packets in, interleaved `f32` PCM out. +/// +/// Unwind safe because the published `Decoder` that boxes it is. +pub(crate) trait Backend: Send + std::panic::UnwindSafe + std::panic::RefUnwindSafe { + /// Decode one packet into interleaved samples at [`sample_rate`](Self::sample_rate) + /// and [`layout`](Self::layout), untrimmed. + fn decode(&mut self, packet: &[u8]) -> Result; + + /// Drop codec history after a discontinuity, so the next packet does not + /// predict from audio that is no longer adjacent. + fn reset(&mut self) -> Result<(), Error>; + + /// The rate this backend decodes to, which may differ from the catalog's. + fn sample_rate(&self) -> u32; + + /// The layout this backend decodes to, which may differ from the catalog's. + fn layout(&self) -> Layout; + + /// Frames at the start of the stream that are codec priming, not media. + fn delay(&self) -> usize { + 0 + } + + /// The stable lowercase name of this backend, as [`Decoder::name`](super::Decoder::name) + /// reports it. Callers never select by it. + fn name(&self) -> &str; +} + +type Open = fn(&AudioConfig) -> Result, Error>; + +/// A backend constructor: its name, the catalog codecs it advertises, and an opener. +struct Candidate { + name: &'static str, + supports: fn(&AudioCodec) -> bool, + open: Open, +} + +/// Operating-system decoders, in priority order. +const PLATFORM: &[Candidate] = &[]; + +const SOFTWARE: &[Candidate] = &[ + Candidate { + name: libopus::NAME, + supports: |codec| matches!(codec, AudioCodec::Opus), + open: libopus::Libopus::open, + }, + Candidate { + name: pcm::NAME, + supports: |codec| matches!(codec, AudioCodec::Pcm), + open: pcm::Pcm::open, + }, + // Claims every AAC profile and refuses at open what it can't decode: the + // profile that matters is the description's, which the catalog string can + // contradict. + #[cfg(feature = "aac")] + Candidate { + name: symphonia::NAME, + supports: |codec| matches!(codec, AudioCodec::AAC(_)), + open: symphonia::Symphonia::open, + }, +]; + +/// The name [`Kind::Named`] uses for a catalog codec, `None` for one this crate has no name for. +fn codec_name(codec: &AudioCodec) -> Option<&'static str> { + match codec { + AudioCodec::Opus => Some("opus"), + AudioCodec::Pcm => Some("pcm"), + AudioCodec::AAC(_) => Some("aac"), + _ => None, + } +} + +/// Open the first backend that advertises the catalog codec and accepts the track. +pub(crate) fn open(catalog: &AudioConfig, config: &Config) -> Result, Error> { + if let Kind::Named(requested) = &config.kind + && codec_name(&catalog.codec) != Some(requested) + { + return Err(Error::Unsupported(format!( + "audio decoder {requested:?} is unavailable for {}", + catalog.codec + ))); + } + + select(catalog, candidates(&config.kind, PLATFORM, SOFTWARE)) +} + +/// The candidates `kind` allows, in the order to try them. +/// +/// Takes the tiers as arguments so a test can supply stubs instead of whatever +/// this host compiles in. +fn candidates<'a>(kind: &Kind, platform: &'a [Candidate], software: &'a [Candidate]) -> Vec<&'a Candidate> { + match kind { + Kind::Software => software.iter().collect(), + // `open` has already checked that a name matches the codec. + Kind::Auto | Kind::Named(_) => platform.iter().chain(software).collect(), + } +} + +fn select(catalog: &AudioConfig, candidates: Vec<&Candidate>) -> Result, Error> { + let codec = &catalog.codec; + let mut refused = Vec::new(); + + for candidate in candidates { + if !(candidate.supports)(codec) { + continue; + } + match (candidate.open)(catalog) { + Ok(backend) => return Ok(backend), + Err(err) => refused.push((candidate.name, err)), + } + } + + // One refusal is the whole answer, so keep its variant: a malformed + // description stays a container error rather than becoming a string. + if refused.len() == 1 { + let (_, err) = refused.remove(0); + return Err(err); + } + if !refused.is_empty() { + let reasons: Vec = refused.iter().map(|(name, err)| format!("{name}: {err}")).collect(); + return Err(Error::Unsupported(reasons.join(", "))); + } + + Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::Activity; + + /// Opens anything it advertises and reports which candidate it came from. + struct Stub(&'static str); + + impl Backend for Stub { + fn decode(&mut self, _packet: &[u8]) -> Result { + Ok(Decoded { + samples: Vec::new(), + activity: Activity::Active, + }) + } + + fn reset(&mut self) -> Result<(), Error> { + Ok(()) + } + + fn sample_rate(&self) -> u32 { + 48_000 + } + + fn layout(&self) -> Layout { + Layout::Stereo + } + + fn name(&self) -> &str { + self.0 + } + } + + const PLATFORM_STUB: Candidate = Candidate { + name: "platform", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Ok(Box::new(Stub("platform"))), + }; + + /// Compiled in but refusing the track, like a platform decoder asked for a + /// layout its framework does not open. + const REFUSING: Candidate = Candidate { + name: "refusing", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Err(Error::Unsupported("not this track".into())), + }; + + const SOFTWARE_STUB: Candidate = Candidate { + name: "software", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Ok(Box::new(Stub("software"))), + }; + + /// Advertises nothing but PCM, so an Opus track never reaches its opener. + const PCM_ONLY: Candidate = Candidate { + name: "pcm-only", + supports: |codec| matches!(codec, AudioCodec::Pcm), + open: |_| panic!("opened for a codec it does not advertise"), + }; + + fn opus() -> AudioConfig { + AudioConfig::new(AudioCodec::Opus, 48_000, 2) + } + + fn pick(kind: Kind, platform: &[Candidate], software: &[Candidate]) -> Result { + let backend = select(&opus(), candidates(&kind, platform, software))?; + Ok(backend.name().to_owned()) + } + + #[test] + fn auto_prefers_platform() { + let name = pick(Kind::Auto, &[PCM_ONLY, PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn auto_falls_back_to_software() { + let name = pick(Kind::Auto, &[REFUSING], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + #[test] + fn software_skips_platform() { + let name = pick(Kind::Software, &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + /// A codec name is not a backend selector: it tries the same tiers as `Auto`. + #[test] + fn named_codec_picks_like_auto() { + let name = pick(Kind::Named("opus".into()), &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn every_refusal_is_reported() { + const ALSO_REFUSING: Candidate = Candidate { + name: "also-refusing", + ..REFUSING + }; + + let err = pick(Kind::Auto, &[REFUSING], &[ALSO_REFUSING]).unwrap_err(); + let message = err.to_string(); + assert!( + message.contains("refusing: ") && message.contains("also-refusing: "), + "{message}" + ); + } + + fn named(name: &str) -> Config { + Config { + kind: Kind::Named(name.into()), + } + } + + /// The codec names published moq-audio accepts still open their codec. + #[test] + fn codec_names_open_their_codec() { + let pcm = AudioConfig::new(AudioCodec::Pcm, 48_000, 2); + assert_eq!(open(&pcm, &named("pcm")).unwrap().name(), pcm::NAME); + assert_eq!(open(&opus(), &named("opus")).unwrap().name(), libopus::NAME); + } + + /// A name for another codec is refused, not quietly swapped for one that decodes. + #[test] + fn another_codecs_name_is_refused() { + assert!(matches!(open(&opus(), &named("pcm")), Err(Error::Unsupported(_)))); + } + + /// Backend names are internal: asking for one is refused like any unknown name. + #[test] + fn backend_names_are_refused() { + let message = open(&opus(), &named(libopus::NAME)) + .err() + .expect("libopus is a backend, not a codec") + .to_string(); + assert!(message.contains("\"libopus\"") && message.contains("opus"), "{message}"); + } +} diff --git a/rs/moq-audio/src/decode/backend/pcm.rs b/rs/moq-audio/src/decode/backend/pcm.rs new file mode 100644 index 00000000000..bead86fb5e0 --- /dev/null +++ b/rs/moq-audio/src/decode/backend/pcm.rs @@ -0,0 +1,78 @@ +//! Uncompressed little-endian `f32` PCM, described entirely by the catalog. + +use super::Backend; +use crate::decode::Decoded; +use crate::{Activity, Error, Layout, pcm}; + +pub(super) const NAME: &str = "pcm"; + +pub(super) struct Pcm { + sample_rate: u32, + layout: Layout, + bytes_per_frame: usize, +} + +impl Pcm { + /// Uses the catalog's rate and channel count, and requires an absent `description`. + pub(super) fn open(catalog: &hang::catalog::AudioConfig) -> Result, Error> { + if catalog.sample_rate == 0 { + return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); + } + if catalog.channel_count == 0 { + return Err(Error::Unsupported("pcm channel count must be greater than zero".into())); + } + if catalog.description.is_some() { + return Err(Error::Unsupported("pcm catalog description must be absent".into())); + } + let bitrate = pcm::bitrate(catalog.sample_rate, catalog.channel_count)?; + if catalog.bitrate.is_some_and(|declared| declared != bitrate) { + return Err(Error::Unsupported(format!( + "pcm catalog bitrate must be {bitrate} bits per second" + ))); + } + + Ok(Box::new(Self { + sample_rate: catalog.sample_rate, + layout: Layout::from_channels(catalog.channel_count)?, + bytes_per_frame: pcm::frame_bytes(1, catalog.channel_count)?, + })) + } +} + +impl Backend for Pcm { + fn decode(&mut self, packet: &[u8]) -> Result { + if packet.is_empty() || !packet.len().is_multiple_of(self.bytes_per_frame) { + return Err(Error::Misaligned { + got: packet.len(), + expected: packet.len().max(1).next_multiple_of(self.bytes_per_frame), + }); + } + + let samples = packet + .as_chunks::<{ pcm::BYTES_PER_SAMPLE }>() + .0 + .iter() + .map(|sample| f32::from_le_bytes(*sample)) + .collect(); + Ok(Decoded { + samples, + activity: Activity::Active, + }) + } + + fn reset(&mut self) -> Result<(), Error> { + Ok(()) + } + + fn sample_rate(&self) -> u32 { + self.sample_rate + } + + fn layout(&self) -> Layout { + self.layout + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/decode/backend/symphonia.rs b/rs/moq-audio/src/decode/backend/symphonia.rs new file mode 100644 index 00000000000..e2a87c6253d --- /dev/null +++ b/rs/moq-audio/src/decode/backend/symphonia.rs @@ -0,0 +1,106 @@ +//! AAC-LC through symphonia, the pure-Rust fallback for hosts without a +//! platform AAC decoder. + +use symphonia_core::codecs::audio::AudioDecoder; + +use super::Backend; +use crate::decode::Decoded; +use crate::{Activity, Error, Layout, aac}; + +pub(super) const NAME: &str = "symphonia"; + +pub(super) struct Symphonia { + inner: symphonia_codec_aac::AacDecoder, + sample_rate: u32, + layout: Layout, +} + +impl Symphonia { + /// AAC-LC in mono or stereo only, which is what every gateway that feeds + /// this crate publishes. + /// + /// HE-AAC is rejected however its config spells it: leading with SBR or PS + /// (mp4a.40.5 / .29), or leading with LC and declaring SBR in a sync extension + /// after the core. Symphonia decodes no SBR either way, so the alternative is + /// half-rate audio that sounds like a fault rather than an unsupported codec. + /// A stream that signals SBR only in band is indistinguishable from LC in the + /// config, and does decode as the core. + pub(super) fn open(catalog: &hang::catalog::AudioConfig) -> Result, Error> { + use symphonia_core::codecs::audio::well_known::CODEC_ID_AAC; + use symphonia_core::codecs::audio::{AudioCodecParameters, AudioDecoderOptions}; + + let hang::catalog::AudioCodec::AAC(codec) = &catalog.codec else { + return Err(Error::Unsupported(format!("symphonia cannot decode {}", catalog.codec))); + }; + let description = aac::description(catalog, codec.profile)?; + + let mut params = AudioCodecParameters::new(); + params + .for_codec(CODEC_ID_AAC) + .with_extra_data(description.to_vec().into_boxed_slice()); + + let inner = symphonia_codec_aac::AacDecoder::try_new(¶ms, &AudioDecoderOptions::default()) + .map_err(|err| Error::Unsupported(format!("aac decoder: {err}")))?; + + // Resolved by the decoder from the config, so this is what it will emit + // even when the catalog's own fields say otherwise. + let params = inner.codec_params(); + let sample_rate = params + .sample_rate + .ok_or_else(|| Error::Unsupported("aac config declares no sample rate".into()))?; + let channel_count = params + .channels + .as_ref() + .map(|channels| channels.count()) + .ok_or_else(|| Error::Unsupported("aac config declares no channels".into()))?; + + Ok(Box::new(Self { + inner, + sample_rate, + layout: Layout::from_channels(channel_count as u32)?, + })) + } +} + +impl Backend for Symphonia { + fn decode(&mut self, packet: &[u8]) -> Result { + // The packet is a raw AAC frame, not ADTS, so there is nothing to timestamp + // it with here: the container carries the timestamp and the decoder only + // reads the payload. + let packet = symphonia_core::packet::PacketRef::new( + 0, + symphonia_core::units::Timestamp::ZERO, + symphonia_core::units::Duration::ZERO, + packet, + ); + + let decoded = self + .inner + .decode_ref(&packet) + .map_err(|err| Error::Decode(format!("aac: {err}")))?; + + let mut samples = Vec::new(); + decoded.copy_to_vec_interleaved(&mut samples); + Ok(Decoded { + samples, + activity: Activity::Active, + }) + } + + fn reset(&mut self) -> Result<(), Error> { + self.inner.reset(); + Ok(()) + } + + fn sample_rate(&self) -> u32 { + self.sample_rate + } + + fn layout(&self) -> Layout { + self.layout + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 3fd22b32673..cefdb75670f 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -5,7 +5,7 @@ use std::collections::VecDeque; use bytes::Bytes; use super::decoder::{Config, Decoder}; -use crate::resample::{Resampler, remix, validate_remix}; +use crate::resample::{Remix, Resampler}; use crate::{Activity, Error, Format, Frame, Layout}; /// Where a consumer starts on a track that already holds groups. @@ -63,6 +63,8 @@ pub struct Consumer { decoder: Decoder, track: moq_mux::container::Consumer, resampler: Option, + /// Converts the decoded layout to the output's, when they differ. + remix: Option, options: Options, max_age: std::time::Duration, resolved_sample_rate: u32, @@ -111,7 +113,9 @@ impl Consumer { let decoder = Decoder::new(catalog, &options.decoder)?; let sample_rate = options.output.sample_rate.unwrap_or_else(|| decoder.sample_rate()); let layout = options.output.layout.unwrap_or_else(|| decoder.layout()); - validate_remix(decoder.layout(), layout)?; + let remix = (decoder.layout() != layout) + .then(|| Remix::new(decoder.layout(), layout)) + .transpose()?; let resampler = if sample_rate == decoder.sample_rate() { None @@ -167,6 +171,7 @@ impl Consumer { decoder, track, resampler, + remix, options, max_age, resolved_sample_rate: sample_rate, @@ -184,6 +189,11 @@ impl Consumer { }) } + /// The decoder backend name in use, e.g. `"libopus"` or `"symphonia"`. + pub fn name(&self) -> &str { + self.decoder.name() + } + /// The options this consumer was built with. pub fn options(&self) -> &Options { &self.options @@ -440,10 +450,9 @@ impl Consumer { /// Remix and pack decoded PCM into an output frame. fn frame(&self, pcm: Vec, timestamp: moq_net::Timestamp, activity: Activity) -> Result { - let pcm = if self.decoder.layout() == self.resolved_layout { - pcm - } else { - remix(&pcm, self.decoder.layout(), self.resolved_layout)? + let pcm = match &self.remix { + Some(remix) => remix.process(&pcm), + None => pcm, }; let bytes = self diff --git a/rs/moq-audio/src/decode/decoder.rs b/rs/moq-audio/src/decode/decoder.rs index 3d813c40c65..7b600582fd6 100644 --- a/rs/moq-audio/src/decode/decoder.rs +++ b/rs/moq-audio/src/decode/decoder.rs @@ -1,36 +1,25 @@ //! Audio decoder front end. //! -//! Mirror of [`encode::Encoder`](crate::encode::Encoder): dispatches over the -//! catalog codec and produces interleaved `f32` PCM. - -use unsafe_libopus::{ - OPUS_OK, OPUS_RESET_STATE, OPUS_SET_GAIN_REQUEST, OpusDecoder, opus_decode_float, opus_decoder_create, - opus_decoder_ctl_impl, opus_decoder_destroy, varargs, -}; - -#[cfg(feature = "aac")] -use symphonia_core::codecs::audio::AudioDecoder; +//! Mirror of [`encode::Encoder`](crate::encode::Encoder): opens a +//! [`Backend`](super::backend::Backend) for the catalog codec and trims its +//! startup delay, producing interleaved `f32` PCM. use super::Decoded; -#[cfg(feature = "aac")] -use crate::aac; -use crate::opus; -use crate::pcm; -use crate::{Activity, Error, Layout}; - -/// Opus packets cap at 120 ms (RFC 6716 §2.1.4). -const MAX_FRAME_MS: usize = 120; +use super::backend::{self, Backend}; +use crate::{Error, Layout}; /// Decoder backend selection. #[derive(Clone, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub enum Kind { - /// Pick the available backend automatically. + /// Prefer a platform decoder, falling back to software. #[default] Auto, - /// Require the built-in software backend. + /// Require a software backend. Software, - /// Require a backend by its stable lowercase name. + /// Require the track to be this codec, by its lowercase name: `"opus"`, + /// `"pcm"`, or `"aac"`. Any other codec is refused. The library still picks + /// the backend, platform first. Named(String), } @@ -54,183 +43,43 @@ impl Config { /// The bring-your-own-payload layer under [`Consumer`](super::Consumer): use it /// when the packets don't come from a plain track subscription. pub struct Decoder { - backend: Backend, - sample_rate: u32, - layout: Layout, + backend: Box, + /// Startup delay in native-rate frames, and how much of it is left to trim. delay: usize, -} - -enum Backend { - Opus(Opus), - Pcm { - bytes_per_frame: usize, - }, - #[cfg(feature = "aac")] - Aac(Box), -} - -struct Opus { - inner: *mut OpusDecoder, - pre_skip_remaining: usize, - max_frame_size: usize, - in_dtx: bool, -} - -// SAFETY: see Encoder. -unsafe impl Send for Opus {} - -/// Boxed in [`Backend`]: the symphonia decoder carries its own filterbank state, -/// which is far larger than the other backends' handles. -#[cfg(feature = "aac")] -struct Aac { - inner: symphonia_codec_aac::AacDecoder, + delay_remaining: usize, } impl Decoder { /// Build a decoder from a catalog [`AudioConfig`](hang::catalog::AudioConfig). /// /// Opus decodes at 48 kHz with the pre-skip and gain its OpusHead - /// `description` declares, refusing a malformed head or a channel mapping - /// other than mono/stereo; without a description it takes the catalog's - /// channel count and applies neither. PCM uses the catalog fields directly - /// and requires an absent `description`. + /// `description` declares, refusing a malformed head; without a description + /// it takes the catalog's channel count and applies neither. PCM uses the + /// catalog fields directly and requires an absent `description`. AAC reads + /// its AudioSpecificConfig, synthesizing one from the catalog when absent. pub fn new(catalog: &hang::catalog::AudioConfig, config: &Config) -> Result { - let name = match &catalog.codec { - hang::catalog::AudioCodec::Opus => "opus", - hang::catalog::AudioCodec::Pcm => "pcm", - #[cfg(feature = "aac")] - hang::catalog::AudioCodec::AAC(_) => "aac", - codec => return Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))), - }; - match &config.kind { - Kind::Auto | Kind::Software => {} - Kind::Named(requested) if requested == name => {} - Kind::Named(requested) => { - return Err(Error::Unsupported(format!( - "audio decoder backend {requested:?} is unavailable for {name}" - ))); - } - } - match &catalog.codec { - hang::catalog::AudioCodec::Opus => Self::new_opus(catalog), - hang::catalog::AudioCodec::Pcm => Self::new_pcm(catalog), - #[cfg(feature = "aac")] - hang::catalog::AudioCodec::AAC(aac) => Self::new_aac(catalog, aac.profile), - codec => Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))), - } - } - - fn new_opus(catalog: &hang::catalog::AudioConfig) -> Result { - let head = opus::head(catalog)?; - let channels = opus::validate_channels(head.channel_count)?; - - let mut err = 0i32; - // SAFETY: out-pointer is valid; inner is checked for null below. - let inner = unsafe { opus_decoder_create(opus::DECODE_RATE as i32, channels, &mut err) }; - if err != OPUS_OK || inner.is_null() { - return Err(opus::error(err, "opus_decoder_create")); - } - // Owned before the gain ctl so a failure there still destroys the decoder. - let decoder = Opus { - inner, - pre_skip_remaining: head.pre_skip as usize, - max_frame_size: (opus::DECODE_RATE as usize * MAX_FRAME_MS) / 1000, - in_dtx: false, - }; - - // Same Q7.8 dB units as OpusHead, and it survives OPUS_RESET_STATE. - // SAFETY: `inner` owns a live decoder and OPUS_SET_GAIN takes one i32. - let rc = - unsafe { opus_decoder_ctl_impl(decoder.inner, OPUS_SET_GAIN_REQUEST, varargs![head.output_gain as i32]) }; - if rc != OPUS_OK { - return Err(opus::error(rc, "OPUS_SET_GAIN")); - } - - Ok(Self { - delay: decoder.pre_skip_remaining, - backend: Backend::Opus(decoder), - sample_rate: opus::DECODE_RATE, - layout: Layout::from_channels(head.channel_count)?, - }) - } - - /// AAC-LC only, which is what every gateway that feeds this crate publishes. - /// - /// HE-AAC is rejected however its config spells it: leading with SBR or PS - /// (mp4a.40.5 / .29), or leading with LC and declaring SBR in a sync extension - /// after the core. Symphonia decodes no SBR either way, so the alternative is - /// half-rate audio that sounds like a fault rather than an unsupported codec. - /// A stream that signals SBR only in band is indistinguishable from LC in the - /// config, and does decode as the core. - #[cfg(feature = "aac")] - fn new_aac(catalog: &hang::catalog::AudioConfig, profile: u8) -> Result { - use symphonia_core::codecs::audio::well_known::CODEC_ID_AAC; - use symphonia_core::codecs::audio::{AudioCodecParameters, AudioDecoderOptions}; - - let description = aac::description(catalog, profile)?; - - let mut params = AudioCodecParameters::new(); - params - .for_codec(CODEC_ID_AAC) - .with_extra_data(description.to_vec().into_boxed_slice()); - - let inner = symphonia_codec_aac::AacDecoder::try_new(¶ms, &AudioDecoderOptions::default()) - .map_err(|err| Error::Unsupported(format!("aac decoder: {err}")))?; - - // Resolved by the decoder from the config, so this is what it will emit - // even when the catalog's own fields say otherwise. - let params = inner.codec_params(); - let sample_rate = params - .sample_rate - .ok_or_else(|| Error::Unsupported("aac config declares no sample rate".into()))?; - let channel_count = params - .channels - .as_ref() - .map(|channels| channels.count()) - .ok_or_else(|| Error::Unsupported("aac config declares no channels".into()))?; - + let backend = backend::open(catalog, config)?; + let delay = backend.delay(); Ok(Self { - backend: Backend::Aac(Box::new(Aac { inner })), - sample_rate, - layout: Layout::from_channels(channel_count as u32)?, - delay: 0, + backend, + delay, + delay_remaining: delay, }) } - fn new_pcm(catalog: &hang::catalog::AudioConfig) -> Result { - if catalog.sample_rate == 0 { - return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); - } - if catalog.channel_count == 0 { - return Err(Error::Unsupported("pcm channel count must be greater than zero".into())); - } - if catalog.description.is_some() { - return Err(Error::Unsupported("pcm catalog description must be absent".into())); - } - let bitrate = pcm::bitrate(catalog.sample_rate, catalog.channel_count)?; - if catalog.bitrate.is_some_and(|declared| declared != bitrate) { - return Err(Error::Unsupported(format!( - "pcm catalog bitrate must be {bitrate} bits per second" - ))); - } - let bytes_per_frame = pcm::frame_bytes(1, catalog.channel_count)?; - - Ok(Self { - backend: Backend::Pcm { bytes_per_frame }, - sample_rate: catalog.sample_rate, - layout: Layout::from_channels(catalog.channel_count)?, - delay: 0, - }) + /// The decoder backend name in use, e.g. `"libopus"` or `"symphonia"`. + pub fn name(&self) -> &str { + self.backend.name() } - /// The rate the codec decodes at, read from the catalog. + /// The rate the codec decodes at, which may differ from the catalog's. pub fn sample_rate(&self) -> u32 { - self.sample_rate + self.backend.sample_rate() } - /// The PCM layout decoded from the catalog. + /// The PCM layout the codec decodes to. pub fn layout(&self) -> Layout { - self.layout + self.backend.layout() } /// Reset codec history and reapply startup delay for a new discontinuous epoch. @@ -242,27 +91,12 @@ impl Decoder { /// Reapply catalog startup delay for a new playhead epoch without resetting codec prediction. pub(super) fn reapply_delay(&mut self) { - if let Backend::Opus(opus) = &mut self.backend { - opus.pre_skip_remaining = self.delay; - } + self.delay_remaining = self.delay; } /// Reset codec prediction after packet loss without reapplying stream startup delay. pub(super) fn reset_prediction(&mut self) -> Result<(), Error> { - match &mut self.backend { - Backend::Opus(opus) => { - // SAFETY: `inner` owns a live decoder and OPUS_RESET_STATE takes no arguments. - let rc = unsafe { opus_decoder_ctl_impl(opus.inner, OPUS_RESET_STATE, varargs![]) }; - if rc != OPUS_OK { - return Err(crate::opus::error(rc, "OPUS_RESET_STATE")); - } - opus.in_dtx = false; - } - Backend::Pcm { .. } => {} - #[cfg(feature = "aac")] - Backend::Aac(aac) => aac.inner.reset(), - } - Ok(()) + self.backend.reset() } /// How much startup delay is still to be trimmed, in native-rate frames. @@ -271,101 +105,25 @@ impl Decoder { /// it, so a caller tracking where a packet ends has to add back whatever this /// dropped across the call. pub(super) fn delay_remaining(&self) -> usize { - match &self.backend { - Backend::Opus(opus) => opus.pre_skip_remaining, - Backend::Pcm { .. } => 0, - #[cfg(feature = "aac")] - Backend::Aac(_) => 0, - } + self.delay_remaining } /// Decode one packet into interleaved `f32` PCM and report its codec activity. /// - /// Empty Opus packets invoke packet-loss concealment. Loss during DTX remains - /// classified as DTX, while loss during active audio remains active. + /// An empty Opus packet marks one lost packet and conceals as much audio as the + /// last packet that decoded held, so a lost 20 ms packet yields 20 ms. It is + /// refused with [`Error::Decode`] before any packet has decoded, since there is + /// no length to conceal. Loss during DTX remains classified as DTX, while loss + /// during active audio remains active. pub fn decode(&mut self, packet: &[u8]) -> Result { - match &mut self.backend { - Backend::Opus(opus) => { - let channels = self.layout.channels() as usize; - let mut out = vec![0.0f32; opus.max_frame_size * channels]; - // SAFETY: `inner` owns a live OpusDecoder; packet/out slices are - // bounded by the lengths we pass. - let samples = unsafe { - opus_decode_float( - &mut *opus.inner, - packet.as_ptr(), - packet.len() as i32, - out.as_mut_ptr(), - opus.max_frame_size as i32, - 0, - ) - }; - if samples < 0 { - return Err(crate::opus::decode_error(samples)); - } - out.truncate(samples as usize * channels); - let trim_frames = opus.pre_skip_remaining.min(samples as usize); - if trim_frames > 0 { - let trim_samples = trim_frames * channels; - out.copy_within(trim_samples.., 0); - out.truncate(out.len() - trim_samples); - opus.pre_skip_remaining -= trim_frames; - } - let activity = crate::opus::activity(packet, opus.in_dtx); - opus.in_dtx = activity.is_dtx(); - Ok(Decoded { samples: out, activity }) - } - Backend::Pcm { bytes_per_frame } => { - if packet.is_empty() || !packet.len().is_multiple_of(*bytes_per_frame) { - return Err(Error::Misaligned { - got: packet.len(), - expected: packet.len().max(1).next_multiple_of(*bytes_per_frame), - }); - } - - let out = packet - .as_chunks::<{ pcm::BYTES_PER_SAMPLE }>() - .0 - .iter() - .map(|sample| f32::from_le_bytes([sample[0], sample[1], sample[2], sample[3]])) - .collect(); - Ok(Decoded { - samples: out, - activity: Activity::Active, - }) - } - #[cfg(feature = "aac")] - Backend::Aac(aac) => { - // The packet is a raw AAC frame, not ADTS, so there is nothing to - // timestamp it with here: the container carries the timestamp and the - // decoder only reads the payload. - let packet = symphonia_core::packet::PacketRef::new( - 0, - symphonia_core::units::Timestamp::ZERO, - symphonia_core::units::Duration::ZERO, - packet, - ); - - let decoded = aac - .inner - .decode_ref(&packet) - .map_err(|err| Error::Decode(format!("aac: {err}")))?; - - let mut out = Vec::new(); - decoded.copy_to_vec_interleaved(&mut out); - Ok(Decoded { - samples: out, - activity: Activity::Active, - }) - } + let mut decoded = self.backend.decode(packet)?; + let channels = self.backend.layout().channels() as usize; + let trim = self.delay_remaining.min(decoded.samples.len() / channels); + if trim > 0 { + decoded.samples.drain(..trim * channels); + self.delay_remaining -= trim; } - } -} - -impl Drop for Opus { - fn drop(&mut self) { - // SAFETY: `inner` is a live OpusDecoder that nothing else aliases. - unsafe { opus_decoder_destroy(self.inner) }; + Ok(decoded) } } @@ -400,10 +158,18 @@ pub(crate) mod tests { catalog } + /// The published `Decoder` was unwind safe before it boxed a backend; keep it so. + #[test] + fn decoder_is_unwind_safe() { + fn assert_unwind_safe() {} + assert_unwind_safe::(); + } + #[cfg(feature = "aac")] #[test] fn aac_decodes_a_sine() { let mut decoder = Decoder::new(&aac_catalog(), &Config::default()).unwrap(); + assert_eq!(decoder.name(), "symphonia"); assert_eq!(decoder.sample_rate(), 44_100); assert_eq!(decoder.layout(), Layout::Mono); @@ -504,6 +270,29 @@ pub(crate) mod tests { } } + /// One lost packet conceals one packet's worth of audio, not the 120 ms + /// libopus would fill given the whole buffer. + #[test] + fn opus_conceals_the_length_of_the_last_packet() { + let packets = opus_packets(3); + let mut decoder = Decoder::new( + &opus_catalog(moq_mux::codec::opus::Config::new(48_000, 1)), + &Config::default(), + ) + .unwrap(); + + // Nothing decoded yet, so there is no length to conceal. + assert!(matches!(decoder.decode(&[]), Err(Error::Decode(_)))); + + for packet in &packets { + decoder.decode(packet).unwrap(); + } + assert_eq!(decoder.decode(&[]).unwrap().samples.len(), 960); + + // Concealment doesn't change the length: the next loss is the same size. + assert_eq!(decoder.decode(&[]).unwrap().samples.len(), 960); + } + #[test] fn opus_applies_the_declared_gain() { let packets = opus_packets(5); @@ -564,26 +353,6 @@ pub(crate) mod tests { } } - /// Mapping families other than 0 need the multistream decoder; a stereo - /// family 1 head is refused rather than decoded as family 0. - #[test] - fn opus_refuses_unsupported_channel_mappings() { - let valid = moq_mux::codec::opus::Config::new(48_000, 2).encode().unwrap().to_vec(); - for family in [1, 255] { - let mut description = valid.clone(); - description[18] = family; - // One coupled stream, left then right. - description.extend_from_slice(&[1, 1, 0, 1]); - - let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); - catalog.description = Some(description.into()); - assert!( - matches!(Decoder::new(&catalog, &Config::default()), Err(Error::Unsupported(_))), - "family {family}" - ); - } - } - /// Without a description the catalog shapes the stream, which has no pre-skip. #[test] fn opus_decodes_without_a_description() { @@ -636,6 +405,24 @@ pub(crate) mod tests { )); } + /// Published moq-audio accepts the codec's name, not a backend's. + #[cfg(feature = "aac")] + #[test] + fn named_aac_decodes_aac() { + let config = Config { + kind: Kind::Named("aac".into()), + }; + assert!(Decoder::new(&aac_catalog(), &config).is_ok()); + + let config = Config { + kind: Kind::Named("opus".into()), + }; + assert!(matches!( + Decoder::new(&aac_catalog(), &config), + Err(Error::Unsupported(_)) + )); + } + #[test] fn refuses_unavailable_backend() { let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 2); diff --git a/rs/moq-audio/src/decode/mod.rs b/rs/moq-audio/src/decode/mod.rs index 7e3cbd14a71..6f4500054c4 100644 --- a/rs/moq-audio/src/decode/mod.rs +++ b/rs/moq-audio/src/decode/mod.rs @@ -10,8 +10,11 @@ //! [`Decoded`] interleaved `f32` samples. //! //! [`Options`] keeps subscription and output policy separate from the -//! lower-level decoder [`Config`]. +//! lower-level decoder [`Config`], whose [`Kind`] picks the backend: a +//! platform decoder first where one takes the track, then software (libopus, +//! PCM, and symphonia for AAC-LC). +mod backend; mod consumer; mod decoded; mod decoder; diff --git a/rs/moq-audio/src/encode/backend/libopus.rs b/rs/moq-audio/src/encode/backend/libopus.rs new file mode 100644 index 00000000000..118c701be46 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/libopus.rs @@ -0,0 +1,207 @@ +//! Opus through libopus 1.3.1, via [`unsafe_libopus`]. + +use bytes::Bytes; +use unsafe_libopus::{ + OPUS_APPLICATION_AUDIO, OPUS_GET_BITRATE_REQUEST, OPUS_GET_LOOKAHEAD_REQUEST, OPUS_OK, OPUS_RESET_STATE, + OPUS_SET_BITRATE_REQUEST, OPUS_SET_DTX_REQUEST, OpusEncoder, opus_encode_float, opus_encoder_create, + opus_encoder_ctl_impl, opus_encoder_destroy, varargs, +}; + +use super::Backend; +use crate::encode::{Encoded, Settings}; +use crate::{Error, opus}; + +pub(super) const NAME: &str = "libopus"; + +/// libopus packet size ceiling per RFC 6716 §3.4. +const MAX_PACKET_BYTES: usize = 4_000; + +pub(super) struct Libopus { + inner: *mut OpusEncoder, + scratch: Vec, + sample_rate: u32, + channels: u32, + frame_size: usize, + bitrate: u64, + lookahead: usize, +} + +// SAFETY: OpusEncoder is heap-allocated state owned exclusively by this +// struct; libopus encoder methods take a single &mut, so a unique owner is +// allowed to move it across threads. +unsafe impl Send for Libopus {} + +impl Libopus { + /// Opens at the settings' rate and layout, which the front end has already + /// checked against what Opus codes. + pub(super) fn open(settings: &Settings) -> Result, Error> { + Ok(Box::new(Self::new(settings)?)) + } + + fn new(settings: &Settings) -> Result { + let sample_rate = settings.sample_rate; + let channels = settings.layout.channels(); + let frame_size = opus::frame_size(sample_rate, settings.frame_duration)?; + + let mut err = 0i32; + // SAFETY: out-pointer `err` is valid; inner is checked for null below. + let inner = unsafe { + opus_encoder_create( + sample_rate as i32, + opus::validate_channels(channels)?, + OPUS_APPLICATION_AUDIO, + &mut err, + ) + }; + if err != OPUS_OK || inner.is_null() { + return Err(opus::error(err, "opus_encoder_create")); + } + + // Owned from here, so an early return below destroys it. + let mut backend = Self { + inner, + scratch: vec![0u8; MAX_PACKET_BYTES], + sample_rate, + channels, + frame_size, + bitrate: 0, + lookahead: 0, + }; + + if let Some(bitrate) = settings.bitrate { + backend.set_rate(bitrate.as_bps())?; + } + backend.set_ctl(OPUS_SET_DTX_REQUEST, i32::from(settings.dtx), "OPUS_SET_DTX")?; + + let bitrate = backend.get_ctl(OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE")?; + backend.bitrate = u64::try_from(bitrate) + .map_err(|_| Error::Unsupported(format!("Opus reported negative bitrate {bitrate}")))?; + let lookahead = backend.get_ctl(OPUS_GET_LOOKAHEAD_REQUEST, "OPUS_GET_LOOKAHEAD")?; + backend.lookahead = usize::try_from(lookahead) + .map_err(|_| Error::Unsupported(format!("Opus reported negative lookahead {lookahead}")))?; + + Ok(backend) + } + + /// Refuse rates libopus would silently clamp, then apply the rest. + fn set_rate(&mut self, bitrate: u64) -> Result<(), Error> { + let (channels, frame_size) = (self.channels, self.frame_size); + let max = 300_000 * channels as u64; + let min = opus::bitrate_floor(self.sample_rate, frame_size).max(500); + if !(min..=max).contains(&bitrate) { + return Err(Error::Unsupported(format!( + "Opus bitrate must be between {min} and {max} bits per second for {channels} channel(s) at {frame_size} samples, got {bitrate}" + ))); + } + self.set_ctl(OPUS_SET_BITRATE_REQUEST, bitrate as i32, "OPUS_SET_BITRATE") + } + + fn set_ctl(&mut self, request: i32, value: i32, name: &'static str) -> Result<(), Error> { + // SAFETY: `inner` owns a live encoder and each request here expects one i32. + let rc = unsafe { opus_encoder_ctl_impl(self.inner, request, varargs![value]) }; + if rc != OPUS_OK { + return Err(opus::error(rc, name)); + } + Ok(()) + } + + fn get_ctl(&self, request: i32, name: &'static str) -> Result { + let mut value = 0; + // SAFETY: `inner` owns a live encoder and each request here expects one + // valid mutable i32 output. + let rc = unsafe { opus_encoder_ctl_impl(self.inner, request, varargs![&mut value]) }; + if rc != OPUS_OK { + return Err(opus::error(rc, name)); + } + Ok(value) + } +} + +impl Backend for Libopus { + fn encode(&mut self, pcm: &[f32]) -> Result { + // SAFETY: `inner` owns a live OpusEncoder; pcm and scratch slices are + // bounded by the lengths we pass, and the front end sized `pcm` to one frame. + let n = unsafe { + opus_encode_float( + self.inner, + pcm.as_ptr(), + self.frame_size as i32, + self.scratch.as_mut_ptr(), + self.scratch.len() as i32, + ) + }; + if n < 0 { + return Err(opus::error(n, "opus_encode_float")); + } + let payload = Bytes::copy_from_slice(&self.scratch[..n as usize]); + let activity = opus::activity(&payload, false); + Ok(Encoded { payload, activity }) + } + + fn reset(&mut self) { + // SAFETY: `inner` owns a live encoder and OPUS_RESET_STATE takes no arguments. + let rc = unsafe { opus_encoder_ctl_impl(self.inner, OPUS_RESET_STATE, varargs![]) }; + debug_assert_eq!(rc, OPUS_OK, "OPUS_RESET_STATE failed with {rc}"); + } + + fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error> { + if bitrate != self.bitrate { + self.set_rate(bitrate)?; + self.bitrate = bitrate; + } + Ok(()) + } + + fn bitrate(&self) -> u64 { + self.bitrate + } + + fn delay(&self) -> usize { + self.lookahead + } + + fn name(&self) -> &str { + NAME + } +} + +impl Drop for Libopus { + fn drop(&mut self) { + // SAFETY: `inner` is a live OpusEncoder that nothing else aliases. + unsafe { opus_encoder_destroy(self.inner) }; + } +} + +#[cfg(test)] +mod tests { + use unsafe_libopus::OPUS_GET_DTX_REQUEST; + + use super::*; + + #[test] + fn runtime_bitrate_reaches_libopus() { + let mut backend = Libopus::new(&Settings { + bitrate: Some(moq_net::bandwidth::Rate::from_bps(64_000)), + ..Settings::default() + }) + .unwrap(); + + backend.set_bitrate(32_000).unwrap(); + assert_eq!(backend.bitrate(), 32_000); + assert_eq!( + backend.get_ctl(OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE").unwrap(), + 32_000 + ); + } + + #[test] + fn applies_dtx_control() { + let backend = Libopus::new(&Settings { + dtx: true, + ..Settings::default() + }) + .unwrap(); + + assert_eq!(backend.get_ctl(OPUS_GET_DTX_REQUEST, "OPUS_GET_DTX").unwrap(), 1); + } +} diff --git a/rs/moq-audio/src/encode/backend/mod.rs b/rs/moq-audio/src/encode/backend/mod.rs new file mode 100644 index 00000000000..97f4dbdc025 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/mod.rs @@ -0,0 +1,336 @@ +//! Pluggable audio encoder backends. +//! +//! The mirror of the decode backends. [`Backend`] is the seam between the codec +//! and the [`Encoder`](super::Encoder) front end, which owns what every backend +//! of a codec shares: validating [`Settings`](super::Settings) against the +//! codec, framing the input, draining the startup delay at the end, and the +//! catalog entry, whose description is synthesized from the settings rather than +//! read back from the backend. +//! +//! [`open`] tries the platform encoders before the software ones, skipping any +//! that does not emit the codec, and refuses when none opens. [`Kind::Named`] +//! names the codec, not a backend, so which backend encodes it stays the +//! library's choice. The software tier +//! is libopus for Opus and a passthrough for PCM. AAC has no software encoder, +//! so it is only as available as the platform's, and no platform encoder is +//! wired in yet. + +use super::Encoded; +use super::encoder::{Codec, Kind, Settings}; +use crate::Error; + +mod libopus; +mod pcm; + +#[cfg(test)] +pub(crate) mod stub; + +/// An opened encoder: one frame of interleaved `f32` PCM in, one packet out. +/// +/// Input arrives at the settings' rate, in the crate's canonical channel order +/// for the settings' layout; a codec with another native order reorders it here. +/// +/// One packet per frame is part of the contract: the producer stamps packets by +/// counting frames. A codec that pipelines output (MediaCodec) needs a `flush` +/// and a zero-or-more return, which changes `Encoder::encode` too, so that lands +/// with the first backend that needs it rather than as an always-empty method. +/// +/// Unwind safe because the published `Encoder` that boxes it is. +pub(crate) trait Backend: Send + std::panic::UnwindSafe + std::panic::RefUnwindSafe { + /// Encode exactly one frame of the codec's frame size. + fn encode(&mut self, pcm: &[f32]) -> Result; + + /// Drop codec history so the next frame codes as if it were the first. + fn reset(&mut self); + + /// Retune the live encoder to `bitrate` bits per second, a no-op at the current + /// rate. + /// + /// No default: a backend that can't change rate mid-stream refuses with + /// [`Error::Unsupported`] and keeps its opening rate, rather than inheriting a + /// silent no-op that ignores congestion. + fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error>; + + /// The current target bitrate in bits per second, as the codec resolved it. + fn bitrate(&self) -> u64; + + /// Frames of codec priming at the start of the decoded stream, at the codec + /// rate: Opus lookahead, AAC encoder delay. + fn delay(&self) -> usize; + + /// The stable lowercase name of this backend, as [`Encoder::name`](super::Encoder::name) + /// reports it. Callers never select by it. + fn name(&self) -> &str; +} + +/// A backend constructor: its name, the codecs it emits, and an opener. +struct Candidate { + name: &'static str, + codecs: &'static [Codec], + open: fn(&Settings) -> Result, Error>, +} + +/// Operating-system encoders, in priority order. +const PLATFORM: &[Candidate] = &[]; + +const SOFTWARE: &[Candidate] = &[ + Candidate { + name: libopus::NAME, + codecs: &[Codec::Opus], + open: libopus::Libopus::open, + }, + Candidate { + name: pcm::NAME, + codecs: &[Codec::Pcm], + open: pcm::Pcm::open, + }, +]; + +/// The platform tier on a test thread that called [`stub::install`], so AAC tests +/// open the same backend on every host and every other test sees the real tiers. +#[cfg(test)] +const STUB_PLATFORM: &[Candidate] = &[Candidate { + name: stub::NAME, + codecs: &[Codec::Aac], + open: stub::Stub::open, +}]; + +/// Open the first backend that emits the codec and accepts the settings. +pub(crate) fn open(settings: &Settings) -> Result, Error> { + if let Kind::Named(requested) = &settings.kind + && requested != settings.codec.as_str() + { + return Err(Error::Unsupported(format!( + "audio encoder {requested:?} is unavailable for {}", + settings.codec + ))); + } + + #[cfg(test)] + let platform = match stub::installed() { + true => STUB_PLATFORM, + false => PLATFORM, + }; + #[cfg(not(test))] + let platform = PLATFORM; + + select(settings, candidates(&settings.kind, platform, SOFTWARE)) +} + +/// The candidates `kind` allows, in the order to try them. +/// +/// Takes the tiers as arguments so a test can supply stubs instead of whatever +/// this host compiles in. +fn candidates<'a>(kind: &Kind, platform: &'a [Candidate], software: &'a [Candidate]) -> Vec<&'a Candidate> { + match kind { + Kind::Software => software.iter().collect(), + // `open` has already checked that a name matches the codec. + Kind::Auto | Kind::Named(_) => platform.iter().chain(software).collect(), + } +} + +fn select(settings: &Settings, candidates: Vec<&Candidate>) -> Result, Error> { + let codec = settings.codec; + let mut refused = Vec::new(); + + for candidate in candidates { + if !candidate.codecs.contains(&codec) { + continue; + } + match (candidate.open)(settings) { + Ok(backend) => return Ok(backend), + Err(err) => refused.push((candidate.name, err)), + } + } + + // One refusal is the whole answer, so keep its variant. + if refused.len() == 1 { + let (_, err) = refused.remove(0); + return Err(err); + } + if !refused.is_empty() { + let reasons: Vec = refused.iter().map(|(name, err)| format!("{name}: {err}")).collect(); + return Err(Error::Unsupported(reasons.join(", "))); + } + + let available: Vec<&str> = PLATFORM + .iter() + .chain(SOFTWARE) + .filter(|c| c.codecs.contains(&codec)) + .map(|c| c.name) + .collect(); + let available = match available.is_empty() { + true => "none".to_owned(), + false => available.join(", "), + }; + Err(Error::Unsupported(match &settings.kind { + Kind::Software => format!("no software {codec} audio encoder (this build has: {available})"), + Kind::Auto | Kind::Named(_) => format!("no {codec} audio encoder (this build has: {available})"), + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Opens anything it advertises and reports which candidate it came from. + struct Fake(&'static str); + + impl Backend for Fake { + fn encode(&mut self, _pcm: &[f32]) -> Result { + Ok(Encoded::new(bytes::Bytes::new())) + } + + fn reset(&mut self) {} + + fn set_bitrate(&mut self, _bitrate: u64) -> Result<(), Error> { + Ok(()) + } + + fn bitrate(&self) -> u64 { + 0 + } + + fn delay(&self) -> usize { + 0 + } + + fn name(&self) -> &str { + self.0 + } + } + + const PLATFORM_STUB: Candidate = Candidate { + name: "platform", + codecs: &[Codec::Aac], + open: |_| Ok(Box::new(Fake("platform"))), + }; + + /// Compiled in but refusing the settings, like a platform encoder asked for a + /// layout its framework does not open. + const REFUSING: Candidate = Candidate { + name: "refusing", + codecs: &[Codec::Aac], + open: |_| Err(Error::Unsupported("not these settings".into())), + }; + + const SOFTWARE_STUB: Candidate = Candidate { + name: "software", + codecs: &[Codec::Aac], + open: |_| Ok(Box::new(Fake("software"))), + }; + + /// Emits nothing but PCM, so an AAC request never reaches its opener. + const PCM_ONLY: Candidate = Candidate { + name: "pcm-only", + codecs: &[Codec::Pcm], + open: |_| panic!("opened for a codec it does not emit"), + }; + + fn aac(kind: Kind) -> Settings { + Settings { + kind, + ..Settings::from_input(Codec::Aac, &Default::default()) + } + } + + fn pick(kind: Kind, platform: &[Candidate], software: &[Candidate]) -> Result { + let settings = aac(kind); + let backend = select(&settings, candidates(&settings.kind, platform, software))?; + Ok(backend.name().to_owned()) + } + + #[test] + fn auto_prefers_platform() { + let name = pick(Kind::Auto, &[PCM_ONLY, PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn auto_falls_back_to_software() { + let name = pick(Kind::Auto, &[REFUSING], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + #[test] + fn software_skips_platform() { + let name = pick(Kind::Software, &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + /// A codec name is not a backend selector: it tries the same tiers as `Auto`. + #[test] + fn named_codec_picks_like_auto() { + let name = pick(Kind::Named("aac".into()), &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn every_refusal_is_reported() { + const ALSO_REFUSING: Candidate = Candidate { + name: "also-refusing", + ..REFUSING + }; + + let err = pick(Kind::Auto, &[REFUSING], &[ALSO_REFUSING]).unwrap_err(); + let message = err.to_string(); + assert!( + message.contains("refusing: ") && message.contains("also-refusing: "), + "{message}" + ); + } + + /// No AAC encoder is wired in outside the test stub, so `Auto` refuses at + /// construction and says there is nothing to fall back to. A platform backend + /// gates this to the hosts without one. + #[test] + fn aac_without_a_platform_encoder_is_refused() { + let err = open(&aac(Kind::Auto)).err().expect("no AAC encoder on this host"); + let message = err.to_string(); + assert!(message.contains("aac") && message.contains("none"), "{message}"); + } + + /// The stub stands in for the platform tier only, so `Software` still refuses + /// AAC with it installed. + #[test] + fn stub_is_not_software() { + let _stub = stub::install(); + assert_eq!(open(&aac(Kind::Auto)).unwrap().name(), stub::NAME); + + let err = open(&aac(Kind::Software)).err().expect("no software AAC encoder"); + assert!(err.to_string().contains("no software aac"), "{err}"); + } + + fn named(codec: Codec, name: &str) -> Settings { + Settings { + codec, + kind: Kind::Named(name.into()), + ..Settings::default() + } + } + + /// A codec's own name opens that codec, like `Auto`. + #[test] + fn codec_names_open_their_codec() { + let _stub = stub::install(); + assert_eq!(open(&named(Codec::Opus, "opus")).unwrap().name(), libopus::NAME); + assert_eq!(open(&named(Codec::Pcm, "pcm")).unwrap().name(), pcm::NAME); + assert_eq!(open(&named(Codec::Aac, "aac")).unwrap().name(), stub::NAME); + } + + /// A name for another codec is refused, not quietly swapped for the settings' codec. + #[test] + fn another_codecs_name_is_refused() { + assert!(matches!(open(&named(Codec::Opus, "pcm")), Err(Error::Unsupported(_)))); + } + + /// Backend names are internal: asking for one is refused like any unknown name. + #[test] + fn backend_names_are_refused() { + let message = open(&named(Codec::Opus, libopus::NAME)) + .err() + .expect("libopus is a backend, not a codec") + .to_string(); + assert!(message.contains("\"libopus\"") && message.contains("opus"), "{message}"); + } +} diff --git a/rs/moq-audio/src/encode/backend/pcm.rs b/rs/moq-audio/src/encode/backend/pcm.rs new file mode 100644 index 00000000000..62a2382a536 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/pcm.rs @@ -0,0 +1,55 @@ +//! Uncompressed little-endian `f32` PCM, which needs no codec at all. + +use super::Backend; +use crate::encode::{Encoded, Settings}; +use crate::{Error, Layout, pcm}; + +pub(super) const NAME: &str = "pcm"; + +pub(super) struct Pcm { + bitrate: u64, +} + +impl Pcm { + /// The catalog carries only a channel count, so a named layout that count + /// would decode as another one is refused rather than relabeled. + pub(super) fn open(settings: &Settings) -> Result, Error> { + let layout = settings.layout; + if !matches!(layout, Layout::Discrete(_)) && Layout::from_channels(layout.channels())? != layout { + return Err(Error::Unsupported(format!( + "pcm carries only a channel count, which decodes as {:?}, not {layout:?}", + Layout::from_channels(layout.channels())? + ))); + } + let bitrate = pcm::bitrate(settings.sample_rate, settings.layout.channels())?; + Ok(Box::new(Self { bitrate })) + } +} + +impl Backend for Pcm { + fn encode(&mut self, pcm: &[f32]) -> Result { + let mut payload = Vec::with_capacity(std::mem::size_of_val(pcm)); + for sample in pcm { + payload.extend_from_slice(&sample.to_le_bytes()); + } + Ok(Encoded::new(payload.into())) + } + + fn reset(&mut self) {} + + fn set_bitrate(&mut self, _bitrate: u64) -> Result<(), Error> { + Err(Error::Unsupported("pcm bitrate is fixed".into())) + } + + fn bitrate(&self) -> u64 { + self.bitrate + } + + fn delay(&self) -> usize { + 0 + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/encode/backend/stub.rs b/rs/moq-audio/src/encode/backend/stub.rs new file mode 100644 index 00000000000..a64cf664689 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/stub.rs @@ -0,0 +1,86 @@ +//! A stand-in AAC encoder, so the AAC front end is testable on a host with no +//! platform encoder. A test opts in with [`install`]; every other test sees the +//! real tiers. + +use std::cell::Cell; + +use bytes::Bytes; + +use super::Backend; +use crate::Error; +use crate::encode::{Encoded, Settings}; + +pub(crate) const NAME: &str = "stub"; + +/// The AudioToolbox AAC-LC encoder delay, which is what a real backend reports. +pub(crate) const DELAY: usize = 2112; + +thread_local! { + static INSTALLED: Cell = const { Cell::new(false) }; +} + +/// Stand the stub in for the platform tier on this thread until the guard drops. +pub(crate) fn install() -> Installed { + INSTALLED.set(true); + Installed(()) +} + +/// Whether this thread has the stub installed. +pub(super) fn installed() -> bool { + INSTALLED.get() +} + +/// Uninstalls the stub on drop. +pub(crate) struct Installed(()); + +impl Drop for Installed { + fn drop(&mut self) { + INSTALLED.set(false); + } +} + +/// Emits each frame's index as its payload, and cannot retune. +pub(crate) struct Stub { + bitrate: u64, + frames: u64, +} + +impl Stub { + pub(super) fn open(settings: &Settings) -> Result, Error> { + Ok(Box::new(Self { + bitrate: settings.bitrate.map_or(128_000, |rate| rate.as_bps()), + frames: 0, + })) + } +} + +impl Backend for Stub { + fn encode(&mut self, _pcm: &[f32]) -> Result { + let payload = Bytes::copy_from_slice(&self.frames.to_be_bytes()); + self.frames += 1; + Ok(Encoded::new(payload)) + } + + fn reset(&mut self) { + self.frames = 0; + } + + fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error> { + match bitrate == self.bitrate { + true => Ok(()), + false => Err(Error::Unsupported("the stub cannot change rate mid-stream".into())), + } + } + + fn bitrate(&self) -> u64 { + self.bitrate + } + + fn delay(&self) -> usize { + DELAY + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/encode/capture.rs b/rs/moq-audio/src/encode/capture.rs index 0eaf08362d9..3430ba5b525 100644 --- a/rs/moq-audio/src/encode/capture.rs +++ b/rs/moq-audio/src/encode/capture.rs @@ -12,7 +12,7 @@ use moq_mux::catalog::hang::CatalogExt; use super::producer::Reserved; use super::{Input, Options, Producer}; use crate::capture; -use crate::resample::{Resampler, remix, validate_remix}; +use crate::resample::{Remix, Resampler}; use crate::{Error, Format, Frame, Layout as PcmLayout}; /// Backoff bounds for reopening a capture source. The quick first retry covers @@ -448,7 +448,7 @@ impl Driver { None => continue, }, }; - let pcm_layout = match PcmLayout::from_channels(layout.channels) { + let pcm_layout = match device_layout(layout.channels) { Ok(layout) => layout, Err(err) => match self.failed(err, track, desired.revision).await { Some(result) => return Some(result), @@ -891,23 +891,29 @@ impl EncoderOutput<'_, E> { } } +/// The layout of a capture device, which reports only a channel count. That names +/// speakers for mono and stereo alone: a six-channel microphone array is not a +/// 5.1 speaker layout, so it stays discrete rather than being remixed as one. +fn device_layout(channels: u32) -> Result { + match channels { + 0..=2 => PcmLayout::from_channels(channels), + channels => Ok(PcmLayout::Discrete(channels)), + } +} + /// Converts one opened stream's native layout into the producer's fixed input /// layout. A new instance per open keeps filter state out of recovery gaps. struct Converter { - input: capture::Layout, - output: capture::Layout, + remix: Option, resampler: Option, anchor_us: Option, } impl Converter { fn new(input: capture::Layout, output: capture::Layout) -> Result { - if input.channels != output.channels { - validate_remix( - PcmLayout::from_channels(input.channels)?, - PcmLayout::from_channels(output.channels)?, - )?; - } + let remix = (input.channels != output.channels) + .then(|| Remix::new(device_layout(input.channels)?, device_layout(output.channels)?)) + .transpose()?; let resampler = if input.sample_rate == output.sample_rate { None @@ -924,8 +930,7 @@ impl Converter { }; Ok(Self { - input, - output, + remix, resampler, anchor_us: None, }) @@ -956,10 +961,8 @@ impl Converter { let data = resampler.process(&samples.data, moq_net::Timestamp::from_micros(timestamp_us)?)?; samples.replace(data); } - if self.input.channels != self.output.channels { - let input = PcmLayout::from_channels(self.input.channels)?; - let output = PcmLayout::from_channels(self.output.channels)?; - let data = remix(&samples.data, input, output)?; + if let Some(remix) = &self.remix { + let data = remix.process(&samples.data); samples.replace(data); } if samples.data.is_empty() { diff --git a/rs/moq-audio/src/encode/encoder.rs b/rs/moq-audio/src/encode/encoder.rs index ca2045a6333..5ba2e3b0747 100644 --- a/rs/moq-audio/src/encode/encoder.rs +++ b/rs/moq-audio/src/encode/encoder.rs @@ -1,26 +1,29 @@ //! Audio encoder front end. //! -//! [`Encoder`] dispatches over the closed [`Codec`] set. Opus wraps libopus -//! 1.3.1 via [`unsafe_libopus`], while PCM serializes interleaved `f32` samples -//! directly. +//! [`Encoder`] checks [`Settings`] against the codec, opens a +//! [`Backend`](super::backend::Backend) for it, and owns what every backend of a +//! codec shares: framing, the terminal drain, and the catalog entry. use std::str::FromStr; use std::time::Duration; use bytes::Bytes; -use unsafe_libopus::{ - OPUS_APPLICATION_AUDIO, OPUS_GET_BITRATE_REQUEST, OPUS_GET_LOOKAHEAD_REQUEST, OPUS_OK, OPUS_RESET_STATE, - OPUS_SET_BITRATE_REQUEST, OPUS_SET_DTX_REQUEST, OpusEncoder, opus_encode_float, opus_encoder_create, - opus_encoder_ctl_impl, opus_encoder_destroy, varargs, -}; use super::Encoded; +use super::backend::{self, Backend}; use crate::opus; use crate::pcm; use crate::{Error, Format, Layout}; -/// libopus packet size ceiling per RFC 6716 §3.4. -const MAX_PACKET_BYTES: usize = 4_000; +/// Samples per channel in one AAC-LC frame. +const AAC_FRAME_SIZE: usize = 1024; + +/// The audioObjectType of AAC-LC (ISO 14496-3 Table 1.17), `mp4a.40.2`. +const AAC_LC: u8 = 2; + +/// The widest sample rate an AudioSpecificConfig can name: the escape from the +/// frequency table is a 24-bit field. +const AAC_MAX_SAMPLE_RATE: u32 = 0xFF_FFFF; /// Output audio codec. `#[non_exhaustive]` so new codecs can be added without /// breaking external `match`es. @@ -32,6 +35,9 @@ pub enum Codec { Opus, /// Uncompressed interleaved little-endian IEEE-754 binary32 PCM. Pcm, + /// AAC-LC (`mp4a.40.2`), through the platform's encoder. A host without one + /// refuses it at construction. + Aac, } impl Codec { @@ -41,6 +47,7 @@ impl Codec { match self { Self::Opus => "opus", Self::Pcm => "pcm", + Self::Aac => "aac", } } } @@ -58,11 +65,27 @@ impl FromStr for Codec { match s { "opus" => Ok(Self::Opus), "pcm" => Ok(Self::Pcm), + "aac" => Ok(Self::Aac), other => Err(Error::Unsupported(format!("unknown codec: {other}"))), } } } +/// Encoder backend selection. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +#[non_exhaustive] +pub enum Kind { + /// Prefer a platform encoder, falling back to software. + #[default] + Auto, + /// Require a software backend. + Software, + /// Require [`Settings::codec`] to be this codec, by its lowercase name: + /// `"opus"`, `"pcm"`, or `"aac"`. Any other codec is refused. The library + /// still picks the backend, platform first. + Named(String), +} + /// PCM supplied to [`Producer::write`](super::Producer::write). #[derive(Clone, Debug)] #[non_exhaustive] @@ -101,9 +124,12 @@ pub struct Settings { /// Sample rate accepted by the codec. pub sample_rate: u32, /// Layout accepted by the codec. + /// + /// AAC takes the layouts its channelConfiguration names: mono, stereo, 3.0, + /// 4.0, 5.0, 5.1, and 7.1. pub layout: Layout, - /// Bitrate in bits per second. `None` lets Opus pick. PCM requires `None` - /// because its bitrate is fixed by the sample rate and channel count. + /// Bitrate in bits per second. `None` lets the codec pick. PCM requires + /// `None` because its bitrate is fixed by the sample rate and channel count. /// /// Rates too low for Opus to code anything at the chosen /// [`frame_duration`](Self::frame_duration) are rejected. The floor is 1200 @@ -113,8 +139,13 @@ pub struct Settings { /// Enable Opus discontinuous transmission during silence. pub dtx: bool, /// Encoded frame duration. Opus accepts 2.5 / 5 / 10 / 20 / 40 / 60 ms. - /// PCM accepts any duration containing a whole number of samples. + /// PCM accepts any duration containing a whole number of samples. AAC frames + /// are 1024 samples, so it accepts the duration that rounds to that at + /// [`sample_rate`](Self::sample_rate), which [`from_input`](Self::from_input) + /// fills in. pub frame_duration: Duration, + /// Which encoder implementation to use. + pub kind: Kind, } impl Settings { @@ -127,6 +158,7 @@ impl Settings { bitrate: None, dtx: false, frame_duration: Duration::from_millis(20), + kind: Kind::Auto, } } @@ -134,13 +166,72 @@ impl Settings { pub fn from_input(codec: Codec, input: &Input) -> Self { let sample_rate = match codec { Codec::Opus => opus::pick_rate(input.sample_rate), - Codec::Pcm => input.sample_rate, + Codec::Pcm | Codec::Aac => input.sample_rate, + }; + let defaults = Self::new(sample_rate, input.layout); + let frame_duration = match codec { + Codec::Aac => aac_frame_duration(sample_rate), + Codec::Opus | Codec::Pcm => defaults.frame_duration, }; Self { codec, - sample_rate, - layout: input.layout, - ..Self::default() + frame_duration, + ..defaults + } + } + + /// Check the settings against the codec, returning its frame size. + /// + /// Codec rules live here rather than in a backend, so every backend of a + /// codec refuses the same settings. + fn frame_size(&self) -> Result { + self.layout.validate()?; + let (rate, channels) = (self.sample_rate, self.layout.channels()); + + match self.codec { + Codec::Opus => { + opus::validate_rate(rate)?; + if !matches!(self.layout, Layout::Mono | Layout::Stereo) { + return Err(Error::Unsupported("opus requires a named mono or stereo layout".into())); + } + opus::frame_size(rate, self.frame_duration) + } + Codec::Pcm => { + if self.bitrate.is_some() { + return Err(Error::Unsupported( + "pcm bitrate is fixed; leave Settings::bitrate unset".into(), + )); + } + if self.dtx { + return Err(Error::Unsupported( + "pcm does not support discontinuous transmission".into(), + )); + } + if rate == 0 { + return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); + } + let frame_size = pcm::frame_size(rate, self.frame_duration)?; + pcm::frame_bytes(frame_size, channels)?; + pcm::bitrate(rate, channels)?; + Ok(frame_size) + } + Codec::Aac => { + if self.dtx { + return Err(Error::Unsupported( + "aac does not support discontinuous transmission".into(), + )); + } + aac_config(self)?; + let frames = (self.frame_duration.as_nanos() * u128::from(rate) + 500_000_000) / 1_000_000_000; + if frames != AAC_FRAME_SIZE as u128 { + return Err(Error::Unsupported(format!( + "aac frames are {AAC_FRAME_SIZE} samples, {:?} at {rate} Hz (got {:?})", + aac_frame_duration(rate), + self.frame_duration + ))); + } + Ok(AAC_FRAME_SIZE) + } } } } @@ -151,6 +242,52 @@ impl Default for Settings { } } +/// One AAC frame at `sample_rate`, to the nearest nanosecond. +fn aac_frame_duration(sample_rate: u32) -> Duration { + if sample_rate == 0 { + return Duration::ZERO; + } + let rate = u64::from(sample_rate); + Duration::from_nanos((AAC_FRAME_SIZE as u64 * 1_000_000_000 + rate / 2) / rate) +} + +/// The AudioSpecificConfig fields for AAC-LC at the settings' rate and layout. +/// +/// Only layouts with a channelConfiguration are accepted, since synthesizing +/// one from a bare count would mislabel the rest: config 3 is 3.0 where the +/// count's default layout is 2.1, and 6.1 has no config the encoder writes. +/// 7.1 takes config 7, the one every decoder reads as eight channels. +fn aac_config(settings: &Settings) -> Result { + let layout = settings.layout; + if !matches!( + layout, + Layout::Mono + | Layout::Stereo + | Layout::ThreePointZero + | Layout::FourPointZero + | Layout::FivePointZero + | Layout::FivePointOne + | Layout::SevenPointOne + ) { + return Err(Error::Unsupported(format!( + "aac has no channelConfiguration for {layout:?}; use mono, stereo, 3.0, 4.0, 5.0, 5.1, or 7.1" + ))); + } + + let sample_rate = settings.sample_rate; + if !(1..=AAC_MAX_SAMPLE_RATE).contains(&sample_rate) { + return Err(Error::Unsupported(format!( + "aac sample rate must be between 1 and {AAC_MAX_SAMPLE_RATE} Hz (got {sample_rate})" + ))); + } + + Ok(moq_mux::codec::aac::Config { + profile: AAC_LC, + sample_rate, + channel_count: layout.channels(), + }) +} + /// Audio encoder over codec-sized interleaved `f32` PCM. /// /// Build one with [`Encoder::new`], feed full PCM frames via @@ -158,38 +295,16 @@ impl Default for Settings { /// [`finish`](Self::finish). Publish every packet either call returns and apply /// the terminal [`Finish::discard_padding`] when the container supports it. pub struct Encoder { - backend: Backend, + backend: Box, settings: Settings, - /// Codec sample rate. - codec_rate: u32, - /// Codec channel count. - codec_channels: u32, - /// Current libopus target bitrate. - bitrate: u64, - /// Encoder lookahead expressed in the OpusHead 48 kHz timebase. - pre_skip: u16, - /// Encoder lookahead in codec-rate frames. - lookahead: usize, frame_size: usize, + /// The catalog description, synthesized from the settings at construction so + /// the rendition can be registered before the first packet exists. + description: Option, /// Whether input has reached the codec, since a fresh encoder owes no drain. started: bool, } -enum Backend { - Opus(Opus), - Pcm, -} - -struct Opus { - inner: *mut OpusEncoder, - scratch: Vec, -} - -// SAFETY: OpusEncoder is heap-allocated state owned exclusively by this -// struct; libopus encoder methods take a single &mut, so a unique owner is -// allowed to move it across threads. -unsafe impl Send for Opus {} - /// Packets emitted by [`Encoder::finish`] and the decoded padding at their end. pub struct Finish { packets: Vec, @@ -214,158 +329,40 @@ impl Finish { } impl Encoder { - /// Open an encoder for `settings`. + /// Open an encoder for `settings`, refusing a codec no backend on this host + /// encodes. pub fn new(settings: &Settings) -> Result { - settings.layout.validate()?; - match settings.codec { - Codec::Opus => Self::new_opus(settings.clone()), - Codec::Pcm => Self::new_pcm(settings.clone()), - } - } - - fn new_opus(settings: Settings) -> Result { - let codec_rate = settings.sample_rate; - opus::validate_rate(codec_rate)?; - - let codec_channels = settings.layout.channels(); - if !matches!(settings.layout, Layout::Mono | Layout::Stereo) { - return Err(Error::Unsupported("opus requires a named mono or stereo layout".into())); - } - let channels = opus::validate_channels(codec_channels)?; + let frame_size = settings.frame_size()?; + let backend = backend::open(settings)?; - let frame_size = opus::frame_size(codec_rate, settings.frame_duration)?; - - let mut err = 0i32; - // SAFETY: out-pointer `err` is valid; inner is checked for null below. - let inner = unsafe { opus_encoder_create(codec_rate as i32, channels, OPUS_APPLICATION_AUDIO, &mut err) }; - if err != OPUS_OK || inner.is_null() { - return Err(opus::error(err, "opus_encoder_create")); - } - - let configured = Self::configure_opus(inner, &settings, codec_rate, codec_channels, frame_size); - let (bitrate, lookahead, pre_skip) = match configured { - Ok(configured) => configured, - Err(err) => { - // SAFETY: `inner` was created above and not yet handed out. - unsafe { opus_encoder_destroy(inner) }; - return Err(err); + let description = match settings.codec { + Codec::Opus => { + // OpusHead carries the lookahead in the 48 kHz timebase. + let lookahead = backend.delay() as u64; + let pre_skip = u16::try_from((lookahead * 48_000) / u64::from(settings.sample_rate)) + .map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in OpusHead")))?; + let head = moq_mux::codec::opus::Config::new(settings.sample_rate, settings.layout.channels()) + .with_pre_skip(pre_skip) + .encode() + .map_err(moq_mux::Error::from)?; + Some(head) } + Codec::Aac => Some(aac_config(settings)?.encode()), + Codec::Pcm => None, }; Ok(Self { - backend: Backend::Opus(Opus { - inner, - scratch: vec![0u8; MAX_PACKET_BYTES], - }), - settings, - codec_rate, - codec_channels, - bitrate, - pre_skip, - lookahead, + backend, + settings: settings.clone(), frame_size, + description, started: false, }) } - fn new_pcm(settings: Settings) -> Result { - if settings.bitrate.is_some() { - return Err(Error::Unsupported( - "pcm bitrate is fixed; leave Settings::bitrate unset".into(), - )); - } - if settings.dtx { - return Err(Error::Unsupported( - "pcm does not support discontinuous transmission".into(), - )); - } - - let codec_rate = settings.sample_rate; - if codec_rate == 0 { - return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); - } - - let codec_channels = settings.layout.channels(); - if codec_channels == 0 { - return Err(Error::Unsupported("pcm channel count must be greater than zero".into())); - } - let frame_size = pcm::frame_size(codec_rate, settings.frame_duration)?; - pcm::frame_bytes(frame_size, codec_channels)?; - let bitrate = pcm::bitrate(codec_rate, codec_channels)?; - Ok(Self { - backend: Backend::Pcm, - settings, - codec_rate, - codec_channels, - bitrate, - pre_skip: 0, - lookahead: 0, - frame_size, - started: false, - }) - } - - fn configure_opus( - inner: *mut OpusEncoder, - settings: &Settings, - codec_rate: u32, - codec_channels: u32, - frame_size: usize, - ) -> Result<(u64, usize, u16), Error> { - if let Some(bitrate) = settings.bitrate { - Self::set_opus_bitrate(inner, codec_channels, bitrate.as_bps(), codec_rate, frame_size)?; - } - Self::set_opus_ctl(inner, OPUS_SET_DTX_REQUEST, i32::from(settings.dtx), "OPUS_SET_DTX")?; - - let bitrate = Self::get_opus_ctl(inner, OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE")?; - let bitrate = u64::try_from(bitrate) - .map_err(|_| Error::Unsupported(format!("Opus reported negative bitrate {bitrate}")))?; - let lookahead = Self::get_opus_ctl(inner, OPUS_GET_LOOKAHEAD_REQUEST, "OPUS_GET_LOOKAHEAD")?; - let lookahead = u64::try_from(lookahead) - .map_err(|_| Error::Unsupported(format!("Opus reported negative lookahead {lookahead}")))?; - let pre_skip = u16::try_from((lookahead * 48_000) / codec_rate as u64) - .map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in OpusHead")))?; - let lookahead = usize::try_from(lookahead) - .map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in memory")))?; - - Ok((bitrate, lookahead, pre_skip)) - } - - fn set_opus_bitrate( - inner: *mut OpusEncoder, - channels: u32, - bitrate: u64, - codec_rate: u32, - frame_size: usize, - ) -> Result<(), Error> { - let max = 300_000 * channels as u64; - let min = opus::bitrate_floor(codec_rate, frame_size).max(500); - if !(min..=max).contains(&bitrate) { - return Err(Error::Unsupported(format!( - "Opus bitrate must be between {min} and {max} bits per second for {channels} channel(s) at {frame_size} samples, got {bitrate}" - ))); - } - Self::set_opus_ctl(inner, OPUS_SET_BITRATE_REQUEST, bitrate as i32, "OPUS_SET_BITRATE") - } - - fn set_opus_ctl(inner: *mut OpusEncoder, request: i32, value: i32, name: &'static str) -> Result<(), Error> { - // SAFETY: `inner` owns a live encoder and each request here expects one i32. - let rc = unsafe { opus_encoder_ctl_impl(inner, request, varargs![value]) }; - if rc != OPUS_OK { - return Err(opus::error(rc, name)); - } - Ok(()) - } - - fn get_opus_ctl(inner: *mut OpusEncoder, request: i32, name: &'static str) -> Result { - let mut value = 0; - // SAFETY: `inner` owns a live encoder and each request here expects one - // valid mutable i32 output. - let rc = unsafe { opus_encoder_ctl_impl(inner, request, varargs![&mut value]) }; - if rc != OPUS_OK { - return Err(opus::error(rc, name)); - } - Ok(value) + /// The encoder backend name in use, e.g. `"libopus"`. + pub fn name(&self) -> &str { + self.backend.name() } /// The encoder settings, including the latest accepted runtime bitrate. @@ -382,13 +379,13 @@ impl Encoder { /// Sample rate the codec actually runs at, which is /// [`Settings::sample_rate`]. pub fn codec_rate(&self) -> u32 { - self.codec_rate + self.settings.sample_rate } /// Channel count the codec actually runs at, which is /// [`Settings::layout`]'s channel count. pub fn codec_channels(&self) -> u32 { - self.codec_channels + self.settings.layout.channels() } /// Number of samples per channel the codec consumes per call to @@ -399,23 +396,21 @@ impl Encoder { /// Current target bitrate. pub fn bitrate(&self) -> moq_net::bandwidth::Rate { - moq_net::bandwidth::Rate::from_bps(self.bitrate) + moq_net::bandwidth::Rate::from_bps(self.backend.bitrate()) } - /// Retune the live Opus encoder to `bitrate`. + /// Retune the live encoder to `bitrate`. + /// + /// # Errors + /// + /// Returns [`Error::Unsupported`] when the codec's rate is fixed (PCM) or the + /// backend can't change it mid-stream. The encoder keeps running at its + /// opening rate, so a caller driving a control loop should stop adapting + /// rather than stop encoding. pub fn set_bitrate(&mut self, bitrate: moq_net::bandwidth::Rate) -> Result<(), Error> { - let Backend::Opus(opus) = &mut self.backend else { - return Err(Error::Unsupported("pcm bitrate is fixed".into())); - }; - if bitrate.as_bps() != self.bitrate { - Self::set_opus_bitrate( - opus.inner, - self.codec_channels, - bitrate.as_bps(), - self.codec_rate, - self.frame_size, - )?; - self.bitrate = bitrate.as_bps(); + let previous = self.backend.bitrate(); + self.backend.set_bitrate(bitrate.as_bps())?; + if bitrate.as_bps() != previous { self.settings.bitrate = Some(bitrate); } Ok(()) @@ -423,11 +418,7 @@ impl Encoder { /// Drop all codec history so a later epoch cannot emit audio from this one. pub(super) fn reset(&mut self) { - if let Backend::Opus(opus) = &mut self.backend { - // SAFETY: `inner` owns a live encoder and OPUS_RESET_STATE takes no arguments. - let rc = unsafe { opus_encoder_ctl_impl(opus.inner, OPUS_RESET_STATE, varargs![]) }; - debug_assert_eq!(rc, OPUS_OK, "OPUS_RESET_STATE failed with {rc}"); - } + self.backend.reset(); self.started = false; } @@ -436,47 +427,34 @@ impl Encoder { self.started } + /// Codec priming the catalog can't signal, in codec-rate frames, which the + /// producer folds into its timestamps instead. + /// + /// Opus declares its lookahead as OpusHead pre-skip, which the decoder trims, + /// so nothing is folded. An AudioSpecificConfig has no such field, so each + /// AAC packet is stamped that much earlier and the priming lands before the + /// first input sample rather than delaying it. + pub(super) fn folded_delay(&self) -> usize { + match self.settings.codec { + Codec::Aac => self.backend.delay(), + Codec::Opus | Codec::Pcm => 0, + } + } + /// Encode one frame of interleaved `f32` PCM at [`codec_rate`](Self::codec_rate). /// /// `pcm.len()` must equal `frame_size() * codec_channels()`. The /// [`Producer`](super::Producer) handles format conversion and resampling /// before calling this; for direct use, the caller does the same. pub fn encode(&mut self, pcm: &[f32]) -> Result { - let expected = self.frame_size * self.codec_channels as usize; + let expected = self.frame_size * self.codec_channels() as usize; if pcm.len() != expected { return Err(Error::Misaligned { got: std::mem::size_of_val(pcm), expected: expected * std::mem::size_of::(), }); } - let encoded = match &mut self.backend { - Backend::Opus(opus) => { - // SAFETY: `inner` owns a live OpusEncoder; pcm and scratch slices - // are bounded by the lengths we pass. - let n = unsafe { - opus_encode_float( - opus.inner, - pcm.as_ptr(), - self.frame_size as i32, - opus.scratch.as_mut_ptr(), - opus.scratch.len() as i32, - ) - }; - if n < 0 { - return Err(crate::opus::error(n, "opus_encode_float")); - } - let payload = Bytes::copy_from_slice(&opus.scratch[..n as usize]); - let activity = crate::opus::activity(&payload, false); - Encoded { payload, activity } - } - Backend::Pcm => { - let mut payload = Vec::with_capacity(std::mem::size_of_val(pcm)); - for sample in pcm { - payload.extend_from_slice(&sample.to_le_bytes()); - } - Encoded::new(payload.into()) - } - }; + let encoded = self.backend.encode(pcm)?; self.started = true; Ok(encoded) } @@ -496,7 +474,7 @@ impl Encoder { /// Same drain as [`finish`](Self::finish), without consuming the encoder. pub(super) fn drain(&mut self, pcm: &[f32]) -> Result { - let channels = self.codec_channels as usize; + let channels = self.codec_channels() as usize; let frame_samples = self.frame_size * channels; if pcm.len() > frame_samples || !pcm.len().is_multiple_of(channels) { return Err(Error::Misaligned { @@ -529,7 +507,8 @@ impl Encoder { }); } - let drain = self.lookahead.saturating_sub(padding); + let lookahead = self.backend.delay(); + let drain = lookahead.saturating_sub(padding); let silence = vec![0.0; frame_samples]; for _ in 0..drain.div_ceil(self.frame_size) { packets.push(self.encode(&silence)?); @@ -538,7 +517,7 @@ impl Encoder { let discard_padding = packets .len() .saturating_mul(self.frame_size) - .saturating_sub(self.lookahead) + .saturating_sub(lookahead) .saturating_sub(source_frames); Ok(Finish { @@ -549,46 +528,27 @@ impl Encoder { /// hang catalog entry describing this encoder's output stream. pub fn catalog(&self) -> hang::catalog::AudioConfig { - match self.settings.codec { - Codec::Opus => { - // `codec_channels` is validated to mono/stereo at encoder construction, - // so the OpusHead (channel mapping family 0) always encodes. - let head = moq_mux::codec::opus::Config::new(self.codec_rate, self.codec_channels) - .with_pre_skip(self.pre_skip) - .encode() - .expect("opus encoder channels validated to mono/stereo"); - - let mut config = hang::catalog::AudioConfig::new( - hang::catalog::AudioCodec::Opus, - self.codec_rate, - self.codec_channels, - ); - config.bitrate = self.settings.bitrate.map(moq_net::bandwidth::Rate::as_bps); - config.description = Some(head); - config.container = hang::catalog::Container::Legacy; - config - } - Codec::Pcm => { - let mut config = hang::catalog::AudioConfig::new( - hang::catalog::AudioCodec::Pcm, - self.codec_rate, - self.codec_channels, - ); - config.bitrate = Some( - pcm::bitrate(self.codec_rate, self.codec_channels) - .expect("pcm encoder bitrate validated at construction"), - ); - config.container = hang::catalog::Container::Legacy; - config - } - } - } -} + let (rate, channels) = (self.codec_rate(), self.codec_channels()); + let (codec, bitrate): (hang::catalog::AudioCodec, _) = match self.settings.codec { + Codec::Opus => ( + hang::catalog::AudioCodec::Opus, + self.settings.bitrate.map(moq_net::bandwidth::Rate::as_bps), + ), + Codec::Pcm => ( + hang::catalog::AudioCodec::Pcm, + Some(pcm::bitrate(rate, channels).expect("pcm encoder bitrate validated at construction")), + ), + Codec::Aac => ( + hang::catalog::AAC { profile: AAC_LC }.into(), + self.settings.bitrate.map(moq_net::bandwidth::Rate::as_bps), + ), + }; -impl Drop for Opus { - fn drop(&mut self) { - // SAFETY: `inner` is a live OpusEncoder that nothing else aliases. - unsafe { opus_encoder_destroy(self.inner) }; + let mut config = hang::catalog::AudioConfig::new(codec, rate, channels); + config.bitrate = bitrate; + config.description = self.description.clone(); + config.container = hang::catalog::Container::Legacy; + config } } @@ -609,11 +569,11 @@ mod tests { out } - fn opus_inner(encoder: &Encoder) -> *mut OpusEncoder { - let Backend::Opus(opus) = &encoder.backend else { - panic!("expected Opus encoder"); - }; - opus.inner + /// The published `Encoder` was unwind safe before it boxed a backend; keep it so. + #[test] + fn encoder_is_unwind_safe() { + fn assert_unwind_safe() {} + assert_unwind_safe::(); } #[test] @@ -675,7 +635,6 @@ mod tests { let desc = cfg.description.expect("OpusHead should be present"); assert_eq!(desc.len(), 19); let head = moq_mux::codec::opus::Config::parse(&mut desc.as_ref()).unwrap(); - assert_eq!(head.pre_skip, enc.pre_skip); assert_eq!(head.pre_skip, 312); } @@ -688,7 +647,7 @@ mod tests { let first = dec.decode(&enc.encode(&frame).unwrap().payload).unwrap(); assert_eq!( first.samples.len(), - (enc.frame_size() - enc.pre_skip as usize) * enc.codec_channels() as usize + (enc.frame_size() - enc.backend.delay()) * enc.codec_channels() as usize ); let second = dec.decode(&enc.encode(&frame).unwrap().payload).unwrap(); @@ -757,15 +716,6 @@ mod tests { enc.set_bitrate(moq_net::bandwidth::Rate::from_bps(32_000)).unwrap(); assert_eq!(enc.bitrate(), moq_net::bandwidth::Rate::from_bps(32_000)); assert_eq!(enc.settings().bitrate, Some(moq_net::bandwidth::Rate::from_bps(32_000))); - assert_eq!( - Encoder::get_opus_ctl( - opus_inner(&enc), - unsafe_libopus::OPUS_GET_BITRATE_REQUEST, - "OPUS_GET_BITRATE" - ) - .unwrap(), - 32_000 - ); } #[test] @@ -777,20 +727,6 @@ mod tests { assert_eq!(enc.bitrate(), original); } - #[test] - fn opus_applies_dtx_control() { - let enc = Encoder::new(&Settings { - dtx: true, - ..Settings::default() - }) - .unwrap(); - - assert_eq!( - Encoder::get_opus_ctl(opus_inner(&enc), unsafe_libopus::OPUS_GET_DTX_REQUEST, "OPUS_GET_DTX").unwrap(), - 1 - ); - } - #[test] fn codec_roundtrips_as_str() { assert_eq!(Codec::Opus.as_str(), "opus"); @@ -799,15 +735,20 @@ mod tests { assert_eq!(Codec::Pcm.as_str(), "pcm"); assert_eq!(Codec::Pcm.to_string(), "pcm"); assert_eq!("pcm".parse::().unwrap(), Codec::Pcm); - assert!("aac".parse::().is_err()); + assert_eq!(Codec::Aac.as_str(), "aac"); + assert_eq!(Codec::Aac.to_string(), "aac"); + assert_eq!("aac".parse::().unwrap(), Codec::Aac); + assert!("mp3".parse::().is_err()); } #[test] fn settings_fix_the_codec_rate() { let enc = Encoder::new(&Settings::new(24_000, Layout::Mono)).unwrap(); assert_eq!(enc.codec_rate(), 24_000); - assert_eq!(enc.catalog().sample_rate, 24_000); - assert_eq!(enc.pre_skip, 312); + let catalog = enc.catalog(); + assert_eq!(catalog.sample_rate, 24_000); + let head = moq_mux::codec::opus::Config::parse(&mut catalog.description.unwrap().as_ref()).unwrap(); + assert_eq!(head.pre_skip, 312); } #[test] @@ -826,6 +767,31 @@ mod tests { assert_eq!(output.samples, input); } + /// A PCM catalog names only a count, and 3 or 4 channels decode as 2.1 or + /// quad, so 3.0 and 4.0 are refused; discrete channels still pass through. + #[test] + fn pcm_refuses_layouts_its_count_cannot_name() { + for layout in [Layout::ThreePointZero, Layout::FourPointZero] { + let err = Encoder::new(&Settings { + codec: Codec::Pcm, + ..Settings::new(48_000, layout) + }); + assert!(matches!(err, Err(Error::Unsupported(_))), "{layout:?}"); + } + + for layout in [Layout::TwoPointOne, Layout::Quad, Layout::Discrete(3)] { + let mut enc = Encoder::new(&Settings { + codec: Codec::Pcm, + ..Settings::new(48_000, layout) + }) + .unwrap(); + let mut dec = Decoder::new(&enc.catalog(), &DecodeConfig::default()).unwrap(); + let input = sine(440.0, enc.codec_rate(), enc.codec_channels(), enc.frame_size()); + let output = dec.decode(&enc.encode(&input).unwrap().payload).unwrap(); + assert_eq!(output.samples, input, "{layout:?}"); + } + } + #[test] fn pcm_catalog_declares_fixed_bitrate() { let enc = Encoder::new(&Settings { @@ -883,8 +849,10 @@ mod tests { assert!(matches!(Encoder::new(&settings), Err(Error::Unsupported(_)))); } + /// The catalog carries only a count, so a discrete layout comes back as the + /// count's default one, with the samples untouched. #[test] - fn pcm_preserves_discrete_multichannel_layout() { + fn pcm_passes_discrete_multichannel_samples_through() { let settings = Settings { codec: Codec::Pcm, ..Settings::new(48_000, Layout::Discrete(3)) @@ -895,7 +863,7 @@ mod tests { let input = [0.1, 0.2, 0.3].repeat(encoder.frame_size()); let output = decoder.decode(&encoder.encode(&input).unwrap().payload).unwrap(); - assert_eq!(decoder.layout(), Layout::Discrete(3)); + assert_eq!(decoder.layout(), Layout::TwoPointOne); assert_eq!(output.samples, input); } @@ -904,4 +872,129 @@ mod tests { let settings = Settings::new(48_000, Layout::Discrete(2)); assert!(matches!(Encoder::new(&settings), Err(Error::Unsupported(_)))); } + + fn aac(layout: Layout) -> Settings { + Settings::from_input(Codec::Aac, &Input::new(48_000, layout)) + } + + /// Open `settings` on the test stub, since this host has no AAC encoder. + fn stub(settings: &Settings) -> Result { + let _stub = backend::stub::install(); + Encoder::new(settings) + } + + /// Without the stub, the public constructor sees the real tiers and refuses. + #[test] + fn aac_is_refused_without_an_encoder() { + let err = Encoder::new(&aac(Layout::Stereo)) + .err() + .expect("no AAC encoder on this host"); + assert!(matches!(err, Error::Unsupported(_)), "{err}"); + } + + /// The ASC is synthesized from the settings, so it exists before any packet. + #[test] + fn aac_catalog_carries_the_synthesized_asc() { + let enc = stub(&aac(Layout::Stereo)).unwrap(); + assert_eq!(enc.name(), backend::stub::NAME); + assert_eq!(enc.frame_size(), 1024); + + let catalog = enc.catalog(); + assert_eq!(catalog.codec, hang::catalog::AAC { profile: 2 }.into()); + assert_eq!(catalog.codec.to_string(), "mp4a.40.2"); + assert_eq!(catalog.sample_rate, 48_000); + assert_eq!(catalog.channel_count, 2); + assert_eq!(catalog.container, hang::catalog::Container::Legacy); + // AAC-LC (2), 48 kHz (index 3), stereo (config 2). + assert_eq!(catalog.description.as_deref(), Some(&[0x11, 0x90][..])); + } + + #[test] + fn aac_takes_the_layouts_with_a_channel_configuration() { + for (layout, config) in [ + (Layout::Mono, 1), + (Layout::Stereo, 2), + (Layout::ThreePointZero, 3), + (Layout::FourPointZero, 4), + (Layout::FivePointZero, 5), + (Layout::FivePointOne, 6), + (Layout::SevenPointOne, 7), + ] { + let catalog = stub(&aac(layout)).unwrap().catalog(); + let description = catalog.description.unwrap(); + assert_eq!(description[1] >> 3 & 0xF, config, "{layout:?}"); + assert_eq!(catalog.channel_count, layout.channels(), "{layout:?}"); + } + + for layout in [ + Layout::TwoPointOne, + Layout::Quad, + Layout::SixPointOne, + Layout::Discrete(2), + ] { + assert!(matches!(stub(&aac(layout)), Err(Error::Unsupported(_))), "{layout:?}"); + } + } + + /// AAC frames are 1024 samples however the duration is spelled. + #[test] + fn aac_frame_duration_is_the_codecs() { + assert_eq!(aac(Layout::Stereo).frame_duration, Duration::from_nanos(21_333_333)); + let settings = Settings { + frame_duration: Duration::from_micros(21_333), + ..aac(Layout::Stereo) + }; + assert_eq!(stub(&settings).unwrap().frame_size(), 1024); + + let settings = Settings { + frame_duration: Duration::from_millis(20), + ..aac(Layout::Stereo) + }; + let err = stub(&settings).err().expect("20 ms is 960 samples"); + assert!(err.to_string().contains("1024"), "{err}"); + } + + #[test] + fn aac_refuses_dtx() { + let settings = Settings { + dtx: true, + ..aac(Layout::Stereo) + }; + assert!(matches!(stub(&settings), Err(Error::Unsupported(_)))); + } + + /// A backend that can't retune keeps its opening rate. + #[test] + fn fixed_rate_backend_keeps_its_opening_rate() { + let mut enc = stub(&Settings { + bitrate: Some(moq_net::bandwidth::Rate::from_bps(96_000)), + ..aac(Layout::Stereo) + }) + .unwrap(); + + let err = enc.set_bitrate(moq_net::bandwidth::Rate::from_bps(64_000)); + assert!(matches!(err, Err(Error::Unsupported(_)))); + assert_eq!(enc.bitrate(), moq_net::bandwidth::Rate::from_bps(96_000)); + assert_eq!(enc.settings().bitrate, Some(moq_net::bandwidth::Rate::from_bps(96_000))); + assert_eq!(enc.catalog().bitrate, Some(96_000)); + } + + /// The drain pushes the encoder delay out through whole silent frames. + #[test] + fn aac_finish_drains_the_encoder_delay() { + let mut enc = stub(&aac(Layout::Mono)).unwrap(); + assert_eq!(enc.folded_delay(), backend::stub::DELAY); + enc.encode(&[0.0; 1024]).unwrap(); + + // 2112 frames of delay take three 1024-frame packets. + let finish = enc.finish(&[]).unwrap(); + assert_eq!(finish.packets().len(), 3); + assert_eq!(finish.discard_padding(), 3 * 1024 - backend::stub::DELAY); + } + + /// Opus signals its lookahead as pre-skip, so the producer folds none of it. + #[test] + fn opus_folds_no_delay() { + assert_eq!(Encoder::new(&Settings::default()).unwrap().folded_delay(), 0); + } } diff --git a/rs/moq-audio/src/encode/mod.rs b/rs/moq-audio/src/encode/mod.rs index 44da8b64f34..f7122bd18c2 100644 --- a/rs/moq-audio/src/encode/mod.rs +++ b/rs/moq-audio/src/encode/mod.rs @@ -1,6 +1,8 @@ //! Encode raw PCM and publish it as a moq audio track. //! -//! The output codec is selected via [`Codec`]. +//! The output codec is selected via [`Codec`], and the implementation behind it +//! via [`Kind`]: a platform encoder when the host has one, software otherwise. +//! AAC has no software encoder, so a host without a platform one refuses it. //! //! Entry points, high to low level: //! - `publish_capture` captures a microphone (or system audio) and publishes @@ -15,6 +17,7 @@ //! `publish_capture` is unlinked above because it only exists with the `capture` //! feature, so a default-feature rustdoc build has nothing to link to. +mod backend; mod encoded; mod encoder; mod producer; @@ -23,7 +26,7 @@ mod producer; mod capture; pub use encoded::Encoded; -pub use encoder::{Codec, Encoder, Finish, Input, Settings}; +pub use encoder::{Codec, Encoder, Finish, Input, Kind, Settings}; pub use producer::{Options, Producer}; #[cfg(feature = "capture")] diff --git a/rs/moq-audio/src/encode/producer.rs b/rs/moq-audio/src/encode/producer.rs index dcc3d1c9569..742f5636793 100644 --- a/rs/moq-audio/src/encode/producer.rs +++ b/rs/moq-audio/src/encode/producer.rs @@ -10,7 +10,7 @@ use moq_net::Timestamp; use super::encoded::Encoded; use super::encoder::{Encoder, Input, Settings}; -use crate::resample::{Resampler, remix, validate_remix}; +use crate::resample::{Remix, Resampler}; use crate::{Activity, Error, Frame}; /// Encode and publication policy for [`Producer`]. @@ -64,6 +64,8 @@ impl Default for Options { pub struct Producer { encoder: Encoder, input: Input, + /// Converts the input layout to the codec's, when they differ. + remix: Option, resampler: Option, track: moq_mux::container::Producer, _ext: std::marker::PhantomData E>, @@ -140,7 +142,9 @@ impl Reserved { /// Separate from [`encode`](Self::encode), which cannot fail, so a layout the /// codec rejects leaves the reservation intact for another input. pub(crate) fn register(&mut self, input: Input, options: &Options) -> Result { - validate_remix(input.layout, options.settings.layout)?; + let remix = (input.layout != options.settings.layout) + .then(|| Remix::new(input.layout, options.settings.layout)) + .transpose()?; let encoder = Encoder::new(&options.settings)?; let resampler = if input.sample_rate == encoder.codec_rate() { @@ -163,6 +167,7 @@ impl Reserved { Ok(Registered { encoder, input, + remix, resampler, }) } @@ -172,6 +177,7 @@ impl Reserved { Producer { encoder: registered.encoder, input: registered.input, + remix: registered.remix, resampler: registered.resampler, track: self.track, _ext: self._ext, @@ -193,6 +199,7 @@ impl Reserved { pub(crate) struct Registered { encoder: Encoder, input: Input, + remix: Option, resampler: Option, } @@ -337,7 +344,10 @@ impl Producer { let input = &self.input; let (format, channels) = (input.format, input.layout.channels()); let pcm = format.as_interleaved_f32(frame.data.as_ref(), channels)?; - let pcm = remix(&pcm, input.layout, self.encoder.settings().layout)?; + let pcm = match &self.remix { + Some(remix) => remix.process(&pcm), + None => pcm.into_owned(), + }; let pcm: Vec = match self.resampler.as_mut() { Some(r) => r.process(&pcm, frame.timestamp)?, None => pcm, @@ -356,7 +366,12 @@ impl Producer { let chunk: Vec = self.pending.drain(..frame_samples).collect(); let packet = self.encoder.encode(&chunk)?; - let timestamp = Self::timestamp(epoch_us, self.frames_produced, self.encoder.codec_rate())?; + let timestamp = Self::timestamp( + epoch_us, + self.frames_produced, + self.encoder.folded_delay(), + self.encoder.codec_rate(), + )?; self.frames_produced += self.encoder.frame_size() as u64; self.activity = packet.activity; Self::publish(&mut self.track, packet, timestamp)?; @@ -366,10 +381,18 @@ impl Producer { Ok(()) } - /// PTS of the next frame: the epoch plus the samples emitted since it. - fn timestamp(epoch_us: u64, frames_produced: u64, codec_rate: u32) -> Result { - let offset_us = (frames_produced * 1_000_000) / codec_rate as u64; - Ok(Timestamp::from_micros(epoch_us + offset_us)?) + /// PTS of the frame `frames` samples past the epoch, stamped `delay` samples + /// earlier to fold in codec priming the catalog can't signal. + /// + /// Priming that would land before a zero epoch is stamped at zero instead: it + /// decodes to the codec's warm-up rather than to input, so only its spacing is + /// lost. + fn timestamp(epoch_us: u64, frames: u64, delay: usize, codec_rate: u32) -> Result { + let frames = i128::from(frames) - delay as i128; + let offset_us = (frames * 1_000_000).div_euclid(i128::from(codec_rate)); + let micros = (i128::from(epoch_us) + offset_us).max(0); + let micros = u64::try_from(micros).map_err(|_| moq_net::TimeOverflow)?; + Ok(Timestamp::from_micros(micros)?) } fn publish( @@ -464,8 +487,10 @@ impl Producer { let codec_rate = self.encoder.codec_rate(); let channels = self.encoder.codec_channels() as usize; let source_frames = self.pending.len() / channels; - let start = Self::timestamp(epoch_us, self.frames_produced, codec_rate)?; - let end = Self::timestamp(epoch_us, self.frames_produced + source_frames as u64, codec_rate)?; + let delay = self.encoder.folded_delay(); + let start = Self::timestamp(epoch_us, self.frames_produced, delay, codec_rate)?; + // The source ends where it ends: priming only moves the packets carrying it. + let end = Self::timestamp(epoch_us, self.frames_produced + source_frames as u64, 0, codec_rate)?; let finish = self.encoder.drain(&self.pending)?; let discard_padding = finish.discard_padding(); let packets = finish.into_packets(); @@ -483,7 +508,7 @@ impl Producer { )?; } else { for packet in packets { - let timestamp = Self::timestamp(epoch_us, self.frames_produced, codec_rate)?; + let timestamp = Self::timestamp(epoch_us, self.frames_produced, delay, codec_rate)?; self.activity = packet.activity; Self::publish(&mut self.track, packet, timestamp)?; self.frames_produced += frame_size as u64; @@ -888,6 +913,50 @@ mod tests { assert_eq!(pts, vec![1_000_000]); } + /// AAC can't signal its encoder delay, so each packet is stamped that much + /// earlier and the first input sample still decodes at the epoch. + #[tokio::test] + async fn aac_folds_the_encoder_delay_into_timestamps() { + async fn pts(epoch_us: u64) -> Vec { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let consumer = broadcast.consume(); + + let input = Input::new(48_000, Layout::Mono); + let options = Options { + track: Some("audio".to_string()), + settings: Settings::from_input(crate::encode::Codec::Aac, &input), + ..Options::default() + }; + let stub = crate::encode::backend::stub::install(); + let mut producer = Producer::new(&mut broadcast, catalog, input, &options).unwrap(); + drop(stub); + + let track = consumer + .track("audio") + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_max_age(Duration::from_secs(1))) + .await + .unwrap(); + let mut reader = moq_mux::container::Consumer::new( + track, + moq_mux::container::legacy::Wire(moq_mux::container::Kind::Audio), + ); + + producer.write(&pcm_frame(&[0.1; 4 * 1024], epoch_us)).unwrap(); + let mut pts = Vec::new(); + for _ in 0..4 { + pts.push(reader.read().await.unwrap().expect("a packet").timestamp.as_micros()); + } + pts + } + + // 2112 frames of delay at 48 kHz is 44 ms, rounded down per packet. + assert_eq!(pts(1_000_000).await, vec![956_000, 977_333, 998_666, 1_020_000]); + // Priming before a zero epoch stamps at zero; the input still starts on time. + assert_eq!(pts(0).await, vec![0, 0, 0, 20_000]); + } + /// The encoder needs no correction for the resampler's own delay: it anchors /// the epoch to the first input timestamp and advances by emitted samples, /// while `Resampler::process` drops its startup silence rather than passing it diff --git a/rs/moq-audio/src/layout.rs b/rs/moq-audio/src/layout.rs index 0ff4d0d09b1..90373ed715f 100644 --- a/rs/moq-audio/src/layout.rs +++ b/rs/moq-audio/src/layout.rs @@ -1,6 +1,11 @@ use crate::Error; /// Speaker meaning and interleaving order for PCM channels. +/// +/// Named layouts interleave in the SMPTE/WAVE order (front left, front right, +/// center, LFE, back left, back right, back center, side left, side right), +/// keeping only the speakers the layout has. Every decoder reorders its codec's +/// native order into this one. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub enum Layout { @@ -10,11 +15,47 @@ pub enum Layout { #[default] Stereo, /// Channels with no declared speaker positions, in source order. + /// + /// Passes through unchanged but can't be remixed into another layout. Discrete(u32), + /// 2.1: left, right, LFE. + TwoPointOne, + /// 3.0: left, right, center. + ThreePointZero, + /// Quad: left, right, back left, back right. + Quad, + /// 4.0: left, right, center, back center. + FourPointZero, + /// 5.0: left, right, center, side left, side right. + FivePointZero, + /// 5.1: left, right, center, LFE, side left, side right. + FivePointOne, + /// 6.1: left, right, center, LFE, back center, side left, side right. + SixPointOne, + /// 7.1: left, right, center, LFE, back left, back right, side left, side right. + SevenPointOne, +} + +/// One speaker position, declared in the canonical interleaving order. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum Speaker { + FrontLeft, + FrontRight, + FrontCenter, + Lfe, + BackLeft, + BackRight, + BackCenter, + SideLeft, + SideRight, } impl Layout { - /// Infer today's conventional layout from a channel count. + /// The default layout for a channel count, by the WAVE convention: 1 is mono, + /// 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1. + /// + /// Any other count is [`Discrete`](Self::Discrete), since there is no + /// convention to take speaker positions from. pub fn from_channels(channels: u32) -> Result { match channels { 0 => Err(Error::Unsupported( @@ -22,6 +63,12 @@ impl Layout { )), 1 => Ok(Self::Mono), 2 => Ok(Self::Stereo), + 3 => Ok(Self::TwoPointOne), + 4 => Ok(Self::Quad), + 5 => Ok(Self::FivePointZero), + 6 => Ok(Self::FivePointOne), + 7 => Ok(Self::SixPointOne), + 8 => Ok(Self::SevenPointOne), channels => Ok(Self::Discrete(channels)), } } @@ -29,12 +76,40 @@ impl Layout { /// Number of interleaved channels in this layout. pub fn channels(self) -> u32 { match self { - Self::Mono => 1, - Self::Stereo => 2, Self::Discrete(channels) => channels, + layout => layout.speakers().map_or(0, <[_]>::len) as u32, } } + /// The speaker each channel feeds, in interleaved order, or `None` for a + /// discrete layout. + pub(crate) fn speakers(self) -> Option<&'static [Speaker]> { + use Speaker::*; + + Some(match self { + Self::Mono => &[FrontCenter], + Self::Stereo => &[FrontLeft, FrontRight], + Self::Discrete(_) => return None, + Self::TwoPointOne => &[FrontLeft, FrontRight, Lfe], + Self::ThreePointZero => &[FrontLeft, FrontRight, FrontCenter], + Self::Quad => &[FrontLeft, FrontRight, BackLeft, BackRight], + Self::FourPointZero => &[FrontLeft, FrontRight, FrontCenter, BackCenter], + Self::FivePointZero => &[FrontLeft, FrontRight, FrontCenter, SideLeft, SideRight], + Self::FivePointOne => &[FrontLeft, FrontRight, FrontCenter, Lfe, SideLeft, SideRight], + Self::SixPointOne => &[FrontLeft, FrontRight, FrontCenter, Lfe, BackCenter, SideLeft, SideRight], + Self::SevenPointOne => &[ + FrontLeft, + FrontRight, + FrontCenter, + Lfe, + BackLeft, + BackRight, + SideLeft, + SideRight, + ], + }) + } + pub(crate) fn validate(self) -> Result<(), Error> { if self.channels() == 0 { return Err(Error::Unsupported( @@ -44,3 +119,54 @@ impl Layout { Ok(()) } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn counts_map_to_the_wave_defaults() { + let expected = [ + Layout::Mono, + Layout::Stereo, + Layout::TwoPointOne, + Layout::Quad, + Layout::FivePointZero, + Layout::FivePointOne, + Layout::SixPointOne, + Layout::SevenPointOne, + ]; + for (count, layout) in (1..).zip(expected) { + assert_eq!(Layout::from_channels(count).unwrap(), layout); + assert_eq!(layout.channels(), count); + } + + assert_eq!(Layout::from_channels(9).unwrap(), Layout::Discrete(9)); + assert!(Layout::from_channels(0).is_err()); + } + + /// Canonical order is the WAVE bit order, so every layout's speakers must + /// ascend through [`Speaker`]'s declaration order without repeating. + #[test] + fn speakers_follow_the_canonical_order() { + let layouts = [ + Layout::Mono, + Layout::Stereo, + Layout::TwoPointOne, + Layout::ThreePointZero, + Layout::Quad, + Layout::FourPointZero, + Layout::FivePointZero, + Layout::FivePointOne, + Layout::SixPointOne, + Layout::SevenPointOne, + ]; + for layout in layouts { + let speakers = layout.speakers().unwrap(); + assert!( + speakers.windows(2).all(|pair| (pair[0] as u8) < (pair[1] as u8)), + "{layout:?} is out of order" + ); + } + } +} diff --git a/rs/moq-audio/src/lib.rs b/rs/moq-audio/src/lib.rs index f6c3572268e..8dc3c97d42a 100644 --- a/rs/moq-audio/src/lib.rs +++ b/rs/moq-audio/src/lib.rs @@ -3,8 +3,9 @@ //! Counterpart to [`moq-video`](https://crates.io/crates/moq-video) for audio //! tracks, and shaped the same way. Sits on top of [`moq_mux`] and [`hang`] and //! adds the missing piece for native callers: Rust-native Opus and uncompressed -//! PCM codecs that turn raw samples into HANG audio tracks and back, plus AAC-LC -//! on the way in, which is what the gateways (RTMP, SRT, HLS, gstreamer) publish. +//! PCM codecs that turn raw samples into HANG audio tracks and back, plus AAC-LC, +//! which is what the gateways (RTMP, SRT, HLS, gstreamer) publish. AAC decodes in +//! software and encodes only through a platform encoder. //! //! - `capture` describes an audio source (`capture::Config`) and grabs buffers //! per platform: a microphone via cpal (CoreAudio / WASAPI / ALSA) everywhere, @@ -26,7 +27,7 @@ //! - [`decode`] subscribes to an encoded track and decodes it back to PCM. //! [`decode::Consumer`] is the mirror of [`encode::Producer`]. It reads AAC-LC //! too, behind the default-on `aac` feature, since a broadcast that came in -//! through a gateway is AAC rather than one of the two codecs we encode. +//! through a gateway is AAC rather than one of the codecs we encode in software. //! - `playback` plays decoded PCM out a speaker. `playback::Engine` owns the //! output device and mixes the `playback::Sink`s registered with it, so one //! device serves every track in a call. Requires the `playback` feature, so diff --git a/rs/moq-audio/src/opus.rs b/rs/moq-audio/src/opus.rs index c8b2e8fac26..8b744bc09ee 100644 --- a/rs/moq-audio/src/opus.rs +++ b/rs/moq-audio/src/opus.rs @@ -20,9 +20,8 @@ pub(crate) const DECODE_RATE: u32 = 48_000; /// The OpusHead a decoder opens with. /// -/// The catalog's description when present, refused when malformed or when it -/// asks for a channel mapping this crate cannot decode. Without one, a -/// mono/stereo stream with no pre-skip or gain, shaped by the catalog. +/// The catalog's description when present, refused when malformed. Without +/// one, a family 0 stream with no pre-skip or gain, shaped by the catalog. pub(crate) fn head(catalog: &hang::catalog::AudioConfig) -> Result { let Some(description) = &catalog.description else { return Ok(moq_mux::codec::opus::Config::new( @@ -30,16 +29,8 @@ pub(crate) fn head(catalog: &hang::catalog::AudioConfig) -> Result Error { if code == unsafe_libopus::OPUS_INVALID_PACKET { return Error::Decode(format!("libopus rejected the packet (code {code})")); } - error(code, "opus_decode_float") + error(code, "opus_multistream_decode_float") } /// Classify a packet, preserving DTX across packet loss. @@ -108,6 +99,171 @@ pub(crate) fn activity(packet: &[u8], in_dtx: bool) -> Activity { } } +/// Classify a multistream packet, preserving DTX across packet loss. +/// +/// Every stream but the last is self-delimited (RFC 6716 framing plus the length +/// libopus writes ahead of that stream's payload). One `opus_packet_parse` of the +/// whole buffer treats the later streams as payload, so an all-DTX surround +/// packet reads as active. DTX means every stream coded nothing. +pub(crate) fn multistream_activity(packet: &[u8], streams: u8, in_dtx: bool) -> Activity { + if packet.is_empty() { + return if in_dtx { Activity::Dtx } else { Activity::Active }; + } + if streams <= 1 { + return activity(packet, in_dtx); + } + if streams_carry_nothing(packet, streams) { + Activity::Dtx + } else { + Activity::Active + } +} + +/// Whether every stream in a multistream packet coded no audio. +fn streams_carry_nothing(mut packet: &[u8], streams: u8) -> bool { + for index in 0..streams { + let last = index + 1 == streams; + if last { + return carries_nothing(packet); + } + let Some((silent, offset)) = self_delimited(packet) else { + return false; + }; + if !silent { + return false; + } + packet = &packet[offset..]; + } + false +} + +/// One self-delimited Opus packet at the front of `data`: whether every frame is +/// empty, and how many bytes it occupies, including its trailing padding. +/// +/// `None` when the bytes are not that packet. The length of the last frame is +/// coded where libopus puts it, before the frame payloads. +fn self_delimited(data: &[u8]) -> Option<(bool, usize)> { + if data.is_empty() { + return None; + } + let framesize = unsafe { unsafe_libopus::opus_packet_get_samples_per_frame(data.as_ptr(), 48_000) }; + if framesize <= 0 { + return None; + } + + let toc = data[0]; + let mut pos = 1usize; + let mut len = data.len() - 1; + let mut last_size = len; + let mut cbr = false; + let mut pad = 0usize; + let mut sizes = [0i32; 48]; + + let count = match toc & 0x3 { + 0 => 1, + 1 => { + cbr = true; + 2 + } + 2 => { + let (bytes, size) = parse_size(data.get(pos..pos.checked_add(len)?)?)?; + len = len.checked_sub(bytes)?; + if size as usize > len { + return None; + } + sizes[0] = size; + pos += bytes; + last_size = len - size as usize; + 2 + } + _ => { + if len < 1 { + return None; + } + let ch = data[pos]; + pos += 1; + len -= 1; + let count = (ch & 0x3f) as usize; + if count == 0 || count > sizes.len() || framesize as usize * count > 5760 { + return None; + } + if ch & 0x40 != 0 { + loop { + if len == 0 { + return None; + } + let p = data[pos] as usize; + pos += 1; + len -= 1; + let tmp = if p == 255 { 254 } else { p }; + len = len.checked_sub(tmp)?; + pad += tmp; + if p != 255 { + break; + } + } + } + cbr = ch & 0x80 == 0; + if !cbr { + last_size = len; + for slot in &mut sizes[..count - 1] { + let (bytes, size) = parse_size(data.get(pos..pos.checked_add(len)?)?)?; + len = len.checked_sub(bytes)?; + if size as usize > len { + return None; + } + *slot = size; + pos += bytes; + last_size = last_size.checked_sub(bytes + size as usize)?; + } + } + count + } + }; + + let (bytes, size) = parse_size(data.get(pos..pos.checked_add(len)?)?)?; + len = len.checked_sub(bytes)?; + if size as usize > len { + return None; + } + sizes[count - 1] = size; + pos += bytes; + if cbr { + if size as usize * count > len { + return None; + } + for slot in &mut sizes[..count - 1] { + *slot = size; + } + } else if bytes + size as usize > last_size { + return None; + } + + for &frame in &sizes[..count] { + pos = pos.checked_add(frame as usize)?; + if pos > data.len() { + return None; + } + } + let offset = pad.checked_add(pos)?; + if offset == 0 || offset > data.len() { + return None; + } + let silent = sizes[..count].iter().all(|&frame| frame == 0); + Some((silent, offset)) +} + +/// The self-delimited length prefix (RFC 6716 §3.2.5), or `None` when it is cut off. +fn parse_size(data: &[u8]) -> Option<(usize, i32)> { + let first = *data.first()?; + if first < 252 { + Some((1, i32::from(first))) + } else { + let second = *data.get(1)?; + Some((2, 4 * i32::from(second) + i32::from(first))) + } +} + /// Whether the sender coded no audio at all for this packet: a bare TOC whose /// every frame is empty. /// @@ -196,6 +352,38 @@ mod tests { assert_eq!(activity(&[], false), Activity::Active); } + /// A surround packet is one self-delimited Opus packet per stream, then a + /// normal packet for the last. DTX is all of them empty; one coded frame is + /// audio. Parsing the buffer as a single stream would read the later + /// subpackets as that frame's payload. + #[test] + fn multistream_activity_requires_every_stream_empty() { + // 5.1: two coupled streams, then two mono. Code 0, empty frame. + let dtx = [0xfc, 0x00, 0xfc, 0x00, 0xf8, 0x00, 0xf8]; + assert_eq!(multistream_activity(&dtx, 4, false), Activity::Dtx); + // A coded frame on the last stream. + let last = [0xfc, 0x00, 0xfc, 0x00, 0xf8, 0x00, 0xf8, 0xaa]; + assert_eq!(multistream_activity(&last, 4, false), Activity::Active); + // A coded frame on an earlier stream. The length byte is the payload size. + let early = [0xfc, 0x01, 0xaa, 0xfc, 0x00, 0xf8, 0x00, 0xf8]; + assert_eq!(multistream_activity(&early, 4, false), Activity::Active); + // Two empty frames in one self-delimited code-1 packet, then a bare TOC. + let cbr = [0xf9, 0x00, 0xf8]; + assert_eq!(multistream_activity(&cbr, 2, false), Activity::Dtx); + let cbr_payload = [0xf9, 0x01, 0xaa, 0xbb, 0xf8]; + assert_eq!(multistream_activity(&cbr_payload, 2, false), Activity::Active); + // Code 3 packs the 60 ms case: three empty frames, self-delimited, then a bare TOC. + let code3 = [0xfb, 0x03, 0x00, 0xf8]; + assert_eq!(multistream_activity(&code3, 2, false), Activity::Dtx); + let code3_payload = [0xfb, 0x03, 0x01, 0xaa, 0xbb, 0xcc, 0xf8]; + assert_eq!(multistream_activity(&code3_payload, 2, false), Activity::Active); + // Loss still carries the previous classification, whatever the layout. + assert_eq!(multistream_activity(&[], 4, true), Activity::Dtx); + assert_eq!(multistream_activity(&[], 4, false), Activity::Active); + // One stream is an ordinary packet. + assert_eq!(multistream_activity(&[0xf8], 1, false), Activity::Dtx); + } + /// A silence run's periodic refresh is an ordinarily coded frame, and a /// speech onset can leave an earlier frame of the same packet empty. Neither /// is distinguishable by framing, so both read active rather than risking diff --git a/rs/moq-audio/src/playback.rs b/rs/moq-audio/src/playback.rs index 49e81de3546..1f5e514a683 100644 --- a/rs/moq-audio/src/playback.rs +++ b/rs/moq-audio/src/playback.rs @@ -50,7 +50,7 @@ pub use sink::{Control, Input, Sink, Write}; #[cfg(feature = "aec")] pub(crate) use driver::Shared; #[cfg(feature = "aec")] -pub(crate) use mixer::BUS_CHANNELS; +pub(crate) use mixer::REFERENCE_CHANNELS; use crate::Error; @@ -137,13 +137,14 @@ impl Engine { /// Add a stream to the mix, taking PCM in the layout `input` describes. /// /// Independent of the device: several sinks can play at different rates and - /// channel counts, and each is resampled on its way to the mix. One device + /// layouts, and each is resampled and remixed to the device's on its way to + /// the mix. One device /// mixes up to 64 of them, past which this returns an error rather than /// handing back a sink that plays nothing. pub fn sink(&self, input: Input) -> Result { let sink = self .shared - .add(|id, rate| sink::new(id, rate, input, self.shared.clone(), self.handle.clone()))?; + .add(|id, rate, bus| sink::new(id, rate, bus, input, self.shared.clone(), self.handle.clone()))?; // Covers the case where the mixer's command queue was momentarily full, // so a sink is never left silently unmixed. diff --git a/rs/moq-audio/src/playback/device.rs b/rs/moq-audio/src/playback/device.rs index 8d55a28a42e..680e6a80f7b 100644 --- a/rs/moq-audio/src/playback/device.rs +++ b/rs/moq-audio/src/playback/device.rs @@ -11,10 +11,9 @@ use crate::Error; /// second choice. const RATES: &[u32] = &[48_000, 44_100]; -/// Channel counts to try, best first. The mixer produces stereo, and mono is -/// the only other count worth naming: anything else is a surround layout we -/// would be guessing the speaker order of. -const CHANNELS: &[u16] = &[2, 1]; +/// The widest channel count with a well-known layout. Wider counts name no +/// speaker positions to mix into, so they are never opened. +const MAX_CHANNELS: u16 = 8; /// Sample formats we can write, best first: `f32` is what the mixer produces, /// and the rest are conversions on the way out. @@ -129,16 +128,24 @@ pub(super) fn open(selector: Option<&str>) -> Result { /// Pick the stream format to open `device` with. /// -/// Only considers formats in [`FORMATS`], and prefers in that order: a channel -/// count in [`CHANNELS`], a rate the pipeline already runs at, then a format we -/// write without converting. Failing all of those it takes the highest rate the -/// device supports, since resampling down is kinder than resampling up. +/// Only considers formats in [`FORMATS`] and well-known layouts, and prefers in +/// that order: the device's own channel count, the widest layout, a rate the +/// pipeline already runs at, then a format we write without converting. Failing +/// the rates it takes the highest the device supports, since resampling down is +/// kinder than resampling up. pub(super) fn negotiate(device: &cpal::Device) -> Result { let supported = device .supported_output_configs() .map_err(|err| Error::Playback(format!("cannot enumerate output configs: {err}")))?; - choose(supported).ok_or_else(|| Error::Unsupported("output device offers no sample format we can write".into())) + // What the device is set up for: a 5.1 HDMI sink reports six channels and a + // headset two. Taken first because a sound server's plugin also accepts + // every count up to its limit, where the widest would upmix a headset. + let native = device.default_output_config().ok().map(|config| config.channels()); + + choose(supported, native).ok_or_else(|| { + Error::Unsupported("output device offers no sample format and speaker layout we can write".into()) + }) } /// Pick the best of the stream configurations a device reports. @@ -146,10 +153,14 @@ pub(super) fn negotiate(device: &cpal::Device) -> Result) -> Option { +fn choose( + supported: impl Iterator, + native: Option, +) -> Option { supported .filter(|config| FORMATS.contains(&config.sample_format())) - .min_by_key(preference) + .filter(|config| (1..=MAX_CHANNELS).contains(&config.channels())) + .min_by_key(|config| preference(config, native)) .map(|config| match preferred_rate(&config) { Some(rate) => config.try_with_sample_rate(rate).expect("a rate the range covers"), None => config.with_max_sample_rate(), @@ -164,11 +175,11 @@ fn choose(supported: impl Iterator) -> /// and a pass per channel count that gave up when neither preferred rate matched /// would hand that to the mono device and downmix. The channel count leads /// because a downmix is audible where a resample is not. -fn preference(config: &cpal::SupportedStreamConfigRange) -> (usize, usize, std::cmp::Reverse, usize) { - let channels = CHANNELS - .iter() - .position(|count| *count == config.channels()) - .unwrap_or(CHANNELS.len()); +fn preference( + config: &cpal::SupportedStreamConfigRange, + native: Option, +) -> ((bool, std::cmp::Reverse), usize, std::cmp::Reverse, usize) { + let channels = (native != Some(config.channels()), std::cmp::Reverse(config.channels())); let rate = match preferred_rate(config) { Some(rate) => (RATES.iter().position(|r| *r == rate).expect("from RATES"), rate), // Nothing we asked for, so take the most the device offers: resampling @@ -223,33 +234,72 @@ mod tests { /// the way to a stereo sink. #[test] fn stereo_wins_even_when_the_device_lists_mono_first() { - let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 48_000, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(1, 48_000, SampleFormat::F32), range(2, 48_000, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!(chosen.channels(), 2); } /// Preferring stereo must not refuse a device that has no stereo to offer. #[test] fn mono_is_taken_when_that_is_all_there_is() { - let chosen = choose([range(1, 48_000, SampleFormat::F32)].into_iter()).expect("a config"); + let chosen = choose([range(1, 48_000, SampleFormat::F32)].into_iter(), None).expect("a config"); assert_eq!(chosen.channels(), 1); } - /// Neither preferred count is offered, so the pass that accepts any count - /// has to catch it. Without it a surround-only sink would not open at all. + /// A surround-only sink opens at its own width rather than being refused. #[test] - fn a_count_we_do_not_prefer_still_opens() { - let chosen = choose([range(6, 48_000, SampleFormat::F32)].into_iter()).expect("a config"); + fn a_surround_only_device_opens() { + let chosen = choose([range(6, 48_000, SampleFormat::F32)].into_iter(), None).expect("a config"); assert_eq!(chosen.channels(), 6); } + /// A 5.1 HDMI sink opens at six channels rather than being folded to stereo. + #[test] + fn six_channels_are_chosen_when_offered() { + let offered = || [range(2, 48_000, SampleFormat::F32), range(6, 48_000, SampleFormat::F32)].into_iter(); + assert_eq!(choose(offered(), None).expect("a config").channels(), 6); + assert_eq!(choose(offered(), Some(6)).expect("a config").channels(), 6); + } + + /// A sound server's plugin accepts every count up to its limit, so the + /// device's own count beats the widest: a headset stays at two rather than + /// being upmixed to 7.1 and folded back down by the server. + #[test] + fn the_native_count_beats_the_widest() { + let offered = (1..=8).map(|channels| range(channels, 48_000, SampleFormat::F32)); + assert_eq!(choose(offered, Some(2)).expect("a config").channels(), 2); + } + + /// Past 7.1 there is no convention naming the speakers, so there is nothing + /// to remix into. + #[test] + fn counts_without_a_layout_are_refused() { + assert!(choose([range(12, 48_000, SampleFormat::F32)].into_iter(), Some(12)).is_none()); + let chosen = choose( + [ + range(12, 48_000, SampleFormat::F32), + range(2, 48_000, SampleFormat::F32), + ] + .into_iter(), + Some(12), + ) + .expect("a config"); + assert_eq!(chosen.channels(), 2); + } + /// Rate is preferred within a channel count, not across one: a stereo config /// at an awkward rate beats a mono config at the pipeline's own rate, /// because resampling is inaudible and a downmix is not. #[test] fn channels_outrank_the_sample_rate() { - let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 44_100, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(1, 48_000, SampleFormat::F32), range(2, 44_100, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 44_100)); } @@ -257,8 +307,11 @@ mod tests { /// produces rather than one that costs a conversion. #[test] fn f32_is_preferred_over_a_format_we_convert_to() { - let chosen = choose([range(2, 48_000, SampleFormat::I16), range(2, 48_000, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(2, 48_000, SampleFormat::I16), range(2, 48_000, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!(chosen.sample_format(), SampleFormat::F32); } @@ -266,8 +319,8 @@ mod tests { /// stream that plays noise. #[test] fn a_device_we_cannot_write_to_is_rejected() { - assert!(choose([range(2, 48_000, SampleFormat::I8)].into_iter()).is_none()); - assert!(choose(std::iter::empty()).is_none()); + assert!(choose([range(2, 48_000, SampleFormat::I8)].into_iter(), None).is_none()); + assert!(choose(std::iter::empty(), None).is_none()); } /// Channels lead even when neither preferred rate is on offer. @@ -278,8 +331,11 @@ mod tests { /// downmix the whole preference exists to avoid. #[test] fn stereo_at_an_awkward_rate_beats_mono_at_a_preferred_one() { - let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 96_000, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(1, 48_000, SampleFormat::F32), range(2, 96_000, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 96_000)); } @@ -293,6 +349,7 @@ mod tests { range(2, 96_000, SampleFormat::F32), ] .into_iter(), + None, ) .expect("a config"); assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 96_000)); @@ -309,6 +366,7 @@ mod tests { range(2, 32_000, SampleFormat::F32), ] .into_iter(), + None, ) .expect("a config"); assert_eq!( diff --git a/rs/moq-audio/src/playback/driver.rs b/rs/moq-audio/src/playback/driver.rs index ce30e3688df..12bbd70fa5e 100644 --- a/rs/moq-audio/src/playback/driver.rs +++ b/rs/moq-audio/src/playback/driver.rs @@ -19,7 +19,7 @@ use rand::RngExt; use super::mixer::{self, Mixer}; use super::sink::{Registration, Sink}; -use crate::Error; +use crate::{Error, Layout}; /// Backoff bounds for reopening a device that failed. The first retry is quick because the common /// case is a device that came right back (a USB re-enumerate, a sample-rate change); the ceiling @@ -78,6 +78,9 @@ struct State { /// Rate the device is running at, which is what sinks resample to. Zero /// until the first stream opens. rate: u32, + /// Layout the device is running in, which is what sinks remix to. Stereo + /// stands in until the first stream opens. + layout: Layout, /// Registration channel to the live mixer, replaced every time the stream is /// rebuilt. `None` while no stream is running. mixer: Option>, @@ -108,13 +111,14 @@ struct State { impl Shared { /// Build a sink, register it, and start mixing it. /// - /// `build` is handed the sink's id and the rate its channel should target. + /// `build` is handed the sink's id and the rate and layout its channel should + /// target. /// It runs with no device open too: the registration waits for the next /// restart, so a device that is briefly missing doesn't become an error the /// caller has to retry. pub(super) fn add(&self, build: F) -> Result where - F: FnOnce(u64, u32) -> Result<(Sink, Registration), Error>, + F: FnOnce(u64, u32, Layout) -> Result<(Sink, Registration), Error>, { let mut state = self.state.lock().unwrap(); @@ -131,7 +135,7 @@ impl Shared { // 48 kHz stands in until a device opens and the channel is rebuilt at // the real rate. let rate = if state.rate == 0 { 48_000 } else { state.rate }; - let (sink, mut registration) = build(state.next_id, rate)?; + let (sink, mut registration) = build(state.next_id, rate, state.layout)?; state.next_id += 1; if let Some(mixer) = &state.mixer { @@ -270,11 +274,11 @@ impl Shared { } /// Point every sink at a freshly opened stream: rebuild each channel at - /// `rate` and hand the new consumers to `mixer`. - fn rebind(&self, rate: u32, mixer: SyncSender) { + /// `rate` and `layout` and hand the new consumers to `mixer`. + fn rebind(&self, rate: u32, layout: Layout, mixer: SyncSender) { let mut state = self.state.lock().unwrap(); for sink in &mut state.sinks { - sink.rebuild(rate); + sink.rebuild(rate, layout); sink.attach(&mixer); } @@ -289,6 +293,7 @@ impl Shared { } state.rate = rate; + state.layout = layout; state.mixer = Some(mixer); // The old mixer is gone, and with it every sink it was told about. state.detaching.clear(); @@ -787,7 +792,8 @@ impl Driver { // a full retirement channel is the one case where the mixer has to free // on the audio thread after all. let (retired_tx, retired_rx) = sync_channel(COMMAND_QUEUE); - let mixer = Mixer::new(rx, retired_tx, rate, channels); + let layout = Layout::from_channels(channels as u32)?; + let mixer = Mixer::new(rx, retired_tx, rate, layout)?; let failures = Arc::new(Failures::default()); let reporter = FailureReporter { @@ -799,7 +805,7 @@ impl Driver { .play() .map_err(|err| Error::Playback(format!("cannot start output stream: {err}")))?; - self.shared.rebind(rate, tx); + self.shared.rebind(rate, layout, tx); self.stream = Some(stream); self.failures = Some(failures); // Replaces the previous receiver, dropping anything the old stream @@ -807,7 +813,7 @@ impl Driver { self.retired = Some(retired_rx); self.retry = RETRY_MIN; - tracing::info!(rate, channels, ?format, "opened audio output"); + tracing::info!(rate, ?layout, ?format, "opened audio output"); Ok(()) } @@ -1005,7 +1011,7 @@ mod tests { let handle = Arc::new(super::super::Handle { commands }); let (tx, mixer) = sync_channel(depth); - shared.rebind(48_000, tx); + shared.rebind(48_000, Layout::Stereo, tx); Wired { shared, @@ -1016,7 +1022,7 @@ mod tests { } fn add(shared: &Arc, handle: &Arc) -> Result { - shared.add(|id, rate| sink::new(id, rate, Input::default(), shared.clone(), handle.clone())) + shared.add(|id, rate, bus| sink::new(id, rate, bus, Input::default(), shared.clone(), handle.clone())) } /// Long enough that only a lost wake, rather than a loaded machine, trips a diff --git a/rs/moq-audio/src/playback/mixer.rs b/rs/moq-audio/src/playback/mixer.rs index d3f23124e37..6187f2ca9ae 100644 --- a/rs/moq-audio/src/playback/mixer.rs +++ b/rs/moq-audio/src/playback/mixer.rs @@ -19,6 +19,10 @@ use fixed_resample::ResamplingCons; #[cfg(feature = "aec")] use fixed_resample::ResamplingProd; +#[cfg(feature = "aec")] +use crate::resample::Remix; +use crate::{Error, Layout}; + /// Frames mixed per pass. The callback buffer is chunked to this so the scratch /// buffers stay a fixed size no matter what period the device asks for. const CHUNK: usize = 1024; @@ -27,9 +31,10 @@ const CHUNK: usize = 1024; /// inaudible as a click, short enough to feel instant. const RAMP: f32 = 0.003; -/// The mix bus is stereo: sinks resample into it and it fans out to however many -/// channels the device wants. -pub(crate) const BUS_CHANNELS: usize = 2; +/// The echo reference is the mix downmixed to stereo, whatever layout the +/// device plays, so the canceller's model survives a device switch. +#[cfg(feature = "aec")] +pub(crate) const REFERENCE_CHANNELS: usize = 2; /// Sinks one device will mix. The entry list is allocated to this up front and /// never grows, which is what keeps registration off the allocator. @@ -138,36 +143,61 @@ pub(super) struct Mixer { /// Where anything the mixer is done with goes to be dropped, since dropping /// it here would free on the audio thread. retired: SyncSender, - /// Channels the device takes. + /// Channels the device takes, which is also the bus layout's: every sink + /// remixes into it on its way here. channels: usize, /// Per-frame gain step, so any change spans [`RAMP`] regardless of rate. step: f32, - /// Stereo accumulator for one chunk. + /// Accumulator for one chunk, in the device's layout. bus: Vec, - /// Stereo scratch for the sink being read. + /// Scratch for the sink being read, in the device's layout. scratch: Vec, - /// Where echo cancellation reads what was played. Fed the mix after - /// clipping but before it fans out, since that is the signal the speaker - /// gets and therefore the one the microphone hears back. + /// Where echo cancellation reads what was played. Fed the clipped mix, since + /// that is the signal the speaker gets and therefore the one the microphone + /// hears back. #[cfg(feature = "aec")] reference: Option>, + /// Downmixes the bus to the reference's stereo. + #[cfg(feature = "aec")] + downmix: Remix, + /// Stereo scratch for the downmixed reference. + #[cfg(feature = "aec")] + stereo: Vec, } impl Mixer { - /// `rate` and `channels` describe the device, not the sinks: each sink - /// resamples into the bus on its way here. - pub(super) fn new(commands: Receiver, retired: SyncSender, rate: u32, channels: usize) -> Self { - Self { + /// `rate` and `layout` describe the device, not the sinks: each sink + /// resamples and remixes into the bus on its way here. + pub(super) fn new( + commands: Receiver, + retired: SyncSender, + rate: u32, + layout: Layout, + ) -> Result { + // Sinks remix by speaker position, so a bus without any has nothing to + // remix into. + if layout.speakers().is_none() { + return Err(Error::Unsupported(format!( + "cannot mix into an output without speaker positions ({layout:?})" + ))); + } + + let channels = layout.channels() as usize; + Ok(Self { entries: Vec::with_capacity(MAX_SINKS), commands, retired, channels, step: 1.0 / (rate as f32 * RAMP), - bus: vec![0.0; CHUNK * BUS_CHANNELS], - scratch: vec![0.0; CHUNK * BUS_CHANNELS], + bus: vec![0.0; CHUNK * channels], + scratch: vec![0.0; CHUNK * channels], #[cfg(feature = "aec")] reference: None, - } + #[cfg(feature = "aec")] + downmix: Remix::new(layout, Layout::Stereo)?, + #[cfg(feature = "aec")] + stereo: vec![0.0; CHUNK * REFERENCE_CHANNELS], + }) } /// Hand something the mixer is done with back to the driver to drop. @@ -234,6 +264,10 @@ impl Mixer { scratch, #[cfg(feature = "aec")] reference, + #[cfg(feature = "aec")] + downmix, + #[cfg(feature = "aec")] + stereo, .. } = self; let channels = *channels; @@ -242,7 +276,7 @@ impl Mixer { let mut done = 0; while done < total { let frames = (total - done).min(CHUNK); - let samples = frames * BUS_CHANNELS; + let samples = frames * channels; bus[..samples].fill(0.0); @@ -257,13 +291,16 @@ impl Mixer { let mut applied = entry.applied; let mut peak = 0.0f32; - for frame in 0..frames { + for (input, mixed) in scratch[..samples] + .chunks_exact(channels) + .zip(bus[..samples].chunks_exact_mut(channels)) + { applied += (target - applied).clamp(-*step, *step); - let left = scratch[frame * 2] * applied; - let right = scratch[frame * 2 + 1] * applied; - peak = peak.max(left.abs()).max(right.abs()); - bus[frame * 2] += left; - bus[frame * 2 + 1] += right; + for (input, mixed) in input.iter().zip(mixed) { + let sample = input * applied; + peak = peak.max(sample.abs()); + *mixed += sample; + } } entry.applied = applied; @@ -280,26 +317,12 @@ impl Mixer { // useful to do about it from here and nothing may be logged. #[cfg(feature = "aec")] if let Some(reference) = reference.as_mut() { - reference.push_interleaved(&bus[..samples]); + let stereo = &mut stereo[..frames * REFERENCE_CHANNELS]; + downmix.apply(&bus[..samples], stereo); + reference.push_interleaved(stereo); } - let out = &mut out[done * channels..(done + frames) * channels]; - match channels { - 1 => { - for (frame, out) in out.iter_mut().enumerate() { - *out = (bus[frame * 2] + bus[frame * 2 + 1]) * 0.5; - } - } - _ => { - for (frame, out) in out.chunks_exact_mut(channels).enumerate() { - out[0] = bus[frame * 2]; - out[1] = bus[frame * 2 + 1]; - // Surround devices get silence past the front pair, which - // is better than duplicating stereo into the rears. - out[2..].fill(0.0); - } - } - } + out[done * channels..(done + frames) * channels].copy_from_slice(&bus[..samples]); done += frames; } @@ -316,6 +339,9 @@ mod tests { const RATE: u32 = 48_000; + /// The bus most tests mix into. + const STEREO: usize = 2; + /// Frames pushed per test: a tenth of a second, far more than any `fill` /// below drains, so a short read never starves by accident. const FRAMES: usize = RATE as usize / 10; @@ -328,21 +354,23 @@ mod tests { /// audio thread never drops one. retired: Receiver, next: u64, + channels: usize, } impl Harness { - fn new(channels: usize) -> Self { - Self::with_depth(channels, 8) + fn new(layout: Layout) -> Self { + Self::with_depth(layout, 8) } - fn with_depth(channels: usize, depth: usize) -> Self { + fn with_depth(layout: Layout, depth: usize) -> Self { let (commands, rx) = sync_channel(depth); let (retired_tx, retired) = sync_channel(MAX_SINKS); Self { - mixer: Mixer::new(rx, retired_tx, RATE, channels), + mixer: Mixer::new(rx, retired_tx, RATE, layout).unwrap(), commands, retired, next: 0, + channels: layout.channels() as usize, } } @@ -352,7 +380,7 @@ mod tests { /// pushed samples and the assertions. fn add(&mut self, gain: Arc) -> (u64, ResamplingProd) { let (prod, cons) = resampling_channel::( - BUS_CHANNELS, + self.channels, RATE, RATE, true, @@ -389,12 +417,12 @@ mod tests { /// Push `frames` stereo frames of a constant sample. fn push(prod: &mut ResamplingProd, value: f32, frames: usize) { - prod.push_interleaved(&vec![value; frames * BUS_CHANNELS]); + prod.push_interleaved(&vec![value; frames * STEREO]); } #[test] fn discards_writes_until_the_device_reads() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let (_, mut prod) = harness.add(Arc::new(Gain::new())); // Nothing has read yet, so these samples are dropped rather than queued @@ -411,7 +439,7 @@ mod tests { #[test] fn sums_sinks_and_clips() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; // Three sinks at 0.5 sum to 1.5, which must clip to 1.0. @@ -433,7 +461,7 @@ mod tests { #[test] fn volume_ramps_instead_of_stepping() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let gain = Arc::new(Gain::new()); @@ -453,8 +481,8 @@ mod tests { // The whole ramp is monotonic, not just its endpoints. let ramp = (RATE as f32 * RAMP) as usize; assert!(ramp < out.len() / 2, "test buffer is shorter than the ramp"); - for frame in out[..ramp * BUS_CHANNELS] - .as_chunks::() + for frame in out[..ramp * STEREO] + .as_chunks::() .0 .iter() .collect::>() @@ -484,7 +512,7 @@ mod tests { /// device buffer into NaN. #[test] fn output_stays_finite_after_a_non_finite_volume() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let gain = Arc::new(Gain::new()); @@ -500,7 +528,7 @@ mod tests { #[test] fn peak_reports_the_loudest_sample_then_resets() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let gain = Arc::new(Gain::new()); @@ -517,7 +545,7 @@ mod tests { #[test] fn removed_sinks_stop_mixing() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let (id, mut prod) = harness.add(Arc::new(Gain::new())); @@ -536,7 +564,7 @@ mod tests { /// callback would free on the audio thread, so it goes back to the driver. #[test] fn removed_sinks_are_handed_back_rather_than_dropped() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 512]; let (id, _prod) = harness.add(Arc::new(Gain::new())); @@ -561,7 +589,7 @@ mod tests { #[cfg(feature = "aec")] #[test] fn the_echo_reference_gets_the_mix() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let (reference, mut tap) = reference_channel(); @@ -574,7 +602,7 @@ mod tests { // does, so that nothing queues up while nobody is listening. That first // read also primes the channel with its configured latency in silence, // which is why the buffer below is read past it rather than at it. - let mut heard = vec![0.0f32; 2048 * BUS_CHANNELS]; + let mut heard = vec![0.0f32; 2048 * REFERENCE_CHANNELS]; tap.read_interleaved(&mut heard, false); for prod in &mut prods { @@ -596,7 +624,7 @@ mod tests { #[cfg(feature = "aec")] #[test] fn a_replaced_echo_reference_is_handed_back() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 512]; harness @@ -629,7 +657,7 @@ mod tests { #[cfg(feature = "aec")] fn reference_channel() -> (ResamplingProd, ResamplingCons) { resampling_channel::( - BUS_CHANNELS, + REFERENCE_CHANNELS, RATE, RATE, true, @@ -645,7 +673,7 @@ mod tests { /// thread, which is why the driver caps registrations at MAX_SINKS. #[test] fn the_entry_list_never_grows() { - let mut harness = Harness::with_depth(2, MAX_SINKS); + let mut harness = Harness::with_depth(Layout::Stereo, MAX_SINKS); let mut out = vec![0.0f32; 512]; let capacity = harness.mixer.entries.capacity(); @@ -660,50 +688,65 @@ mod tests { #[test] fn silence_when_no_sink_is_registered() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![1.0f32; 512]; harness.fill(&mut out); assert!(out.iter().all(|s| *s == 0.0), "callback buffer was not overwritten"); } + /// The bus is the device's own layout, so every speaker of a surround device + /// carries what the sinks put there rather than silence past the front pair. #[test] - fn mono_device_gets_the_stereo_average() { - let mut harness = Harness::new(1); - let mut out = vec![0.0f32; 1024]; + fn a_surround_bus_mixes_every_speaker() { + let mut harness = Harness::new(Layout::FivePointOne); + let mut out = vec![0.0f32; 6 * 512]; let (_, mut prod) = harness.add(Arc::new(Gain::new())); harness.fill(&mut out); - - // Hard left, so a mono device should hear half of it. - let mut samples = vec![0.0f32; FRAMES * BUS_CHANNELS]; - for frame in samples.as_chunks_mut::().0.iter_mut() { - frame[0] = 1.0; - } - prod.push_interleaved(&samples); + let frame = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]; + prod.push_interleaved(&frame.repeat(FRAMES)); harness.settle(&mut out); - assert!((out[out.len() - 1] - 0.5).abs() < 1e-5, "got {}", out[out.len() - 1]); + + let last = &out[out.len() - 6..]; + for (got, want) in last.iter().zip(frame) { + assert!((got - want).abs() < 1e-5, "got {last:?}"); + } } + /// The canceller models a stereo reference whatever the device plays, so a + /// surround bus reaches it downmixed rather than cut to its front pair. + #[cfg(feature = "aec")] #[test] - fn surround_devices_get_silence_past_the_front_pair() { - let mut harness = Harness::new(6); - let mut out = vec![0.0f32; 6 * 512]; + fn the_echo_reference_downmixes_a_surround_bus() { + let mut harness = Harness::new(Layout::FivePointOne); + let mut out = vec![0.0f32; 6 * 2048]; + let (reference, mut tap) = reference_channel(); + harness.commands.send(Command::Reference(Some(reference))).unwrap(); let (_, mut prod) = harness.add(Arc::new(Gain::new())); harness.fill(&mut out); - push(&mut prod, 1.0, FRAMES); + let mut heard = vec![0.0f32; 2048 * REFERENCE_CHANNELS]; + tap.read_interleaved(&mut heard, false); + + // Center only, which a stereo downmix splits evenly at -3 dB. + prod.push_interleaved(&[0.0, 0.0, 0.5, 0.0, 0.0, 0.0].repeat(FRAMES)); harness.settle(&mut out); + tap.read_interleaved(&mut heard, false); - let last = &out[out.len() - 6..]; - assert!(last[0] > 0.9 && last[1] > 0.9, "front pair was silent"); - assert!(last[2..].iter().all(|s| *s == 0.0), "rear channels were not silent"); + let want = 0.5 * std::f32::consts::FRAC_1_SQRT_2; + let tail = &heard[heard.len() - 64..]; + assert!( + tail.iter().all(|s| (*s - want).abs() < 1e-5), + "the tap saw {:?}, not the downmix", + &tail[..4] + ); } #[test] fn underflow_reads_as_silence_rather_than_stale_samples() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 8192]; let (_, mut prod) = harness.add(Arc::new(Gain::new())); diff --git a/rs/moq-audio/src/playback/sink.rs b/rs/moq-audio/src/playback/sink.rs index 41b8d0f79de..74bed20c192 100644 --- a/rs/moq-audio/src/playback/sink.rs +++ b/rs/moq-audio/src/playback/sink.rs @@ -1,6 +1,5 @@ //! [`Sink`]: one stream of PCM on its way to the speaker. -use std::borrow::Cow; use std::sync::mpsc::{SyncSender, TrySendError}; use std::sync::{Arc, Mutex}; use std::time::Duration; @@ -8,8 +7,8 @@ use std::time::Duration; use fixed_resample::{PushStatus, ResamplingChannelConfig, ResamplingCons, ResamplingProd, resampling_channel}; use super::driver::Shared; -use super::mixer::{self, BUS_CHANNELS, Gain}; -use crate::resample::remix; +use super::mixer::{self, Gain}; +use crate::resample::Remix; use crate::{Error, Format, Layout}; /// Default for [`Input::latency`]: audio buffered between [`Sink::write`] and @@ -28,7 +27,7 @@ const HEADROOM: f64 = 3.0; /// /// The playback counterpart to [`encode::Input`](crate::encode::Input): it /// describes the buffers you hand in, not the device, which is free to run at -/// its own rate and channel count. +/// its own rate and layout. /// /// `#[non_exhaustive]`: construct via [`Input::default`] and set fields, so new /// options can be added without breaking callers. @@ -40,7 +39,8 @@ pub struct Input { /// Samples per second per channel. Resampled to the device rate if they /// differ. pub sample_rate: u32, - /// Speaker meaning and channel order. + /// Speaker meaning and channel order. Remixed to the device's layout, so it + /// must name speaker positions rather than be [`Layout::Discrete`]. pub layout: Layout, /// How much audio to hold between [`Sink::write`] and the speaker (default: @@ -77,9 +77,9 @@ impl Input { if self.sample_rate == 0 { return Err(Error::Unsupported("sample rate must be > 0".into())); } - if !matches!(self.layout, Layout::Mono | Layout::Stereo) { + if self.layout.speakers().is_none() { return Err(Error::Unsupported(format!( - "playback accepts named mono or stereo input (got {:?})", + "playback needs speaker positions to remix (got {:?})", self.layout ))); } @@ -120,13 +120,13 @@ impl Write { /// One stream of PCM being played, mixed with every other sink on the device. /// /// Write decoded samples with [`write`](Self::write) and drop the sink to stop. -/// Writes are cheap and never block on the device: they hand samples to a ring -/// buffer that the audio thread drains on its own clock, resampling to the -/// device rate on the way. +/// Writes are cheap and never block on the device: they remix to the device's +/// layout and hand samples to a ring buffer that the audio thread drains on its +/// own clock, resampling to the device rate on the way. pub struct Sink { id: u64, input: Input, - prod: Arc>>, + channel: Arc>, control: Control, /// Whether the last write overflowed, so a writer that stays ahead of the /// device logs once rather than on every write. @@ -151,17 +151,21 @@ impl Sink { /// The returned [`Write`] counts input sample frames accepted and dropped; /// dropped live audio should be observed for telemetry, not retried. pub fn write(&mut self, samples: &[u8]) -> Result { - let pcm = self - .input - .format - .as_interleaved_f32(samples, self.input.layout.channels())?; - let pcm = match self.input.layout.channels() as usize { - BUS_CHANNELS => pcm, - _ => Cow::Owned(remix(&pcm, self.input.layout, Layout::Stereo)?), + let channels = self.input.layout.channels(); + let pcm = self.input.format.as_interleaved_f32(samples, channels)?; + let requested_sample_frames = pcm.len() / channels as usize; + + let mut channel = self.channel.lock().unwrap(); + let mixed; + let pcm = match &channel.remix { + Some(remix) => { + mixed = remix.process(&pcm); + &mixed + } + None => pcm.as_ref(), }; - let requested_sample_frames = pcm.len() / BUS_CHANNELS; - let accepted_sample_frames = match self.prod.lock().unwrap().push_interleaved(&pcm) { + let accepted_sample_frames = match channel.prod.push_interleaved(pcm) { // OutputNotReady means the device has not read yet, so these samples // are dropped rather than queued to play late. PushStatus::Ok => { @@ -201,7 +205,7 @@ impl Sink { /// climbs when the writer runs ahead, and falls toward zero when it falls /// behind. pub fn buffered(&self) -> Duration { - Duration::from_secs_f64(self.prod.lock().unwrap().occupied_seconds().max(0.0)) + Duration::from_secs_f64(self.channel.lock().unwrap().prod.occupied_seconds().max(0.0)) } /// The PCM layout this sink was built with. @@ -278,15 +282,21 @@ impl Control { } } +/// The ring into the mixer and the remix that fills it, swapped together when +/// the device changes rate or layout. +struct Channel { + prod: ResamplingProd, + /// Converts the sink's layout to the device's, when they differ. + remix: Option, +} + /// A sink as the driver sees it: enough to rebuild its channel when the device /// changes underneath it. pub(super) struct Registration { pub(super) id: u64, - /// The caller's rate, which is the input side of the channel. - rate: u32, - /// The depth the rebuilt channel has to keep, from the caller's [`Input`]. - latency: Duration, - prod: Arc>>, + /// The caller's rate, layout, and latency: the input side of the channel. + input: Input, + channel: Arc>, gain: Arc, /// The consumer waiting to be handed to a mixer. Taken once it is attached, /// and refilled by [`rebuild`](Self::rebuild). @@ -319,34 +329,36 @@ impl Registration { } } - /// Re-create the channel for a device now running at `rate`, swapping the - /// producer the caller's [`Sink`] writes into. - pub(super) fn rebuild(&mut self, rate: u32) { - let (prod, cons) = channel(self.rate, rate, self.latency); - *self.prod.lock().unwrap() = prod; + /// Re-create the channel for a device now running at `rate` in `bus`, + /// swapping the producer the caller's [`Sink`] writes into. + pub(super) fn rebuild(&mut self, rate: u32, bus: Layout) { + let (channel, cons) = channel(&self.input, rate, bus); + *self.channel.lock().unwrap() = channel; self.pending = Some(cons); } } /// Build a sink and its registration. The device may not be open yet, in which -/// case `rate` is a placeholder the driver replaces on the next rebuild. +/// case `rate` and `bus` are placeholders the driver replaces on the next +/// rebuild. pub(super) fn new( id: u64, rate: u32, + bus: Layout, input: Input, shared: Arc, engine: Arc, ) -> Result<(Sink, Registration), Error> { input.validate()?; - let (prod, cons) = channel(input.sample_rate, rate, input.latency); - let prod = Arc::new(Mutex::new(prod)); + let (channel, cons) = self::channel(&input, rate, bus); + let channel = Arc::new(Mutex::new(channel)); let gain = Arc::new(Gain::new()); let sink = Sink { id, input, - prod: prod.clone(), + channel: channel.clone(), control: Control { gain: gain.clone() }, overflowing: false, shared, @@ -355,9 +367,8 @@ pub(super) fn new( let registration = Registration { id, - rate: sink.input.sample_rate, - latency: sink.input.latency, - prod, + input: sink.input.clone(), + channel, gain, pending: Some(cons), }; @@ -365,14 +376,17 @@ pub(super) fn new( Ok((sink, registration)) } -/// The ring buffer between a writer and the audio thread, resampling the -/// caller's rate to the device's. -fn channel(from: u32, to: u32, latency: Duration) -> (ResamplingProd, ResamplingCons) { - let latency = latency.as_secs_f64(); - resampling_channel::( - BUS_CHANNELS, - from, - to, +/// The ring buffer between a writer and the audio thread, remixing the caller's +/// layout to the device's and resampling its rate to the device's. +fn channel(input: &Input, rate: u32, bus: Layout) -> (Channel, ResamplingCons) { + let remix = + (input.layout != bus).then(|| Remix::new(input.layout, bus).expect("sink and bus layouts name their speakers")); + + let latency = input.latency.as_secs_f64(); + let (prod, cons) = resampling_channel::( + bus.channels() as usize, + input.sample_rate, + rate, // We only ever push interleaved, which lets the channel skip its planar // staging buffer. true, @@ -385,7 +399,9 @@ fn channel(from: u32, to: u32, latency: Duration) -> (ResamplingProd, Resam overflow_autocorrect_percent_threshold: Some(75.0), ..Default::default() }, - ) + ); + + (Channel { prod, remix }, cons) } #[cfg(test)] @@ -393,20 +409,65 @@ mod tests { use super::*; fn sink(input: Input, output_rate: u32) -> (Sink, ResamplingCons) { + sink_into(input, output_rate, Layout::Stereo) + } + + fn sink_into(input: Input, output_rate: u32, bus: Layout) -> (Sink, ResamplingCons) { let shared = Arc::new(Shared::default()); let engine = Arc::new(super::super::Handle { commands: super::super::driver::Commands::default(), }); - let (sink, mut registration) = new(0, output_rate, input, shared, engine).unwrap(); + let (sink, mut registration) = new(0, output_rate, bus, input, shared, engine).unwrap(); (sink, registration.pending.take().unwrap()) } + /// Write `frame` repeated as `input` and read back what the bus got. + fn mix(input: Layout, bus: Layout, frame: &[f32]) -> Vec { + let input = Input { + layout: input, + ..Default::default() + }; + let (mut sink, mut cons) = sink_into(input, 48_000, bus); + let channels = bus.channels() as usize; + cons.read_interleaved(&mut vec![0.0; channels], false); + + let pcm: Vec = frame.repeat(4800).iter().flat_map(|s| s.to_le_bytes()).collect(); + assert_eq!(sink.write(&pcm).unwrap().dropped_sample_frames, 0); + + let mut out = vec![0.0; 4800 * channels]; + cons.read_interleaved(&mut out, false); + out[out.len() - channels..].to_vec() + } + + fn close(got: &[f32], want: &[f32]) { + assert_eq!(got.len(), want.len(), "{got:?} vs {want:?}"); + for (g, w) in got.iter().zip(want) { + assert!((g - w).abs() < 1e-4, "{got:?} vs {want:?}"); + } + } + + /// A 5.1 track on a stereo device plays its downmix, center and surrounds + /// folded into the front pair at -3 dB. + #[test] + fn a_surround_sink_downmixes_into_a_stereo_bus() { + let h = std::f32::consts::FRAC_1_SQRT_2; + let got = mix(Layout::FivePointOne, Layout::Stereo, &[0.1, 0.2, 0.3, 0.4, 0.05, 0.06]); + close(&got, &[0.1 + h * 0.3 + h * 0.05, 0.2 + h * 0.3 + h * 0.06]); + } + + /// A stereo track on a 5.1 device plays from the front pair alone. + #[test] + fn a_stereo_sink_fills_the_front_of_a_surround_bus() { + let got = mix(Layout::Stereo, Layout::FivePointOne, &[0.25, 0.75]); + close(&got, &[0.25, 0.75, 0.0, 0.0, 0.0, 0.0]); + } + fn s16(frames: usize, channels: usize) -> Vec { vec![0; frames * channels * 2] } fn ready(cons: &mut ResamplingCons) { - cons.read_interleaved(&mut [0.0; BUS_CHANNELS], false); + cons.read_interleaved(&mut [0.0; 2], false); } #[test] @@ -495,7 +556,7 @@ mod tests { #[test] fn rejects_layouts_it_cannot_mix() { - for layout in [Layout::Discrete(0), Layout::Discrete(6)] { + for layout in [Layout::Discrete(0), Layout::Discrete(2), Layout::Discrete(6)] { let input = Input { layout, ..Default::default() @@ -511,8 +572,13 @@ mod tests { } #[test] - fn accepts_mono_and_stereo() { - for layout in [Layout::Mono, Layout::Stereo] { + fn accepts_named_layouts() { + for layout in [ + Layout::Mono, + Layout::Stereo, + Layout::FivePointOne, + Layout::SevenPointOne, + ] { let input = Input { layout, ..Default::default() diff --git a/rs/moq-audio/src/resample.rs b/rs/moq-audio/src/resample.rs index 173a3b1ba27..402f0b85295 100644 --- a/rs/moq-audio/src/resample.rs +++ b/rs/moq-audio/src/resample.rs @@ -2,14 +2,17 @@ //! //! Wraps [`rubato`] with a small interleaved-`f32` interface so the //! producer/consumer doesn't have to convert to planar on every call. -//! The resampler keeps the channel layout unchanged; [`remix`] converts mono -//! and stereo after sample-rate conversion. +//! The resampler keeps the channel layout unchanged; [`Remix`] converts between +//! layouts after sample-rate conversion. + +use std::f32::consts::FRAC_1_SQRT_2; use rubato::audioadapter_buffers::direct::SequentialSliceOfVecs; use rubato::{ Async, FixedAsync, Resampler as RubatoTrait, SincInterpolationParameters, SincInterpolationType, WindowFunction, }; +use crate::layout::Speaker; use crate::{Error, Layout}; #[derive(Debug, thiserror::Error)] @@ -301,50 +304,147 @@ impl Resampler { } } -/// Convert between known layouts without assigning positions to discrete channels. -pub(crate) fn remix(samples: &[f32], input: Layout, output: Layout) -> Result, Error> { - validate_remix(input, output)?; - match (input, output) { - (input, output) if input == output => Ok(samples.to_vec()), - (Layout::Mono, Layout::Stereo) => { - let mut output = Vec::with_capacity(samples.len() * 2); - for &sample in samples { - output.extend_from_slice(&[sample, sample]); +/// A channel mix from one layout to another, each output channel a weighted sum +/// of the input channels. +/// +/// Refuses to give discrete channels speaker positions, though it will drop +/// them from named channels. +/// +/// Downmixing uses the ITU-R BS.775 coefficients: center and surrounds fold into +/// the front pair at -3 dB and the LFE is dropped. Upmixing leaves the speakers +/// the input lacks silent. Mono is the exception both ways: it plays at full +/// level from both front speakers when there is no center, and a mono output +/// averages the stereo downmix. +pub(crate) struct Remix { + inputs: usize, + outputs: usize, + /// One row of `inputs` weights per output channel. + weights: Vec, +} + +impl Remix { + pub(crate) fn new(input: Layout, output: Layout) -> Result { + input.validate()?; + output.validate()?; + + let (inputs, outputs) = (input.channels() as usize, output.channels() as usize); + // Dropping speaker positions is always safe; inventing them is not. + let unchanged = input == output || output == Layout::Discrete(inputs as u32); + let weights = match (input.speakers(), output.speakers()) { + _ if unchanged => (0..outputs) + .flat_map(|o| (0..inputs).map(move |i| if i == o { 1.0 } else { 0.0 })) + .collect(), + (Some(from), Some(to)) => weights(from, to), + _ => { + return Err(Error::Unsupported(format!( + "cannot convert audio layout {input:?} to {output:?} without speaker positions" + ))); + } + }; + + Ok(Self { + inputs, + outputs, + weights, + }) + } + + /// Mix whole interleaved input frames into `output`, which holds as many + /// frames. Never allocates, so the audio thread can call it. + pub(crate) fn apply(&self, input: &[f32], output: &mut [f32]) { + for (frame, out) in input + .chunks_exact(self.inputs) + .zip(output.chunks_exact_mut(self.outputs)) + { + for (sample, row) in out.iter_mut().zip(self.weights.chunks_exact(self.inputs)) { + *sample = row.iter().zip(frame).map(|(weight, input)| weight * input).sum(); } - Ok(output) } - (Layout::Stereo, Layout::Mono) => Ok(samples - .as_chunks::<2>() - .0 - .iter() - .map(|pair| (pair[0] + pair[1]) * 0.5) - .collect()), - _ => Err(Error::Unsupported(format!( - "cannot convert audio layout {input:?} to {output:?} without speaker positions" - ))), + } + + /// Mix whole interleaved input frames into a new buffer. + pub(crate) fn process(&self, input: &[f32]) -> Vec { + let mut output = vec![0.0; input.len() / self.inputs * self.outputs]; + self.apply(input, &mut output); + output } } -/// Check that [`remix`] can convert between two layouts. -pub(crate) fn validate_remix(input: Layout, output: Layout) -> Result<(), Error> { - input.validate()?; - output.validate()?; - if input == output - || matches!( - (input, output), - (Layout::Mono, Layout::Stereo) | (Layout::Stereo, Layout::Mono) - ) { - return Ok(()); - } - Err(Error::Unsupported(format!( - "cannot convert audio layout {input:?} to {output:?} without speaker positions" - ))) +/// The weights mixing `input` speakers into `output` speakers, one row per output. +fn weights(input: &[Speaker], output: &[Speaker]) -> Vec { + use Speaker::*; + + // The only layout without a front pair. Average the stereo downmix rather + // than invent a center weight for every speaker. + if output == [FrontCenter] && input != [FrontCenter] { + let stereo = weights(input, &[FrontLeft, FrontRight]); + let (left, right) = stereo.split_at(input.len()); + return left.iter().zip(right).map(|(l, r)| (l + r) * 0.5).collect(); + } + + let mut weights = vec![0.0; output.len() * input.len()]; + let has = |speaker| output.contains(&speaker); + + for (i, &speaker) in input.iter().enumerate() { + let mut feed = |to: Speaker, weight: f32| { + if let Some(o) = output.iter().position(|s| *s == to) { + weights[o * input.len() + i] += weight; + } + }; + + if has(speaker) { + feed(speaker, 1.0); + continue; + } + + match speaker { + FrontCenter => { + let weight = if input == [FrontCenter] { 1.0 } else { FRAC_1_SQRT_2 }; + feed(FrontLeft, weight); + feed(FrontRight, weight); + } + Lfe => {} + SideLeft | BackLeft | SideRight | BackRight => { + let (front, side, back) = match speaker { + SideLeft | BackLeft => (FrontLeft, SideLeft, BackLeft), + _ => (FrontRight, SideRight, BackRight), + }; + // Side and back are the same surround to a layout with only one of them. + let other = if speaker == side { back } else { side }; + if has(other) { + feed(other, 1.0); + } else { + feed(front, FRAC_1_SQRT_2); + } + } + BackCenter => { + if has(BackLeft) { + feed(BackLeft, FRAC_1_SQRT_2); + feed(BackRight, FRAC_1_SQRT_2); + } else if has(SideLeft) { + feed(SideLeft, FRAC_1_SQRT_2); + feed(SideRight, FRAC_1_SQRT_2); + } else { + feed(FrontLeft, 0.5); + feed(FrontRight, 0.5); + } + } + // Every output but mono, handled above, has a front pair. + FrontLeft | FrontRight => unreachable!("{output:?} has no front pair"), + } + } + + weights } #[cfg(test)] mod tests { use super::*; + fn remix(samples: &[f32], input: Layout, output: Layout) -> Result, Error> { + Ok(Remix::new(input, output)?.process(samples)) + } + /// `frames` into a stream at `rate`, as a timestamp in the source's own scale. fn at(frames: u64, rate: u64) -> moq_net::Timestamp { moq_net::Timestamp::from_scale(frames, rate).unwrap() @@ -548,4 +648,105 @@ mod tests { [2.0, 3.0] ); } + + /// One frame of 5.1 with a distinct level per speaker, in canonical order. + const FIVE_ONE: [f32; 6] = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]; + + fn close(got: &[f32], want: &[f32]) { + assert_eq!(got.len(), want.len(), "{got:?} vs {want:?}"); + for (g, w) in got.iter().zip(want) { + assert!((g - w).abs() < 1e-6, "{got:?} vs {want:?}"); + } + } + + #[test] + fn remix_downmixes_five_one_to_stereo_by_bs775() { + let h = FRAC_1_SQRT_2; + let [l, r, c, _lfe, ls, rs] = FIVE_ONE; + close( + &remix(&FIVE_ONE, Layout::FivePointOne, Layout::Stereo).unwrap(), + &[l + h * c + h * ls, r + h * c + h * rs], + ); + } + + #[test] + fn remix_downmixes_five_one_to_mono_through_stereo() { + let stereo = remix(&FIVE_ONE, Layout::FivePointOne, Layout::Stereo).unwrap(); + close( + &remix(&FIVE_ONE, Layout::FivePointOne, Layout::Mono).unwrap(), + &[(stereo[0] + stereo[1]) * 0.5], + ); + } + + #[test] + fn remix_upmixes_stereo_into_the_front_pair() { + close( + &remix(&[0.25, 0.75], Layout::Stereo, Layout::FivePointOne).unwrap(), + &[0.25, 0.75, 0.0, 0.0, 0.0, 0.0], + ); + } + + #[test] + fn remix_upmixes_mono_into_the_center() { + close( + &remix(&[0.5], Layout::Mono, Layout::FivePointOne).unwrap(), + &[0.0, 0.0, 0.5, 0.0, 0.0, 0.0], + ); + // Quad has no center, so mono plays from both fronts as it does in stereo. + close( + &remix(&[0.5], Layout::Mono, Layout::Quad).unwrap(), + &[0.5, 0.5, 0.0, 0.0], + ); + } + + /// 7.1 to 5.1 folds the back pair into the sides at full level, since a 5.1 + /// surround pair is the only surround it has. + #[test] + fn remix_folds_back_into_side_surrounds() { + let seven = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]; + close( + &remix(&seven, Layout::SevenPointOne, Layout::FivePointOne).unwrap(), + &[0.1, 0.2, 0.3, 0.4, 0.5 + 0.7, 0.6 + 0.8], + ); + } + + #[test] + fn remix_refuses_positions_it_would_invent() { + for (input, output) in [ + (Layout::Discrete(6), Layout::Stereo), + (Layout::Mono, Layout::Discrete(2)), + (Layout::Discrete(0), Layout::Discrete(0)), + ] { + assert!( + matches!(Remix::new(input, output), Err(Error::Unsupported(_))), + "{input:?} -> {output:?}" + ); + } + + assert_eq!( + remix(&[1.0, 2.0, 3.0], Layout::Discrete(3), Layout::Discrete(3)).unwrap(), + [1.0, 2.0, 3.0] + ); + assert_eq!( + remix(&[1.0, 2.0, 3.0], Layout::TwoPointOne, Layout::Discrete(3)).unwrap(), + [1.0, 2.0, 3.0] + ); + assert!(Remix::new(Layout::Discrete(3), Layout::TwoPointOne).is_err()); + } + + /// Every pair of named layouts converts, and the mix is sized to the output. + #[test] + fn remix_converts_between_every_named_layout() { + let layouts: Vec = (1..=8) + .map(|n| Layout::from_channels(n).unwrap()) + .chain([Layout::ThreePointZero, Layout::FourPointZero]) + .collect(); + for &input in &layouts { + for &output in &layouts { + let frame = vec![0.5; input.channels() as usize * 2]; + let mixed = remix(&frame, input, output).unwrap(); + assert_eq!(mixed.len(), output.channels() as usize * 2, "{input:?} -> {output:?}"); + } + } + } } diff --git a/rs/moq-audio/tests/import.rs b/rs/moq-audio/tests/import.rs new file mode 100644 index 00000000000..010c1976c4e --- /dev/null +++ b/rs/moq-audio/tests/import.rs @@ -0,0 +1,64 @@ +//! Container imports that must decode end to end: a stream `moq-mux` imports +//! plays through [`decode::Consumer`] like the same stream from any container. + +use std::time::Duration; + +use moq_audio::{Format, Layout, decode}; + +/// MPEG-TS names surround Opus only by channel count, so the importer has to +/// synthesize the OpusHead mapping table or the decoder refuses the track. +#[tokio::test] +async fn ts_surround_opus_decodes() { + // A 440 Hz center channel in 5.1; see `import_opus_surround_catalog` in moq-mux. + let data = include_bytes!("../../moq-mux/src/container/ts/test_data/opus_5_1.ts"); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let broadcast_consumer = broadcast.consume(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let mut import = moq_mux::container::ts::Import::new(broadcast, catalog.reserve()); + import.decode(&data[..]).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let (name, config) = snapshot.audio.renditions.iter().next().expect("an Opus track"); + + let mut options = decode::Options::default(); + options.output.format = Format::F32; + // The whole file is imported before anything decodes it. + options.max_age = Duration::from_secs(30); + let mut consumer = decode::Consumer::new(&broadcast_consumer, config, name, options) + .await + .unwrap(); + assert_eq!(consumer.layout(), Layout::FivePointOne); + + // Canonical 5.1 order: FL, FR, FC, LFE, SL, SR. + let mut energy = [0.0f64; 6]; + let mut frames = 0; + while let Some(frame) = tokio::time::timeout(Duration::from_secs(5), consumer.read()) + .await + .expect("decoded frame timed out") + .unwrap() + { + let (samples, rest) = frame.data.as_chunks::<4>(); + assert!(rest.is_empty()); + for chunk in samples.as_chunks::<6>().0 { + for (channel, sample) in energy.iter_mut().zip(chunk) { + *channel += f32::from_le_bytes(*sample).powi(2) as f64; + } + frames += 1; + } + } + + assert!(frames > 12_000, "expected most of 0.5 s at 48 kHz, got {frames} frames"); + let center = energy[2]; + assert!( + center / frames as f64 > 0.001, + "center should carry the tone: {energy:?}" + ); + for (channel, &other) in energy.iter().enumerate().filter(|&(channel, _)| channel != 2) { + assert!( + other < center / 100.0, + "channel {channel} should be near silent: {energy:?}" + ); + } +} diff --git a/rs/moq-audio/tests/roundtrip.rs b/rs/moq-audio/tests/roundtrip.rs index 570dacac45f..55e09bfab39 100644 --- a/rs/moq-audio/tests/roundtrip.rs +++ b/rs/moq-audio/tests/roundtrip.rs @@ -203,3 +203,71 @@ async fn pcm_round_trip_is_lossless() { assert_eq!(decoded, samples); assert!(consumer.read().await.unwrap().is_none()); } + +/// A 5.1 broadcast carries only its channel count in the catalog, which reads +/// back as 5.1 in canonical order and remixes to whatever the subscriber asks +/// for. +#[tokio::test] +async fn pcm_five_one_reads_back_at_any_layout() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let mut catalog_consumer = catalog.consume().unwrap(); + let broadcast_consumer = broadcast.consume(); + + let input = encode::Input::new(48_000, Layout::FivePointOne); + let mut options = encode::Options::default(); + options.track = Some("pcm".to_string()); + options.settings = encode::Settings::new(48_000, Layout::FivePointOne); + options.settings.codec = encode::Codec::Pcm; + + // A level per speaker: left, right, center, LFE, side left, side right. + let speakers = [0.1f32, 0.2, 0.3, 0.4, 0.05, 0.06]; + let mut producer = encode::Producer::new(&mut broadcast, catalog.clone(), input, &options).unwrap(); + producer + .write(&Frame::new( + f32_bytes(&speakers.repeat(960)), + Timestamp::from_micros(0).unwrap(), + )) + .unwrap(); + + let snapshot = catalog_consumer.next().await.unwrap().unwrap(); + let rendition = snapshot.audio.renditions.get("pcm").unwrap(); + assert_eq!(rendition.channel_count, 6); + + let h = std::f32::consts::FRAC_1_SQRT_2; + let left = 0.1 + h * 0.3 + h * 0.05; + let right = 0.2 + h * 0.3 + h * 0.06; + let cases = [ + (None, Layout::FivePointOne, speakers.to_vec()), + (Some(Layout::Stereo), Layout::Stereo, vec![left, right]), + (Some(Layout::Mono), Layout::Mono, vec![(left + right) * 0.5]), + ]; + + let mut consumers = Vec::new(); + for (output, _, _) in &cases { + let mut options = decode::Options::default(); + options.output.layout = *output; + consumers.push( + decode::Consumer::new(&broadcast_consumer, rendition, "pcm", options) + .await + .unwrap(), + ); + } + producer.finish().unwrap(); + + for (mut consumer, (_, layout, frame)) in consumers.into_iter().zip(cases) { + assert_eq!(consumer.layout(), layout); + let decoded = consumer.read().await.unwrap().unwrap(); + let samples: Vec = decoded + .data + .as_chunks::<4>() + .0 + .iter() + .map(|sample| f32::from_le_bytes([sample[0], sample[1], sample[2], sample[3]])) + .collect(); + assert_eq!(samples.len(), 960 * frame.len(), "{layout:?}"); + for (got, want) in samples.iter().zip(frame.iter().cycle()) { + assert!((got - want).abs() < 1e-6, "{layout:?}: got {got}, want {want}"); + } + } +} diff --git a/rs/moq-auth/CHANGELOG.md b/rs/moq-auth/CHANGELOG.md index 20fd5c973d5..088e9e919d1 100644 --- a/rs/moq-auth/CHANGELOG.md +++ b/rs/moq-auth/CHANGELOG.md @@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0](https://github.com/moq-dev/moq/compare/moq-auth-v0.1.5...moq-auth-v0.2.0) - 2026-09-30 + +### Added + +- *(net)* read a subtree through an origin mount ([#4271](https://github.com/moq-dev/moq/pull/4271)) + +### Fixed + +- *(hls,auth)* redact credentials from URLs in errors ([#4536](https://github.com/moq-dev/moq/pull/4536)) +- *(auth)* make grant expiry exact, dropping the clock-skew grace ([#4368](https://github.com/moq-dev/moq/pull/4368)) +- *(auth)* admit a SETUP token equal to the jwt query ([#4359](https://github.com/moq-dev/moq/pull/4359)) +- *(auth)* [**breaking**] restore 0.14 auth parity ([#4319](https://github.com/moq-dev/moq/pull/4319)) + +### Other + +- *(auth)* run the outage tests on a paused clock without sockets ([#4527](https://github.com/moq-dev/moq/pull/4527)) + ## [0.1.5](https://github.com/moq-dev/moq/compare/moq-auth-v0.1.4...moq-auth-v0.1.5) - 2026-09-27 ### Added diff --git a/rs/moq-auth/Cargo.toml b/rs/moq-auth/Cargo.toml index 417398bcaa6..fa40b782a70 100644 --- a/rs/moq-auth/Cargo.toml +++ b/rs/moq-auth/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.5" +version = "0.2.0" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-auth/src/client.rs b/rs/moq-auth/src/client.rs index 12484d3e5f2..21d1560c6a1 100644 --- a/rs/moq-auth/src/client.rs +++ b/rs/moq-auth/src/client.rs @@ -40,7 +40,7 @@ impl Client { None => false, }; if !loopback { - return Err(Error::InsecureUrl(url.to_string())); + return Err(Error::InsecureUrl(redact(&url))); } (builder, url) } @@ -50,12 +50,12 @@ impl Client { }, #[cfg(unix)] "unix" => { - let path = url.to_file_path().map_err(|()| Error::InvalidUrl(url.to_string()))?; + let path = url.to_file_path().map_err(|()| Error::InvalidUrl(redact(&url)))?; // The socket is the transport; the request target is the server's root. let target = Url::parse("http://localhost/").expect("a constant URL parses"); (builder.unix_socket(path), target) } - _ => return Err(Error::InvalidUrl(url.to_string())), + _ => return Err(Error::InvalidUrl(redact(&url))), }; Ok(Self { @@ -67,25 +67,24 @@ impl Client { /// Admit a session: POST `connect`, validate the reply, and return the lease the /// session holds. The session reports totals through [`lease::Consumer::close`]. pub async fn connect(&self, request: Request) -> crate::Result { - let mut request = request; - request.event = Event::Connect; - - let grant = self.post(&request).await?; - let (producer, consumer) = lease::Producer::new(grant.clone()); + connect(self.clone(), request).await + } +} - let driver = Driver { - client: self.clone(), - request, - producer: Some(producer), - started: Instant::now(), - }; - tokio::spawn(driver.run()); +/// Where a lease's requests go: the auth server over HTTP, or an in-process +/// answer in tests, so the lease's timers run on Tokio's paused clock with no +/// socket for them to outrun. +trait Post: Clone + Send + Sync + 'static { + /// Send a `connect` or `revalidate`: the grant as answered, not yet validated, + /// a refusal, or an outage. + fn post(&self, request: &Request) -> impl Future> + Send; - Ok(consumer) - } + /// Send the `end`. + fn post_end(&self, request: &Request) -> impl Future> + Send; +} - /// One POST: a 2xx with a valid grant admits, a 401 or 403 refuses, a 2xx - /// whose grant fails validation is that error, and everything else is an +impl Post for Client { + /// A 2xx carries the grant, a 401 or 403 refuses, and everything else is an /// outage the caller decides about. async fn post(&self, request: &Request) -> crate::Result { let response = self.http.post(self.url.clone()).json(request).send().await?; @@ -96,25 +95,69 @@ impl Client { if !status.is_success() { return Err(Error::Unavailable(format!("auth server answered {status}"))); } - let grant: Grant = response.json().await?; - grant.validate().map_err(|err| match err { - // An empty grant is a refusal, not a malformed answer. - Error::UselessGrant => Error::Refused, - other => other, - })?; - Ok(grant) + Ok(response.json().await?) + } + + async fn post_end(&self, request: &Request) -> crate::Result<()> { + self.http + .post(self.url.clone()) + .json(request) + .send() + .await? + .error_for_status()?; + Ok(()) } } +/// Admit a session through `server` and spawn the driver behind its lease. +async fn connect(server: S, mut request: Request) -> crate::Result { + request.event = Event::Connect; + + let grant = ask(&server, &request).await?; + let (producer, consumer) = lease::Producer::new(grant.clone()); + + let driver = Driver { + server, + request, + producer: Some(producer), + started: Instant::now(), + }; + tokio::spawn(driver.run()); + + Ok(consumer) +} + +/// One `connect` or `revalidate`: a valid grant admits, and one that fails +/// validation is that error. +async fn ask(server: &S, request: &Request) -> crate::Result { + let grant = server.post(request).await?; + grant.validate().map_err(|err| match err { + // An empty grant is a refusal, not a malformed answer. + Error::UselessGrant => Error::Refused, + other => other, + })?; + Ok(grant) +} + +/// `url` without its userinfo, query, or fragment, any of which may carry a credential. +fn redact(url: &Url) -> String { + let mut url = url.clone(); + let _ = url.set_username(""); + let _ = url.set_password(None); + url.set_query(None); + url.set_fragment(None); + url.to_string() +} + /// The task behind a lease: re-checks on cadence and reports the end. -struct Driver { - client: Client, +struct Driver { + server: S, request: Request, producer: Option, started: Instant, } -impl Driver { +impl Driver { async fn run(mut self) { let (reason, bytes) = self.drive().await; @@ -125,7 +168,7 @@ impl Driver { bytes, }; // The session is already gone; nothing to do with a failure but say so. - if let Err(err) = self.client.post_end(&request).await { + if let Err(err) = self.server.post_end(&request).await { tracing::warn!(id = %request.id, %err, "failed to report the session end"); } } @@ -179,22 +222,10 @@ impl Driver { } fn post_revalidate(&self) -> Pin> + Send>> { - let client = self.client.clone(); + let server = self.server.clone(); let mut request = self.request.clone(); request.event = Event::Revalidate; - Box::pin(async move { client.post(&request).await }) - } -} - -impl Client { - async fn post_end(&self, request: &Request) -> crate::Result<()> { - self.http - .post(self.url.clone()) - .json(request) - .send() - .await? - .error_for_status()?; - Ok(()) + Box::pin(async move { ask(&server, &request).await }) } } @@ -266,34 +297,42 @@ mod tests { server } - /// Keep HTTP handling on the paused test clock instead of wiremock's separate runtime. - async fn clock_server(log: Log, grant: Grant, stall: bool) -> Client { - use axum::{Json, Router, extract::State, http::StatusCode, response::IntoResponse, routing::post}; - let router = Router::new() - .route( - "/", - post( - |State((log, grant, stall)): State<(Log, Grant, bool)>, Json(request): Json| async move { - let event = request.event.clone(); - log.0.lock().push(request); - match event { - Event::Connect => Json(grant).into_response(), - Event::Revalidate if stall => std::future::pending().await, - Event::Revalidate => StatusCode::SERVICE_UNAVAILABLE.into_response(), - Event::End { .. } => StatusCode::OK.into_response(), - } - }, - ), - ) - .with_state((log, grant, stall)); - let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); - let url = format!("http://{}/", listener.local_addr().unwrap()); - tokio::spawn(async move { axum::serve(listener, router).await.unwrap() }); - // Only the lease clock is under test; an HTTP timeout can auto-advance - // Tokio's paused clock before loopback I/O gets its first reactor turn. - Client { - http: reqwest::Client::builder().no_proxy().build().unwrap(), - url: url.parse().unwrap(), + /// An in-process auth server for tests on Tokio's paused clock: it logs each + /// request and answers with `respond`, never when that returns `None`. With no + /// socket, the clock only advances once every answer has landed. + #[derive(Clone)] + struct Script { + log: Log, + #[allow(clippy::type_complexity)] + respond: std::sync::Arc Option> + Send + Sync>, + } + + impl Script { + fn new(log: Log, respond: impl Fn(&Request) -> Option> + Send + Sync + 'static) -> Self { + Self { + log, + respond: std::sync::Arc::new(respond), + } + } + + async fn connect(&self) -> crate::Result { + connect(self.clone(), request()).await + } + } + + impl Post for Script { + async fn post(&self, request: &Request) -> crate::Result { + self.log.0.lock().push(request.clone()); + let answer = (self.respond)(request); + match answer { + Some(answer) => answer, + None => std::future::pending().await, + } + } + + async fn post_end(&self, request: &Request) -> crate::Result<()> { + self.log.0.lock().push(request.clone()); + Ok(()) } } @@ -379,6 +418,23 @@ mod tests { assert!(matches!(err, Error::Refused), "{err}"); } + #[tokio::test] + async fn http_error_redacts_url() { + // A freed port refuses the connection, so reqwest fails with the dialed URL attached. + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind"); + let address = listener.local_addr().expect("local address"); + drop(listener); + + let url = format!("http://user:pass@{address}/?jwt=secret").parse().unwrap(); + let err = Client::new(url, None).unwrap().connect(request()).await.unwrap_err(); + + assert!(matches!(err, Error::Unavailable(_)), "unexpected error: {err}"); + let printed = format!("{err} {err:?}"); + for secret in ["jwt", "secret", "user:pass"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } + #[tokio::test] async fn revalidate_runs_on_cadence_and_applies_the_reply() { let log = Log::default(); @@ -447,25 +503,32 @@ mod tests { tokio::time::pause(); let mut grant = Grant::new(patterns(&["**"]), Patterns::new()); grant.expires = Some(SystemTime::now() - Duration::from_secs(1)); - let client = clock_server(Log::default(), grant, false).await; - assert!(matches!(client.connect(request()).await, Err(Error::GrantExpired))); + let script = Script::new(Log::default(), move |_| Some(Ok(grant.clone()))); + assert!(matches!(script.connect().await, Err(Error::GrantExpired))); } + /// An outage is evidence of nothing: the grant stands through failed re-checks + /// until `expires`, and closes then, not later. #[tokio::test] - async fn a_grant_closes_at_its_expiry() { + async fn an_outage_keeps_the_grant_until_expires() { tokio::time::pause(); - // Whole seconds, as the grant crosses the wire, so the client sees this exact instant. - // An hour out, so a slow runner cannot expire it before `connect` answers. - let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap(); - let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(now.as_secs() + 3600); - let mut grant = Grant::new(patterns(&["**"]), Patterns::new()); - grant.expires = Some(expires); - let client = clock_server(Log::default(), grant, false).await; + let expires = SystemTime::now() + Duration::from_secs(3); + let log = Log::default(); + let script = Script::new(log.clone(), move |request| { + Some(match request.event { + Event::Connect => { + let mut grant = grant(None, Some(Duration::from_secs(1))); + grant.expires = Some(expires); + Ok(grant) + } + _ => Err(Error::Unavailable("auth server answered 503".into())), + }) + }); - // The client reads both clocks somewhere inside `connect`, so bracket it: the - // bounds hold however long it takes. + // `expires` is wall-clock time, which the client maps onto Tokio's clock + // somewhere inside `connect`, so bracket it: the bounds hold however long it takes. let (wall, tick) = (SystemTime::now(), tokio::time::Instant::now()); - let consumer = client.connect(request()).await.unwrap(); + let consumer = script.connect().await.unwrap(); let earliest = tick + expires.duration_since(SystemTime::now()).unwrap(); let latest = tokio::time::Instant::now() + expires.duration_since(wall).unwrap(); @@ -475,51 +538,18 @@ mod tests { tokio::time::timeout_at(earliest - tolerance, consumer.closed()) .await .is_err(), - "live until its expiry" - ); - let reason = tokio::time::timeout_at(latest + tolerance, consumer.closed()) - .await - .expect("closed at its expiry, not later"); - assert_eq!(reason, Reason::Expired); - } - - /// On the real clock: a paused one jumps to the expiry timer whenever the runtime - /// waits on a socket, and macOS delivers loopback asynchronously, so the lease can - /// expire and drop the re-check before the server sees it. Load only delays the - /// close, so asserting it never lands before `expires` holds on a busy machine. - #[tokio::test] - async fn an_outage_keeps_the_grant_until_expires() { - // Whole seconds, as the grant crosses the wire, so the client sees this exact instant. - let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap(); - let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(now.as_secs() + 3); - - let log = Log::default(); - let server = server(log.clone(), move |request| match request.event { - Event::Connect => { - let mut grant = grant(None, Some(Duration::from_secs(1))); - grant.expires = Some(expires); - ResponseTemplate::new(200).set_body_json(grant) - } - Event::Revalidate => ResponseTemplate::new(503), - Event::End { .. } => ResponseTemplate::new(200), - }) - .await; - let consumer = client(&server).connect(request()).await.unwrap(); - - let reason = tokio::time::timeout(Duration::from_secs(10), consumer.closed()) - .await - .expect("expired"); - assert_eq!(reason, Reason::Expired); - assert!(SystemTime::now() >= expires, "an outage must not close before expires"); - assert!( - log.revalidates() >= 1, - "no re-check reached the server during the outage" + "an outage must not close before expires" ); + assert!(log.revalidates() >= 1, "the outage was answered before expires"); assert_eq!( consumer.grant().publish, patterns(&["**"]), "the grant stands through the outage" ); + let reason = tokio::time::timeout_at(latest + tolerance, consumer.closed()) + .await + .expect("closed at expires, not later"); + assert_eq!(reason, Reason::Expired); assert!(matches!( log.end().await.event, Event::End { @@ -532,13 +562,11 @@ mod tests { #[tokio::test] async fn expiry_fires_while_a_recheck_is_stalled() { tokio::time::pause(); - let client = clock_server( - Log::default(), - grant(Some(Duration::from_secs(3)), Some(Duration::from_secs(1))), - true, - ) - .await; - let consumer = client.connect(request()).await.unwrap(); + let script = Script::new(Log::default(), |request| match request.event { + Event::Connect => Some(Ok(grant(Some(Duration::from_secs(3)), Some(Duration::from_secs(1))))), + _ => None, + }); + let consumer = script.connect().await.unwrap(); let reason = tokio::time::timeout(Duration::from_secs(5), consumer.closed()) .await @@ -588,6 +616,19 @@ mod tests { )); #[cfg(unix)] assert!(Client::new("unix:///run/moq-auth.sock".parse().unwrap(), None).is_ok()); + + // The refused URL is reported, minus anything that may carry a credential. + for url in [ + "http://user:pass@auth.example/?jwt=secret#frag", + "ftp://user:pass@auth.example/?jwt=secret#frag", + ] { + let err = Client::new(url.parse().unwrap(), None).err().expect("refused"); + let printed = format!("{err} {err:?}"); + assert!(printed.contains("auth.example/"), "{printed}"); + for secret in ["jwt", "secret", "user", "pass", "frag"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } } /// Backoff leaves the driver in this same state (nothing in flight, a timer armed), diff --git a/rs/moq-auth/src/error.rs b/rs/moq-auth/src/error.rs index fcd36d3496d..c32d0d06b16 100644 --- a/rs/moq-auth/src/error.rs +++ b/rs/moq-auth/src/error.rs @@ -178,8 +178,12 @@ from_message! { } #[cfg(feature = "client")] -from_message! { - reqwest::Error => Unavailable, +impl From for Error { + fn from(err: reqwest::Error) -> Self { + // reqwest prints the full URL in its error, and a dialed URL can carry + // credentials in its query or userinfo. + Self::Unavailable(message(err.without_url())) + } } pub type Result = std::result::Result; diff --git a/rs/moq-boy/CHANGELOG.md b/rs/moq-boy/CHANGELOG.md index 5aed50492d3..289a77154ac 100644 --- a/rs/moq-boy/CHANGELOG.md +++ b/rs/moq-boy/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.9](https://github.com/moq-dev/moq/compare/moq-boy-v0.5.8...moq-boy-v0.5.9) - 2026-09-30 + +### Other + +- update Cargo.lock dependencies + ## [0.5.8](https://github.com/moq-dev/moq/compare/moq-boy-v0.5.7...moq-boy-v0.5.8) - 2026-09-27 ### Other diff --git a/rs/moq-boy/Cargo.toml b/rs/moq-boy/Cargo.toml index 71be7defbfe..53102aa218f 100644 --- a/rs/moq-boy/Cargo.toml +++ b/rs/moq-boy/Cargo.toml @@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0" keywords = ["moq", "gameboy", "streaming", "emulator", "live"] categories = ["multimedia::video", "emulators", "network-programming"] -version = "0.5.8" +version = "0.5.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-c/CHANGELOG.md b/rs/moq-c/CHANGELOG.md index e633377dfcb..6324f5616d1 100644 --- a/rs/moq-c/CHANGELOG.md +++ b/rs/moq-c/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.9](https://github.com/moq-dev/moq/compare/libmoq-v0.6.8...libmoq-v0.6.9) - 2026-09-30 + +### Fixed + +- *(net)* an origin::Dynamic keeps its origin alive ([#4417](https://github.com/moq-dev/moq/pull/4417)) +- *(libmoq)* render moq.pc only when packaging ([#4372](https://github.com/moq-dev/moq/pull/4372)) +- *(libmoq)* open extern "C" in the generated moq.h ([#4350](https://github.com/moq-dev/moq/pull/4350)) + ## [0.6.8](https://github.com/moq-dev/moq/compare/libmoq-v0.6.7...libmoq-v0.6.8) - 2026-09-27 ### Other diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 809a4c53ab3..4f74abdaf4b 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -491,8 +491,8 @@ pub struct moq_datagram { /// Publisher-side raw track properties. /// /// A null [moq_publish_track] `info` pointer uses the moq-net defaults. -/// A zero-initialized struct also uses those defaults, except `priority` where -/// zero is the default itself. +/// A zero-initialized struct also uses those defaults, except `priority`, which +/// has no presence flag: zero is the least urgent, and 127 is the moq-net default. #[repr(C)] #[allow(non_camel_case_types)] pub struct moq_track_info { @@ -3652,7 +3652,7 @@ pub extern "C" fn moq_consume_track_cancel(track: u32) -> i32 { /// touched again, so release `user_data` there. The terminal callback fires even after /// [moq_consume_datagrams_cancel]. Read each datagram with [moq_consume_datagram] and release /// it with [moq_consume_datagram_free]. Datagrams arrive only over datagram-capable -/// transports and lite-05 or newer moq-lite; there is no stream fallback. +/// transports on moq-transport or lite-05 and newer moq-lite; there is no stream fallback. /// /// Returns a non-zero handle to the subscription on success, or a negative code on failure. /// diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index b23a57c18e0..21d3b1c2257 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -67,6 +67,9 @@ pub struct moq_audio_encoder_input { /// `moq_audio_sample_format` discriminant. pub format: u32, pub sample_rate: u32, + /// Interleaved channel count, which also names the speaker layout by the + /// WAVE convention: 1 mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, + /// 8 7.1, in front left, front right, center, LFE, back, side order. pub channels: u32, } @@ -76,7 +79,8 @@ pub struct moq_audio_encoder_input { #[repr(C)] #[allow(non_camel_case_types)] pub struct moq_audio_encoder_output { - /// Codec id, UTF-8 (currently only "opus"). + /// Codec id, UTF-8: "opus", "pcm", or "aac". AAC encodes through the + /// platform's encoder, so a host without one refuses it. pub codec: *const c_char, pub codec_len: usize, /// 0 = derive from input. @@ -86,8 +90,8 @@ pub struct moq_audio_encoder_output { /// 0 = libopus default. pub bitrate: u32, /// Encoded frame duration in microseconds. Opus accepts exactly - /// 2500/5000/10000/20000/40000/60000 us. 0 = the 20 ms default, which - /// matches the JS publish path. + /// 2500/5000/10000/20000/40000/60000 us. 0 = the codec's default: 20 ms for + /// Opus, which matches the JS publish path, and 1024 samples for AAC. pub frame_duration_us: u32, } @@ -98,7 +102,9 @@ pub struct moq_audio_decoder_output { pub format: u32, /// 0 = deliver at the codec's native sample rate. pub sample_rate: u32, - /// 0 = deliver at the codec's native channel count. + /// 0 = deliver at the codec's native channel count. A count names its + /// layout as `moq_audio_encoder_input.channels` describes, and the decoder + /// remixes to it. pub channels: u32, /// Upper bound on buffering before skipping a stalled group, in /// microseconds. Same congestion-control knob as diff --git a/rs/moq-cli/CHANGELOG.md b/rs/moq-cli/CHANGELOG.md index 30b677f4948..26e7e140565 100644 --- a/rs/moq-cli/CHANGELOG.md +++ b/rs/moq-cli/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.13.0](https://github.com/moq-dev/moq/compare/moq-cli-v0.12.8...moq-cli-v0.13.0) - 2026-09-30 + +### Added + +- *(srt)* select a program of a multi-program feed ([#4569](https://github.com/moq-dev/moq/pull/4569)) +- *(cli)* linger export ts across a broadcast that leaves and returns ([#4504](https://github.com/moq-dev/moq/pull/4504)) +- *(ts)* import one program of a multiplex, or each as its own broadcast ([#4505](https://github.com/moq-dev/moq/pull/4505)) +- *(srt)* log the TS importer's per-stream counters on ingest ([#4506](https://github.com/moq-dev/moq/pull/4506)) +- *(mux)* report every TS elementary stream's access units and quiet time ([#4502](https://github.com/moq-dev/moq/pull/4502)) +- *(net)* drain queued stream data before a graceful close ([#4430](https://github.com/moq-dev/moq/pull/4430)) + +### Fixed + +- *(cli)* refuse every MoQ-side flag a verb never reads ([#4419](https://github.com/moq-dev/moq/pull/4419)) +- *(cli)* refuse a client CA under --auth-public on a listener ([#4364](https://github.com/moq-dev/moq/pull/4364)) +- *(cli)* schedule play decode by the earliest owed picture ([#4374](https://github.com/moq-dev/moq/pull/4374)) +- *(auth)* [**breaking**] restore 0.14 auth parity ([#4319](https://github.com/moq-dev/moq/pull/4319)) + +### Other + +- flush quiet audio in the documented ffmpeg MPEG-TS line ([#4514](https://github.com/moq-dev/moq/pull/4514)) + ## [0.12.8](https://github.com/moq-dev/moq/compare/moq-cli-v0.12.7...moq-cli-v0.12.8) - 2026-09-27 ### Fixed diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index bfec48b6f45..1d93822e90b 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.12.8" +version = "0.13.0" edition = "2024" # Depends on moq-relay, whose sysinfo 0.39 needs 1.95, above the 1.91 workspace # floor. This binary is an application, so the bump stays here rather than @@ -130,6 +130,8 @@ sd-notify = { workspace = true } moq-msf = { path = "../moq-msf" } # `test_relay` stands up a real relay for the `fetch` tests to read through. moq-relay = { path = "../moq-relay", default-features = false, features = ["test-support"] } +# Writes the PAT and PMTs, CRCs included, of the two-program input `import ts --program all` splits. +mpeg2ts = "0.6.0" tempfile = { workspace = true } # `test-util` enables `tokio::time::pause` so the TS round-trip test simulates the # exporter drain timeouts instantly instead of waiting on the wall clock. diff --git a/rs/moq-cli/README.md b/rs/moq-cli/README.md index de0241a778b..8d68d1be713 100644 --- a/rs/moq-cli/README.md +++ b/rs/moq-cli/README.md @@ -32,7 +32,7 @@ moq --connect https://relay.example.com/anon \ ### Publish to a remote relay ```bash -ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ +ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - | \ moq --connect https://relay.example.com --broadcast my-stream.hang import ts ``` @@ -54,8 +54,8 @@ moq --connect https://relay.example.com --broadcast my-stream.hang play Hosts a MoQ server and publishes a single broadcast read from stdin into it. Useful for local testing without a separate relay process. ```bash -ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ - moq --listen '[::]:4443' --listen-tls-generate localhost --broadcast my-stream.hang import ts +ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - | \ + moq --listen '[::]:4443' --listen-tls-generate localhost --auth-public '**' --broadcast my-stream.hang import ts ``` ### Self-host: subscribe to an inbound broadcast @@ -63,7 +63,7 @@ ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ Hosts a MoQ server and writes an incoming broadcast's media to stdout. The inverse of the above. ```bash -moq --listen '[::]:4443' --listen-tls-generate localhost --broadcast my-stream.hang export ts | ffplay - +moq --listen '[::]:4443' --listen-tls-generate localhost --auth-public '**' --broadcast my-stream.hang export ts | ffplay - ``` ### Import formats diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 5e50b6e8c2e..4379abc1730 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -285,6 +285,17 @@ impl Invocation { /// 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<()> { + for command in &self.stages { + if let Command::Export(export) = command + && let Some(stdout) = export.sink.stdout() + { + anyhow::ensure!( + stdout.linger.is_zero() || matches!(stdout.format, SubscribeFormat::Ts), + "--linger needs an output that can mark a restart, and only `export ts` can" + ); + } + } + // One stage is what the CLI has always run, so nothing below can bite. if self.stages.len() == 1 { return Ok(()); @@ -734,7 +745,7 @@ pub enum ImportSource { /// Fragmented MP4 / CMAF from stdin. Fmp4, /// MPEG-TS from stdin. - Ts, + Ts(TsImport), /// FLV / RTMP container from stdin. Flv, /// Pull a remote HLS / LL-HLS playlist (http/https URL or local file) into MoQ. @@ -742,7 +753,7 @@ pub enum ImportSource { /// RTMP: pull a remote play (`--connect`) or accept incoming publishes (`--listen`). Rtmp(crate::rtmp::Args), /// SRT: pull a remote stream (`--connect`) or accept incoming publishes (`--listen`). - Srt(crate::srt::Args), + Srt(crate::srt::ImportArgs), /// WebRTC: WHEP client pulling a remote (`--connect`) or WHIP server accepting publishes (`--listen`). Rtc(crate::rtc::Args), /// Capture a local source (camera, display, window, app, microphone) and @@ -757,13 +768,60 @@ impl ImportSource { Some(match self { Self::Avc3 => PublishFormat::Avc3, Self::Fmp4 => PublishFormat::Fmp4, - Self::Ts => PublishFormat::Ts, + Self::Ts(args) => PublishFormat::Ts { + program: args.program.and_then(TsProgram::number), + }, Self::Flv => PublishFormat::Flv, _ => return None, }) } } +/// The MPEG-TS stdin container: which programs of a multiplex to publish. +#[derive(usage::Args, Clone)] +#[usage(unknown_flags = "error", args_override_self = false)] +pub struct TsImport { + /// Import one program of a multi-program stream, by its PAT program number, or `all` to + /// publish each program as its own broadcast (`event.hang` becomes `event/1.hang`, + /// `event/2.hang`, ...). Without it, a stream carrying more than one program is refused. + #[usage(long)] + pub program: Option, +} + +/// An `import ts --program` or `import srt --program` value. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum TsProgram { + /// The program with this PAT program number. + One(u16), + /// Every program, each as its own broadcast. + All, +} + +impl TsProgram { + /// The single program selected, `None` for `all`. + fn number(self) -> Option { + match self { + Self::One(program) => Some(program), + Self::All => None, + } + } +} + +impl std::str::FromStr for TsProgram { + type Err = String; + + fn from_str(arg: &str) -> Result { + match arg { + "all" => Ok(Self::All), + _ => match arg.parse() { + Ok(0) => Err("program 0 is the network PID, not a program".to_string()), + Ok(program) => Ok(Self::One(program)), + Err(_) => Err(format!("expected a program number or `all`, got `{arg}`")), + }, + } + } +} + // ------------------------------------------------------------------ export /// export = MoQ -> one sink. @@ -852,6 +910,7 @@ impl ExportSink { let container = |format, container: &Container| Stdout { format, max_age: container.max_age.into_std(), + linger: container.linger.into_std(), fragment_duration: None, mux_rate: None, }; @@ -880,6 +939,7 @@ impl ExportSink { pub struct Stdout { pub format: SubscribeFormat, pub max_age: Duration, + pub linger: Duration, pub fragment_duration: Option, pub mux_rate: Option, } @@ -892,6 +952,11 @@ pub struct Container { #[usage(long, default = "500ms")] pub max_age: crate::duration::Duration, + /// How long to wait for the broadcast to come back once it ends (e.g. `10s`). + /// `ts` only; the output stops while it is gone and resumes flagged as a break. + #[usage(long, default = "0s")] + pub linger: crate::duration::Duration, + /// The released spelling of [`Self::max_age`]. #[usage(long = "latency-max", hide = true)] latency_max: Option, @@ -962,6 +1027,62 @@ mod tests { assert!(cli.validate().is_ok()); } + /// Only TS can mark where a returned broadcast restarts, so only `export ts` may linger. + #[test] + fn linger_is_ts_only() { + let parse = |format: &str, linger: &str| { + Invocation::try_parse_from(["moq", "--connect", "http://relay", "export", format, "--linger", linger]) + .unwrap() + }; + assert!(parse("ts", "10s").validate().is_ok()); + for format in ["fmp4", "mkv", "flv", "h264", "h265"] { + let err = parse(format, "10s").validate().unwrap_err().to_string(); + assert!(err.contains("--linger"), "{format}: {err}"); + assert!( + parse(format, "0s").validate().is_ok(), + "{format}: no linger is always fine" + ); + } + } + + #[test] + fn import_ts_takes_a_program_number_or_all() { + // `None` when the command line is refused. + let program = |value: &str| { + let cli = Invocation::try_parse_from(["moq", "import", "ts", "--program", value]).ok()?; + let Command::Import(import) = &cli.stages[0] else { + panic!("an import stage"); + }; + let ImportSource::Ts(args) = &import.source else { + panic!("an import ts stage"); + }; + Some(args.program) + }; + assert_eq!(program("2"), Some(Some(TsProgram::One(2)))); + assert_eq!(program("all"), Some(Some(TsProgram::All))); + assert_eq!(program("0"), None, "0 is the network PID"); + assert_eq!(program("two"), None); + } + + /// `import srt` takes the same `--program` as `import ts`; `export srt` has no program to pick. + #[test] + fn import_srt_takes_a_program() { + let cli = + Invocation::try_parse_from(["moq", "import", "srt", "--listen", "[::]:9000", "--program", "all"]).unwrap(); + let Command::Import(import) = &cli.stages[0] else { + panic!("an import stage"); + }; + let ImportSource::Srt(args) = &import.source else { + panic!("an import srt stage"); + }; + assert_eq!(args.program(), Some(moq_srt::Program::All)); + assert!(args.endpoint.listen.is_some()); + + assert!( + Invocation::try_parse_from(["moq", "export", "srt", "--listen", "[::]:9000", "--program", "2"]).is_err() + ); + } + /// A released spelling is refused, and the error names what to write instead. /// /// The alternative is what this replaced: the flag parsed onto a hidden field, @@ -1487,9 +1608,11 @@ mod tests { assert!(err.contains(reported), "{err}"); } - let cli = Invocation::try_parse_from(["moq", "--cluster-mesh", "auth", "generate"]).unwrap(); - let err = cli.reject("auth").unwrap_err().to_string(); - assert!(err.contains("--cluster-mesh"), "{err}"); + // Gossip discovery is removed, so its flag is refused for every verb. + let Err(err) = Invocation::try_parse_from(["moq", "--cluster-mesh", "auth", "generate"]) else { + panic!("--cluster-mesh must be refused"); + }; + assert!(err.to_string().contains("--cluster-mesh"), "{err}"); #[cfg(unix)] { diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index c51b95a0d74..a4394934b87 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -26,7 +26,7 @@ mod test_env; mod transcode; mod web; -use args::{Command, Export, ExportSink, Import, ImportSource, Invocation, MoqSide}; +use args::{Command, Export, ExportSink, Import, ImportSource, Invocation, MoqSide, TsImport, TsProgram}; use hang::moq_net; use publish::Publish; use subscribe::{Subscribe, SubscribeArgs}; @@ -635,11 +635,19 @@ fn spawn_import( if let Some(format) = import.source.stdin_format() { warn_if_missing_format(&name); - let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; let config = moq_mux::catalog::Config::default() .with_max_age(max_age) .with_bandwidth(bandwidth.clone()); - let publish = Publish::new(broadcast, &format, config)?; + let publish = if let ImportSource::Ts(TsImport { + program: Some(TsProgram::All), + }) = &import.source + { + let name = require_broadcast(name, "import ts --program all")?; + Publish::ts_programs(origin.clone(), name, config) + } else { + let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; + Publish::new(broadcast, &format, config)? + }; publish.announce()?; local = Some(publish); } else { @@ -657,11 +665,13 @@ fn spawn_import( } } ImportSource::Srt(srt) => { + let program = srt.program(); + let srt = srt.endpoint; if let Some(addr) = srt.listen { let name = require_broadcast(name, "import srt --listen")?; - tasks.spawn(srt::listen_import(target(name), addr, srt.latency.into_std())); + tasks.spawn(srt::listen_import(target(name), addr, srt.latency.into_std(), program)); } else if let Some(url) = srt.connect { - tasks.spawn(srt::connect_import(target(name), url, srt.latency.into_std())); + tasks.spawn(srt::connect_import(target(name), url, srt.latency.into_std(), program)); } } ImportSource::Rtc(rtc) => { @@ -712,6 +722,7 @@ fn spawn_export( let args = SubscribeArgs { format: stdout.format, max_age: stdout.max_age, + linger: stdout.linger, fragment_duration: stdout.fragment_duration, mux_rate: stdout.mux_rate, catalog: export.catalog_format, diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index fec8b15c9f4..9734e002834 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -234,7 +234,7 @@ impl Media { decode.output.format = moq_audio::Format::F32; match moq_audio::decode::Consumer::new(&rendition, &config, &name, decode).await { Ok(consumer) => { - tracing::info!(track = name, "playing audio rendition"); + tracing::info!(track = name, decoder = consumer.name(), "playing audio rendition"); if speaker.is_none() { speaker = Some(self.output.speaker().await?); } diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 5b95e763bb1..c6192604a98 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -9,8 +9,8 @@ pub enum PublishFormat { Avc3, /// Fragmented MP4 (CMAF). Fmp4, - /// MPEG-TS (transport stream). - Ts, + /// MPEG-TS (transport stream), limited to one `program` of a multiplex when given. + Ts { program: Option }, /// FLV (Flash Video / RTMP). Flv, } @@ -132,29 +132,6 @@ pub struct CaptureArgs { pub no_audio: bool, } -/// Report the streams whose frame-sync counters moved since `previous`, one line each. -/// -/// The importer already warns on each individual resync; this is the running total, which is -/// what an operator turns into a rate. -fn log_stats(latest: Option<&ts::Stats>, previous: Option<&ts::Stats>) { - let Some(latest) = latest else { - return; - }; - for (pid, stream) in &latest.streams { - if previous.and_then(|previous| previous.streams.get(pid)) == Some(stream) { - continue; - } - tracing::info!( - pid = *pid, - track = stream.track, - resyncs = stream.resyncs, - discarded = stream.discarded, - unconfirmed = stream.unconfirmed, - "audio frame sync lost" - ); - } -} - enum PublishDecoder { Avc3 { split: Box, @@ -164,6 +141,8 @@ enum PublishDecoder { // TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) // verbatim, so it uses the `mpegts` catalog extension rather than the media-only `()`. Ts(Box>), + /// `import ts --program all`: one importer, broadcast, and catalog per program. + TsPrograms(Box), Flv(Box), } @@ -178,17 +157,19 @@ impl PublishDecoder { import.decode(frames)?; } Self::Fmp4(d) => d.decode(chunk)?, - Self::Ts(d) => d.decode(chunk)?, + Self::Ts(d) => d.decode(chunk).map_err(suggest_program)?, + Self::TsPrograms(d) => d.decode(chunk)?, Self::Flv(d) => d.decode(chunk)?, } Ok(()) } - /// Audio frame sync the decoder has lost so far, for the formats that scan for it. - /// `None` where the container frames audio explicitly and so can't lose sync. + /// What each elementary stream has delivered and the audio frame sync lost so far, for + /// the formats that report it. fn stats(&self) -> Option { match self { Self::Ts(d) => Some(d.stats()), + Self::TsPrograms(d) => Some(d.stats()), Self::Avc3 { .. } | Self::Fmp4(_) | Self::Flv(_) => None, } } @@ -205,6 +186,7 @@ impl PublishDecoder { } Self::Fmp4(d) => d.finish()?, Self::Ts(d) => d.finish()?, + Self::TsPrograms(d) => d.finish()?, Self::Flv(d) => d.finish()?, } Ok(()) @@ -217,15 +199,27 @@ impl PublishDecoder { Self::Avc3 { import, .. } => import.abort(err), Self::Fmp4(d) => d.abort(err), Self::Ts(d) => d.abort(err), + Self::TsPrograms(d) => d.abort(err), Self::Flv(d) => d.abort(err), } } } +/// Point a multi-program refusal at the flag that resolves it. +fn suggest_program(err: anyhow::Error) -> anyhow::Error { + if err.is::() { + err.context("choose one with `--program `, or publish each with `--program all`") + } else { + err + } +} + /// The catalog a stdin decoder publishes into. TS carries the `mpegts` extension. enum PublishCatalog { Media(moq_mux::catalog::Producer), Ts(moq_mux::catalog::Producer), + /// `import ts --program all`: each program's catalog, finished by [`ts::Programs::finish`]. + TsPrograms, } impl PublishCatalog { @@ -234,11 +228,31 @@ impl PublishCatalog { match self { Self::Media(catalog) => catalog.finish()?, Self::Ts(catalog) => catalog.finish()?, + Self::TsPrograms => {} } Ok(()) } } +/// Build the importer and `mpegts` catalog for one TS broadcast. +/// +/// TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) verbatim, so it +/// uses the `mpegts` catalog extension rather than the media-only `()`. The catalog producer +/// owns the broadcast's catalog tracks, so each broadcast gets exactly one. +fn ts_import( + broadcast: &mut moq_net::broadcast::Producer, + config: moq_mux::catalog::Config, + program: Option, +) -> anyhow::Result<(ts::Import, moq_mux::catalog::Producer)> { + let config = config.with_catalog(moq_mux::catalog::hang::Catalog::::default()); + let catalog = moq_mux::catalog::Producer::new(broadcast, config)?; + let mut import = ts::Import::new(broadcast.clone(), catalog.reserve()); + if let Some(program) = program { + import = import.with_program(program); + } + Ok((import, catalog)) +} + // Exactly one Source exists per process, so the size gap between the small // Stream variant and the larger Capture config is irrelevant. #[allow(clippy::large_enum_variant)] @@ -254,20 +268,21 @@ enum Source { /// concurrently. #[cfg(feature = "capture")] Capture { + broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer, video: Option<(moq_video::capture::Config, moq_video::encode::Options)>, audio: Option<(moq_audio::capture::Config, moq_audio::encode::Options)>, }, } -/// A single-broadcast publisher: decodes stdin (or captures local devices) into +/// A stdin or capture publisher: decodes stdin (or captures local devices) into /// a broadcast that the MoQ side announces. pub struct Publish { source: Source, // Keeps the origin-created broadcast alive for the publisher's lifetime; - // tracks and importers don't. Only the capture path also writes through it. - #[cfg_attr(not(feature = "capture"), allow(dead_code))] - broadcast: moq_net::broadcast::Producer, + // tracks and importers don't. `None` for `import ts --program all`, whose + // programs each keep and announce their own. + broadcast: Option, } impl Publish { @@ -283,20 +298,15 @@ impl Publish { format: &PublishFormat, config: moq_mux::catalog::Config, ) -> anyhow::Result { - // TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) - // verbatim, so it uses the `mpegts` catalog extension rather than the media-only - // `()`. The catalog producer owns the broadcast's catalog tracks, so each broadcast - // gets exactly one; TS builds its `Ext` catalog here instead of the shared `()` below. - if let PublishFormat::Ts = format { - let config = config.with_catalog(moq_mux::catalog::hang::Catalog::::default()); - let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; - let ts = ts::Import::new(broadcast.clone(), catalog.reserve()); + // TS builds its `Ext` catalog instead of the shared `()` below. + if let PublishFormat::Ts { program } = *format { + let (ts, catalog) = ts_import(&mut broadcast, config, program)?; return Ok(Self { source: Source::Stream { decoder: PublishDecoder::Ts(Box::new(ts)), catalog: PublishCatalog::Ts(catalog), }, - broadcast, + broadcast: Some(broadcast), }); } @@ -315,7 +325,7 @@ impl Publish { let fmp4 = fmp4::Import::new(broadcast.clone(), catalog.reserve()); PublishDecoder::Fmp4(Box::new(fmp4)) } - PublishFormat::Ts => unreachable!("TS is handled above with the mpegts catalog extension"), + PublishFormat::Ts { .. } => unreachable!("TS is handled above with the mpegts catalog extension"), PublishFormat::Flv => { let flv = flv::Import::new(broadcast.clone(), catalog.reserve()); PublishDecoder::Flv(Box::new(flv)) @@ -327,10 +337,25 @@ impl Publish { decoder, catalog: PublishCatalog::Media(catalog), }, - broadcast, + broadcast: Some(broadcast), }) } + /// Build a publisher decoding a multi-program TS from stdin into one broadcast per program, + /// named after `name` (`event.hang` becomes `event/1.hang`, `event/2.hang`, ...). + /// + /// The programs aren't known until the PAT arrives, so each broadcast is created and + /// announced then, and [`announce`](Self::announce) has nothing to do. + pub fn ts_programs(origin: moq_net::origin::Producer, name: String, config: moq_mux::catalog::Config) -> Self { + Self { + source: Source::Stream { + decoder: PublishDecoder::TsPrograms(Box::new(ts::Programs::new(origin, name, config))), + catalog: PublishCatalog::TsPrograms, + }, + broadcast: None, + } + } + /// Build a publisher capturing local devices (camera/screen and microphone). /// /// `bandwidth` is the uplink's send estimate, when there is one: the video @@ -359,14 +384,22 @@ impl Publish { anyhow::ensure!(video.is_some() || audio.is_some(), "nothing to capture"); Ok(Self { - source: Source::Capture { catalog, video, audio }, - broadcast, + source: Source::Capture { + broadcast: broadcast.clone(), + catalog, + video, + audio, + }, + broadcast: Some(broadcast), }) } /// Advertise the broadcast's path, now that the catalog tracks are in place. pub fn announce(&self) -> anyhow::Result<()> { - self.broadcast + let Some(broadcast) = &self.broadcast else { + return Ok(()); + }; + broadcast .announce(Default::default()) .context("failed to announce broadcast") } @@ -376,7 +409,12 @@ impl Publish { match self.source { Source::Stream { decoder, catalog } => decode(decoder, catalog, tokio::io::stdin()).await, #[cfg(feature = "capture")] - Source::Capture { catalog, video, audio } => { + Source::Capture { + broadcast, + catalog, + video, + audio, + } => { // Each enabled medium publishes its own track onto the shared // broadcast + catalog. Both stamp frames on the catalog's // advertised clock, so HLS/DASH wall times match the mapping on @@ -385,7 +423,7 @@ impl Publish { // macOS the audio future holds ObjC handles across an await, // so it is `!Send`. let video_fut = { - let broadcast = self.broadcast.clone(); + let broadcast = broadcast.clone(); let catalog = catalog.clone(); async move { match video { @@ -401,20 +439,17 @@ impl Publish { } } }; - let audio_fut = { - let broadcast = self.broadcast.clone(); - async move { - match audio { - Some((config, encode)) => { - let mut options = moq_audio::encode::Capture::default(); - options.capture = config; - options.encode = encode; - moq_audio::encode::publish_capture(broadcast, catalog, options) - .await - .map_err(anyhow::Error::from) - } - None => Ok(()), + let audio_fut = async move { + match audio { + Some((config, encode)) => { + let mut options = moq_audio::encode::Capture::default(); + options.capture = config; + options.encode = encode; + moq_audio::encode::publish_capture(broadcast, catalog, options) + .await + .map_err(anyhow::Error::from) } + None => Ok(()), } }; @@ -437,10 +472,11 @@ async fn decode( ) -> anyhow::Result<()> { let mut buffer = bytes::BytesMut::new(); - // Damage reported so far, so only the change is logged. A live feed is + // Counters reported so far, so only the change is logged. A live feed is // diagnosed by the rate at which these climb, and stdin may never end, so // they have to surface as they accumulate rather than at exit. - let mut reported = decoder.stats(); + let mut log = ts::stats::Log::default(); + let mut sampled = tokio::time::Instant::now(); // Run the read/decode loop so an error surfaces here rather than // dropping the decoder (and its tracks) with a bare Error::Dropped. @@ -453,10 +489,11 @@ async fn decode( } decoder.decode_chunk(&buffer)?; - let latest = decoder.stats(); - if latest != reported { - log_stats(latest.as_ref(), reported.as_ref()); - reported = latest; + if sampled.elapsed() >= ts::stats::Log::INTERVAL { + sampled = tokio::time::Instant::now(); + if let Some(stats) = decoder.stats() { + log.sample(stats); + } } } } @@ -468,7 +505,9 @@ async fn decode( let outcome = result.and_then(|()| decoder.finish()); // The drain at end of input can publish a frame nothing vouched for, so the // final snapshot is only complete after `finish`. - log_stats(decoder.stats().as_ref(), reported.as_ref()); + if let Some(stats) = decoder.stats() { + log.finish(&stats); + } match outcome { Ok(()) => catalog.finish(), Err(err) => { @@ -731,7 +770,7 @@ mod tests { let broadcast = origin.create_broadcast("cli").unwrap(); broadcast.announce(Default::default()).unwrap(); settle().await; - let mut publish = Publish::new(broadcast, &PublishFormat::Ts, Default::default()).unwrap(); + let mut publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); #[allow(irrefutable_let_patterns)] let Source::Stream { decoder, .. } = &mut publish.source else { panic!("expected a stream source"); @@ -809,7 +848,7 @@ mod tests { async fn ts_import_anchors_the_catalog_clock_on_arrival() { let broadcast = moq_net::broadcast::Info::new().produce(); let consumer = broadcast.consume(); - let mut publish = Publish::new(broadcast, &PublishFormat::Ts, Default::default()).unwrap(); + let mut publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); #[allow(irrefutable_let_patterns)] let Source::Stream { decoder, .. } = &mut publish.source else { panic!("expected a stream source"); @@ -855,7 +894,7 @@ mod tests { async fn eof_finishes_the_catalog_with_its_renditions() { let broadcast = moq_net::broadcast::Info::new().produce(); let consumer = broadcast.consume(); - let publish = Publish::new(broadcast, &PublishFormat::Ts, Default::default()).unwrap(); + let publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); let mut catalogs = hang::catalog::Catalog::<()>::subscribe(&consumer).await.unwrap(); #[allow(irrefutable_let_patterns)] @@ -880,6 +919,113 @@ mod tests { assert_eq!(last.audio.renditions.len(), 1, "the audio rendition is still listed"); } + /// A PAT listing two programs, then one MP2 PES of each: program 1 on PID `0x61` at 1 s + /// with fill bytes `0xAA`/`0xBB`, program 2 on PID `0x71` an hour later with `0xCC`/`0xDD`. + fn two_programs() -> Vec { + use mpeg2ts::es::StreamType; + use mpeg2ts::ts::payload::{Pat, Pmt}; + use mpeg2ts::ts::{ + ContinuityCounter, EsInfo, Pid, ProgramAssociation, TransportScramblingControl, TsHeader, TsPacket, + TsPacketWriter, TsPayload, VersionNumber, WriteTsPacket, + }; + + let write = |out: &mut Vec, pid: u16, payload: TsPayload| { + let packet = TsPacket { + header: TsHeader { + transport_error_indicator: false, + transport_priority: false, + pid: Pid::new(pid).unwrap(), + transport_scrambling_control: TransportScramblingControl::NotScrambled, + continuity_counter: ContinuityCounter::default(), + }, + adaptation_field: None, + payload: Some(payload), + }; + TsPacketWriter::new(out).write_ts_packet(&packet).unwrap(); + }; + let programs = [ + (1, 0x100, 0x61, 90_000, [0xAA, 0xBB]), + (2, 0x200, 0x71, 3_601 * 90_000, [0xCC, 0xDD]), + ]; + + let mut out = Vec::new(); + let pat = Pat { + transport_stream_id: 1, + version_number: VersionNumber::default(), + table: programs + .iter() + .map(|&(program_num, pmt_pid, ..)| ProgramAssociation { + program_num, + program_map_pid: Pid::new(pmt_pid).unwrap(), + }) + .collect(), + }; + write(&mut out, Pid::PAT, TsPayload::Pat(pat)); + for &(program_num, pmt_pid, es_pid, ..) in &programs { + let pmt = Pmt { + program_num, + pcr_pid: Some(Pid::new(es_pid).unwrap()), + version_number: VersionNumber::default(), + program_info: Vec::new(), + es_info: vec![EsInfo { + stream_type: StreamType::Mpeg1Audio, + elementary_pid: Pid::new(es_pid).unwrap(), + descriptors: Vec::new(), + }], + }; + write(&mut out, pmt_pid, TsPayload::Pmt(pmt)); + } + for &(_, _, es_pid, pts, fills) in &programs { + out.extend(mp2_pes_packet(es_pid, pts, fills)); + } + out + } + + /// One TS packet on `pid` holding a PES of two MP2 frames at `pts`, the second confirming + /// the first so the legacy path publishes it. + fn mp2_pes_packet(pid: u16, pts: u64, fills: [u8; 2]) -> Vec { + let mut payload = Vec::new(); + for fill in fills { + let mut frame = vec![0xFF, 0xF5, 0x18, 0xC0]; + frame.resize(72, fill); + payload.extend(frame); + } + let mut pes = vec![0x00, 0x00, 0x01, 0xc0]; + let len = 3 + 5 + payload.len(); + pes.extend([(len >> 8) as u8, len as u8, 0x80, 0x80, 0x05]); + pes.extend([ + 0x21 | (((pts >> 30) & 0x07) << 1) as u8, + (pts >> 22) as u8, + 0x01 | (((pts >> 15) & 0x7f) << 1) as u8, + (pts >> 7) as u8, + 0x01 | ((pts & 0x7f) << 1) as u8, + ]); + pes.extend(payload); + + let stuffing = 184 - 1 - pes.len(); + let mut packet = vec![0x47, 0x40 | (pid >> 8) as u8, pid as u8, 0x30, stuffing as u8]; + if stuffing > 0 { + packet.push(0x00); + packet.resize(5 + stuffing, 0xff); + } + packet.extend(pes); + assert_eq!(packet.len(), 188); + packet + } + + /// Plain `import ts` refuses a multiplex, naming its programs and the flag that picks one. + #[test] + fn a_multiplex_is_refused_with_the_programs_and_the_flag() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let mut publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); + #[allow(irrefutable_let_patterns)] + let Source::Stream { decoder, .. } = &mut publish.source else { + panic!("expected a stream source"); + }; + let err = format!("{:#}", decoder.decode_chunk(&two_programs()).unwrap_err()); + assert!(err.contains("--program") && err.contains("programs (1, 2)"), "{err}"); + } + /// Read the first frame of a verbatim track back as raw bytes. async fn read_frame(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-cli/src/srt.rs b/rs/moq-cli/src/srt.rs index 7afbe3ff7fc..35993e691dd 100644 --- a/rs/moq-cli/src/srt.rs +++ b/rs/moq-cli/src/srt.rs @@ -10,6 +10,7 @@ use moq_srt::{Reject, Request, Server}; use moq_tokio::RedactedUrl; use url::Url; +use crate::args::TsProgram; use crate::moq::{ImportTarget, notify_ready}; /// SRT endpoint args: exactly one of `--connect` (dial) / `--listen` (bind). @@ -31,8 +32,49 @@ pub struct Args { pub latency: crate::duration::Duration, } +/// SRT import args: the endpoint, plus which programs of a multiplex to publish. +#[derive(usage::Args, Clone)] +#[usage(unknown_flags = "error", args_override_self = false)] +pub struct ImportArgs { + #[usage(flatten)] + pub endpoint: Args, + + /// Import one program of a multi-program feed, by its PAT program number, or `all` to + /// publish each program as its own broadcast (`event.hang` becomes `event/1.hang`, + /// `event/2.hang`, ...). Without it, a feed carrying more than one program is refused. + #[usage(long)] + pub program: Option, +} + +impl ImportArgs { + /// The library's selection for `--program`. + pub fn program(&self) -> Option { + self.program.map(|program| match program { + TsProgram::One(program) => moq_srt::Program::One(program), + TsProgram::All => moq_srt::Program::All, + }) + } +} + +/// Point a multi-program refusal at the flag that resolves it. +fn suggest_program(err: moq_srt::Error) -> anyhow::Error { + let multiplex = matches!(&err, moq_srt::Error::Mux(moq_mux::Error::Other(inner)) + if inner.is::()); + let err = anyhow::Error::from(err); + if multiplex { + err.context("choose one with `--program `, or publish each with `--program all`") + } else { + err + } +} + /// Accept incoming SRT publishes into the Origin as `target.name`; reject requests (import). -pub async fn listen_import(target: ImportTarget, addr: SocketAddr, latency: Duration) -> anyhow::Result<()> { +pub async fn listen_import( + target: ImportTarget, + addr: SocketAddr, + latency: Duration, + program: Option, +) -> anyhow::Result<()> { let ImportTarget { origin, name, @@ -53,10 +95,12 @@ pub async fn listen_import(target: ImportTarget, addr: SocketAddr, latency: Dura if let Err(err) = publish .with_max_age(max_age) .with_bandwidth(bandwidth) + .with_program(program) .accept(&origin, &name) .await { - tracing::warn!(%name, %err, "SRT ingest ended with error"); + let err = suggest_program(err); + tracing::warn!(%name, err = format!("{err:#}"), "SRT ingest ended with error"); } }); } @@ -107,7 +151,12 @@ pub async fn listen_export( } /// Dial a remote SRT server and pull its stream into the Origin under `target.name` (import). -pub async fn connect_import(target: ImportTarget, url: Url, latency: Duration) -> anyhow::Result<()> { +pub async fn connect_import( + target: ImportTarget, + url: Url, + latency: Duration, + program: Option, +) -> anyhow::Result<()> { let (addr, resource) = parse_url(&url).await?; let name = &target.name; tracing::info!(url = %RedactedUrl::new(&url), %name, "SRT client pulling"); @@ -116,8 +165,9 @@ pub async fn connect_import(target: ImportTarget, url: Url, latency: Duration) - let client = moq_srt::Client::new(addr, resource) .with_latency(latency) .with_max_age(target.max_age) - .with_bandwidth(target.bandwidth); - Ok(client.pull(&target.origin, name).await?) + .with_bandwidth(target.bandwidth) + .with_program(program); + client.pull(&target.origin, name).await.map_err(suggest_program) } /// Push a broadcast from the Origin to a remote SRT server (export). @@ -184,6 +234,18 @@ mod tests { assert!(parse("udp://127.0.0.1:9000").await.is_err()); } + /// A multiplex refusal names the flag that resolves it; other errors pass through unchanged. + #[test] + fn a_multiplex_suggests_the_program_flag() { + let refused = moq_mux::container::ts::MultipleProgramsError { programs: vec![1, 2] }; + let err = suggest_program(moq_srt::Error::Mux(anyhow::Error::from(refused).into())); + let err = format!("{err:#}"); + assert!(err.contains("--program") && err.contains("programs (1, 2)"), "{err}"); + + let err = format!("{:#}", suggest_program(moq_srt::Error::ListenerClosed)); + assert!(!err.contains("--program"), "{err}"); + } + #[tokio::test] async fn requires_port_and_resource() { assert!(parse("srt://127.0.0.1").await.is_err()); diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index 0680d83f8b8..2d1d8f67c58 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -139,6 +139,9 @@ pub struct SubscribeArgs { /// How far playback may drift from the live edge before skipping groups. pub max_age: Duration, + /// How long to wait for the broadcast to come back after it ends (TS only). + pub linger: Duration, + /// Cap the output duration: publisher groups by default for fMP4, video GOPs for MKV. pub fragment_duration: Option, @@ -300,6 +303,8 @@ impl Subscribe { // is re-framed as ADTS. `fragment_duration` does not apply to TS. `with_ts` // selects the `mpegts` catalog extension so undecoded elementary streams // (SCTE-35, teletext, DVB AC-3, ...) are re-emitted verbatim on their PIDs. + let source = self.source.clone(); + let mut broadcast = source.broadcast().await?; let mut ts = moq_mux::container::ts::Export::with_ts(self.source, self.catalog) .await? .with_max_age(self.args.max_age); @@ -316,23 +321,44 @@ impl Subscribe { // bounded; it needs to know whether each frame was waited for, hence the // hand-rolled poll instead of `ts.next()`. let mut delivery = Delivery::new(self.args.max_age); + let linger = self.args.linger; loop { - let mut waited = false; - let frame = hang::moq_net::kio::wait(|waiter| match ts.poll_next(waiter) { - std::task::Poll::Pending => { - waited = true; - std::task::Poll::Pending - } - ready => ready, - }) - .await?; - - let Some(frame) = frame else { break }; - delivery.update(&frame, ts.discontinuity()); - delivery.deliver(&frame, waited, &mut stdout).await?; + let end = loop { + let mut waited = false; + let frame = hang::moq_net::kio::wait(|waiter| match ts.poll_next(waiter) { + std::task::Poll::Pending => { + waited = true; + std::task::Poll::Pending + } + ready => ready, + }) + .await; + + let frame = match frame { + Ok(Some(frame)) => frame, + Ok(None) => break Ok(()), + Err(err) => break Err(err), + }; + delivery.update(&frame, ts.discontinuity()); + delivery.deliver(&frame, waited, &mut stdout).await?; + }; + + // Any end waits out the linger, and on expiry the last one is the result: a + // clean catalog finish exits 0, a drop or any other failure exits 1. + if linger.is_zero() { + return Ok(end?); + } + match &end { + Ok(()) => tracing::info!(?linger, "broadcast finished, waiting for it to return"), + Err(err) => tracing::warn!(%err, ?linger, "broadcast ended, waiting for it to return"), + } + let Some(returned) = resume_within(&source, &broadcast, &mut ts, linger).await? else { + tracing::info!(?linger, "broadcast did not return"); + return Ok(end?); + }; + broadcast = returned; + tracing::info!("broadcast returned, resuming"); } - - Ok(()) } async fn run_flv(self) -> anyhow::Result<()> { @@ -355,6 +381,28 @@ impl Subscribe { } } +/// Wait up to `linger` for the `ended` broadcast to return and `ts` to resume on it. +/// +/// The linger bounds the whole return, catalog subscription included: a returned +/// broadcast whose catalog never resolves must not hold the export past it. `None` +/// when it did not return in time. +async fn resume_within( + source: &moq_mux::Source, + ended: &hang::moq_net::broadcast::Consumer, + ts: &mut moq_mux::container::ts::Export, + linger: Duration, +) -> anyhow::Result> { + let resume = async { + let returned = source.returned(ended).await?; + ts.resume().await?; + anyhow::Ok(returned) + }; + match tokio::time::timeout(linger, resume).await { + Ok(returned) => Ok(Some(returned?)), + Err(_) => Ok(None), + } +} + /// Paced stdout delivery for the TS export: sleeps until each frame's send /// instant, with total delivery lag bounded by the latency budget. /// @@ -675,4 +723,31 @@ mod tests { delivery.deliver(&next, false, &mut out).await.unwrap(); assert_eq!(now.elapsed(), Duration::from_millis(40)); } + + /// A broadcast that returns but never serves its catalog gives up at the linger, + /// rather than waiting on the catalog past it. + #[tokio::test(start_paused = true)] + async fn a_return_without_a_catalog_expires_with_the_linger() { + let (origin, driver) = hang::moq_net::origin::Producer::new(Default::default()); + tokio::spawn(hang::moq_net::time::run(driver)); + let source = moq_mux::Source::new(origin.consume(), "live"); + + let mut first = origin.publish("live", Default::default()).unwrap(); + let catalog = moq_mux::catalog::Producer::new(&mut first, Default::default()).unwrap(); + let ended = source.broadcast().await.unwrap(); + let mut ts = moq_mux::container::ts::Export::with_ts(source.clone(), CatalogFormat::Hang) + .await + .unwrap(); + drop((first, catalog)); + + // Back, but its catalog request is never answered. + let second = origin.publish("live", Default::default()).unwrap(); + let _unanswered = second.dynamic(); + + let linger = Duration::from_secs(10); + let start = tokio::time::Instant::now(); + let resumed = resume_within(&source, &ended, &mut ts, linger).await.unwrap(); + assert!(resumed.is_none(), "a return that never resumes is no return"); + assert_eq!(start.elapsed(), linger); + } } diff --git a/rs/moq-cli/tests/export.rs b/rs/moq-cli/tests/export.rs new file mode 100644 index 00000000000..3815187993a --- /dev/null +++ b/rs/moq-cli/tests/export.rs @@ -0,0 +1,212 @@ +//! `moq export ts --linger` over a real relay: the export rides out a publisher that +//! leaves and comes back, and exits with the verdict of the broadcast's last end. +#![cfg(unix)] + +use std::process::Stdio; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::process::{Child, ChildStdin}; +use tokio::task::JoinHandle; + +const TIMEOUT: Duration = Duration::from_secs(30); +/// About three seconds of HEVC and Opus. +const CLIP: &[u8] = include_bytes!("../../moq-mux/src/container/ts/test_data/bbb_cbr.ts"); + +type Output = Arc>>; + +struct Relay { + url: String, + fingerprint: String, +} + +async fn relay() -> Relay { + let _ = moq_tokio::crypto::install_default(); + let fixture = moq_relay::test_relay().await.expect("test relay"); + let ready = fixture.relay.ready(); + tokio::spawn(fixture.relay.run()); + ready.wait().await.expect("relay ready"); + Relay { + url: fixture.url.to_string(), + fingerprint: fixture.fingerprint, + } +} + +fn moq(relay: &Relay, args: &[&str]) -> tokio::process::Command { + let mut command = tokio::process::Command::new(env!("CARGO_BIN_EXE_moq")); + // A `MOQ_*` variable in the developer's shell must not reconfigure the child. + for (name, _) in std::env::vars_os() { + if name.to_string_lossy().starts_with("MOQ_") { + command.env_remove(name); + } + } + command + .args([ + "--connect", + &relay.url, + "--connect-tls-fingerprint", + &relay.fingerprint, + "--broadcast", + "demo", + ]) + .args(args) + .kill_on_drop(true); + command +} + +/// Start `moq export ts --linger `, collecting its stdout. +fn export(relay: &Relay, linger: &str) -> (Child, Output) { + let mut child = moq(relay, &["export", "ts", "--linger", linger]) + .stdout(Stdio::piped()) + .spawn() + .expect("spawn export"); + let mut stdout = child.stdout.take().expect("stdout"); + let output = Output::default(); + let sink = output.clone(); + tokio::spawn(async move { + let mut buf = vec![0; 64 * 1024]; + while let Ok(n) = stdout.read(&mut buf).await + && n > 0 + { + sink.lock().unwrap().extend_from_slice(&buf[..n]); + } + }); + (child, output) +} + +/// Start `moq import ts` and feed it the clip at about real time, handing stdin back +/// once it is all written. Closing stdin then finishes the broadcast. +fn import(relay: &Relay) -> (Child, JoinHandle) { + let mut child = moq(relay, &["import", "ts"]) + .stdin(Stdio::piped()) + .spawn() + .expect("spawn import"); + let mut stdin = child.stdin.take().expect("stdin"); + let feeding = tokio::spawn(async move { + for chunk in CLIP.chunks(188 * 40) { + stdin.write_all(chunk).await.expect("write stdin"); + tokio::time::sleep(Duration::from_millis(150)).await; + } + stdin + }); + (child, feeding) +} + +/// Wait until the export has written more than `len` bytes. +async fn output_past(output: &Output, len: usize) { + tokio::time::timeout(TIMEOUT, async { + while output.lock().unwrap().len() <= len { + tokio::time::sleep(Duration::from_millis(50)).await; + } + }) + .await + .expect("the export wrote nothing"); +} + +/// End the publisher the way an operator does, which drops the broadcast unfinished. +async fn interrupt(mut child: Child, stdin: ChildStdin) { + let pid = child.id().expect("running").to_string(); + let status = std::process::Command::new("kill") + .args(["-INT", &pid]) + .status() + .expect("kill"); + assert!(status.success()); + // The interrupted process exits once its stdin read returns; closing stdin any + // sooner could land first and finish the broadcast instead. + tokio::time::sleep(Duration::from_millis(500)).await; + drop(stdin); + wait(&mut child).await; +} + +async fn wait(child: &mut Child) -> std::process::ExitStatus { + tokio::time::timeout(TIMEOUT, child.wait()) + .await + .expect("moq never exited") + .expect("wait for moq") +} + +/// The 188-byte packets of `ts`, checking they are aligned. +fn packets(ts: &[u8]) -> impl Iterator { + ts.as_chunks::<188>() + .0 + .iter() + .inspect(|packet| assert_eq!(packet[0], 0x47, "the output is packet aligned")) +} + +fn pid(packet: &[u8]) -> u16 { + u16::from(packet[1] & 0x1f) << 8 | u16::from(packet[2]) +} + +/// The adaptation field flags byte, when the packet carries a non-empty adaptation field. +fn adaptation_flags(packet: &[u8]) -> Option { + (packet[3] & 0x20 != 0 && packet[4] > 0).then_some(packet[5]) +} + +#[tokio::test] +async fn a_clean_finish_exits_zero_once_the_linger_expires() { + let relay = relay().await; + let (mut export, output) = export(&relay, "1s"); + + let (mut publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, 0).await; + drop(stdin); + assert!(wait(&mut publisher).await.success()); + let finished = Instant::now(); + + let status = wait(&mut export).await; + assert!(status.success(), "a clean finish exits 0, got {status}"); + assert!( + finished.elapsed() >= Duration::from_millis(900), + "the export waited out its linger" + ); +} + +#[tokio::test] +async fn a_drop_exits_one_once_the_linger_expires() { + let relay = relay().await; + let (mut export, output) = export(&relay, "1s"); + + let (publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, 0).await; + interrupt(publisher, stdin).await; + + let status = wait(&mut export).await; + assert_eq!(status.code(), Some(1), "a drop exits 1, got {status}"); +} + +#[tokio::test] +async fn a_publisher_restarted_within_the_linger_resumes_the_output() { + let relay = relay().await; + let (mut export, output) = export(&relay, "10s"); + + let (publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, 0).await; + interrupt(publisher, stdin).await; + // Let the paced tail of the first broadcast drain before marking where it ended. + tokio::time::sleep(Duration::from_secs(1)).await; + let mark = output.lock().unwrap().len().next_multiple_of(188); + + let (mut publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, mark).await; + drop(stdin); + assert!(wait(&mut publisher).await.success()); + + let status = wait(&mut export).await; + assert!(status.success(), "the last end was a clean finish, got {status}"); + + let output = output.lock().unwrap(); + let after = &output[mark..]; + let total = packets(after).count(); + assert!(total > 100, "the returned broadcast went out: {total} packets"); + assert!(packets(after).any(|p| pid(p) == 0), "PAT re-emitted after the restart"); + // The PCR the returned broadcast opens with flags the break. + let first_pcr = packets(after) + .find_map(|p| adaptation_flags(p).filter(|flags| flags & 0x10 != 0)) + .expect("a PCR after the restart"); + assert_ne!(first_pcr & 0x80, 0, "the restart is flagged as a break"); +} diff --git a/rs/moq-e2ee/CHANGELOG.md b/rs/moq-e2ee/CHANGELOG.md index e51500a8edb..7f837ccb64e 100644 --- a/rs/moq-e2ee/CHANGELOG.md +++ b/rs/moq-e2ee/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.9](https://github.com/moq-dev/moq/compare/moq-e2ee-v0.0.8...moq-e2ee-v0.0.9) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net + ## [0.0.8](https://github.com/moq-dev/moq/compare/moq-e2ee-v0.0.7...moq-e2ee-v0.0.8) - 2026-09-27 ### Other diff --git a/rs/moq-e2ee/Cargo.toml b/rs/moq-e2ee/Cargo.toml index 7ae4e28b5ef..1719fc078b1 100644 --- a/rs/moq-e2ee/Cargo.toml +++ b/rs/moq-e2ee/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.8" +version = "0.0.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-e2ee/tests/transport.rs b/rs/moq-e2ee/tests/transport.rs index bb114105e2c..72dde42bc77 100644 --- a/rs/moq-e2ee/tests/transport.rs +++ b/rs/moq-e2ee/tests/transport.rs @@ -1,4 +1,4 @@ -//! Grouped tracks on moq-lite and MoQ Transport; datagrams on moq-lite. +//! Grouped tracks and datagrams on moq-lite and MoQ Transport. mod support; @@ -104,10 +104,9 @@ async fn grouped_over_ietf() { .expect("timed out"); } -#[tokio::test] -async fn datagrams_over_lite() { +async fn datagram_roundtrip(version: &str) { tokio::time::timeout(TEST_TIMEOUT, async { - let mut fixture = connect_protected("moq-lite-05".parse().unwrap(), "audio").await; + let mut fixture = connect_protected(version.parse().unwrap(), "audio").await; fixture .producer .append_datagram(Timestamp::from_millis(9).unwrap(), b"opus") @@ -123,3 +122,13 @@ async fn datagrams_over_lite() { .await .expect("timed out"); } + +#[tokio::test] +async fn datagrams_over_lite() { + datagram_roundtrip("moq-lite-05").await; +} + +#[tokio::test] +async fn datagrams_over_ietf() { + datagram_roundtrip("moq-transport-21").await; +} diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index 982b8aa4713..9094c0b3521 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.4.9](https://github.com/moq-dev/moq/compare/moq-ffi-v0.4.8...moq-ffi-v0.4.9) - 2026-09-30 + +### Added + +- *(ffi)* Python, Go, and Dart print MoqError's Rust message ([#4433](https://github.com/moq-dev/moq/pull/4433)) + +### Fixed + +- *(net)* an origin::Dynamic keeps its origin alive ([#4417](https://github.com/moq-dev/moq/pull/4417)) + ## [0.4.8](https://github.com/moq-dev/moq/compare/moq-ffi-v0.4.7...moq-ffi-v0.4.8) - 2026-09-27 ### Added diff --git a/rs/moq-ffi/Cargo.toml b/rs/moq-ffi/Cargo.toml index 60d3bfd653b..c6205452571 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.4.8" +version = "0.4.9" edition = "2024" keywords = ["quic", "http3", "webtransport", "media", "live"] diff --git a/rs/moq-ffi/build.sh b/rs/moq-ffi/build.sh index 75342c3f08a..ef8ef928f89 100755 --- a/rs/moq-ffi/build.sh +++ b/rs/moq-ffi/build.sh @@ -172,7 +172,7 @@ generate_bindings() { # Go uses a separate, third-party bindgen. Upstream has no uniffi 0.32 # release yet, so install the compatible generator fork with: - # cargo install --locked uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.9.0+v0.32.0 + # cargo install --locked uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.10.0-kixelated.1+v0.32.0 if command -v uniffi-bindgen-go >/dev/null 2>&1; then echo " Generating go bindings..." uniffi-bindgen-go --library "$lib_path" --out-dir "$OUTPUT_DIR/bindings/go" diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 16750c1375e..22c3ba47428 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -48,7 +48,7 @@ impl From for moq_audio::Format { /// Audio codec selection for the encoder. /// /// An immutable object so adding a codec later does not break callers -/// switching over a closed enum. Currently only Opus is available. +/// switching over a closed enum. #[derive(uniffi::Object)] pub struct MoqAudioCodec { inner: moq_audio::encode::Codec, @@ -63,6 +63,16 @@ impl MoqAudioCodec { inner: moq_audio::encode::Codec::Opus, }) } + + /// AAC-LC (`mp4a.40.2`) through the platform's encoder, at the input's rate + /// and layout. A host without one refuses it when the producer is built. + /// Its frames are 1024 samples, so leave `frame_duration_us` at 0. + #[uniffi::constructor] + pub fn aac() -> Arc { + Arc::new(Self { + inner: moq_audio::encode::Codec::Aac, + }) + } } impl MoqAudioCodec { @@ -76,6 +86,9 @@ impl MoqAudioCodec { pub struct MoqAudioEncoderInput { pub format: MoqAudioSampleFormat, pub sample_rate: u32, + /// Interleaved channel count, which also names the speaker layout by the + /// WAVE convention: 1 mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, + /// 8 7.1, in front left, front right, center, LFE, back, side order. pub channels: u32, } @@ -93,7 +106,7 @@ pub struct MoqAudioEncoderOutput { pub bitrate: Option, /// Encoded frame duration in microseconds. Opus accepts exactly /// 2500/5000/10000/20000/40000/60000 us, and the default 20 ms matches the - /// JS publish path. + /// JS publish path. 0 takes the codec's own frame, which AAC needs. #[uniffi(default = 20000)] pub frame_duration_us: u32, } @@ -105,7 +118,9 @@ pub struct MoqAudioDecoderOutput { /// `None` delivers samples at the codec's native rate. #[uniffi(default = None)] pub sample_rate: Option, - /// `None` delivers samples at the codec's native channel count. + /// `None` delivers samples at the codec's native channel count. A count + /// names its layout as [`MoqAudioEncoderInput::channels`] describes, and + /// the decoder remixes to it. #[uniffi(default = None)] pub channels: Option, /// Upper bound on buffering before skipping a stalled group, in @@ -285,7 +300,16 @@ impl MoqBroadcastProducer { options.settings.layout = moq_audio::Layout::from_channels(channels)?; } options.settings.bitrate = output.bitrate.map(|bps| moq_net::bandwidth::Rate::from_bps(bps.into())); - options.settings.frame_duration = Duration::from_micros(output.frame_duration_us.into()); + if output.frame_duration_us != 0 { + options.settings.frame_duration = Duration::from_micros(output.frame_duration_us.into()); + } else if output.codec.codec() == moq_audio::encode::Codec::Aac { + // from_input sized this at the input rate. The codec rate may be the + // override above, and AAC's own frame is 1024 samples of that rate. + let mut rated = input.clone(); + rated.sample_rate = options.settings.sample_rate; + options.settings.frame_duration = + moq_audio::encode::Settings::from_input(moq_audio::encode::Codec::Aac, &rated).frame_duration; + } if let Some(bandwidth) = &bandwidth { options.bandwidth = bandwidth.allocator().clone(); } diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 84da7e0076a..14e441e3209 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -633,7 +633,7 @@ impl MoqTrackConsumer { /// Receive the next best-effort datagram in arrival order. /// /// Returns `None` when the track ends. Datagram delivery is unavailable over - /// IETF moq-transport, pre-lite-05 moq-lite, and stream-only transports. + /// pre-lite-05 moq-lite and stream-only transports. /// Datagrams are a separate cursor from groups, so this works alongside either /// group order, never commits the track to one, and progresses while a group /// read is pending. diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index cce70fb82f7..30e370dbbf5 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -150,7 +150,10 @@ fn stream_kind(err: &moq_net::StreamError) -> MoqProtocolKind { } /// Error returned by all UniFFI-exported functions. +/// +/// Exports `Display`, which the bindings surface as the error's string form. #[derive(Debug, thiserror::Error, uniffi::Error)] +#[uniffi::export(Display)] #[non_exhaustive] pub enum MoqError { /// A protocol failure carrying the peer's session or stream code. diff --git a/rs/moq-ffi/src/flate.rs b/rs/moq-ffi/src/flate.rs index a447306ec11..2c86f745590 100644 --- a/rs/moq-ffi/src/flate.rs +++ b/rs/moq-ffi/src/flate.rs @@ -8,6 +8,7 @@ use std::sync::Arc; +use moq_mux::binary::Config; use moq_mux::catalog::hang::Extra; use crate::error::MoqError; @@ -25,9 +26,9 @@ pub struct MoqFlateConfig { pub mime: Option, } -impl From for moq_mux::binary::Config { +impl From for Config { fn from(config: MoqFlateConfig) -> Self { - let mut out = moq_mux::binary::Config::default().with_compression(config.compression); + let mut out = Config::default().with_compression(config.compression); if let Some(mime) = config.mime { out = out.with_mime(mime); } @@ -48,9 +49,7 @@ impl MoqBroadcastProducer { let _guard = crate::ffi::enter(); self.with_state(|state| { let track = state.broadcast.create_track(name, None)?; - let producer = state - .catalog - .binary_snapshot(track, moq_mux::binary::Config::from(config))?; + let producer = state.catalog.binary_snapshot(track, Config::from(config))?; Ok(Arc::new(MoqFlateSnapshotProducer { inner: std::sync::Mutex::new(Some(producer)), })) @@ -68,9 +67,7 @@ impl MoqBroadcastProducer { let _guard = crate::ffi::enter(); self.with_state(|state| { let track = state.broadcast.create_track(name, None)?; - let producer = state - .catalog - .binary_stream(track, moq_mux::binary::Config::from(config))?; + let producer = state.catalog.binary_stream(track, Config::from(config))?; Ok(Arc::new(MoqFlateStreamProducer { inner: std::sync::Mutex::new(Some(producer)), })) diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index ffe4bedaf35..dfe9049474b 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -11,11 +11,12 @@ use crate::media::{MoqAudioInit, MoqContainerFormat, MoqContainerInit, MoqFrame, /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// /// Construct with the fields you care about; the rest use raw-track defaults -/// (priority 0, no publisher age limit, microsecond timescale). +/// (priority 127, no publisher age limit, microsecond timescale). #[derive(Clone, uniffi::Record)] pub struct MoqTrackInfo { /// Priority, used only to break ties between subscriptions of equal subscriber priority. - #[uniffi(default = 0)] + /// Higher is more urgent; the default 127 is the midpoint. + #[uniffi(default = 127)] pub priority: u8, /// Maximum age of a non-latest group before the publisher evicts it, in /// microseconds. Null imposes no publisher age limit. This is the publisher-side half of diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 6b4dcb29ea0..c0f5ee44be8 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -530,6 +530,60 @@ async fn raw_audio_frame_durations() { broadcast.close().unwrap(); } +/// A frame duration of 0 takes the codec's own frame, and AAC, which encodes only +/// through a platform encoder, is refused where there is none. +#[cfg(feature = "audio")] +#[tokio::test] +async fn raw_audio_codec_default_frame() { + use crate::audio::*; + + let broadcast = MoqBroadcastProducer::new().unwrap(); + let input = || MoqAudioEncoderInput { + format: MoqAudioSampleFormat::F32, + sample_rate: 48_000, + channels: 2, + }; + let output = |codec| MoqAudioEncoderOutput { + codec, + sample_rate: None, + channels: None, + bitrate: None, + frame_duration_us: 0, + }; + + let opus = broadcast + .encode_audio("opus".into(), input(), output(MoqAudioCodec::opus()), None) + .unwrap(); + opus.finish().unwrap(); + + assert_eq!(MoqAudioCodec::aac().codec(), moq_audio::encode::Codec::Aac); + let aac = broadcast.encode_audio("aac".into(), input(), output(MoqAudioCodec::aac()), None); + let Err(MoqError::Audio(message)) = aac else { + panic!("no platform AAC encoder on this host"); + }; + assert!(message.contains("no aac audio encoder"), "{message}"); + + // 0 still means 1024 samples after an output-rate override, not the input rate. + let mut resampled = output(MoqAudioCodec::aac()); + resampled.sample_rate = Some(48_000); + let aac = broadcast.encode_audio( + "aac-rate".into(), + MoqAudioEncoderInput { + format: MoqAudioSampleFormat::F32, + sample_rate: 44_100, + channels: 2, + }, + resampled, + None, + ); + let Err(MoqError::Audio(message)) = aac else { + panic!("no platform AAC encoder on this host"); + }; + assert!(message.contains("no aac audio encoder"), "{message}"); + + broadcast.close().unwrap(); +} + #[tokio::test] async fn raw_track_datagram_roundtrip() { let broadcast = MoqBroadcastProducer::new().unwrap(); diff --git a/rs/moq-gst/CHANGELOG.md b/rs/moq-gst/CHANGELOG.md index f8d3f075ee0..d81fa4a9e94 100644 --- a/rs/moq-gst/CHANGELOG.md +++ b/rs/moq-gst/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.4.9](https://github.com/moq-dev/moq/compare/moq-gst-v0.4.8...moq-gst-v0.4.9) - 2026-09-30 + +### Fixed + +- *(gst)* recover from leading deltas and timestamp rewinds ([#4480](https://github.com/moq-dev/moq/pull/4480)) +- *(moq-gst)* moqsrc waits for its session to end on stop ([#4416](https://github.com/moq-dev/moq/pull/4416)) +- *(gst)* keep waiting for a keyframe after a header-only buffer ([#4356](https://github.com/moq-dev/moq/pull/4356)) + +### Other + +- one rpm repo command that works on DNF4 and DNF5 ([#4567](https://github.com/moq-dev/moq/pull/4567)) + ## [0.4.8](https://github.com/moq-dev/moq/compare/moq-gst-v0.4.7...moq-gst-v0.4.8) - 2026-09-27 ### Other diff --git a/rs/moq-gst/Cargo.toml b/rs/moq-gst/Cargo.toml index 7adbdccd526..d3d5b33448e 100644 --- a/rs/moq-gst/Cargo.toml +++ b/rs/moq-gst/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.8" +version = "0.4.9" edition = "2024" rust-version.workspace = true publish = true diff --git a/rs/moq-gst/README.md b/rs/moq-gst/README.md index d7dde7b85f0..ffd42f952c7 100644 --- a/rs/moq-gst/README.md +++ b/rs/moq-gst/README.md @@ -27,7 +27,7 @@ sudo apt update && sudo apt install gstreamer1.0-moq ### Fedora / RHEL / Rocky / AlmaLinux ```bash -sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo +sudo curl -fsSL https://rpm.moq.dev/moq.repo -o /etc/yum.repos.d/moq.repo sudo dnf install gstreamer1-moq ``` diff --git a/rs/moq-gst/package.sh b/rs/moq-gst/package.sh index b48f392eb20..85ff0731b67 100755 --- a/rs/moq-gst/package.sh +++ b/rs/moq-gst/package.sh @@ -145,7 +145,7 @@ mkdir -p "$OUTPUT_DIR" echo ">> Running nfpm ($PACKAGER)..." export VERSION ARCH="$PKG_ARCH" PKG_NAME PLUGIN_PATH="$BUILT_SO" PLUGIN_DIR -"$WORKSPACE_DIR/rs/scripts/package-nfpm.sh" \ +"$WORKSPACE_DIR/sh/rs/package-nfpm.sh" \ "$WORKSPACE_DIR/packaging/moq-gst/nfpm.yaml" "$PACKAGER" "$OUTPUT_DIR/" echo ">> Done. Artifacts in: $OUTPUT_DIR" diff --git a/rs/moq-gst/scrub.sh b/rs/moq-gst/scrub.sh index 5d4699deee1..09ec56ad34a 100755 --- a/rs/moq-gst/scrub.sh +++ b/rs/moq-gst/scrub.sh @@ -40,7 +40,7 @@ scrub_macos() { # Framework path covers the official .pkg installer, and /usr/lib lets # dyld resolve system libs (libiconv, libc++) via the dyld_shared_cache at # @rpath substitution time. - "$SCRIPT_DIR/../scripts/scrub-macho.sh" "$dylib" \ + "$SCRIPT_DIR/../../sh/rs/scrub-macho.sh" "$dylib" \ /opt/homebrew/lib \ /Library/Frameworks/GStreamer.framework/Libraries \ /usr/lib diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 6fa5ba2c886..b606283142b 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -51,16 +51,15 @@ struct Media { encoder: bool, /// Apply a timeline break before the next valid frame, using the normal write error path. discontinuity: bool, - /// A video break closed the group, and a pause resumes mid-GOP, so deltas drop until a keyframe - /// opens the next one. Stays set once armed: a successful decode may publish nothing (a - /// header-only buffer), and a delta only misses its keyframe while no group is open, which for - /// video means after a break. + /// Video can start or resume mid-GOP, so deltas drop until a keyframe opens a group. Stays set: + /// a successful decode may publish nothing (a header-only buffer), and a delta only misses its + /// keyframe while no group is open. keyframe: bool, } impl Media { /// Publish one frame at `micros` on the media clock, handed over at `now`. Returns false when a - /// delta frame is dropped while waiting for the keyframe after a break. + /// frame is dropped while waiting for a keyframe at or beyond the live edge. fn write(&mut self, data: &Bytes, micros: u64, now: Instant) -> Result { if std::mem::take(&mut self.discontinuity) { self.track.discontinuity()?; @@ -69,6 +68,12 @@ impl Media { let ts = hang::container::Timestamp::from_micros(micros).ok(); match self.track.decode(data, ts) { Err(moq_mux::Error::MissingKeyframe(_)) if self.keyframe => return Ok(false), + Err(moq_mux::Error::TimestampRewind(_)) => { + // A rejected delta leaves its group open; later deltas cannot decode across that gap. + self.track.cut(None)?; + self.keyframe = !self.audio; + return Ok(false); + } result => result?, } // One group (one QUIC stream) per audio packet, so the relay forwards it without waiting for @@ -486,7 +491,7 @@ impl Pad { audio, encoder, discontinuity: false, - keyframe: false, + keyframe: !audio, }))); self.caps = Some(caps.clone()); Ok(name) @@ -708,7 +713,10 @@ impl Pad { let result: Result<()> = match self.track.as_mut().expect("track present") { Sink::Media(media) => match media.write(&data, micros, now) { Ok(false) => { - gst::debug!(CAT, "dropping delta frame until the keyframe after a break"); + gst::debug!( + CAT, + "dropping frame until the next decodable frame at or beyond the live edge" + ); return Ok(PushOutcome::Dropped); } result => result.map(|_| ()), @@ -1737,6 +1745,54 @@ mod tests { } } + #[test] + fn video_start_drops_deltas_until_the_first_keyframe() { + gst::init().unwrap(); + let (broadcast, catalog) = producers(); + let mut pad = Pad::new(); + pad.observe_caps(&broadcast, &catalog, producer_options(&h264_caps(), Some("video"))); + pad.observe_segment(time_segment()); + let delta = Bytes::from_static(&[0, 0, 0, 1, 0x61, 0xe0, 0x12, 0x34]); + let now = Instant::now(); + let push = |pad: &mut Pad, data: Bytes, pts: u64| { + pad.push_buffer(data, Some(gst::ClockTime::from_mseconds(pts)), None, None, now) + .unwrap() + }; + assert_eq!(push(&mut pad, delta.clone(), 0), PushOutcome::Dropped); + assert!(!pad.is_failed()); + assert_eq!(push(&mut pad, delta.clone(), 33), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 66), PushOutcome::Published); + assert_eq!(push(&mut pad, delta, 100), PushOutcome::Published); + } + + #[test] + fn video_rewind_drops_deltas_until_a_keyframe_clears_the_live_edge() { + gst::init().unwrap(); + let delta = Bytes::from_static(&[0, 0, 0, 1, 0x61, 0xe0, 0x12, 0x34]); + for rewind in [delta.clone(), h264_keyframe_au()] { + let (broadcast, catalog) = producers(); + let mut pad = Pad::new(); + pad.observe_caps(&broadcast, &catalog, producer_options(&h264_caps(), Some("video"))); + pad.observe_segment(time_segment()); + let now = Instant::now(); + let push = |pad: &mut Pad, data: Bytes, pts: u64| { + pad.push_buffer(data, Some(gst::ClockTime::from_mseconds(pts)), None, None, now) + .unwrap() + }; + assert_eq!(push(&mut pad, h264_keyframe_au(), 1000), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1033), PushOutcome::Published); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1100), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1133), PushOutcome::Published); + // Below the previous group's start, so not a reordered frame the producer tolerates. + assert_eq!(push(&mut pad, rewind, 16), PushOutcome::Dropped); + assert!(!pad.is_failed()); + assert_eq!(push(&mut pad, delta.clone(), 1166), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1066), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1200), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1233), PushOutcome::Published); + } + } + // A pause resumes mid-GOP: the break closed the group, so deltas drop until the next keyframe // instead of invalidating the pad. #[test] diff --git a/rs/moq-hls/CHANGELOG.md b/rs/moq-hls/CHANGELOG.md index e8c40609215..21315716c38 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.5.9](https://github.com/moq-dev/moq/compare/moq-hls-v0.5.8...moq-hls-v0.5.9) - 2026-09-30 + +### Fixed + +- *(hls,auth)* redact credentials from URLs in errors ([#4536](https://github.com/moq-dev/moq/pull/4536)) + ## [0.5.8](https://github.com/moq-dev/moq/compare/moq-hls-v0.5.7...moq-hls-v0.5.8) - 2026-09-27 ### Other diff --git a/rs/moq-hls/Cargo.toml b/rs/moq-hls/Cargo.toml index 47b2a92d4de..122ad928b4f 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.5.8" +version = "0.5.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-hls/src/error.rs b/rs/moq-hls/src/error.rs index a87420bcd32..2d909b79601 100644 --- a/rs/moq-hls/src/error.rs +++ b/rs/moq-hls/src/error.rs @@ -141,7 +141,9 @@ impl Error { impl From for Error { fn from(err: reqwest::Error) -> Self { - Error::Reqwest(std::sync::Arc::new(err)) + // reqwest prints the full URL in its error, and a playlist or segment URL + // routinely carries a signed token in its query. + Error::Reqwest(std::sync::Arc::new(err.without_url())) } } @@ -166,4 +168,22 @@ mod tests { assert_eq!(Error::ParsePlaylist("not a playlist".to_string()).status(), None); assert_eq!(Error::Moq(moq_net::Error::Transport("lost".to_string())).status(), None); } + + #[tokio::test] + async fn http_error_redacts_url() { + // A freed port refuses the connection, so reqwest fails with the dialed URL attached. + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind"); + let address = listener.local_addr().expect("local address"); + drop(listener); + + let err: Error = reqwest::get(format!("http://user:pass@{address}/media.m3u8?jwt=secret")) + .await + .expect_err("dial a closed port") + .into(); + + let printed = format!("{err} {err:?}"); + for secret in ["jwt", "secret", "user:pass"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } } diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 4bf488a2e57..f37ed43892f 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -708,6 +708,62 @@ mod tests { assert_eq!(video.bandwidth(), 2_000_000); } + // The estimator also measures the framerate and publishes it once it settles, so an + // imported source gains one about a second in. Rebuilding for it would re-time the fMP4 + // (its timescale derives from the framerate) and churn every recording cursor mid-stream. + #[tokio::test] + async fn estimated_framerate_keeps_the_rendition() { + let origin = produce_origin(); + let _broadcast = origin.create_broadcast("live").expect("publish allowed"); + _broadcast.announce(Default::default()).expect("publish allowed"); + settle().await; + let upstream = empty_upstream(&origin, "live").await; + + let mut catalog = catalog_with_both(); + catalog.video.renditions.get_mut("video0").unwrap().framerate = None; + let renditions = renditions::Producer::new(Config::default().window); + let mut cursor = renditions.subscribe(); + renditions.sync(&upstream, &catalog); + let video = renditions.get(Kind::Video, "video0").expect("video rendition"); + while next_event(&mut cursor).await.is_some() {} + + for framerate in [Some(30.0), Some(60.0)] { + catalog.video.renditions.get_mut("video0").unwrap().framerate = framerate; + renditions.sync(&upstream, &catalog); + assert!( + Arc::ptr_eq(&video, &renditions.get(Kind::Video, "video0").unwrap()), + "the video rendition survives a framerate estimate of {framerate:?}" + ); + assert!(next_event(&mut cursor).await.is_none(), "no rendition churn"); + } + + // The settled estimate still reaches the fallback cadence of a duration-less frame, + // at the timescale the rendition was built with (90 kHz without a framerate). + let muxer = video.muxer().unwrap(); + assert_eq!(muxer.timescale().as_u64(), 90_000); + let fragment = muxer.fragment(0, &[vp8_frame(0, true)]).unwrap(); + assert_eq!(first_sample_duration(&fragment), Some(1_500), "16.7 ms at 90 kHz"); + + // An NTSC estimate is 1501.5 ticks at 90 kHz: it snaps to whole ticks and still muxes. + catalog.video.renditions.get_mut("video0").unwrap().framerate = Some(60_000.0 / 1001.0); + renditions.sync(&upstream, &catalog); + let fragment = video.muxer().unwrap().fragment(0, &[vp8_frame(0, true)]).unwrap(); + assert_eq!(first_sample_duration(&fragment), Some(1_502)); + } + + /// The `trun` duration of a fragment's first sample. + fn first_sample_duration(fragment: &bytes::Bytes) -> Option { + use moq_mux::container::fmp4::mp4_atom::{self, DecodeMaybe}; + + let mut cursor = std::io::Cursor::new(fragment.as_ref()); + while let Some(atom) = mp4_atom::Any::decode_maybe(&mut cursor).unwrap() { + if let mp4_atom::Any::Moof(moof) = atom { + return moof.traf[0].trun[0].entries[0].duration; + } + } + panic!("no moof in fragment"); + } + #[tokio::test] async fn estimate_before_first_init_reaches_aac_descriptor() { let origin = produce_origin(); diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 7d30ee5f326..af468b35cc7 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -192,9 +192,9 @@ fn normalize_video(config: &VideoConfig) -> VideoConfig { config.delay = None; config.label = None; config.stalled = None; - // The muxer ignores a non-finite framerate, and NaN never equals itself, so a catalog - // carrying one would otherwise look different from itself on every republish. - config.framerate = config.framerate.filter(|fps| fps.is_finite()); + // Publishers estimate it and republish once it settles. The rendition keeps the fMP4 + // timescale it was built with, and the framerate is refreshed in place like the bitrate. + config.framerate = None; config } @@ -218,6 +218,9 @@ pub struct Rendition { /// Advertised bitrate for the master playlist `BANDWIDTH` attribute; read through /// [`bandwidth`](Self::bandwidth), refreshed in place by [`refresh`](Self::refresh). bitrate: RwLock>, + /// The latest catalog framerate (video only), refreshed in place by [`refresh`](Self::refresh): + /// the muxer's fallback sample cadence and the DASH `frameRate`. + framerate: RwLock>, /// Coded width, for the master playlist `RESOLUTION` (video only). pub width: Option, /// Coded height, for the master playlist `RESOLUTION` (video only). @@ -250,8 +253,8 @@ pub struct Rendition { impl Rendition { /// Whether `config` describes the same media this rendition is already serving, i.e. whether /// it decodes and muxes identically. Fields the publisher revises without touching the media - /// (its bitrate and jitter estimates, a label) are ignored here and picked up by - /// [`refresh`](Self::refresh) instead. + /// (its bitrate, jitter, and framerate estimates, a label) are ignored here, and the bitrate + /// and framerate are picked up by [`refresh`](Self::refresh) instead. pub(crate) fn matches_video(&self, config: &VideoConfig) -> bool { let Config::Video(current) = &self.config else { return false; @@ -273,14 +276,15 @@ impl Rendition { self.bitrate().unwrap_or(default_bandwidth(self.kind)) } - /// Take the advertised bitrate from a catalog update that - /// [`matches`](Self::matches_video) this rendition. + /// Take the advertised bitrate and framerate from a catalog update that + /// [`matches`](Self::matches_video) this rendition (audio passes no framerate). /// /// The publisher's estimator republishes the catalog whenever its measured bitrate moves, so /// this is the common update by far: rebuilding the rendition for it would reset the playlist /// window, the cached init segment, and `EXT-X-MEDIA-SEQUENCE` several times a minute. - pub(crate) fn refresh(&self, bitrate: Option) { + pub(crate) fn refresh(&self, bitrate: Option, framerate: Option) { *self.bitrate.write().expect("bitrate lock poisoned") = bitrate; + *self.framerate.write().expect("framerate lock poisoned") = framerate; } /// The latest catalog bitrate, preserving `None` for muxer-specific fallback behavior. @@ -288,6 +292,11 @@ impl Rendition { *self.bitrate.read().expect("bitrate lock poisoned") } + /// The latest catalog framerate. + fn framerate(&self) -> Option { + *self.framerate.read().expect("framerate lock poisoned") + } + /// Build a video rendition over the broadcast's timeline `section`, timed by the /// catalog root `clock`. /// @@ -304,6 +313,7 @@ impl Rendition { name, kind: Kind::Video, bitrate: RwLock::new(config.bitrate), + framerate: RwLock::new(config.framerate), width: config.coded_width, height: config.coded_height, codec: config.codec.to_string(), @@ -330,6 +340,7 @@ impl Rendition { name, kind: Kind::Audio, bitrate: RwLock::new(config.bitrate), + framerate: RwLock::new(None), width: None, height: None, codec: config.codec.to_string(), @@ -565,7 +576,7 @@ impl Rendition { }) .collect(); let (framerate, sample_rate, channel_count) = match &self.config { - Config::Video(config) => (config.framerate, None, None), + Config::Video(_) => (self.framerate(), None, None), Config::Audio(config) => (None, Some(config.sample_rate), Some(config.channel_count)), }; Some(mpd::Representation { @@ -611,13 +622,15 @@ impl Rendition { clock.wall_clock(pts).ok() } - fn muxer(&self) -> Result { + /// A muxer at the timescale this rendition's config chose, with the latest bitrate and + /// fallback framerate. + pub(crate) fn muxer(&self) -> Result { let bitrate = self.bitrate(); Ok(match &self.config { Config::Video(config) => { let mut config = config.clone(); config.bitrate = bitrate; - Muxer::video(&config)? + Muxer::video(&config)?.with_framerate(self.framerate()) } Config::Audio(config) => { let mut config = config.clone(); diff --git a/rs/moq-hls/src/export/renditions.rs b/rs/moq-hls/src/export/renditions.rs index 63815fed7ca..757b9657dfc 100644 --- a/rs/moq-hls/src/export/renditions.rs +++ b/rs/moq-hls/src/export/renditions.rs @@ -352,7 +352,7 @@ impl Producer { /// "Reconfigured" means the media itself changed (see [`Rendition::matches_video`]). A /// rendition whose entry only carries a revised estimate is kept as-is and just takes the /// new advertised bitrate, since the publisher republishes the catalog every time its - /// measured bitrate or jitter moves. + /// measured bitrate, jitter, or framerate moves. /// /// Renditions are only servable when the catalog advertises the broadcast's timeline (its /// root `archive` entry): without one there is nothing to render playlists from, so the @@ -405,8 +405,8 @@ impl Producer { let key = (Kind::Video, name.clone()); if let Some(rendition) = current.get(&key) { // Survived the stale pass, so it decodes the same: keep its window, its cached - // init segment and its media sequence, and just take the new advertised bitrate. - rendition.refresh(video.bitrate); + // init segment and its media sequence, and just take the new bitrate and framerate. + rendition.refresh(video.bitrate, video.framerate); continue; } let rendition = match Rendition::video(name.clone(), video, upstream, section.clone(), clock) { @@ -422,7 +422,7 @@ impl Producer { for (name, audio) in &catalog.audio.renditions { let key = (Kind::Audio, name.clone()); if let Some(rendition) = current.get(&key) { - rendition.refresh(audio.bitrate); + rendition.refresh(audio.bitrate, None); continue; } let rendition = match Rendition::audio(name.clone(), audio, upstream, section.clone(), clock) { diff --git a/rs/moq-json/CHANGELOG.md b/rs/moq-json/CHANGELOG.md index 3fe1b6d5a7e..66b8c0045aa 100644 --- a/rs/moq-json/CHANGELOG.md +++ b/rs/moq-json/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.6](https://github.com/moq-dev/moq/compare/moq-json-v0.5.5...moq-json-v0.5.6) - 2026-09-30 + +### Fixed + +- *(net)* keep an aborted track's finished groups, expire ended tracks ([#4378](https://github.com/moq-dev/moq/pull/4378)) + +### Other + +- *(json)* prove the Rust snapshot gate measures the encoded delta ([#4462](https://github.com/moq-dev/moq/pull/4462)) + ## [0.5.5](https://github.com/moq-dev/moq/compare/moq-json-v0.5.4...moq-json-v0.5.5) - 2026-09-27 ### Added diff --git a/rs/moq-json/Cargo.toml b/rs/moq-json/Cargo.toml index 62dc702b489..1a4b0dbf455 100644 --- a/rs/moq-json/Cargo.toml +++ b/rs/moq-json/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.5.5" +version = "0.5.6" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-json/benches/codec.rs b/rs/moq-json/benches/codec.rs index 1c9c3a6999a..fd2d2f58c62 100644 --- a/rs/moq-json/benches/codec.rs +++ b/rs/moq-json/benches/codec.rs @@ -375,6 +375,30 @@ fn consumer(c: &mut Criterion) { group.finish(); } +fn snapshot_budget(c: &mut Criterion) { + let mut group = c.benchmark_group("snapshot_budget"); + for entries in [100, 1000, 10000] { + let value: Map = (0..entries) + .map(|i| (format!("path-{i}"), json!({"bytes": 123}))) + .collect(); + let bytes = serde_json::to_vec(&value).unwrap(); + for bounded in [false, true] { + group.bench_with_input( + BenchmarkId::new(if bounded { "bounded" } else { "unbounded" }, entries), + &bytes, + |b, bytes| { + let mut config = moq_json::snapshot::consumer::Config::default(); + config.max_size = bounded.then_some(8 * 1024 * 1024); + let mut decoder = moq_json::snapshot::Decoder::::new(config); + decoder.snapshot(bytes).unwrap(); + b.iter(|| decoder.delta(black_box(br#"{"path-0":{"bytes":124}}"#)).unwrap()); + }, + ); + } + } + group.finish(); +} + criterion_group!( benches, encode_patch, @@ -384,6 +408,7 @@ criterion_group!( marshal, baseline, producer, - consumer + consumer, + snapshot_budget ); criterion_main!(benches); diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index 8683f64964d..656f62b114a 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -84,6 +84,10 @@ pub enum Error { /// a continuous log. #[error("stream rolled to a second group")] Rolled, + + /// A decoded frame or reconstructed snapshot exceeded its configured byte budget. + #[error("decoded JSON exceeded {0} bytes")] + TooLarge(usize), } impl From for Error { diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 536d5752cf4..7457b8b947b 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -17,6 +17,10 @@ pub struct Config { /// How the frames are compressed. Must match the encoder's /// [`Config::compression`](super::Config::compression). Defaults to [`Compression::None`]. pub compression: Compression, + + /// Maximum bytes in an inflated frame or the compact JSON of the reconstructed value. + /// Unset preserves the DEFLATE decoder's default frame cap and leaves state size unlimited. + pub max_size: Option, } /// Consumes a JSON value from a track, reconstructing it from snapshots and deltas. diff --git a/rs/moq-json/src/snapshot/decoder.rs b/rs/moq-json/src/snapshot/decoder.rs index e2782df42f5..31ece91018f 100644 --- a/rs/moq-json/src/snapshot/decoder.rs +++ b/rs/moq-json/src/snapshot/decoder.rs @@ -31,6 +31,7 @@ use crate::{Error, Result}; pub struct Decoder { /// Whether frames are DEFLATE-compressed, matching the encoder's config. compression: bool, + max_size: Option, /// The current group's DEFLATE decoder (one window per group), rebuilt at each snapshot. flate: Option, @@ -52,6 +53,7 @@ impl Decoder { pub fn new(config: Config) -> Self { Self { compression: config.compression.is_deflate(), + max_size: config.max_size, flate: None, plain: Vec::new(), check: RefCell::new(crate::merge::CheckScratch::default()), @@ -65,37 +67,65 @@ impl Decoder { /// Also starts the group's DEFLATE window, so this must be called at every group boundary, not /// only the first. pub fn snapshot(&mut self, payload: &[u8]) -> Result<()> { - // Each group is its own compressed stream, so the window starts cold here. - self.flate = self.compression.then(moq_flate::Decoder::new); - self.current = Some(match self.flate.as_mut() { - Some(flate) => serde_json::from_slice(&flate.frame(payload)?)?, - None => serde_json::from_slice(payload)?, + self.current = None; + // Every group starts a new DEFLATE window; enforce the budget while inflating. + self.flate = self.compression.then(|| { + moq_flate::Decoder::with_max_frame_size(self.max_size.map_or(moq_flate::DEFAULT_MAX_FRAME_SIZE, |size| { + (size as u64).min(moq_flate::DEFAULT_MAX_FRAME_SIZE) + })) }); - Ok(()) + let inflated = self.flate.as_mut().map(|flate| flate.frame(payload)).transpose()?; + let plain = inflated.as_deref().unwrap_or(payload); + if let Some(limit) = self.max_size + && plain.len() > limit + { + return Err(Error::TooLarge(limit)); + } + self.current = Some(serde_json::from_slice(plain)?); + self.check_size() } - /// Apply one of a group's later frames: an [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396.html) - /// merge patch against the current value. - /// - /// Errors with [`Error::MissingSnapshot`] when no snapshot has been applied yet, since a patch - /// has nothing to apply to. + /// Apply a merge patch, refusing frames or reconstructed state beyond the configured budget. + /// A failed patch invalidates the baseline; start a new snapshot before applying more deltas. pub fn delta(&mut self, payload: &[u8]) -> Result<()> { if self.current.is_none() { return Err(Error::MissingSnapshot); } - - let plain = match self.flate.as_mut() { - Some(flate) => { - flate.frame_into(payload, &mut self.plain)?; - self.plain.as_slice() + let result = (|| { + let plain = match self.flate.as_mut() { + Some(flate) => { + flate.frame_into(payload, &mut self.plain)?; + self.plain.as_slice() + } + None => payload, + }; + if let Some(limit) = self.max_size + && plain.len() > limit + { + return Err(Error::TooLarge(limit)); } - None => payload, - }; - crate::merge::apply_bytes( - self.current.as_mut().expect("a snapshot precedes any delta"), - plain, - &self.check, - )?; + crate::merge::apply_bytes( + self.current.as_mut().expect("a snapshot precedes any delta"), + plain, + &self.check, + )?; + self.check_size() + })(); + if result.is_err() { + self.current = None; + } + result + } + + fn check_size(&mut self) -> Result<()> { + let Some(limit) = self.max_size else { return Ok(()) }; + // Count the compact representation without allocating another full snapshot. + // A patch and the prior state are each bounded, and an oversized result is + // released before it can be materialized or used by another patch. + if serde_json::to_writer(Budget(limit), self.current.as_ref().unwrap()).is_err() { + self.current = None; + return Err(Error::TooLarge(limit)); + } Ok(()) } @@ -105,6 +135,22 @@ impl Decoder { } } +struct Budget(usize); + +impl std::io::Write for Budget { + fn write(&mut self, bytes: &[u8]) -> std::io::Result { + if bytes.len() > self.0 { + return Err(std::io::Error::other("JSON size budget exceeded")); + } + self.0 -= bytes.len(); + Ok(bytes.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } +} + impl Decoder { /// Materialize the reconstructed value as `T`, or `None` before the first snapshot. /// @@ -145,7 +191,10 @@ mod test { use serde_json::{Value, json}; fn consume(compression: Compression) -> ConsumerConfig { - ConsumerConfig { compression } + ConsumerConfig { + compression, + ..Default::default() + } } fn deflate() -> Config { @@ -177,6 +226,80 @@ mod test { out } + #[test] + fn inflated_snapshots_and_patches_obey_the_budget() { + for snapshot in [true, false] { + let mut config = consume(Compression::Deflate); + config.max_size = Some(1024); + let mut decoder = Decoder::::new(config); + let mut encoder = moq_flate::Encoder::new(); + if !snapshot { + decoder.snapshot(&encoder.frame(b"{}")).unwrap(); + } + let payload = encoder.frame( + serde_json::to_string(&json!({"large": "x".repeat(4096)})) + .unwrap() + .as_bytes(), + ); + assert!(payload.len() < 1024); + let result = if snapshot { + decoder.snapshot(&payload) + } else { + decoder.delta(&payload) + }; + assert!(matches!(result, Err(Error::Flate(moq_flate::Error::TooLarge(1024))))); + assert!(decoder.value().is_none()); + } + } + + #[test] + fn patches_cannot_accumulate_past_the_budget() { + for compression in [Compression::None, Compression::Deflate] { + let mut config = consume(compression); + config.max_size = Some(13); + let mut decoder = Decoder::::new(config); + let mut encoder = moq_flate::Encoder::new(); + let mut payload = |bytes: &[u8]| { + if compression == Compression::Deflate { + encoder.frame(bytes).to_vec() + } else { + bytes.to_vec() + } + }; + decoder.snapshot(&payload(br#"{"a":1}"#)).unwrap(); + decoder.delta(&payload(br#"{"b":2}"#)).unwrap(); // exactly 13 bytes + assert_eq!(decoder.value(), Some(&json!({"a":1,"b":2}))); + decoder.delta(&payload(br#"{"a":null}"#)).unwrap(); // deletion frees budget + decoder.delta(&payload(br#"{"c":3}"#)).unwrap(); + assert!(matches!( + decoder.delta(&payload(br#"{"d":4}"#)), + Err(Error::TooLarge(13)) + )); + assert!(decoder.value().is_none()); + assert!(matches!(decoder.delta(b"{}"), Err(Error::MissingSnapshot))); + // A fresh group can recover after refusal. + let bytes = if compression == Compression::Deflate { + moq_flate::Encoder::new().frame(b"{}").to_vec() + } else { + b"{}".to_vec() + }; + decoder.snapshot(&bytes).unwrap(); + } + } + + #[test] + fn plain_frames_obey_the_budget_before_parsing() { + let config = ConsumerConfig { + max_size: Some(2), + ..Default::default() + }; + let mut decoder = Decoder::::new(config); + assert!(matches!(decoder.snapshot(b"not json"), Err(Error::TooLarge(2)))); + decoder.snapshot(b"{}").unwrap(); + assert!(matches!(decoder.delta(b"not json"), Err(Error::TooLarge(2)))); + assert!(decoder.value().is_none()); + } + #[test] fn plaintext_roundtrip() { let values = vec![ diff --git a/rs/moq-json/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index 9ad51161713..ac23d567cae 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -215,6 +215,10 @@ pub struct Encoder { /// Frames emitted into the current group, snapshot included. group_frames: usize, + /// The most bytes a group may hold, the cap a delta is admitted under. A field rather than the + /// constant so a test can shrink it to a size it can reach. + max_group_bytes: u64, + /// Whether the next frame has to be a full snapshot, because a frame was lost or the caller cut /// the group. Kept separate from [`last`](Self::last) so a resync doesn't erase the value: that /// field is also what [`Producer::modify`](super::Producer::modify) seeds an edit from, and dropping @@ -235,6 +239,7 @@ impl Encoder { delta_bytes: 0, snapshot_len: 0, group_frames: 0, + max_group_bytes: moq_net::group::MAX_CACHE_BYTES, resync: false, _marker: PhantomData, } @@ -351,7 +356,7 @@ impl Encoder { // come out slightly larger than its input, so the plaintext is not an upper bound. Compressing // first advances the window, but [`Self::snapshot`] opens a fresh one, so an over-budget delta // costs only the wasted compression. - if self.snapshot_len + self.delta_bytes + payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { + if self.snapshot_len + self.delta_bytes + payload.len() as u64 > self.max_group_bytes { return self.snapshot(value).map(Some); } @@ -697,6 +702,47 @@ mod test { ); } + /// A sync-flushed DEFLATE frame can come out larger than its input, so the plaintext is not an + /// upper bound on what lands in the group. A patch that fits the budget by its plaintext but not + /// by its encoded size would otherwise slip through the gate, overflow the group, and evict the + /// snapshot a late joiner needs. Matches the JS `a compressed delta is gated on its encoded size`. + #[test] + fn a_compressed_delta_is_gated_on_its_encoded_size() { + let value = json!({ "v": "x".repeat(1000) }); + let patched = json!({ "v": "x".repeat(1000), "q": "a" }); + let plaintext = serde_json::to_vec(&json!({ "q": "a" })).unwrap().len(); + let config = Config { + delta_ratio: 100, + compression: Compression::Deflate, + }; + + // Measure the frames under the default budget, which admits the delta. + let mut probe = Encoder::::new(config.clone()); + let snapshot = commit(&mut probe, &value).expect("a snapshot"); + let delta = commit(&mut probe, &patched).expect("a delta"); + assert!(!delta.keyframe); + assert!( + delta.payload.len() > plaintext, + "the encoded delta ({}) must outgrow its plaintext ({plaintext}) for this to test anything", + delta.payload.len() + ); + + // A budget with room for the plaintext patch but not the encoded one. + let mut encoder = Encoder::::new(config); + encoder.max_group_bytes = (snapshot.payload.len() + plaintext) as u64; + assert!(commit(&mut encoder, &value).unwrap().keyframe); + + // The patch rolls a fresh snapshot instead of joining the first group. + let rolled = commit(&mut encoder, &patched).expect("a rolled snapshot"); + assert!(rolled.keyframe); + let mut decoder = moq_flate::Decoder::new(); + assert_eq!( + serde_json::from_slice::(&decoder.frame(&rolled.payload).unwrap()).unwrap(), + patched, + "the snapshot carries the whole value, not a patch" + ); + } + #[test] fn compressed_deltas_reuse_the_group_window() { let phrase = "Media over QUIC delivers real-time latency at massive scale"; diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 9b86d81e8d4..761ccaf0094 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -76,6 +76,7 @@ mod test { track, consumer::Config { compression: Compression::Deflate, + ..Default::default() }, ) } diff --git a/rs/moq-loc/CHANGELOG.md b/rs/moq-loc/CHANGELOG.md index 851eb1a60dd..f9919b8a870 100644 --- a/rs/moq-loc/CHANGELOG.md +++ b/rs/moq-loc/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.17](https://github.com/moq-dev/moq/compare/moq-loc-v0.2.16...moq-loc-v0.2.17) - 2026-09-30 + +### Other + +- updated the following local packages: moq-net + ## [0.2.16](https://github.com/moq-dev/moq/compare/moq-loc-v0.2.15...moq-loc-v0.2.16) - 2026-09-27 ### Other diff --git a/rs/moq-loc/Cargo.toml b/rs/moq-loc/Cargo.toml index ca491c7795b..9b254acd5d9 100644 --- a/rs/moq-loc/Cargo.toml +++ b/rs/moq-loc/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.16" +version = "0.2.17" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index f4ef743a18e..3b1f6bac4a3 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.9](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.8...moq-mux-v0.10.9) - 2026-09-30 + +### Added + +- *(srt)* select a program of a multi-program feed ([#4569](https://github.com/moq-dev/moq/pull/4569)) +- *(moq-mux)* estimate the catalog framerate ([#4576](https://github.com/moq-dev/moq/pull/4576)) +- *(cli)* linger export ts across a broadcast that leaves and returns ([#4504](https://github.com/moq-dev/moq/pull/4504)) +- *(ts)* import one program of a multiplex, or each as its own broadcast ([#4505](https://github.com/moq-dev/moq/pull/4505)) +- *(srt)* log the TS importer's per-stream counters on ingest ([#4506](https://github.com/moq-dev/moq/pull/4506)) +- *(mux)* report every TS elementary stream's access units and quiet time ([#4502](https://github.com/moq-dev/moq/pull/4502)) + +### Fixed + +- *(moq-mux)* signal a new time base when the DTS reserve steps the PCR back ([#4574](https://github.com/moq-dev/moq/pull/4574)) +- *(mux)* publish the 48 kHz decoder rate for Opus imports ([#4443](https://github.com/moq-dev/moq/pull/4443)) +- *(mux)* follow the stream's reorder depth in TS export ([#4500](https://github.com/moq-dev/moq/pull/4500)) +- *(mux)* rebind single-track FLV export to a better rendition before the header ([#4445](https://github.com/moq-dev/moq/pull/4445)) +- *(mux)* LOC video groups end with the duration marker ([#4450](https://github.com/moq-dev/moq/pull/4450)) + ## [0.10.8](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.7...moq-mux-v0.10.8) - 2026-09-27 ### Added diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index 3199311ce0d..3c5a09e6be3 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.10.8" +version = "0.10.9" edition = "2024" rust-version.workspace = true @@ -43,3 +43,4 @@ webm-iterable = "0.7" [dev-dependencies] futures = { workspace = true } tokio = { workspace = true, features = ["test-util"] } +tracing-test = { workspace = true, features = ["no-env-filter"] } diff --git a/rs/moq-mux/src/catalog/estimate.rs b/rs/moq-mux/src/catalog/estimate.rs index 9455626547f..52830505b88 100644 --- a/rs/moq-mux/src/catalog/estimate.rs +++ b/rs/moq-mux/src/catalog/estimate.rs @@ -4,8 +4,29 @@ use std::time::{Duration, Instant}; use moq_net::Timestamp; -/// The window over which bitrate is averaged before it is reported. -const BITRATE_WINDOW: Duration = Duration::from_secs(1); +/// The window over which bitrate and framerate are averaged before they are reported. +const RATE_WINDOW: Duration = Duration::from_secs(1); + +/// The frame rates a measurement snaps to. Anything else (a variable-rate source's average) +/// publishes nothing, since consumers size clocks from the value (an fMP4 timescale of +/// `framerate * 1000`). +const FRAMERATES: [f64; 11] = [ + 24_000.0 / 1001.0, + 24.0, + 25.0, + 30_000.0 / 1001.0, + 30.0, + 48.0, + 50.0, + 60_000.0 / 1001.0, + 60.0, + 100.0, + 120.0, +]; + +/// How far a measurement may sit from the rate it snaps to: half the 0.1% gap between an NTSC +/// rate and its integer neighbour, so no measurement is ambiguous between them. +const FRAMERATE_TOLERANCE: f64 = 0.0005; const JITTER_WINDOW: Duration = Duration::from_secs(10); /// The catalog fields an [`Estimator`] can measure from the frames fed to it. @@ -22,6 +43,8 @@ pub struct Estimate { pub bitrate: Option, /// The most this track's minimum flush lateness has trailed the broadcast's earliest track. pub delay: Option, + /// The maximum frame rate in frames per second, when it is a standard one. + pub framerate: Option, } impl Estimate { @@ -42,9 +65,15 @@ impl Estimate { self.delay = delay.into(); self } + + /// Set the frame rate in frames per second (or clear it with `None`). + pub fn with_framerate(mut self, framerate: impl Into>) -> Self { + self.framerate = framerate.into(); + self + } } -/// Measures the catalog jitter and bitrate of one track from the frames written to it. +/// Measures the catalog jitter, bitrate, and framerate of one track from the frames written to it. /// /// A [`container::Producer`](crate::container::Producer) created through the catalog owns one, /// feeds it as you write, and publishes the result automatically. Local encoders also call @@ -85,6 +114,7 @@ impl Estimate { pub struct Estimator { jitter: Jitter, bitrate: Bitrate, + framerate: Framerate, /// This track's recent minimum flush lateness. baseline: Window, /// The recent minimum across every track sharing it. A standalone estimator's is its own, so @@ -113,6 +143,7 @@ impl Estimator { pub fn write(&mut self, timestamp: Timestamp, bytes: usize) { let timestamp = nanos(timestamp); self.bitrate.write(timestamp, bytes); + self.framerate.write(timestamp); } /// Measure when an encoder handed a frame to the transport. Only locally encoded frames should @@ -134,6 +165,7 @@ impl Estimator { /// frame) leaves the span open to fold into the next one, so nothing is lost by cutting often. pub fn cut(&mut self, end: Option) { self.bitrate.cut(end.map(nanos)); + self.framerate.cut(); } /// Discard the open bitrate span and the flush baselines, so nothing is measured across a break @@ -143,6 +175,7 @@ impl Estimator { /// pre-pause minimum would otherwise read as a delay until it left the window. pub fn discontinuity(&mut self) { self.bitrate.discontinuity(); + self.framerate.discontinuity(); self.baseline = Window::default(); self.broadcast.discontinuity(); } @@ -168,6 +201,7 @@ impl Estimator { jitter: self.jitter.current(), bitrate: self.bitrate.current(), delay: (!self.delay.is_zero()).then_some(self.delay), + framerate: self.framerate.max, } } } @@ -195,7 +229,7 @@ fn elapsed(start: u128, end: u128) -> Option { /// Tracks the maximum bitrate in bits per second, averaged over whole spans. /// /// A span's bytes are only counted once it is closed, and the average is taken over at least -/// [`BITRATE_WINDOW`] of media so a lone keyframe doesn't spike the reported value. +/// [`RATE_WINDOW`] of media so a lone keyframe doesn't spike the reported value. #[derive(Default)] struct Bitrate { span: Option, @@ -237,7 +271,7 @@ impl Bitrate { self.window_bytes = self.window_bytes.saturating_add(span.bytes); self.window_duration += duration; - if self.window_duration < BITRATE_WINDOW { + if self.window_duration < RATE_WINDOW { return; } @@ -259,6 +293,69 @@ impl Bitrate { } } +/// Tracks the maximum framerate: frames written per second of advance in the highest timestamp, +/// snapped to one of [`FRAMERATES`]. +/// +/// Not per span like [`Bitrate`]: a reordered group spans more than its own frames (an open GOP's +/// leading pictures present before its keyframe), while the highest timestamp advances one period +/// per frame whatever the order. Sampled at cuts, so every window starts and ends at the same point +/// of the group structure. +#[derive(Default)] +struct Framerate { + /// The highest timestamp written, in scale-free nanoseconds. + high: Option, + /// The highest timestamp when the window opened. + open: Option, + /// Frames written since the window opened. + frames: u64, + max: Option, +} + +impl Framerate { + fn write(&mut self, ts: u128) { + self.high = Some(self.high.map_or(ts, |high| high.max(ts))); + self.frames += 1; + } + + fn cut(&mut self) { + let Some(high) = self.high else { + return; + }; + // The first window opens at a cut too, not at the first frame, which may be a join that + // starts partway into the group structure. + let Some(open) = self.open else { + self.open = Some(high); + self.frames = 0; + return; + }; + let Some(duration) = elapsed(open, high).filter(|duration| *duration >= RATE_WINDOW) else { + return; + }; + let measured = self.frames as f64 / duration.as_secs_f64(); + let snapped = FRAMERATES + .into_iter() + .map(|rate| (rate, (measured - rate).abs() / rate)) + .filter(|(_, error)| *error <= FRAMERATE_TOLERANCE) + .min_by(|a, b| a.1.total_cmp(&b.1)) + .map(|(rate, _)| rate); + if let Some(framerate) = snapped + && self.max.is_none_or(|max| framerate > max) + { + self.max = Some(framerate); + } + self.open = Some(high); + self.frames = 0; + } + + /// Time nothing across a break in the timeline. + fn discontinuity(&mut self) { + *self = Self { + max: self.max, + ..Self::default() + }; + } +} + /// An open run of frames: everything written since the last boundary that could be timed. struct Span { /// Scale-free nanoseconds, per [`nanos`]. @@ -562,6 +659,107 @@ mod tests { assert_eq!(estimate.jitter, None); } + /// Write groups `groups` of `order.len()` frames at 25 fps, in decode order with `order` giving + /// each frame's display offset from its keyframe, cutting at every keyframe like + /// `container::Producer::write`. Group 0 starts a second in, so leading pictures stay positive. + fn feed_groups(estimator: &mut Estimator, groups: std::ops::Range, order: &[i64]) { + for group in groups { + let keyframe = 25 + (group * order.len() as u64) as i64; + for (i, &offset) in order.iter().enumerate() { + let ts = micros(((keyframe + offset) as u64) * 40_000); + if i == 0 { + estimator.cut(Some(ts)); + } + estimator.write(ts, 1_000); + } + } + } + + #[test] + fn framerate_waits_for_the_window() { + let mut estimator = Estimator::new(); + // Half a second of 25 fps. + let order: Vec = (0..12).collect(); + feed_groups(&mut estimator, 0..1, &order); + estimator.cut(None); + assert_eq!(estimator.estimate().framerate, None); + + feed_groups(&mut estimator, 1..5, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } + + /// B-frames in decode order: every group presents a frame below the one written before it. + #[test] + fn framerate_counts_reordered_groups() { + let mut estimator = Estimator::new(); + // IPBB in a 24-frame closed GOP. + let mut order = vec![0]; + for quad in 0..(23 / 3) { + let base = quad * 3; + order.extend([base + 3, base + 1, base + 2]); + } + order.extend(22..24); + assert_eq!(order.len(), 24); + feed_groups(&mut estimator, 0..5, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } + + /// An open GOP's leading pictures present before their keyframe, so a group spans more than + /// its own frames: timing groups by their span would read 24 frames over 27 periods. + #[test] + fn framerate_counts_leading_pictures() { + let mut estimator = Estimator::new(); + // Keyframe, then three leading B-frames presented before it, then the rest. + let mut order = vec![0, -3, -2, -1]; + order.extend(1..21); + assert_eq!(order.len(), 24); + feed_groups(&mut estimator, 0..5, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } + + /// 30000/1001 fps on a 90 kHz clock: no period is a whole number of nanoseconds, and the + /// measurement is 0.1% from 30 fps. + #[test] + fn framerate_snaps_to_ntsc() { + let mut estimator = Estimator::new(); + for i in 0..300u64 { + let ts = Timestamp::from_scale(i * 3003, 90_000).unwrap(); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + estimator.cut(None); + } + assert_eq!(estimator.estimate().framerate, Some(30_000.0 / 1001.0)); + } + + /// A variable-rate source whose windows average no standard rate publishes nothing. + #[test] + fn framerate_skips_nonstandard_rates() { + let mut estimator = Estimator::new(); + // 27 fps: 37 ms apart, give or take. + for i in 0..100u64 { + let ts = micros(i * 37_037); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + } + assert_eq!(estimator.estimate().framerate, None); + } + + /// The highest rate over any window is reported, and a slower one doesn't lower it. + #[test] + fn framerate_reports_the_maximum() { + let mut estimator = Estimator::new(); + let order: Vec = (0..25).collect(); + feed_groups(&mut estimator, 0..3, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + + for i in 0..40u64 { + let ts = micros(4_000_000 + i * 41_667); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + } + assert_eq!(estimator.estimate().framerate, Some(25.0), "24 fps doesn't lower it"); + } + /// A break in the timeline discards the open span rather than timing it across the gap, and /// resets the frame spacing so the gap is never mistaken for a frame duration. #[test] @@ -582,4 +780,22 @@ mod tests { ); assert_eq!(estimator.estimate().jitter, None, "the gap is not a frame duration"); } + + /// Frames on either side of a break are never timed across it. + #[test] + fn discontinuity_resets_the_framerate_window() { + let mut estimator = Estimator::new(); + for i in 0..10u64 { + estimator.write(micros(i * 40_000), 1_000); + } + estimator.discontinuity(); + + // Resumed 40 minutes later at 25 fps. Timed across the gap it would read ~0 fps. + for i in 0..60u64 { + let ts = micros(2_400_000_000 + i * 40_000); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + } + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } } diff --git a/rs/moq-mux/src/catalog/msf/consumer.rs b/rs/moq-mux/src/catalog/msf/consumer.rs index c8e2a256a0a..58374e78ecf 100644 --- a/rs/moq-mux/src/catalog/msf/consumer.rs +++ b/rs/moq-mux/src/catalog/msf/consumer.rs @@ -332,8 +332,9 @@ fn derive_from_codec_config(track: &moq_msf::Track, codec: &AudioCodec, init: by if buf.has_remaining() { return Err(Error::OpusTrailingBytes(track.name.clone()).into()); } + // Opus decodes at 48 kHz; the OpusHead rate is informational. Ok(DerivedAudio { - sample_rate: cfg.sample_rate, + sample_rate: 48_000, channel_count: cfg.channel_count, }) } @@ -654,7 +655,7 @@ mod test { let catalog = from_msf::<()>(&msf).expect("Opus OpusHead should parse"); let audio = catalog.audio.renditions.get("audio0").expect("audio0 rendition"); - assert_eq!(audio.sample_rate, 24_000); + assert_eq!(audio.sample_rate, 48_000, "OpusHead rate is informational"); assert_eq!(audio.channel_count, 6); } diff --git a/rs/moq-mux/src/catalog/tracks.rs b/rs/moq-mux/src/catalog/tracks.rs index 2e040a17ba4..80e29e2fb92 100644 --- a/rs/moq-mux/src/catalog/tracks.rs +++ b/rs/moq-mux/src/catalog/tracks.rs @@ -296,11 +296,13 @@ impl RenditionConfig for hang::catalog::VideoConfig { .with_jitter(self.jitter) .with_bitrate(self.bitrate) .with_delay(self.delay) + .with_framerate(self.framerate) } fn set_estimate(&mut self, estimate: Estimate) { self.jitter = estimate.jitter; self.bitrate = estimate.bitrate; self.delay = estimate.delay; + self.framerate = estimate.framerate; } } @@ -598,6 +600,9 @@ impl> Rendition { if estimate.delay.is_none() { estimate.delay = detected.delay; } + if estimate.framerate.is_none() { + estimate.framerate = detected.framerate; + } estimate } @@ -920,6 +925,7 @@ mod tests { let config = snapshot.video.renditions.get("v").unwrap(); assert!(config.jitter.is_some(), "absent jitter should be auto-detected"); assert!(config.bitrate.is_some(), "absent bitrate should be auto-detected"); + assert_eq!(config.framerate, Some(25.0), "absent framerate should be auto-detected"); } #[test] @@ -989,6 +995,7 @@ mod tests { let hint = VideoHint { bitrate: Some(456), + framerate: Some(30.0), ..Default::default() }; let mut config = config(None, None); @@ -1000,6 +1007,11 @@ mod tests { let snapshot = catalog.snapshot(); let config = snapshot.video.renditions.get("v").unwrap(); assert_eq!(config.bitrate, Some(456), "a hinted bitrate must not be overwritten"); + assert_eq!( + config.framerate, + Some(30.0), + "a hinted framerate must not be overwritten" + ); assert!(config.jitter.is_some(), "the unhinted jitter should still be detected"); } diff --git a/rs/moq-mux/src/codec/aac/mod.rs b/rs/moq-mux/src/codec/aac/mod.rs index e2477911fc8..ad46c1773b9 100644 --- a/rs/moq-mux/src/codec/aac/mod.rs +++ b/rs/moq-mux/src/codec/aac/mod.rs @@ -27,6 +27,26 @@ pub enum Error { #[error("unsupported sample rate index: {0}")] UnsupportedSampleRateIndex(u8), + + /// The channelConfiguration is a reserved value (8, 9, 10, or 15). + #[error("reserved channelConfiguration: {0}")] + ReservedChannelConfig(u8), + + /// A program config element is used with an object type that has no GASpecificConfig. + #[error("channelConfiguration 0 is unsupported for audioObjectType {0}")] + ProgramConfigUnsupported(u8), + + /// ADTS signals a program config element, but none leads the first raw data block. + #[error("channelConfiguration 0 without a program config element leading the first raw data block")] + ProgramConfigMissing, + + /// The program config element ends before its declared fields. + #[error("program config element truncated")] + ProgramConfigTruncated, + + /// The program config element declares zero channels. + #[error("program config element declares no channels")] + ProgramConfigEmpty, } pub type Result = std::result::Result; @@ -46,34 +66,21 @@ impl Config { /// (object_type == 31), and explicit sample rates (freq_index == 15). The /// fields are bit-packed and not byte-aligned, so a bit reader is required: /// with an explicit 24-bit rate the channelConfiguration lands mid-byte after - /// it. Any SBR/PS extension bits after the core fields are consumed. + /// it. A channelConfiguration of 0 takes the count from the program config element + /// that follows, and a reserved one is refused. Any SBR/PS extension bits after the + /// core fields are consumed. pub fn parse(buf: &mut T) -> Result { - if buf.remaining() < 2 { - return Err(Error::ConfigTooShort); - } - let mut reader = BitReader::new(buf); - - // audioObjectType: 5 bits, escaped to 6 more when it reads 31. - let mut object_type = reader.read(5, Error::ConfigTooShort)? as u8; - if object_type == 31 { - object_type = 32 + reader.read(6, Error::ExtendedConfigTooShort)? as u8; - } - - // samplingFrequencyIndex: 4 bits; index 15 means an explicit 24-bit rate follows. - let freq_index = reader.read(4, Error::IncompleteConfig)? as u8; - let sample_rate = if freq_index == 15 { - reader.read(24, Error::ExplicitSampleRateTooShort)? - } else { - *SAMPLE_RATES - .get(freq_index as usize) - .ok_or(Error::UnsupportedSampleRateIndex(freq_index))? + let (object_type, sample_rate, channel_config) = read_header(&mut reader)?; + let channel_count = match channel_config { + 0 => { + let core = read_core(&mut reader, object_type)?; + read_general_audio(&mut reader, core)?; + program_config(&mut reader)? + } + _ => channel_count_from_config(channel_config)?, }; - // channelConfiguration: 4 bits, immediately after the (possibly explicit) rate. - let channel_config = reader.read(4, Error::IncompleteConfig)? as u8; - let channel_count = channel_count_from_config(channel_config); - // AudioSpecificConfig can carry variable-length extensions (SBR, PS, etc.). // We've extracted the essential fields; drain the rest so the buffer is advanced. if buf.remaining() > 0 { @@ -132,6 +139,199 @@ impl Config { } } +/// Read an AudioSpecificConfig's leading fields: the audioObjectType, sample rate, and +/// channelConfiguration. +fn read_header(reader: &mut BitReader) -> Result<(u8, u32, u8)> { + if reader.buf.remaining() < 2 { + return Err(Error::ConfigTooShort); + } + let object_type = read_object_type(reader)?; + + // samplingFrequencyIndex: 4 bits; index 15 means an explicit 24-bit rate follows. + let freq_index = reader.read(4, Error::IncompleteConfig)? as u8; + let sample_rate = if freq_index == 15 { + reader.read(24, Error::ExplicitSampleRateTooShort)? + } else { + *SAMPLE_RATES + .get(freq_index as usize) + .ok_or(Error::UnsupportedSampleRateIndex(freq_index))? + }; + + // channelConfiguration: 4 bits, immediately after the (possibly explicit) rate. + let channel_config = reader.read(4, Error::IncompleteConfig)? as u8; + Ok((object_type, sample_rate, channel_config)) +} + +/// Read the core audioObjectType, which explicit SBR and PS name after an extension rate. Any +/// other object type is its own core, and the leading sample rate is always the core's. +fn read_core(reader: &mut BitReader, object_type: u8) -> Result { + if !matches!(object_type, 5 | 29) { + return Ok(object_type); + } + if reader.read(4, Error::IncompleteConfig)? == 15 { + reader.read(24, Error::IncompleteConfig)?; + } + let core = read_object_type(reader)?; + if core == 22 { + // extensionChannelConfiguration, only for ER BSAC. + reader.read(4, Error::IncompleteConfig)?; + } + Ok(core) +} + +/// Read a GASpecificConfig up to the program config element that a channelConfiguration of 0 +/// puts next, refusing a `core` object type whose specific config is something else. +fn read_general_audio(reader: &mut BitReader, core: u8) -> Result<()> { + if !GENERAL_AUDIO.contains(&core) { + return Err(Error::ProgramConfigUnsupported(core)); + } + + // frameLengthFlag, dependsOnCoreCoder (then a 14-bit coreCoderDelay), and extensionFlag. + reader.read(1, Error::IncompleteConfig)?; + if reader.read(1, Error::IncompleteConfig)? == 1 { + reader.read(14, Error::IncompleteConfig)?; + } + reader.read(1, Error::IncompleteConfig)?; + Ok(()) +} + +/// Build the AudioSpecificConfig for a stream that signals its fields per frame, as ADTS does. +/// +/// A `channel_config` of 0 means a program config element leads `block`, the stream's first raw +/// data block; it moves into the config, so the config describes the channels on its own, and +/// `block` advances past it. Any other value leaves `block` untouched. An element placed anywhere +/// else is refused: reaching past the channel data needs a full Huffman decode. +pub(crate) fn in_band_config(profile: u8, sample_rate: u32, channel_config: u8, block: &mut &[u8]) -> Result { + let mut out = BitWriter::default(); + out.write(5, u32::from(profile & 0x1F)); + match SAMPLE_RATES.iter().position(|&rate| rate == sample_rate) { + Some(index) => out.write(4, index as u32), + None => { + out.write(4, 15); + out.write(24, sample_rate); + } + } + out.write(4, u32::from(channel_config)); + + if channel_config == 0 { + // GASpecificConfig: frameLengthFlag, dependsOnCoreCoder, and extensionFlag, all clear. + out.write(3, 0); + + // The element ends byte aligned to the block, so the reader stops exactly past it. + let mut reader = BitReader::new(block); + if reader.read(3, Error::ProgramConfigMissing)? != ID_PCE { + return Err(Error::ProgramConfigMissing); + } + reader.record = Some(out); + program_config(&mut reader)?; + out = reader.record.take().expect("recording set above"); + } + + Ok(Bytes::from(out.bytes)) +} + +/// The fields a stream that signals its config per frame, as ADTS does, carries in each header. +#[derive(Clone, Debug, PartialEq)] +pub(crate) struct InBand { + /// The core audioObjectType. Explicit SBR and PS name it under their own, and a decoder finds + /// them again in band, as it would in a stream that never signaled them (implicit signaling). + pub object_type: u8, + /// The core's sample rate, which SBR doubles on output. + pub sample_rate: u32, + pub channel_config: u8, + /// When `channel_config` is 0, the program config element framed to lead a raw data block: + /// its element ID, then the element aligned to the block. + pub program_config: Option, +} + +/// Split an AudioSpecificConfig into what a stream that carries it per frame signals, as ADTS +/// does; the inverse of [`in_band_config`]. +pub(crate) fn in_band(asc: &[u8]) -> Result { + let mut asc = asc; + let mut reader = BitReader::new(&mut asc); + let (object_type, sample_rate, channel_config) = read_header(&mut reader)?; + let core = read_core(&mut reader, object_type)?; + + let program_config = match channel_config { + 0 => { + read_general_audio(&mut reader, core)?; + let mut out = BitWriter::default(); + out.write(3, ID_PCE); + reader.record = Some(out); + program_config(&mut reader)?; + Some(Bytes::from(reader.record.take().expect("recording set above").bytes)) + } + _ => None, + }; + + Ok(InBand { + object_type: core, + sample_rate, + channel_config, + program_config, + }) +} + +/// The raw data block element ID of a program config element (ISO 14496-3 Table 4.85). +const ID_PCE: u32 = 5; + +/// The audioObjectTypes whose specific config is a GASpecificConfig (ISO 14496-3 §1.6.2.1), the +/// only ones where channelConfiguration 0 means a program config element follows. +const GENERAL_AUDIO: [u8; 12] = [1, 2, 3, 4, 6, 7, 17, 19, 20, 21, 22, 23]; + +/// Read an audioObjectType: 5 bits, escaped to 6 more when it reads 31. +fn read_object_type(reader: &mut BitReader) -> Result { + let object_type = reader.read(5, Error::ConfigTooShort)? as u8; + if object_type == 31 { + return Ok(32 + reader.read(6, Error::ExtendedConfigTooShort)? as u8); + } + Ok(object_type) +} + +/// Walk a program_config_element (ISO 14496-3 Table 4.2) to the number of channels it outputs. +/// +/// Its byte alignment is relative to where the reader started: the AudioSpecificConfig, or the +/// raw data block. +fn program_config(reader: &mut BitReader) -> Result { + let mut read = |n| reader.read(n, Error::ProgramConfigTruncated); + + // element_instance_tag, object_type, sampling_frequency_index. + read(10)?; + let (front, side, back) = (read(4)?, read(4)?, read(4)?); + let (lfe, assoc, cc) = (read(2)?, read(3)?, read(4)?); + // Mono and stereo mixdowns each name an element; a matrix mixdown an index and a flag. + for bits in [4, 4, 3] { + if read(1)? == 1 { + read(bits)?; + } + } + + let mut channels = lfe; + for _ in 0..front + side + back { + // A channel pair element carries two channels, a single channel element one. + channels += 1 + read(1)?; + read(4)?; + } + // Tags of the LFE and data elements, then each coupling channel element's switch flag and tag. + for _ in 0..lfe + assoc { + read(4)?; + } + for _ in 0..cc { + read(5)?; + } + + reader.align(); + let comment = reader.read(8, Error::ProgramConfigTruncated)?; + for _ in 0..comment { + reader.read(8, Error::ProgramConfigTruncated)?; + } + + if channels == 0 { + return Err(Error::ProgramConfigEmpty); + } + Ok(channels) +} + /// The 13 standard AAC sampling frequencies, indexed by samplingFrequencyIndex /// (ISO 14496-3 Table 1.18). Index 15 is the escape for an explicit 24-bit rate. const SAMPLE_RATES: [u32; 13] = [ @@ -147,6 +347,8 @@ struct BitReader<'a, T: Buf> { buf: &'a mut T, current: u8, bits_left: u8, + /// Every bit read is copied here when set, with alignment redone on the writer's own bytes. + record: Option, } impl<'a, T: Buf> BitReader<'a, T> { @@ -155,6 +357,15 @@ impl<'a, T: Buf> BitReader<'a, T> { buf, current: 0, bits_left: 0, + record: None, + } + } + + /// Skip to the next byte boundary. + fn align(&mut self) { + self.bits_left = 0; + if let Some(record) = &mut self.record { + record.align(); } } @@ -172,27 +383,52 @@ impl<'a, T: Buf> BitReader<'a, T> { self.bits_left -= 1; value = (value << 1) | u32::from((self.current >> self.bits_left) & 1); } + if let Some(record) = &mut self.record { + record.write(n, value); + } Ok(value) } } -/// Map an AAC `channel_config` (ISO 14496-3 Table 1.19) to its real channel count. -/// Configs 1..=6 happen to be identity (5.1 has config=6 and 6 channels). Config -/// 7 is 7.1 = 8 channels. Config 0 means "described elsewhere" — we default to -/// stereo. -fn channel_count_from_config(channel_config: u8) -> u32 { - match channel_config { - 1..=6 => channel_config as u32, - 7 => 8, - 0 => { - tracing::warn!("channel_config=0 (program config element) unsupported, defaulting to stereo"); - 2 - } - _ => { - tracing::warn!(channel_config, "unsupported channel config, defaulting to stereo"); - 2 +/// MSB-first bit writer, the inverse of [`BitReader`]. +#[derive(Default)] +struct BitWriter { + bytes: Vec, + /// Bits used in the last byte; 0 when the next write starts a new one. + used: u8, +} + +impl BitWriter { + /// Write the low `n` bits (n <= 32) of `value`, MSB-first. + fn write(&mut self, n: u8, value: u32) { + for i in (0..n).rev() { + if self.used == 0 { + self.bytes.push(0); + } + let bit = ((value >> i) & 1) as u8; + *self.bytes.last_mut().expect("pushed above") |= bit << (7 - self.used); + self.used = (self.used + 1) % 8; } } + + /// Pad the last byte with zeros. + fn align(&mut self) { + self.used = 0; + } +} + +/// Map an AAC `channel_config` (ISO 14496-3 Table 1.19) to its channel count, for every value but +/// 0, which a program config element describes instead. Configs 1..=6 are identity. 7, 12, and 14 +/// are 8 channels (7.1 with wide fronts, rear surrounds, or front heights), 11 is 6.1, and 13 is +/// 22.2. The rest are reserved. +fn channel_count_from_config(channel_config: u8) -> Result { + match channel_config { + 1..=6 => Ok(channel_config as u32), + 7 | 12 | 14 => Ok(8), + 11 => Ok(7), + 13 => Ok(24), + _ => Err(Error::ReservedChannelConfig(channel_config)), + } } /// Inverse of [`channel_count_from_config`]. Defaults to stereo for unsupported @@ -281,10 +517,239 @@ mod tests { assert_eq!(parsed.channel_count, 8, "7.1 surround should round-trip as 8 channels"); } + /// The AudioSpecificConfig ffmpeg 9.0.1 writes for quad (`-af pan=quad|...`, native `aac` + /// encoder, `.m4a`): channelConfiguration 0 and a program config element with two channel + /// pair elements, front and back, then a "Lavc63.1.101" comment and an SBR sync extension. + const FFMPEG_QUAD_ASC: [u8; 24] = [ + 0x11, 0x80, 0x04, 0xC4, 0x04, 0x00, 0x21, 0x10, 0x0C, 0x4C, 0x61, 0x76, 0x63, 0x36, 0x33, 0x2E, 0x31, 0x2E, + 0x31, 0x30, 0x31, 0x56, 0xE5, 0x00, + ]; + + /// Write a program config element with `front`, `side`, and `back` elements (true for a + /// channel pair) and `lfe` LFE elements, starting at the writer's position. + fn write_pce(out: &mut BitWriter, front: &[bool], side: &[bool], back: &[bool], lfe: u32) { + // element_instance_tag, object_type (LC), sampling_frequency_index (48 kHz). + out.write(4, 0); + out.write(2, 1); + out.write(4, 3); + out.write(4, front.len() as u32); + out.write(4, side.len() as u32); + out.write(4, back.len() as u32); + out.write(2, lfe); + // No data or coupling elements, and no mixdowns. + out.write(3, 0); + out.write(4, 0); + out.write(3, 0); + for (tag, &cpe) in front.iter().chain(side).chain(back).enumerate() { + out.write(1, cpe.into()); + out.write(4, tag as u32); + } + for tag in 0..lfe { + out.write(4, tag); + } + out.align(); + // A one-byte comment. + out.write(8, 1); + out.write(8, b'x'.into()); + } + + /// An AudioSpecificConfig with channelConfiguration 0 around [`write_pce`]'s element. + fn pce_asc(object_type: u8, front: &[bool], side: &[bool], back: &[bool], lfe: u32) -> Vec { + let mut out = BitWriter::default(); + out.write(5, object_type.into()); + out.write(4, 3); + out.write(4, 0); + out.write(3, 0); + write_pce(&mut out, front, side, back, lfe); + out.bytes + } + #[test] - fn channel_config_zero_falls_back_to_stereo() { - // Config 0 means "described in PCE" which we don't implement. - assert_eq!(channel_count_from_config(0), 2); + fn parses_ffmpeg_program_config_element() { + let cfg = Config::parse(&mut FFMPEG_QUAD_ASC.as_slice()).unwrap(); + assert_eq!(cfg.profile, 2); + assert_eq!(cfg.sample_rate, 48_000); + assert_eq!(cfg.channel_count, 4, "two channel pair elements"); + } + + #[test] + fn parses_program_config_element_counts() { + // 5.1: a single and a pair in front, a pair in back, and an LFE. + let asc = pce_asc(2, &[false, true], &[], &[true], 1); + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, 6); + + // Side elements count too: 3/2/2 with no LFE. + let asc = pce_asc(2, &[false, true], &[true], &[true], 0); + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, 7); + } + + /// audioObjectType 5 (SBR), 24 kHz core, channelConfiguration 0, a 48 kHz extension rate, + /// then the core type (LC) whose GASpecificConfig carries a front and back pair. + fn sbr_pce_asc() -> Vec { + let mut out = BitWriter::default(); + out.write(5, 5); + out.write(4, 6); + out.write(4, 0); + out.write(4, 3); + out.write(5, 2); + out.write(3, 0); + write_pce(&mut out, &[true], &[], &[true], 0); + out.bytes + } + + #[test] + fn parses_program_config_element_behind_explicit_sbr() { + let cfg = Config::parse(&mut sbr_pce_asc().as_slice()).unwrap(); + assert_eq!(cfg.profile, 5); + assert_eq!(cfg.channel_count, 4); + } + + #[test] + fn refuses_bad_program_config_elements() { + let asc = pce_asc(2, &[], &[], &[], 0); + assert!(matches!( + Config::parse(&mut asc.as_slice()), + Err(Error::ProgramConfigEmpty) + )); + + let asc = pce_asc(2, &[true], &[], &[], 0); + assert!(matches!( + Config::parse(&mut &asc[..asc.len() - 1]), + Err(Error::ProgramConfigTruncated) + )); + + // ALS (36) describes its channels in its own specific config, not a PCE. + let mut out = BitWriter::default(); + out.write(5, 31); + out.write(6, 4); + out.write(4, 3); + out.write(4, 0); + out.write(8, 0); + assert!(matches!( + Config::parse(&mut out.bytes.as_slice()), + Err(Error::ProgramConfigUnsupported(36)) + )); + } + + #[test] + fn channel_config_dispositions() { + let expected = [1, 2, 3, 4, 5, 6, 8]; + for (config, count) in (1..=7).zip(expected) { + let asc = [0x11, 0x80 | (config << 3)]; + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, count); + } + + for (config, count) in [(11, 7), (12, 8), (13, 24), (14, 8)] { + let asc = [0x11, 0x80 | (config << 3)]; + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, count); + } + + for config in [8, 9, 10, 15] { + let asc = [0x11, 0x80 | (config << 3)]; + assert!(matches!( + Config::parse(&mut asc.as_slice()), + Err(Error::ReservedChannelConfig(c)) if c == config + )); + } + } + + #[test] + fn in_band_config_moves_the_program_config_element() { + // A raw data block leading with ID_PCE, which puts the element 3 bits off the byte grid + // the AudioSpecificConfig puts it on, so the copy has to redo the alignment. + let mut block = BitWriter::default(); + block.write(3, ID_PCE); + write_pce(&mut block, &[false, true], &[], &[true], 1); + let pce = block.bytes.clone(); + // The channel elements that follow are never read. + block.write(8, 0xFF); + + let mut rest = block.bytes.as_slice(); + let asc = in_band_config(2, 48_000, 0, &mut rest).unwrap(); + assert_eq!(asc, pce_asc(2, &[false, true], &[], &[true], 1)); + assert_eq!(Config::parse(&mut asc.as_ref()).unwrap().channel_count, 6); + assert_eq!(rest, [0xFF], "the element moves out of the block"); + + // And back: the element leads the block again, byte for byte. + let in_band = in_band(&asc).unwrap(); + assert_eq!(in_band.channel_config, 0); + assert_eq!(in_band.program_config, Some(Bytes::from(pce))); + } + + #[test] + fn in_band_of_ffmpeg_program_config_element() { + // Round trip ffmpeg's own element through a raw data block and back into a config. The + // trailing SBR sync extension is not part of the element, so it drops. + let in_band = in_band(&FFMPEG_QUAD_ASC).unwrap(); + assert_eq!(in_band.channel_config, 0); + let pce = in_band.program_config.unwrap(); + let mut block = pce.as_ref(); + let asc = in_band_config(2, 48_000, 0, &mut block).unwrap(); + assert!(block.is_empty(), "the element is all that was framed"); + assert_eq!(asc, FFMPEG_QUAD_ASC[..FFMPEG_QUAD_ASC.len() - 3]); + } + + #[test] + fn in_band_without_a_program_config_element() { + let stereo = in_band(&[0x11, 0x90]).unwrap(); + assert_eq!((stereo.channel_config, stereo.program_config), (2, None)); + assert_eq!(in_band(&[0x11, 0xE0]).unwrap().channel_config, 12); + } + + #[test] + fn in_band_of_explicit_sbr_is_its_lc_core() { + // GStreamer 1.28 `fdkaacenc` at 48 kHz stereo: HE-AAC is SBR over a 24 kHz stereo LC core, + // and HE-AACv2 is PS over a mono one. + for (asc, channel_config) in [([0x2B, 0x11, 0x88, 0x00], 2), ([0xEB, 0x09, 0x88, 0x00], 1)] { + let expected = InBand { + object_type: 2, + sample_rate: 24_000, + channel_config, + program_config: None, + }; + assert_eq!(in_band(&asc).unwrap(), expected); + } + + // A config naming SBR but stopping before its core has no core to name. + assert!(matches!(in_band(&[0x2A, 0x10]), Err(Error::IncompleteConfig))); + } + + #[test] + fn in_band_of_explicit_sbr_keeps_its_program_config_element() { + let in_band = in_band(&sbr_pce_asc()).unwrap(); + assert_eq!(in_band.object_type, 2); + assert_eq!(in_band.sample_rate, 24_000); + assert_eq!(in_band.channel_config, 0); + let pce = in_band.program_config.expect("a program config element"); + let mut block = pce.as_ref(); + let asc = in_band_config(2, 24_000, 0, &mut block).unwrap(); + assert_eq!(Config::parse(&mut asc.as_ref()).unwrap().channel_count, 4); + } + + #[test] + fn in_band_config_refuses_a_block_without_a_leading_pce() { + // ID_CPE first: any element past the channel data is out of reach. + assert!(matches!( + in_band_config(2, 48_000, 0, &mut [0x20, 0x00].as_slice()), + Err(Error::ProgramConfigMissing) + )); + assert!(matches!( + in_band_config(2, 48_000, 0, &mut [].as_slice()), + Err(Error::ProgramConfigMissing) + )); + } + + #[test] + fn in_band_config_matches_encode() { + // Without a PCE the block is unread and the config is the plain two-byte form. + let asc = in_band_config(2, 44_100, 2, &mut [].as_slice()).unwrap(); + let encoded = Config { + profile: 2, + sample_rate: 44_100, + channel_count: 2, + } + .encode(); + assert_eq!(asc, encoded); } #[test] diff --git a/rs/moq-mux/src/codec/h264/import.rs b/rs/moq-mux/src/codec/h264/import.rs index d672ab6f1ba..c5ce2394693 100644 --- a/rs/moq-mux/src/codec/h264/import.rs +++ b/rs/moq-mux/src/codec/h264/import.rs @@ -267,6 +267,7 @@ fn config_from_avcc(avcc_bytes: &[u8]) -> Result { }); config.coded_width = avcc.coded_width; config.coded_height = avcc.coded_height; + config.framerate = avcc.sps.first().and_then(|sps| super::sps_framerate(sps)); config.description = Some(Bytes::copy_from_slice(avcc_bytes)); Ok(config) } @@ -284,6 +285,7 @@ fn config_from_sps(sps_nal: &[u8]) -> Result { }); config.coded_width = Some(sps.coded_width); config.coded_height = Some(sps.coded_height); + config.framerate = super::sps_framerate(sps_nal); Ok(config) } @@ -319,6 +321,24 @@ mod tests { (track, catalog) } + /// Only a fixed-rate SPS states the frame rate; without `fixed_frame_rate_flag` its tick is a + /// ceiling, left for the catalog estimator to measure. + #[test] + fn config_takes_only_a_fixed_framerate() { + use crate::codec::h264::fixtures; + + let fixed = super::super::build_avcc( + &[Bytes::from_static(fixtures::SPS_IPB)], + &[Bytes::from_static(fixtures::PPS)], + ) + .unwrap(); + assert_eq!(config(&fixed).unwrap().framerate, Some(25.0)); + + let mut inline = vec![0, 0, 0, 1]; + inline.extend_from_slice(fixtures::SPS_IPB_VARIABLE); + assert_eq!(config(&inline).unwrap().framerate, None); + } + /// An avcC initializer resolves a config with the avcC stored as `description`. #[tokio::test(start_paused = true)] async fn initialize_avc1_lands_in_catalog() { diff --git a/rs/moq-mux/src/codec/h264/mod.rs b/rs/moq-mux/src/codec/h264/mod.rs index 9baf5367255..bddbe199633 100644 --- a/rs/moq-mux/src/codec/h264/mod.rs +++ b/rs/moq-mux/src/codec/h264/mod.rs @@ -144,6 +144,202 @@ impl Sps { } } +/// The reordering an SPS NAL unit declares in its VUI: `max_num_reorder_frames` from the +/// bitstream restriction, and the frame period when `fixed_frame_rate_flag` is set. +/// +/// `None` when the SPS carries no VUI or no bitstream restriction, or fails to parse. +pub(crate) fn sps_reorder(nal: &[u8]) -> Option { + let vui = sps_vui(nal)?; + Some(crate::codec::video::Reorder { + depth: vui.depth?, + period: vui.period, + }) +} + +/// The frame rate an SPS NAL unit fixes with `fixed_frame_rate_flag`. +/// +/// Without the flag the VUI tick only bounds the rate from above, so it is left to measurement. +/// A field-capable SPS is left out too: `pic_struct` in the slice header then decides whether a +/// tick counts a field or a frame (ITU-T H.264 E.2.1, Table E-6), and only measurement settles it. +pub(crate) fn sps_framerate(nal: &[u8]) -> Option { + let vui = sps_vui(nal)?; + if !vui.frame_only { + return None; + } + let (units, scale) = vui.period?; + Some(scale as f64 / units as f64) +} + +/// What an SPS VUI declares about picture timing. +struct Vui { + /// `frame_mbs_only_flag`: every picture is a frame, so two ticks are one frame. + frame_only: bool, + /// One frame's duration as `(units, scale)` when `fixed_frame_rate_flag` is set. + period: Option<(u64, u64)>, + /// `max_num_reorder_frames`, when the bitstream restriction is present. + depth: Option, +} + +/// `None` when the SPS carries no VUI or fails to parse. +fn sps_vui(nal: &[u8]) -> Option { + if nal.len() < 4 { + return None; + } + let rbsp = h264_parser::nal::ebsp_to_rbsp(&nal[1..]); + let sps = h264_parser::Sps::parse(&rbsp).ok()?; + if !sps.vui_parameters_present_flag { + return None; + } + vui(&rbsp).ok().flatten() +} + +/// Walk an SPS RBSP to its VUI (ITU-T H.264 7.3.2.1.1, E.1.1). `h264_parser` stops at +/// `vui_parameters_present_flag` without exposing its position, so this re-reads the fields +/// before it. +fn vui(rbsp: &[u8]) -> h264_parser::Result> { + use h264_parser::bitreader::BitReader; + use h264_parser::eg::{read_se, read_ue}; + + let mut r = BitReader::new(rbsp); + let profile_idc = r.read_u8()?; + r.skip_bits(16)?; // constraint flags, reserved bits, level_idc + read_ue(&mut r)?; // seq_parameter_set_id + if matches!( + profile_idc, + 100 | 110 | 122 | 244 | 44 | 83 | 86 | 118 | 128 | 138 | 139 | 134 | 135 + ) { + let chroma_format_idc = read_ue(&mut r)?; + if chroma_format_idc == 3 { + r.skip_bits(1)?; // separate_colour_plane_flag + } + read_ue(&mut r)?; // bit_depth_luma_minus8 + read_ue(&mut r)?; // bit_depth_chroma_minus8 + r.skip_bits(1)?; // qpprime_y_zero_transform_bypass_flag + if r.read_flag()? { + let lists = if chroma_format_idc == 3 { 12 } else { 8 }; + for i in 0..lists { + if r.read_flag()? { + let size = if i < 6 { 16 } else { 64 }; + let (mut last, mut next) = (8i32, 8i32); + for _ in 0..size { + if next != 0 { + next = (last + read_se(&mut r)?).rem_euclid(256); + } + if next != 0 { + last = next; + } + } + } + } + } + } + read_ue(&mut r)?; // log2_max_frame_num_minus4 + match read_ue(&mut r)? { + 0 => { + read_ue(&mut r)?; // log2_max_pic_order_cnt_lsb_minus4 + } + 1 => { + r.skip_bits(1)?; // delta_pic_order_always_zero_flag + read_se(&mut r)?; // offset_for_non_ref_pic + read_se(&mut r)?; // offset_for_top_to_bottom_field + for _ in 0..read_ue(&mut r)? { + read_se(&mut r)?; // offset_for_ref_frame + } + } + _ => {} + } + read_ue(&mut r)?; // max_num_ref_frames + r.skip_bits(1)?; // gaps_in_frame_num_value_allowed_flag + read_ue(&mut r)?; // pic_width_in_mbs_minus1 + read_ue(&mut r)?; // pic_height_in_map_units_minus1 + let frame_only = r.read_flag()?; // frame_mbs_only_flag + if !frame_only { + r.skip_bits(1)?; // mb_adaptive_frame_field_flag + } + r.skip_bits(1)?; // direct_8x8_inference_flag + if r.read_flag()? { + for _ in 0..4 { + read_ue(&mut r)?; // frame_crop_*_offset + } + } + if !r.read_flag()? { + return Ok(None); + } + + // vui_parameters() + if r.read_flag()? && r.read_u8()? == 255 { + r.skip_bits(32)?; // sar_width, sar_height + } + if r.read_flag()? { + r.skip_bits(1)?; // overscan_appropriate_flag + } + if r.read_flag()? { + r.skip_bits(4)?; // video_format, video_full_range_flag + if r.read_flag()? { + r.skip_bits(24)?; // colour_primaries, transfer_characteristics, matrix_coefficients + } + } + if r.read_flag()? { + read_ue(&mut r)?; // chroma_sample_loc_type_top_field + read_ue(&mut r)?; // chroma_sample_loc_type_bottom_field + } + let mut period = None; + if r.read_flag()? { + let units = r.read_bits(32)?; + let scale = r.read_bits(32)?; + // With a fixed rate, a frame lasts two ticks (E.2.1). + if r.read_flag()? && units > 0 && scale > 0 { + period = Some((2 * u64::from(units), u64::from(scale))); + } + } + let nal_hrd = r.read_flag()?; + if nal_hrd { + skip_hrd(&mut r)?; + } + let vcl_hrd = r.read_flag()?; + if vcl_hrd { + skip_hrd(&mut r)?; + } + if nal_hrd || vcl_hrd { + r.skip_bits(1)?; // low_delay_hrd_flag + } + r.skip_bits(1)?; // pic_struct_present_flag + if !r.read_flag()? { + return Ok(Some(Vui { + frame_only, + period, + depth: None, + })); + } + r.skip_bits(1)?; // motion_vectors_over_pic_boundaries_flag + for _ in 0..4 { + read_ue(&mut r)?; // max_bytes_per_pic_denom .. log2_max_mv_length_vertical + } + let depth = read_ue(&mut r)?; // max_num_reorder_frames + Ok(Some(Vui { + frame_only, + period, + depth: Some(depth), + })) +} + +/// Skip `hrd_parameters()` (ITU-T H.264 E.1.2). +fn skip_hrd(r: &mut h264_parser::bitreader::BitReader) -> h264_parser::Result<()> { + use h264_parser::eg::read_ue; + + let cpb_cnt_minus1 = read_ue(r)?; + if cpb_cnt_minus1 > 31 { + return Err(h264_parser::Error::MalformedSps("cpb_cnt_minus1 out of range".into())); + } + r.skip_bits(8)?; // bit_rate_scale, cpb_size_scale + for _ in 0..=cpb_cnt_minus1 { + read_ue(r)?; // bit_rate_value_minus1 + read_ue(r)?; // cpb_size_value_minus1 + r.skip_bits(1)?; // cbr_flag + } + r.skip_bits(20) // four delay/offset lengths +} + /// Parsed AVCDecoderConfigurationRecord (ISO/IEC 14496-15 §5.3.3.1.2). /// /// Just the codec-config fields that the hang catalog records. The original @@ -469,12 +665,90 @@ fn process_nal( } } +/// Real SPS NAL units from 64x64, 25 fps x264 encodes (High profile, 50 Hz VUI tick), for +/// tests that need a VUI with a bitstream restriction. +#[cfg(test)] +pub(crate) mod fixtures { + /// `bframes=1:force-cfr=1`: one B-frame per reference (`max_num_reorder_frames` 1) with + /// `fixed_frame_rate_flag` set. + pub(crate) const SPS_IPB: &[u8] = &[ + 0x67, 0x64, 0x00, 0x0a, 0xac, 0xe4, 0x10, 0x9b, 0x01, 0x10, 0x00, 0x00, 0x03, 0x00, 0x10, 0x00, 0x00, 0x03, + 0x03, 0x28, 0xf1, 0x22, 0x51, 0x20, + ]; + /// `bframes=3:b-pyramid=2:force-cfr=1`: a B-pyramid (`max_num_reorder_frames` 2) with + /// `fixed_frame_rate_flag` set. + pub(crate) const SPS_PYRAMID: &[u8] = &[ + 0x67, 0x64, 0x00, 0x0a, 0xac, 0xd9, 0x44, 0x26, 0xc0, 0x44, 0x00, 0x00, 0x03, 0x00, 0x04, 0x00, 0x00, 0x03, + 0x00, 0xca, 0x3c, 0x48, 0x96, 0x58, + ]; + /// `bframes=1` at x264's default: `max_num_reorder_frames` 1 without `fixed_frame_rate_flag`. + pub(crate) const SPS_IPB_VARIABLE: &[u8] = &[ + 0x67, 0x64, 0x00, 0x0a, 0xac, 0xe4, 0x10, 0x9b, 0x01, 0x10, 0x00, 0x00, 0x03, 0x00, 0x10, 0x00, 0x00, 0x03, + 0x03, 0x20, 0xf1, 0x22, 0x51, 0x20, + ]; + /// `interlaced=1:tff=1:bframes=0` at 320x240, with `fixed_frame_rate_flag` forced on: the same + /// 50 Hz tick, but `frame_mbs_only_flag` 0 leaves `pic_struct` to the slice header. + pub(crate) const SPS_FIELD: &[u8] = &[ + 0x67, 0xf4, 0x00, 0x15, 0x91, 0x9d, 0x02, 0x82, 0x1f, 0x89, 0xc0, 0x44, 0x00, 0x00, 0x03, 0x00, 0x04, 0x00, + 0x00, 0x03, 0x00, 0xca, 0x7c, 0x50, 0xaa, 0x80, + ]; + pub(crate) const PPS: &[u8] = &[0x68, 0xeb, 0xe3, 0xcb, 0x22, 0xc0]; +} + #[cfg(test)] mod tests { use super::*; const SC4: &[u8] = &[0, 0, 0, 1]; + #[test] + fn sps_reorder_reads_the_vui() { + use crate::codec::video::Reorder; + + let fixed = Some((2, 50)); + assert_eq!( + sps_reorder(fixtures::SPS_IPB), + Some(Reorder { + depth: 1, + period: fixed + }) + ); + assert_eq!( + sps_reorder(fixtures::SPS_PYRAMID), + Some(Reorder { + depth: 2, + period: fixed + }) + ); + assert_eq!( + sps_reorder(fixtures::SPS_IPB_VARIABLE), + Some(Reorder { depth: 1, period: None }) + ); + // The field-capable SPS still declares its depth and tick; only the frame rate needs + // `pic_struct` to read it. + assert_eq!( + sps_reorder(fixtures::SPS_FIELD), + Some(Reorder { + depth: 0, + period: Some((2, 50)) + }) + ); + // Baseline with no VUI declares nothing. + assert_eq!(sps_reorder(&[0x67, 0x42, 0xc0, 0x1f, 0xde]), None); + // A VUI cut short is no declaration rather than a wrong one. + assert_eq!(sps_reorder(&fixtures::SPS_IPB[..fixtures::SPS_IPB.len() - 3]), None); + } + + #[test] + fn sps_framerate_needs_a_fixed_rate() { + assert_eq!(sps_framerate(fixtures::SPS_IPB), Some(25.0)); + // The same 50 Hz tick without `fixed_frame_rate_flag` is only a ceiling. + assert_eq!(sps_framerate(fixtures::SPS_IPB_VARIABLE), None); + // A field-capable SPS makes the tick a field or a frame depending on `pic_struct`. + assert_eq!(sps_framerate(fixtures::SPS_FIELD), None); + assert_eq!(sps_framerate(&[0x67, 0x42, 0xc0, 0x1f, 0xde]), None); + } + fn annexb_frame(nals: &[&[u8]]) -> Bytes { let mut buf = BytesMut::new(); for nal in nals { diff --git a/rs/moq-mux/src/codec/h265/import.rs b/rs/moq-mux/src/codec/h265/import.rs index 23ce9c32228..a46634d931c 100644 --- a/rs/moq-mux/src/codec/h265/import.rs +++ b/rs/moq-mux/src/codec/h265/import.rs @@ -272,7 +272,7 @@ fn config_from_sps(sps_nal: &[u8]) -> Result { }); 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.framerate = super::sps_period(&sps.rbsp).map(|(units, scale)| scale as f64 / units as f64); config.display_aspect_width = vui_data.display_ratio_width; config.display_aspect_height = vui_data.display_ratio_height; Ok(config) @@ -297,19 +297,12 @@ fn find_sps(payload: &[u8]) -> Option { #[derive(Default)] struct VuiData { - framerate: Option, display_ratio_width: Option, display_ratio_height: Option, } impl VuiData { fn new(vui: &scuffle_h265::VuiParameters) -> Self { - // FPS = time_scale / num_units_in_tick - let framerate = vui - .vui_timing_info - .as_ref() - .map(|t| t.time_scale.get() as f64 / t.num_units_in_tick.get() as f64); - let (display_ratio_width, display_ratio_height) = match &vui.aspect_ratio_info { // Extended SAR has explicit arbitrary values for width and height. scuffle_h265::AspectRatioInfo::ExtendedSar { sar_width, sar_height } => { @@ -322,7 +315,6 @@ impl VuiData { }; VuiData { - framerate, display_ratio_width, display_ratio_height, } @@ -369,6 +361,19 @@ mod tests { (track, catalog) } + /// Only an SPS whose HRD fixes the picture rate states it; the VUI tick alone is a ceiling, + /// left for the catalog estimator to measure. + #[test] + fn config_takes_only_a_fixed_framerate() { + let mut fixed = vec![0, 0, 0, 1]; + fixed.extend_from_slice(fixtures::SPS_PYRAMID); + assert_eq!(config(&fixed).unwrap().framerate, Some(25.0)); + + let mut ceiling = vec![0, 0, 0, 1]; + ceiling.extend_from_slice(fixtures::SPS); + assert_eq!(config(&ceiling).unwrap().framerate, None); + } + /// An hvcC initializer resolves a config with the hvcC stored as `description`. /// The hvc1 analogue of the avcC test in [`crate::codec::h264`]'s importer. #[tokio::test(start_paused = true)] diff --git a/rs/moq-mux/src/codec/h265/mod.rs b/rs/moq-mux/src/codec/h265/mod.rs index ab5eda651c1..d0f420e2745 100644 --- a/rs/moq-mux/src/codec/h265/mod.rs +++ b/rs/moq-mux/src/codec/h265/mod.rs @@ -215,6 +215,39 @@ pub(crate) fn config_from_hvcc(hvcc: &[u8]) -> Result Option { + let sps = SpsNALUnit::parse(&mut &nal[..]).ok()?; + let highest = sps.rbsp.sps_max_sub_layers_minus1 as usize; + let reorder = &sps.rbsp.sub_layer_ordering_info.sps_max_num_reorder_pics; + let depth = *reorder.get(highest).or(reorder.last())?; + Some(crate::codec::video::Reorder { + depth: u32::try_from(depth).ok()?, + period: sps_period(&sps.rbsp), + }) +} + +/// One picture's duration at the highest sub-layer as `(units, scale)`, when the VUI's HRD +/// parameters fix the picture rate within the CVS (ITU-T H.265 E.3.2). Without that the VUI tick +/// only bounds the rate from above. +pub(crate) fn sps_period(sps: &scuffle_h265::SpsRbsp) -> Option<(u64, u64)> { + let highest = sps.sps_max_sub_layers_minus1 as usize; + let timing = sps.vui_parameters.as_ref()?.vui_timing_info.as_ref()?; + let sub_layers = &timing.hrd_parameters.as_ref()?.sub_layers; + let elemental = sub_layers + .get(highest) + .or(sub_layers.last())? + .elemental_duration_in_tc_minus1?; + let units = elemental + .checked_add(1)? + .checked_mul(u64::from(timing.num_units_in_tick.get()))?; + Some((units, u64::from(timing.time_scale.get()))) +} + /// Annex-B → length-prefixed transmuxer; the H.265 analogue of /// [`crate::codec::h264::Avc1`]. /// @@ -477,6 +510,13 @@ pub(crate) mod fixtures { 0x02, 0x00, 0x00, 0x03, 0x00, 0x3c, 0x10, ]; pub(crate) const PPS: &[u8] = &[0x44, 0x01, 0xc1, 0x72, 0xb4, 0x62, 0x40]; + /// SPS from a 64x64, 25 fps x265 encode with `bframes=3:b-pyramid=1` and HRD signalling + /// (`sps_max_num_reorder_pics` 2). + pub(crate) const SPS_PYRAMID: &[u8] = &[ + 0x42, 0x01, 0x01, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00, 0x90, 0x00, 0x00, 0x03, 0x00, 0x00, 0x03, 0x00, 0x3c, + 0xa0, 0x20, 0x81, 0x05, 0x96, 0x56, 0x59, 0x24, 0xca, 0xf0, 0x16, 0x80, 0x80, 0x00, 0x00, 0x03, 0x00, 0x80, + 0x00, 0x00, 0x0c, 0xb0, 0x0a, 0x48, 0x2f, 0x00, 0x07, 0xa1, 0x20, 0x00, 0xf4, 0x24, 0x40, + ]; /// An hvcC record built from the real parameter sets (4-byte NALU lengths). pub(crate) fn hvcc() -> Bytes { @@ -507,6 +547,14 @@ mod tests { moq_net::Timestamp::from_micros(0).unwrap() } + #[test] + fn sps_reorder_reads_the_highest_sub_layer() { + let reorder = sps_reorder(fixtures::SPS_PYRAMID).unwrap(); + assert_eq!(reorder.depth, 2); + assert_eq!(reorder.period, Some((1, 25))); + assert_eq!(sps_reorder(&fixtures::SPS[..8]), None); + } + /// hvc1: a length-prefixed access unit with an IDR slice wraps as one keyframe; /// the payload is passed through verbatim. The leading prefix-SEI NAL exercises /// the walk past non-slice NALs. diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index c7b69925d25..3ee70a185a7 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -107,22 +107,23 @@ impl Import { } /// Build a catalog config from an OpusHead. Errors on a malformed or empty buffer. +/// +/// The catalog rate is the decoder's 48 kHz output, not the OpusHead's informational input rate. pub fn config(init: &[u8]) -> crate::Result { let mut buf = init; let mut config: hang::catalog::AudioConfig = Config::parse(&mut buf)?.into(); - // Publish the head as given: re-encoding it would drop a channel mapping table. + // Publish the head as given: a re-encode would rewrite its version byte. config.description = Some(bytes::Bytes::copy_from_slice(init)); Ok(config) } impl From for hang::catalog::AudioConfig { /// Build a catalog config from a config resolved out of band (e.g. gstreamer caps). + /// + /// The catalog describes the decoder's output: Opus always decodes at 48 kHz, whatever the + /// informational input rate in [`Config::sample_rate`] claims. fn from(config: Config) -> Self { - let mut audio = hang::catalog::AudioConfig::new( - hang::catalog::AudioCodec::Opus, - config.sample_rate, - config.channel_count, - ); + let mut audio = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, config.channel_count); audio.description = config.encode().ok(); audio.container = hang::catalog::Container::Legacy; audio @@ -135,6 +136,18 @@ mod tests { use moq_net::Timestamp; + #[test] + fn catalog_rate_is_decoder_rate() { + // A 44.1 kHz input rate is informational; the description keeps it, the catalog does not. + let head = super::Config::new(44_100, 2).encode().unwrap(); + let config = super::config(&head).unwrap(); + assert_eq!(config.sample_rate, 48_000); + assert_eq!(config.description.as_deref(), Some(head.as_ref())); + + let config: hang::catalog::AudioConfig = super::Config::new(44_100, 2).into(); + assert_eq!(config.sample_rate, 48_000); + } + #[tokio::test(start_paused = true)] async fn a_loc_reservation_reaches_the_wire_and_the_catalog() { let mut broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/moq-mux/src/codec/opus/mapping.rs b/rs/moq-mux/src/codec/opus/mapping.rs new file mode 100644 index 00000000000..4157dd5303f --- /dev/null +++ b/rs/moq-mux/src/codec/opus/mapping.rs @@ -0,0 +1,179 @@ +//! The OpusHead channel mapping table (RFC 7845 §5.1.1). + +use bytes::Buf; + +use super::{Error, Result}; + +/// An OpusHead channel mapping table (RFC 7845 §5.1.1), present for every family but 0. +#[derive(Clone, Copy, PartialEq, Eq)] +pub struct Mapping { + family: u8, + streams: u8, + coupled: u8, + channels: u8, + // Sized for the most channels any family allows, so `opus::Config` stays `Copy`. + table: [u8; 255], +} + +/// The fields of a channel mapping table, checked into a [`Mapping`] by [`Mapping::new`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Config<'a> { + /// The channel mapping family; 0 has no table and is refused. + pub family: u8, + /// Number of Opus streams in each packet. + pub streams: u8, + /// How many of those streams are coupled (stereo); they come first. + pub coupled: u8, + /// The decoded channel feeding each output channel, 255 for silence. + pub table: &'a [u8], +} + +/// The family 1 stream counts and table for 1 to 8 channels, as libopus and +/// RFC 7845 §5.1.1.2 lay out the Vorbis channel orders. +const VORBIS: [(u8, u8, &[u8]); 8] = [ + (1, 0, &[0]), + (1, 1, &[0, 1]), + (2, 1, &[0, 2, 1]), + (2, 2, &[0, 1, 2, 3]), + (3, 2, &[0, 4, 1, 2, 3]), + (4, 2, &[0, 4, 1, 2, 3, 5]), + (4, 3, &[0, 4, 1, 2, 3, 5, 6]), + (5, 3, &[0, 6, 1, 2, 3, 4, 5, 7]), +]; + +impl Mapping { + /// The family 1 mapping a surround encoder uses for `channels` in Vorbis + /// order, for sources that name only a channel count. + pub(crate) fn vorbis(channels: u8) -> Result { + let (streams, coupled, table) = *channels + .checked_sub(1) + .and_then(|index| VORBIS.get(index as usize)) + .ok_or(Error::UnsupportedChannelCount(channels as u32))?; + Self::new(Config { + family: 1, + streams, + coupled, + table, + }) + } + + /// Check `config` into a mapping with one output channel per table entry. + /// + /// Refuses family 0, a channel count the family does not allow, and a table + /// that names no streams, more coupled streams than streams, or a channel + /// past the decoded ones. + pub fn new(config: Config<'_>) -> Result { + let Config { + family, + streams, + coupled, + table, + } = config; + let max_channels = match family { + 0 => return Err(Error::UnsupportedMappingFamily(0)), + 1 => 8, + _ => 255, + }; + if table.is_empty() || table.len() > max_channels { + return Err(Error::UnsupportedChannelCount(table.len() as u32)); + } + + let decoded = streams as u32 + coupled as u32; + if streams == 0 || coupled > streams || decoded > 255 { + return Err(Error::InvalidMappingTable); + } + if table.iter().any(|&entry| entry != 255 && entry as u32 >= decoded) { + return Err(Error::InvalidMappingTable); + } + + let mut padded = [0u8; 255]; + padded[..table.len()].copy_from_slice(table); + Ok(Self { + family, + streams, + coupled, + channels: table.len() as u8, + table: padded, + }) + } + + pub(super) fn parse(buf: &mut T, family: u8, channels: u8) -> Result { + if buf.remaining() < 2 + channels as usize { + return Err(Error::MappingTableTooShort); + } + let streams = buf.get_u8(); + let coupled = buf.get_u8(); + let mut table = [0u8; 255]; + buf.copy_to_slice(&mut table[..channels as usize]); + Self::new(Config { + family, + streams, + coupled, + table: &table[..channels as usize], + }) + } + + /// The channel mapping family: 1 is the Vorbis speaker order, 2 and 3 are + /// ambisonics, and 255 is channels with no declared position. + pub fn family(&self) -> u8 { + self.family + } + + /// Number of Opus streams in each packet. + pub fn streams(&self) -> u8 { + self.streams + } + + /// How many of those streams are coupled (stereo); they come first. + pub fn coupled(&self) -> u8 { + self.coupled + } + + /// The decoded channel feeding each output channel, 255 for silence. + pub fn table(&self) -> &[u8] { + &self.table[..self.channels as usize] + } +} + +impl std::fmt::Debug for Mapping { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Mapping") + .field("family", &self.family) + .field("streams", &self.streams) + .field("coupled", &self.coupled) + .field("table", &self.table()) + .finish() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn new_validates_the_table() { + fn new(family: u8, streams: u8, coupled: u8, table: &[u8]) -> Result { + Mapping::new(Config { + family, + streams, + coupled, + table, + }) + } + + let mapping = new(255, 2, 0, &[0, 1, 255]).unwrap(); + assert_eq!(mapping.family(), 255); + assert_eq!((mapping.streams(), mapping.coupled()), (2, 0)); + assert_eq!(mapping.table(), &[0, 1, 255]); + + assert!(matches!(new(0, 1, 1, &[0, 1]), Err(Error::UnsupportedMappingFamily(0)))); + assert!(matches!(new(1, 1, 0, &[]), Err(Error::UnsupportedChannelCount(0)))); + assert!(matches!(new(1, 9, 0, &[0; 9]), Err(Error::UnsupportedChannelCount(9)))); + for (streams, coupled, table) in [(0, 0, &[0][..]), (1, 2, &[0]), (1, 1, &[2]), (200, 100, &[0])] { + assert!( + matches!(new(1, streams, coupled, table), Err(Error::InvalidMappingTable)), + "{streams} streams, {coupled} coupled, {table:?}" + ); + } + } +} diff --git a/rs/moq-mux/src/codec/opus/mod.rs b/rs/moq-mux/src/codec/opus/mod.rs index a0c6ac0cbba..3565a11761a 100644 --- a/rs/moq-mux/src/codec/opus/mod.rs +++ b/rs/moq-mux/src/codec/opus/mod.rs @@ -4,8 +4,10 @@ //! publishes raw Opus frames (no Ogg framing) to a moq broadcast. mod import; +pub mod mapping; pub use import::*; +pub use mapping::Mapping; use bytes::{Buf, Bytes}; @@ -28,9 +30,8 @@ pub enum Error { #[error("unsupported OpusHead version {0}")] UnsupportedVersion(u8), - /// The channel count is zero, or more than the channel mapping family - /// allows: family 0 (the only one [`Config::encode`] emits) covers - /// mono/stereo, and family 1 up to eight channels. + /// The channel count is zero, or more than the channel mapping family allows: + /// family 0 covers mono/stereo and family 1 up to eight channels. #[error("channel mapping family does not allow {0} channels")] UnsupportedChannelCount(u32), @@ -43,8 +44,11 @@ pub enum Error { #[error("invalid OpusHead channel mapping table")] InvalidMappingTable, - /// [`Config::encode`] only emits channel mapping family 0. - #[error("cannot encode channel mapping family {0}")] + /// A channel mapping family the operation cannot carry: family 0 given to + /// [`Mapping::new`], which has no table; a [`Config::encode`] whose + /// `mapping_family` is not its `mapping`'s; or a container with no room for + /// the table. + #[error("unsupported channel mapping family {0}")] UnsupportedMappingFamily(u8), } @@ -66,7 +70,11 @@ pub struct Config { /// Gain to apply to the decoded output, in Q7.8 dB. pub output_gain: i16, /// Channel mapping family; 0 is mono/stereo with no mapping table. + /// + /// Always `mapping`'s family, or 0 without one. pub mapping_family: u8, + /// The channel mapping table, or `None` for family 0 (mono/stereo, one stream). + pub mapping: Option, } impl Config { @@ -78,6 +86,7 @@ impl Config { pre_skip: 0, output_gain: 0, mapping_family: 0, + mapping: None, } } @@ -89,10 +98,9 @@ impl Config { /// Parse an OpusHead buffer (RFC 7845 §5.1). /// - /// Accepts any minor version and refuses a new major version. A nonzero - /// channel mapping family must carry a complete, consistent mapping table, - /// which is validated but not returned. Bytes after the header are left in - /// `buf`. + /// Accepts any minor version and refuses a new major version. Reads the + /// channel mapping, refusing a channel count the family forbids or an + /// inconsistent mapping table. Bytes after the header are left in `buf`. pub fn parse(buf: &mut T) -> Result { if buf.remaining() < 19 { return Err(Error::HeadTooShort); @@ -112,32 +120,11 @@ impl Config { let output_gain = buf.get_i16_le(); let mapping_family = buf.get_u8(); - let max_channels = match mapping_family { - 0 => 2, - 1 => 8, - _ => 255, + let mapping = match mapping_family { + 0 if (1..=2).contains(&channel_count) => None, + 0 => return Err(Error::UnsupportedChannelCount(channel_count)), + family => Some(Mapping::parse(buf, family, channel_count as u8)?), }; - if channel_count == 0 || channel_count > max_channels { - return Err(Error::UnsupportedChannelCount(channel_count)); - } - - if mapping_family != 0 { - if buf.remaining() < 2 + channel_count as usize { - return Err(Error::MappingTableTooShort); - } - let streams = buf.get_u8() as u32; - let coupled = buf.get_u8() as u32; - if streams == 0 || coupled > streams || streams + coupled > 255 { - return Err(Error::InvalidMappingTable); - } - for _ in 0..channel_count { - // 255 marks a silent channel. - let index = buf.get_u8() as u32; - if index != 255 && index >= streams + coupled { - return Err(Error::InvalidMappingTable); - } - } - } Ok(Self { sample_rate, @@ -145,28 +132,44 @@ impl Config { pre_skip, output_gain, mapping_family, + mapping, }) } - /// Encode the minimal OpusHead packet (19 bytes; channel mapping family 0). + /// Encode an OpusHead packet (RFC 7845 §5.1), followed by the channel mapping + /// table when there is one. /// - /// Errors unless the mapping family is 0 and `channel_count` is 1 or 2, since - /// multichannel streams need a mapping table this helper does not emit. + /// Errors with [`Error::UnsupportedChannelCount`] when `channel_count` is not + /// 1 or 2 without a `mapping` (family 0 is only defined for mono/stereo), or + /// is not the mapping's own channel count, and with + /// [`Error::UnsupportedMappingFamily`] when `mapping_family` is not the + /// mapping's family. pub fn encode(&self) -> Result { - if self.mapping_family != 0 { + if self.mapping_family != self.mapping.map_or(0, |mapping| mapping.family()) { return Err(Error::UnsupportedMappingFamily(self.mapping_family)); } - if !(1..=2).contains(&self.channel_count) { + let valid = match &self.mapping { + None => (1..=2).contains(&self.channel_count), + Some(mapping) => self.channel_count == mapping.table().len() as u32, + }; + if !valid { return Err(Error::UnsupportedChannelCount(self.channel_count)); } - let mut head = Vec::with_capacity(19); + + let mut head = Vec::with_capacity(21 + self.channel_count as usize); head.extend_from_slice(b"OpusHead"); head.push(1); // version head.push(self.channel_count as u8); head.extend_from_slice(&self.pre_skip.to_le_bytes()); head.extend_from_slice(&self.sample_rate.to_le_bytes()); head.extend_from_slice(&self.output_gain.to_le_bytes()); - head.push(0); // channel mapping family (0 = mono/stereo) + match &self.mapping { + None => head.push(0), + Some(mapping) => { + head.extend_from_slice(&[mapping.family(), mapping.streams(), mapping.coupled()]); + head.extend_from_slice(mapping.table()); + } + } Ok(Bytes::from(head)) } } @@ -250,7 +253,7 @@ mod tests { assert!(matches!(err, Error::UnsupportedChannelCount(6))); } - /// A 19-byte family 0 head with the given version, channels, gain, and family. + /// A 19-byte head with the given version, channels, gain, and family. fn head(version: u8, channels: u8, gain: i16, family: u8) -> Vec { let mut head = b"OpusHead".to_vec(); head.push(version); @@ -287,12 +290,75 @@ mod tests { )); } + #[test] + fn parses_a_mapping_table() { + // 5.1 in family 1: four streams, two coupled, Vorbis order. + let mut bytes = head(1, 6, 0, 1); + bytes.extend_from_slice(&[4, 2, 0, 4, 1, 2, 3, 5]); + let trailing = [bytes.as_slice(), b"trailing"].concat(); + let mut buf = trailing.as_slice(); + let parsed = Config::parse(&mut buf).unwrap(); + assert_eq!(buf, b"trailing"); + assert_eq!(parsed.channel_count, 6); + assert_eq!(parsed.mapping_family, 1); + + let mapping = parsed.mapping.unwrap(); + assert_eq!(mapping.family(), 1); + assert_eq!(mapping.streams(), 4); + assert_eq!(mapping.coupled(), 2); + assert_eq!(mapping.table(), &[0, 4, 1, 2, 3, 5]); + + // The table survives a re-encode. + assert_eq!(parsed.encode().unwrap(), bytes); + } + + #[test] + fn encodes_the_vorbis_mappings() { + for channels in 1..=8u8 { + let mut config = Config::new(48_000, channels as u32); + config.mapping_family = 1; + config.mapping = Some(Mapping::vorbis(channels).unwrap()); + let head = config.encode().unwrap(); + assert_eq!(head.len(), 21 + channels as usize, "{channels} channels"); + assert_eq!( + Config::parse(&mut head.as_ref()).unwrap(), + config, + "{channels} channels" + ); + } + + // 5.1 is the table libopus and ffmpeg write. + let five_one = Mapping::vorbis(6).unwrap(); + assert_eq!((five_one.streams(), five_one.coupled()), (4, 2)); + assert_eq!(five_one.table(), &[0, 4, 1, 2, 3, 5]); + + assert!(matches!(Mapping::vorbis(0), Err(Error::UnsupportedChannelCount(0)))); + assert!(matches!(Mapping::vorbis(9), Err(Error::UnsupportedChannelCount(9)))); + + // The channel count must agree with the table. + let mut config = Config::new(48_000, 5); + config.mapping_family = 1; + config.mapping = Some(five_one); + assert!(matches!(config.encode(), Err(Error::UnsupportedChannelCount(5)))); + + // So must the family, both ways. + let mut config = Config::new(48_000, 6); + config.mapping = Some(five_one); + assert!(matches!(config.encode(), Err(Error::UnsupportedMappingFamily(0)))); + let mut config = Config::new(48_000, 2); + config.mapping_family = 1; + assert!(matches!(config.encode(), Err(Error::UnsupportedMappingFamily(1)))); + } + #[test] fn parse_rejects_channel_counts_the_family_does_not_allow() { - for (channels, family) in [(0, 0), (3, 0), (0, 1), (9, 1)] { + for (channels, family) in [(0, 0), (3, 0), (0, 1), (9, 1), (0, 255)] { + let mut bytes = head(1, channels, 0, family); + bytes.extend_from_slice(&[1, 0]); + bytes.extend(std::iter::repeat_n(0, channels as usize)); assert!( matches!( - Config::parse(&mut head(1, channels, 0, family).as_slice()), + Config::parse(&mut bytes.as_slice()), Err(Error::UnsupportedChannelCount(_)) ), "{channels} channels in family {family}" @@ -301,42 +367,26 @@ mod tests { } #[test] - fn parse_reads_a_mapping_table() { - // 5.1 in family 1: four streams, two coupled, Vorbis order. - let mut bytes = head(1, 6, 0, 1); - bytes.extend_from_slice(&[4, 2, 0, 4, 1, 2, 3, 5]); - bytes.extend_from_slice(b"trailing"); - let mut buf = bytes.as_slice(); - let parsed = Config::parse(&mut buf).unwrap(); - assert_eq!(parsed.channel_count, 6); - assert_eq!(parsed.mapping_family, 1); - assert_eq!(buf, b"trailing"); - - // Encode only emits family 0. - assert!(matches!(parsed.encode(), Err(Error::UnsupportedMappingFamily(1)))); - } - - #[test] - fn parse_rejects_a_truncated_or_invalid_mapping_table() { - // No table at all. - let bytes = head(1, 2, 0, 1); + fn parse_rejects_a_bad_mapping_table() { + // Family 1 promising a table that is not there, or only half of it. assert!(matches!( - Config::parse(&mut bytes.as_slice()), + Config::parse(&mut head(1, 2, 0, 1).as_slice()), Err(Error::MappingTableTooShort) )); - - // Table cut short of its last channel. - let mut bytes = head(1, 2, 0, 1); - bytes.extend_from_slice(&[1, 1, 0]); + let mut short = head(1, 2, 0, 1); + short.extend_from_slice(&[1, 1, 0]); assert!(matches!( - Config::parse(&mut bytes.as_slice()), + Config::parse(&mut short.as_slice()), Err(Error::MappingTableTooShort) )); for table in [ - [0, 0, 0, 1], // no streams - [1, 2, 0, 1], // more coupled than streams - [1, 1, 0, 2], // index past the two decoded channels + // No streams. + [0, 0, 0, 1], + // More coupled streams than streams. + [1, 2, 0, 1], + // A channel index past the two decoded channels. + [1, 1, 0, 2], ] { let mut bytes = head(1, 2, 0, 1); bytes.extend_from_slice(&table); @@ -347,8 +397,11 @@ mod tests { } // 255 is a silent channel, not an index. - let mut bytes = head(1, 2, 0, 1); - bytes.extend_from_slice(&[1, 1, 0, 255]); - assert!(Config::parse(&mut bytes.as_slice()).is_ok()); + let mut silent = head(1, 2, 0, 1); + silent.extend_from_slice(&[1, 0, 0, 255]); + assert_eq!( + Config::parse(&mut silent.as_slice()).unwrap().mapping.unwrap().table(), + &[0, 255] + ); } } diff --git a/rs/moq-mux/src/codec/video.rs b/rs/moq-mux/src/codec/video.rs index 9344d565ee0..219da9d09d5 100644 --- a/rs/moq-mux/src/codec/video.rs +++ b/rs/moq-mux/src/codec/video.rs @@ -1,10 +1,11 @@ -//! Shared catalog-publishing logic for the video codec importers. +//! Shared logic for the video codecs. //! //! Every video importer resolves its [`VideoConfig`](hang::catalog::VideoConfig) lazily from the //! bitstream and re-publishes it whenever the stream reveals a change. [`Catalog`] owns the part of //! that which is identical across codecs: overlay the caller's [`VideoHint`], skip a publish //! that matches the last one, and drive the shared [`hang::catalog::stalled::Detector`] detector so a -//! lagging rendition is marked in the catalog. +//! lagging rendition is marked in the catalog. [`Reorder`] is what a sequence header declares about +//! frame reordering, read by the exporters that author a decode clock. use std::time::{Duration, Instant}; @@ -14,6 +15,18 @@ use crate::catalog::VideoHint; type Track = crate::container::Producer; +/// The reordering a video sequence header declares. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct Reorder { + /// The most pictures that can precede any picture in decode order and follow it in output + /// order: H.264 `max_num_reorder_frames`, HEVC `sps_max_num_reorder_pics`. A count of + /// pictures, not a time. + pub depth: u32, + /// One picture's duration as `(units, scale)`, i.e. `units / scale` seconds, when the header + /// declares a fixed picture rate. + pub period: Option<(u64, u64)>, +} + /// The catalog-publishing state a video importer overlays onto every config it resolves. /// /// Holds the caller's hint, the last config published (to dedupe re-publishes), and the diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 42c74424677..35ebe48ca31 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -1382,7 +1382,7 @@ mod tests { assert_eq!(micros, vec![0, 100_000], "markers skipped, next group reached"); } - /// LOC consumers skip an empty payload so later producers can write the duration marker. + /// LOC video consumers skip an empty payload: it is the duration marker, not media. #[tokio::test] async fn loc_empty_payload_is_skipped() { let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 73491f6ae62..04f362726cd 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -11,7 +11,8 @@ //! //! By default FLV carries a single video and a single audio stream, so only the //! best video rendition (see [`Video::ranked`](hang::catalog::Video::ranked)) and -//! the first audio rendition are muxed and the rest are ignored. With +//! the first audio rendition are muxed and the rest are ignored. The video pick +//! follows the catalog until the stream header goes out, then stays. With //! [`with_multitrack`](Export::with_multitrack) every rendition is muxed instead, //! each as an enhanced-RTMP multitrack track addressed by its own track id (use //! this only for a player that advertised the `Multitrack` capability). @@ -327,8 +328,8 @@ impl Export { // Only bind before the header is emitted: the sequence-header (config) tags // go out with the header, and there's no in-band way to introduce a new // track's config mid-stream, so a rendition first seen afterward is left - // unmuxed rather than emitted as undecodable config-less frames. (This - // mirrors the single-track path ignoring extra renditions.) + // unmuxed rather than emitted as undecodable config-less frames. Until then a + // single-track stream rebinds to a better-ranked video rendition. if !self.header_emitted { self.bind_video(&catalog)?; self.bind_audio(&catalog)?; @@ -338,16 +339,10 @@ impl Export { tracing::warn!("ignoring FLV rendition that appeared after the stream header"); } - // A bound track vanishing from the catalog is a layout change FLV can't express. - for track in self.tracks() { - let present = if is_video_flavor(track.flavor) { - catalog.video.renditions.contains_key(&track.name) - } else { - catalog.audio.renditions.contains_key(&track.name) - }; - anyhow::ensure!(present, "FLV track '{}' removed mid-stream", track.name); - } - + // A bound track leaving the catalog is read to its own end rather than refused. A + // publisher retires a rendition as its track finishes or drops, and the catalog + // update races that end on another stream, so only the track's end can say which it + // was: a finish ends it cleanly, and a drop is the error the export reports. Ok(()) } @@ -365,6 +360,16 @@ impl Export { ranked }; + // Before the header, a single-track stream follows the best rendition, so a + // snapshot that lacks it doesn't fix the pick. Dropping the bound track + // unsubscribes it; nothing was emitted from it yet. + if !self.multitrack + && let Some((best, _)) = renditions.first() + && self.video.first().is_some_and(|t| &t.name != *best) + { + self.video.clear(); + } + for (name, config) in renditions { if !self.multitrack && !self.video.is_empty() { break; @@ -685,10 +690,6 @@ fn ensure_legacy(container: &Container, kind: &str, name: &str) -> anyhow::Resul } } -fn is_video_flavor(flavor: Flavor) -> bool { - matches!(flavor, Flavor::Avc | Flavor::Hevc | Flavor::Av1 | Flavor::Vp9) -} - fn video_flavor(config: &hang::catalog::VideoConfig) -> anyhow::Result { match &config.codec { VideoCodec::H264(_) => Ok(Flavor::Avc), diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 147bdc165e2..1c1679db135 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -748,6 +748,101 @@ async fn export_picks_the_best_selected_rendition() { assert_eq!(snap.audio.renditions.len(), 1, "audio is selected too"); } +/// A single-track export whose first snapshot lacks the best rendition switches to +/// it when it appears before the header goes out. +#[tokio::test(start_paused = true)] +async fn export_rebinds_to_a_better_rendition_before_the_header() { + use hang::catalog::{Container, H264, VideoConfig}; + use moq_net::Timestamp; + + use crate::container::Producer; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + + // The small rendition is Annex-B (no description), so its header can't resolve + // until a keyframe arrives, which keeps the stream header pending. + let small = producer.create_track(producer.unique_name(".avc3"), None).unwrap(); + let mut config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: true, + }); + config.container = Container::Legacy; + config.coded_width = Some(640); + config.coded_height = Some(360); + catalog + .modify() + .unwrap() + .video + .renditions + .insert(small.name().to_string(), config); + let _small = Producer::new( + small, + crate::catalog::hang::Container::Legacy(crate::container::Kind::Data), + ); + + let mut exporter = Export::new(crate::source::announced(&consumer)).await.unwrap(); + assert!( + tokio::time::timeout(Duration::from_millis(100), exporter.next()) + .await + .is_err(), + "the header waits on the small rendition's config" + ); + + // The best rendition shows up before any header went out. + let description = avcc_level(0x1e); + let large = producer.create_track(producer.unique_name(".avc1"), None).unwrap(); + let mut config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1e, + inline: false, + }); + config.container = Container::Legacy; + config.description = Some(Bytes::from(description.clone())); + config.coded_width = Some(1920); + config.coded_height = Some(1080); + catalog + .modify() + .unwrap() + .video + .renditions + .insert(large.name().to_string(), config); + let mut large = Producer::new( + large, + crate::catalog::hang::Container::Legacy(crate::container::Kind::Data), + ); + large + .write(crate::container::Frame { + timestamp: Timestamp::from_millis(0).unwrap(), + duration: None, + payload: Bytes::from_static(&[0, 0, 0, 1, 0x65]), + keyframe: true, + }) + .unwrap(); + + let header = tokio::time::timeout(Duration::from_millis(100), exporter.next()) + .await + .expect("the header follows the better rendition") + .unwrap() + .unwrap(); + assert!( + header.windows(description.len()).any(|w| w == description.as_slice()), + "the sequence header carries the better rendition's avcC" + ); + + let frame = tokio::time::timeout(Duration::from_millis(100), exporter.next()) + .await + .expect("the better rendition's frame follows") + .unwrap() + .unwrap(); + assert_eq!(frame[0], super::TAG_VIDEO); + assert!(frame.windows(5).any(|w| w == [0, 0, 0, 1, 0x65])); +} + struct ParsedTag { tag_type: u8, timestamp: u32, @@ -900,6 +995,93 @@ async fn export_authors_dts_and_composition_time_for_reordered_avc() { ); } +/// Poll `exporter` into `out` until it ends or goes idle; `None` if it went idle. +async fn drain_until_idle(exporter: &mut Export, out: &mut Vec) -> Option> { + loop { + match tokio::time::timeout(Duration::from_millis(100), exporter.next()).await { + Ok(Ok(Some(chunk))) => out.extend_from_slice(&chunk), + Ok(Ok(None)) => return Some(Ok(())), + Ok(Err(e)) => return Some(Err(e)), + Err(_) => return None, + } + } +} + +/// A bound track that leaves the catalog is read to its own end, not refused as removed: +/// a publisher retires a rendition as its track ends, and the catalog update can land first. +#[tokio::test(start_paused = true)] +async fn a_track_leaving_the_catalog_is_read_to_its_end() { + use hang::catalog::{AAC, AudioConfig, Container, H264, VideoConfig}; + use moq_net::Timestamp; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + let video_track = producer.create_track(producer.unique_name(".avc1"), None).unwrap(); + let audio_track = producer.create_track(producer.unique_name(".aac"), None).unwrap(); + let audio_name = audio_track.name().to_string(); + + let mut video_config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: false, + }); + video_config.container = Container::Legacy; + video_config.description = Some(Bytes::from(avcc())); + let mut audio_config = AudioConfig::new(AAC { profile: 2 }, 44100, 2); + audio_config.container = Container::Legacy; + audio_config.description = Some(Bytes::from_static(&ASC)); + { + let mut catalog = catalog.modify().unwrap(); + catalog + .video + .renditions + .insert(video_track.name().to_string(), video_config); + catalog.audio.renditions.insert(audio_name.clone(), audio_config); + } + + let legacy = || crate::catalog::hang::Container::Legacy(crate::container::Kind::Data); + let mut video = crate::container::Producer::new(video_track, legacy()); + let mut audio = crate::container::Producer::new(audio_track, legacy()); + let frame = |timestamp_ms: u64, payload: &'static [u8], keyframe| crate::container::Frame { + timestamp: Timestamp::from_millis(timestamp_ms).unwrap(), + duration: None, + payload: Bytes::from_static(payload), + keyframe, + }; + video.write(frame(0, &[0, 0, 0, 1, 0x65], true)).unwrap(); + audio.write(frame(0, &[0xde, 0xad], true)).unwrap(); + + let mut exporter = Export::new(crate::source::announced(&consumer)) + .await + .unwrap() + .with_max_age(RECORDING_MAX_AGE); + let mut exported = Vec::new(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + + // The audio rendition retires before its tail lands; the video carries on. + catalog.modify().unwrap().audio.renditions.remove(&audio_name); + audio.write(frame(23, &[0xbe, 0xef], true)).unwrap(); + audio.finish().unwrap(); + video.write(frame(33, &[0, 0, 0, 1, 0x41], false)).unwrap(); + video.finish().unwrap(); + catalog.finish().unwrap(); + + let end = drain_until_idle(&mut exporter, &mut exported).await; + assert!( + matches!(end, Some(Ok(()))), + "a track leaving the catalog is not a layout change: {end:?}" + ); + let tags = parse_tags(&exported); + let audio_frames = tags + .iter() + .filter(|t| t.tag_type == super::TAG_AUDIO && t.body[1] == super::AAC_RAW) + .count(); + assert_eq!(audio_frames, 2, "the leaving track's tail went out"); +} + async fn drain_exporter_chunks(mut exporter: Export, chunks: usize) -> Vec { let mut exported = Vec::new(); for _ in 0..chunks { diff --git a/rs/moq-mux/src/container/flv/import.rs b/rs/moq-mux/src/container/flv/import.rs index 3bacdebf002..59480c0d25d 100644 --- a/rs/moq-mux/src/container/flv/import.rs +++ b/rs/moq-mux/src/container/flv/import.rs @@ -409,7 +409,7 @@ impl Import { match packet_type { AUDIO_PACKET_SEQUENCE_START => { let config = match fourcc { - b"Opus" => config_from_opus_head(payload)?, + b"Opus" => crate::codec::opus::config(payload)?, b"mp4a" => config_from_asc(payload)?, // MP3 / AC-3 / E-AC-3 are verbatim with no sequence header; they // configure from the first frame. Anything else is unsupported. @@ -786,15 +786,6 @@ fn config_from_asc(asc_bytes: &[u8]) -> anyhow::Result { Ok(config) } -/// Build an audio config for Opus from an `OpusHead` (RFC 7845) record. -fn config_from_opus_head(head: &[u8]) -> anyhow::Result { - let mut cursor = head; - let cfg = crate::codec::opus::Config::parse(&mut cursor)?; - let mut config = AudioConfig::new(AudioCodec::Opus, cfg.sample_rate, cfg.channel_count); - config.description = Some(Bytes::copy_from_slice(head)); - Ok(config) -} - /// Build an audio config for MP3 from a frame header (config is in band). fn config_from_mp3(frame: &[u8]) -> anyhow::Result { let cfg = crate::codec::mp3::Config::parse(frame)?; diff --git a/rs/moq-mux/src/container/flv/import_test.rs b/rs/moq-mux/src/container/flv/import_test.rs index e4b72b31a8d..7d50266ffa6 100644 --- a/rs/moq-mux/src/container/flv/import_test.rs +++ b/rs/moq-mux/src/container/flv/import_test.rs @@ -271,7 +271,8 @@ async fn import_enhanced_vp9() { /// header and carries the frames through. #[tokio::test(start_paused = true)] async fn import_enhanced_opus() { - let head = crate::codec::opus::Config::new(48_000, 2).encode().unwrap(); + // A 44.1 kHz input rate is informational; the catalog still reports the decoder's 48 kHz. + let head = crate::codec::opus::Config::new(44_100, 2).encode().unwrap(); let mut out = Vec::new(); out.extend_from_slice(b"FLV"); diff --git a/rs/moq-mux/src/container/fmp4/muxer.rs b/rs/moq-mux/src/container/fmp4/muxer.rs index 373e260236a..c220b7ddb56 100644 --- a/rs/moq-mux/src/container/fmp4/muxer.rs +++ b/rs/moq-mux/src/container/fmp4/muxer.rs @@ -125,6 +125,36 @@ impl Muxer { Ok(self) } + /// Synthesize missing video sample durations at `framerate`, a newer estimate than the + /// config this muxer was built from. + /// + /// Only the fallback cadence follows it: the timescale, and so the init segment, stays the + /// one the original config chose. The cadence snaps to whole ticks at that timescale (an NTSC + /// rate is fractional ticks at 90 kHz, which would otherwise fail to mux as inexact). Ignored + /// for audio, for a missing, non-finite or non-positive rate, and for one whose frame rounds + /// to zero ticks or past `trun`'s 32-bit sample duration. + pub fn with_framerate(mut self, framerate: Option) -> Self { + if !matches!(self.kind, Kind::Video(_)) { + return self; + } + let Some(fps) = framerate.filter(|fps| fps.is_finite() && *fps > 0.0) else { + return self; + }; + let timescale = self.timescale.as_u64(); + let ticks = (timescale as f64 / fps).round(); + if !(1.0..=f64::from(u32::MAX)).contains(&ticks) { + return self; + } + // Exactly `ticks / timescale`, rounded to the nanosecond, so the fallback snaps back to + // `ticks` within the muxer's one-nanosecond tolerance. + let timescale = u128::from(timescale); + let nanos = (ticks as u128 * 1_000_000_000 + timescale / 2) / timescale; + if let Ok(nanos) = u64::try_from(nanos) { + self.default_frame = Duration::from_nanos(nanos); + } + self + } + /// The rendition's catalog container, whichever kind of track this is. fn catalog_container(&self) -> &CatalogContainer { match &self.kind { @@ -582,6 +612,61 @@ mod tests { assert_eq!(decoded[0].timestamp.as_micros(), 33_333); } + // A rendition built before the publisher's framerate estimate settled keeps its 90 kHz + // timescale, but a duration-less frame follows the newer cadence. + #[test] + fn with_framerate_updates_the_fallback_without_the_timescale() { + let muxer = video_muxer_without_framerate().with_framerate(Some(60.0)); + assert_eq!(muxer.timescale().as_u64(), 90_000); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + assert_eq!(super::super::sample_durations(&fragment), vec![Some(1_500)]); + } + + // An NTSC rate is fractional ticks at a timescale that doesn't divide it (1501.5 at 90 kHz), + // so the cadence snaps to whole ticks rather than failing the fragment as inexact. + #[test] + fn with_framerate_snaps_a_fractional_cadence_to_whole_ticks() { + for (fps, ticks) in [(60_000.0 / 1001.0, 1_502), (24_000.0 / 1001.0, 3_754)] { + let muxer = video_muxer_without_framerate().with_framerate(Some(fps)); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + assert_eq!(super::super::sample_durations(&fragment), vec![Some(ticks)], "{fps}"); + } + + // 30 kHz doesn't divide a second's nanoseconds either: 1251.25 ticks rounds to 1251. + let mut config = VideoConfig::new(VideoCodec::VP8); + config.framerate = Some(30.0); + let muxer = Muxer::video(&config).unwrap().with_framerate(Some(24_000.0 / 1001.0)); + assert_eq!(muxer.timescale().as_u64(), 30_000); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + assert_eq!(super::super::sample_durations(&fragment), vec![Some(1_251)]); + } + + #[test] + fn with_framerate_ignores_an_unusable_rate() { + // 90 kHz at 1e-6 fps is 9e10 ticks per frame, past trun's 32 bits; at 1e9 fps it is 0. + for fps in [ + None, + Some(0.0), + Some(-30.0), + Some(f64::NAN), + Some(f64::INFINITY), + Some(1e-6), + Some(1e9), + ] { + let muxer = video_muxer_without_framerate().with_framerate(fps); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + // The 30 fps fallback at 90 kHz. + assert_eq!(super::super::sample_durations(&fragment), vec![Some(3_000)], "{fps:?}"); + } + } + + fn video_muxer_without_framerate() -> Muxer { + let mut config = VideoConfig::new(VideoCodec::VP8); + config.coded_width = Some(320); + config.coded_height = Some(240); + Muxer::video(&config).unwrap() + } + #[test] fn with_timescale_recomputes_the_fallback_frame_duration() { let timescale = moq_net::Timescale::new(90_000).unwrap(); diff --git a/rs/moq-mux/src/container/loc/mod.rs b/rs/moq-mux/src/container/loc/mod.rs index 413e042ea3c..f3ef259f12b 100644 --- a/rs/moq-mux/src/container/loc/mod.rs +++ b/rs/moq-mux/src/container/loc/mod.rs @@ -82,4 +82,25 @@ impl Container for Wire { fn end(&self, frame: &Frame) -> Option { (self.0 != Kind::Data && frame.payload.is_empty()).then_some(frame.timestamp) } + + fn finish_group( + &self, + group: &mut moq_net::group::Producer, + end: Option, + ) -> Result<(), Self::Error> { + if self.0 == Kind::Video + && let Some(timestamp) = end + { + self.write( + group, + &[Frame { + timestamp, + payload: bytes::Bytes::new(), + keyframe: false, + duration: None, + }], + )?; + } + Ok(()) + } } diff --git a/rs/moq-mux/src/container/mkv/import.rs b/rs/moq-mux/src/container/mkv/import.rs index 72b90d4de7a..141e6bacc19 100644 --- a/rs/moq-mux/src/container/mkv/import.rs +++ b/rs/moq-mux/src/container/mkv/import.rs @@ -572,20 +572,18 @@ fn build_audio_config( match codec_id { "A_OPUS" => { - // Codec private is OpusHead. If present, it's authoritative for rate/channels. - let (cfg_rate, cfg_channels) = if let Some(priv_data) = codec_private { - let mut cursor = priv_data.clone(); - let cfg = crate::codec::opus::Config::parse(&mut cursor)?; - (cfg.sample_rate, cfg.channel_count) - } else { - (sample_rate, channels) + // The catalog describes the decoder's output: Opus always decodes at 48 kHz, whatever the + // informational input rate in the OpusHead or SamplingFrequency claims. + let mut config = match codec_private { + Some(head) => { + let mut config = crate::codec::opus::config(head)?; + if config.channel_count == 0 { + config.channel_count = channels; + } + config + } + None => AudioConfig::new(AudioCodec::Opus, 48_000, channels), }; - - let mut config = AudioConfig::new( - AudioCodec::Opus, - if cfg_rate > 0 { cfg_rate } else { sample_rate }, - if cfg_channels > 0 { cfg_channels } else { channels }, - ); config.description = codec_private.cloned(); Ok(config) } diff --git a/rs/moq-mux/src/container/mkv/import_test.rs b/rs/moq-mux/src/container/mkv/import_test.rs index 354e0c7d71a..fe9f827b165 100644 --- a/rs/moq-mux/src/container/mkv/import_test.rs +++ b/rs/moq-mux/src/container/mkv/import_test.rs @@ -305,6 +305,24 @@ fn test_vp9_opus_catalog() { assert_eq!(a.channel_count, 2); } +#[test] +fn test_opus_catalog_rate_is_decoder_rate() { + // A 44.1 kHz input rate is informational; the catalog still reports the decoder's 48 kHz. + let data = MkvBuilder::new() + .header("webm") + .segment_start() + .info(1_000_000) + .tracks(vec![track_entry_audio_opus(1, 44100.0, 2)]) + .cluster(0, || vec![simple_block(1, 0, true, b"opus")]) + .segment_end() + .build(); + + let catalog = run(&data); + let a = catalog.audio.renditions.values().next().unwrap(); + assert_eq!(a.sample_rate, 48000); + assert_eq!(a.channel_count, 2); +} + #[test] fn test_mp3_catalog() { let data = MkvBuilder::new() diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index 0fa14fc6705..15cccd0878b 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -1168,29 +1168,80 @@ mod tests { assert_eq!(collect_payloads(consumer).await, vec![vec![(0, 2), (20_000, 2)]]); } - /// LOC producers do not write the marker until skipping consumers have shipped. + /// Drain all LOC groups, returning each group's (timestamp_micros, payload_len) pairs. + async fn collect_loc_payloads(mut consumer: moq_net::track::Subscriber) -> Vec> { + let mut groups = Vec::new(); + while let Some(mut group) = consumer.recv_group().await.unwrap() { + let mut frames = Vec::new(); + while let Some(frame) = group.read_frame().await.unwrap() { + let decoded = moq_loc::decode(frame.payload).unwrap(); + frames.push((decoded.timestamp, decoded.payload.len())); + } + groups.push(frames); + } + groups + } + + /// A LOC video group ends with an empty frame at the next keyframe's timestamp, like Legacy. #[tokio::test] - async fn loc_cut_writes_no_duration_marker() { + async fn loc_cut_writes_a_duration_marker_at_the_callers_bound() { let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Loc(crate::container::Kind::Video)); producer.write(frame(0, true)).unwrap(); + producer.write(frame(10_000, false)).unwrap(); producer - .cut(Some(moq_net::Timestamp::from_micros(33_000).unwrap())) + .cut(Some(moq_net::Timestamp::from_micros(15_000).unwrap())) .unwrap(); + producer.write(frame(20_000, true)).unwrap(); producer.finish().unwrap(); - let mut groups = Vec::new(); - let mut consumer = consumer; - while let Some(mut group) = consumer.recv_group().await.unwrap() { - let mut count = 0; - while group.next_frame().await.unwrap().is_some() { - count += 1; - } - groups.push(count); - } - assert_eq!(groups, vec![1], "LOC producers do not write the marker yet"); + let groups = collect_loc_payloads(consumer).await; + assert_eq!(groups[0], vec![(0, 2), (10_000, 2), (15_000, 0)]); + assert_eq!(groups[1][0], (20_000, 2)); + assert_eq!(groups[1].last().unwrap().1, 0, "finish closes the last group"); + } + + /// LOC audio never writes a duration marker, even at finish. + #[tokio::test] + async fn loc_audio_writes_no_duration_marker() { + let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.audio)); + let consumer = track.subscribe(replay()); + let mut producer = Producer::new(track, Container::Loc(crate::container::Kind::Audio)); + + producer.write(frame(0, true)).unwrap(); + producer.write(frame(20_000, false)).unwrap(); + producer + .cut(Some(moq_net::Timestamp::from_micros(30_000).unwrap())) + .unwrap(); + producer.write(frame(40_000, true)).unwrap(); + producer.finish().unwrap(); + + assert_eq!( + collect_loc_payloads(consumer).await, + vec![vec![(0, 2), (20_000, 2)], vec![(40_000, 2)]] + ); + } + + /// LOC data tracks never write a duration marker, so an empty data frame stays data. + #[tokio::test] + async fn loc_data_writes_no_duration_marker() { + let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let consumer = track.subscribe(replay()); + let mut producer = Producer::new(track, Container::Loc(crate::container::Kind::Data)); + + producer.write(frame(0, true)).unwrap(); + producer + .cut(Some(moq_net::Timestamp::from_micros(15_000).unwrap())) + .unwrap(); + producer.write(frame(20_000, true)).unwrap(); + producer.finish().unwrap(); + + assert_eq!( + collect_loc_payloads(consumer).await, + vec![vec![(0, 2)], vec![(20_000, 2)]] + ); } /// `cut()` flushes the current group immediately; the next write must be a keyframe. diff --git a/rs/moq-mux/src/container/ts/adts.rs b/rs/moq-mux/src/container/ts/adts.rs index b5a986a2f30..632947bdce4 100644 --- a/rs/moq-mux/src/container/ts/adts.rs +++ b/rs/moq-mux/src/container/ts/adts.rs @@ -21,7 +21,8 @@ pub(super) struct Header { /// audioObjectType (ADTS `profile` + 1). AAC-LC is 2. pub object_type: u8, pub sample_rate: u32, - pub channel_count: u32, + /// channelConfiguration; 0 means a program config element in the raw data block describes the channels. + pub channel_config: u8, /// Total access-unit length, header included. pub frame_len: usize, /// Header length: 7 without CRC, 9 with. @@ -51,7 +52,7 @@ impl Header { Ok(Self { object_type: profile + 1, sample_rate, - channel_count: channel_count_from_config(channel_config), + channel_config, frame_len, header_len, }) @@ -62,13 +63,21 @@ impl Header { pub(super) fn write_header( object_type: u8, sample_rate: u32, - channel_count: u32, + channel_config: u8, raw_len: usize, ) -> anyhow::Result<[u8; 7]> { - // ADTS `profile` is the 2-bit audioObjectType - 1. - let profile = object_type.saturating_sub(1) & 0x03; + // ADTS `profile` is the 2-bit audioObjectType - 1, so only Main, LC, SSR, and LTP fit. + anyhow::ensure!( + (1..=4).contains(&object_type), + "audioObjectType {object_type} not representable in ADTS" + ); + let profile = object_type - 1; let freq_index = freq_index_from_rate(sample_rate)?; - let channel_config = channel_config_from_count(channel_count); + // ADTS has 3 bits for it; the higher configurations only fit an AudioSpecificConfig. + anyhow::ensure!( + channel_config < 8, + "channelConfiguration {channel_config} not representable in ADTS" + ); let frame_len = raw_len + 7; anyhow::ensure!(frame_len < (1 << 13), "AAC frame too large for ADTS framing"); @@ -96,21 +105,13 @@ fn freq_index_from_rate(sample_rate: u32) -> anyhow::Result { .with_context(|| format!("sample rate {sample_rate} not representable in ADTS")) } -/// Map an AAC `channel_config` (ISO 14496-3 Table 1.19) to a channel count. -fn channel_count_from_config(channel_config: u8) -> u32 { - match channel_config { - 1..=6 => channel_config as u32, - 7 => 8, - _ => 2, - } -} - -/// Inverse of [`channel_count_from_config`]. -fn channel_config_from_count(channel_count: u32) -> u8 { +/// Map a channel count to the ADTS `channel_config` (ISO 14496-3 Table 1.19) naming it, refusing a +/// count that none does rather than guess a layout. +pub(super) fn channel_config_from_count(channel_count: u32) -> anyhow::Result { match channel_count { - 1..=6 => channel_count as u8, - 8 => 7, - _ => 2, + 1..=6 => Ok(channel_count as u8), + 8 => Ok(7), + _ => anyhow::bail!("{channel_count} channels have no ADTS channelConfiguration"), } } @@ -126,7 +127,7 @@ mod tests { assert_eq!(parsed.object_type, 2); assert_eq!(parsed.sample_rate, 48_000); - assert_eq!(parsed.channel_count, 2); + assert_eq!(parsed.channel_config, 2); assert_eq!(parsed.header_len, 7); assert_eq!(parsed.frame_len, 107, "frame_len includes the 7-byte header"); } @@ -138,11 +139,30 @@ mod tests { assert!(Header::parse(&header).is_err()); } + #[test] + fn write_refuses_object_types_outside_the_profile_field() { + for object_type in [0, 5, 29] { + assert!(write_header(object_type, 48_000, 2, 10).is_err()); + } + for object_type in 1..=4 { + let header = write_header(object_type, 48_000, 2, 10).unwrap(); + assert_eq!(Header::parse(&header).unwrap().object_type, object_type); + } + } + + #[test] + fn channel_counts_without_a_configuration_are_refused() { + assert_eq!(channel_config_from_count(8).unwrap(), 7); + for count in [0, 7, 9, 24] { + assert!(channel_config_from_count(count).is_err()); + } + } + #[test] fn frame_len_for_5_1() { let header = write_header(2, 44_100, 6, 512).unwrap(); let parsed = Header::parse(&header).unwrap(); - assert_eq!(parsed.channel_count, 6); + assert_eq!(parsed.channel_config, 6); assert_eq!(parsed.sample_rate, 44_100); assert_eq!(parsed.frame_len, 519); } diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index e1380502ae8..e493c9a3afc 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -16,7 +16,7 @@ //! length-prefixed -> Annex-B conversion, re-injecting the parameter sets as //! inline NALs on every keyframe. CMAF tracks are rejected with a clear error. -use std::collections::{BTreeMap, HashMap, VecDeque}; +use std::collections::{BTreeMap, HashMap, HashSet, VecDeque}; use std::pin::Pin; use std::task::Poll; use std::time::Duration; @@ -37,7 +37,8 @@ use moq_net::Timestamp; use crate::catalog::hang::Catalog; use crate::catalog::{CatalogFormat, Stream}; -use crate::codec::annexb; +use crate::codec::video::Reorder; +use crate::codec::{aac, annexb}; use crate::container::{ExportSource, Frame}; use super::adts; @@ -112,6 +113,10 @@ fn sanitize_mux_rate(rate: u64) -> Option { pub struct Export { source: crate::Source, catalog: Option>, + catalog_format: CatalogFormat, + /// Tracks [`Self::resume`] left on the ended broadcast, resubscribed as the + /// returned catalog lists them. + stale: HashSet, max_age: Duration, tracks: HashMap, @@ -145,6 +150,9 @@ pub struct Export { /// Generation of the last returned frame, updated only at the output boundary. emitted_epoch: u64, pcr_discontinuity: bool, + /// Back-off of the last PCR emitted ([`Self::pcr_at`]), so a reserve that grows past it + /// flags the next one as a new time base. + pcr_reserve: Option, /// TS packets muxed into the span that is still open. pending: Vec, /// Offsets into [`pending`](Self::pending) where a keyframe's packets begin, so @@ -166,8 +174,8 @@ pub struct Export { /// high-water mark rather than on every frame. watermark: Option, /// When the interleave started waiting on a lagging track: the arrival of the - /// first leading frame it held. Cleared once every track has caught up - /// ([`Self::pick_next_track`]). + /// first leading frame it held. Cleared once every track has caught up, or by + /// [`Self::resume`], but not by a rewind ([`Self::pick_next_track`]). stall: Option, /// Wakes [`Self::pick_next_track`] once the stall has lasted `max_age`. hold: Option>>, @@ -218,10 +226,9 @@ struct Track { /// High-water mark of the timestamps muxed within this rendition, independent of /// cross-track skew. Bounds where its next frame can land ([`Track::shown`]). timeline: Option, - /// Decode-clock reserve (90 kHz ticks): how far ahead of its PTS each frame decodes. Taken - /// from the catalog `jitter` (the reorder depth) so it is large enough for `DTS <= PTS`, - /// or [`DEFAULT_DTS_RESERVE`] when the catalog declares none. Only video uses it. - dts_reserve: u64, + /// Decode-clock reserve: how far ahead of its PTS each frame decodes. Only video sizes it; + /// every other kind holds [`DEFAULT_DTS_RESERVE`]. + reserve: Reserve, } impl Track { @@ -242,7 +249,7 @@ impl Track { return false; }; let reorder = match self.kind { - Kind::Video(_) => u128::from(self.dts_reserve) * 1_000_000_000 / 90_000, + Kind::Video(_) => u128::from(self.reserve.ticks) * 1_000_000_000 / 90_000, _ => 0, }; let floor = timeline.as_nanos().saturating_sub(reorder); @@ -250,15 +257,135 @@ impl Track { } } +/// A video rendition's decode-clock reserve in 90 kHz ticks: how far each frame's DTS runs +/// behind its PTS. It must exceed the rendition's reordering for `DTS <= PTS` to hold, and +/// [`Export::pcr_at`] backs the clock off by the largest one. +/// +/// The catalog `jitter` (the importer's max PTS - DTS) sizes it when published. Otherwise the +/// reorder depth the SPS declares sizes it, at the SPS's fixed picture rate or the catalog +/// `framerate`, so two exporters agree on it from their first keyframe. Otherwise it holds +/// [`DEFAULT_DTS_RESERVE`]. Reordering deeper than all of those raises it further +/// ([`Self::observe`]). +/// +/// It never shrinks: that would step the decode clock forward past frames already muxed and +/// the PCR ahead of DTS values already sent. +struct Reserve { + /// The catalog `jitter`, in ticks. + jitter: Option, + /// The catalog `framerate`: the picture period for an SPS that declares no fixed rate. + framerate: Option, + /// The avcC/hvcC [`Self::declared`] was read from. + description: Option, + declared: Option, + /// The reserve covering the deepest reordering muxed so far. + observed: u64, + /// Frames muxed since the one that set the rendition's high-water mark. + since_peak: u64, + /// The reserve in effect. + ticks: u64, +} + +impl Default for Reserve { + fn default() -> Self { + Self { + jitter: None, + framerate: None, + description: None, + declared: None, + observed: 0, + since_peak: 0, + ticks: DEFAULT_DTS_RESERVE, + } + } +} + +impl Reserve { + /// Take the rendition's timing from a catalog snapshot, before or after the program + /// tables are written. + fn configure(&mut self, config: &VideoConfig, name: &str) { + self.jitter = config + .jitter + .map(|t| (t.as_micros() * 90_000 / 1_000_000) as u64) + .filter(|&ticks| ticks > 0); + self.framerate = config.framerate.filter(|fps| fps.is_finite() && *fps > 0.0); + self.settle(name, "catalog"); + } + + /// Read the reorder depth from the codec config a keyframe is carried with. + fn describe(&mut self, stream_type: StreamType, description: Option<&Bytes>, name: &str) { + if self.description.as_ref() == description { + return; + } + self.description = description.cloned(); + self.declared = description.and_then(|d| declared_reorder(stream_type, d)); + self.settle(name, "sps"); + } + + /// Account for a frame muxed `gap` ticks below the rendition's high-water mark. + /// + /// This is the one path where the reserve depends on when an exporter joined rather than on + /// what the stream declares: a joiner adopts the depth only once it has muxed the deepest + /// reordering itself, and until then its DTS and PCR differ from an exporter that has. It + /// fires only when the catalog and the SPS both undercount the stream's reordering (or + /// declare none), and each growth is logged. + /// + /// The decode clock steps at least one tick per frame, so a frame decoded `k` frames after + /// the one that set the high-water mark needs `k` ticks beyond its gap. + fn observe(&mut self, gap: u64, name: &str) { + self.since_peak += 1; + let covering = gap.saturating_add(self.since_peak).min(MAX_DTS_RESERVE); + if covering > self.observed { + self.observed = covering; + self.settle(name, "observed"); + } + } + + /// Account for a frame at or above the rendition's high-water mark. + fn peak(&mut self) { + self.since_peak = 0; + } + + fn settle(&mut self, name: &str, source: &'static str) { + // As in [`Self::observe`], a reordered frame needs a tick for each frame decoded between + // it and the one above it; the declared depth stands in for that count. + let declared = self.declared.and_then(|reorder| { + let period = match reorder.period { + Some((units, scale)) => units.saturating_mul(90_000).div_ceil(scale), + None => (90_000.0 / self.framerate?).ceil() as u64, + }; + let depth = u64::from(reorder.depth); + let ticks = depth.saturating_mul(period).saturating_add(depth.max(1)); + Some(ticks.min(MAX_DTS_RESERVE)) + }); + let target = self + .jitter + .or(declared) + .unwrap_or(DEFAULT_DTS_RESERVE) + .max(self.observed); + if target > self.ticks { + if source == "observed" { + tracing::warn!( + track = %name, + from = self.ticks, + to = target, + "reordering deeper than the catalog or SPS declares; raising the video DTS reserve" + ); + } else { + tracing::info!(track = %name, from = self.ticks, to = target, source, "raising the video DTS reserve"); + } + self.ticks = target; + } + } +} + #[derive(Clone)] enum Kind { /// Video carries its TS stream type (H.264 = 0x1B, H.265 = 0x24). Video(StreamType), - Aac { - object_type: u8, - sample_rate: u32, - channel_count: u32, - }, + /// AAC, framed as ADTS. A `channel_config` of 0 defers the layout to a program config + /// element, which leads the next raw data block written and is then taken. A catalog update + /// rebuilds the kind and so repeats it once, which a decoder tuning in mid-stream welcomes. + Aac(aac::InBand), /// Opus (private stream_type 0x06). Each frame is one Opus packet, prefixed with /// the Opus-in-TS access-unit control header and announced with the 'Opus' /// registration plus DVB extension descriptor. @@ -540,6 +667,8 @@ impl Export { Ok(Self { source, catalog: Some(catalog), + catalog_format, + stale: HashSet::new(), max_age: Duration::ZERO, tracks: HashMap::new(), counters: HashMap::new(), @@ -555,6 +684,7 @@ impl Export { epoch: 0, emitted_epoch: 0, pcr_discontinuity: false, + pcr_reserve: None, pending: Vec::new(), keyframes: Vec::new(), queue: VecDeque::new(), @@ -718,6 +848,19 @@ impl Export { } let frame = pending.frame; let track = self.tracks.get_mut(&name).unwrap(); + if let Kind::Video(stream_type) = track.kind { + if frame.keyframe { + track.reserve.describe(stream_type, track.source.description(), &name); + } + if let Some(timeline) = track.timeline + && frame.timestamp < timeline + { + let gap = to_ticks(timeline) - to_ticks(frame.timestamp); + track.reserve.observe(gap, &name); + } else { + track.reserve.peak(); + } + } track.timeline = Some(track.timeline.map_or(frame.timestamp, |last| last.max(frame.timestamp))); self.last_timestamp = Some(frame.timestamp); self.advance(frame.timestamp)?; @@ -923,7 +1066,13 @@ impl Export { } } - // The program tables are written once; reject layout changes afterwards. + // The program tables are written once; reject a track added afterwards. + // + // A track that leaves the catalog is not a layout change: it keeps its PID and is + // read to its own end. A publisher retires a rendition as its track finishes or + // drops, and the catalog update races that end on another stream, so the leaving + // cannot say which it was. The track's end does: a finish ends it cleanly, and a + // drop is the error the export reports. if self.psi.is_some() { for name in active.keys() { anyhow::ensure!( @@ -931,14 +1080,18 @@ impl Export { "TS track layout changed after PAT/PMT was emitted: '{name}' added" ); } - for name in self.tracks.keys() { - anyhow::ensure!( - active.contains_key(name), - "TS track layout changed after PAT/PMT was emitted: '{name}' removed" - ); + if !self.stale.is_empty() { + self.resubscribe(&catalog, &mpegts)?; } let es_pids: Vec = self.tracks.values().map(|t| t.pid).collect(); reject_colliding_si_pids(&mpegts, self.pmt_pid(), &es_pids)?; + // The layout is locked but the timing is not: a `jitter` or `framerate` published + // after the tables still sizes the decode clock. + for (name, config) in catalog.video.renditions.iter() { + if let Some(track) = self.tracks.get_mut(name) { + track.reserve.configure(config, name); + } + } return Ok(()); } @@ -977,21 +1130,20 @@ impl Export { let kind = video_kind(config, name)?; let descriptors = track_descriptors(&mpegts, name); let pid = pids[name]; - // The catalog `jitter` carries the reorder depth (max PTS - DTS), so use it as the - // decode-clock reserve; it may arrive in a later snapshot, so refresh it each time. - let reserve = dts_reserve(config); match old.remove(name) { Some(mut track) => { track.pid = pid; track.kind = kind; track.descriptors = descriptors; - track.dts_reserve = reserve; + track.reserve.configure(config, name); self.tracks.insert(name.clone(), track); } None => { let Some(source) = ExportSource::for_video(&self.source, name, config, self.max_age)? else { continue; }; + let mut reserve = Reserve::default(); + reserve.configure(config, name); self.insert_track(name, source, pid, kind, descriptors, reserve); } } @@ -1011,7 +1163,7 @@ impl Export { let Some(source) = ExportSource::for_audio(&self.source, name, config, self.max_age)? else { continue; }; - self.insert_track(name, source, pid, kind, descriptors, DEFAULT_DTS_RESERVE); + self.insert_track(name, source, pid, kind, descriptors, Reserve::default()); } } } @@ -1035,13 +1187,41 @@ impl Export { } None => { let source = ExportSource::for_stream(&self.source, name, self.max_age)?; - self.insert_track(name, source, pid, kind, descriptors, DEFAULT_DTS_RESERVE); + self.insert_track(name, source, pid, kind, descriptors, Reserve::default()); } } } Ok(()) } + /// Point each stale track this snapshot lists at the returned broadcast. + /// + /// The PIDs and PMT stay as announced. A track the returned catalog does not list stays + /// finished, silent on its PID. + fn resubscribe(&mut self, catalog: &Catalog, mpegts: &catalog::Mpegts) -> anyhow::Result<()> { + for (name, track) in self.tracks.iter_mut() { + if !self.stale.contains(name) { + continue; + } + let source = if let Some(config) = catalog.video.renditions.get(name) { + ExportSource::for_video(&self.source, name, config, self.max_age)? + } else if let Some(config) = catalog.audio.renditions.get(name) { + ExportSource::for_audio(&self.source, name, config, self.max_age)? + } else if mpegts.tracks.get(name).is_some_and(|t| t.verbatim.is_some()) { + Some(ExportSource::for_stream(&self.source, name, self.max_age)?) + } else { + None + }; + let Some(source) = source else { + continue; + }; + self.stale.remove(name); + track.source = source; + track.finished = false; + } + Ok(()) + } + /// Insert a freshly created export track. fn insert_track( &mut self, @@ -1050,7 +1230,7 @@ impl Export { pid: u16, kind: Kind, descriptors: Vec, - dts_reserve: u64, + reserve: Reserve, ) { self.tracks.insert( name.to_string(), @@ -1065,7 +1245,7 @@ impl Export { descriptors, last_dts: None, timeline: None, - dts_reserve, + reserve, }, ); } @@ -1077,6 +1257,41 @@ impl Export { self.emitted_epoch } + /// Carry on with the broadcast that replaced the one this export was reading. + /// + /// Call it once [`Source::returned`](crate::Source::returned) has resolved, after + /// [`next`](Self::next) returned `None` or an error. Whatever the ended broadcast left + /// unwritten is dropped and the program clock restarts, so the next output flags the + /// break and re-emits the PAT/PMT. The returned catalog resubscribes each track as it + /// lists it, under the program already announced; one that adds a track fails as a + /// layout change. + pub async fn resume(&mut self) -> Result<(), crate::Error> { + self.catalog = Some(self.source.catalog::(self.catalog_format).await?); + self.si_flushed = false; + // A name no entry carries, so the returned catalog repoints every SI entry. + for si in self.si.values_mut() { + si.track.clear(); + } + if self.psi.is_none() { + // Nothing announced yet: the returned catalog builds the program afresh. + self.tracks.clear(); + } + // Whatever the ended broadcast left is done, including a track whose error ended + // the export: polled again, it would end this one too. + for (name, track) in self.tracks.iter_mut() { + track.finished = true; + track.pending = None; + track.discontinuity = 0; + self.stale.insert(name.clone()); + } + // A replacement broadcast gets its own budget: only a rewind within one broadcast + // carries a stall across. + self.stall = None; + self.hold = None; + self.rewind(); + Ok(()) + } + /// Discard uncommitted bytes and restart the program clock. Every rendition /// joins the new generation: no track is fenced across a declared marker. fn rewind(&mut self) { @@ -1088,9 +1303,8 @@ impl Export { self.keyframes.clear(); self.queue.clear(); self.watermark = None; - // The new generation waits for every track again, with a fresh budget: a - // frame held across the break restarts its `arrived` below. - self.stall = None; + // The stall carries across with its budget, and so does a held frame's + // `arrived` ([`Self::pick_next_track`]). self.clock = None; self.low = None; self.last_pcr = None; @@ -1108,8 +1322,7 @@ impl Export { if let Some(pending) = track.pending.as_ref() { track.discontinuity = pending.discontinuity; } - if let Some(mut pending) = track.pending.take() { - pending.arrived = web_async::time::Instant::now(); + if let Some(pending) = track.pending.take() { track.pending = track.admit(pending, self.epoch); } } @@ -1181,7 +1394,7 @@ impl Export { tracks.iter().find(|t| { matches!( t.kind, - Kind::Aac { .. } | Kind::Opus { .. } | Kind::Mp2 { .. } | Kind::Ac3 | Kind::Eac3 + Kind::Aac(_) | Kind::Opus { .. } | Kind::Mp2 { .. } | Kind::Ac3 | Kind::Eac3 ) }) }) @@ -1193,7 +1406,7 @@ impl Export { .map(|t| { let stream_type = match &t.kind { Kind::Video(stream_type) => *stream_type, - Kind::Aac { .. } => StreamType::AdtsAac, + Kind::Aac(_) => StreamType::AdtsAac, // Opus rides private-data PES; the registration + extension descriptors // below tell the demuxer it's Opus. Kind::Opus { .. } => StreamType::from_u8(0x06).map_err(anyhow::Error::msg)?, @@ -1305,8 +1518,12 @@ impl Export { /// sources give a stalled group, output goes around the lagging track until it /// catches up; zero keeps arrival order. The stall is timed from its first held /// frame rather than per frame: a frame's successor is only pulled once it goes - /// out, so a per-frame wait would release one frame per `max_age`. No track is - /// fenced, so a boundary does not jump the queue. + /// out, so a per-frame wait would release one frame per `max_age`. A rewind does + /// not restart it either: a source's latency skip is a rewind, and a hold renewed + /// at each one delays every source by the budget they skip on, so under loss the + /// feed collapses into alternating holds and skips. [`Self::resume`] does, since a + /// replacement broadcast owes nothing to the one it replaced. No track is fenced, + /// so a boundary does not jump the queue. fn pick_next_track(&mut self, waiter: &kio::Waiter) -> Option { let (timestamp, pid, name, arrived) = self .tracks @@ -1341,9 +1558,12 @@ impl Export { if self.span_counters.is_none() { self.span_counters = Some(self.counters.clone()); } - let track = self.tracks.get(name).context("missing track")?; + let track = self.tracks.get_mut(name).context("missing track")?; let pid = track.pid; let kind = track.kind.clone(); + if let Kind::Aac(aac) = &mut track.kind { + aac.program_config.take(); + } let is_video = matches!(kind, Kind::Video(_)); let timestamp = frame.timestamp; let keyframe = frame.keyframe; @@ -1353,14 +1573,13 @@ impl Export { // verbatim streams carry no PES payload; the section is written separately below. let es_payload = match &kind { Kind::Video(stream_type) => Some(video_es_payload(*stream_type, track.source.description(), &frame)?), - Kind::Aac { - object_type, - sample_rate, - channel_count, - } => { - let header = adts::write_header(*object_type, *sample_rate, *channel_count, frame.payload.len())?; - let mut framed = Vec::with_capacity(7 + frame.payload.len()); + Kind::Aac(aac) => { + let pce = aac.program_config.as_deref().unwrap_or_default(); + let raw_len = pce.len() + frame.payload.len(); + let header = adts::write_header(aac.object_type, aac.sample_rate, aac.channel_config, raw_len)?; + let mut framed = Vec::with_capacity(header.len() + raw_len); framed.extend_from_slice(&header); + framed.extend_from_slice(pce); framed.extend_from_slice(&frame.payload); Some(framed) } @@ -1384,7 +1603,7 @@ impl Export { let dts = if is_video { let pts = to_ticks(frame.timestamp); let track = self.tracks.get_mut(name).context("missing track")?; - author_dts(pts, track.dts_reserve, &mut track.last_dts) + author_dts(pts, track.reserve.ticks, &mut track.last_dts) } else { None }; @@ -1691,20 +1910,26 @@ impl Export { /// /// The value backs off by the largest reserve of any track, not just the PCR /// track's: every rendition's PES must decode at or after the clock, and each - /// video track backs its DTS off by its own catalog jitter. Back off through the - /// 33-bit wrap rather than saturating: a timeline that starts inside the reserve - /// would otherwise clamp its first slots to zero and break the uniform step. The - /// wire field is a circular clock, so the masked wrapped value is the correct - /// mod-2^33 back-off. + /// video track backs its DTS off by its own [`Reserve`]. A reserve that grows steps + /// the clock back with it, which only a new time base allows (ISO 13818-1 2.4.3.4), + /// so that PCR sets `discontinuity_indicator`. The DTS already sent stay ahead of + /// the clock values sent with them, and [`author_dts`] keeps every later DTS above + /// those. Back off through the 33-bit wrap rather than saturating: a timeline that + /// starts inside the reserve would otherwise clamp its first slots to zero and break + /// the uniform step. The wire field is a circular clock, so the masked wrapped value + /// is the correct mod-2^33 back-off. fn pcr_at(&mut self, index: u128, before: Option) -> anyhow::Result> { let pcr_pid = self.psi.as_ref().context("PSI not built")?.pcr_pid; let reserve = self .tracks .values() - .map(|t| t.dts_reserve) + .map(|t| t.reserve.ticks) .max() .unwrap_or(DEFAULT_DTS_RESERVE); let ticks = slot_ticks(index, PCR_INTERVAL).wrapping_sub(reserve); + if self.pcr_reserve.replace(reserve).is_some_and(|last| reserve > last) { + self.pcr_discontinuity = true; + } // Nothing has gone out on this PID yet, so there is no counter to repeat and // any value starts a valid run; take the one before the next to be used. let cc = match before { @@ -1936,14 +2161,17 @@ fn counter_before(bytes: &[u8], cut: usize, pid: u16, carried: Option) -> Op const PES_OPTIONAL_LEN: usize = 3 + 5; /// Extra bytes when the optional region also carries a DTS (5 DTS bytes). const PES_DTS_LEN: usize = 5; -/// Fallback decode-clock reserve in 90 kHz ticks when the catalog declares no `jitter`. At -/// 16 ticks (~0.18 ms) it is just a strict-monotonic nudge: it keeps DTS strictly increasing -/// across reordered (B-frame) decode order (the `ffplay -fflags +igndts` fix) but does not -/// keep `DTS <= PTS`. When the catalog carries `jitter` (the reorder depth, populated on -/// import), the track uses that instead, which is large enough to keep `DTS <= PTS`. See -/// [`author_dts`] and [`Track::dts_reserve`]. +/// Fallback decode-clock reserve in 90 kHz ticks when neither the catalog `jitter` nor the SPS +/// sizes one. At 16 ticks (~0.18 ms) it is just a strict-monotonic nudge: it keeps DTS strictly +/// increasing across reordered (B-frame) decode order (the `ffplay -fflags +igndts` fix) but +/// does not keep `DTS <= PTS` until reordering raises it. See [`author_dts`] and [`Reserve`]. const DEFAULT_DTS_RESERVE: u64 = 16; +/// Largest reserve an SPS or observed reordering can raise a track to (2 s): far past any real +/// reorder depth, so a corrupt SPS or a timestamp stepping back within a timeline cannot drag +/// the PCR back without bound. +const MAX_DTS_RESERVE: u64 = 2 * 90_000; + /// Whether `timestamp` has crossed into a later repetition slot than `last`. /// /// Slots are absolute on the media timeline (`floor(timestamp / interval)`) rather than @@ -2086,11 +2314,19 @@ fn video_es_payload(stream_type: StreamType, description: Option<&Bytes>, frame: fn audio_kind(config: &AudioConfig, name: &str) -> anyhow::Result { ensure_raw(&config.container, "audio", name)?; match &config.codec { - AudioCodec::AAC(aac) => Ok(Kind::Aac { - object_type: aac.profile, - sample_rate: config.sample_rate, - channel_count: config.channel_count, - }), + AudioCodec::AAC(codec) => { + // The description is exact, and names the LC core under explicit SBR or PS. Without + // one, the catalog is all there is. + Ok(Kind::Aac(match &config.description { + Some(asc) => aac::in_band(asc)?, + None => aac::InBand { + object_type: codec.profile, + sample_rate: config.sample_rate, + channel_config: adts::channel_config_from_count(config.channel_count)?, + program_config: None, + }, + })) + } AudioCodec::Mp2 => Ok(Kind::Mp2 { sample_rate: config.sample_rate, }), @@ -2203,16 +2439,15 @@ fn ensure_raw(container: &Container, kind: &str, name: &str) -> anyhow::Result<( /// `ffplay -fflags +igndts` workaround). /// /// Since decode order is already the delivery order, the only job is to keep DTS strictly -/// increasing. The clock runs [`DTS_RESERVE`] ticks behind the PTS and never goes backwards: -/// a reordered frame whose PTS dips below the clock is nudged one tick past the last DTS. With -/// the small reserve this keeps DTS monotonic but lets it sit above a B-frame's own PTS; a -/// frame-scale reserve (or the faithful wire DTS) would be needed for `DTS <= PTS`. +/// increasing. The clock runs `reserve` ticks behind the PTS and never goes backwards: a +/// reordered frame whose PTS dips below the clock is nudged one tick past the last DTS. A +/// reserve larger than the reordering keeps `DTS <= PTS`; the [`DEFAULT_DTS_RESERVE`] fallback +/// keeps DTS monotonic but lets it sit above a B-frame's own PTS. /// -/// `reserve` is how far behind the PTS to run the clock (the catalog reorder depth, or the -/// fallback). `pts` and `last` are continuous (unwrapped) 90 kHz ticks, so the clock never -/// wraps mid-stream; the 33-bit wire wrap happens once at emission in [`write_pes`]. `last` is -/// the previous DTS, updated in place. Returns `None` when the DTS equals the PTS (PES stays -/// PTS-only). +/// `reserve` is the track's [`Reserve`]. `pts` and `last` are continuous (unwrapped) 90 kHz +/// ticks, so the clock never wraps mid-stream; the 33-bit wire wrap happens once at emission. +/// `last` is the previous DTS, updated in place. Returns `None` when the DTS equals the PTS +/// (PES stays PTS-only). fn author_dts(pts: u64, reserve: u64, last: &mut Option) -> Option { let mut dts = pts.saturating_sub(reserve); if let Some(prev) = *last @@ -2224,14 +2459,17 @@ fn author_dts(pts: u64, reserve: u64, last: &mut Option) -> Option { (dts != pts).then_some(dts) } -/// The decode-clock reserve for a video rendition: its catalog `jitter` (the reorder depth) -/// in 90 kHz ticks, or [`DEFAULT_DTS_RESERVE`] when none is declared. -fn dts_reserve(config: &VideoConfig) -> u64 { - config - .jitter - .map(|t| (t.as_micros() * 90_000 / 1_000_000) as u64) - .filter(|&ticks| ticks > 0) - .unwrap_or(DEFAULT_DTS_RESERVE) +/// The reordering declared by the first SPS in a video rendition's avcC/hvcC. +fn declared_reorder(stream_type: StreamType, description: &[u8]) -> Option { + match stream_type { + StreamType::H264 => { + crate::codec::h264::sps_reorder(crate::codec::h264::Avcc::parse(description).ok()?.sps.first()?) + } + StreamType::H265 => { + crate::codec::h265::sps_reorder(crate::codec::h265::Hvcc::parse(description).ok()?.sps.first()?) + } + _ => None, + } } #[cfg(test)] diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 2a136c9e5dc..778c226325b 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -1425,6 +1425,150 @@ async fn ac3_roundtrip_byte_exact() { assert_eq!(roundtripped, ingested, "AC-3 frames must survive byte-for-byte"); } +/// The first ADTS frame of the first AAC PES: its header and raw data block. +fn first_adts_frame(ts: &[u8]) -> (super::adts::Header, Vec) { + let mut pes = PesPacketReader::new(TsPacketReader::new(Cursor::new(ts))); + let packet = pes.read_pes_packet().unwrap().expect("an AAC PES"); + let header = super::adts::Header::parse(&packet.data).unwrap(); + (header, packet.data[header.header_len..header.frame_len].to_vec()) +} + +/// ffmpeg's quad AAC fixture has no channelConfiguration, so its layout rides in a program +/// config element. Import moves it into the description and export puts it back: channel_config +/// 0 in ADTS and the element leading the first raw data block, exactly as ffmpeg wrote it. +#[tokio::test(start_paused = true)] +async fn aac_program_config_roundtrip() { + let data = include_bytes!("test_data/aac_quad.ts"); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = crate::container::ts::Import::new(broadcast, catalog.reserve()); + import.decode(&BytesMut::from(&data[..])).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let (name, audio) = snapshot.audio.renditions.iter().next().expect("an AAC track"); + assert_eq!(audio.channel_count, 4); + let ingested = read_frames(&consumer, name, Kind::Audio).await; + assert!(!ingested.is_empty(), "no AAC frames"); + + let ts = drain(consumer).await; + assert_packet_aligned(&ts); + + let (header, block) = first_adts_frame(&ts); + assert_eq!(header.channel_config, 0, "the layout is not a channelConfiguration"); + assert_eq!( + block, + first_adts_frame(data).1, + "the first raw data block, element and all" + ); + + let mut broadcast2 = moq_net::broadcast::Info::new().produce(); + let consumer2 = broadcast2.consume(); + let catalog2 = crate::catalog::Producer::new(&mut broadcast2, crate::catalog::Config::default()).unwrap(); + let mut import2 = crate::container::ts::Import::new(broadcast2, catalog2.reserve()); + import2.decode(&BytesMut::from(ts.as_ref())).unwrap(); + import2.finish().unwrap(); + + let snapshot2 = catalog2.snapshot(); + let (name2, audio2) = snapshot2 + .audio + .renditions + .iter() + .next() + .expect("round-trip lost the AAC track"); + assert_eq!(audio2.channel_count, 4); + assert_eq!(audio2.description, audio.description); + let roundtripped = read_frames(&consumer2, name2, Kind::Audio).await; + assert_eq!(roundtripped, ingested, "the element is written once, not per frame"); +} + +/// GStreamer 1.28 `fdkaacenc` output, 48 kHz stereo, remuxed to FLV by ffmpeg 9.0.1. Its +/// AudioSpecificConfig signals SBR (and PS for v2) explicitly: object type 5 or 29 over an LC core +/// at 24 kHz, stereo for v1 and mono for v2. ADTS has two bits for the object type, so export +/// labels the LC core at its own rate and layout and leaves SBR and PS to implicit signaling, the +/// header ffmpeg's ADTS muxer writes too. ffprobe reads the result back as HE-AAC or HE-AACv2 at +/// 48 kHz stereo, like the source. +#[tokio::test(start_paused = true)] +async fn aac_explicit_sbr_exports_its_lc_core() { + let fixtures: [(&[u8], u8); 2] = [ + (include_bytes!("test_data/he_aac.flv"), 2), + (include_bytes!("test_data/he_aac_v2.flv"), 1), + ]; + for (data, channel_config) in fixtures { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = crate::container::flv::Import::new(broadcast, catalog.reserve()); + import.decode(data).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let (name, _) = snapshot.audio.renditions.iter().next().expect("an AAC track"); + let ingested = read_frames(&consumer, name, Kind::Audio).await; + assert!(!ingested.is_empty(), "no AAC frames"); + + let ts = drain(consumer).await; + assert_packet_aligned(&ts); + + let (header, block) = first_adts_frame(&ts); + assert_eq!(header.object_type, 2, "the LC core, not a masked SBR or PS"); + assert_eq!(header.sample_rate, 24_000, "the core rate, not the output rate"); + assert_eq!(header.channel_config, channel_config); + assert_eq!(block, ingested[0], "the raw data block is untouched"); + } +} + +/// Without a description, the catalog is all ADTS has to label a track with. A channel count no +/// channelConfiguration names is refused rather than written as stereo, and HE-AAC, whose core +/// rate and layout only a description names, is refused rather than masked to AAC Main. +#[tokio::test(start_paused = true)] +async fn aac_export_refuses_what_adts_cannot_label() { + for (profile, channel_count, refusal) in [(2, 7, "7 channels"), (5, 2, "audioObjectType 5")] { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + + let track = broadcast + .create_track( + broadcast.unique_name(".aac"), + hang::container::track_info(hang::catalog::PRIORITY.audio), + ) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile }, 48_000, channel_count); + cfg.container = Container::Legacy; + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(track.name().to_string(), cfg); + + let mut producer = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Data)); + producer + .write(Frame { + timestamp: Timestamp::from_millis(0).unwrap(), + duration: None, + payload: Bytes::from_static(&[0x01, 0x02]), + keyframe: true, + }) + .unwrap(); + producer.finish().unwrap(); + + let mut exporter = Export::new(crate::source::announced(&consumer)).await.unwrap(); + let err = loop { + match tokio::time::timeout(Duration::from_secs(1), exporter.next()).await { + Ok(Ok(Some(_))) => continue, + Ok(Ok(None)) => panic!("export completed; expected a refusal naming {refusal}"), + Ok(Err(e)) => break e, + Err(_) => panic!("export neither errored nor completed"), + } + }; + assert!(err.to_string().contains(refusal), "expected {refusal}, got: {err}"); + } +} + /// The ffmpeg E-AC-3 fixture must survive TS -> MoQ -> TS byte-for-byte in an /// audio-only program; the PMT re-announces ATSC 0x87 with the 'EAC3' /// registration descriptor. @@ -2560,7 +2704,13 @@ async fn reordered_video_keeps_the_table_cadence() { assert_eq!(export.discontinuity(), 0, "a reorder is not a rewind"); assert_eq!(count_pid(&out, 0x0000), 10, "PAT once per 500ms slot, not per reorder"); assert_eq!(count_pid(&out, 0x0011), 3, "SDT once per 2s slot, not per reorder"); - assert_eq!(count_discontinuity(&out), 0, "a reorder is not a discontinuity"); + // The SPS declares no reorder depth, so the first B-frame grows the reserve once, after + // the first PCR: that one step back is a new time base, the reorders after it are not. + assert_eq!( + count_discontinuity(&out), + 1, + "only the reserve's growth restarts the clock" + ); } /// A program with more than one track marks the break once, not once per track. A @@ -3762,10 +3912,10 @@ async fn tune_in_does_not_wait_on_dropped_audio() { assert!(!out.is_empty(), "the tune-in waited on audio it had dropped"); } -/// A rewind taken while going around a quiet track gives the new generation a -/// fresh hold rather than the one that already expired. +/// A rewind taken while going around a quiet track keeps going around it: the +/// expired hold carries into the new generation rather than starting afresh. #[tokio::test(start_paused = true)] -async fn rewind_restarts_the_stall() { +async fn rewind_keeps_an_expired_stall() { let max_age = Duration::from_millis(500); let mut rig = Interleave::new(); let mut export = rig.export(max_age).await; @@ -3785,33 +3935,18 @@ async fn rewind_restarts_the_stall() { for tick in 0..=5 { rig.video(GOP + tick); } - // Well inside `max_age`: the new generation must still be waiting on the audio. - while let Ok(frame) = tokio::time::timeout(max_age / 5, export.next()).await { - out.extend(frame.expect("exporter error")); - } - let after = |out: &[Frame]| { - pes_pts_in_order(out) - .into_iter() - .filter(|&pts| pts > GOP * VIDEO_US * 90 / 1_000) - .count() - }; - assert_eq!( - after(&out), - 0, - "the new generation went around the audio without waiting" - ); - - // Once its own wait lapses, it goes around the audio too. - tokio::time::advance(max_age).await; out.extend(poll_frames(&mut export)); - assert!(after(&out) > 0, "the new generation never went out"); + let after = pes_pts_in_order(&out) + .into_iter() + .filter(|&pts| pts >= GOP * VIDEO_US * 90 / 1_000) + .count(); + assert!(after > 0, "the new generation waited on the audio again"); assert_eq!(export.discontinuity(), 1); } -/// A frame held across a rewind starts the new generation's hold afresh rather than -/// from when it first arrived. +/// A frame held across a rewind keeps the wait it has already served. #[tokio::test(start_paused = true)] -async fn rewind_restarts_a_held_frame() { +async fn rewind_keeps_a_held_frame_waiting_time() { let max_age = Duration::from_millis(500); let mut rig = Interleave::new(); let mut export = rig.export(max_age).await; @@ -3830,15 +3965,70 @@ async fn rewind_restarts_a_held_frame() { rig.video.discontinuity().unwrap(); rig.video(GOP); out.extend(poll_frames(&mut export)); - assert_eq!( - export.discontinuity(), - 0, - "the held audio went around the video at once" - ); + assert_eq!(export.discontinuity(), 1, "the held audio waited a second budget"); +} + +/// A rewind part way through a hold neither ends it nor renews it: the new generation +/// waits out only what is left of the budget. +#[tokio::test(start_paused = true)] +async fn rewind_keeps_a_partial_stall() { + let max_age = Duration::from_millis(500); + let mut rig = Interleave::new(); + let mut export = rig.export(max_age).await; + let mut out = Vec::new(); + + rig.video(0); + rig.audio_until(1, &mut export, &mut out); + for tick in 1..=5 { + rig.video(tick); + } + assert!(poll_frames(&mut export).is_empty(), "video waits for the quiet audio"); + tokio::time::advance(max_age / 2).await; + assert!(poll_frames(&mut export).is_empty(), "the hold lapsed early"); + + rig.video.discontinuity().unwrap(); + for tick in 0..=5 { + rig.video(GOP + tick); + } + assert!(poll_frames(&mut export).is_empty(), "the rewind ended the hold"); + + tokio::time::advance(max_age / 2).await; + assert!(!poll_frames(&mut export).is_empty(), "the rewind renewed the hold"); + assert_eq!(export.discontinuity(), 1); +} + +/// Under loss every source skip is a rewind. However many arrive while a sparse +/// track stays quiet, the interleave holds for one budget, not one per rewind: +/// renewing it at each would delay every source by the budget they skip on, +/// and the feed would collapse into alternating holds and skips. +#[tokio::test(start_paused = true)] +async fn repeated_rewinds_hold_once() { + let max_age = Duration::from_millis(500); + let mut rig = Interleave::new(); + let mut export = rig.export(max_age).await; + let mut out = Vec::new(); + rig.video(0); + rig.audio_until(1, &mut export, &mut out); + for tick in 1..=5 { + rig.video(tick); + } + assert!(poll_frames(&mut export).is_empty(), "video waits for the quiet audio"); tokio::time::advance(max_age).await; out.extend(poll_frames(&mut export)); - assert_eq!(export.discontinuity(), 1, "the new generation never went out"); + + for generation in 1..=8 { + rig.video.discontinuity().unwrap(); + for tick in 0..=5 { + rig.video(generation * GOP + tick); + } + out.extend(poll_frames(&mut export)); + assert_eq!( + export.discontinuity(), + generation, + "rewind {generation} held the feed for a fresh budget" + ); + } } /// A section lost before the cycle wraps commits an observed subset; the next @@ -4952,3 +5142,579 @@ async fn export_stuffing_keeps_the_fractional_remainder() { ); assert!(clocked.nulls > 0, "no null stuffing was emitted"); } + +// The decode clock follows the stream's reordering: its reserve comes from the catalog `jitter`, +// else the depth the SPS declares, else the reordering muxed so far, and it keeps following all +// three after the program tables are written. + +/// Display offsets within a group, in decode order: a closed GOP with one B-frame per reference. +/// A B-frame lands one frame below the high-water mark. +const IPB: [u64; GOP as usize] = [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13]; +/// A three-B pyramid: the outer B-frames sit under the middle one, so one lands three frames +/// below the high-water mark while the SPS can declare a depth of two. +const PYRAMID: [u64; GOP as usize] = [0, 4, 2, 1, 3, 8, 6, 5, 7, 12, 10, 9, 11, 14, 13]; +/// Where the [`Reordered`] timeline starts, in frames: whole groups, and far enough in that +/// the PCR's back-off never wraps below zero. +const REORDERED_BASE: u64 = 20 * GOP; +/// One 25 fps frame in 90 kHz ticks. +const FRAME_TICKS: u64 = 3_600; + +/// The start of video frame `frame` of a [`Reordered`] broadcast, in display order. +fn reordered_at(frame: u64) -> Timestamp { + Timestamp::from_micros((REORDERED_BASE + frame) * VIDEO_US).unwrap() +} + +/// A reordered H.264 rendition and an AAC one, on the late-join fixture's cadence. +struct Reordered { + _broadcast: moq_net::broadcast::Producer, + catalog: crate::catalog::Producer, + video: Producer, + audio: Producer, + source: crate::Source, + name: String, + /// Groups laid out as [`PYRAMID`]; every other group is [`IPB`]. + pyramid: &'static [u64], + audio_index: u64, +} + +impl Reordered { + fn new(sps: &'static [u8], pps: &'static [u8], pyramid: &'static [u64]) -> Self { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + + let track = broadcast + .create_track( + broadcast.unique_name(".avc1"), + hang::container::track_info(hang::catalog::PRIORITY.video), + ) + .unwrap(); + let name = track.name().to_string(); + let mut cfg = VideoConfig::new(H264 { + profile: sps[1], + constraints: sps[2], + level: sps[3], + inline: false, + }); + cfg.container = Container::Legacy; + cfg.description = + Some(crate::codec::h264::build_avcc(&[Bytes::from_static(sps)], &[Bytes::from_static(pps)]).unwrap()); + catalog.modify().unwrap().video.renditions.insert(name.clone(), cfg); + let video = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Video)); + + let track = broadcast + .create_track( + broadcast.unique_name(".aac"), + hang::container::track_info(hang::catalog::PRIORITY.audio), + ) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile: 2 }, 48_000, 2); + cfg.container = Container::Legacy; + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(track.name().to_string(), cfg); + let audio = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Audio)); + + Self { + source: crate::source::announced(&consumer), + _broadcast: broadcast, + catalog, + video, + audio, + name, + pyramid, + audio_index: 0, + } + } + + /// An exporter with its subscriptions resolved, so later polls need no runtime. + async fn export(&self, max_age: Duration) -> Export { + let mut export = Export::new(self.source.clone()).await.unwrap().with_max_age(max_age); + assert!(drain_frames(&mut export).await.is_empty()); + export + } + + /// Write the video frame `tick`-th in decode order. + fn video(&mut self, tick: u64) { + let (group, at) = (tick / GOP, (tick % GOP) as usize); + let layout = if self.pyramid.contains(&group) { &PYRAMID } else { &IPB }; + let keyframe = at == 0; + let slice = if keyframe { + vec![0x65u8; 3_000] + } else { + vec![0x41u8; 400] + }; + self.video + .write(Frame { + timestamp: reordered_at(group * GOP + layout[at]), + duration: None, + payload: length_prefixed(&[&slice]), + keyframe, + }) + .unwrap(); + } + + /// Write the next audio frame if it starts before video frame `frame`. + fn audio_before(&mut self, frame: u64) -> bool { + let index = self.audio_index; + let timestamp = Timestamp::from_micros(REORDERED_BASE * VIDEO_US + index * AUDIO_US).unwrap(); + if timestamp >= reordered_at(frame) { + return false; + } + self.audio + .write(Frame { + timestamp, + duration: None, + payload: Bytes::from_iter((0..180u16).map(|i| (i ^ index as u16) as u8)), + keyframe: index.is_multiple_of(AUDIO_GROUP), + }) + .unwrap(); + self.audio_index += 1; + true + } + + fn publish_jitter(&mut self, jitter: Duration) { + let mut catalog = self.catalog.modify().unwrap(); + catalog.video.renditions.get_mut(&self.name).unwrap().jitter = Some(jitter); + } + + fn finish(&mut self) { + self.video.finish().unwrap(); + self.audio.finish().unwrap(); + } +} + +/// Export a [`Reordered`] broadcast twice, like [`export_twice`]: the second exporter joins at +/// [`JOIN`], and both are drained after every tick. `jitter` is published at its tick when given. +async fn export_reordered( + sps: &'static [u8], + pps: &'static [u8], + pyramid: &'static [u64], + jitter: Option<(u64, Duration)>, +) -> (Vec, Vec) { + let mut rig = Reordered::new(sps, pps, pyramid); + let mut a = Export::new(rig.source.clone()).await.unwrap(); + let mut b = None; + let (mut out_a, mut out_b) = (Vec::new(), Vec::new()); + for tick in 0..TICKS { + if let Some((at, jitter)) = jitter + && at == tick + { + rig.publish_jitter(jitter); + } + rig.video(tick); + while rig.audio_before(tick + 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(rig.source.clone()).await.unwrap()); + } + } + rig.finish(); + let mut b = b.unwrap(); + out_a.extend(drain_frames(&mut a).await); + out_b.extend(drain_frames(&mut b).await); + (out_a, out_b) +} + +/// `(PTS, DTS)` of every video PES start in the frames stamped within `range`, in transport +/// order. The whole stream is read so the program tables resolve every PID. +fn video_timing(frames: &[Frame], range: impl std::ops::RangeBounds) -> Vec<(u64, Option)> { + let stamps: Vec = frames + .iter() + .flat_map(|f| std::iter::repeat_n(f.timestamp, f.payload.len() / 188)) + .collect(); + let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let mut reader = TsPacketReader::new(Cursor::new(bytes)); + let mut out = Vec::new(); + let mut index = 0; + while let Some(packet) = reader.read_ts_packet().unwrap() { + let stamp = stamps[index]; + index += 1; + if !range.contains(&stamp) { + continue; + } + if let Some(TsPayload::PesStart(pes)) = packet.payload + && (mpeg2ts::es::StreamId::VIDEO_MIN..=mpeg2ts::es::StreamId::VIDEO_MAX) + .contains(&pes.header.stream_id.as_u8()) + { + let pts = pes.header.pts.expect("video PES carried no PTS").as_u64(); + out.push((pts, pes.header.dts.map(|t| t.as_u64()))); + } + } + out +} + +/// Every video frame decodes at or before it is presented. +fn assert_decodes_before_presenting(timing: &[(u64, Option)]) { + assert!(timing.len() > 20, "too few video frames to judge: {}", timing.len()); + for (i, &(pts, dts)) in timing.iter().enumerate() { + let dts = dts.unwrap_or(pts); + assert!(dts <= pts, "frame {i} decodes at {dts}, after it is presented at {pts}"); + } +} + +/// In transport order, every PES unit decodes at or after the last PCR preceding it, and the +/// clock only steps back where a PCR signals a new time base. +fn assert_decodes_after_the_clock(frames: &[Frame]) { + let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let mut reader = TsPacketReader::new(Cursor::new(bytes)); + let mut last_pcr = None; + while let Some(packet) = reader.read_ts_packet().unwrap() { + if let Some(af) = packet.adaptation_field.as_ref() + && let Some(pcr) = af.pcr + { + let pcr = pcr.as_u64() / 300; + if let Some(last) = last_pcr { + assert!( + pcr > last || af.discontinuity_indicator, + "the clock steps back from {last} to {pcr} without a discontinuity" + ); + } + last_pcr = Some(pcr); + } + if let Some(TsPayload::PesStart(pes)) = packet.payload + && let Some(pcr) = last_pcr + { + let pts = pes.header.pts.expect("PES carried no PTS").as_u64(); + let decode = pes.header.dts.map(|t| t.as_u64()).unwrap_or(pts); + assert!(decode >= pcr, "unit decodes at {decode}, before the clock at {pcr}"); + } + } +} + +/// With no `jitter`, an SPS that declares its reorder depth at a fixed frame rate sizes the +/// reserve from the first keyframe: every B-frame decodes at or before it is presented from the +/// start, and an exporter whose B-frames arrive behind the audio covering them renders the same +/// bytes as one that sees each tick whole. +#[tokio::test(start_paused = true)] +async fn declared_reorder_sizes_the_decode_clock_from_the_first_frame() { + let mut rig = Reordered::new( + crate::codec::h264::fixtures::SPS_IPB, + crate::codec::h264::fixtures::PPS, + &[], + ); + let max_age = Duration::from_millis(500); + let (mut late, mut whole) = (rig.export(max_age).await, rig.export(max_age).await); + let (mut out_late, mut out_whole) = (Vec::new(), Vec::new()); + for tick in 0..TICKS / 2 { + while rig.audio_before(tick + 2) { + out_late.extend(poll_frames(&mut late)); + } + rig.video(tick); + out_late.extend(poll_frames(&mut late)); + out_whole.extend(poll_frames(&mut whole)); + } + rig.finish(); + out_late.extend(drain_frames(&mut late).await); + out_whole.extend(drain_frames(&mut whole).await); + + let late: Vec = out_late.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let whole: Vec = out_whole.iter().flat_map(|f| f.payload.iter().copied()).collect(); + assert!(late.len() > 100 * 188, "too little output to compare: {}", late.len()); + assert!(late == whole, "arrival order changed the rendering"); + + let timing = video_timing(&out_late, ..); + assert_decodes_before_presenting(&timing); + // Depth 1 at 25 fps, and one tick so the B-frame decodes after the P-frame above it. + let (pts, dts) = timing[1]; + assert_eq!( + pts, + (REORDERED_BASE + 2) * FRAME_TICKS, + "the first P-frame follows the keyframe" + ); + assert_eq!( + dts, + Some(pts - FRAME_TICKS - 1), + "the first P-frame already runs on the declared reserve" + ); + assert_decodes_after_the_clock(&out_late); +} + +/// With nothing declared, the reserve grows to the deepest reordering muxed so far. This is the +/// one path where it depends on when an exporter joined: a joiner that has muxed only shallow +/// groups runs a shallower clock than a runner that saw a deep one before the join, until the +/// deep structure recurs. From then on the two render the same bytes. +#[tokio::test(start_paused = true)] +async fn undeclared_reorder_converges_after_its_deepest_reorder() { + // The runner sees a pyramid in group 2; the joiner, arriving at group 5, first in group 7. + // Group 9 repeats it on the settled reserve. + let (runner, joiner) = export_reordered(SPS, PPS, &[2, 7, 9], None).await; + let keyframes: Vec = joiner.iter().filter(|f| f.keyframe).map(|f| f.timestamp).collect(); + let deepest = reordered_at(8 * GOP); + assert!( + keyframes[1] < deepest, + "the joiner must render shallow groups before the deep one" + ); + + assert_ne!( + video_timing(&runner, keyframes[1]..deepest), + video_timing(&joiner, keyframes[1]..deepest), + "a joiner that has not muxed the deepest reordering runs the runner's clock" + ); + assert_only_continuity_differs(&runner, &joiner, deepest); + + for frames in [&runner, &joiner] { + assert_decodes_before_presenting(&video_timing(frames, deepest..)); + // Growth steps the reserve up mid-stream; the clock must still never overtake a decode. + assert_decodes_after_the_clock(frames); + } +} + +/// A `jitter` first published after the program tables sizes the decode clock from then on, +/// so the running exporter renders what a joiner that found it in its first catalog renders. +#[tokio::test(start_paused = true)] +async fn jitter_published_after_the_tables_raises_the_reserve() { + let jitter = Duration::from_millis(80); + let (runner, joiner) = export_reordered(SPS, PPS, &[], Some((2 * GOP, jitter))).await; + let keyframes: Vec = joiner.iter().filter(|f| f.keyframe).map(|f| f.timestamp).collect(); + assert_only_continuity_differs(&runner, &joiner, keyframes[1]); + + // Every keyframe after the publish decodes a full `jitter` ahead of its presentation. + let ticks = 80 * 90; + let keyframe_timing: Vec<(u64, Option)> = video_timing(&runner, reordered_at(3 * GOP)..) + .into_iter() + .filter(|(pts, _)| (pts / FRAME_TICKS).is_multiple_of(GOP)) + .collect(); + assert!( + keyframe_timing.len() > 3, + "too few keyframes to judge: {keyframe_timing:?}" + ); + for (pts, dts) in keyframe_timing { + assert_eq!(dts, Some(pts - ticks), "keyframe at {pts} ignores the published jitter"); + } + assert_decodes_after_the_clock(&runner); +} + +/// Publish a Legacy AAC rendition named `name`. +fn aac_rendition( + broadcast: &mut moq_net::broadcast::Producer, + catalog: &mut crate::catalog::Producer, + name: &str, +) -> Producer { + let track = broadcast + .create_track(name, hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile: 2 }, 48_000, 2); + cfg.container = Container::Legacy; + catalog.modify().unwrap().audio.renditions.insert(name.to_string(), cfg); + Producer::new(track, HangContainer::Legacy(crate::container::Kind::Data)) +} + +/// Write one AAC frame at `ms`, in a group of its own. +fn write_aac(producer: &mut Producer, ms: u64) { + producer + .write(Frame { + timestamp: Timestamp::from_millis(ms).unwrap(), + duration: None, + payload: Bytes::from_static(&[0x21, 0x10, 0x04, 0x60]), + keyframe: true, + }) + .unwrap(); + producer.cut(None).unwrap(); +} + +/// Count the PES packets across `frames`. +fn pes_count(frames: &[Frame]) -> usize { + let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let mut reader = TsPacketReader::new(Cursor::new(bytes)); + let mut count = 0; + while let Some(packet) = reader.read_ts_packet().unwrap() { + if matches!(packet.payload, Some(TsPayload::PesStart(_))) { + count += 1; + } + } + count +} + +/// Pull frames until the export ends, returning them and how it ended. +async fn drain_to_end(export: &mut Export) -> (Vec, crate::Result<()>) { + let mut out = Vec::new(); + loop { + match tokio::time::timeout(Duration::from_secs(5), export.next()) + .await + .expect("the export ends") + { + Ok(Some(frame)) => out.push(frame), + Ok(None) => return (out, Ok(())), + Err(err) => return (out, Err(err)), + } + } +} + +/// A track that leaves the catalog after the PMT is read to its own end rather than +/// refused as a layout change. A publisher retires a rendition as its track ends, and +/// that catalog update can land before the track's last frames and its finish do, so +/// this retires the rendition first: the order in which the old check misread a clean +/// end as a removed track. +#[tokio::test(start_paused = true)] +async fn a_track_leaving_the_catalog_is_read_to_its_end() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut kept = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let mut leaving = aac_rendition(&mut broadcast, &mut catalog, "b.aac"); + + let mut export = Export::new(crate::source::announced(&consumer)) + .await + .unwrap() + .with_max_age(RECORDING_MAX_AGE); + for ms in (0..200).step_by(20) { + write_aac(&mut kept, ms); + write_aac(&mut leaving, ms); + } + let mut frames = drain_frames(&mut export).await; + assert!(!frames.is_empty(), "the program started"); + + catalog.modify().unwrap().audio.renditions.remove("b.aac"); + for ms in (200..300).step_by(20) { + write_aac(&mut kept, ms); + write_aac(&mut leaving, ms); + } + leaving.finish().unwrap(); + for ms in (300..400).step_by(20) { + write_aac(&mut kept, ms); + } + kept.finish().unwrap(); + catalog.finish().unwrap(); + + let (rest, end) = drain_to_end(&mut export).await; + end.expect("a track leaving the catalog is not a layout change"); + frames.extend(rest); + assert_eq!(pes_count(&frames), 20 + 15, "every frame of both tracks went out"); +} + +/// A broadcast that ends and is published again carries on in the same export: the +/// returned catalog resubscribes the program's tracks, the clock break is flagged once, +/// and the PAT/PMT go out again for a receiver re-acquiring after the gap. Both ways a +/// broadcast ends, a clean finish and a drop, resume the same way. +async fn resume_after(finish: bool) { + let origin = crate::source::produce_origin(); + let source = crate::Source::new(origin.consume(), "live"); + let publish = || { + let mut broadcast = origin.publish("live", Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + (broadcast, catalog) + }; + + let (mut broadcast, mut catalog) = publish(); + let mut track = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let ended = source.broadcast().await.unwrap(); + let mut export = Export::new(source.clone()) + .await + .unwrap() + .with_max_age(RECORDING_MAX_AGE); + for ms in (0..200).step_by(20) { + write_aac(&mut track, ms); + } + let mut before = drain_frames(&mut export).await; + if finish { + track.finish().unwrap(); + catalog.finish().unwrap(); + } + drop((broadcast, catalog, track)); + let (rest, end) = drain_to_end(&mut export).await; + before.extend(rest); + assert_eq!(end.is_ok(), finish, "a finish ends cleanly and a drop fails: {end:?}"); + + // The returned catalog lists the track only in its second snapshot, and the restarted + // publisher's clock starts over. + let (mut broadcast, mut catalog) = publish(); + std::ops::DerefMut::deref_mut(&mut catalog.modify().unwrap()); + source.returned(&ended).await.unwrap(); + export.resume().await.unwrap(); + let mut after = drain_frames(&mut export).await; + assert!(after.is_empty(), "nothing to carry before the track is listed"); + let mut track = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + for ms in (0..200).step_by(20) { + write_aac(&mut track, ms); + } + after.extend(drain_frames(&mut export).await); + track.finish().unwrap(); + catalog.finish().unwrap(); + let (rest, end) = drain_to_end(&mut export).await; + after.extend(rest); + end.unwrap(); + + assert_eq!(export.discontinuity(), 1, "the return is one break"); + assert_eq!(count_discontinuity(&before), 0); + assert_eq!(count_discontinuity(&after), 1, "the break is flagged once"); + assert!(count_pid(&after, 0x0000) >= 1, "PAT re-emitted after the return"); + assert_eq!(pes_count(&after), 10, "the returned broadcast's frames all went out"); +} + +/// A replacement broadcast gets a fresh interleave budget: a hold that expired on the +/// broadcast before it doesn't let the new one go around a track still within its own. +#[tokio::test(start_paused = true)] +async fn resume_does_not_inherit_an_expired_stall() { + let max_age = Duration::from_secs(2); + let origin = crate::source::produce_origin(); + let source = crate::Source::new(origin.consume(), "live"); + let publish = || { + let mut broadcast = origin.publish("live", Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + (broadcast, catalog) + }; + // Output that needs no more than a tenth of the budget to pass. + async fn quick(export: &mut Export, max_age: Duration) -> Vec { + let mut out = Vec::new(); + while let Ok(frame) = tokio::time::timeout(max_age / 10, export.next()).await { + out.extend(frame.expect("exporter error")); + } + out + } + + let (mut broadcast, mut catalog) = publish(); + let mut leading = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let mut quiet = aac_rendition(&mut broadcast, &mut catalog, "b.aac"); + let ended = source.broadcast().await.unwrap(); + let mut export = Export::new(source.clone()).await.unwrap().with_max_age(max_age); + write_aac(&mut quiet, 0); + for ms in (0..200).step_by(20) { + write_aac(&mut leading, ms); + } + quick(&mut export, max_age).await; + tokio::time::advance(max_age).await; + assert!( + !quick(&mut export, max_age).await.is_empty(), + "the leading track went around the quiet one" + ); + drop((broadcast, catalog, leading, quiet)); + let (_, end) = drain_to_end(&mut export).await; + assert!(end.is_err(), "a drop fails the export"); + + let (mut broadcast, mut catalog) = publish(); + let mut leading = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let mut quiet = aac_rendition(&mut broadcast, &mut catalog, "b.aac"); + source.returned(&ended).await.unwrap(); + export.resume().await.unwrap(); + for ms in (0..200).step_by(20) { + write_aac(&mut leading, ms); + } + assert_eq!( + pes_count(&quick(&mut export, max_age).await), + 0, + "the replacement went around its quiet track on the old broadcast's budget" + ); + write_aac(&mut quiet, 200); + assert!( + !quick(&mut export, max_age).await.is_empty(), + "the replacement went out once both tracks showed" + ); +} + +#[tokio::test(start_paused = true)] +async fn resume_after_a_finish() { + resume_after(true).await; +} + +#[tokio::test(start_paused = true)] +async fn resume_after_a_drop() { + resume_after(false).await; +} diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 3965a5cd504..299ad4d037a 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -69,8 +69,10 @@ pub struct Import { pmt_pids: HashSet, /// Per elementary-stream-PID codec routing. streams: HashMap>, - /// Counters from audio routes a later PMT replaced, keyed by PID. + /// Counters from routes a later PMT replaced, keyed by PID. retired_stats: BTreeMap, + /// Access units per elementary stream, timed on the program clock. + liveness: Liveness, /// In-progress PES reassembly, keyed by elementary PID. pending: HashMap, /// Per elementary-stream-PID TS continuity state. @@ -133,6 +135,9 @@ pub struct Import { /// advances it, so a cue could be stamped with another program's PTS. last_pts: Option, media_unwrap: PtsUnwrap, + /// The program number chosen by [`with_program`](Self::with_program). `None` imports the + /// multiplex's only program and refuses a PAT that lists more than one. + program: Option, } impl Import { @@ -157,6 +162,7 @@ impl Import { pmt_pids: HashSet::new(), streams: HashMap::new(), retired_stats: BTreeMap::new(), + liveness: Liveness::default(), pending: HashMap::new(), continuity: HashMap::new(), pcr_pid: None, @@ -175,9 +181,20 @@ impl Import { identity_recorded: false, last_pts: None, media_unwrap: PtsUnwrap::default(), + program: None, } } + /// Import only the program numbered `program` in the PAT, ignoring the rest of the multiplex. + /// + /// Without this, a PAT that lists more than one program fails the import with + /// [`MultipleProgramsError`] rather than merging them onto one clock. A PAT that does not + /// list `program` fails it too. + pub fn with_program(mut self, program: u16) -> Self { + self.program = Some(program); + self + } + /// Select the container this importer wraps decoded media renditions in. /// /// [`Legacy`](hang::catalog::Container::Legacy) unless selected. It applies to every rendition @@ -272,15 +289,17 @@ impl Import { if self.pcr_pid.is_some_and(|p| p.as_u16() == pid) && pkt[1] & 0x80 == 0 { if discontinuity_indicator(&pkt) { self.timebase_break()?; - } else if self.supports_mpegts - && let Some(pcr) = pcr(&pkt) - && self.mux_rate.pcr(pcr) - { - self.record_mux_rate()?; + } else if let Some(pcr) = pcr(&pkt) { + self.liveness.pcr(pcr); + if self.supports_mpegts && self.mux_rate.pcr(pcr) { + self.record_mux_rate()?; + } } } if let Some(section) = self.sections.get_mut(&pid) { - self.published |= section.packet(&pkt, self.last_pts)?; + let units = section.packet(&pkt, self.last_pts)?; + self.published |= units > 0; + self.liveness.delivered(pid, units); continue; } // Intercept the standalone SI PIDs before the routing gate below drops them: @@ -363,11 +382,16 @@ impl Import { let pid = packet.header.pid; match packet.payload { Some(TsPayload::Pmt(pmt)) => { + // PMTs of several programs may share one PID; only the chosen one maps streams. + if self.program.is_some_and(|program| program != pmt.program_num) { + return Ok(()); + } // Which PID speaks for the program clock, so a `discontinuity_indicator` there // can be read as a timebase reset rather than a counter jump. if self.pcr_pid != pmt.pcr_pid { self.pcr_pid = pmt.pcr_pid; // A new clock: the intervals straddling the switch measure nothing. + self.liveness.discontinuity(); if self.mux_rate.discontinuity() { self.record_mux_rate()?; } @@ -417,12 +441,7 @@ impl Import { } Some(TsPayload::PesStart(pes)) => self.handle_pes_start(pid, pes)?, Some(TsPayload::PesContinuation(bytes)) => self.handle_pes_continuation(pid, &bytes)?, - // Learn the PMT PIDs so the routing gate in `decode` lets them through. - Some(TsPayload::Pat(pat)) => { - self.pmt_pids - .extend(pat.table.iter().map(|entry| entry.program_map_pid)); - self.record_program_identity(&pat)?; - } + Some(TsPayload::Pat(pat)) => self.handle_pat(&pat)?, _ => {} } Ok(()) @@ -493,11 +512,10 @@ impl Import { // by an 'Opus' registration descriptor. Channels and the (always 48 kHz) rate // come from the descriptors, so the importer is built up front. StreamType::Mpeg2PacketizedData if registration_format(descriptors) == Some(*b"Opus") => { - let channel_count = opus_channel_count(descriptors).unwrap_or(2); + let config = opus_config(descriptors)?; let track = self .broadcast .unique_track(".opus", self.catalog.track_info(hang::catalog::PRIORITY.audio))?; - let config = opus::Config::new(48_000, channel_count); let mut config: hang::catalog::AudioConfig = config.into(); config.container = self.container.clone(); Stream::Opus(Box::new(OpusStream { @@ -537,6 +555,9 @@ impl Import { if !matches!(stream, Stream::Ignored | Stream::Clock) { self.initialized = true; } + if !matches!(stream, Stream::Ignored) { + self.liveness.register(pid.as_u16()); + } self.streams.insert(pid, stream); self.continuity.entry(pid).or_default(); Ok(()) @@ -595,6 +616,7 @@ impl Import { descriptors, )?; self.sections.insert(pid.as_u16(), stream); + self.liveness.register(pid.as_u16()); self.initialized = true; tracing::debug!( pid = pid.as_u16(), @@ -650,6 +672,8 @@ impl Import { if let Some(pts) = pes.header.pts { self.catalog.anchor(Timestamp::from_scale(pts.as_u64(), 90_000)?)?; } + // Nothing is published, but each PES is a picture the source delivered. + self.liveness.delivered(pid.as_u16(), 1); return Ok(()); } @@ -698,7 +722,9 @@ impl Import { if let Some(pts) = pending.pts { self.catalog.anchor(Timestamp::from_scale(pts, 90_000)?)?; } - self.published |= stream.write(pending, batched)?; + let units = stream.write(pending, batched)?; + self.published |= units > 0; + self.liveness.delivered(pid.as_u16(), units); // Record the decoded media track's PID + PMT descriptors (language, ...) once // its lazily created track exists, so export can preserve them. @@ -749,6 +775,7 @@ impl Import { self.media_unwrap.discontinuity(); self.last_pts = None; self.published = false; + self.liveness.discontinuity(); if self.mux_rate.discontinuity() { self.record_mux_rate()?; } @@ -795,19 +822,46 @@ impl Import { Ok(()) } + /// Pick the imported program from a PAT and learn its PMT PID, so the routing gate in + /// `decode` lets that PMT through and no other. + /// + /// Every PAT is checked, so a program added mid-stream ends an unselected import, and a + /// selected program that disappears ends a selected one; media already published stays. + fn handle_pat(&mut self, pat: &mpeg2ts::ts::payload::Pat) -> anyhow::Result<()> { + // program_number 0 is the network PID association, not a program. + let programs: Vec<_> = pat.table.iter().filter(|entry| entry.program_num != 0).collect(); + let numbers = || programs.iter().map(|entry| entry.program_num).collect::>(); + let entry = match self.program { + Some(program) => match programs.iter().find(|entry| entry.program_num == program) { + Some(entry) => entry, + None => anyhow::bail!( + "transport stream has no program {program}; its PAT lists {}", + list_programs(&numbers()) + ), + }, + None => match programs.as_slice() { + [] => return Ok(()), + [entry] => entry, + _ => return Err(MultipleProgramsError { programs: numbers() }.into()), + }, + }; + self.pmt_pids.insert(entry.program_map_pid); + self.record_program_identity(pat.transport_stream_id, entry) + } + /// Capture the transport/service identity (TSID, service number, PMT PID) from the /// PAT into the catalog service record, once. No-op without `mpegts` support. - fn record_program_identity(&mut self, pat: &mpeg2ts::ts::payload::Pat) -> anyhow::Result<()> { + fn record_program_identity( + &mut self, + transport_stream_id: u16, + entry: &mpeg2ts::ts::ProgramAssociation, + ) -> anyhow::Result<()> { if !self.supports_mpegts || self.identity_recorded { return Ok(()); } - // program_number 0 is the network PID association, not a service; skip it. - let Some(entry) = pat.table.iter().find(|entry| entry.program_num != 0) else { - return Ok(()); - }; if let Some(mpegts) = self.catalog.modify()?.ext.mpegts_mut() { let program = mpegts.program.get_or_insert_with(Default::default); - program.transport_stream_id = pat.transport_stream_id; + program.transport_stream_id = transport_stream_id; program.program_number = entry.program_num; program.pmt_pid = entry.program_map_pid.as_u16(); } @@ -850,8 +904,9 @@ impl Import { for pid in pids { self.flush(pid)?; } - for stream in self.streams.values_mut() { - stream.finish()?; + for (pid, stream) in &mut self.streams { + let units = stream.finish()?; + self.liveness.delivered(pid.as_u16(), units); } for section in self.sections.values_mut() { section.finish()?; @@ -860,21 +915,27 @@ impl Import { Ok(()) } - /// Snapshot the audio frame sync this importer has lost or could not verify. + /// Snapshot what every elementary stream has delivered, and the audio frame sync lost on + /// the way. /// /// Cheap: it reads counters the demuxer already keeps, so a caller can poll it per /// chunk and report the delta. pub fn stats(&self) -> Stats { let mut streams = self.retired_stats.clone(); - for (pid, stream) in &self.streams { - let Some(current) = stream.stats() else { - continue; - }; + let routes = self + .streams + .iter() + .filter_map(|(pid, stream)| Some((pid.as_u16(), stream.stats()?))) + .chain(self.sections.keys().map(|&pid| (pid, StreamStats::new(".ts")))); + for (pid, current) in routes { streams - .entry(pid.as_u16()) + .entry(pid) .and_modify(|retired| retired.merge(¤t)) .or_insert(current); } + for (pid, stats) in &mut streams { + (stats.units, stats.quiet) = self.liveness.stream(*pid); + } Stats { streams } } @@ -896,33 +957,60 @@ impl Import { } } -/// Frame sync the demuxed audio streams lost or could not verify, keyed by elementary -/// stream PID. +/// A PAT listed more than one program, and the [`Import`] was not told which one to take. +/// +/// Importing them all onto one broadcast would put unrelated clocks on one timeline, so the +/// import stops instead. Pick one with [`Import::with_program`], or import each as its own +/// broadcast with [`Programs`](super::Programs). +#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)] +#[error("transport stream carries {} programs ({})", .programs.len(), list_programs(.programs))] +pub struct MultipleProgramsError { + /// The program numbers the PAT lists, in PAT order. + pub programs: Vec, +} + +fn list_programs(programs: &[u16]) -> String { + programs.iter().map(u16::to_string).collect::>().join(", ") +} + +/// What each demuxed elementary stream delivered, and the audio frame sync it lost or could +/// not verify, keyed by elementary stream PID. /// /// Snapshot it with [`Import::stats`]. Every count is cumulative for the life of the /// importer, so what an operator alarms on is the rate: a feed that resyncs once an hour is -/// healthy, one that resyncs every second is losing audio. +/// healthy, one that resyncs every second is losing audio, and one whose access units stop +/// advancing while the mux keeps flowing has lost that stream. #[derive(Clone, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub struct Stats { - /// Counters per elementary stream PID, ordered by PID. A PID that has never lost frame - /// sync is absent, so an empty map means nothing has been lost. + /// One row per elementary stream PID the importer carries, ordered by PID. A PID the + /// importer drops (an undecoded stream without the `mpegts` catalog section) has none. pub streams: BTreeMap, } impl Stats { - /// Whether no stream has lost frame sync. + /// Whether no elementary stream has been registered yet. pub fn is_empty(&self) -> bool { self.streams.is_empty() } } -/// What one elementary stream lost or could not verify. See [`Stats`]. +/// What one elementary stream delivered, lost, or could not verify. See [`Stats`]. #[derive(Clone, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub struct StreamStats { - /// The current or most recent MoQ track suffix for this PID (`.mp2`, `.ac3`, `.aac`, ...). + /// The current or most recent MoQ track suffix for this PID (`.avc3`, `.mp2`, `.ts`, ...), + /// or empty for MPEG-1/2 video, which is read for its clock and not published. pub track: &'static str, + /// Access units the stream delivered: frames published for decoded media, PES payloads or + /// sections carried verbatim, and PES read on MPEG-1/2 video. + pub units: u64, + /// Transport time since the stream last delivered an access unit, or since the PMT + /// declared it, measured on the program clock (PCR). `None` until the first PCR arrives. + /// + /// No threshold applies: a sparse stream such as SCTE-35 is legitimately quiet for + /// seconds, so how long is too long is for whoever alarms to decide. + pub quiet: Option, /// Completed resyncs: the stream lost frame sync and locked onto a confirmed frame /// again. Each one is a gap in the audio. pub resyncs: u64, @@ -937,7 +1025,15 @@ pub struct StreamStats { } impl StreamStats { - /// Add a newer route's counters while naming the route that is active now. + fn new(track: &'static str) -> Self { + Self { + track, + ..Default::default() + } + } + + /// Add a newer route's frame-sync counters while naming the route that is active now. + /// Delivery is kept per PID rather than per route, so it needs no merging. fn merge(&mut self, current: &Self) { self.track = current.track; self.resyncs += current.resyncs; @@ -1098,13 +1194,13 @@ impl SectionStream { }) } - /// Consume one 188-byte TS packet, publishing each completed section. `pts` is - /// the current media clock used to timestamp a section (its arrival on the + /// Consume one 188-byte TS packet, publishing each completed section and returning how + /// many. `pts` is the current media clock used to timestamp a section (its arrival on the /// timeline; the splice time itself is inside the section bytes), if one is running. - fn packet(&mut self, pkt: &[u8], pts: Option) -> anyhow::Result { + fn packet(&mut self, pkt: &[u8], pts: Option) -> anyhow::Result { let mut sections = Vec::new(); self.reassembler.push(pkt, &mut sections); - let published = !sections.is_empty(); + let published = sections.len() as u64; for section in sections { self.emit(section, pts)?; } @@ -1197,7 +1293,7 @@ impl VerbatimStream { /// Publish one reassembled PES payload verbatim, in its own group, stamped with /// its PTS (or the live edge when the PES carried none). - fn write(&mut self, pending: Pending) -> anyhow::Result { + fn write(&mut self, pending: Pending) -> anyhow::Result { // Record the original PES stream_id once, from the first PES, so export // re-emits the stream under its real id (e.g. 0xBD for teletext/DVB AC-3). if !self.stream_id_recorded { @@ -1223,7 +1319,7 @@ impl VerbatimStream { }; self.track.write(frame)?; self.track.cut(None)?; - Ok(true) + Ok(1) } fn discontinuity(&mut self, published: bool) -> anyhow::Result<()> { @@ -1375,6 +1471,73 @@ impl Continuity { } } +/// How long each elementary stream has gone without delivering an access unit. +/// +/// Measured on the program clock, the PCR summed interval by interval, so it runs straight +/// through the 33-bit wrap, a signalled time-base reset and a corrupt PCR instead of jumping +/// with them. Not the media clock: that follows the video PTS, and stops with the very stream +/// this catches. +#[derive(Default)] +struct Liveness { + /// The last PCR in 27 MHz ticks, forgotten at a reset so no interval spans one. + pcr: Option, + /// PCR ticks elapsed since the first PCR, if one has arrived. + elapsed: Option, + /// Per PID: access units delivered, and `elapsed` at the last one, or at registration. + /// Kept per PID rather than per route, so a PMT remap carries it like `retired_stats`. + streams: HashMap, +} + +impl Liveness { + /// A PCR arrived on the program's clock PID. + fn pcr(&mut self, pcr: u64) { + let elapsed = self.elapsed.get_or_insert(0); + if let Some(last) = self.pcr.replace(pcr) { + let step = (pcr + super::mux_rate::PCR_WRAP - last) % super::mux_rate::PCR_WRAP; + // Stepped one interval at a time, so a corrupt PCR, or the clock stepping back + // without a flag, costs one interval rather than inventing hours of silence on + // every PID. The bound is the mux-rate meter's. + if step <= super::mux_rate::MAX_INTERVAL { + *elapsed += step; + } + } + } + + /// The clock restarted or changed PID: the next interval measures nothing. + fn discontinuity(&mut self) { + self.pcr = None; + } + + /// The PMT declared `pid`. Its silence counts from here until it delivers. + fn register(&mut self, pid: u16) { + let now = self.elapsed.unwrap_or(0); + self.streams.entry(pid).or_insert((0, now)); + } + + /// `pid` delivered `units` access units just now. + fn delivered(&mut self, pid: u16, units: u64) { + if units == 0 { + return; + } + let now = self.elapsed.unwrap_or(0); + if let Some((count, last)) = self.streams.get_mut(&pid) { + *count += units; + *last = now; + } + } + + /// `pid`'s access units and how long it has been quiet. See [`StreamStats`]. + fn stream(&self, pid: u16) -> (u64, Option) { + let Some(&(units, last)) = self.streams.get(&pid) else { + return (0, None); + }; + let quiet = self + .elapsed + .map(|now| std::time::Duration::from_nanos((now - last) * 1_000 / 27)); + (units, quiet) + } +} + /// Byte-level reassembler for MPEG-TS private sections on one PID. /// /// Private sections (SCTE-35 table_id 0xFC and others) are not PES. This handles @@ -1521,7 +1684,8 @@ enum Stream { } impl Stream { - fn write(&mut self, pending: Pending, batched: bool) -> anyhow::Result { + /// Route one reassembled PES, returning how many access units it published. + fn write(&mut self, pending: Pending, batched: bool) -> anyhow::Result { match self { Stream::H264 { split, import, unwrap } => { let reorder = reorder_delay(pending.pts, pending.dts); @@ -1529,9 +1693,9 @@ impl Stream { // Each PES is one access unit, so flush to emit it immediately. let mut frames = split.decode(&pending.data, pts)?; frames.extend(split.flush(pts)?); - let mut published = false; + let mut published = 0; for frame in frames { - published |= skip_missing_keyframe(import.decode([frame]))?; + published += u64::from(skip_missing_keyframe(import.decode([frame]))?); } // After decode, so the track (and its catalog rendition) exists. if let Some(reorder) = reorder { @@ -1545,9 +1709,9 @@ impl Stream { // Each PES is one access unit, so flush to emit it immediately. let mut frames = split.decode(&pending.data, pts)?; frames.extend(split.flush(pts)?); - let mut published = false; + let mut published = 0; for frame in frames { - published |= skip_missing_keyframe(import.decode([frame]))?; + published += u64::from(skip_missing_keyframe(import.decode([frame]))?); } if let Some(reorder) = reorder { import.observe_reorder(reorder)?; @@ -1558,7 +1722,7 @@ impl Stream { Stream::Opus(stream) => stream.write(pending), Stream::Legacy(stream) => stream.write(pending), Stream::Verbatim(stream) => stream.write(pending), - Stream::Clock | Stream::Ignored => Ok(false), + Stream::Clock | Stream::Ignored => Ok(0), } } @@ -1652,16 +1816,19 @@ impl Stream { } } - fn finish(&mut self) -> anyhow::Result<()> { + /// Finish the track, returning the access units a drained tail published. + fn finish(&mut self) -> anyhow::Result { match self { - Stream::H264 { import, .. } => Ok(import.finish()?), - Stream::H265 { import, .. } => Ok(import.finish()?), - Stream::Aac(stream) => stream.finish(), - Stream::Opus(stream) => stream.finish(), - Stream::Legacy(stream) => stream.finish(), - Stream::Verbatim(stream) => stream.finish(), - Stream::Clock | Stream::Ignored => Ok(()), + // Only the self-describing audio holds a frame back for a successor to confirm. + Stream::Aac(stream) => return stream.finish(), + Stream::Legacy(stream) => return stream.finish(), + Stream::H264 { import, .. } => import.finish()?, + Stream::H265 { import, .. } => import.finish()?, + Stream::Opus(stream) => stream.finish()?, + Stream::Verbatim(stream) => stream.finish()?, + Stream::Clock | Stream::Ignored => {} } + Ok(0) } fn abort(self, err: moq_net::Error) { @@ -1676,22 +1843,19 @@ impl Stream { } } - /// Frame sync this stream has lost, or `None` when it has lost none (or scans for none: - /// only the self-describing audio codecs do). + /// This route's track and the frame sync it has lost (only the self-describing audio + /// codecs scan for it), or `None` for a PID that is dropped rather than carried. fn stats(&self) -> Option { - let stats = match self { + Some(match self { Stream::Aac(stream) => stream.resync.stats(), Stream::Legacy(stream) => stream.resync.stats(), - Stream::H264 { .. } - | Stream::H265 { .. } - | Stream::Opus(_) - | Stream::Verbatim(_) - | Stream::Clock - | Stream::Ignored => return None, - }; - // A healthy stream reports nothing, so an empty snapshot means an intact feed. - let lost = stats.resyncs > 0 || stats.discarded > 0 || stats.unconfirmed > 0; - lost.then_some(stats) + Stream::H264 { .. } => StreamStats::new(".avc3"), + Stream::H265 { .. } => StreamStats::new(".hev1"), + Stream::Opus(_) => StreamStats::new(".opus"), + Stream::Verbatim(_) => StreamStats::new(".ts"), + Stream::Clock => StreamStats::new(""), + Stream::Ignored => return None, + }) } /// The MoQ track name of a decoded media stream, once its (lazily created) track @@ -1761,10 +1925,7 @@ impl Resync { // count from it for the life of the broadcast. unconfirmed: true, draining: false, - stats: StreamStats { - track, - ..Default::default() - }, + stats: StreamStats::new(track), } } @@ -1954,7 +2115,7 @@ struct AacStream { } impl AacStream { - fn write(&mut self, pending: Pending, batched: bool) -> anyhow::Result { + fn write(&mut self, pending: Pending, batched: bool) -> anyhow::Result { let pes_base = unwrap_pts(&mut self.unwrap, pending.pts)?; // Prepend the partial frame left by the previous PES, if any. @@ -1976,6 +2137,7 @@ impl AacStream { // A single PES can carry several ADTS frames; split and feed each raw frame. let mut burst = std::time::Duration::ZERO; + let mut published = 0; let mut offset = 0; // Earliest candidate passed over for declaring a frame longer than the buffer holds, // carried only if nothing later in the buffer confirms. @@ -2077,36 +2239,41 @@ impl AacStream { } }; + let mut block = &data[offset + header.header_len..end]; let import = match &mut self.import { Some(import) => import, None => { - let config = aac::Config { - profile: header.object_type, - sample_rate: header.sample_rate, - channel_count: header.channel_count, - }; + // Synthesize the AudioSpecificConfig `description` so out-of-band consumers + // (fMP4/MKV export, WebCodecs) can configure the decoder. A channel_config of 0 + // moves the program config element out of this first frame into it, as + // ffmpeg's aac_adtstoasc does; the TS export puts it back. + let asc = aac::in_band_config( + header.object_type, + header.sample_rate, + header.channel_config, + &mut block, + )?; + let mut config = aac::config(&asc)?; + config.container = self.container.clone(); // Consume the reservation held since the PMT: this resolves the gated rendition, // and carries the catalog's declared media retention onto the track. - // The importer synthesizes the AudioSpecificConfig `description` from the config so - // out-of-band consumers (fMP4/MKV export, WebCodecs) can configure the decoder. let reserved = self.reserved.take().expect("aac reservation already consumed"); let track = self .broadcast .unique_track(".aac", reserved.track_info(hang::catalog::PRIORITY.audio))?; - let mut config: hang::catalog::AudioConfig = config.into(); - config.container = self.container.clone(); let aac = aac::Import::new(track, reserved, config)?; self.import.insert(aac) } }; - import.decode(&data[offset + header.header_len..end], pts)?; + import.decode(block, pts)?; // Count only completed frames; input gaps and unfinished tails are not a media burst. burst += std::time::Duration::from_nanos((1024_u64 * 1_000_000_000).div_ceil(header.sample_rate as u64)); // The importer accumulates; cut each ADTS frame into its own group (one QUIC stream) // so the relay forwards it without waiting for the next. import.cut(None)?; self.resync.published(unvouched); + published += 1; // Offsets behind the published frame are spent; carrying one would republish it. fallback = None; @@ -2130,7 +2297,7 @@ impl AacStream { self.tail_pts = pts; } - Ok(!burst.is_zero()) + Ok(published) } fn discontinuity(&mut self, published: bool) -> anyhow::Result<()> { @@ -2160,17 +2327,18 @@ impl AacStream { self.resync.desynced(); } - fn finish(&mut self) -> anyhow::Result<()> { + fn finish(&mut self) -> anyhow::Result { // Drain a frame held only for want of a successor to confirm it: at end of stream // that successor is never coming. Only once this stream has published a frame, // though. Before that nothing has vouched for any boundary, so accepting one here // would hand a capture that joined mid-frame and ended immediately the same false // frame that starting unconfirmed exists to reject, and build the track's config out // of it. + let mut drained = 0; if !self.tail.is_empty() && self.import.is_some() { self.resync.drain(); // No PTS to translate, so no mapping needed. - self.write(Pending::empty(), true)?; + drained = self.write(Pending::empty(), true)?; } // A partial frame at end of stream isn't emissible; drop it, but leave a trace for // diagnosing truncated captures. @@ -2186,7 +2354,7 @@ impl AacStream { if let Some(import) = &mut self.import { import.finish()?; } - Ok(()) + Ok(drained) } fn abort(mut self, err: moq_net::Error) { @@ -2205,11 +2373,12 @@ struct OpusStream { } impl OpusStream { - fn write(&mut self, pending: Pending) -> anyhow::Result { + fn write(&mut self, pending: Pending) -> anyhow::Result { let base = unwrap_pts(&mut self.unwrap, pending.pts)?; let data = &pending.data; let mut offset = 0; + let mut published = 0; // 48 kHz samples elapsed since this PES's PTS, advancing each packet after the first. let mut elapsed: u64 = 0; while offset < data.len() { @@ -2237,8 +2406,9 @@ impl OpusStream { // doesn't stall the timeline for the rest of the PES. elapsed += opus::packet_samples(packet).unwrap_or(960) as u64; offset = end; + published += 1; } - Ok(offset > 0) + Ok(published) } fn discontinuity(&mut self, published: bool) -> anyhow::Result<()> { @@ -2272,14 +2442,15 @@ fn registration_format(descriptors: &[mpeg2ts::ts::Descriptor]) -> Option<[u8; 4 .and_then(|s| s.try_into().ok()) } -/// The Opus channel count from the DVB extension descriptor (tag 0x7f, ext tag 0x80). +/// The OpusHead implied by the DVB extension descriptor (tag 0x7f, ext tag 0x80). /// /// `channel_config_code` follows the Opus-in-TS mapping (and ffmpeg's demuxer): 0 is dual -/// mono (decoded as stereo), 1..=8 is the channel count directly. Higher codes (0x81 -/// explicitly-coded layouts, reserved values) aren't supported, so they fall back to the -/// caller's default rather than being read as a raw 129..=255 count. -fn opus_channel_count(descriptors: &[mpeg2ts::ts::Descriptor]) -> Option { - descriptors +/// mono (decoded as stereo), 1..=8 is the channel count directly, with family 0 for mono and +/// stereo and the Vorbis family 1 mapping above that. Higher codes (0x81 explicitly-coded +/// layouts, reserved values) aren't supported, so they fall back to stereo rather than being +/// read as a raw 129..=255 count. +fn opus_config(descriptors: &[mpeg2ts::ts::Descriptor]) -> crate::Result { + let channels = descriptors .iter() .find(|d| d.tag == 0x7f && d.data.first() == Some(&0x80)) .and_then(|d| d.data.get(1)) @@ -2288,6 +2459,15 @@ fn opus_channel_count(descriptors: &[mpeg2ts::ts::Descriptor]) -> Option { 1..=8 => Some(cc as u32), _ => None, }) + .unwrap_or(2); + + let mut config = opus::Config::new(48_000, channels); + if channels > 2 { + let mapping = opus::Mapping::vorbis(channels as u8)?; + config.mapping_family = mapping.family(); + config.mapping = Some(mapping); + } + Ok(config) } /// Parse one Opus-in-TS access-unit control header, returning `(header_len, payload_size)`. @@ -2357,8 +2537,8 @@ struct LegacyStream { } impl LegacyStream { - fn write(&mut self, pending: Pending) -> anyhow::Result { - let mut published = false; + fn write(&mut self, pending: Pending) -> anyhow::Result { + let mut published = 0; let pes_base = unwrap_pts(&mut self.unwrap, pending.pts)?; // Prepend the partial frame left by the previous PES, if any. @@ -2519,7 +2699,7 @@ impl LegacyStream { // so the relay forwards it without waiting for the next. import.cut(None)?; self.resync.published(unvouched); - published = true; + published += 1; // Offsets behind the published frame are spent; carrying one would republish it. fallback = None; @@ -2566,17 +2746,18 @@ impl LegacyStream { self.resync.desynced(); } - fn finish(&mut self) -> anyhow::Result<()> { + fn finish(&mut self) -> anyhow::Result { // Drain a frame held only for want of a successor to confirm it: at end of stream // that successor is never coming. Only once this stream has published a frame, // though. Before that nothing has vouched for any boundary, so accepting one here // would hand a capture that joined mid-frame and ended immediately the same false // frame that starting unconfirmed exists to reject, and build the track's config out // of it. + let mut drained = 0; if !self.tail.is_empty() && self.import.is_some() { self.resync.drain(); // No PTS to translate, so no mapping needed. - self.write(Pending::empty())?; + drained = self.write(Pending::empty())?; } // A partial frame at end of stream isn't emissible verbatim; drop it, but // leave a trace for diagnosing truncated captures. @@ -2596,7 +2777,7 @@ impl LegacyStream { if let Some(import) = &mut self.import { import.finish()?; } - Ok(()) + Ok(drained) } fn abort(mut self, err: moq_net::Error) { @@ -2732,7 +2913,7 @@ impl Read for Feed { } #[cfg(test)] -mod test { +pub(super) mod test { use std::collections::BTreeMap; use std::time::Duration; @@ -2769,6 +2950,29 @@ mod test { assert_eq!(stats.resyncs, 0, "the stream has not regained sync yet"); } + #[test] + fn liveness_steps_over_a_corrupt_pcr_and_the_wrap() { + const MS: u64 = 27_000; + let mut liveness = super::Liveness::default(); + liveness.register(0x100); + let mut pcr = super::super::mux_rate::PCR_WRAP - 100 * MS; + for _ in 0..10 { + liveness.pcr(pcr); + pcr = (pcr + 40 * MS) % super::super::mux_rate::PCR_WRAP; + } + assert_eq!(liveness.stream(0x100), (0, Some(Duration::from_millis(360)))); + + // A PCR hours ahead, then the clock carrying on where it was: neither step counts. + liveness.pcr(pcr + 23_861_000 * MS); + liveness.pcr(pcr); + assert_eq!(liveness.stream(0x100).1, Some(Duration::from_millis(360))); + + liveness.pcr(pcr + 40 * MS); + liveness.delivered(0x100, 3); + liveness.pcr(pcr + 80 * MS); + assert_eq!(liveness.stream(0x100), (3, Some(Duration::from_millis(40)))); + } + #[test] fn resync_does_not_count_an_unvouched_eof_publication() { let mut resync = super::Resync::new(0x61, ".mp2"); @@ -2985,23 +3189,34 @@ mod test { /// /// The clock rides the first elementary stream, as a real mux puts it on the video. fn synth_pmt(es: &[(StreamType, u16)], cuei: bool) -> Vec { + synth_programs(&[(1, 0x0100, es)], cuei) + } + + /// A program to synthesize: `(program_num, pmt_pid, [(stream_type, pid)])`. + type SynthProgram<'a> = (u16, u16, &'a [(StreamType, u16)]); + + /// Serialize one PAT listing every program, then each program's PMT, as [`synth_pmt`] + /// does for one. + fn synth_programs(programs: &[SynthProgram], cuei: bool) -> Vec { use mpeg2ts::ts::payload::{Pat, Pmt}; use mpeg2ts::ts::{ ContinuityCounter, Descriptor, EsInfo, Pid, ProgramAssociation, TransportScramblingControl, TsHeader, TsPacket, TsPacketWriter, TsPayload, VersionNumber, WriteTsPacket, }; - const PMT_PID: u16 = 0x0100; let pat = Pat { transport_stream_id: 1, version_number: VersionNumber::default(), - table: vec![ProgramAssociation { - program_num: 1, - program_map_pid: Pid::new(PMT_PID).unwrap(), - }], + table: programs + .iter() + .map(|&(program_num, pmt_pid, _)| ProgramAssociation { + program_num, + program_map_pid: Pid::new(pmt_pid).unwrap(), + }) + .collect(), }; - let pmt = Pmt { - program_num: 1, + let pmt = |program_num: u16, es: &[(StreamType, u16)]| Pmt { + program_num, pcr_pid: es.first().map(|&(_, pid)| Pid::new(pid).unwrap()), version_number: VersionNumber::default(), program_info: if cuei { @@ -3039,7 +3254,9 @@ mod test { let mut out = Vec::new(); write(&mut out, Pid::PAT, TsPayload::Pat(pat)); - write(&mut out, PMT_PID, TsPayload::Pmt(pmt)); + for &(program_num, pmt_pid, es) in programs { + write(&mut out, pmt_pid, TsPayload::Pmt(pmt(program_num, es))); + } out } @@ -3853,6 +4070,8 @@ mod test { AAC_PID, super::StreamStats { track: ".aac", + units: 4, + quiet: None, resyncs: 1, discarded: 47, unconfirmed: 0, @@ -4044,6 +4263,8 @@ mod test { MP2_PID, super::StreamStats { track: ".mp2", + units: 4, + quiet: None, resyncs: 1, discarded: 72, unconfirmed: 0, @@ -4229,6 +4450,8 @@ mod test { MP2_PID, super::StreamStats { track: ".mp2", + units: 2, + quiet: None, resyncs: 0, discarded: 0, unconfirmed: 1, @@ -4990,6 +5213,88 @@ mod test { out } + /// A two-program multiplex whose clocks sit an hour apart: program 1's MP2 on + /// `0x0061` starts at 1 s, program 2's on `0x0071` at 3601 s. + pub(in crate::container::ts) fn two_programs() -> Vec { + let mut data = synth_programs( + &[ + (1, 0x0100, &[(StreamType::Mpeg1Audio, 0x0061)]), + (2, 0x0200, &[(StreamType::Mpeg1Audio, 0x0071)]), + ], + false, + ); + data.extend(mp2_pes(0x0061, 0, 90_000, [0xAA, 0xBB])); + data.extend(mp2_pes(0x0071, 0, 3_601 * 90_000, [0xCC, 0xDD])); + data + } + + #[test] + fn a_multi_program_input_is_refused_before_publishing() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()); + + let err = import.decode(&two_programs()).unwrap_err(); + assert_eq!( + err.downcast_ref::(), + Some(&super::MultipleProgramsError { programs: vec![1, 2] }), + "{err:#}" + ); + assert!(catalog.snapshot().audio.renditions.is_empty(), "nothing was published"); + } + + #[test] + fn a_program_added_mid_stream_ends_the_import() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()); + import + .decode(&synth_pmt(&[(StreamType::Mpeg1Audio, 0x0061)], false)) + .unwrap(); + import.decode(&mp2_pes(0x0061, 0, 90_000, [0xAA, 0xBB])).unwrap(); + + let err = import.decode(&two_programs()).unwrap_err(); + assert!(err.downcast_ref::().is_some(), "{err:#}"); + assert_eq!( + catalog.snapshot().audio.renditions.len(), + 1, + "program 1 stays published" + ); + } + + #[tokio::test(start_paused = true)] + async fn a_selected_program_publishes_only_its_streams_on_its_clock() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()).with_program(2); + import.decode(&two_programs()).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let names: Vec<_> = snapshot.audio.renditions.keys().collect(); + assert_eq!(names.len(), 1, "only program 2's stream: {names:?}"); + let (frames, _) = read_breaks(&consumer, names[0]).await; + assert!(!frames.is_empty(), "program 2 published"); + assert!( + frames + .iter() + .all(|frame| frame.payload[4] == 0xCC || frame.payload[4] == 0xDD), + "no program 1 frame leaks in" + ); + assert_eq!(frames[0].timestamp.as_micros(), 3_601_000_000, "program 2's own PTS"); + } + + #[test] + fn a_selected_program_the_pat_does_not_list_is_refused() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()).with_program(3); + + let err = import.decode(&two_programs()).unwrap_err().to_string(); + assert!(err.contains("no program 3") && err.contains("1, 2"), "{err}"); + } + /// Two MP2 renditions, the first of which the PMT designates as the PCR PID. const PCR_PID: u16 = 0x0061; const PEER_PID: u16 = 0x0062; diff --git a/rs/moq-mux/src/container/ts/import_test.rs b/rs/moq-mux/src/container/ts/import_test.rs index 0814f2be15b..5d47ba5e138 100644 --- a/rs/moq-mux/src/container/ts/import_test.rs +++ b/rs/moq-mux/src/container/ts/import_test.rs @@ -156,6 +156,32 @@ fn import_ac3_catalog() { assert!(audio.description.is_none(), "verbatim AC-3 needs no description"); } +/// `aac_quad.ts` is an ffmpeg-authored audio-only AAC program in quad, which has no +/// channelConfiguration, so its ADTS headers carry 0 and the first raw data block leads with a +/// program config element. Regenerated with (ffmpeg 9.0.1): +/// `ffmpeg -f lavfi -i sine=frequency=440:sample_rate=48000:duration=0.1 +/// -af "pan=quad|FL=c0|FR=c0|BL=c0|BR=c0" -c:a aac -b:a 128k -f mpegts aac_quad.ts`. +#[test] +fn import_aac_program_config_catalog() { + let data = include_bytes!("test_data/aac_quad.ts"); + let catalog = import_ts(data); + + assert_eq!(catalog.audio.renditions.len(), 1, "expected one AAC track"); + let audio = catalog.audio.renditions.values().next().unwrap(); + assert_eq!(audio.codec.to_string(), "mp4a.40.2"); + assert_eq!(audio.sample_rate, 48_000); + assert_eq!( + audio.channel_count, 4, + "two channel pair elements, not a guessed stereo" + ); + + // The element moved into the description is byte-for-byte what ffmpeg itself writes as the + // AudioSpecificConfig for the same stream in MP4, minus the trailing SBR sync extension. + let mut expected = vec![0x11, 0x80, 0x04, 0xC4, 0x04, 0x00, 0x21, 0x10, 0x0C]; + expected.extend_from_slice(b"Lavc63.1.101"); + assert_eq!(audio.description.as_deref(), Some(expected.as_slice())); +} + /// `opus.ts` is an ffmpeg-authored audio-only Opus program (private stream_type 0x06 /// plus the 'Opus' registration and DVB extension descriptors), generated with: /// `ffmpeg -f lavfi -i sine=frequency=440:sample_rate=48000:duration=0.5 @@ -174,6 +200,29 @@ fn import_opus_catalog() { assert_eq!(audio.channel_count, 2); } +/// `opus_5_1.ts` is a 440 Hz center channel in 5.1, which ffmpeg's libopus +/// encodes as family 1 and its muxer labels `channel_config_code` 6: +/// `ffmpeg -f lavfi -i sine=frequency=440:sample_rate=48000:duration=0.5 +/// -ac 6 -c:a libopus -b:a 128k -f mpegts opus_5_1.ts`. The descriptor names only +/// the channel count, so the importer must synthesize the Vorbis mapping table +/// or the track has no OpusHead a decoder accepts. +#[test] +fn import_opus_surround_catalog() { + let data = include_bytes!("test_data/opus_5_1.ts"); + let catalog = import_ts(data); + + assert_eq!(catalog.audio.renditions.len(), 1, "expected one Opus track"); + let audio = catalog.audio.renditions.values().next().unwrap(); + assert_eq!(audio.channel_count, 6); + + let head = crate::codec::opus::Config::parse(&mut audio.description.as_deref().expect("an OpusHead")).unwrap(); + assert_eq!(head.channel_count, 6); + let mapping = head.mapping.expect("a family 1 mapping"); + assert_eq!(mapping.family(), 1); + assert_eq!((mapping.streams(), mapping.coupled()), (4, 2)); + assert_eq!(mapping.table(), &[0, 4, 1, 2, 3, 5]); +} + /// Opus frames from real ffmpeg output must decode: a non-empty run of Opus packets, /// each a plausible size (the control header was stripped, not left in the payload). #[tokio::test(start_paused = true)] @@ -663,3 +712,232 @@ async fn import_publishes_stream_pts_on_an_arrival_clock() { "the stream is live on arrival" ); } + +/// The PCR a packet's adaptation field carries, in 27 MHz ticks. +fn pcr(pkt: &[u8]) -> Option { + if pkt[3] & 0x20 == 0 || pkt[4] < 7 || pkt[5] & 0x10 == 0 { + return None; + } + let base = (u64::from(pkt[6]) << 25) + | (u64::from(pkt[7]) << 17) + | (u64::from(pkt[8]) << 9) + | (u64::from(pkt[9]) << 1) + | (u64::from(pkt[10]) >> 7); + Some(base * 300 + ((u64::from(pkt[10] & 0x01) << 8) | u64::from(pkt[11]))) +} + +fn packet_pid(pkt: &[u8]) -> u16 { + (u16::from(pkt[1] & 0x1f) << 8) | u16::from(pkt[2]) +} + +/// Each packet of `ts` with the program clock it arrives at, counted from the first PCR. +fn timed(ts: &[u8]) -> impl Iterator { + let mut first = None; + let mut now = std::time::Duration::ZERO; + ts.as_chunks::<188>().0.iter().map(move |pkt| { + if let Some(pcr) = pcr(pkt) { + let first = *first.get_or_insert(pcr); + now = std::time::Duration::from_nanos((pcr - first) * 1_000 / 27); + } + (now, pkt) + }) +} + +/// `ts` with the PES on `pid` suppressed from its first PES start at or after `from` to its +/// first at or after `to`, as an encoder whose one input died behind a running mux emits it. +/// +/// A suppressed packet that carried the PCR keeps it in an adaptation-only packet, every +/// other one becomes null stuffing so the mux rate holds, and the counters after the gap are +/// renumbered so continuity stays legal. +fn suppress(ts: &[u8], pid: u16, from: std::time::Duration, to: std::time::Duration) -> Vec { + let mut null = [0xff; 188]; + null[..4].copy_from_slice(&[0x47, 0x1f, 0xff, 0x10]); + + let mut out = Vec::with_capacity(ts.len()); + let (mut active, mut done) = (false, false); + let (mut last_cc, mut dropped) = (0, 0u8); + for (now, pkt) in timed(ts) { + let mut pkt = *pkt; + if packet_pid(&pkt) == pid { + if pkt[1] & 0x40 != 0 { + if !active && !done && now >= from { + active = true; + } else if active && now >= to { + (active, done) = (false, true); + } + } + let payload = pkt[3] & 0x10 != 0; + if active { + dropped = (dropped + u8::from(payload)) & 0x0f; + pkt = match pcr(&pkt) { + Some(_) => { + let mut clock = [0xff; 188]; + clock[..6].copy_from_slice(&[0x47, pkt[1] & 0x1f, pkt[2], 0x20 | last_cc, 183, 0x10]); + clock[6..12].copy_from_slice(&pkt[6..12]); + clock + } + None => null, + }; + } else { + pkt[3] = (pkt[3] & 0xf0) | (pkt[3].wrapping_sub(dropped) & 0x0f); + if payload { + last_cc = pkt[3] & 0x0f; + } + } + } + out.extend_from_slice(&pkt); + } + assert!(done, "the fixture must resume the PID before it ends"); + out +} + +/// What #3489 measured before MoQ saw the stimulus: the same packets and PCRs as `ts`, and +/// not one continuity error the fixture didn't already have. +fn assert_legal(ts: &[u8], stimulus: &[u8]) { + assert_eq!(ts.len(), stimulus.len(), "the mux rate moved"); + let clocks = |ts: &[u8]| { + ts.as_chunks::<188>() + .0 + .iter() + .filter_map(|pkt| pcr(pkt)) + .collect::>() + }; + assert_eq!(clocks(ts), clocks(stimulus), "a PCR went missing"); + let errors = |ts: &[u8]| { + let mut last = std::collections::HashMap::new(); + let mut errors = std::collections::BTreeMap::::new(); + for pkt in ts.as_chunks::<188>().0 { + let pid = packet_pid(pkt); + if pid == 0x1fff || pkt[3] & 0x10 == 0 { + continue; + } + let cc = pkt[3] & 0x0f; + if last.insert(pid, cc).is_some_and(|previous| cc != (previous + 1) & 0x0f) { + *errors.entry(pid).or_default() += 1; + } + } + errors + }; + assert_eq!(errors(ts), errors(stimulus), "the stimulus broke continuity"); +} + +/// Import `ts` with an `mpegts` catalog, snapshotting the stats once the program clock +/// reaches each of `at`, and once more at the end of the input. +fn sample(ts: &[u8], at: &[std::time::Duration]) -> Vec { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let _catalog = crate::catalog::Producer::new( + &mut broadcast, + crate::catalog::Config::default() + .with_catalog(crate::catalog::hang::Catalog::::default()), + ) + .unwrap(); + let mut import = crate::container::ts::Import::new(broadcast, _catalog.reserve()); + + let mut samples = Vec::new(); + let mut done = 0; + for &at in at { + let end = 188 + * timed(ts) + .position(|(now, _)| now >= at) + .expect("the fixture reaches it"); + import.decode(&ts[done..end]).unwrap(); + samples.push(import.stats()); + done = end; + } + import.decode(&ts[done..]).unwrap(); + samples.push(import.stats()); + samples +} + +/// #3489's stimulus: `pid` goes quiet between `from` and `to` while its PCR and continuity stay +/// legal. Its row stops counting and its silence grows with the program clock, where the +/// unmodified fixture keeps counting; `peer` keeps delivering throughout; and the row counts +/// again once the PID returns. +fn assert_stalls(fixture: &[u8], pid: u16, track: &str, peer: u16, from: f64, to: f64) { + use std::time::Duration; + + let stimulus = suppress(fixture, pid, Duration::from_secs_f64(from), Duration::from_secs_f64(to)); + assert_legal(fixture, &stimulus); + + let at = [Duration::from_secs_f64(from + 0.4), Duration::from_secs_f64(to - 0.2)]; + let control = sample(fixture, &at); + assert!( + control[1].streams[&pid].units > control[0].streams[&pid].units, + "the unmodified fixture delivers on {pid:#x} across the window" + ); + + let samples = sample(&stimulus, &at); + let [early, late, end] = [&samples[0], &samples[1], &samples[2]].map(|s| s.streams[&pid].clone()); + assert_eq!(early.track, track); + assert!(early.units > 0, "{pid:#x} delivered before it went quiet"); + assert_eq!(late.units, early.units, "{pid:#x} stopped counting"); + + let (early_quiet, late_quiet) = (early.quiet.unwrap(), late.quiet.unwrap()); + assert!( + early_quiet >= Duration::from_millis(350), + "{pid:#x} has been quiet since the window opened: {early_quiet:?}" + ); + let grew = late_quiet - early_quiet; + let elapsed = at[1] - at[0]; + assert!( + grew.abs_diff(elapsed) <= Duration::from_millis(50), + "the silence grows with the program clock: {grew:?} over {elapsed:?}" + ); + + let (peer_early, peer_late) = (&samples[0].streams[&peer], &samples[1].streams[&peer]); + assert!(peer_late.units > peer_early.units, "{peer:#x} kept delivering"); + assert!( + peer_late.quiet.unwrap() < Duration::from_millis(200), + "{peer:#x} is not quiet: {:?}", + peer_late.quiet + ); + + assert!(end.units > late.units, "{pid:#x} counts again once it returns"); + assert!(end.quiet.unwrap() < late_quiet, "{pid:#x} is no longer as quiet"); +} + +/// Video carrying the program's PCR, the layout #3489 measured: the suppressed PID still +/// drives the clock its own silence is measured on. +#[test] +fn import_reports_a_silent_video_pid() { + let data = include_bytes!("test_data/scte35/bbb5s.ts"); + assert_stalls(data, 0x100, ".hev1", 0x101, 1.5, 3.5); +} + +/// One of two MP2 programs goes quiet behind a dedicated PCR PID. +#[test] +fn import_reports_a_silent_audio_pid() { + let data = include_bytes!("test_data/scte35/kyrion_dirtystart.ts"); + assert_stalls(data, 0x101, ".mp2", 0x102, 1.5, 3.5); +} + +/// SCTE-35 is sparse, so its row reports the silence and leaves the verdict to the caller. +#[test] +fn import_reports_a_silent_scte35_pid() { + let data = include_bytes!("test_data/scte35/kyrion_dirtystart.ts"); + assert_stalls(data, 0x14d, ".ts", 0x100, 2.5, 3.5); +} + +/// Every elementary stream the importer carries reports a row, decoded, clock-only, and +/// verbatim alike, and every row has delivered. +#[test] +fn import_reports_every_elementary_stream() { + for (data, rows) in [ + ( + &include_bytes!("test_data/kyrion_mpeg2av_ac3.ts")[..], + &[(0x100, ""), (0x101, ".ac3"), (0x102, ".mp2"), (0x14d, ".ts")][..], + ), + ( + &include_bytes!("test_data/scte35/bbb5s.ts")[..], + &[(0x21, ".ts"), (0x100, ".hev1"), (0x101, ".opus")][..], + ), + ] { + let stats = sample(data, &[]).pop().unwrap(); + let tracks: Vec<(u16, &str)> = stats.streams.iter().map(|(&pid, s)| (pid, s.track)).collect(); + assert_eq!(tracks, rows); + for (pid, stream) in &stats.streams { + assert!(stream.units > 0, "{pid:#x} delivered nothing: {stream:?}"); + assert!(stream.quiet.is_some(), "{pid:#x} has no program clock: {stream:?}"); + } + } +} diff --git a/rs/moq-mux/src/container/ts/mod.rs b/rs/moq-mux/src/container/ts/mod.rs index 1a8b9e0a0e5..05858df90f1 100644 --- a/rs/moq-mux/src/container/ts/mod.rs +++ b/rs/moq-mux/src/container/ts/mod.rs @@ -22,6 +22,7 @@ mod adts; mod export; mod import; mod mux_rate; +mod programs; mod si; // The `mpegts` catalog section (per-track PID + descriptors plus verbatim carriage @@ -32,6 +33,9 @@ mod catalog; pub use catalog::{Catalog, Descriptor, Ext, Framing, Mpegts, Program, SiEntry, Track, Verbatim}; pub use export::*; pub use import::*; +pub use programs::Programs; + +pub mod stats; #[cfg(test)] mod export_test; diff --git a/rs/moq-mux/src/container/ts/mux_rate.rs b/rs/moq-mux/src/container/ts/mux_rate.rs index 59071f0e348..ec4298b0ff6 100644 --- a/rs/moq-mux/src/container/ts/mux_rate.rs +++ b/rs/moq-mux/src/container/ts/mux_rate.rs @@ -13,7 +13,7 @@ const PCR_HZ: u64 = 27_000_000; /// Bits per transport packet. const PACKET_BITS: u64 = 188 * 8; /// The 33-bit base times 300 plus the 9-bit extension: the PCR wraps here. -const PCR_WRAP: u64 = (1 << 33) * 300; +pub(super) const PCR_WRAP: u64 = (1 << 33) * 300; /// How much PCR time one window spans before it is judged. const WINDOW: u64 = 2 * PCR_HZ; /// Intervals are pooled into samples this long before they are compared. One @@ -23,7 +23,7 @@ const WINDOW: u64 = 2 * PCR_HZ; const SAMPLE: u64 = WINDOW / 4; /// A PCR interval longer than this is a gap or a wrap gone wrong, not a sample: /// TR 101 290 already flags anything over 100 ms. -const MAX_INTERVAL: u64 = PCR_HZ; +pub(super) const MAX_INTERVAL: u64 = PCR_HZ; /// How far one sample may sit from a rate and still agree with it, in thousandths. /// A hardware multiplexer's rate wanders more than a percent between half-second /// samples while its whole-window average holds far tighter; a VBR source is off by diff --git a/rs/moq-mux/src/container/ts/programs.rs b/rs/moq-mux/src/container/ts/programs.rs new file mode 100644 index 00000000000..5b2b21c9b82 --- /dev/null +++ b/rs/moq-mux/src/container/ts/programs.rs @@ -0,0 +1,231 @@ +//! Every program of a multiplex, each imported as its own broadcast. + +use anyhow::Context; +use mpeg2ts::ts::{ReadTsPacket, TsPacket, TsPacketReader, TsPayload}; + +use super::{Ext, Import, Stats}; +use crate::catalog; + +/// Imports every program the first PAT lists, each as its own broadcast on `origin`, with its +/// own clock and catalog. +/// +/// Program `n` of `event.hang` publishes on `event/n.hang`, keeping the catalog suffix last so +/// format detection still sees it; a name without one gains a plain `/n`. Input ahead of that +/// PAT is dropped, as a single [`Import`] drops media ahead of its PSI. A program a later PAT +/// adds is not published; one it removes ends the import. +pub struct Programs { + origin: moq_net::origin::Producer, + name: moq_net::PathOwned, + config: catalog::Config, + /// Input held until it contains a whole PAT. + pending: Vec, + /// Empty until the PAT arrives. + programs: Vec, +} + +/// One program's broadcast. +struct Program { + /// Keeps the origin-created broadcast alive; the importer's clone doesn't. + _broadcast: moq_net::broadcast::Producer, + import: Import, + catalog: catalog::Producer, +} + +impl Programs { + /// Split the multiplex into broadcasts named after `name`, each catalog built from `config`. + pub fn new(origin: moq_net::origin::Producer, name: impl moq_net::AsPath, config: catalog::Config) -> Self { + Self { + origin, + name: name.as_path().to_owned(), + config, + pending: Vec::new(), + programs: Vec::new(), + } + } + + /// Demux a chunk of the multiplex. A trailing partial packet is retained for the next call. + pub fn decode(&mut self, data: &[u8]) -> anyhow::Result<()> { + if !self.programs.is_empty() { + return self.feed(data); + } + self.pending.extend_from_slice(data); + let Some(programs) = pat_programs(&self.pending).filter(|programs| !programs.is_empty()) else { + // Only a packet's worth of tail can still hold the start of the PAT. + let keep = self.pending.len().saturating_sub(TsPacket::SIZE - 1); + self.pending.drain(..keep); + return Ok(()); + }; + for program in programs { + let name = program_broadcast(self.name.as_str(), program); + let mut broadcast = self + .origin + .create_broadcast(&name) + .with_context(|| format!("failed to create broadcast {name}"))?; + // TS carries undecoded elementary streams verbatim, so each catalog carries the + // `mpegts` extension, and owns its broadcast's catalog tracks. + let config = self + .config + .clone() + .with_catalog(catalog::hang::Catalog::::default()); + let catalog = catalog::Producer::new(&mut broadcast, config)?; + let import = Import::new(broadcast.clone(), catalog.reserve()).with_program(program); + broadcast + .announce(Default::default()) + .with_context(|| format!("failed to announce broadcast {name}"))?; + self.programs.push(Program { + _broadcast: broadcast, + import, + catalog, + }); + } + let pending = std::mem::take(&mut self.pending); + self.feed(&pending) + } + + fn feed(&mut self, data: &[u8]) -> anyhow::Result<()> { + for program in &mut self.programs { + program.import.decode(data)?; + } + Ok(()) + } + + /// Every program's counters in one map: PIDs are unique across a multiplex. + pub fn stats(&self) -> Stats { + let mut stats = Stats::default(); + for program in &self.programs { + stats.streams.extend(program.import.stats().streams); + } + stats + } + + /// Finish each program's tracks, then its catalog while it still lists them. + pub fn finish(&mut self) -> anyhow::Result<()> { + for program in &mut self.programs { + program.import.finish()?; + program.catalog.finish()?; + } + Ok(()) + } + + /// Abort every program's tracks with `err`, as [`Import::abort`] does. Consumes the importer. + pub fn abort(self, err: moq_net::Error) { + for program in self.programs { + program.import.abort(err.clone()); + } + } +} + +/// The broadcast one program of `name` publishes on: `event.hang` becomes `event/2.hang`. +fn program_broadcast(name: &str, program: u16) -> String { + match catalog::CatalogFormat::detect(name) { + Some(format) => { + let stem = &name[..name.len() - format.extension().len()]; + format!("{stem}/{program}{}", format.extension()) + } + None => format!("{name}/{program}"), + } +} + +/// The program numbers listed by the first whole PAT in `data`, in PAT order, or `None` if +/// there is none yet. +fn pat_programs(data: &[u8]) -> Option> { + let mut off = 0; + while let Some(rel) = memchr::memchr(0x47, &data[off..]) { + off += rel; + let packet = data.get(off..off + TsPacket::SIZE)?; + // PID 0 opening a section. The section CRC rejects a sync byte found in payload. + if packet[1] & 0x5f == 0x40 + && packet[2] == 0 + && let Ok(Some(TsPacket { + payload: Some(TsPayload::Pat(pat)), + .. + })) = TsPacketReader::new(packet).read_ts_packet() + { + return Some( + pat.table + .iter() + .map(|entry| entry.program_num) + .filter(|&program| program != 0) + .collect(), + ); + } + off += 1; + } + None +} + +#[cfg(test)] +mod test { + use std::time::Duration; + + use super::*; + use crate::catalog::hang::Container; + use crate::container::Consumer; + use crate::container::ts::import::test::two_programs; + + #[test] + fn program_broadcasts_keep_the_catalog_suffix_last() { + assert_eq!(program_broadcast("event.hang", 2), "event/2.hang"); + assert_eq!(program_broadcast("demo/event.msf", 7), "demo/event/7.msf"); + assert_eq!(program_broadcast("event", 1), "event/1"); + } + + #[test] + fn pat_programs_reads_the_first_whole_pat() { + let data = two_programs(); + assert_eq!(pat_programs(&data), Some(vec![1, 2])); + // A sync byte in leading junk is skipped; a truncated PAT is not a PAT yet. + let mut shifted = vec![0x47, 0x40, 0x00, 0x10]; + shifted.extend_from_slice(&data); + assert_eq!(pat_programs(&shifted), Some(vec![1, 2])); + assert_eq!(pat_programs(&data[..100]), None); + } + + /// The input is held until the PAT is whole, then each program publishes as its own + /// broadcast carrying only that program, its catalog clock anchored on its own first frame + /// apart on one shared clock. + #[tokio::test] + async fn every_program_publishes_its_own_broadcast() { + let origin = crate::source::produce_origin(); + let mut programs = Programs::new(origin.clone(), "event.hang", catalog::Config::default()); + + let input = two_programs(); + let before = std::time::SystemTime::now(); + programs.decode(&input[..100]).unwrap(); + assert!( + programs.programs.is_empty(), + "no program is known before the PAT is whole" + ); + programs.decode(&input[100..]).unwrap(); + programs.finish().unwrap(); + let after = std::time::SystemTime::now(); + + for (path, fills) in [("event/1.hang", [0xAA, 0xBB]), ("event/2.hang", [0xCC, 0xDD])] { + let consumer = crate::Source::new(origin.consume(), path).broadcast().await.unwrap(); + let catalog = hang::catalog::Catalog::<()>::subscribe(&consumer) + .await + .unwrap() + .next() + .await + .unwrap() + .expect("a catalog"); + let renditions: Vec<_> = catalog.audio.renditions.iter().collect(); + assert_eq!(renditions.len(), 1, "{path} carries its own program's one stream"); + let (name, config) = renditions[0]; + let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); + let container = Container::try_from(config).unwrap(); + let frame = Consumer::new(track, container).read().await.unwrap().expect("a frame"); + assert!(fills.contains(&frame.payload[4]), "{path} carries only its own program"); + let skew = Duration::from_secs(2); + let wall = catalog + .clock + .expect("the catalog advertises a clock") + .wall_clock(frame.timestamp) + .unwrap(); + assert!( + before - skew <= wall && wall <= after + skew, + "{path} is live on arrival: {wall:?} not in {before:?}..={after:?}" + ); + } + } +} diff --git a/rs/moq-mux/src/container/ts/stats.rs b/rs/moq-mux/src/container/ts/stats.rs new file mode 100644 index 00000000000..9853721168e --- /dev/null +++ b/rs/moq-mux/src/container/ts/stats.rs @@ -0,0 +1,159 @@ +//! Reporting on the per-stream counters [`Import::stats`](super::Import::stats) returns. + +use std::collections::BTreeSet; + +use super::{Stats, StreamStats}; + +/// Logs what moved in an importer's [`Stats`] from one sample to the next, so every front +/// door that runs a TS importer reports the same lines. +/// +/// Feed it a snapshot every [`INTERVAL`](Self::INTERVAL) of wall time. The caller owns the +/// timer, since what counts as "now" differs between a CLI, a server, and a test. +#[derive(Default)] +pub struct Log { + previous: Option, + /// Streams already reported quiet, so a silence is logged when it starts and not again + /// until the stream has delivered. + quiet: BTreeSet, +} + +impl Log { + /// How often to [`sample`](Self::sample). + /// + /// Long enough that every continuous stream delivers many access units in between, so a + /// count that did not move is a stream that stopped rather than one between frames. + pub const INTERVAL: std::time::Duration = std::time::Duration::from_secs(1); + + /// Compare a snapshot taken [`INTERVAL`](Self::INTERVAL) after the last. + /// + /// Logs a stream whose access units did not advance since the last sample, once per + /// silence, and any stream whose frame-sync counters moved. + pub fn sample(&mut self, latest: Stats) { + self.sync(&latest); + for (pid, stream) in &latest.streams { + let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); + if previous.is_none_or(|previous| previous.units != stream.units) { + self.quiet.remove(pid); + } else if self.quiet.insert(*pid) { + tracing::info!( + pid = *pid, + track = stream.track, + units = stream.units, + quiet = ?stream.quiet, + "elementary stream stopped delivering access units" + ); + } + } + self.previous = Some(latest); + } + + /// Compare the snapshot taken after [`Import::finish`](super::Import::finish). + /// + /// It covers less than an interval, so only the frame sync is compared: the drain at end + /// of input can publish a frame nothing vouched for. + pub fn finish(&self, latest: &Stats) { + self.sync(latest); + } + + /// Report the streams whose frame-sync counters moved, one line each. + /// + /// The importer already warns on each individual resync; this is the running total, which + /// is what an operator turns into a rate. + fn sync(&self, latest: &Stats) { + let lost = |stream: &StreamStats| (stream.resyncs, stream.discarded, stream.unconfirmed); + for (pid, stream) in &latest.streams { + let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); + if previous.map_or((0, 0, 0), lost) == lost(stream) { + continue; + } + tracing::info!( + pid = *pid, + track = stream.track, + resyncs = stream.resyncs, + discarded = stream.discarded, + unconfirmed = stream.unconfirmed, + "audio frame sync lost" + ); + } + } +} + +#[cfg(test)] +mod test { + use super::*; + + /// A stream whose count stops across a sample is logged once, with its silence, and again + /// only after it has delivered in between; a stream that keeps counting never is, and + /// neither reports frame sync it never lost. + #[test] + #[tracing_test::traced_test] + fn reports_a_stream_that_stopped() { + const VIDEO: u16 = 0x100; + const AUDIO: u16 = 0x101; + let sample = |video: u64, audio: u64| { + let mut stats = Stats::default(); + for (pid, track, units) in [(VIDEO, ".avc3", video), (AUDIO, ".mp2", audio)] { + let stream = StreamStats { + track, + units, + quiet: Some(std::time::Duration::from_millis(40)), + ..Default::default() + }; + stats.streams.insert(pid, stream); + } + stats + }; + + let mut log = Log::default(); + for (video, audio) in [(10, 10), (10, 20), (10, 30), (11, 40), (11, 50)] { + log.sample(sample(video, audio)); + } + + logs_assert(|lines: &[&str]| { + let stopped: Vec<_> = lines + .iter() + .filter(|line| line.contains("stopped delivering access units")) + .collect(); + match stopped.as_slice() { + [first, second] if [first, second].iter().all(|line| line.contains("pid=256")) => Ok(()), + _ => Err(format!("expected two lines for the video PID, got {stopped:?}")), + } + }); + assert!(!logs_contain("audio frame sync lost"), "nothing lost frame sync"); + } + + /// A resync is reported on the sample that saw it, and the end of input still reports one + /// the last partial interval found. + #[test] + #[tracing_test::traced_test] + fn reports_frame_sync_lost_at_the_end() { + let sample = |resyncs: u64, units: u64| { + let stream = StreamStats { + track: ".mp2", + units, + resyncs, + ..Default::default() + }; + let mut stats = Stats::default(); + stats.streams.insert(0x101, stream); + stats + }; + + let mut log = Log::default(); + log.sample(sample(0, 10)); + log.sample(sample(0, 20)); + log.finish(&sample(1, 21)); + + logs_assert(|lines: &[&str]| { + match lines + .iter() + .filter(|line| line.contains("audio frame sync lost")) + .count() + { + 1 => Ok(()), + n => Err(format!("expected one frame-sync line, got {n}")), + } + }); + assert!(!logs_contain("stopped delivering"), "the stream kept counting"); + } +} diff --git a/rs/moq-mux/src/container/ts/test_data/aac_quad.ts b/rs/moq-mux/src/container/ts/test_data/aac_quad.ts new file mode 100644 index 00000000000..17aff478620 Binary files /dev/null and b/rs/moq-mux/src/container/ts/test_data/aac_quad.ts differ diff --git a/rs/moq-mux/src/container/ts/test_data/he_aac.flv b/rs/moq-mux/src/container/ts/test_data/he_aac.flv new file mode 100644 index 00000000000..5bf778ce3c0 Binary files /dev/null and b/rs/moq-mux/src/container/ts/test_data/he_aac.flv differ diff --git a/rs/moq-mux/src/container/ts/test_data/he_aac_v2.flv b/rs/moq-mux/src/container/ts/test_data/he_aac_v2.flv new file mode 100644 index 00000000000..1df313b4099 Binary files /dev/null and b/rs/moq-mux/src/container/ts/test_data/he_aac_v2.flv differ diff --git a/rs/moq-mux/src/container/ts/test_data/opus_5_1.ts b/rs/moq-mux/src/container/ts/test_data/opus_5_1.ts new file mode 100644 index 00000000000..14ad7cb9c04 Binary files /dev/null and b/rs/moq-mux/src/container/ts/test_data/opus_5_1.ts differ diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index 7c88e0156fa..9c884ac552d 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -59,6 +59,15 @@ impl Source { crate::catalog::Consumer::new(&broadcast, format).await } + /// Wait for the broadcast to come back after `ended`, the one an export was reading, closes. + /// + /// A broadcast that stays up never returns, so a clean catalog end that leaves it announced + /// waits here until the caller's own deadline. Bound the wait with a timeout. + pub async fn returned(&self, ended: &moq_net::broadcast::Consumer) -> crate::Result { + ended.closed().await; + Ok(self.origin.routed_broadcast(&self.path).await?) + } + /// Begin resolving the catalog broadcast (the one at this source's path). pub(crate) fn request_catalog(&self) -> kio::Pending { self.origin.request_broadcast(&self.path) @@ -373,6 +382,36 @@ mod tests { assert!(binding.broadcast().await.is_err()); } + #[tokio::test] + async fn returned_waits_for_a_new_broadcast_after_the_old_one_ends() { + let origin = produce_origin(); + let first = origin.publish("live", Default::default()).unwrap(); + settle().await; + let source = Source::new(origin.consume(), "live"); + let ended = source.broadcast().await.unwrap(); + + let returned = source.returned(&ended); + tokio::pin!(returned); + tokio::select! { + biased; + _ = &mut returned => panic!("the broadcast is still up"), + _ = settle() => {} + } + + // Gone, and nothing serves the path yet. + drop(first); + tokio::select! { + biased; + _ = &mut returned => panic!("nothing has published the path again"), + _ = settle() => {} + } + + let _second = origin.publish("live", Default::default()).unwrap(); + let back = returned.await.unwrap(); + assert!(!back.is_closed()); + assert!(!back.is_clone(&ended)); + } + #[tokio::test] async fn no_override_targets_catalog_broadcast() { let origin = produce_origin(); diff --git a/rs/moq-net/CHANGELOG.md b/rs/moq-net/CHANGELOG.md index e60aef120ec..08e8bc428d2 100644 --- a/rs/moq-net/CHANGELOG.md +++ b/rs/moq-net/CHANGELOG.md @@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.8](https://github.com/moq-dev/moq/compare/moq-net-v0.3.7...moq-net-v0.3.8) - 2026-09-30 + +### Added + +- *(lite)* moq-lite-07 switches to 64-bit leading-ones varints ([#4455](https://github.com/moq-dev/moq/pull/4455)) +- *(net)* BigInt-free varint codec, internal U64, and checked Varint.decode ([#4454](https://github.com/moq-dev/moq/pull/4454)) +- *(net)* drain queued stream data before a graceful close ([#4430](https://github.com/moq-dev/moq/pull/4430)) +- *(net)* read a subtree through an origin mount ([#4271](https://github.com/moq-dev/moq/pull/4271)) + +### Fixed + +- *(net)* send the AUTHORITY setup option from moqt:// clients ([#4578](https://github.com/moq-dev/moq/pull/4578)) +- *(net)* re-resolve a splice successor on every judgment +- *(net)* preserve cached history for late relay subscribers ([#4472](https://github.com/moq-dev/moq/pull/4472)) +- *(net)* align IETF object extension limits ([#4475](https://github.com/moq-dev/moq/pull/4475)) +- *(net)* cancel an unwanted lite track still waiting on TRACK_INFO ([#4494](https://github.com/moq-dev/moq/pull/4494)) +- *(net)* skip announce updates the peer cannot tell apart ([#4423](https://github.com/moq-dev/moq/pull/4423)) +- *(net)* an origin::Dynamic keeps its origin alive ([#4417](https://github.com/moq-dev/moq/pull/4417)) +- *(net)* resolve a relayed subscription's start from its source ([#4387](https://github.com/moq-dev/moq/pull/4387)) +- *(moq-net)* hide routes through a peer that withdrew the prefix ([#4399](https://github.com/moq-dev/moq/pull/4399)) +- *(net)* forget spliced tracks unread for the linger, finished ones included ([#4361](https://github.com/moq-dev/moq/pull/4361)) +- *(net)* select scoped routes after filtering, not before ([#4363](https://github.com/moq-dev/moq/pull/4363)) +- *(net)* refuse chained and wildcard origin mounts in any order ([#4362](https://github.com/moq-dev/moq/pull/4362)) +- *(net)* keep an aborted track's finished groups, expire ended tracks ([#4378](https://github.com/moq-dev/moq/pull/4378)) +- *(net)* keep a settled track's groups when it is aborted ([#4351](https://github.com/moq-dev/moq/pull/4351)) + +### Other + +- *(moq-net)* watch mesh_withdraw's cursor from its own task ([#4564](https://github.com/moq-dev/moq/pull/4564)) +- Merge pull request #4561 from moq-dev/quest/m1/cluster-publisher-in-place +- Merge pull request #4484 from moq-dev/quest/m1/splice-edges +- Merge remote-tracking branch 'origin/main' into quest/m1/splice-edges +- *(quest)* drop suffix-based routing from the plans ([#4382](https://github.com/moq-dev/moq/pull/4382)) + ## [0.3.7](https://github.com/moq-dev/moq/compare/moq-net-v0.3.6...moq-net-v0.3.7) - 2026-09-27 ### Added diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index 967afb259d1..f5b82dcb394 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.3.7" +version = "0.3.8" edition = "2024" rust-version.workspace = true @@ -16,7 +16,7 @@ categories = ["multimedia", "network-programming", "web-programming"] ignored = ["getrandom"] [features] -# Exposes the wire codecs to the `fuzz/` harness and the announce bench through the +# Exposes the wire codecs to the `fuzz/` harness and the announce and varint benches through the # hidden `fuzz` module. Off by default and hidden from the docs. fuzz = [] @@ -75,6 +75,12 @@ name = "announce" harness = false required-features = ["fuzz"] +# Reaches the private lite codec through the hidden `fuzz` module. +[[bench]] +name = "varint" +harness = false +required-features = ["fuzz"] + [[bench]] name = "group" harness = false diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index e6e0945c465..fde970c50df 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -5,8 +5,8 @@ //! (cursors), so a cost that grows with the size of the table rather than with //! the tree around the touched path shows up as a slope. The table is a trie //! keyed by path segment: an announcement visits only the cursors on the walk -//! down to its prefix and beneath it, and each recomputes its best route from -//! the entries at that prefix alone. +//! down to its prefix and beneath it. Competing routes at that prefix are +//! ranked once per change, then each cursor selects its first visible entry. //! //! Run with `cargo bench -p moq-net --bench origin`. @@ -20,9 +20,9 @@ use moq_net::{Hop, Hops, Pattern, Patterns, Timestamp, announce, broadcast, kio, const SHAPES: [(usize, usize); 3] = [(100, 10), (1_000, 100), (1_000, 1_000)]; /// `(duplicates, subscribers)` shapes for one *contended* prefix: how many -/// routes cover the same path, against how many cursors watch it. The first row -/// is a live fleet's mesh width; the rest sweep past it so the slope is visible. -const CONTENDED: [(usize, usize); 4] = [(30, 30), (60, 60), (240, 60), (240, 240)]; +/// routes cover the same path, against how many cursors watch it. Includes +/// sparse fanout, a live fleet's mesh width, and larger contended tables. +const CONTENDED: [(usize, usize); 6] = [(1, 1), (30, 1), (30, 30), (60, 60), (240, 60), (240, 240)]; /// An origin with `publishers` broadcasts under `room/` and `subscribers` /// cursors watching everything. The handles are held: dropping a broadcast @@ -175,8 +175,7 @@ fn bench_announce_fleet(c: &mut Criterion) { /// publisher produces. A mesh produces the other one: the same path arrives /// once per peer it can travel through, so a prefix carries one entry per peer. /// The trie narrows a change to the touched prefix, but picking the winner -/// there still visits every entry at it, once per watching cursor, so both are -/// swept. +/// there shares the ranking across its watching cursors, so both are swept. /// /// The arriving route is priced below every incumbent so it takes the prefix /// outright: each cursor is told twice per iteration, once for the new winner @@ -219,6 +218,64 @@ fn bench_announce_duplicate(c: &mut Criterion) { group.finish(); } +/// Re-price a live mesh route with cursors watching different scopes. +/// The challenger alternates between winning and losing, so selection must +/// honor each cursor's scope rather than reuse one global winner. +fn bench_reprice_duplicate(c: &mut Criterion) { + let mut group = c.benchmark_group("origin/reprice_duplicate"); + for (duplicates, subscribers) in CONTENDED { + let id = BenchmarkId::from_parameter(format!("{duplicates}d_{subscribers}s")); + group.bench_function(id, |b| { + let (producer, _driver) = origin::Producer::new(origin::Config::default()); + let _routes: Vec<_> = (1..=duplicates) + .map(|peer| { + producer + .scope( + "", + &Patterns::from(Pattern::subtree(&format!("{PATH}/p{}", (peer - 1) % 2)).unwrap()), + ) + .unwrap() + .dynamic(PATH, peer_route(peer as u64, INCUMBENT_COST)) + .unwrap() + }) + .collect(); + let challenger = duplicates as u64 + 1; + let route = producer + .dynamic(PATH, peer_route(challenger, INCUMBENT_COST + 1)) + .unwrap(); + let mut cursors: Vec = (0..subscribers) + .map(|peer| { + producer + .consume() + .scope( + "", + &Patterns::from(Pattern::subtree(&format!("{PATH}/p{}", peer % 2)).unwrap()), + ) + .unwrap() + .with_hidden(true) + .announced() + }) + .collect(); + for cursor in &mut cursors { + while cursor.next().now_or_never().flatten().is_some() {} + } + b.iter(|| { + for cost in [INCUMBENT_COST - 1, INCUMBENT_COST + 1] { + route.update(peer_route(challenger, cost)).unwrap(); + for cursor in &mut cursors { + let event = cursor.next().now_or_never().flatten().expect("winner changed"); + let moq_net::announce::Event::Update(update) = event else { + panic!("expected an update: got {event:?}"); + }; + assert_eq!(update.route.cost, moq_net::origin::Cost::new(cost.min(INCUMBENT_COST))); + } + } + }); + }); + } + group.finish(); +} + /// The contended path: one node's stats feed, which every peer in the mesh /// carries a route to. const PATH: &str = ".stats/p0/node/edge0"; @@ -429,6 +486,7 @@ criterion_group!( bench_announce_mounted, bench_announce_fleet, bench_announce_duplicate, + bench_reprice_duplicate, bench_announce_fronts, bench_serve_idle, bench_subscribe, diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 55926989962..14f7661d3b0 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -7,6 +7,15 @@ //! `track_aborted_scan` isolates the other half of delivery: how much a cached //! prefix of aborted groups costs the scan that has to walk past it. //! +//! `track_subscriber_churn` measures viewers joining and leaving beside steady ones: +//! each departure wakes the producer's aggregate poll, which walks the subscription +//! list, so departed entries left in the list show up as a slope over churn. +//! `track_subscriber_churn_after_peak` runs the same churn after a departed audience, +//! so entries walked in proportion to the old peak show up as a slope over it. +//! +//! `track_subscriber_join` measures a burst of viewers joining one track: each join +//! registers in the subscription list, so any per-join walk of it shows up as a slope. +//! //! Run with `cargo bench -p moq-net --bench track`. use std::hint::black_box; @@ -15,7 +24,7 @@ use std::task::Poll; use std::time::{Duration, Instant}; use bytes::Bytes; -use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main}; +use criterion::{BatchSize, BenchmarkId, Criterion, Throughput, criterion_group, criterion_main}; use moq_net::{Error, Timestamp, broadcast, cache, track}; /// Fanout sizes spanning a direct viewer, a small room, and a large room. @@ -30,6 +39,18 @@ const PAYLOAD: usize = 64; /// Small enough to reach steady-state eviction during Criterion warm-up. const CACHE_CAPACITY: u64 = 64 * 1024; +/// Steady viewers that stay subscribed while others churn. +const STEADY: [usize; 3] = [1, 8, 64]; + +/// Viewers that join and leave, one at a time, during one measured run. +const CHURN: [usize; 3] = [8, 64, 512]; + +/// Viewers that join at once and stay, during one measured run. +const JOIN: [usize; 3] = [64, 1024, 16384]; + +/// Viewers that joined and left before the churn, leaving the list room for that many. +const PEAK: [usize; 3] = [0, 1024, 16384]; + /// Concurrent publishers sharing one relay-style cache pool. const WRITERS: [usize; 4] = [1, 2, 4, 8]; @@ -123,6 +144,44 @@ impl AbortedScan { } } +/// Steady viewers on one track, with the producer's aggregate poll caught up. +struct Churn { + _broadcast: broadcast::Producer, + track: track::Producer, + _steady: Vec, + waiter: kio::Waiter, +} + +impl Churn { + /// `peak` more viewers join and leave first, and the aggregate poll sees them go. + fn new(steady: usize, peak: usize) -> Self { + let broadcast = broadcast::Info::default().produce(); + let mut track = broadcast.create_track("bench", None).unwrap(); + let steady = (0..steady).map(|_| track.subscribe(None)).collect(); + let peak: Vec<_> = (0..peak).map(|_| track.subscribe(None)).collect(); + let waiter = kio::Waiter::noop(); + assert!(track.poll_subscription_changed(&waiter).is_ready()); + drop(peak); + assert!(track.poll_subscription_changed(&waiter).is_pending()); + + Self { + _broadcast: broadcast, + track, + _steady: steady, + waiter, + } + } + + /// Join and leave `churn` times with the steady viewers' preferences, polling the + /// aggregate after each departure the way a relay forwarding demand upstream does. + fn run(&mut self, churn: usize) { + for _ in 0..churn { + drop(self.track.subscribe(None)); + assert!(self.track.poll_subscription_changed(&self.waiter).is_pending()); + } + } +} + fn bench_fanout(c: &mut Criterion) { let mut group = c.benchmark_group("track_fanout_group"); for subscribers in FANOUT { @@ -206,5 +265,68 @@ fn bench_aborted_scan(c: &mut Criterion) { group.finish(); } -criterion_group!(benches, bench_fanout, bench_parallel_write, bench_aborted_scan); +fn bench_subscriber_churn(c: &mut Criterion) { + let mut group = c.benchmark_group("track_subscriber_churn"); + for steady in STEADY { + for churn in CHURN { + group.throughput(Throughput::Elements(churn as u64)); + group.bench_with_input( + BenchmarkId::new(format!("steady_{steady}"), churn), + &churn, + |b, &churn| { + b.iter_batched_ref( + || Churn::new(steady, 0), + |setup| setup.run(churn), + BatchSize::SmallInput, + ); + }, + ); + } + } + group.finish(); +} + +fn bench_subscriber_churn_after_peak(c: &mut Criterion) { + const CHURN: usize = 512; + let mut group = c.benchmark_group("track_subscriber_churn_after_peak"); + group.throughput(Throughput::Elements(CHURN as u64)); + for peak in PEAK { + group.bench_with_input(BenchmarkId::from_parameter(peak), &peak, |b, &peak| { + b.iter_batched_ref(|| Churn::new(1, peak), |setup| setup.run(CHURN), BatchSize::SmallInput); + }); + } + group.finish(); +} + +fn bench_subscriber_join(c: &mut Criterion) { + let mut group = c.benchmark_group("track_subscriber_join"); + for join in JOIN { + group.throughput(Throughput::Elements(join as u64)); + group.bench_with_input(BenchmarkId::from_parameter(join), &join, |b, &join| { + b.iter_batched( + || { + let broadcast = broadcast::Info::default().produce(); + let track = broadcast.create_track("bench", None).unwrap(); + (broadcast, track) + }, + |(broadcast, track)| { + let viewers: Vec<_> = (0..join).map(|_| track.subscribe(None)).collect(); + (broadcast, track, viewers) + }, + BatchSize::SmallInput, + ); + }); + } + group.finish(); +} + +criterion_group!( + benches, + bench_fanout, + bench_parallel_write, + bench_aborted_scan, + bench_subscriber_churn, + bench_subscriber_churn_after_peak, + bench_subscriber_join +); criterion_main!(benches); diff --git a/rs/moq-net/benches/varint.rs b/rs/moq-net/benches/varint.rs new file mode 100644 index 00000000000..01ce78a3978 --- /dev/null +++ b/rs/moq-net/benches/varint.rs @@ -0,0 +1,43 @@ +//! Lite-07 leading-ones varints against lite-06 QUIC varints: the bytes and the CPU to +//! encode and decode what a publisher writes per frame, per group, and per request. +//! +//! The two versions share these layouts, so the only difference is the varint codec. +//! The byte counts print once before the timings. +//! +//! Run with `cargo bench -p moq-net --features fuzz --bench varint`. + +use std::hint::black_box; + +use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; +use moq_net::{Version, fuzz::LiteSample}; + +fn versions() -> [(&'static str, Version); 2] { + ["moq-lite-06", "moq-lite-07-wip"].map(|name| (name, name.parse().unwrap())) +} + +fn bench(c: &mut Criterion) { + println!("{:<10} {:>8} {:>8}", "sample", "lite-06", "lite-07"); + for sample in LiteSample::ALL { + let [lite06, lite07] = versions().map(|(_, version)| sample.encode(version).len()); + println!("{:<10} {lite06:>8} {lite07:>8}", format!("{sample:?}")); + } + + let mut group = c.benchmark_group("lite_varint"); + for sample in LiteSample::ALL { + for (name, version) in versions() { + let id = format!("{sample:?}/{name}"); + group.bench_function(BenchmarkId::new("encode", &id), |b| { + b.iter(|| black_box(sample.encode(black_box(version)))) + }); + + let wire = sample.encode(version); + group.bench_function(BenchmarkId::new("decode", &id), |b| { + b.iter(|| black_box(sample.decode(black_box(version), black_box(&wire)))) + }); + } + } + group.finish(); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 47d1aecd888..e3baa329d87 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -17,6 +17,7 @@ pub struct Client { stats: stats::Session, versions: Versions, setup_path: Option, + setup_authority: Option, cost: Option, peer_hop: Option, } @@ -82,6 +83,12 @@ impl Client { self } + /// Set the URI authority to advertise in SETUP (moq-transport only) + pub fn with_authority(mut self, authority: impl Into) -> Self { + self.setup_authority = Some(authority.into()); + self + } + /// Price this link, in the units the rest of the mesh uses (moq-lite-06+, and /// `moqt-17`+ via the MoQ Cluster extension). /// @@ -266,6 +273,7 @@ impl Client { cost: self.cost, version: draft, path: self.setup_path.clone(), + authority: self.setup_authority.clone(), peer_setup_stream: None, peer_declared: None, })?; @@ -341,6 +349,9 @@ impl Client { if let Some(path) = &self.setup_path { parameters.set_bytes(ietf::ParameterBytes::Path, path.clone().into_bytes()); } + if let Some(authority) = &self.setup_authority { + parameters.set_bytes(ietf::ParameterBytes::Authority, authority.clone().into_bytes()); + } ietf::solicit::into_setup(&mut parameters, ietf_encoding); ietf::hidden::into_setup(&mut parameters, ietf_encoding); ietf::active_count::into_setup(&mut parameters, ietf_encoding); @@ -412,6 +423,7 @@ impl Client { cost: self.cost, version: v, path: None, + authority: None, peer_setup_stream: None, peer_declared: Some(peer_declared), })?; @@ -766,6 +778,42 @@ mod tests { assert!(matches!(next.await, Some(crate::announce::Event::Live))); } + /// The client SETUP on the bidi control stream (the pre-draft-17 framing) carries the + /// AUTHORITY next to the PATH. + #[tokio::test(start_paused = true)] + async fn draft14_setup_carries_the_authority() { + let fake = FakeSession::new(Some(ALPN_LITE), mock_server_setup(Version::Lite(lite::Version::Lite01))); + let client = Client::new() + .with_versions( + [ + Version::Lite(lite::Version::Lite01), + Version::Ietf(ietf::Version::Draft14), + ] + .into(), + ) + .with_path("/anon") + .with_authority("relay.example.com:4443"); + + let (_session, driver) = client + .connect(tokio::time::Instant::now().into_std(), fake.clone()) + .await + .unwrap(); + tokio::spawn(crate::time::run(driver)); + + let mut setup_bytes = Bytes::from(fake.control_writes()); + let setup = setup::Client::decode(&mut setup_bytes, Version::Ietf(ietf::Version::Draft14)).unwrap(); + let mut parameters = setup.parameters; + let parameters = ietf::Parameters::decode(&mut parameters, ietf::Version::Draft14).unwrap(); + assert_eq!( + parameters.get_bytes(ietf::ParameterBytes::Authority), + Some(b"relay.example.com:4443".as_ref()) + ); + assert_eq!( + parameters.get_bytes(ietf::ParameterBytes::Path), + Some(b"/anon".as_ref()) + ); + } + #[tokio::test(start_paused = true)] async fn alpn_lite_falls_back_to_draft14_and_switches_version_post_setup() { run_alpn_lite_fallback_case(Some(ALPN_LITE)).await; diff --git a/rs/moq-net/src/coding/decode.rs b/rs/moq-net/src/coding/decode.rs index 13579e73309..57888613548 100644 --- a/rs/moq-net/src/coding/decode.rs +++ b/rs/moq-net/src/coding/decode.rs @@ -83,6 +83,16 @@ pub enum DecodeError { Version, } +impl DecodeError { + /// A complete frame cannot be extended by reading more stream bytes. + pub(crate) fn complete(self) -> Self { + match self { + Self::Short => Self::InvalidValue, + other => other, + } + } +} + impl Decode for bool { fn decode(r: &mut R, version: V) -> Result { match u8::decode(r, version)? { diff --git a/rs/moq-net/src/coding/reader.rs b/rs/moq-net/src/coding/reader.rs index 434e9625511..4d08357d6f6 100644 --- a/rs/moq-net/src/coding/reader.rs +++ b/rs/moq-net/src/coding/reader.rs @@ -410,6 +410,113 @@ mod tests { } } + fn refuses_frame + Debug, V: StreamCodes + Clone>(prefix: &[u8], version: V, oversized: bool) { + let mut reader = Reader::new(Chunks([b"following bytes".as_slice()].into()), version); + reader.buffer.extend_from_slice(prefix); + let mut cx = Context::from_waker(std::task::Waker::noop()); + let result = reader.poll_decode::(&mut cx); + if oversized { + assert!( + matches!( + result, + Poll::Ready(Err(Error::Decode(DecodeError::MessageTooLarge { .. }))) + ), + "{result:?}" + ); + } else { + assert!( + matches!(result, Poll::Ready(Err(Error::Decode(DecodeError::InvalidValue)))), + "{result:?}" + ); + } + assert_eq!(reader.buffer.len(), prefix.len()); + assert_eq!(reader.stream.0.len(), 1, "read past the complete frame"); + } + + #[test] + fn malformed_complete_frames_are_refused() { + use crate::{Version, ietf, lite, setup}; + refuses_frame::(&[0], lite::Version::Lite05, false); + refuses_frame::(&[0], lite::Version::Lite05, false); + refuses_frame::(&[0, 0], ietf::Version::Draft20, false); + for version in [ + Version::Lite(lite::Version::Lite01), + Version::Lite(lite::Version::Lite02), + Version::Ietf(ietf::Version::Draft14), + ] { + let prefix = if version.is_lite() { + &[0x20, 0][..] + } else { + &[0x20, 0, 0][..] + }; + refuses_frame::(prefix, version, false); + let prefix = if version.is_lite() { + &[0x21, 0][..] + } else { + &[0x21, 0, 0][..] + }; + refuses_frame::(prefix, version, false); + } + } + + #[test] + fn oversized_setup_is_refused_at_the_prefix() { + use crate::{Version, lite, setup}; + for version in [lite::Version::Lite01, lite::Version::Lite02] { + for size in [65537u64, (1 << 40) + 1] { + let mut prefix = vec![0x20]; + size.encode(&mut prefix, version).unwrap(); + refuses_frame::(&prefix, Version::Lite(version), true); + prefix[0] = 0x21; + refuses_frame::(&prefix, Version::Lite(version), true); + } + } + for version in [lite::Version::Lite05, lite::Version::Lite06] { + let mut prefix = Vec::new(); + 65537u64.encode(&mut prefix, version).unwrap(); + refuses_frame::(&prefix, version, true); + } + } + + #[test] + fn setup_at_the_limit_waits_for_its_body() { + use crate::{Version, lite, setup}; + for version in [lite::Version::Lite01, lite::Version::Lite02] { + let mut prefix = vec![0x20]; + 65536u64.encode(&mut prefix, version).unwrap(); + assert!(matches!( + setup::Client::decode(&mut prefix.as_slice(), Version::Lite(version)), + Err(DecodeError::Short) + )); + prefix[0] = 0x21; + assert!(matches!( + setup::Server::decode(&mut prefix.as_slice(), Version::Lite(version)), + Err(DecodeError::Short) + )); + } + for version in [lite::Version::Lite05, lite::Version::Lite06] { + let mut prefix = Vec::new(); + 65536u64.encode(&mut prefix, version).unwrap(); + assert!(matches!( + lite::Setup::decode(&mut prefix.as_slice(), version), + Err(DecodeError::Short) + )); + } + } + + #[test] + fn fragmented_setup_waits_for_its_body() { + let mut reader = Reader::new(Chunks([b"\x01".as_slice()].into()), crate::lite::Version::Lite05); + let mut cx = Context::from_waker(std::task::Waker::noop()); + assert!(reader.poll_decode::(&mut cx).is_pending()); + reader.stream.0.push_back(b"\x00"); + assert!(matches!( + reader.poll_decode::(&mut cx), + Poll::Ready(Ok(_)) + )); + assert!(reader.buffer.is_empty()); + } + /// A consumer parked on the group cannot run until this task yields, so a burst of /// chunks owes exactly one wake: at the boundary, from whoever wrote them. Every /// other exit hands the wake to the caller's `finish` or `abort`. diff --git a/rs/moq-net/src/coding/varint.rs b/rs/moq-net/src/coding/varint.rs index a9339771747..08e35cab0fa 100644 --- a/rs/moq-net/src/coding/varint.rs +++ b/rs/moq-net/src/coding/varint.rs @@ -270,7 +270,7 @@ impl VarInt { /// - `1111110x` → 7 bytes, 49 usable bits (draft-18+, INVALID in draft-17 per #1595) /// - `11111110` → 8 bytes, 56 usable bits /// - `11111111` → 9 bytes, 64 usable bits - fn decode_leading_ones(r: &mut R, version: ietf::Version) -> Result { + fn decode_leading_ones(r: &mut R) -> Result { if !r.has_remaining() { return Err(DecodeError::Short); } @@ -341,9 +341,6 @@ impl VarInt { } 6 => { // 1111110x + 6 bytes, 49 bits (draft-18+, INVALID in draft-17 per #1595) - if matches!(version, ietf::Version::Draft17) { - return Err(DecodeError::InvalidValue); - } if r.remaining() < 6 { return Err(DecodeError::Short); } @@ -380,7 +377,7 @@ impl VarInt { /// Always emits the minimal canonical form. Draft-18 also accepts 7-byte form /// (`1111110x`) on decode but we never emit it because the 8-byte form is one byte /// larger but simpler and is universally valid. - fn encode_leading_ones(&self, w: &mut W, _version: ietf::Version) -> Result<(), EncodeError> { + fn encode_leading_ones(&self, w: &mut W) -> Result<(), EncodeError> { let x = self.0; let remaining = w.remaining_mut(); @@ -452,16 +449,39 @@ impl VarInt { use crate::{Version, ietf, lite}; -// All lite versions use QUIC-style varint encoding. +// Lite01-06 use QUIC-style varints; lite-07+ uses leading-ones. Lite-07 is only reached +// through its ALPN, so the codec is known before the first byte of any stream. impl Encode for VarInt { - fn encode(&self, w: &mut W, _: lite::Version) -> Result<(), EncodeError> { - self.encode_quic(w) + fn encode(&self, w: &mut W, version: lite::Version) -> Result<(), EncodeError> { + match version { + lite::Version::Lite01 + | lite::Version::Lite02 + | lite::Version::Lite03 + | lite::Version::Lite04 + | lite::Version::Lite05 + | lite::Version::Lite06 => self.encode_quic(w), + _ => self.encode_leading_ones(w), + } } } impl Decode for VarInt { - fn decode(r: &mut R, _: lite::Version) -> Result { - Self::decode_quic(r) + fn decode(r: &mut R, version: lite::Version) -> Result { + match version { + lite::Version::Lite01 + | lite::Version::Lite02 + | lite::Version::Lite03 + | lite::Version::Lite04 + | lite::Version::Lite05 + | lite::Version::Lite06 => Self::decode_quic(r), + // Lite-07 values span the full 64 bits, but `VarInt` is still 62-bit here, so a + // larger value is a loud decode error, never a truncation. Known limitation, lifted + // when the VarInt codec quest (quest/m1/rs2ts/varint-codec.md) widens `VarInt`. + _ => match Self::decode_leading_ones(r)? { + x if x > Self::MAX => Err(DecodeError::BoundsExceeded), + x => Ok(x), + }, + } } } @@ -470,7 +490,7 @@ impl Encode for VarInt { fn encode(&self, w: &mut W, version: ietf::Version) -> Result<(), EncodeError> { match version { ietf::Version::Draft14 | ietf::Version::Draft15 | ietf::Version::Draft16 => self.encode_quic(w), - _ => self.encode_leading_ones(w, version), + _ => self.encode_leading_ones(w), } } } @@ -479,7 +499,11 @@ impl Decode for VarInt { fn decode(r: &mut R, version: ietf::Version) -> Result { match version { ietf::Version::Draft14 | ietf::Version::Draft15 | ietf::Version::Draft16 => Self::decode_quic(r), - _ => Self::decode_leading_ones(r, version), + // Draft-18 made 1111110x the 7-byte form; draft-17 reserves it (#1595). + ietf::Version::Draft17 if r.chunk().first().is_some_and(|b| b.leading_ones() == 6) => { + Err(DecodeError::InvalidValue) + } + _ => Self::decode_leading_ones(r), } } } @@ -536,7 +560,9 @@ where VarInt: Decode, { fn decode(r: &mut R, version: V) -> Result { - VarInt::decode(r, version).map(|v| v.into_inner() as usize) + // Truncating on 32-bit targets (wasm32) would let an oversized length pass a size cap. + let v = VarInt::decode(r, version)?; + v.into_inner().try_into().map_err(|_| DecodeError::BoundsExceeded) } } @@ -590,7 +616,7 @@ mod tests { for (bytes, expected) in cases { // Test decoding let mut buf = Bytes::from(bytes.to_vec()); - let decoded = VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft17).expect("decode should succeed"); + let decoded = VarInt::decode_leading_ones(&mut buf).expect("decode should succeed"); assert_eq!( decoded.into_inner(), *expected, @@ -605,9 +631,7 @@ mod tests { && (bytes.len() == 1 || *expected != 37) { let mut encoded = Vec::new(); - varint - .encode_leading_ones(&mut encoded, ietf::Version::Draft17) - .expect("encode should succeed"); + varint.encode_leading_ones(&mut encoded).expect("encode should succeed"); assert_eq!(&encoded, bytes, "encode mismatch for value {expected}"); } } @@ -619,7 +643,7 @@ mod tests { let mut buf = Bytes::from_static(&[0xFC]); assert!( matches!( - VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft17), + VarInt::decode(&mut buf, ietf::Version::Draft17), Err(DecodeError::InvalidValue) ), "0xFC should be rejected as invalid on draft-17" @@ -641,7 +665,7 @@ mod tests { let varint = VarInt::from_u64(value).expect("value should be representable as VarInt"); let mut encoded = Vec::new(); varint - .encode_leading_ones(&mut encoded, ietf::Version::Draft17) + .encode_leading_ones(&mut encoded) .expect("leading-ones encode should succeed"); assert_eq!( encoded.len(), @@ -650,8 +674,7 @@ mod tests { ); let mut bytes = Bytes::from(encoded); - let decoded = VarInt::decode_leading_ones(&mut bytes, ietf::Version::Draft17) - .expect("leading-ones decode should succeed"); + let decoded = VarInt::decode_leading_ones(&mut bytes).expect("leading-ones decode should succeed"); assert_eq!(decoded.into_inner(), value, "round-trip mismatch for value {value}"); } } @@ -661,7 +684,7 @@ mod tests { // 1111110x prefix: invalid on draft-17. let bytes = Bytes::from(vec![0xFC, 0, 0, 0, 0, 0, 0]); let mut buf = bytes.clone(); - let err = VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft17).unwrap_err(); + let err = VarInt::decode(&mut buf, ietf::Version::Draft17).unwrap_err(); assert!(matches!(err, DecodeError::InvalidValue)); } @@ -719,6 +742,67 @@ mod tests { } } + fn lite(value: u64, version: lite::Version) -> Vec { + let mut buf = Vec::new(); + VarInt::try_from(value).unwrap().encode(&mut buf, version).unwrap(); + buf + } + + /// Lite-01 through lite-06 keep the QUIC form byte for byte. + #[test] + fn lite06_keeps_quic_varints() { + for version in [lite::Version::Lite01, lite::Version::Lite05, lite::Version::Lite06] { + assert_eq!(lite(63, version), [0x3F]); + assert_eq!(lite(64, version), [0x40, 0x40]); + assert_eq!(lite(16_384, version), [0x80, 0x00, 0x40, 0x00]); + } + } + + /// Lite-07 switches to leading-ones, including at every length boundary. + #[test] + fn lite07_uses_leading_ones() { + let version = lite::Version::Lite07; + let cases: &[(u64, &[u8])] = &[ + (0, &[0x00]), + (127, &[0x7F]), + (128, &[0x80, 0x80]), + ((1 << 14) - 1, &[0xBF, 0xFF]), + (1 << 14, &[0xC0, 0x40, 0x00]), + ((1 << 21) - 1, &[0xDF, 0xFF, 0xFF]), + (1 << 21, &[0xE0, 0x20, 0x00, 0x00]), + ((1 << 56) - 1, &[0xFE, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]), + (1 << 56, &[0xFF, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]), + ( + VarInt::MAX.into_inner(), + &[0xFF, 0x3F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], + ), + ]; + for (value, wire) in cases { + assert_eq!(lite(*value, version), *wire, "encode {value}"); + let mut buf = *wire; + assert_eq!(VarInt::decode(&mut buf, version).unwrap().into_inner(), *value); + assert!(buf.is_empty()); + } + } + + /// The 7-byte `1111110x` form is valid on lite-07, as on draft-18+. + #[test] + fn lite07_accepts_7_byte_varint() { + let mut buf: &[u8] = &[0xFD, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD]; + let decoded = VarInt::decode(&mut buf, lite::Version::Lite07).unwrap(); + assert_eq!(decoded.into_inner(), 0x1_2345_6789_ABCD); + } + + /// Lite-07 values above 2^62-1 are legal on the wire, but the 62-bit `VarInt` cannot + /// hold them yet, so they must fail loud rather than wrap or truncate. + #[test] + fn lite07_values_above_62_bits_fail_loud() { + for wire in [[0xFF, 0x40, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00], [0xFF; 9]] { + let err = VarInt::decode(&mut &wire[..], lite::Version::Lite07).unwrap_err(); + assert!(matches!(err, DecodeError::BoundsExceeded), "{wire:02x?}: {err:?}"); + } + } + #[test] fn draft18_accepts_7_byte_varint() { // Value 0x1234_5678_9ABC encoded as 7-byte leading-ones (1111110x | hi, +6 bytes). @@ -732,7 +816,7 @@ mod tests { bytes.push(((value >> shift) & 0xFF) as u8); } let mut buf = Bytes::from(bytes); - let decoded = VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft18).unwrap(); + let decoded = VarInt::decode(&mut buf, ietf::Version::Draft18).unwrap(); assert_eq!(decoded.into_inner(), value); } } diff --git a/rs/moq-net/src/driver.rs b/rs/moq-net/src/driver.rs index 634d6f3af7c..9fb2c7baf13 100644 --- a/rs/moq-net/src/driver.rs +++ b/rs/moq-net/src/driver.rs @@ -62,6 +62,7 @@ impl Driver { /// Panics if `now` is earlier than the previous poll or construction time. pub fn poll(&mut self, now: Instant, waiter: &kio::Waiter) -> Result, Error> { self.clock.advance(now); + self.clock.register_driver(waiter); match self.state.poll(waiter) { Poll::Ready(Ok(())) => Err(Error::Closed), Poll::Ready(Err(err)) => Err(err), diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 5fc9f793b63..36c0a4be23f 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -61,7 +61,7 @@ const IETF_VERSIONS: &[ietf::Version] = &[ const LITE_KINDS: u8 = 21; /// How many types [`ietf_wire`] dispatches over. -const IETF_KINDS: u8 = 39; +const IETF_KINDS: u8 = 40; /// Split the two selector bytes off the input: a version and a type. fn select(data: &[u8], versions: usize) -> Option<(usize, u8, &[u8])> { @@ -252,6 +252,124 @@ pub fn decode_announces(mut data: &[u8], compress: bool) -> Vec { resolved } +/// A varint-heavy lite wire object, as the varint bench times it: what a publisher +/// pays per frame, per group, and per request. +#[derive(Clone, Copy, Debug)] +pub enum LiteSample { + /// A 30 fps video group's FRAME headers: a zigzag timestamp delta in microseconds and + /// a size, 60 of them, led by a 60 KB keyframe. Payloads are left out. + Video, + /// A 50 Hz Opus group's FRAME headers: 50 of 20 ms and 160 bytes. + Audio, + /// A GROUP header, well into a long-running track. + Group, + /// A SUBSCRIBE for a track, the way a player opens one. + Subscribe, + /// A datagram's header, with an empty payload. + Datagram, + /// A SETUP declaring a probe level, a cost, and a random Hop ID. + Setup, +} + +impl LiteSample { + /// Every sample, in the order the bench reports them. + pub const ALL: [Self; 6] = [ + Self::Video, + Self::Audio, + Self::Group, + Self::Subscribe, + Self::Datagram, + Self::Setup, + ]; + + /// The FRAME headers for [`Self::Video`] and [`Self::Audio`], as (delta, size) pairs. + fn frames(self) -> Vec<(i64, u64)> { + match self { + Self::Video => (0..60) + .map(|n| match n { + 0 => (0, 60_000), + n if n % 10 == 0 => (33_333, 17_000), + _ => (33_333, 8_000), + }) + .collect(), + Self::Audio => (0..50).map(|n| (if n == 0 { 0 } else { 20_000 }, 160)).collect(), + _ => Vec::new(), + } + } + + /// Encode this sample at `version`, which must be a moq-lite version. + pub fn encode(self, version: crate::Version) -> Vec { + let version = lite::Version::try_from(version).expect("a moq-lite version"); + let mut buf = Vec::new(); + match self { + Self::Video | Self::Audio => { + for (delta, size) in self.frames() { + VarInt::from_zigzag(delta).unwrap().encode(&mut buf, version).unwrap(); + size.encode(&mut buf, version).unwrap(); + } + } + Self::Group => lite::Group { + subscribe: 3, + sequence: 1_234, + frame_start: 0, + } + .encode(&mut buf, version) + .unwrap(), + Self::Subscribe => lite::Subscribe { + id: 3, + broadcast: Path::new("room/alice"), + track: "video".into(), + priority: 2, + max_age: std::time::Duration::from_secs(10), + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + } + .encode(&mut buf, version) + .unwrap(), + Self::Datagram => lite::Datagram { + subscribe: 3, + sequence: 1_234, + timestamp: 1_234_567_890, + payload: bytes::Bytes::new(), + } + .encode(&mut buf, version) + .unwrap(), + Self::Setup => lite::Setup { + probe: lite::ProbeLevel::Report, + cost: Some(1), + hop: Some(crate::Hop::new(0x1d_2c3b_4a59_6877).unwrap()), + ..Default::default() + } + .encode(&mut buf, version) + .unwrap(), + } + buf + } + + /// Decode what [`Self::encode`] wrote at `version`, returning how many objects it read. + pub fn decode(self, version: crate::Version, mut data: &[u8]) -> usize { + let version = lite::Version::try_from(version).expect("a moq-lite version"); + let data = &mut data; + match self { + Self::Video | Self::Audio => { + let mut frames = 0; + while !data.is_empty() { + VarInt::decode(data, version).unwrap(); + u64::decode(data, version).unwrap(); + frames += 1; + } + frames + } + Self::Group => lite::Group::decode(data, version).map(|_| 1).unwrap(), + Self::Subscribe => lite::Subscribe::decode(data, version).map(|_| 1).unwrap(), + Self::Datagram => lite::Datagram::decode(data, version).map(|_| 1).unwrap(), + Self::Setup => lite::Setup::decode(data, version).map(|_| 1).unwrap(), + } + } +} + /// Feed a lite-07 announce stream through the stateful decoder, then check that our /// encoder's compression of what it resolved reads back as the same announcements. /// @@ -318,19 +436,21 @@ pub fn ietf_wire(data: &[u8]) -> bool { 36 => roundtrip::(rest, version, stable), 37 => roundtrip::(rest, version, stable), 38 => roundtrip::(rest, version, stable), + 39 => roundtrip::(rest, version, stable), _ => unreachable!("kind is taken modulo IETF_KINDS"), } } /// Decode a varint with whichever codec the selected version uses. /// -/// Byte 0 picks the version, which is the whole point: moq-lite and drafts 14-16 use -/// the QUIC two-bit length tag, while draft-17+ counts leading ones, and the two -/// disagree about which byte sequences are even legal. +/// Byte 0 picks the version, which is the whole point: lite-01 to lite-06 and drafts +/// 14-16 use the QUIC two-bit length tag, while lite-07 and draft-17+ count leading +/// ones, and the two disagree about which byte sequences are even legal. /// -/// The decoded value is deliberately not asserted to be within [`VarInt::MAX`]: the -/// leading-ones form spans the full `u64` by design, so a 9-byte encoding decodes -/// above the 62-bit ceiling and only fails when re-encoded for a QUIC-form version. +/// The decoded value is deliberately not asserted to be within [`VarInt::MAX`]: on the +/// IETF wire the leading-ones form spans the full `u64` by design, so a 9-byte encoding +/// decodes above the 62-bit ceiling. Lite-07 allows the same range, but refuses it at +/// decode until `VarInt` widens to 64 bits. pub fn varint(data: &[u8]) -> bool { let Some((&selector, rest)) = data.split_first() else { return false; diff --git a/rs/moq-net/src/ietf/datagram.rs b/rs/moq-net/src/ietf/datagram.rs new file mode 100644 index 00000000000..fae9b48bdfc --- /dev/null +++ b/rs/moq-net/src/ietf/datagram.rs @@ -0,0 +1,301 @@ +//! OBJECT_DATAGRAM: one Object carried in a QUIC datagram (draft-14 section 10.3.1 through +//! draft-20 section 11.3.1). +//! +//! The model counterpart is [`crate::Datagram`], a single-frame group, so only an Object at +//! ID 0 maps onto it. The Type is a set of flags on every draft; draft-14 lacks the +//! DEFAULT_PRIORITY bit and a status with an omitted Object ID. + +use bytes::{Buf, BufMut, Bytes}; + +use crate::coding::{Decode, DecodeError, Encode, EncodeError}; + +use super::Version; + +/// The bits of an OBJECT_DATAGRAM Type. +mod flag { + pub const PROPERTIES: u64 = 0x01; + pub const END_OF_GROUP: u64 = 0x02; + pub const ZERO_OBJECT_ID: u64 = 0x04; + pub const DEFAULT_PRIORITY: u64 = 0x08; + pub const STATUS: u64 = 0x20; + /// Every defined bit. Anything else, including the reserved 0x10, is invalid. + pub const ALL: u64 = PROPERTIES | END_OF_GROUP | ZERO_OBJECT_ID | DEFAULT_PRIORITY | STATUS; +} + +/// What follows an OBJECT_DATAGRAM's header. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum DatagramBody { + /// The Object Payload, delimited by the datagram boundary. + Payload(Bytes), + /// The Object Status of an Object without a payload. + Status(u64), +} + +/// A decoded OBJECT_DATAGRAM. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ObjectDatagram { + pub track_alias: u64, + pub group_id: u64, + /// The Object ID, or `None` when the ZERO_OBJECT_ID bit omits it (Object 0). + pub object_id: Option, + /// The Publisher Priority, or `None` to inherit the subscription's (draft-15+). + pub publisher_priority: Option, + /// No Object past this one exists in the group. + pub end_of_group: bool, + /// The Object Properties block without its length prefix, which carries the Timestamp. + pub properties: Option>, + pub body: DatagramBody, +} + +impl ObjectDatagram { + /// Whether `kind` is a Type this draft defines. + fn valid(kind: u64, version: Version) -> bool { + match version { + Version::Draft14 => kind <= 0x07 || kind == 0x20 || kind == 0x21, + // A status cannot also end the group. + _ => kind & !flag::ALL == 0 && !(kind & flag::STATUS != 0 && kind & flag::END_OF_GROUP != 0), + } + } +} + +impl Encode for ObjectDatagram { + fn encode(&self, w: &mut W, version: Version) -> Result<(), EncodeError> { + let mut kind = 0; + if self.properties.is_some() { + kind |= flag::PROPERTIES; + } + if self.end_of_group { + kind |= flag::END_OF_GROUP; + } + if self.object_id.is_none() { + kind |= flag::ZERO_OBJECT_ID; + } + if self.publisher_priority.is_none() { + kind |= flag::DEFAULT_PRIORITY; + } + if matches!(self.body, DatagramBody::Status(_)) { + kind |= flag::STATUS; + } + if !Self::valid(kind, version) { + return Err(EncodeError::InvalidState); + } + + kind.encode(w, version)?; + self.track_alias.encode(w, version)?; + self.group_id.encode(w, version)?; + if let Some(object_id) = self.object_id { + object_id.encode(w, version)?; + } + if let Some(priority) = self.publisher_priority { + priority.encode(w, version)?; + } + if let Some(properties) = &self.properties { + // A present but empty block is a protocol violation for the peer. + if properties.is_empty() { + return Err(EncodeError::InvalidState); + } + properties.encode(w, version)?; + } + + match &self.body { + DatagramBody::Status(status) => { + // Draft-17 on: only a Normal Object may carry Properties. + let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); + if !legacy && *status != 0 && self.properties.is_some() { + return Err(EncodeError::InvalidState); + } + status.encode(w, version)? + } + DatagramBody::Payload(payload) => { + // Runs to the datagram boundary: written raw, no length prefix. + if w.remaining_mut() < payload.len() { + return Err(EncodeError::Short); + } + w.put_slice(payload); + } + } + Ok(()) + } +} + +impl Decode for ObjectDatagram { + fn decode(r: &mut R, version: Version) -> Result { + let kind = u64::decode(r, version)?; + if !Self::valid(kind, version) { + return Err(DecodeError::InvalidValue); + } + + let track_alias = u64::decode(r, version)?; + let group_id = u64::decode(r, version)?; + let object_id = match kind & flag::ZERO_OBJECT_ID != 0 { + true => None, + false => Some(u64::decode(r, version)?), + }; + let publisher_priority = match kind & flag::DEFAULT_PRIORITY != 0 { + true => None, + false => Some(u8::decode(r, version)?), + }; + let properties = match kind & flag::PROPERTIES != 0 { + true => { + let properties = Vec::::decode(r, version)?; + if properties.is_empty() { + return Err(DecodeError::InvalidValue); + } + Some(properties) + } + false => None, + }; + + let body = match kind & flag::STATUS != 0 { + true => { + let status = u64::decode(r, version)?; + // Draft-17 on: only a Normal Object may carry Properties. + let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); + if !legacy && status != 0 && properties.is_some() { + return Err(DecodeError::InvalidValue); + } + if r.has_remaining() { + return Err(DecodeError::TrailingBytes); + } + DatagramBody::Status(status) + } + false => DatagramBody::Payload(r.copy_to_bytes(r.remaining())), + }; + + Ok(Self { + track_alias, + group_id, + object_id, + publisher_priority, + end_of_group: kind & flag::END_OF_GROUP != 0, + properties, + body, + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const ALL: [Version; 9] = [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft18, + Version::Draft19, + Version::Draft20, + Version::Draft21, + Version::Draft22, + ]; + + fn single(priority: Option) -> ObjectDatagram { + ObjectDatagram { + track_alias: 3, + group_id: 42, + object_id: None, + publisher_priority: priority, + end_of_group: true, + properties: Some(vec![0x10, 0x05]), + body: DatagramBody::Payload(Bytes::from_static(b"hello")), + } + } + + #[test] + fn roundtrip_every_draft() { + for version in ALL { + let datagram = single(Some(7)); + let mut buf = datagram.encode_bytes(version).unwrap(); + assert_eq!(buf[0], 0x07, "{version}: properties, end of group, object 0"); + let decoded = ObjectDatagram::decode(&mut buf, version).unwrap(); + assert_eq!(decoded, datagram, "{version}"); + assert!(!buf.has_remaining()); + } + } + + #[test] + fn default_priority_needs_draft15() { + assert!(matches!( + single(None).encode_bytes(Version::Draft14), + Err(EncodeError::InvalidState) + )); + assert!(ObjectDatagram::decode(&mut &[0x0C, 0x01, 0x02][..], Version::Draft14).is_err()); + + let mut buf = single(None).encode_bytes(Version::Draft16).unwrap(); + assert_eq!(buf[0], 0x0F); + assert_eq!( + ObjectDatagram::decode(&mut buf, Version::Draft16).unwrap(), + single(None) + ); + } + + #[test] + fn explicit_object_id_and_status() { + let datagram = ObjectDatagram { + track_alias: 1, + group_id: 2, + object_id: Some(0), + publisher_priority: Some(128), + end_of_group: false, + properties: None, + body: DatagramBody::Status(0), + }; + for version in ALL { + let mut buf = datagram.encode_bytes(version).unwrap(); + assert_eq!(buf[0], 0x20, "{version}"); + assert_eq!(ObjectDatagram::decode(&mut buf, version).unwrap(), datagram); + } + } + + #[test] + fn rejects_invalid_types() { + for version in ALL { + // A status that ends the group, the reserved bit, and a bit past the defined ones. + for kind in [0x22u64, 0x10, 0x40] { + let mut bytes = kind.encode_bytes(version).unwrap().to_vec(); + bytes.extend_from_slice(&[0x01, 0x02, 0x03, 0x04]); + assert!( + ObjectDatagram::decode(&mut &bytes[..], version).is_err(), + "{version}: {kind:#x}" + ); + } + } + } + + #[test] + fn status_with_properties_needs_normal() { + let datagram = ObjectDatagram { + track_alias: 1, + group_id: 2, + object_id: Some(0), + publisher_priority: Some(0), + end_of_group: false, + properties: Some(vec![0x10, 0x05]), + body: DatagramBody::Status(3), + }; + for version in ALL { + let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); + match datagram.encode_bytes(version) { + Ok(mut buf) => { + assert!(legacy, "{version}"); + assert_eq!(ObjectDatagram::decode(&mut buf, version).unwrap(), datagram); + } + Err(err) => { + assert!(!legacy, "{version}"); + assert!(matches!(err, EncodeError::InvalidState)); + } + } + } + } + + #[test] + fn rejects_empty_properties() { + // PROPERTIES and ZERO_OBJECT_ID, alias 1, group 2, priority 0, empty block. + let bytes = [0x05, 0x01, 0x02, 0x00, 0x00, b'x']; + assert!(matches!( + ObjectDatagram::decode(&mut &bytes[..], Version::Draft16), + Err(DecodeError::InvalidValue) + )); + } +} diff --git a/rs/moq-net/src/ietf/fetch.rs b/rs/moq-net/src/ietf/fetch.rs index 5987d8efbc7..7bf6d6d3619 100644 --- a/rs/moq-net/src/ietf/fetch.rs +++ b/rs/moq-net/src/ietf/fetch.rs @@ -167,7 +167,8 @@ impl Message for Fetch<'_> { ); let subscriber_priority = subscriber_priority.unwrap_or(128); - let group_order = group_order.unwrap_or(GroupOrder::Descending); + // No preference: the publisher picks the order. + let group_order = group_order.unwrap_or(GroupOrder::Any); Ok(Self { request_id, @@ -186,6 +187,9 @@ pub struct FetchOk { pub group_order: GroupOrder, pub end_of_track: bool, pub end_location: Location, + /// The track's properties, as SUBSCRIBE_OK carries them: MAX_CACHE_DURATION from the + /// draft-14/15 parameters, the Track Properties block from draft-16 on. + pub properties: super::Properties, } impl Message for FetchOk { const ID: u64 = 0x18; @@ -212,6 +216,8 @@ impl Message for FetchOk { self.end_of_track.encode(w, version)?; self.end_location.encode(w, version)?; encode_params!(w, version,); + // Track Properties are the final field, so nothing may follow. + self.properties.encode(w, version)?; } } Ok(()) @@ -229,12 +235,19 @@ impl Message for FetchOk { let group_order = GroupOrder::decode(buf, version)?; let end_of_track = bool::decode(buf, version)?; let end_location = Location::decode(buf, version)?; - let _params = Parameters::decode(buf, version)?; + let params = Parameters::decode(buf, version)?; + let properties = super::Properties { + max_cache_duration: params + .get_varint(super::ParameterVarInt::from(0x04)) + .map(std::time::Duration::from_millis), + ..Default::default() + }; Ok(Self { request_id, group_order, end_of_track, end_location, + properties, }) } _ => { @@ -243,11 +256,15 @@ impl Message for FetchOk { // GROUP_ORDER isn't legal here, but keep accepting it so a peer that still sends // it doesn't have its session torn down over a hint. decode_params!(buf, version, + 0x04 => max_cache_duration: Option, 0x22 => group_order: Option, ); - // FETCH_OK may declare a timescale; we don't surface it yet, and a fetched - // object without an interpretable timestamp is stamped on arrival. - let _ = super::Properties::decode(buf, version)?; + // The timescale is read but not surfaced yet: a fetched object without an + // interpretable timestamp is stamped on arrival. + let mut properties = super::Properties::decode(buf, version)?; + if version == Version::Draft15 { + properties.max_cache_duration = max_cache_duration.map(std::time::Duration::from_millis); + } let group_order = group_order.unwrap_or(GroupOrder::Descending); @@ -256,6 +273,7 @@ impl Message for FetchOk { group_order, end_of_track, end_location, + properties, }) } } @@ -593,6 +611,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft14); @@ -652,6 +671,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft15); @@ -669,6 +689,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft16); @@ -686,6 +707,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft17); @@ -724,6 +746,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft18); @@ -744,6 +767,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; #[rustfmt::skip] @@ -866,3 +890,42 @@ mod object_tests { assert!(FetchObject::decode(&mut bytes, VERSION).is_err()); } } + +#[cfg(test)] +mod cache_duration_tests { + use super::*; + use std::time::Duration; + + /// FETCH_OK carries MAX_CACHE_DURATION where SUBSCRIBE_OK does, so a track fetched with no + /// subscription still learns its retention window. + #[test] + fn max_cache_duration_is_read_in_each_drafts_field() { + for version in [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft18, + Version::Draft19, + Version::Draft20, + Version::Draft21, + Version::Draft22, + ] { + for age in [0u64, 30_000] { + let mut payload = match version { + Version::Draft14 => vec![0, 1, 0, 0, 0, 1, 4], + Version::Draft15 => vec![0, 0, 0, 0, 1, 4], + Version::Draft16 => vec![0, 0, 0, 0, 0, 4], + _ => vec![0, 0, 0, 0, 4], + }; + age.encode(&mut payload, version).unwrap(); + let got = FetchOk::decode_msg(&mut payload.as_slice(), version).unwrap(); + assert_eq!( + got.properties.max_cache_duration, + Some(Duration::from_millis(age)), + "{version}" + ); + } + } + } +} diff --git a/rs/moq-net/src/ietf/hidden.rs b/rs/moq-net/src/ietf/hidden.rs index 6fedea39166..388334a516d 100644 --- a/rs/moq-net/src/ietf/hidden.rs +++ b/rs/moq-net/src/ietf/hidden.rs @@ -4,7 +4,8 @@ //! for is hidden: it is left out of discovery unless the subscription opts in. The //! opt-in is the HIDDEN parameter on SUBSCRIBE_NAMESPACE, and since an unknown //! parameter fails decoding, it is only sent to a peer whose SETUP carried the HIDDEN -//! option. The rule itself is the one moq-lite applies (see +//! option. Peers that did not declare the option receive every namespace. +//! The rule itself is the one moq-lite applies (see //! [`crate::origin::Consumer::with_hidden`]). use super::Version; diff --git a/rs/moq-net/src/ietf/message.rs b/rs/moq-net/src/ietf/message.rs index 4bf95248df7..3dad0df82f1 100644 --- a/rs/moq-net/src/ietf/message.rs +++ b/rs/moq-net/src/ietf/message.rs @@ -38,7 +38,7 @@ impl Decode for T { } let raw = buf.copy_to_bytes(size); let mut slice = &raw[..]; - match Self::decode_msg(&mut slice, version) { + match Self::decode_msg(&mut slice, version).map_err(DecodeError::complete) { Ok(result) => { if slice.remaining() > 0 { return Err(DecodeError::Long); @@ -56,7 +56,7 @@ impl Decode for T { return Err(DecodeError::Short); } let mut limited = buf.take(size); - match Self::decode_msg(&mut limited, version) { + match Self::decode_msg(&mut limited, version).map_err(DecodeError::complete) { Ok(result) => { if limited.remaining() > 0 { return Err(DecodeError::Long); diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index f97355e8203..d3b73563e79 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -10,6 +10,7 @@ pub mod active_count; mod adapter; pub mod cluster; mod control; +mod datagram; pub(crate) mod error; mod fetch; mod filter; @@ -36,6 +37,7 @@ mod track; mod version; use control::Control; +pub use datagram::*; pub use fetch::*; pub use filter::*; pub use goaway::*; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 47809d9a16b..34b24f39c97 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -15,7 +15,7 @@ use web_transport_trait::poll::SendStream as _; use crate::{ AsPath, Error, Timescale, Timestamp, - coding::{Stream, Writer}, + coding::{Encode as _, Stream, Writer}, ietf::{self, Control, EndLocation, FetchHeader, FetchType, Filter, GroupOrder, Location, RequestId}, track::Subscription, util::{MaybeBoxedExt, MaybeSendBox}, @@ -44,6 +44,83 @@ enum FillStep { Done, } +/// Where a fetch object sits relative to the one written before it on the same stream. +#[derive(Clone, Copy)] +enum FetchPrior { + /// The first object on the stream. + None, + /// The next object of the same group. + Same, +} + +/// The group a FETCH answers with, read out of the cache so a later eviction cannot +/// truncate what FETCH_OK already promised. +struct FetchedGroup { + sequence: u64, + /// The Object ID of the first frame. + first: u64, + frames: Vec, + /// The group ended within the range, so every frame it will ever hold was read. + complete: bool, +} + +impl FetchPrior { + /// The prior for the next object of a single-group stream, clearing `first`. + fn next(first: &mut bool) -> Self { + match std::mem::take(first) { + true => Self::None, + false => Self::Same, + } + } +} + +impl FetchedGroup { + /// One past the last Object ID read. + fn end(&self) -> u64 { + self.first + self.frames.len() as u64 + } +} + +/// Read group `sequence` of `track` for a FETCH, from object `skip` up to the exclusive +/// `until`, or through the end of the group without one. +/// +/// This is a [`track::Consumer::fetch_group`], so a relay fetches a miss upstream. +async fn read_fetch( + track: &track::Consumer, + sequence: u64, + skip: u64, + until: Option, + priority: u8, +) -> Result { + let fetch = group::Fetch { + priority, + frame_start: skip, + }; + let mut group = track.fetch_group(sequence, fetch).await?; + + // `fetch_group` positions the consumer at `skip`, or refuses a group that no + // longer holds it. + let first = group.index(); + let mut frames = Vec::new(); + let mut complete = false; + while until.is_none_or(|until| first + (frames.len() as u64) < until) { + match group.read_frame().await? { + Some(frame) => frames.push(frame), + None => { + complete = true; + break; + } + } + } + + Ok(FetchedGroup { + sequence, + first, + frames, + complete, + }) +} + /// A broadcast whose route table is watched for changes in what we advertise: the /// namespace becoming (un)advertisable, or its path or cost moving. struct Watched { @@ -624,26 +701,40 @@ where .await }; - // Every data stream this subscription opened is closed by now, which PUBLISH_DONE - // requires, so the count it reports is final. let completed = served.is_some(); let (res, filled) = served.unwrap_or((Ok(()), false)); - let mut streams = track_serve.opened() + u64::from(filled); // Draft-14 on carries no end location in PUBLISH_DONE: an END_OF_TRACK object is // what tells the subscriber where the track ended. A cancelled subscription is - // owed nothing more. + // owed nothing more, and one cancelled while the marker waits for stream credit + // abandons it. if completed && res.is_ok() && let Some(end) = track_serve.end() { - match track_serve.write_end_of_track(end, priority).await { - Ok(()) => streams += 1, - // A failure only costs the subscriber the early boundary. - Err(err) => tracing::debug!(%err, id = %request_id, "end of track failed"), + let mut marker = std::pin::pin!(track_serve.write_end_of_track(end, priority)); + let mut closed_session = self.session.clone(); + let written = kio::wait(|waiter| { + if let Poll::Ready(res) = waiter.poll_future(marker.as_mut()) { + return Poll::Ready(res); + } + let mut cx = std::task::Context::from_waker(waiter.waker()); + if stream.reader.poll_closed(&mut cx).is_ready() || closed_session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Err(Error::Cancel)); + } + Poll::Pending + }) + .await; + // A failure only costs the subscriber the early boundary. + if let Err(err) = written { + tracing::debug!(%err, id = %request_id, "end of track failed"); } } + // Every data stream this subscription opened is closed by now, which PUBLISH_DONE + // requires, so the count it reports is final. + let streams = track_serve.opened() + u64::from(filled); + // Send PublishDone let (status, reason) = match &res { Ok(()) => (ietf::PublishDoneStatus::TrackEnded, "track ended"), @@ -867,20 +958,13 @@ where stream, sequence, index, - std::mem::take(&mut first), + FetchPrior::next(&mut first), frame.timestamp, timescale, version, ) .await?; - stream.encode(&(frame.payload.len() as u64)).await?; - if frame.payload.is_empty() && matches!(version, Version::Draft14 | Version::Draft15) { - stream.encode(&0u64).await?; - } - if !frame.payload.is_empty() { - let mut payload = frame.payload; - stream.write_all(&mut payload).await?; - } + Self::write_fetch_payload(stream, frame.payload, version).await?; } index += 1; group.keep_alive(); @@ -912,7 +996,7 @@ where stream, sequence, index, - std::mem::take(&mut first), + FetchPrior::next(&mut first), frame.timestamp, timescale, version, @@ -958,7 +1042,7 @@ where stream: &mut Writer, sequence: u64, object: u64, - first: bool, + prior: FetchPrior, timestamp: Timestamp, timescale: Option, version: Version, @@ -983,10 +1067,10 @@ where return Ok(()); } - let header = match first { + let header = match prior { // The first object must carry its absolute Group and Object IDs. Include the // priority too: "same as the prior object" has no prior to refer to. - true => ietf::FetchObject::Object { + FetchPrior::None => ietf::FetchObject::Object { subgroup: ietf::FetchSubgroup::Zero, group: Some(sequence), object: Some(object), @@ -994,7 +1078,7 @@ where properties, }, // Same group and priority; the Object ID is the prior one plus one. - false => ietf::FetchObject::Object { + FetchPrior::Same => ietf::FetchObject::Object { subgroup: ietf::FetchSubgroup::Zero, group: None, object: None, @@ -1008,6 +1092,24 @@ where Ok(()) } + /// Write a whole fetch object's length and payload, after its header. + async fn write_fetch_payload( + stream: &mut Writer, + payload: bytes::Bytes, + version: Version, + ) -> Result<(), Error> { + stream.encode(&(payload.len() as u64)).await?; + // Draft-14 and 15 still carry a Normal status after an empty object. + if payload.is_empty() && matches!(version, Version::Draft14 | Version::Draft15) { + stream.encode(&0u64).await?; + } + if !payload.is_empty() { + let mut payload = payload; + stream.write_all(&mut payload).await?; + } + Ok(()) + } + /// Register a pending subscription until the returned guard drops. fn register_join(&self, request_id: RequestId) -> Join { self.joins.lock().insert(request_id, None); @@ -1017,166 +1119,160 @@ where } } - /// Serve the current-group prefix for a relative joining FETCH with offset zero. + /// Answer a FETCH within one group: a standalone range of the named track, or a + /// joining FETCH's prefix of its subscription's group. + /// + /// The answer is buffered before replying: FETCH_OK names where the response ends, + /// which a range running past the track only learns by reading it, and a refusal can + /// still replace it until then. async fn run_fetch_stream(mut self, mut stream: Stream, msg: ietf::Fetch<'_>) -> Result<(), Error> { + let priority = super::priority::from_wire(msg.subscriber_priority); + + // Draft-20 moved the range into LOCATION_FILTER and replaced joining FETCH with + // subscription fills; this still reads the older layout. if Filter::is_draft20(self.version) { return self .reject_fetch( stream, msg.request_id, &Error::Unsupported, - "joining FETCH removed in draft-20", + "FETCH not supported on draft-20", ) .await; } - let subscribe_id = match msg.fetch_type { - FetchType::Standalone { .. } => { - return self - .reject_fetch(stream, msg.request_id, &Error::Unsupported, "not supported") - .await; - } - FetchType::RelativeJoining { - subscriber_request_id, - group_offset, + let (track, start, end, timescale, joined) = match msg.fetch_type { + FetchType::Standalone { + namespace, + track, + start, + end, } => { - if group_offset != 0 { + // An End Object of 0 asks for the whole End Group. + let end = match end.object { + 0 => end.group.checked_add(1).map(|group| Location { group, object: 0 }), + _ => Some(end), + }; + let Some(end) = end.filter(|end| (start.group, start.object) < (end.group, end.object)) else { return self - .reject_fetch(stream, msg.request_id, &Error::Unsupported, "not supported") + .reject_fetch(stream, msg.request_id, &Error::InvalidRange, "empty range") .await; - } - subscriber_request_id + }; + + // The peer must have seen the announcement to name this namespace, so this + // resolves like a SUBSCRIBE does. + let broadcast = match self.serving_origin().await.request_broadcast(&namespace).await { + Ok(broadcast) => broadcast, + Err(err) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, + }; + let track = match broadcast.track(&track) { + Ok(track) => track, + Err(err) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, + }; + + // No SUBSCRIBE declared a timescale for this request, so its objects go + // out unstamped. + (track, start, end, None, false) } - FetchType::AbsoluteJoining { .. } => { - return self - .reject_fetch(stream, msg.request_id, &Error::Unsupported, "not supported") - .await; + FetchType::RelativeJoining { + subscriber_request_id, .. + } + | FetchType::AbsoluteJoining { + subscriber_request_id, .. + } => { + let (end, cache, timescale) = match self.joined(&mut stream, subscriber_request_id).await? { + Ok(joined) => joined, + Err((err, reason)) => return self.reject_fetch(stream, msg.request_id, &err, reason).await, + }; + let start = match msg.fetch_type { + FetchType::RelativeJoining { group_offset, .. } => end.group.saturating_sub(group_offset), + FetchType::AbsoluteJoining { group_id, .. } if group_id <= end.group => group_id, + _ => { + return self + .reject_fetch( + stream, + msg.request_id, + &Error::InvalidRange, + "joining group past the subscription", + ) + .await; + } + }; + ( + cache, + Location { + group: start, + object: 0, + }, + end, + timescale, + true, + ) } }; - // Request streams can arrive out of order. Wait on registration, while bounding - // the lifetime of a request whose subscription never arrives or resolves. - let joined = { - let mut pending = false; - let mut deadline = crate::runtime::Deadline::after(&self.runtime, Duration::from_secs(10)); + // One group per FETCH: on a relay, a range costs a serial upstream fetch per missing + // group, all buffered until FETCH_OK. Ranges wait for upstream fills by range. + let last = match end.object { + 0 => end.group - 1, + _ => end.group, + }; + if start.group != last { + return self + .reject_fetch( + stream, + msg.request_id, + &Error::Unsupported, + "FETCH spanning several groups not supported", + ) + .await; + } + let until = (end.object > 0).then_some(end.object); + + // The subscriber cancelling is the only other way this ends early, and is owed + // nothing. + let group = { + let mut read = std::pin::pin!(read_fetch(&track, start.group, start.object, until, priority)); kio::wait(|waiter| { - let mut cx = waiter.context(); - // The request reader is what the subscriber FINs or resets. The writer - // on a draft-14-16 virtual stream reports closed immediately, which is - // not a cancellation. + let mut cx = std::task::Context::from_waker(waiter.waker()); if stream.reader.poll_closed(&mut cx).is_ready() { - return Poll::Ready(Err(Error::Cancel)); - } - let joins = self.joins.poll(waiter, |joins| match joins.get(&subscribe_id) { - Some(Some(_)) => Poll::Ready(()), - Some(None) => { - pending = true; - Poll::Pending - } - None if pending => Poll::Ready(()), - None => Poll::Pending, - }); - if let Poll::Ready(joins) = joins { - return Poll::Ready(Ok(joins.get(&subscribe_id).cloned().flatten())); + return Poll::Ready(None); } - if deadline.poll(waiter).is_ready() { - return Poll::Ready(if pending { Err(Error::Timeout) } else { Ok(None) }); - } - Poll::Pending + waiter.poll_future(read.as_mut()).map(Some) }) .await }; - let joined = match joined { - Err(Error::Timeout) => { - return self - .reject_fetch(stream, msg.request_id, &Error::Timeout, "subscription not ready") - .await; - } - result => result?, + let group = match group { + Some(Ok(group)) => group, + Some(Err(err)) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, + None => return Ok(()), }; - let (end, cache, timescale) = match joined { - None => { - return self - .reject_fetch( - stream, - msg.request_id, - &if matches!( - self.version, - Version::Draft14 - | Version::Draft15 | Version::Draft16 - | Version::Draft17 | Version::Draft18 - | Version::Draft19 - ) { - Error::InvalidJoiningRequestId - } else { - Error::NotFound - }, - "no such subscription", - ) - .await; - } - Some(Joined::Unsupported) => { - if matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { - self.session.close( - crate::SessionError::ProtocolViolation.to_code(), - "joining FETCH requires Largest Object filter", - ); - return Err(Error::ProtocolViolation); - } - return self - .reject_fetch( - stream, - msg.request_id, - &Error::Unsupported, - "joining filter not supported", - ) - .await; - } - Some(Joined::Empty) => { + + let (end_location, end_of_track) = if joined { + // The subscription starts at the saved Largest Object, so the prefix of that + // group has to be here in full or the two leave a gap. + if group.end() != end.object { return self - .reject_fetch( - stream, - msg.request_id, - &Error::InvalidRange, - "no objects at subscription start", - ) + .reject_fetch(stream, msg.request_id, &Error::Evicted, "joining prefix unavailable") .await; } - Some(Joined::Group { end, cache, timescale }) => (end, cache, timescale), - }; - let priority = super::priority::from_wire(msg.subscriber_priority); - let mut group = match cache - .fetch_group( - end.group, - group::Fetch { - priority, - ..Default::default() - }, - ) - .await - { - Ok(group) => group, - Err(err) => { - return self - .reject_fetch(stream, msg.request_id, &err, "joining group unavailable") - .await; + (end, false) + } else { + let end_of_track = group.complete && track.final_sequence() == group.sequence.checked_add(1); + // A group that ends the track ends the response at its last object; otherwise + // the response ends where it was asked to. + match end_of_track { + true => ( + Location { + group: group.sequence, + object: group.end(), + }, + true, + ), + false => (end, false), } }; - // Retain the promised prefix before success: a cached group may already have - // evicted its front, and later cache eviction must not truncate this FETCH. - let mut prefix = Vec::new(); - for _ in 0..end.object { - match group.read_frame().await { - Ok(Some(frame)) => prefix.push(frame), - _ => { - return self - .reject_fetch(stream, msg.request_id, &Error::Evicted, "joining prefix unavailable") - .await; - } - } - } - // FETCH_OK on every draft, never REQUEST_OK: section 5.2 allows exactly one FETCH_OK or // REQUEST_ERROR in answer to a FETCH, and REQUEST_OK's own definition lists the other // requests it answers without ever naming this one. @@ -1189,13 +1285,16 @@ where _ => None, }, // Only draft-14 encodes it, and only as the publisher restating the order. - group_order: msg.group_order.any_to_descending(), - end_of_track: false, - end_location: end, + group_order: match msg.group_order { + GroupOrder::Descending => GroupOrder::Descending, + _ => GroupOrder::Ascending, + }, + end_of_track, + end_location, + properties: Default::default(), }) .await?; - // The FETCH owns the retained prefix, capped at the subscription snapshot. let uni = self.session.open_uni().await.map_err(Error::from_transport)?; let mut writer = Writer::new(uni, self.version); writer.set_priority(priority); @@ -1205,25 +1304,19 @@ where request_id: msg.request_id, }) .await?; - for (index, frame) in prefix.into_iter().enumerate() { + let mut first = true; + for (object, frame) in (group.first..).zip(group.frames) { Self::write_fetch_object( &mut writer, - end.group, - index as u64, - index == 0, + group.sequence, + object, + FetchPrior::next(&mut first), frame.timestamp, timescale, self.version, ) .await?; - writer.encode(&(frame.payload.len() as u64)).await?; - if frame.payload.is_empty() && matches!(self.version, Version::Draft14 | Version::Draft15) { - writer.encode(&0u64).await?; - } - if !frame.payload.is_empty() { - let mut payload = frame.payload; - writer.write_all(&mut payload).await?; - } + Self::write_fetch_payload(&mut writer, frame.payload, self.version).await?; } writer.close().await?; @@ -1235,6 +1328,76 @@ where Ok(()) } + /// Resolve the subscription a joining FETCH names to its saved start, or the refusal + /// to answer the FETCH with. + async fn joined( + &mut self, + stream: &mut Stream, + subscribe_id: RequestId, + ) -> Result), (Error, &'static str)>, Error> { + // Request streams can arrive out of order. Wait on registration, while bounding + // the lifetime of a request whose subscription never arrives or resolves. + let joined = { + let mut pending = false; + let mut deadline = crate::runtime::Deadline::after(&self.runtime, Duration::from_secs(10)); + kio::wait(|waiter| { + let mut cx = waiter.context(); + // The request reader is what the subscriber FINs or resets. The writer + // on a draft-14-16 virtual stream reports closed immediately, which is + // not a cancellation. + if stream.reader.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Err(Error::Cancel)); + } + let joins = self.joins.poll(waiter, |joins| match joins.get(&subscribe_id) { + Some(Some(_)) => Poll::Ready(()), + Some(None) => { + pending = true; + Poll::Pending + } + None if pending => Poll::Ready(()), + None => Poll::Pending, + }); + if let Poll::Ready(joins) = joins { + return Poll::Ready(Ok(joins.get(&subscribe_id).cloned().flatten())); + } + if deadline.poll(waiter).is_ready() { + return Poll::Ready(if pending { Err(Error::Timeout) } else { Ok(None) }); + } + Poll::Pending + }) + .await + }; + let refusal = match joined { + Err(Error::Timeout) => (Error::Timeout, "subscription not ready"), + Err(err) => return Err(err), + Ok(Some(Joined::Group { end, cache, timescale })) => return Ok(Ok((end, cache, timescale))), + Ok(None) => ( + match self.version { + Version::Draft14 + | Version::Draft15 + | Version::Draft16 + | Version::Draft17 + | Version::Draft18 + | Version::Draft19 => Error::InvalidJoiningRequestId, + _ => Error::NotFound, + }, + "no such subscription", + ), + Ok(Some(Joined::Unsupported)) => { + if matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { + self.session.close( + crate::SessionError::ProtocolViolation.to_code(), + "joining FETCH requires Largest Object filter", + ); + return Err(Error::ProtocolViolation); + } + (Error::Unsupported, "joining filter not supported") + } + Ok(Some(Joined::Empty)) => (Error::InvalidRange, "no objects at subscription start"), + }; + Ok(Err(refusal)) + } + async fn reject_track_status(&self, mut stream: Stream, request_id: RequestId) -> Result<(), Error> { let error_code = request::to_code(&Error::Unsupported, request::Kind::TrackStatus, self.version); if self.version == Version::Draft14 { @@ -1387,7 +1550,7 @@ where (true, Some(_)) => { tracing::debug!(broadcast = %absolute, "publish_namespace update"); refused = self - .update_namespace(target, requests, path, suffix, &watch.sent, &advert) + .update_namespace(target, requests, suffix, &watch.sent, &advert) .await?; } (true, None) => { @@ -1529,7 +1692,7 @@ where Ok(Refused::No) } - /// Reprice a namespace the peer holds: REQUEST_UPDATE on the request that carries + /// Update a namespace the peer holds: REQUEST_UPDATE on the request that carries /// it, with only the parameters that changed, then its answer. /// /// Waiting for the answer keeps one update outstanding per stream, which satisfies @@ -1540,16 +1703,14 @@ where /// is dropped the same way, since a peer that ignored it cannot be assumed to hold /// either price. /// - /// A different original publisher is not an update. The cluster draft has it - /// withdrawn and advertised again, so the receiver never reads two publishers' - /// content as one continuous stream. + /// A different original publisher is an update like any other: the receiver + /// drains what it already serves from the old one and never splices the two. /// /// Returns what the refusal, if any, said about coming back. async fn update_namespace( &self, target: &mut Target, requests: &mut HashMap>, - path: &crate::PathOwned, suffix: &crate::PathOwned, held: &Advert, advert: &Advert, @@ -1559,13 +1720,6 @@ where let (Some(next), Some(held)) = (advert.params(), held.params()) else { return Ok(Refused::No); }; - if held.hops.hops().iter().next() != next.hops.hops().iter().next() { - tracing::debug!(broadcast = %self.origin.absolute(path), "publisher changed; advertising again"); - self.withdraw_namespace(target, requests, suffix.clone()).await?; - return self - .advertise_namespace(requests, path, suffix.clone(), Some(next)) - .await; - } let Some(request) = requests.get_mut(suffix) else { return Ok(Refused::No); }; @@ -1754,7 +1908,9 @@ where // Split horizon, as the solicited loop applies it: never advertise a route back // to the peer it came from. - let origin = self.excluding(&peer); + let origin = self + .excluding(&peer) + .discovery(!self.peer_setup.get().await.hidden || self.origin.includes_hidden()); let ns = Namespaces::new(peer, Target::Requests(None)); self.run_namespaces(origin.announced(), crate::Path::empty().to_owned(), ns, Vec::new()) @@ -1802,12 +1958,9 @@ where // the source we are currently advertising to that peer. let origin = origin.excluding(self.exclude(&peer)); - // Hidden namespaces are left out unless the peer opted in (MoQ Hidden). A publish + // Peers that declared MoQ Hidden filter namespaces unless they opted in. A publish // origin that already opted in (the caller's choice for this peer) keeps them. - let origin = match msg.hidden { - true => origin.with_hidden(true), - false => origin, - }; + let origin = origin.discovery(!declared.hidden || msg.hidden || self.origin.includes_hidden()); // Unless the peer asked to be told only on request, it has already heard what an // unsolicited PUBLISH_NAMESPACE can say. Repeating it here would leave it holding @@ -1816,8 +1969,8 @@ where // until the peer is done with it. let origin = match declared.solicit.unwrap_or(false) { true => origin, - false if self.origin.includes_hidden() => origin.empty(), - false => origin.beyond(&self.origin), + false if !declared.hidden || self.origin.includes_hidden() => origin.empty(), + false => origin.beyond(&self.origin.clone().discovery(false)), }; let mut announced = origin.announced(); @@ -2065,6 +2218,9 @@ struct TrackServe { opened: Arc, /// The track's exclusive end, once its groups ran out because it finished. end: Option, + /// Serve the track's datagrams too, as OBJECT_DATAGRAMs. Off when the transport has no + /// datagrams; there is no stream fallback. + datagrams: bool, } impl TrackServe { @@ -2085,8 +2241,10 @@ impl TrackServe { } } track.end_at(range.end.map_or(Bound::Unbounded, |end| Bound::Included(end.group))); + let datagrams = session.max_datagram_size() > 0; Self { + datagrams, session, track, request_id, @@ -2117,11 +2275,13 @@ impl TrackServe { /// the group that will never exist. /// /// The last group's stream has usually finished before the track ends, so the marker - /// cannot ride on it. The stream counts toward PUBLISH_DONE once it is open. + /// cannot ride on it. Like a group stream, it counts toward PUBLISH_DONE once open, + /// since a reset can still deliver its header. async fn write_end_of_track(&mut self, end: u64, priority: u8) -> Result<(), Error> { let mut stream = std::future::poll_fn(|cx| self.session.poll_open_uni(cx)) .await .map_err(Error::from_transport)?; + self.opened.fetch_add(1, Ordering::Relaxed); stream.set_priority(priority.into()); let mut writer = Writer::new(stream, self.version); @@ -2198,6 +2358,8 @@ impl TrackServe { ); } Poll::Ready(Ok(None)) => { + // Datagrams written before the track finished still go out. + self.poll_datagrams(waiter); self.draining = true; if let Poll::Ready(Ok(end)) = self.track.poll_finished(waiter) { self.end = Some(end); @@ -2208,10 +2370,59 @@ impl TrackServe { Poll::Pending => break, } } + // Groups first, so a burst of datagrams cannot starve them. + self.poll_datagrams(waiter); // Newly created group machines start now rather than on the next wake. let _ = self.children.poll(waiter); Poll::Pending } + + /// Send every buffered datagram as an OBJECT_DATAGRAM, best-effort, like moq-lite. + /// + /// A datagram is Object 0 of a group that has no other, so the Object ends its group. + /// The track's end or failure surfaces through its groups, so this only stops. + fn poll_datagrams(&mut self, waiter: &kio::Waiter) { + if !self.datagrams { + return; + } + while let Poll::Ready(Ok(Some(datagram))) = self.track.poll_recv_datagram(waiter) { + let sequence = datagram.sequence; + let properties = match self.timescale { + Some(timescale) => { + let mut properties = Vec::new(); + if ietf::encode_object_time(&mut properties, datagram.timestamp, timescale, self.version).is_err() { + continue; + } + Some(properties) + } + None => None, + }; + let body = ietf::ObjectDatagram { + track_alias: self.request_id.0, + group_id: sequence, + object_id: None, + publisher_priority: Some(super::priority::to_wire(self.track.info().priority)), + end_of_group: true, + properties, + body: ietf::DatagramBody::Payload(datagram.payload), + }; + let Ok(body) = body.encode_bytes(self.version) else { + continue; + }; + + let max = self.session.max_datagram_size(); + if body.len() > max { + tracing::debug!( + sequence, + size = body.len(), + max, + "dropping datagram larger than the transport limit" + ); + continue; + } + let _ = self.session.send_datagram(&body); + } + } } /// Serves one group on its own unidirectional stream in the moq-transport @@ -2245,7 +2456,7 @@ enum GroupState { batch_pos: usize, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a - /// late cancel can still reset the stream. + /// late cancel or expiry can still reset the stream. Closed { writer: Writer, }, @@ -2455,7 +2666,17 @@ impl GroupServe { // Wait until everything is acknowledged by the peer so we can still // cancel the stream. poll_close releases the stream on completion so // the Drop fallback cannot reset the acknowledged stream. - let res = ready!(writer.poll_close(&mut cx)); + let res = match writer.poll_close(&mut cx) { + Poll::Ready(res) => res, + // Those bytes still hold the connection until acknowledged, so a + // group gone stale meanwhile releases them like one still serving: + // dropping the writer resets the stream. + Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + self.state = GroupState::Done; + return Poll::Ready(Err(Error::Old)); + } + Poll::Pending => return Poll::Pending, + }; let sequence = self.msg.group_id; self.state = GroupState::Done; return Poll::Ready(res.map(|()| { @@ -2583,10 +2804,31 @@ mod group_priority_test { /// every moq-transport peer. #[tokio::test] async fn group_header_carries_the_publisher_priority() { + let header = serve_group_header(track::Info::default().with_priority(hang_audio_priority())).await; + assert_eq!( + header.publisher_priority, + priority::to_wire(hang_audio_priority()), + "the wire is lower-first, so audio must encode below video" + ); + assert!( + priority::to_wire(hang_audio_priority()) < priority::to_wire(hang_video_priority()), + "audio outranks video on the wire" + ); + } + + /// A track that never set a priority is the draft's usual publisher priority, 128, + /// not 255, the least urgent value a peer like moxygen would deprioritize. + #[tokio::test] + async fn group_header_defaults_to_the_midpoint() { + let header = serve_group_header(track::Info::default()).await; + assert_eq!(header.publisher_priority, 128); + } + + /// Serve one group of a track with `info` and decode the subgroup header it opens with. + async fn serve_group_header(info: track::Info) -> ietf::GroupHeader { let log = crate::lite::test_transport::Log::default(); let session = SinkSession::new(log.clone()); - let info = track::Info::default().with_priority(hang_audio_priority()); let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", info); let subscriber = track.subscribe(None); @@ -2607,35 +2849,71 @@ mod group_priority_test { let written = log.writes.lock().unwrap().clone(); let mut buf = bytes::Bytes::from(written); - let header = ietf::GroupHeader::decode(&mut buf, Version::Draft14).expect("a group header"); - assert_eq!( - header.publisher_priority, - priority::to_wire(hang_audio_priority()), - "the wire is lower-first, so audio must encode below video" + ietf::GroupHeader::decode(&mut buf, Version::Draft14).expect("a group header") + } + + /// `hang::catalog::PRIORITY` isn't reachable from `moq-net` (hang depends on it, not the + /// other way round), so the two ranks it publishes audio and video at are spelled here. + fn hang_audio_priority() -> u8 { + 80 + } + + fn hang_video_priority() -> u8 { + 60 + } + + /// A subgroup waiting for stream credit keeps its subscription expiry armed. + #[tokio::test] + async fn group_waiting_for_stream_credit_expires() { + tokio::time::pause(); + + let gate = kio::Producer::new(false); + let session = SinkSession::gated_open_uni(gate.consume()); + let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(crate::Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let mut serve = GroupServe::new( + session, + ietf::GroupHeader { + track_alias: 0, + group_id: 0, + sub_group_id: 0, + publisher_priority: 0, + flags: Default::default(), + }, + 0, + group, + Some(Timescale::default()), + Version::Draft19, + GroupSlice::default(), ); + let mut serving = std::pin::pin!(kio::wait(|waiter| serve.poll_serve(waiter))); assert!( - priority::to_wire(hang_audio_priority()) < priority::to_wire(hang_video_priority()), - "audio outranks video on the wire" + futures::poll!(serving.as_mut()).is_pending(), + "stream credit is exhausted" ); - } - /// `hang::catalog::PRIORITY` isn't reachable from `moq-net` (hang depends on it, not the - /// other way round), so the two ranks it publishes audio and video at are spelled here. - fn hang_audio_priority() -> u8 { - 80 - } + tokio::time::advance(Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(crate::Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); - fn hang_video_priority() -> u8 { - 60 + assert!(matches!(serving.await, Err(Error::Old))); } - /// A subgroup waiting for stream credit keeps its subscription expiry armed. + /// A FIN holds the subgroup's bytes until the peer acknowledges it, so a subgroup + /// that goes stale while waiting still expires instead of pinning them. #[tokio::test] - async fn group_waiting_for_stream_credit_expires() { + async fn unacknowledged_fin_expires_with_the_group() { tokio::time::pause(); - let gate = kio::Producer::new(false); - let session = SinkSession::gated_open_uni(gate.consume()); + let session = SinkSession::new(Default::default()).with_unacked_fin(); + let log = session.log.clone(); let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", None); let mut subscriber = track.subscribe(None); let mut old = track.append_group().unwrap(); @@ -2661,8 +2939,9 @@ mod group_priority_test { let mut serving = std::pin::pin!(kio::wait(|waiter| serve.poll_serve(waiter))); assert!( futures::poll!(serving.as_mut()).is_pending(), - "stream credit is exhausted" + "the FIN is unacknowledged" ); + assert!(log.resets().is_empty()); tokio::time::advance(Duration::from_secs(1)).await; let mut edge = track.append_group().unwrap(); @@ -2670,7 +2949,8 @@ mod group_priority_test { .unwrap(); edge.finish().unwrap(); - assert!(matches!(serving.await, Err(Error::Old))); + assert!(matches!(futures::poll!(serving.as_mut()), Poll::Ready(Err(Error::Old)))); + assert_eq!(log.resets(), vec![crate::StreamError::Cancel.to_code()]); } /// The final payload remains guarded after its frame has advanced the group cursor. @@ -3552,6 +3832,337 @@ mod serve_tests { assert!(buf.is_empty()); } + /// Every draft that carries a standalone FETCH. + const FETCH_DRAFTS: [Version; 6] = [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft18, + Version::Draft19, + ]; + + /// Groups `0..count`, each holding `g-0` and `g-1`, skipping `hole`. + fn publish_pairs(h: &mut Serve, count: u64, hole: Option) { + for sequence in (0..count).filter(|sequence| Some(*sequence) != hole) { + let mut group = h.track.create_group(group::Info { sequence }).unwrap(); + for object in 0..2 { + group + .write_frame(timestamp(), format!("{sequence}-{object}").into_bytes()) + .unwrap(); + } + group.finish().unwrap(); + } + } + + /// Run a standalone FETCH of `room/video`, returning what the peer reads back. + async fn standalone_fetch(h: &Serve, start: Location, end: Location, group_order: GroupOrder) -> bytes::Bytes { + let version = h.publisher.version; + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .run_fetch_stream( + stream, + ietf::Fetch { + request_id: FETCH_ID, + subscriber_priority: 128, + group_order, + fetch_type: FetchType::Standalone { + namespace: crate::Path::new("room"), + track: "video".into(), + start, + end, + }, + }, + ) + .await + .unwrap(); + bytes::Bytes::from(h.log.writes.lock().unwrap()[mark..].to_vec()) + } + + /// Decode a FETCH_OK and the fetch stream after it, as `(group, object, payload)`. + fn fetch_answer(mut buf: bytes::Bytes, version: Version) -> (ietf::FetchOk, Vec<(u64, u64, String)>) { + assert_eq!( + u64::decode(&mut buf, version).unwrap(), + ietf::FetchOk::ID, + "{version}: not a FETCH_OK" + ); + let ok = ietf::FetchOk::decode(&mut buf, version).unwrap(); + assert_eq!(u64::decode(&mut buf, version).unwrap(), FetchHeader::TYPE); + assert_eq!(FetchHeader::decode(&mut buf, version).unwrap().request_id, FETCH_ID); + + let mut objects = Vec::new(); + let mut prior: Option<(u64, u64)> = None; + while !buf.is_empty() { + let (group, object) = if version == Version::Draft14 { + let group = u64::decode(&mut buf, version).unwrap(); + assert_eq!(u64::decode(&mut buf, version).unwrap(), 0, "subgroup"); + let object = u64::decode(&mut buf, version).unwrap(); + let _priority = u8::decode(&mut buf, version).unwrap(); + let _properties = Vec::::decode(&mut buf, version).unwrap(); + (group, object) + } else { + let ietf::FetchObject::Object { group, object, .. } = + ietf::FetchObject::decode(&mut buf, version).unwrap() + else { + panic!("{version}: unexpected End of Range"); + }; + match (prior, group) { + (None, group) => (group.unwrap(), object.unwrap()), + // No Group ID: the same group, and an absent Object ID Delta is one. + (Some((group, prior)), None) => (group, prior + object.unwrap_or(1)), + (Some((prior, _)), Some(group)) => { + let group = match version { + Version::Draft15 | Version::Draft16 | Version::Draft17 => group, + _ => prior + group + 1, + }; + (group, object.unwrap()) + } + } + }; + let size = u64::decode(&mut buf, version).unwrap() as usize; + let payload = String::from_utf8(buf.split_to(size).to_vec()).unwrap(); + objects.push((group, object, payload)); + prior = Some((group, object)); + } + (ok, objects) + } + + /// The `(group, object, payload)` a range of two-frame groups holds. + fn pairs(groups: impl IntoIterator) -> Vec<(u64, u64, String)> { + groups + .into_iter() + .flat_map(|group| (0..2).map(move |object| (group, object, format!("{group}-{object}")))) + .collect() + } + + /// A whole group is answered on one fetch stream. + #[tokio::test] + async fn a_standalone_fetch_serves_one_whole_group() { + for version in FETCH_DRAFTS { + let mut h = serve(version); + publish_pairs(&mut h, 5, None); + settle().await; + + // An End Object of 0 asks for the whole End Group. + let buf = standalone_fetch( + &h, + Location { group: 2, object: 0 }, + Location { group: 2, object: 0 }, + GroupOrder::Ascending, + ) + .await; + let (ok, objects) = fetch_answer(buf, version); + assert_eq!(ok.end_location, Location { group: 3, object: 0 }, "{version}"); + assert!(!ok.end_of_track, "{version}"); + assert_eq!(objects, pairs([2]), "{version}"); + assert!(h.log.resets().is_empty(), "{version}"); + } + } + + /// The last group of a finished track ends the response one past its last object, + /// with End of Track set. + #[tokio::test] + async fn a_standalone_fetch_of_the_last_group_reports_the_end_of_track() { + for version in FETCH_DRAFTS { + let mut h = serve(version); + publish_pairs(&mut h, 5, None); + h.track.finish().unwrap(); + settle().await; + + let buf = standalone_fetch( + &h, + Location { group: 4, object: 1 }, + Location { group: 4, object: 0 }, + GroupOrder::Any, + ) + .await; + let (ok, objects) = fetch_answer(buf, version); + assert_eq!(ok.end_location, Location { group: 4, object: 2 }, "{version}"); + assert!(ok.end_of_track, "{version}"); + assert_eq!(objects, pairs([4])[1..].to_vec(), "{version}"); + } + } + + /// Draft-20 carries the range in LOCATION_FILTER, which is not read yet. + #[tokio::test] + async fn a_draft20_fetch_is_refused() { + for version in [Version::Draft20, Version::Draft21, Version::Draft22] { + let mut h = serve(version); + publish_pairs(&mut h, 3, None); + settle().await; + + let buf = standalone_fetch( + &h, + Location { group: 1, object: 0 }, + Location { group: 1, object: 0 }, + GroupOrder::Ascending, + ) + .await; + assert_eq!(fetch_refusal(buf, version), 0x3, "{version}"); + } + } + + /// A range touching several groups is refused, in either order: on a relay each + /// missing group would be its own upstream fetch. + #[tokio::test] + async fn a_standalone_fetch_of_several_groups_is_refused() { + for version in FETCH_DRAFTS { + for order in [GroupOrder::Ascending, GroupOrder::Descending] { + let mut h = serve(version); + publish_pairs(&mut h, 3, None); + settle().await; + + let buf = standalone_fetch( + &h, + Location { group: 0, object: 1 }, + Location { group: 1, object: 1 }, + order, + ) + .await; + assert_eq!(fetch_refusal(buf, version), 0x3, "{version}"); + } + } + } + + /// Read a REQUEST_ERROR (or draft-14 FETCH_ERROR) off a refused FETCH, as its code. + fn fetch_refusal(mut buf: bytes::Bytes, version: Version) -> u64 { + let id = u64::decode(&mut buf, version).unwrap(); + let code = match version { + Version::Draft14 => { + assert_eq!(id, ietf::FetchError::ID); + ietf::FetchError::decode(&mut buf, version).unwrap().error_code + } + _ => { + assert_eq!(id, ietf::RequestError::ID); + ietf::RequestError::decode(&mut buf, version).unwrap().error_code + } + }; + assert!(buf.is_empty(), "{version}: a refusal opens no fetch stream"); + code + } + + /// A group that does not exist, below the newest one or past it, is refused. + #[tokio::test] + async fn a_standalone_fetch_of_a_missing_group_is_refused() { + for version in FETCH_DRAFTS { + for missing in [2, 5] { + let mut h = serve(version); + publish_pairs(&mut h, 4, Some(2)); + settle().await; + + let buf = standalone_fetch( + &h, + Location { + group: missing, + object: 0, + }, + Location { + group: missing, + object: 0, + }, + GroupOrder::Ascending, + ) + .await; + assert_eq!( + fetch_refusal(buf, version), + does_not_exist(version), + "{version}: group {missing}" + ); + } + } + } + + /// A joining FETCH reaching back before the subscription's group is refused, like any + /// FETCH touching several groups. + #[tokio::test] + async fn a_joining_fetch_reaching_back_is_refused() { + for version in JOINING_DRAFTS { + let mut h = serve(version); + publish_pairs(&mut h, 4, None); + let mut group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); + group.write_frame(timestamp(), b"4-0".as_slice()).unwrap(); + settle().await; + + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let mut serving = std::pin::pin!( + h.publisher + .clone() + .run_subscribe_stream(stream, subscribe(Filter::NextObject, None)) + ); + registered(&h, serving.as_mut()).await; + + for fetch_type in [ + FetchType::RelativeJoining { + subscriber_request_id: RequestId(REQUEST_ID), + group_offset: 2, + }, + FetchType::AbsoluteJoining { + subscriber_request_id: RequestId(REQUEST_ID), + group_id: 1, + }, + ] { + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .run_fetch_stream( + stream, + ietf::Fetch { + request_id: FETCH_ID, + subscriber_priority: 128, + group_order: GroupOrder::Ascending, + fetch_type, + }, + ) + .await + .unwrap(); + let buf = bytes::Bytes::from(h.log.writes.lock().unwrap()[mark..].to_vec()); + + assert_eq!(fetch_refusal(buf, version), 0x3, "{version}"); + } + } + } + + /// An absolute joining FETCH starting past the subscription's group names an empty range. + #[tokio::test] + async fn an_absolute_joining_fetch_past_the_subscription_is_refused() { + let version = Version::Draft16; + let mut h = serve(version); + publish_pairs(&mut h, 3, None); + settle().await; + + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let mut serving = std::pin::pin!( + h.publisher + .clone() + .run_subscribe_stream(stream, subscribe(Filter::NextObject, None)) + ); + registered(&h, serving.as_mut()).await; + + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .run_fetch_stream( + stream, + ietf::Fetch { + request_id: FETCH_ID, + subscriber_priority: 128, + group_order: GroupOrder::Ascending, + fetch_type: FetchType::AbsoluteJoining { + subscriber_request_id: RequestId(REQUEST_ID), + group_id: 5, + }, + }, + ) + .await + .unwrap(); + let buf = bytes::Bytes::from(h.log.writes.lock().unwrap()[mark..].to_vec()); + assert_eq!(fetch_refusal(buf, version), invalid_range(version)); + } + /// A fill against an empty track has an empty range: no fetch stream is owed. #[tokio::test] async fn an_empty_track_opens_no_fill_stream() { @@ -4375,19 +4986,47 @@ mod tests { /// 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) { - let log = advertise_with_hidden(solicit, "", false).await; + let log = advertise_with_hidden(Discovery { + solicit, + ..Discovery::default() + }) + .await; (occurrences(&log, b"cam"), log.bi_opens()) } /// [`advertise_both_ways`] with a hidden `.stats/node` beside `cam`, and the peer's /// SUBSCRIBE_NAMESPACE for `prefix` opting in to hidden namespaces or not. - async fn advertise_with_hidden( + struct Discovery<'a> { + version: Version, + declared: bool, solicit: Option, - prefix: &str, + prefix: &'a str, hidden: bool, - ) -> crate::lite::test_transport::Log { - const VERSION: Version = Version::Draft17; + scoped: bool, + } + + impl Default for Discovery<'_> { + fn default() -> Self { + Self { + version: Version::Draft17, + declared: true, + solicit: Some(true), + prefix: "", + hidden: false, + scoped: false, + } + } + } + async fn advertise_with_hidden(case: Discovery<'_>) -> crate::lite::test_transport::Log { + let Discovery { + version, + declared: hidden_declared, + solicit, + prefix, + hidden, + scoped, + } = case; let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); let _cam = origin.announce("cam", crate::origin::Route::default()).unwrap(); let _stats = origin.announce(".stats/node", crate::origin::Route::default()).unwrap(); @@ -4397,21 +5036,34 @@ mod tests { // PUBLISH_NAMESPACE request. let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![ Vec::new(), - publish_namespace_ok(VERSION).await, + publish_namespace_ok(version).await, ]); let log = session.log.clone(); + let setup = peer::PeerSetup::default(); + setup.set(peer::Peer { + solicit, + hidden: hidden_declared, + ..Default::default() + }); + let consume = match scoped { + true => origin + .consume() + .scope("", &crate::Pattern::subtree(".stats").unwrap().into()) + .unwrap(), + false => origin.consume(), + }; let publisher = Publisher::new( crate::time::Clock::tokio(), session.clone(), - origin.consume(), + consume, Control::new(None, false), None, - declared(solicit), - VERSION, + setup, + version, ); - let stream = Stream::open(&mut session.clone(), VERSION).await.unwrap(); + let stream = Stream::open(&mut session.clone(), version).await.unwrap(); let msg = ietf::SubscribeNamespace { request_id: RequestId(1), namespace: crate::Path::new(prefix), @@ -4449,7 +5101,13 @@ mod tests { (Some(true), "", true, 1, 1), (Some(true), ".stats", false, 0, 1), ] { - let log = advertise_with_hidden(solicit, prefix, hidden).await; + let log = advertise_with_hidden(Discovery { + solicit, + prefix, + hidden, + ..Discovery::default() + }) + .await; let case = format!("solicit {solicit:?}, prefix {prefix:?}, hidden {hidden}"); assert_eq!(occurrences(&log, b"cam"), cam, "{case}"); // An inline entry names its suffix, so count the leaf. @@ -4457,6 +5115,41 @@ mod tests { } } + #[tokio::test(start_paused = true)] + async fn hidden_discovery_obeys_peer_setup_and_requested_prefix() { + for version in [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft19, + Version::Draft22, + ] { + for declared in [false, true] { + for solicit in [Some(false), Some(true)] { + for scoped in [false, true] { + for (prefix, hidden) in [("", false), ("", true), (".stats", false)] { + let log = advertise_with_hidden(Discovery { + version, + declared, + solicit, + prefix, + hidden, + scoped, + }) + .await; + let expected = usize::from(!declared || hidden || prefix == ".stats"); + assert_eq!( + occurrences(&log, b"node"), + expected, + "{version:?}: declared={declared}, solicit={solicit:?}, scoped={scoped}, prefix={prefix}, hidden={hidden}" + ); + } + } + } + } + } + } + /// 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. @@ -4688,7 +5381,12 @@ mod tests { async fn a_repricing_is_a_request_update() { const VERSION: Version = Version::Draft19; - let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + // Forward the update at once: the hold is not what this checks. + let origin = crate::origin::Config { + update_hold: Duration::ZERO, + ..crate::origin::Config::new(crate::Hop::new(1).unwrap()) + } + .produce(); let _cold = origin .announce("cam", crate::origin::Route::default().with_cost(4)) .unwrap(); @@ -4811,14 +5509,19 @@ mod tests { assert!(log.closes().iter().any(|(c, _)| *c == code), "{:?}", log.closes()); } - /// A route from a different original publisher is not an update: its content is not - /// continuous with what the peer holds, so the draft has the advertisement withdrawn - /// and made again rather than repriced in place. + /// A route from a different original publisher updates the advertisement in place, + /// like any other change: withdrawing it would make the namespace briefly vanish + /// downstream just because its publisher moved. #[tokio::test] - async fn a_publisher_change_is_withdrawn_and_advertised_again() { + async fn a_publisher_change_is_a_request_update() { const VERSION: Version = Version::Draft19; - let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + // Forward the update at once: the hold is not what this checks. + let origin = crate::origin::Config { + update_hold: Duration::ZERO, + ..crate::origin::Config::new(crate::Hop::new(1).unwrap()) + } + .produce(); let publisher_a = crate::Hops::try_from(vec![crate::Hop::new(7).unwrap()]).unwrap(); let publisher_b = crate::Hops::try_from(vec![crate::Hop::new(8).unwrap()]).unwrap(); let _from_a = origin @@ -4829,9 +5532,9 @@ mod tests { .unwrap(); settle().await; - // Stream 1 accepts the advertisement from A; stream 2 accepts the one from B. + // One stream: the advertisement from A and its update to B, each answered OK. let ok = publish_namespace_ok(VERSION).await; - let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![ok.clone(), ok]); + let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![[ok.clone(), ok].concat()]); let log = session.log.clone(); let publisher = Publisher::new( @@ -4861,16 +5564,6 @@ mod tests { crate::origin::Route::default().with_hops(publisher_b).with_cost(0), ) .unwrap(); - for _ in 0..100 { - assert!(futures::poll!(run.as_mut()).is_pending()); - if occurrences(&log, b"cam") >= 2 { - break; - } - settle().await; - } - - assert_eq!(occurrences(&log, b"cam"), 2, "advertised again for the new publisher"); - assert_eq!(log.bi_opens(), 2, "on a fresh request stream"); let update = request_update( VERSION, &ietf::PublishNamespaceUpdate { @@ -4882,7 +5575,17 @@ mod tests { }, ) .await; - assert_eq!(occurrences(&log, &update), 0, "a publisher change is never an update"); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, &update) >= 1 { + break; + } + settle().await; + } + + assert_eq!(occurrences(&log, &update), 1, "REQUEST_UPDATE carrying B's path"); + assert_eq!(occurrences(&log, b"cam"), 1, "PUBLISH_NAMESPACE was not repeated"); + assert_eq!(log.bi_opens(), 1, "no withdrawal and no second stream"); } /// A peer that refuses an update closes the stream, which withdraws the @@ -5222,8 +5925,8 @@ mod tests { (writes, h.log.resets()) } - /// Send a FETCH we don't implement, returning the same pair. - async fn fetch_unsupported(version: Version, fetch_type: FetchType<'_>) -> (Vec, Vec) { + /// Send a FETCH we refuse, returning the same pair. + async fn fetch_refused(version: Version, fetch_type: FetchType<'_>) -> (Vec, Vec) { let h = harness(version); let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); @@ -5267,8 +5970,8 @@ mod tests { /// Every FETCH we refuse goes out through its own error encoder, so it needs the same /// finish: a reset there loses the rejection the same way. #[tokio::test] - async fn unsupported_fetch_is_refused_without_resetting_the_stream() { - let unsupported = || { + async fn a_refused_fetch_does_not_reset_the_stream() { + let refused = || { [ ( "standalone", @@ -5280,25 +5983,20 @@ mod tests { }, ), ( - "relative joining with an offset", - FetchType::RelativeJoining { - subscriber_request_id: RequestId(3), - group_offset: 1, - }, - ), - ( - "absolute joining", - FetchType::AbsoluteJoining { - subscriber_request_id: RequestId(3), - group_id: 7, + "empty range", + FetchType::Standalone { + namespace: crate::Path::new("nothing/here"), + track: "video".into(), + start: Location { group: 2, object: 0 }, + end: Location { group: 1, object: 0 }, }, ), ] }; for version in [Version::Draft17, Version::Draft18, Version::Draft19, Version::Draft20] { - for (label, fetch_type) in unsupported() { - let (writes, resets) = fetch_unsupported(version, fetch_type).await; + for (label, fetch_type) in refused() { + let (writes, resets) = fetch_refused(version, fetch_type).await; assert!(!writes.is_empty(), "{version} {label}: nothing was sent"); assert_eq!( diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index 3b35bce5d10..75c5d0e25f4 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -56,6 +56,9 @@ pub struct Config { /// transports). A server passes `None`. pub path: Option, + /// The URI authority we advertise in our SETUP, under the same rules as `path`. + pub authority: Option, + /// The peer's SETUP stream, when it was already read before [`start`] (a draft-17+ /// server that gated on the client's path via [`accept_setup`]). It becomes the /// GOAWAY channel; `None` lets the uni loop read the SETUP itself. @@ -94,6 +97,7 @@ where cost, version, path, + authority, peer_setup_stream, peer_declared, } = config; @@ -222,6 +226,7 @@ where subscriber.clone(), version ))); + let mut datagrams = std::pin::pin!(err_only(run_datagrams(adapter.clone(), subscriber.clone()))); // 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())); @@ -270,6 +275,9 @@ where if let Poll::Ready(err) = waiter.poll_future(dispatch.as_mut()) { return Poll::Ready(Err(err)); } + if let Poll::Ready(err) = waiter.poll_future(datagrams.as_mut()) { + return Poll::Ready(Err(err)); + } if task_set.poll(waiter).is_ready() { return Poll::Ready(Ok(())); } @@ -295,7 +303,9 @@ where let session = session.clone(); let goaway = goaway.clone(); async move { - if let Err(err) = run_setup(runtime, session, version, path, self_origin, cost, goaway).await { + if let Err(err) = + run_setup(runtime, session, version, path, authority, self_origin, cost, goaway).await + { tracing::warn!(%err, "setup send error"); } std::future::pending::<()>().await; @@ -362,6 +372,7 @@ where subscriber.clone(), version ))); + let mut datagrams = std::pin::pin!(err_only(run_datagrams(session.clone(), subscriber.clone()))); 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; @@ -400,6 +411,9 @@ where if let Poll::Ready(err) = waiter.poll_future(dispatch.as_mut()) { return Poll::Ready(Err(err)); } + if let Poll::Ready(err) = waiter.poll_future(datagrams.as_mut()) { + return Poll::Ready(Err(err)); + } if let Poll::Ready(err) = waiter.poll_future(goaway_recv.as_mut()) { return Poll::Ready(Err(err)); } @@ -427,8 +441,8 @@ where }; match &res { - Err(Error::Transport(_)) => { - tracing::info!("session terminated"); + Err(err @ Error::Transport(_)) => { + tracing::info!(%err, "session terminated"); session.close(SessionError::Internal.to_code(), ""); } Err(err) => { @@ -552,11 +566,13 @@ fn peer_from_params(params: &ietf::Parameters, version: Version) -> Result( runtime: crate::time::Clock, mut session: S, version: Version, path: Option, + authority: Option, self_origin: Hop, cost: Option, goaway: crate::goaway::Protocol, @@ -571,6 +587,9 @@ async fn run_setup( if let Some(path) = path { parameters.set_bytes(ietf::ParameterBytes::Path, path.into_bytes()); } + if let Some(authority) = authority { + parameters.set_bytes(ietf::ParameterBytes::Authority, authority.into_bytes()); + } cluster::peer_into_setup(&mut parameters, self_origin, cost, version); solicit::into_setup(&mut parameters, version); hidden::into_setup(&mut parameters, version); @@ -662,6 +681,12 @@ where // the peer wrote to. Failing the loop here would tear down the whole session // over a single stream the peer had already given up on. Only death is // tolerated: bytes that arrive and do not parse stay session-fatal. + // + // A transport error counts as death too. A reset whose code the transport cannot + // place in the stream registry surfaces as one: over raw QUIC a moq-transport + // peer resets with its own codes (moxygen's CANCELLED is 0x1), which the + // WebTransport code mapping rejects. If the connection itself died, the next + // accept reports it. let kind: u64 = match tasks .drive(|waiter| { let mut cx = waiter.context(); @@ -670,7 +695,13 @@ where .await { Ok(kind) => kind, - Err(err @ (Error::Cancel | Error::Stream(_) | Error::Remote(_) | Error::Decode(DecodeError::Short))) => { + Err( + err @ (Error::Cancel + | Error::Stream(_) + | Error::Remote(_) + | Error::Transport(_) + | Error::Decode(DecodeError::Short)), + ) => { tracing::debug!(%err, "dropping uni stream that died before its type"); continue; } @@ -743,6 +774,23 @@ where } } +/// Receive QUIC datagrams, each an OBJECT_DATAGRAM for one of our subscriptions. +/// +/// A transport without datagrams never delivers one, so this parks. A transport failure +/// or a malformed datagram ends the session. +async fn run_datagrams(mut session: S, subscriber: Subscriber) -> Result<(), Error> +where + S: crate::transport::poll::Boxable, +{ + if session.max_datagram_size() == 0 { + return Ok(()); + } + loop { + let payload = session.recv_datagram().await.map_err(Error::from_transport)?; + subscriber.recv_datagram(payload)?; + } +} + async fn run_uni_group( subscriber: &mut Subscriber, stream: &mut Reader, @@ -823,7 +871,13 @@ where // header that does not parse included, still fails the session. let (id, data) = match header { Ok(header) => header, - Err(err @ (Error::Cancel | Error::Stream(_) | Error::Remote(_) | Error::Decode(DecodeError::Short))) => { + Err( + err @ (Error::Cancel + | Error::Stream(_) + | Error::Remote(_) + | Error::Transport(_) + | Error::Decode(DecodeError::Short)), + ) => { tracing::debug!(%err, "dropping bidi stream that died before its header"); continue; } @@ -981,6 +1035,7 @@ mod tests { cost: None, version: VERSION, path: None, + authority: None, 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. @@ -1039,6 +1094,7 @@ mod tests { cost: None, version: Version::Draft18, path: None, + authority: None, peer_setup_stream: None, // The requests wait on the peer's SETUP (MoQ Hidden). peer_declared: Some(peer::Peer::default()), @@ -1090,6 +1146,7 @@ mod tests { cost: None, version: Version::Draft18, path: None, + authority: None, peer_setup_stream: None, peer_declared, }) @@ -1197,6 +1254,7 @@ mod tests { cost: None, version: VERSION, path: None, + authority: None, peer_setup_stream: None, // Pre-settled, so nothing waits on a SETUP the dead stream will never // carry and the dispatch loop actually runs. @@ -1211,6 +1269,49 @@ mod tests { assert_eq!(log.closes(), vec![], "nothing may close the transport"); } + /// A draft-17+ client advertises its AUTHORITY in the SETUP it writes on its uni stream. + #[tokio::test] + async fn setup_carries_the_authority() { + const AUTHORITY: &[u8] = b"relay.example.com:4443"; + + // The driver parks forever once SETUP is out, so bound it: paused time makes the + // deadline fire the moment nothing else can run. + tokio::time::pause(); + + for version in [Version::Draft18, Version::Draft19] { + let session = crate::lite::test_transport::ScriptedSession::new(Vec::new()); + let log = session.log.clone(); + + let (driver, _goaway) = start(Config { + runtime: crate::time::Clock::tokio(), + session, + setup: None, + request_id_max: None, + client: true, + publish: None, + subscribe: None, + peer_hop: None, + cost: None, + version, + path: None, + authority: Some(String::from_utf8(AUTHORITY.to_vec()).unwrap()), + peer_setup_stream: None, + peer_declared: Some(peer::Peer::default()), + }) + .expect("start the session"); + + tokio::time::timeout(std::time::Duration::from_secs(10), driver) + .await + .expect_err("the session ended instead of parking after SETUP"); + + assert_eq!( + occurrences(&log, AUTHORITY), + 1, + "{version:?}: SETUP must carry the authority once" + ); + } + } + #[tokio::test] async fn a_uni_stream_dead_before_its_type_does_not_end_the_session() { a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::unis(1)).await; @@ -1221,10 +1322,23 @@ mod tests { a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::bis(1)).await; } + /// moxygen resets a subgroup stream it opened but never wrote with its own CANCELLED + /// (0x1). Over raw QUIC our transport reads that code through the WebTransport space + /// and cannot map it, which used to end the session. + #[tokio::test] + async fn a_uni_stream_reset_with_an_unmapped_code_does_not_end_the_session() { + a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::unis(1).unmapped()).await; + } + + #[tokio::test] + async fn a_bidi_stream_reset_with_an_unmapped_code_does_not_end_the_session() { + a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::bis(1).unmapped()).await; + } + /// The bytes a publisher writes at the head of a group's unidirectional stream. Built /// with the crate's own encoder so the framing can't drift from the decoder the /// dispatch loop runs. - async fn subgroup_header(version: Version, track_alias: u64) -> Vec { + async fn subgroup_header(version: Version, track_alias: u64, sub_group_id: 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); @@ -1232,9 +1346,12 @@ mod tests { .encode(&ietf::GroupHeader { track_alias, group_id: 0, - sub_group_id: 0, + sub_group_id, publisher_priority: 128, - flags: ietf::GroupFlags::default(), + flags: ietf::GroupFlags { + has_subgroup: sub_group_id != 0, + ..Default::default() + }, }) .await .unwrap(); @@ -1293,7 +1410,7 @@ mod tests { /// A late group must reach the dispatch loop and stop with CANCELLED. #[tokio::test(start_paused = true)] async fn a_group_for_a_retired_alias_is_stopped_with_cancelled() { - let log = dispatch_uni(subgroup_header(Version::Draft19, 7).await, Some(7)).await; + let log = dispatch_uni(subgroup_header(Version::Draft19, 7, 0).await, Some(7)).await; assert_eq!( log.stops(), @@ -1303,6 +1420,15 @@ mod tests { assert_eq!(log.closes(), vec![], "one dropped group may not close the session"); } + /// A non-zero subgroup is refused on its own stream, never by closing the session. + #[tokio::test(start_paused = true)] + async fn a_non_zero_subgroup_is_stopped_without_closing_the_session() { + let log = dispatch_uni(subgroup_header(Version::Draft19, 7, 1).await, None).await; + + assert_eq!(log.stops(), vec![crate::ietf::error::INTERNAL_ERROR]); + assert_eq!(log.closes(), vec![], "one refused subgroup may not close the session"); + } + #[tokio::test(start_paused = true)] async fn unknown_uni_type_does_not_claim_the_session_closed() { let log = dispatch_uni(vec![0], None).await; @@ -1389,6 +1515,7 @@ mod tests { cost: None, version: VERSION, path: None, + authority: None, peer_setup_stream: None, peer_declared: None, }) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index ef38c0d0587..6165ea47a5f 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -15,7 +15,7 @@ use crate::{ }; use super::{Message, Version, cluster, error::request, peer}; -use crate::tail::{self, Settle, Tail}; +use crate::tail::{Reading, Settle, Tail}; use kio::Lock; @@ -145,6 +145,9 @@ struct State { // Joining FETCH request ids, mapped to the SUBSCRIBE they name. fetches: HashMap, + // Group FETCH request ids, filling a cache miss. + group_fetches: HashMap>, + // Track aliases chosen by the remote publisher. aliases: TrackAliases, @@ -285,6 +288,52 @@ impl Fill { } } +/// A standalone FETCH of one group through its end, from FETCH_OK to its fetch stream. +enum GroupFetch { + /// Waiting on FETCH_OK, which the fetch stream can overtake. + Pending, + /// Accepted into the track cache, waiting for the fetch stream to write it. + Ready { + producer: group::Producer, + timescale: Option, + /// The first Object ID requested, which the producer starts at. + start: u64, + /// The exclusive last Object ID, when FETCH_OK's End Location falls inside the group. + end: Option, + }, + /// A fetch stream is writing the group. + Receiving, + /// The group is written or failed. + Done, +} + +/// A group FETCH's entry in [`State::group_fetches`], removed when its request ends. +struct GroupFetchEntry { + state: Lock, + fetch_id: RequestId, + slot: kio::Producer, +} + +impl GroupFetchEntry { + fn new(state: &Lock, fetch_id: RequestId, slot: kio::Producer) -> Self { + state.lock().group_fetches.insert(fetch_id, slot.clone()); + Self { + state: state.clone(), + fetch_id, + slot, + } + } +} + +impl Drop for GroupFetchEntry { + fn drop(&mut self) { + self.state.lock().group_fetches.remove(&self.fetch_id); + // A fetch stream that overtook a refused or unserved FETCH_OK holds its own clone + // of the slot, so only closing it wakes that stream. + let _ = self.slot.close(); + } +} + /// A pre-draft-20 joining FETCH, sent as its own request after SUBSCRIBE. #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum JoiningFetch { @@ -375,20 +424,6 @@ impl TrackState { } } -/// Counts a data stream toward its subscription's [`Tail`] once its handler is done with it. -/// -/// Counting at the end rather than at the header means a Stream Count that is reached never -/// races the stream's own work, such as the END_OF_TRACK that declares where the track ends. -struct Counted(kio::Producer); - -impl Drop for Counted { - fn drop(&mut self) { - if let Ok(mut tail) = self.0.write() { - tail.stream(); - } - } -} - struct BroadcastState { // The route announced into our origin for this namespace, post-charge. route: crate::origin::Route, @@ -430,6 +465,10 @@ pub(super) struct Subscriber { // that withheld an identity is not named on the wire. A server answers it per // accepted session; a client only when it knows the peer. session_origin: crate::Hop, + // A random Hop ID of this connection's own, written as the first hop of any path + // that arrives naming no publisher, so a publisher that reconnects reads downstream + // as a new one. Fresh per connection, unlike `session_origin`. + stamp: crate::Hop, // Our own Hop ID, which an advertisement must not already contain: one that does // looped back through us. self_origin: crate::Hop, @@ -542,6 +581,7 @@ where origin, control, session_origin: peer_hop.unwrap_or(crate::Hop::UNKNOWN), + stamp: crate::Hop::random(), self_origin, peer_setup, cost, @@ -594,10 +634,11 @@ where /// The route for an advertisement that carries no path of its own. /// - /// Base moq-transport has no hops on the wire, so the chain is a single 0: the - /// anonymous mark, forwarded unchanged. The session's assigned identity stays - /// on `via` for split-horizon; putting it in the chain would publish a name for - /// a peer that declined to give one. + /// Base moq-transport has no hops on the wire, so the chain is this connection's + /// stamp, naming the unknown publisher for as long as the connection lasts, then + /// the anonymous 0 that keeps it ranked below identified routes. + /// The session's assigned identity stays on `via` for split-horizon; putting it in + /// the chain would publish a name for a peer that declined to give one. /// /// The link is charged all the same. Such an advertisement carries no ROUTE_COST, /// which reads as 0, but the draft charges every advertisement for the direction it @@ -606,13 +647,11 @@ where /// /// It is charged only one hop, though the chain it stands for may be arbitrarily /// long: a peer that carries no hop ids hides its depth, so this route understates - /// its true length. An anonymous route already ranks below every identified one, - /// so that understatement cannot beat a real path. Price such a link with - /// [`crate::Client::with_cost`] among other anonymous routes. + /// its true length. Price such a link with [`crate::Client::with_cost`]. fn session_route(&self, peer: &cluster::Peer) -> crate::origin::Route { let mut hops = crate::Hops::new(); - hops.push(crate::Hop::UNKNOWN) - .expect("an empty hop chain has room for one entry"); + hops.stamp(self.stamp) + .expect("an empty hop chain has room for the stamp and its 0"); crate::origin::Route::default() .with_hops(hops) .with_via(self.via(peer)) @@ -625,8 +664,8 @@ where /// /// A negotiated peer supplies the path and cost, so the route is what the mesh /// actually knows: the full chain, and the accumulated cost plus this link's price. - /// A received 0 stays 0. An advertisement whose path already contains our own Hop - /// ID looped back, and neither forwarding it nor subscribing through it is safe. + /// A path starting with 0 gets this connection's stamp in front of it; the 0s stay. An advertisement whose path already contains our own Hop ID looped back, + /// and neither forwarding it nor subscribing through it is safe. fn route(&self, advert: Option<&cluster::Advert>, peer: &cluster::Peer) -> Option { let Some(advert) = advert else { return Some(Advertised { @@ -638,11 +677,11 @@ where return None; } - Some(Advertised { - route: advert - .route(cluster::link_cost(self.cost, peer)) - .with_via(self.via(peer)), - }) + let mut route = advert + .route(cluster::link_cost(self.cost, peer)) + .with_via(self.via(peer)); + route.hops.stamp(self.stamp).ok()?; + Some(Advertised { route }) } /// Bind the alias the publisher chose for this subscription. @@ -1148,30 +1187,10 @@ where // An omitted parameter keeps its value, so the update lands on what the peer // already advertised. The parameters exist only on a session that negotiated // the extension; anywhere else they are the peer's violation. + // A different original publisher applies in place too: the origin drains what + // the old one already serves and never splices the two. held = match &held { - Some(current) => { - // A different original publisher is a different advertisement, which - // the draft has withdrawn and made again: applying it in place would - // carry subscriptions across content that is not continuous. Refusing - // the update closes the stream, which is the withdrawal the peer owed. - if let Some(hops) = &msg.hops - && hops.hops().iter().next() != current.hops.hops().iter().next() - { - tracing::warn!(%path, "publish_namespace update changes the publisher"); - self.write_error( - stream, - msg.request_id, - &Error::Unsupported, - "a new publisher is a new advertisement", - ) - .await?; - if stream.writer.finish().is_ok() { - let _ = stream.writer.closed().await; - } - return Ok(()); - } - Some(msg.apply(current)) - } + Some(current) => Some(msg.apply(current)), None if msg.hops.is_some() || msg.cost.is_some() => { tracing::warn!(%path, "cluster parameters on a session that negotiated none"); return Err(Error::ProtocolViolation); @@ -1834,6 +1853,9 @@ where true => request.resolving_start(), false => request, }; + // Serves cache misses with a group FETCH. Registered before accepting, so a miss + // queued meanwhile waits for it rather than failing for want of a handler. + let dynamic = request.dynamic(); let mut track = request.accept(info); if live { let _ = track.start_at(largest.map(|largest| largest.group)); @@ -1880,10 +1902,13 @@ where enum End { Unused, Done(Result), + Fetch(group::Request), } let mut fetch_done = fetching.is_none(); let demand = track.demand(); + // Group FETCHes for cache misses, cancelled with the subscription. + let mut group_fetches = TaskSet::owned(); let cancelled = { let mut done = std::pin::pin!(Self::read_publish_done(&mut stream.reader, self.version)); loop { @@ -1894,6 +1919,11 @@ where { fetch_done = true; } + // An error is the track closing, which the arms below report. + if let Poll::Ready(Ok(request)) = dynamic.poll_requested_group(waiter) { + return Poll::Ready(End::Fetch(request)); + } + let _ = group_fetches.poll(waiter); if demand.poll_unused(waiter).is_ready() { return Poll::Ready(End::Unused); } @@ -1902,6 +1932,15 @@ where .await; match end { + End::Fetch(request) => { + let fetch = self.clone().run_group_fetch( + broadcast_path.to_owned(), + track_name.clone(), + request, + timescale, + ); + group_fetches.push(fetch); + } End::Unused => match track.abort_unused(Error::Cancel) { Ok(()) => { tracing::info!(broadcast = %self.origin.absolute(&broadcast_path), track = %track_name, "subscribe cancelled"); @@ -1915,18 +1954,18 @@ where tracing::info!(broadcast = %self.origin.absolute(&broadcast_path), track = %track_name, "subscribe complete"); // The publisher sends PUBLISH_DONE once every data stream it opened // is closed, but QUIC does not order them, so some can still be on - // their way. Wait until Stream Count of them are read, or a bounded - // grace for any reset before its header (the draft says to use a - // timeout). The count is a hint: a published peer sends 0, which - // waits out the grace. - let tail = self + // their way. Wait until Stream Count of their headers arrived and + // each is read to its end, or a bounded grace for any reset before + // its header (the draft says to use a timeout). The count is a hint: + // a published peer sends 0, which waits out the grace. + let held = self .state .lock() .subscribes .get(&request_id) - .map(|held| held.tail.consume()); - if let Some(tail) = tail { - let mut settle = Settle::new(&self.runtime, tail, tail::GRACE); + .map(|held| (held.tail.consume(), held.fill.clone())); + if let Some((tail, fill)) = held { + let mut settle = Settle::new(&self.runtime, tail); kio::wait(|waiter| { if !fetch_done && let Some(fut) = fetching.as_mut() @@ -1934,7 +1973,7 @@ where { fetch_done = true; } - settle.poll(waiter, |tail| count > 0 && tail.streams() >= count) + poll_settled(&mut settle, waiter, &fill, count) }) .await; } @@ -2255,7 +2294,7 @@ where } }; - let (mut track, timescale, fill, _counted) = { + let (mut track, timescale, fill, mut reading) = { let state = self.state.lock(); let track = state.subscribes.get(&request_id).ok_or(Error::NotFound)?; ( @@ -2263,8 +2302,8 @@ where track.timescale, track.fill.clone(), // Every data stream counts toward PUBLISH_DONE's Stream Count, even one - // dropped below. - Counted(track.tail.clone()), + // dropped below, and the subscription's end waits until it is read. + Reading::open(&track.tail, Some(group.group_id), self.runtime.now()), ) }; @@ -2301,14 +2340,25 @@ where // Otherwise dropping the local subscriber cannot end this handler. let opened = { let mut opening = track.clone(); - let mut open = std::pin::pin!(self.open_group(stream, &mut opening, &fill, &group)); + let mut open = std::pin::pin!(self.open_group(stream, &mut opening, &fill, &group, &mut reading)); kio::wait(|waiter| { if let Poll::Ready(err) = track.poll_closed(waiter) { return Poll::Ready(Err(err)); } waiter.poll_future(open.as_mut()) }) - .await? + .await + }; + let opened = match opened { + // The group is at or past the end the publisher declared, which no later stream + // can repair. + Err(Error::Closed) => { + tracing::warn!(group = group.group_id, "group past the declared end of track"); + let _ = track.abort(Error::ProtocolViolation); + return Err(Error::ProtocolViolation); + } + Err(err) => return Err(err), + Ok(opened) => opened, }; let (producer, start) = match opened { Opened::Group(producer, start) => (producer, start), @@ -2339,6 +2389,11 @@ where Err(err @ (Error::Cancel | Error::Stream(crate::StreamError::Cancel))) => { let _ = producer.abort(err); } + Err(err @ Error::Decode(DecodeError::MessageTooLarge { .. })) => { + let _ = producer.abort(err.clone()); + // Return the refusal to the dispatcher so it sends STOP_SENDING. + return Err(err); + } Err(err) => { tracing::debug!(%err, group = %producer.sequence, "group error"); let _ = producer.abort(err); @@ -2355,6 +2410,61 @@ where Ok(()) } + + /// Deliver one OBJECT_DATAGRAM as a datagram on its subscription's track: a + /// single-frame group at the Group ID. + /// + /// A malformed datagram is the peer breaking the protocol, so it errors. One the model + /// cannot carry is dropped like any lost datagram: an Object past ID 0 (the group would + /// need a second object), a status other than Normal, or an alias that is not bound + /// yet (the draft lets us drop rather than buffer). + pub fn recv_datagram(&self, payload: bytes::Bytes) -> Result<(), Error> { + let mut buf = payload; + let datagram = ietf::ObjectDatagram::decode(&mut buf, self.version)?; + let (alias, sequence) = (datagram.track_alias, datagram.group_id); + + if datagram.object_id.unwrap_or(0) != 0 { + tracing::debug!(alias, sequence, "dropping a datagram past object 0"); + return Ok(()); + } + let payload = match datagram.body { + ietf::DatagramBody::Payload(payload) => payload, + ietf::DatagramBody::Status(0) => bytes::Bytes::new(), + ietf::DatagramBody::Status(status) => { + tracing::debug!(alias, sequence, status, "dropping a datagram status"); + return Ok(()); + } + }; + + let mut state = self.state.lock(); + let request_id = match state.aliases.read().map.get(&alias) { + Some(Alias::Active(request_id)) => *request_id, + _ => { + tracing::debug!(alias, sequence, "dropping a datagram for an unbound alias"); + return Ok(()); + } + }; + let Some(track) = state.subscribes.get_mut(&request_id) else { + return Ok(()); + }; + + // Like a subgroup object: a track that declared no timescale is stamped on arrival. + let timestamp = match (track.timescale, &datagram.properties) { + (Some(timescale), Some(properties)) => { + ietf::decode_object_time(&mut properties.as_slice(), timescale, self.version)? + } + _ => None, + }; + let timestamp = timestamp.unwrap_or_else(|| crate::Timestamp::from(self.runtime.now())); + + let Some(producer) = track.producer.as_mut() else { + return Ok(()); + }; + if let Err(err) = producer.insert_datagram(sequence, timestamp, payload) { + tracing::debug!(%err, alias, sequence, "dropping datagram"); + } + Ok(()) + } } /// Mark where the track ends, as an END_OF_TRACK object said. @@ -2393,9 +2503,31 @@ enum Ended { Track, } +/// Object status: no object at or past this location in the group exists (draft-14, 15). +const END_OF_GROUP: u64 = 0x3; + /// Object status: no object at or past this location exists (every implemented draft). const END_OF_TRACK: u64 = 0x4; +// Implementation limit for object extension blocks, independent of the IETF draft. +const MAX_OBJECT_EXTENSIONS: usize = 64 * 1024; + +#[derive(Debug)] +struct ObjectExtensionsLength(usize); + +impl Decode for ObjectExtensionsLength { + fn decode(buf: &mut B, version: Version) -> Result { + let size = usize::decode(buf, version)?; + if size > MAX_OBJECT_EXTENSIONS { + return Err(DecodeError::MessageTooLarge { + size, + max: MAX_OBJECT_EXTENSIONS, + }); + } + Ok(Self(size)) + } +} + /// The start of a subgroup stream's first object, peeked before its group is created. #[derive(Debug, Clone, Copy)] struct FirstObject { @@ -2412,7 +2544,7 @@ impl Decode for PeekFirst { fn decode(buf: &mut B, version: Version) -> Result { let id = u64::decode(buf, version)?; if EXTENSIONS { - let size = usize::decode(buf, version)?; + let ObjectExtensionsLength(size) = ObjectExtensionsLength::decode(buf, version)?; if buf.remaining() < size { return Err(DecodeError::Short); } @@ -2440,15 +2572,34 @@ where track: &mut track::Producer, fill: &kio::Producer, header: &ietf::GroupHeader, + reading: &mut Reading, ) -> Result { let sequence = header.group_id; // Stats (groups/frames/bytes) are counted in the model as the group is written, // through the tagged `track::Producer`. let create = |track: &mut track::Producer| track.create_group(group::Info { sequence }); - let first = match header.flags.has_extensions { - true => stream.decode_peek_maybe::>().await?.map(|peek| peek.0), - false => stream.decode_peek_maybe::>().await?.map(|peek| peek.0), + let peeked = match header.flags.has_extensions { + true => stream + .decode_peek_maybe::>() + .await + .map(|peek| peek.map(|peek| peek.0)), + false => stream + .decode_peek_maybe::>() + .await + .map(|peek| peek.map(|peek| peek.0)), + }; + let first = match peeked { + Ok(first) => first, + // The header arrived, so the stream counts toward the track's end. Abort the + // group it named rather than let the track end clean without it. A fill that + // already holds the group reports it through its own producer. + Err(err) => { + if let Ok(group) = create(track) { + let _ = group.abort(err.clone()); + } + return Err(err); + } }; if first.is_some_and(|first| first.id == 0 && first.end_of_track) { return Ok(Opened::EndOfTrack); @@ -2479,7 +2630,7 @@ where // A group starting partway through is the tail of one the fill began, and // without that head it has a hole at the front. - Some(start) => match self.claim_fill(fill, track, sequence, Some(start)).await? { + Some(start) => match self.claim_fill(fill, track, sequence, Some(start), reading).await? { Some(producer) => Ok(Opened::Group(producer, start)), None => { tracing::warn!(sequence, start, "no fill to stitch a mid-group stream onto"); @@ -2489,7 +2640,7 @@ where // A stream that ends without an object: the group is over and had nothing // outside the fill's range, so the head it delivered is the whole group. - None => match self.claim_fill(fill, track, sequence, None).await? { + None => match self.claim_fill(fill, track, sequence, None, reading).await? { Some(producer) => Ok(Opened::Group(producer, 0)), None => Ok(Opened::Group(create(track)?, 0)), }, @@ -2506,15 +2657,19 @@ where /// /// Waiting is what keeps the two streams from interleaving into one producer. It ends /// with the subscription, so a publisher that promises a fill and never delivers one - /// costs this stream and nothing else. + /// costs this stream and nothing else. Meanwhile this stream stops holding the + /// subscription's end open: the fill's own stream holds it if its header arrived, and + /// the grace gives up on it if not. async fn claim_fill( &self, fill: &kio::Producer, track: &track::Producer, sequence: u64, start: Option, + reading: &mut Reading, ) -> Result, Error> { - kio::wait(|waiter| { + reading.park(); + let settled = kio::wait(|waiter| { if let Poll::Ready(err) = track.poll_closed(waiter) { return Poll::Ready(Err(err)); } @@ -2525,13 +2680,18 @@ where }); match settled { - Poll::Ready(Ok(mut fill)) => Poll::Ready(fill.claim(sequence, start)), + Poll::Ready(Ok(_)) => Poll::Ready(Ok(())), // The subscription went away underneath us. Poll::Ready(Err(_)) => Poll::Ready(Err(Error::Dropped)), Poll::Pending => Poll::Pending, } }) - .await + .await; + // Hold the end open again before taking the head: once the fill is claimed, this + // stream is the only thing saying the group is still being read. + reading.resume(); + settled?; + fill.write().map_err(|_| Error::Dropped)?.claim(sequence, start) } } @@ -2604,6 +2764,11 @@ where let _: u64 = stream.decode().await?; let header: ietf::FetchHeader = stream.decode().await?; + let group_fetch = self.state.lock().group_fetches.get(&header.request_id).cloned(); + if let Some(slot) = group_fetch { + return self.recv_group_fetch(stream, slot).await; + } + let (subscribe_id, fill, joining, largest, _counted) = { let state = self.state.lock(); // A draft-20 fill is named by the SUBSCRIBE's request id. A pre-draft-20 joining @@ -2613,7 +2778,9 @@ where let track = state.subscribes.get(&subscribe_id).ok_or(Error::NotFound)?; // A fill is one of the subscription's own data streams, so PUBLISH_DONE counts // it. A joining FETCH is a request of its own. - let counted = joined.is_none().then(|| Counted(track.tail.clone())); + let counted = joined + .is_none() + .then(|| Reading::open(&track.tail, None, self.runtime.now())); (subscribe_id, track.fill.clone(), track.joining, track.largest, counted) }; @@ -2760,7 +2927,8 @@ where head: &mut Option<(u64, u64, crate::recv::Group)>, ) -> Result<(), Error> { let mut prior_group = None; - while let Some(object) = decode_fetch_object(stream, self.version).await? { + let mut first = true; + while let Some(object) = decode_fetch_object(stream, self.version, std::mem::take(&mut first)).await? { if !object.subgroup_ok { tracing::warn!("subgroup ID is not supported, dropping fill"); return Err(Error::Unsupported); @@ -2819,40 +2987,364 @@ where } } - // The properties carry the frame's presentation timestamp (the Timestamp Object - // Property) in the units the track declared. A track that declared none opted - // out, so its frames are stamped on arrival instead. - let timestamp = match (object.properties, timescale) { - (Some(properties), Some(timescale)) => { - let mut properties = bytes::Bytes::from(properties); - ietf::decode_object_time(&mut properties, timescale, self.version)? - } - _ => None, + let (_, next, producer) = head.as_mut().expect("the head was created above"); + if !self + .recv_fetch_payload(stream, producer, object.properties, timescale) + .await? + { + return Err(Error::Unsupported); + } + *next += 1; + } + + Ok(()) + } + + /// Read one fetch object's length and payload into `producer`, after its header. + /// + /// Returns `false` for a draft-14 or 15 end-of-group or end-of-track marker, which + /// is a status rather than a frame. + async fn recv_fetch_payload( + &self, + stream: &mut Reader, + producer: &mut group::Producer, + properties: Option>, + timescale: Option, + ) -> Result { + // The properties carry the frame's presentation timestamp (the Timestamp Object + // Property) in the units the track declared. A track that declared none opted + // out, so its frames are stamped on arrival instead. + let timestamp = match (properties, timescale) { + (Some(properties), Some(timescale)) => { + let mut properties = bytes::Bytes::from(properties); + ietf::decode_object_time(&mut properties, timescale, self.version)? + } + _ => None, + }; + let timestamp = timestamp.unwrap_or_else(|| crate::Timestamp::from(self.runtime.now())); + + // A fetch object has no status field from draft-16 on; a zero length is simply + // an empty object. Draft-14 and 15 still encode Normal (0) after a zero length. + let size: u64 = stream.decode().await?; + if size == 0 && matches!(self.version, Version::Draft14 | Version::Draft15) { + match stream.decode::().await? { + 0 => {} + END_OF_GROUP | END_OF_TRACK => return Ok(false), + _ => return Err(Error::Unsupported), + } + } + + // `create_frame_owned` is the allocation chokepoint and rejects an oversized `size` + // before allocating, so no pre-check is needed. + let mut frame = producer.create_frame_owned(frame::Info { size, timestamp })?; + if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { + let _ = frame.abort(err.clone()); + return Err(err); + } + frame.finish()?; + Ok(true) + } + + /// Fetch a group from the publisher to fill a cache miss, with a standalone FETCH for + /// this subscription's track. It asks from the frame the reader wants through the end + /// of the group, so a publisher that evicted the prefix can still answer. + /// + /// The group is accepted only once FETCH_OK arrives, so a refusal reaches every + /// waiting [`track::Consumer::fetch_group`] as the publisher's own error. The objects + /// arrive on a fetch stream, which [`Self::recv_fill`] routes into the group. + async fn run_group_fetch( + self, + broadcast: PathOwned, + name: String, + request: group::Request, + timescale: Option, + ) { + let sequence = request.sequence(); + let start = request.frame_start(); + if self.going_away.is_set() { + request.reject(Error::GoingAway); + return; + } + // Our FETCH still encodes the Fetch Type field that draft-20 removed. + if Filter::is_draft20(self.version) { + request.reject(Error::Unsupported); + return; + } + + let fetch_id = match self.control.next_request_id(&self.runtime).await { + Ok(id) => id, + Err(err) => return request.reject(err), + }; + + // Registered before the FETCH goes out, since its fetch stream can overtake FETCH_OK. + let slot = kio::Producer::new(GroupFetch::Pending); + let _registered = GroupFetchEntry::new(&self.state, fetch_id, slot.clone()); + + let mut stream = match Stream::open(&mut self.session.clone(), self.version).await { + Ok(stream) => stream, + Err(err) => return request.reject(err), + }; + + let res = async { + stream.writer.encode(&ietf::Fetch::ID).await?; + stream + .writer + .encode(&ietf::Fetch { + request_id: fetch_id, + subscriber_priority: super::priority::to_wire(request.priority()), + group_order: GroupOrder::Ascending, + // An End Object of 0 is the whole End Group. + fetch_type: FetchType::Standalone { + namespace: broadcast.clone(), + track: name.as_str().into(), + start: ietf::Location { + group: sequence, + object: start, + }, + end: ietf::Location { + group: sequence, + object: 0, + }, + }, + }) + .await?; + self.read_group_fetch_response(&mut stream).await + } + .await; + + let ok = match res { + Ok(ok) => ok, + Err(err) => { + tracing::debug!(%err, group = sequence, "group fetch refused"); + request.reject(err); + let _ = stream.writer.close().await; + return; + } + }; + + // The publisher knows where the track ends, which a range FETCH downstream needs. + if ok.end_of_track { + let end = ok.end_location; + let Some(final_sequence) = end.group.checked_add(u64::from(end.object > 0)) else { + request.reject(Error::ProtocolViolation); + let _ = stream.writer.close().await; + return; }; - let timestamp = timestamp.unwrap_or_else(|| crate::Timestamp::from(self.runtime.now())); - - // A fetch object has no status field from draft-16 on; a zero length is simply - // an empty object. Draft-14 and 15 still encode Normal (0) after a zero length. - let size: u64 = stream.decode().await?; - if size == 0 && matches!(self.version, Version::Draft14 | Version::Draft15) { - let status: u64 = stream.decode().await?; - if status != 0 { - return Err(Error::Unsupported); + request.finish_track_at(final_sequence); + } + + // An empty answer opens no fetch stream at all. + let end = ok.end_location; + if (end.group, end.object) <= (sequence, start) { + request.reject(Error::NotFound); + let _ = stream.writer.close().await; + return; + } + // An exclusive End Location inside the group is its Largest Object plus one, so + // the stream owes every object up to it. One past the group covers it whole. + let end = (end.group == sequence).then_some(end.object); + + // Only a track nothing has subscribed to yet takes this info, as SUBSCRIBE_OK would + // have set it. FETCH_OK carries the same Track Properties, so the retention window + // comes from it. + let info = track::Info::default() + .with_timescale(Timescale::MICRO) + .with_max_age(ok.properties.max_cache_duration); + let mut producer = match request.accept(info) { + Ok(producer) => producer, + // Already served by a concurrent fetch, or the track closed. + Err(err) => { + tracing::debug!(%err, group = sequence, "group fetch not served"); + let _ = stream.writer.close().await; + return; + } + }; + // The objects keep the IDs they have in the group rather than restarting at 0. + if let Err(err) = producer.start_at(start) { + let _ = producer.abort(err); + let _ = stream.writer.close().await; + return; + } + if let Ok(mut state) = slot.write() { + *state = GroupFetch::Ready { + producer, + timescale, + start, + end, + }; + } + + // Hold the request open until its fetch stream is done: closing our side first is + // what a draft-14-16 adapter reads as cancelling the FETCH. A publisher that fails + // after FETCH_OK resets the request instead and owes no fetch stream, so the group + // it left waiting is aborted. A FIN is not that: the fetch stream can trail it. + let mut open = true; + let reset = kio::wait(|waiter| { + if open { + let mut cx = std::task::Context::from_waker(waiter.waker()); + match stream.reader.poll_closed(&mut cx) { + Poll::Ready(Err(err)) => return Poll::Ready(Some(err)), + Poll::Ready(Ok(())) => open = false, + Poll::Pending => {} } } + slot.poll(waiter, |state| match &**state { + GroupFetch::Done => Poll::Ready(()), + _ => Poll::Pending, + }) + .map(|_| None) + }) + .await; + if let Some(err) = reset + && let Ok(mut state) = slot.write() + && matches!(*state, GroupFetch::Ready { .. }) + && let GroupFetch::Ready { producer, .. } = std::mem::replace(&mut *state, GroupFetch::Done) + { + let _ = producer.abort(err); + } + let _ = stream.writer.close().await; + } - let (_, next, producer) = head.as_mut().expect("the head was created above"); + /// Read the answer to a group FETCH: FETCH_OK, or the publisher's refusal as an error. + async fn read_group_fetch_response(&self, stream: &mut Stream) -> Result { + let type_id: u64 = stream.reader.decode().await?; + let size: u16 = stream.reader.decode().await?; + let mut data = stream.reader.read_exact(size as usize).await?; - // `create_frame_owned` is the allocation chokepoint and rejects an oversized `size` - // before allocating, so no pre-check is needed. - let mut frame = producer.create_frame_owned(frame::Info { size, timestamp })?; - if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { - let _ = frame.abort(err.clone()); - return Err(err); + match type_id { + ietf::FetchOk::ID => Ok(ietf::FetchOk::decode_msg(&mut data, self.version)?), + ietf::FetchError::ID if self.version == Version::Draft14 => { + let msg = ietf::FetchError::decode_msg(&mut data, self.version)?; + Err(request::from_code(msg.error_code, request::Kind::Fetch, self.version)) + } + ietf::RequestError::ID => { + let msg = ietf::RequestError::decode_msg(&mut data, self.version)?; + Err(request::from_code(msg.error_code, request::Kind::Fetch, self.version)) + } + _ => Err(Error::UnexpectedMessage), + } + } + + /// Write a group FETCH's objects into the group it accepted. + async fn recv_group_fetch( + &mut self, + stream: &mut Reader, + slot: kio::Producer, + ) -> Result<(), Error> { + // FETCH_OK can trail its own fetch stream. Taking the group in the same step is + // what refuses a second stream for one request. + let taken = kio::wait(|waiter| { + match slot.poll(waiter, |state| match &**state { + GroupFetch::Pending => Poll::Pending, + _ => Poll::Ready(()), + }) { + Poll::Ready(Ok(mut state)) => { + Poll::Ready(match std::mem::replace(&mut *state, GroupFetch::Receiving) { + GroupFetch::Ready { + producer, + timescale, + start, + end, + } => Ok((producer, timescale, start, end)), + other => { + *state = other; + Err(Error::Unsupported) + } + }) + } + Poll::Ready(Err(_)) => Poll::Ready(Err(Error::Dropped)), + Poll::Pending => Poll::Pending, } - frame.finish()?; + }) + .await; + let (producer, timescale, start, end) = taken?; - *next += 1; + let mut producer = crate::recv::Group::new(producer); + let res = match self + .recv_group_fetch_objects(stream, &mut producer, start, end, timescale) + .await + { + Ok(()) => producer.finish(), + Err(err) => { + let _ = producer.abort(err.clone()); + Err(err) + } + }; + + if let Ok(mut state) = slot.write() { + *state = GroupFetch::Done; + } + res + } + + /// Decode one group's objects: all in the producer's group, numbered from `start` with + /// no gaps, and through `end` (exclusive) when FETCH_OK named one inside the group. + async fn recv_group_fetch_objects( + &self, + stream: &mut Reader, + producer: &mut group::Producer, + start: u64, + end: Option, + timescale: Option, + ) -> Result<(), Error> { + let sequence = producer.info().sequence; + let mut next = start; + let mut prior_group = None; + let mut ended = false; + let mut first = true; + while let Some(object) = decode_fetch_object(stream, self.version, std::mem::take(&mut first)).await? { + if ended { + tracing::warn!(sequence, "a group fetch continued past its end marker"); + return Err(Error::ProtocolViolation); + } + if !object.subgroup_ok { + tracing::warn!("subgroup ID is not supported, dropping group fetch"); + return Err(Error::Unsupported); + } + + let group = resolve_fetch_group(self.version, prior_group, object.group)?; + if let Some(group) = group { + prior_group = Some(group); + } + let id = match (object.group.is_some(), object.object) { + (true, Some(id)) => Some(id), + (false, None | Some(1)) => Some(next), + _ => None, + }; + // Another group, or an ID before the next one, is outside what was asked for. + if group.is_some_and(|group| group != sequence) || id.is_some_and(|id| id < next) { + tracing::warn!(sequence, next, group = ?group, object = ?id, "a group fetch answered outside its range"); + return Err(Error::ProtocolViolation); + } + // A skipped ID is an object that does not exist, a hole the model cannot hold. + if id != Some(next) { + tracing::warn!(sequence, next, object = ?id, "a group fetch skipped an object"); + return Err(Error::Unsupported); + } + + match self + .recv_fetch_payload(stream, producer, object.properties, timescale) + .await? + { + true => next += 1, + false => ended = true, + } + if end.is_some_and(|end| next > end) { + tracing::warn!(sequence, ?end, "a group fetch continued past FETCH_OK's End Location"); + return Err(Error::ProtocolViolation); + } + } + + // A clean FIN short of the promised end would otherwise cache a truncated group as + // a complete one. + if end.is_some_and(|end| next < end) { + tracing::warn!( + sequence, + next, + ?end, + "a group fetch ended before FETCH_OK's End Location" + ); + return Err(Error::ProtocolViolation); } Ok(()) @@ -2868,9 +3360,13 @@ struct FetchedObject { } /// Decode the next fetch object header, or `None` at stream end. +/// +/// The `first` object on a stream has no prior to inherit from, so a field it leaves to +/// the prior object is a protocol violation. async fn decode_fetch_object( stream: &mut Reader, version: Version, + first: bool, ) -> Result, Error> { if version == Version::Draft14 { let Some(group) = stream.decode_maybe::().await? else { @@ -2898,17 +3394,27 @@ async fn decode_fetch_object( subgroup, group, object, + priority, properties, - .. - }) => Some(FetchedObject { - group, - object, - subgroup_ok: matches!( - subgroup, - ietf::FetchSubgroup::Zero | ietf::FetchSubgroup::Prior | ietf::FetchSubgroup::Explicit(0) - ), - properties, - }), + }) => { + let inherits = group.is_none() + || object.is_none() + || priority.is_none() + || matches!(subgroup, ietf::FetchSubgroup::Prior | ietf::FetchSubgroup::PriorPlusOne); + if first && inherits { + tracing::warn!("the first fetch object refers to a prior object"); + return Err(Error::ProtocolViolation); + } + Some(FetchedObject { + group, + object, + subgroup_ok: matches!( + subgroup, + ietf::FetchSubgroup::Zero | ietf::FetchSubgroup::Prior | ietf::FetchSubgroup::Explicit(0) + ), + properties, + }) + } }) } @@ -2971,6 +3477,15 @@ fn advance_fill_group( open_fill_group(track, head, sequence) } +/// Ready once a finished subscription's data streams are accounted for: Stream Count of +/// their headers, and no fill outstanding. A tail parked on its head holds nothing open +/// itself, so the fill does until the head is claimed. +fn poll_settled(settle: &mut Settle, waiter: &kio::Waiter, fill: &kio::Producer, count: u64) -> Poll<()> { + // Read before the tail: Done is terminal, so the answer cannot go stale. + let filled = !fill.read().outstanding(); + settle.poll(waiter, |tail| filled && count > 0 && tail.streams() >= count) +} + /// A refused or missing joining FETCH continues the subscription live: drop the outstanding /// fill so a mid-group tail is not left waiting on a head that is never coming. fn settle_join_live(fill: &kio::Producer) { @@ -3006,7 +3521,7 @@ impl GroupIngest { }; } IngestPhase::ExtSize => { - let size: usize = ready!(reader.poll_decode(&mut cx))?; + let ObjectExtensionsLength(size) = ready!(reader.poll_decode(&mut cx))?; self.phase = IngestPhase::ExtBytes { size }; } IngestPhase::ExtBytes { size } => { @@ -3041,7 +3556,7 @@ impl GroupIngest { let frame = group.create_frame_owned(frame::Info { size: 0, timestamp })?; frame.finish()?; self.phase = IngestPhase::Delta; - } else if status == 3 && !self.has_end { + } else if status == END_OF_GROUP && !self.has_end { self.phase = IngestPhase::Finished(Ended::Group); } else if status == END_OF_TRACK { // Defined on every implemented draft, whether or not the header marks @@ -3602,6 +4117,67 @@ mod tests { ); } + /// An OBJECT_DATAGRAM at object 0 is a datagram group at its Group ID; anything the model + /// cannot carry as one is dropped, and a malformed one is the peer's violation. + #[tokio::test] + async fn an_object_datagram_is_a_datagram_group() { + use crate::coding::Encode as _; + use futures::FutureExt as _; + + let subscriber = subscriber_with_tracks(&[(RequestId(11), "cam", "audio")]); + subscriber.register_alias(RequestId(11), 7).unwrap(); + let mut consumer = { + let mut state = subscriber.state.lock(); + let track = state.subscribes.get_mut(&RequestId(11)).unwrap(); + track.timescale = Some(Timescale::default()); + track.producer.as_ref().unwrap().subscribe(None) + }; + + let timestamp = crate::Timestamp::new(96_000, Timescale::default()).unwrap(); + let datagram = |alias: u64, group_id: u64, object_id: Option, body: ietf::DatagramBody| { + let mut properties = Vec::new(); + ietf::encode_object_time(&mut properties, timestamp, Timescale::default(), Version::Draft19).unwrap(); + ietf::ObjectDatagram { + track_alias: alias, + group_id, + object_id, + publisher_priority: None, + // Only a Normal Object may carry Properties, and a status cannot end the group. + end_of_group: matches!(body, ietf::DatagramBody::Payload(_)), + properties: matches!(body, ietf::DatagramBody::Payload(_)).then_some(properties), + body, + } + .encode_bytes(Version::Draft19) + .unwrap() + }; + let payload = |bytes: &'static [u8]| ietf::DatagramBody::Payload(bytes::Bytes::from_static(bytes)); + + // Dropped: a second object in the group, an unbound alias, and a status. + subscriber + .recv_datagram(datagram(7, 4, Some(1), payload(b"no"))) + .unwrap(); + subscriber.recv_datagram(datagram(8, 4, None, payload(b"no"))).unwrap(); + subscriber + .recv_datagram(datagram(7, 4, None, ietf::DatagramBody::Status(END_OF_TRACK))) + .unwrap(); + + subscriber + .recv_datagram(datagram(7, 9, Some(0), payload(b"yes"))) + .unwrap(); + let received = consumer.recv_datagram().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(received.sequence, 9, "the Group ID is the sequence"); + assert_eq!(received.timestamp, timestamp); + assert_eq!(&received.payload[..], b"yes"); + assert!( + consumer.recv_datagram().now_or_never().is_none(), + "only one got through" + ); + + // A status datagram cannot end the group. + let malformed = bytes::Bytes::from_static(&[0x22, 0x07, 0x04, 0x00]); + assert!(is_protocol_violation(&subscriber.recv_datagram(malformed).unwrap_err())); + } + /// One alias naming two different tracks is the collision section 11.1 makes fatal. #[test] fn an_alias_reused_for_another_track_is_fatal() { @@ -4238,9 +4814,9 @@ mod tests { assert!(!table.map.contains_key(&0), "the oldest tombstone is forgotten first"); } - /// moq-transport carries no hop ids, so a peer's broadcasts are marked - /// anonymous (hop 0). An identity assigned via `Client::with_peer_hop` is - /// stored as `via` for split-horizon and never written into the chain. + /// moq-transport carries no hop ids, so a peer's broadcasts are named by the + /// connection's own random stamp. An identity assigned via `Client::with_peer_hop` + /// is stored as `via` for split-horizon and never written into the chain. #[tokio::test] async fn assigned_peer_hop_attributes_announces() { let session = crate::lite::test_transport::SinkSession::new(Default::default()); @@ -4271,8 +4847,10 @@ mod tests { let mut announced = consumer.announced(); let route = announced.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN]); - assert!(route.is_anonymous()); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN]); + assert_ne!(subscriber.stamp, crate::Hop::UNKNOWN); + assert!(route.is_anonymous(), "the 0 after the stamp still ranks it as unknown"); + assert_ne!(subscriber.stamp, assigned, "the assigned identity stays off the chain"); let mut hidden = consumer.excluding(assigned).announced(); hidden.assert_next_wait(); @@ -4335,11 +4913,11 @@ mod tests { assert_eq!(route.hops, upstream); } - /// Two sessions assigned the same identity announce the same anonymous chain. - /// The cursor treats that as an identical re-announce, so a reconnect is - /// invisible and retracting the stale session leaves the fresh route standing. + /// Two sessions assigned the same identity still stamp their own first hop, since + /// a wire with no hop ids cannot say the content continued: the reconnect reads as a + /// new source, while split-horizon keeps filtering on the shared identity. #[tokio::test] - async fn reconnecting_peer_joins_the_front_it_replaces() { + async fn reconnecting_peer_is_a_new_first_hop() { let peer = crate::Hop::new(777).unwrap(); let self_origin = crate::Hop::new(1).unwrap(); @@ -4371,17 +4949,18 @@ mod tests { }; let first = connect(); - announced.assert_next_active("room/host"); + let first_stamp = first.stamp; + let route = announced.assert_next_active("room/host"); + assert_eq!(route.hops.iter().next(), Some(&first_stamp)); - // The peer reconnects before the old session is retired: an identical route - // from the fresh session joins without any consumer-visible churn. - let _second = connect(); - announced.assert_next_wait(); + // The peer reconnects before the old session is retired, under its own stamp. + let second = connect(); + assert_ne!(second.stamp, first_stamp); + assert!(routed_now(&consumer, "room/host").is_some()); - // The stale session finally retracting leaves the fresh route standing. + // Neither route is offered back to the peer they both came from. + consumer.excluding(peer).announced().assert_next_wait(); drop(first); - announced.assert_next_wait(); - assert!(routed_now(&consumer, "room/host").is_some()); } fn cluster_subscriber( @@ -4838,8 +5417,7 @@ mod tests { } /// An update replaces the advertisement in place: the route moves, the refcount does - /// not, and the source is not torn down. Only a changed original publisher replaces - /// it, since that content is not interchangeable. + /// not, and the source is not torn down. #[tokio::test] async fn cluster_update_replaces_in_place() { let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); @@ -5356,12 +5934,11 @@ mod tests { assert_eq!(replies(&log, ietf::RequestOk::ID), 0); } - /// An update whose first Hop ID differs names a different publisher, whose content - /// is not continuous with what is held. The draft has the sender withdraw and - /// advertise again instead, so the update is refused and the stream closed, which - /// is that withdrawal. + /// An update whose first Hop ID differs names a different publisher. It still + /// replaces the advertisement in place and the stream stays open: the origin, not the + /// session, keeps the two publishers' content apart. #[tokio::test] - async fn an_update_that_changes_the_publisher_is_refused() { + async fn an_update_that_changes_the_publisher_applies_in_place() { let self_origin = crate::Hop::new(5).unwrap(); let peer = peer_9(); let (clean, _) = clean_and_looped(); @@ -5377,7 +5954,6 @@ mod tests { let path = crate::Path::new("room/host").to_owned(); let mut attached = true; - let mut result = None; { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, @@ -5387,20 +5963,20 @@ mod tests { &mut attached, )); for _ in 0..20 { - if let std::task::Poll::Ready(res) = futures::poll!(run.as_mut()) { - result = Some(res); - break; - } + assert!( + futures::poll!(run.as_mut()).is_pending(), + "a publisher change must not close the stream" + ); settle().await; } } - assert!(matches!(result, Some(Ok(()))), "refused cleanly, got {result:?}"); - assert_eq!(replies(&log, ietf::RequestError::ID), 1, "REQUEST_ERROR went out"); - assert_eq!(replies(&log, ietf::RequestOk::ID), 0); - let route = routed_now(&consumer, "room/host").expect("the caller releases the route"); + assert!(attached, "the advertisement stays attached"); + assert_eq!(replies(&log, ietf::RequestOk::ID), 1, "REQUEST_OK went out"); + assert_eq!(replies(&log, ietf::RequestError::ID), 0); + let route = routed_now(&consumer, "room/host").expect("still routed"); let hops: Vec<_> = route.hops.iter().map(|h| h.id()).collect(); - assert_eq!(hops, vec![7, 9], "the held path was not replaced"); + assert_eq!(hops, vec![8, 9], "the held path was replaced"); } /// A second PUBLISH_NAMESPACE on the stream that already carries one is not an @@ -6144,6 +6720,132 @@ mod stitch_tests { assert!(matches!(*h.fill.read(), Fill::Done), "the head was claimed"); } + /// A tail parked on its head stops holding the end open, so the finished fill does until + /// the head is claimed: otherwise the subscription looks settled between the fill + /// finishing and the tail waking, and ends before the tail is read. + #[tokio::test] + async fn an_unclaimed_fill_holds_the_end_open() { + let h = Harness::new( + Fill::Serving(Some(Timescale::MICRO)), + vec![ + fill_stream(SEQUENCE, &[b"head-0", b"head-1"]), + tail_stream(SEQUENCE, 2, &[b"tail-2"]), + ], + ); + let mut fill = h.stream().await; + let mut tail = h.stream().await; + + let mut serve_tail = h.subscriber.clone(); + let mut tailing = std::pin::pin!(serve_tail.recv_group(&mut tail)); + assert!( + futures::poll!(tailing.as_mut()).is_pending(), + "the tail waits for its head" + ); + h.subscriber.clone().recv_fill(&mut fill).await.expect("fill"); + + let state = h.subscriber.state.lock().subscribes[&REQUEST].tail.consume(); + let count = state.read().streams(); + let mut settle = Settle::new(&crate::time::Clock::tokio(), state); + let mut settled = std::pin::pin!(kio::wait(|waiter| poll_settled(&mut settle, waiter, &h.fill, count))); + assert!( + futures::poll!(settled.as_mut()).is_pending(), + "the head is still owed to the tail" + ); + + tailing.await.expect("tail"); + settled.await; + } + + /// A subgroup 1 stream costs only itself: the track's subgroup 0 stream still arrives. + #[tokio::test] + async fn a_non_zero_subgroup_leaves_the_track_flowing() { + let mut refused = Vec::new(); + ietf::GroupHeader { + track_alias: ALIAS, + group_id: SEQUENCE, + sub_group_id: 1, + publisher_priority: 0, + flags: ietf::GroupFlags { + has_subgroup: true, + first_object: true, + ..Default::default() + }, + } + .encode(&mut refused, VERSION) + .unwrap(); + + let h = Harness::new(Fill::Done, vec![refused, tail_stream(SEQUENCE, 0, &[b"ok"])]); + let mut consumer = h.track.subscribe(None); + + let mut stream = h.stream().await; + let result = h.subscriber.clone().recv_group(&mut stream).await; + assert!(matches!(result, Err(Error::Unsupported)), "{result:?}"); + + let mut stream = h.stream().await; + h.subscriber.clone().recv_group(&mut stream).await.unwrap(); + let (sequence, frames) = read_group(&mut consumer).await; + assert_eq!(sequence, SEQUENCE); + assert_eq!(frames.len(), 1); + assert_eq!(frames[0].1, b"ok"); + assert!(h.session.log.closes().is_empty()); + } + + #[tokio::test] + async fn object_extension_limit() { + for size in [65536usize, 65537] { + for first in [true, false] { + let mut script = Vec::new(); + ietf::GroupHeader { + track_alias: ALIAS, + group_id: SEQUENCE, + sub_group_id: 0, + publisher_priority: 0, + flags: ietf::GroupFlags { + has_extensions: true, + ..Default::default() + }, + } + .encode(&mut script, VERSION) + .unwrap(); + if !first { + // A complete first object exercises the ingestion path on the next one. + script.extend_from_slice(&[0, 0, 1, 42]); + } + 0u64.encode(&mut script, VERSION).unwrap(); + size.encode(&mut script, VERSION).unwrap(); + if size == 65536 { + // Unknown even properties with value zero, valid with delta type ids. + script.resize(script.len() + size, 0); + script.extend_from_slice(&[1, 42]); + } + // Over-limit lengths deliberately carry no extension bytes. + let h = Harness::new(Fill::Done, vec![script]); + let mut consumer = h.track.subscribe(None); + let mut stream = h.stream().await; + let result = h.subscriber.clone().recv_group(&mut stream).await; + if size == 65536 { + result.unwrap(); + let (_, frames) = read_group(&mut consumer).await; + assert_eq!(frames.len(), if first { 1 } else { 2 }); + } else { + assert!(matches!( + result, + Err(Error::Decode(DecodeError::MessageTooLarge { + size: 65537, + max: 65536 + })) + )); + // The stream dispatcher uses this mapping to stop only this stream. + assert_eq!( + crate::StreamError::from(&result.unwrap_err()), + crate::StreamError::MalformedTrack + ); + } + assert!(h.session.log.closes().is_empty()); + } + } + } + /// Append an END_OF_TRACK object: delta 0, an empty payload, then its status. fn end_of_track(mut stream: Vec) -> Vec { for value in [0u64, 0, END_OF_TRACK] { @@ -6168,6 +6870,24 @@ mod stitch_tests { assert!(consumer.recv_group().await.unwrap().is_none(), "then the track ends"); } + /// A group at or past the end an END_OF_TRACK declared contradicts that end, which no + /// later stream can repair, so the whole track fails rather than ending clean without it. + #[tokio::test] + async fn a_group_past_the_declared_end_aborts_the_track() { + use futures::FutureExt; + + let mut h = Harness::new(Fill::Done, vec![tail_stream(SEQUENCE, 0, &[b"late"])]); + h.track.finish_at(SEQUENCE).unwrap(); + let mut stream = h.stream().await; + + let res = h.subscriber.clone().recv_group(&mut stream).await; + assert!(matches!(res, Err(Error::ProtocolViolation)), "{res:?}"); + assert!(matches!( + h.track.closed().now_or_never(), + Some(Error::ProtocolViolation) + )); + } + /// END_OF_TRACK at object 0 says the group does not exist, so the track ends before it /// and no group is created for it. #[tokio::test] @@ -6583,6 +7303,177 @@ mod stitch_tests { assert_eq!(frames[0].1, b"g7-0"); assert_eq!(frames[1].1, b"g7-1"); } + + /// A draft-14/15 end-of-group marker ends a group fetch, so an object after it is a + /// violation rather than another frame. + #[tokio::test] + async fn a_group_fetch_refuses_an_object_past_its_end_marker() { + const DRAFT: Version = Version::Draft15; + let header = |object: u64| ietf::FetchObject::Object { + subgroup: ietf::FetchSubgroup::Zero, + group: Some(SEQUENCE), + object: Some(object), + priority: Some(0), + properties: None, + }; + let mut buf = bytes::BytesMut::new(); + header(0).encode(&mut buf, DRAFT).unwrap(); + 1u64.encode(&mut buf, DRAFT).unwrap(); + buf.put_slice(b"a"); + header(1).encode(&mut buf, DRAFT).unwrap(); + 0u64.encode(&mut buf, DRAFT).unwrap(); + END_OF_GROUP.encode(&mut buf, DRAFT).unwrap(); + header(1).encode(&mut buf, DRAFT).unwrap(); + 1u64.encode(&mut buf, DRAFT).unwrap(); + buf.put_slice(b"b"); + + let mut run = GroupFetchRun::new(DRAFT, buf.to_vec()).await; + let res = run.recv_objects(0, None).await; + assert!(matches!(res, Err(Error::ProtocolViolation)), "{res:?}"); + } + + /// The first object on a fetch stream has no prior object, so leaving any field to + /// the prior one is a violation, not "the requested group, from its start". + #[tokio::test] + async fn a_group_fetch_refuses_a_first_object_that_inherits() { + use ietf::FetchSubgroup::{Prior, Zero}; + let header = |group, object, subgroup, priority| ietf::FetchObject::Object { + subgroup, + group, + object, + priority, + properties: None, + }; + let headers = [ + // Both IDs omitted: "the requested group, from its start" is exactly the bug. + header(None, None, Zero, Some(0)), + header(Some(SEQUENCE), None, Zero, Some(0)), + header(Some(SEQUENCE), Some(0), Prior, Some(0)), + header(Some(SEQUENCE), Some(0), Zero, None), + ]; + + for version in [Version::Draft15, VERSION] { + for header in &headers { + let mut buf = bytes::BytesMut::new(); + header.encode(&mut buf, version).unwrap(); + 1u64.encode(&mut buf, version).unwrap(); + buf.put_slice(b"a"); + + let mut run = GroupFetchRun::new(version, buf.to_vec()).await; + let res = run.recv_objects(0, None).await; + assert!( + matches!(res, Err(Error::ProtocolViolation)), + "{version} {header:?}: {res:?}" + ); + } + } + } + + /// FETCH_OK's End Location inside the group promises every object before it. A stream + /// that FINs short of it, or runs past it, fails the group instead of caching it. + #[tokio::test] + async fn a_group_fetch_must_reach_its_end_location() { + const END: u64 = 3; + for (count, complete) in [(2, false), (3, true), (4, false)] { + let payloads: Vec<&[u8]> = [b"a", b"b", b"c", b"d"][..count].iter().map(|p| &p[..]).collect(); + let mut run = GroupFetchRun::new(VERSION, group_fetch_objects(SEQUENCE, 0, &payloads)).await; + + let group = run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + let mut consumer = group.consume(); + let slot = kio::Producer::new(GroupFetch::Ready { + producer: group, + timescale: None, + start: 0, + end: Some(END), + }); + let res = run.subscriber.recv_group_fetch(&mut run.stream, slot).await; + assert_eq!(res.is_ok(), complete, "{count} objects: {res:?}"); + + let mut read = 0; + let end = loop { + match consumer.read_frame().await { + Ok(Some(_)) => read += 1, + Ok(None) => break Ok(read), + Err(err) => break Err(err), + } + }; + match complete { + true => assert_eq!(end.expect("a complete group"), END), + false => assert!(end.is_err(), "{count} objects: the group must fail, not end"), + } + } + } + + /// A group fetch's objects after the FETCH_HEADER: the first one names the group and + /// `start`, and every later one is the next object. + fn group_fetch_objects(sequence: u64, start: u64, payloads: &[&[u8]]) -> Vec { + let mut buf = bytes::BytesMut::new(); + for (index, payload) in payloads.iter().enumerate() { + let first = index == 0; + ietf::FetchObject::Object { + subgroup: ietf::FetchSubgroup::Zero, + group: first.then_some(sequence), + object: first.then_some(start), + priority: first.then_some(0), + properties: None, + } + .encode(&mut buf, VERSION) + .unwrap(); + (payload.len() as u64).encode(&mut buf, VERSION).unwrap(); + buf.put_slice(payload); + } + buf.to_vec() + } + + /// A subscriber reading one scripted group fetch stream, already past its header. + struct GroupFetchRun { + subscriber: Subscriber, + stream: Reader<::RecvStream, Version>, + track: track::Producer, + _tasks: (Tasks, TaskSet), + } + + impl GroupFetchRun { + async fn new(version: Version, objects: Vec) -> Self { + let mut session = ScriptedSession::per_stream_eof(vec![objects]); + let tasks = TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + version, + tasks.0.clone(), + Default::default(), + ); + let (_, recv) = session.open_bi().await.unwrap(); + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + track::Info::default(), + ); + + Self { + subscriber, + stream: Reader::new(recv, version), + track, + _tasks: tasks, + } + } + + /// Decode the stream into a fresh group numbered from `start`. + async fn recv_objects(&mut self, start: u64, end: Option) -> Result<(), Error> { + let mut group = self.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + group.start_at(start).unwrap(); + self.subscriber + .recv_group_fetch_objects(&mut self.stream, &mut group, start, end, None) + .await + } + } } /// A scripted peer answering SUBSCRIBE then FETCH, so the join is spelled on the wire. @@ -6593,6 +7484,7 @@ mod joining_fetch_tests { coding::Encode as _, lite::test_transport::ScriptedSession, model::ProduceTest, + transport::poll::Session as _, util::{TaskSet, Tasks}, }; @@ -6643,6 +7535,7 @@ mod joining_fetch_tests { group_order: GroupOrder::Ascending, end_of_track: false, end_location: ietf::Location { group: 4, object: 2 }, + properties: Default::default(), }, version, ) @@ -6893,4 +7786,245 @@ mod joining_fetch_tests { let writes = log.writes.lock().unwrap().clone(); assert!(writes.is_empty(), "a refused join must not write SUBSCRIBE"); } + + /// A publisher that resets the request after FETCH_OK owes no fetch stream, so the + /// group it accepted is aborted instead of left open for every reader to wait on. + /// Without that, `run_group_fetch` never returns. + #[tokio::test(start_paused = true)] + async fn a_group_fetch_reset_after_fetch_ok_aborts_the_group() { + const VERSION: Version = Version::Draft19; + const GROUP: u64 = 4; + + let ok = message_bytes( + ietf::FetchOk::ID, + &ietf::FetchOk { + request_id: None, + group_order: GroupOrder::Ascending, + end_of_track: false, + end_location: ietf::Location { + group: GROUP + 1, + object: 0, + }, + properties: Default::default(), + }, + VERSION, + ); + + let session = ScriptedSession::per_stream_reset(vec![ok]); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + VERSION, + tasks, + Default::default(), + ); + + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + track::Info::default(), + ); + let dynamic = track.dynamic(); + let consumer = track.consume(); + let mut fetch = std::pin::pin!(consumer.fetch_group(GROUP, None)); + assert!(futures::poll!(fetch.as_mut()).is_pending()); + let request = dynamic.requested_group().await.expect("no group requested"); + + subscriber + .clone() + .run_group_fetch(Path::new("broadcast").to_owned(), "video".into(), request, None) + .await; + + assert!(fetch.await.is_err(), "the accepted group was aborted"); + } + + /// A group FETCH for a track nothing subscribed to takes its retention window from + /// FETCH_OK's properties, as a subscription would from SUBSCRIBE_OK's. + #[tokio::test(start_paused = true)] + async fn a_group_fetch_takes_fetch_ok_max_age() { + const GROUP: u64 = 4; + const MAX_AGE: Duration = Duration::from_secs(12); + + for version in [Version::Draft17, Version::Draft19] { + let ok = message_bytes( + ietf::FetchOk::ID, + &ietf::FetchOk { + request_id: None, + group_order: GroupOrder::Ascending, + end_of_track: false, + end_location: ietf::Location { + group: GROUP + 1, + object: 0, + }, + properties: ietf::Properties { + max_cache_duration: Some(MAX_AGE), + ..Default::default() + }, + }, + version, + ); + + let session = ScriptedSession::per_stream_reset(vec![ok]); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + version, + tasks, + Default::default(), + ); + + // A track the publisher has not accepted, so the fetch supplies its info. + let broadcast = crate::broadcast::Info::new().produce(); + let reserved = broadcast.reserve_track("video").unwrap(); + let dynamic = reserved.dynamic(); + let track = broadcast.consume().track("video").unwrap(); + let mut fetch = std::pin::pin!(track.fetch_group(GROUP, None)); + assert!(futures::poll!(fetch.as_mut()).is_pending()); + let request = dynamic.requested_group().await.expect("no group requested"); + + subscriber + .clone() + .run_group_fetch(Path::new("broadcast").to_owned(), "video".into(), request, None) + .await; + + let info = tokio::time::timeout(Duration::from_secs(1), track.query()) + .await + .expect("the fetch installed the track info") + .expect("info"); + assert_eq!(info.max_age, Some(MAX_AGE), "{version}"); + } + } + + /// A cache miss for a group's tail asks upstream from the frame the reader wants and + /// numbers what arrives from there, so a publisher that evicted the prefix can answer. + #[tokio::test(start_paused = true)] + async fn a_group_fetch_asks_from_the_wanted_frame() { + const VERSION: Version = Version::Draft19; + const GROUP: u64 = 4; + const START: u64 = 2; + + let ok = message_bytes( + ietf::FetchOk::ID, + &ietf::FetchOk { + request_id: None, + group_order: GroupOrder::Ascending, + end_of_track: false, + end_location: ietf::Location { + group: GROUP + 1, + object: 0, + }, + properties: Default::default(), + }, + VERSION, + ); + + // The fetch stream answering our first request id, from object START on. + let mut objects = bytes::BytesMut::new(); + ietf::FetchHeader::TYPE.encode(&mut objects, VERSION).unwrap(); + ietf::FetchHeader { + request_id: RequestId(1), + } + .encode(&mut objects, VERSION) + .unwrap(); + for (index, payload) in [b"c", b"d"].iter().enumerate() { + let first = index == 0; + ietf::FetchObject::Object { + subgroup: ietf::FetchSubgroup::Zero, + group: first.then_some(GROUP), + object: first.then_some(START), + priority: first.then_some(0), + properties: None, + } + .encode(&mut objects, VERSION) + .unwrap(); + 1u64.encode(&mut objects, VERSION).unwrap(); + objects.extend_from_slice(&payload[..]); + } + + let session = ScriptedSession::per_stream_eof(vec![ok, objects.to_vec()]); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + VERSION, + tasks, + Default::default(), + ); + + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + track::Info::default(), + ); + let dynamic = track.dynamic(); + let consumer = track.consume(); + let mut fetch = std::pin::pin!(consumer.fetch_group(GROUP, group::Fetch::default().with_frame_start(START))); + assert!(futures::poll!(fetch.as_mut()).is_pending()); + let request = dynamic.requested_group().await.expect("no group requested"); + + let serving = tokio::spawn(subscriber.clone().run_group_fetch( + Path::new("broadcast").to_owned(), + "video".into(), + request, + None, + )); + settle().await; + + // The fetch stream, as the peer would open it. + let (_, recv) = session.clone().open_bi().await.unwrap(); + let mut stream = Reader::new(recv, VERSION); + subscriber.clone().recv_fill(&mut stream).await.expect("group fetch"); + serving.await.expect("run_group_fetch"); + + let mut group = fetch.await.expect("fetched"); + assert_eq!(group.index(), START, "the group starts where the reader wanted"); + let mut payloads = Vec::new(); + while let Some(frame) = group.read_frame().await.expect("complete") { + payloads.push(frame.payload.to_vec()); + } + assert_eq!(payloads, [b"c".to_vec(), b"d".to_vec()]); + + let messages = decode_messages(&session.log, VERSION); + let fetch = messages.iter().find(|(id, _)| *id == ietf::Fetch::ID).expect("FETCH"); + let mut body = fetch.1.clone(); + let msg = ietf::Fetch::decode_msg(&mut body, VERSION).unwrap(); + let FetchType::Standalone { start, end, .. } = msg.fetch_type else { + panic!("a group fetch is standalone: {:?}", msg.fetch_type); + }; + assert_eq!( + start, + ietf::Location { + group: GROUP, + object: START + } + ); + assert_eq!( + end, + ietf::Location { + group: GROUP, + object: 0 + }, + "through the end of the group" + ); + } } diff --git a/rs/moq-net/src/lite/announce.rs b/rs/moq-net/src/lite/announce.rs index 9e460d15302..415fe598d3c 100644 --- a/rs/moq-net/src/lite/announce.rs +++ b/rs/moq-net/src/lite/announce.rs @@ -201,10 +201,13 @@ impl Decode for Cost { if !version.has_route_cost() { return Ok(Cost::UNKNOWN); } - Ok(Cost { + // Costs saturate at 2^62-1 on every version, so a larger one (lite-07's varints + // reach 2^64-1) reads as the ceiling and still forwards to an older peer. + let cost = Cost { warm: u64::decode(buf, version)?, cold: u64::decode(buf, version)?, - }) + }; + Ok(cost.clamped()) } } @@ -783,15 +786,19 @@ mod tests { ); } - // A peer may legally advertise the largest varint there is, and adding this - // link's price to it must not push the result out of range. + // Costs saturate at 2^62-1 on every version, lite-07's 64-bit varints included, so + // charging a link on top of the ceiling still re-encodes for a peer on any version. #[test] fn charged_cost_stays_encodable() { - let mut buf = Vec::new(); - crate::origin::Cost::MAX - .charged(1) - .encode(&mut buf, Version::Lite06) - .expect("a charged cost must stay encodable"); + let cost = Cost::new(u64::MAX).charged(1); + assert_eq!(cost, Cost::new((1 << 62) - 1)); + assert_eq!(Cost::MAX.charged(1), cost); + for version in [Version::Lite06, Version::Lite07] { + let mut buf = Vec::new(); + cost.encode(&mut buf, version) + .expect("a charged cost must stay encodable"); + assert_eq!(Cost::decode(&mut &buf[..], version).unwrap(), cost, "{version}"); + } } #[test] diff --git a/rs/moq-net/src/lite/compress.rs b/rs/moq-net/src/lite/compress.rs index e908e8cbecd..eda17b39163 100644 --- a/rs/moq-net/src/lite/compress.rs +++ b/rs/moq-net/src/lite/compress.rs @@ -581,7 +581,7 @@ mod tests { /// A compressed stream pinned byte for byte: `js/net/src/lite/announce.test.ts` /// decodes the same hex, so a codec change on either side breaks both. - const GOLDEN: &str = "001600000a726f6f6d2f612f63616d000251116222000000000d0102036d696301017333010000020a00010180004444010000010101000d02010162020180005555010000"; + const GOLDEN: &str = "001600000a726f6f6d2f612f63616d00029111a222000000000d0102036d69630101b3330100000209000101c04444010000010101000c020101620201c05555010000"; fn golden() -> Vec { use crate::fuzz::Announced; @@ -604,7 +604,7 @@ mod tests { /// The literal lite-07 stream `js/net` writes for the same announcements, which /// never picks a base. - const JS_LITERAL: &str = "001600000a726f6f6d2f612f63616d000251116222000000001600000a726f6f6d2f612f6d6963000273336222000000020c0000028000444462220000000101010014000006726f6f6d2f620002800055556222000000"; + const JS_LITERAL: &str = "001600000a726f6f6d2f612f63616d00029111a222000000001600000a726f6f6d2f612f6d69630002b333a222000000020b000002c04444a2220000000101010013000006726f6f6d2f620002c05555a222000000"; #[test] fn js_literal_stream_decodes() { diff --git a/rs/moq-net/src/lite/message.rs b/rs/moq-net/src/lite/message.rs index 0d28eb735f6..c3c0ceb61a9 100644 --- a/rs/moq-net/src/lite/message.rs +++ b/rs/moq-net/src/lite/message.rs @@ -23,6 +23,9 @@ pub(super) fn decode_size(buf: &mut B, version: Version) -> Result(&self, w: &mut W, version: Version) -> Result<(), EncodeError>; @@ -35,6 +38,10 @@ impl Encode for T { tracing::trace!(?self, "encoding"); let mut sizer = Sizer::default(); self.encode_msg(&mut sizer, version)?; + // Never emit a body our own receiver would refuse. + if sizer.size > Self::MAX_SIZE { + return Err(EncodeError::TooLarge); + } sizer.size.encode(w, version)?; self.encode_msg(w, version) } @@ -43,6 +50,12 @@ impl Encode for T { impl Decode for T { fn decode(buf: &mut B, version: Version) -> Result { let size = decode_size(buf, version)?; + if size > Self::MAX_SIZE { + return Err(DecodeError::MessageTooLarge { + size, + max: Self::MAX_SIZE, + }); + } if tracing::enabled!(tracing::Level::TRACE) { if buf.remaining() < size { @@ -50,7 +63,7 @@ impl Decode for T { } let raw = buf.copy_to_bytes(size); let mut slice = &raw[..]; - match Self::decode_msg(&mut slice, version) { + match Self::decode_msg(&mut slice, version).map_err(DecodeError::complete) { Ok(result) => { if slice.remaining() > 0 { return Err(DecodeError::Long); @@ -68,7 +81,7 @@ impl Decode for T { return Err(DecodeError::Short); } let mut limited = buf.take(size); - match Self::decode_msg(&mut limited, version) { + match Self::decode_msg(&mut limited, version).map_err(DecodeError::complete) { Ok(result) => { if limited.remaining() > 0 { return Err(DecodeError::Long); diff --git a/rs/moq-net/src/lite/parameters.rs b/rs/moq-net/src/lite/parameters.rs index b0148a6aae3..b7930a6c747 100644 --- a/rs/moq-net/src/lite/parameters.rs +++ b/rs/moq-net/src/lite/parameters.rs @@ -23,20 +23,19 @@ impl Parameters { self.0.get(&id).map(Vec::as_slice) } - /// Set a parameter to a varint value, replacing any existing entry. - pub fn set_varint(&mut self, id: u64, value: u64) { - let mut buf = Vec::new(); - // Infallible: writing into a Vec never runs short. - value.encode(&mut buf, Version::Lite05).expect("varint encode into Vec"); - self.0.insert(id, buf); + /// Set a parameter to a varint value in `version`'s encoding, replacing any existing entry. + pub fn set_varint(&mut self, id: u64, value: u64, version: Version) -> Result<(), EncodeError> { + self.0.insert(id, value.encode_bytes(version)?.to_vec()); + Ok(()) } - /// Decode a parameter as a single varint, if present. Errors if trailing bytes remain. - pub fn get_varint(&self, id: u64) -> Result, DecodeError> { + /// Decode a parameter as a single varint in `version`'s encoding, if present. Errors if + /// trailing bytes remain. + pub fn get_varint(&self, id: u64, version: Version) -> Result, DecodeError> { let Some(mut bytes) = self.0.get(&id).map(Vec::as_slice) else { return Ok(None); }; - let value = u64::decode(&mut bytes, Version::Lite05)?; + let value = u64::decode(&mut bytes, version)?; if !bytes.is_empty() { return Err(DecodeError::Long); } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index f8ef9bd3f2c..f27f44bec95 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1019,6 +1019,20 @@ impl TrackInfoServe { fn poll_serve(&mut self, waiter: &kio::Waiter) -> Poll> { loop { + // While the lookup runs the requester sends nothing, so its send side closing, + // by FIN or reset, means it stopped waiting. Drop the lookup then, so the + // abandonment reaches our own upstream instead of pinning it for an answer + // nobody reads. (Once answered, its FIN is the normal end; `Finish` waits on it.) + if matches!( + self.state, + TrackInfoState::Hop { .. } | TrackInfoState::Request { .. } | TrackInfoState::Query { .. } + ) { + let stream = self.stream.as_mut().expect("stream present"); + let mut cx = waiter.context(); + if let Poll::Ready(res) = stream.reader.poll_closed(&mut cx) { + return Poll::Ready(Err(res.err().unwrap_or(Error::Cancel))); + } + } match &mut self.state { TrackInfoState::Decode => { let stream = self.stream.as_mut().expect("stream present"); @@ -1903,6 +1917,7 @@ mod announce_test { h.announcement .update(crate::origin::Route::default().with_hops(pub_hops()).with_cost(3)) .unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; match h.wire.take_announces().as_slice() { [lite::AnnounceBroadcast::Restart { id: 0, hops, cost }] => { @@ -1954,10 +1969,12 @@ mod announce_test { let mut h = harness().await; let route = |cost| crate::origin::Route::default().with_hops(pub_hops()).with_cost(cost); h.announcement.update(route(u64::MAX)).unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; assert_eq!(h.wire.take_announces().len(), 1, "expected the clamped restart"); h.announcement.update(route(u64::MAX - 1)).unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; h.assert_idle(); } @@ -2027,6 +2044,7 @@ mod announce_test { .with_cost(u64::MAX), ) .unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; match h.wire.take_announces().as_slice() { [lite::AnnounceBroadcast::Restart { cost, .. }] => { @@ -2612,7 +2630,7 @@ enum GroupState { batch_pos: usize, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a - /// late cancel can still reset the stream. + /// late cancel or expiry can still reset the stream. Closed { writer: Writer, }, @@ -2653,6 +2671,29 @@ impl GroupServe { /// every failure as Cancel. fn poll_serve(&mut self, waiter: &kio::Waiter) -> Poll> { loop { + // Queue and SUBSCRIBE_UPDATE priority changes apply on every pass, whatever + // the stream is blocked on, including a FIN awaiting its acknowledgement + // (the transport still schedules its retransmissions). The rank is re-read + // as a send order when handled, since the two conventions are inverted. + if let GroupState::Serve { writer, .. } | GroupState::Closed { writer } = &mut self.state { + while let Poll::Ready(rank) = self.priority.poll_next(waiter) { + writer.set_priority(PriorityHandle::send_order_of(rank)); + } + let seen = self.ctx.track_priority_seen; + // A dropped producer just disables this arm, like the queue arm above. + if let Poll::Ready(Ok(value)) = self.ctx.track_priority.poll(waiter, |value| { + if **value != seen { + Poll::Ready(**value) + } else { + Poll::Pending + } + }) { + self.ctx.track_priority_seen = value; + let rank = self.priority.set_track(value); + writer.set_priority(PriorityHandle::send_order_of(rank)); + } + } + match &mut self.state { GroupState::Open => { if self.group.poll_expired(waiter) { @@ -2700,26 +2741,6 @@ impl GroupServe { } => { let mut cx = waiter.context(); - // Queue and SUBSCRIBE_UPDATE priority changes apply on every pass, - // whatever the write pipeline is blocked on. The rank is re-read as - // a send order when handled, since the two conventions are inverted. - while let Poll::Ready(rank) = self.priority.poll_next(waiter) { - writer.set_priority(PriorityHandle::send_order_of(rank)); - } - let seen = self.ctx.track_priority_seen; - // A dropped producer just disables this arm, like the queue arm above. - if let Poll::Ready(Ok(value)) = self.ctx.track_priority.poll(waiter, |value| { - if **value != seen { - Poll::Ready(**value) - } else { - Poll::Pending - } - }) { - self.ctx.track_priority_seen = value; - let rank = self.priority.set_track(value); - writer.set_priority(PriorityHandle::send_order_of(rank)); - } - let outcome = 'serve: { // The peer closing first cancels the group. if writer.poll_closed(&mut cx).is_ready() { @@ -2843,7 +2864,20 @@ impl GroupServe { // poll_close releases the stream on completion: the peer acknowledged // everything, so the Drop fallback must not reset the stream and // discard bytes still retransmitting. - let res = ready!(writer.poll_close(&mut cx)); + let res = match writer.poll_close(&mut cx) { + Poll::Ready(res) => res, + // Those bytes still hold the connection until acknowledged, so a + // group gone stale meanwhile releases them like one still serving. + Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + let GroupState::Closed { writer } = std::mem::replace(&mut self.state, GroupState::Done) + else { + unreachable!() + }; + writer.abort(&Error::Old); + return Poll::Ready(Err(Error::Old)); + } + Poll::Pending => return Poll::Pending, + }; self.state = GroupState::Done; return Poll::Ready(res.map(|()| { tracing::debug!(sequence = self.sequence, "finished group"); @@ -3244,6 +3278,92 @@ mod serve_group_test { ); } + /// A FIN holds the group's bytes until the peer acknowledges it, so a group that + /// goes stale while waiting still expires instead of pinning them. + #[tokio::test] + async fn unacknowledged_fin_expires_with_the_group() { + tokio::time::pause(); + + let session = SinkSession::new(Log::default()).with_unacked_fin(); + let log = session.log.clone(); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + version: Version::Lite06, + timescale: Some(crate::Timescale::default()), + opens: Default::default(), + }; + + let track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, group)); + assert!(futures::poll!(serve.as_mut()).is_pending(), "the FIN is unacknowledged"); + assert!(log.resets().is_empty()); + + tokio::time::advance(Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(futures::poll!(serve.as_mut()), Poll::Ready(Err(Error::Old)))); + assert_eq!(log.resets(), vec![crate::StreamError::Old.to_code()]); + } + + /// The transport keeps scheduling a finished stream's retransmissions until the + /// FIN is acknowledged, so queue and SUBSCRIBE_UPDATE reorders still reach it. + #[tokio::test] + async fn unacknowledged_fin_follows_priority_changes() { + let session = SinkSession::new(Log::default()).with_unacked_fin(); + let log = session.log.clone(); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + version: Version::Lite06, + timescale: Some(crate::Timescale::default()), + opens: Default::default(), + }; + + let track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); + group.write_frame(Timestamp::ZERO, b"hello".as_slice()).unwrap(); + let consumer = group.consume(); + group.finish().unwrap(); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let queue = subscription.priority.clone(); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, consumer)); + assert!(futures::poll!(serve.as_mut()).is_pending(), "the FIN is unacknowledged"); + assert_eq!(log.priorities().last(), Some(&255)); + + // A newer group of the same subscription goes first. + let _newer = queue.insert(Priority::new(0, 0, 1)); + assert!(futures::poll!(serve.as_mut()).is_pending()); + assert_eq!(log.priorities().last(), Some(&254)); + + // A SUBSCRIBE_UPDATE raising this track reranks it above the newer group. + *track_priority.write().ok().expect("the group watches the priority") = 1; + assert!(futures::poll!(serve.as_mut()).is_pending()); + assert_eq!(log.priorities().last(), Some(&255)); + assert!(log.resets().is_empty()); + } + /// A lite-07 subscription's run loop, from group 0, and the log of its subscribe stream. fn lite07_run( session: SinkSession, @@ -3824,4 +3944,59 @@ mod tests { assert_eq!(probes[0].bitrate, Some(1_000_000)); assert_eq!(probes[1].bitrate, None); } + + /// A requester that FINs its TRACK request before the answer has terminated the + /// transaction (moq-lite: closing the send direction ends the stream), so the + /// lookup ends rather than pinning an upstream request nobody will read. + #[tokio::test] + async fn track_info_ends_when_the_requester_finishes() { + use crate::coding::Encode; + use crate::lite::test_transport::ScriptedSession; + + let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + let broadcast = origin.create_broadcast("room").unwrap(); + // Held, never polled: the track request stays unanswered. + let _dynamic = broadcast.dynamic(); + broadcast.announce(Default::default()).unwrap(); + + let peer_setup = crate::lite::PeerSetup::default(); + peer_setup.set(crate::lite::Setup::default()); + let (_, goaway) = crate::goaway::Handle::new(true); + let publisher = Publisher::new(PublisherConfig { + runtime: crate::time::Clock::tokio(), + session: ScriptedSession::new(Vec::new()), + origin: origin.consume(), + version: Version::Lite06, + peer_setup, + goaway, + peer_hop: None, + }); + + let mut request = Vec::new(); + lite::Track { + broadcast: crate::Path::new("room"), + track: "video".into(), + } + .encode(&mut request, Version::Lite06) + .unwrap(); + + for (finished, session) in [ + (false, ScriptedSession::new(request.clone())), + (true, ScriptedSession::eof(request.clone())), + ] { + let mut session = session; + let (send, recv) = futures::future::poll_fn(|cx| { + ::poll_open_bi(&mut session, cx) + }) + .await + .unwrap(); + let stream = Stream:: { + writer: Writer::new(send, Version::Lite06), + reader: crate::coding::Reader::new(recv, Version::Lite06), + }; + let mut serve = TrackInfoServe::new(publisher.shared.clone(), stream).unwrap(); + let ended = serve.poll(&kio::Waiter::noop()).is_ready(); + assert_eq!(ended, finished, "finished={finished}"); + } + } } diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 51225882cd2..53810df0476 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -185,6 +185,8 @@ pub struct Setup { } impl Message for Setup { + const MAX_SIZE: usize = crate::setup::MAX_SETUP_SIZE; + fn decode_msg(r: &mut R, version: Version) -> Result { if !version.has_setup_stream() { return Err(DecodeError::Version); @@ -192,7 +194,7 @@ impl Message for Setup { let params = Parameters::decode(r, version)?; let probe = params - .get_varint(PARAM_PROBE)? + .get_varint(PARAM_PROBE, version)? .map(ProbeLevel::from_code) .unwrap_or_default(); let path = match params.get_bytes(PARAM_PATH) { @@ -203,11 +205,13 @@ impl Message for Setup { ), None => None, }; - let role = params.get_varint(PARAM_ROLE)?.and_then(Role::from_code); - let cost = params.get_varint(PARAM_COST)?; + let role = params.get_varint(PARAM_ROLE, version)?.and_then(Role::from_code); + let cost = params.get_varint(PARAM_COST, version)?; // 0 is legal on the wire but carries no identity (it can't be excluded), // so it decodes as "not declared" rather than an error. - let hop = params.get_varint(PARAM_HOP)?.and_then(|id| crate::Hop::new(id).ok()); + let hop = params + .get_varint(PARAM_HOP, version)? + .and_then(|id| crate::Hop::new(id).ok()); Ok(Self { probe, @@ -226,7 +230,7 @@ impl Message for Setup { let mut params = Parameters::default(); // None is the wire default, so omit it to keep the message empty when nothing is set. if self.probe != ProbeLevel::None { - params.set_varint(PARAM_PROBE, self.probe.to_code()); + params.set_varint(PARAM_PROBE, self.probe.to_code(), version)?; } if let Some(path) = &self.path { params.set_bytes(PARAM_PATH, path.as_bytes().to_vec()); @@ -234,13 +238,13 @@ impl Message for Setup { // Bidirectional is the wire default (absence of the parameter), so only a // directional role is encoded. if let Some(role) = self.role { - params.set_varint(PARAM_ROLE, role.to_code()); + params.set_varint(PARAM_ROLE, role.to_code(), version)?; } if let Some(cost) = self.cost { - params.set_varint(PARAM_COST, cost); + params.set_varint(PARAM_COST, cost, version)?; } if let Some(hop) = self.hop { - params.set_varint(PARAM_HOP, hop.id()); + params.set_varint(PARAM_HOP, hop.id(), version)?; } params.encode(w, version) @@ -363,6 +367,48 @@ mod tests { } } + /// Parameter values follow the session's varint codec, not a fixed one: a value that + /// takes the two-byte QUIC form on lite-06 fits one leading-ones byte on lite-07. + #[test] + fn parameter_values_use_the_version_codec() { + let msg = Setup { + cost: Some(100), + ..Default::default() + }; + for (version, wire) in [ + (Version::Lite06, &[0x05, 0x01, 0x04, 0x02, 0x40, 0x64][..]), + (Version::Lite07, &[0x04, 0x01, 0x04, 0x01, 0x64][..]), + ] { + let mut buf = Vec::new(); + msg.encode(&mut buf, version).unwrap(); + assert_eq!(buf, wire, "{version}"); + assert_eq!(Setup::decode(&mut &buf[..], version).unwrap(), msg, "{version}"); + } + } + + /// Never emit a SETUP our own receiver would refuse. + #[test] + fn encode_enforces_the_setup_limit() { + // Count, id, and a 4-byte length varint precede the path. + let at_limit = crate::setup::MAX_SETUP_SIZE - 6; + let msg = Setup { + path: Some("a".repeat(at_limit)), + ..Default::default() + }; + assert_eq!(round_trip(&msg), msg); + + let msg = Setup { + path: Some("a".repeat(at_limit + 1)), + ..Default::default() + }; + let mut buf = bytes::BytesMut::new(); + assert!(matches!( + msg.encode(&mut buf, Version::Lite05), + Err(EncodeError::TooLarge) + )); + assert!(buf.is_empty()); + } + #[test] fn path_round_trip() { let msg = Setup { @@ -390,7 +436,7 @@ mod tests { let version = Version::Lite05; let mut params = Parameters::default(); - params.set_varint(super::PARAM_HOP, 0); + params.set_varint(super::PARAM_HOP, 0, version).unwrap(); let mut body = bytes::BytesMut::new(); params.encode(&mut body, version).unwrap(); // Frame the body with the Message Length prefix `Setup::decode` expects. @@ -430,7 +476,7 @@ mod tests { // Frame a SETUP message carrying an unknown probe level (99) by hand: the // parameters body, prefixed with its length (the lite Message size prefix). let mut params = Parameters::default(); - params.set_varint(PARAM_PROBE, 99); + params.set_varint(PARAM_PROBE, 99, Version::Lite05).unwrap(); let mut body = Vec::new(); params.encode(&mut body, Version::Lite05).unwrap(); @@ -460,7 +506,7 @@ mod tests { // server. The draft mandates this fallback. for code in [0u64, 9, 250] { let mut params = Parameters::default(); - params.set_varint(PARAM_ROLE, code); + params.set_varint(PARAM_ROLE, code, Version::Lite05).unwrap(); let mut body = Vec::new(); params.encode(&mut body, Version::Lite05).unwrap(); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 325fe0de100..4e85ed56ffd 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -15,7 +15,7 @@ use crate::{ }; use super::Version; -use crate::tail::{self, Settle, Tail}; +use crate::tail::{self, Reading, Settle, Tail}; use kio::Lock; @@ -69,6 +69,11 @@ pub(super) struct Subscriber { // another session's, while a client only assigns one it knows out of band. The // assigned id stays local and is never written into a hop chain. session_origin: crate::Hop, + // A random Hop ID of this connection's own, written as the first hop of any chain + // that names no publisher (Lite01/02, a Lite03 placeholder, or a peer reporting 0), + // so a publisher that reconnects reads downstream as a new one. Fresh per + // connection, unlike `session_origin`. + stamp: crate::Hop, subscribes: Lock>, /// Why this session ended, once it has. A track still waiting on TRACK_INFO is /// not in [`Self::subscribes`], so dropping its request reads this instead of @@ -110,6 +115,7 @@ impl Subscriber { recv_bandwidth: config.recv_bandwidth, self_origin, session_origin: config.peer_hop.unwrap_or(crate::Hop::UNKNOWN), + stamp: crate::Hop::random(), subscribes: Default::default(), ended: Default::default(), next_id: Default::default(), @@ -306,13 +312,12 @@ impl Subscriber { return Ok(false); } - // Lite03 carries its hop count as UNKNOWN placeholders rather than real - // ids; they stay 0 and count as anonymous. Lite01/02 send no list at all. - // Either way the chain must have at least the anonymous mark so a - // downstream hop can see that this path passed through an unidentified hop. - if hops.is_empty() { - hops.push(crate::Hop::UNKNOWN) - .expect("an empty hop chain always has room for one entry, and repeats nothing"); + // Lite01/02 send no list at all, and Lite03 carries only UNKNOWN placeholders, + // so the publisher may be unnamed: this connection's stamp goes in front to name + // it, and the 0s stay so the route still ranks as anonymous. + if hops.stamp(self.stamp).is_err() { + tracing::debug!(route = %self.log_path(&path), "dropping announce; no room to stamp the chain"); + return Ok(false); } tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "announce"); @@ -405,9 +410,11 @@ impl Subscriber { return Ok(false); } - if hops.is_empty() { - hops.push(crate::Hop::UNKNOWN) - .expect("an empty hop chain always has room for one entry, and repeats nothing"); + // Named by this connection's stamp when the chain names no publisher, exactly as + // the announce was, so a restart of the same unnamed publisher stays in place. + if hops.stamp(self.stamp).is_err() { + announced.declined(path); + return Ok(false); } tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "restart"); @@ -456,7 +463,7 @@ impl Subscriber { // A datagram is never owed a stream, so it never holds the subscription's end open. if let Ok(mut tail) = entry.tail.write() { - tail.account(dg.sequence..dg.sequence.saturating_add(1)); + tail.account(dg.sequence..dg.sequence.saturating_add(1), self.runtime.now()); } entry.producer.insert_datagram(dg.sequence, timestamp, dg.payload)?; Ok(()) @@ -742,6 +749,7 @@ enum GroupRecvState { group: crate::recv::Group, track: track::Producer, ingest: FrameIngest, + _reading: Reading, }, Done, } @@ -762,22 +770,40 @@ impl GroupRecv { let mut cx = waiter.context(); let hdr = ready!(self.reader.poll_decode::(&mut cx))?; - let (group, track, timescale) = { + let (group, track, timescale, reading) = { let mut subs = self.subscriber.subscribes.lock(); let entry = subs.get_mut(&hdr.subscribe).ok_or(Error::Cancel)?; - if let Ok(mut tail) = entry.tail.write() { - tail.open(hdr.sequence); - } + // The subscription's end waits until this stream is read. + let reading = Reading::open(&entry.tail, Some(hdr.sequence), self.subscriber.runtime.now()); let group_info = group::Info { sequence: hdr.sequence }; // Stats (groups/frames/bytes) are counted in the model as the group // is written, through the tagged `track::Producer`. - let mut group = entry.producer.create_group(group_info)?; + let mut group = match entry.producer.create_group(group_info) { + Ok(group) => group, + // The group is at or past the end the publisher declared, which no + // later stream can repair. Before lite-05 only a local finish sets + // an end, and lite-05 specified an inclusive one, so its last + // group lands on it: drop only that stream there. + Err(Error::Closed) + if !matches!( + self.subscriber.version, + Version::Lite01 + | Version::Lite02 | Version::Lite03 + | Version::Lite04 | Version::Lite05 + ) => + { + tracing::warn!(group = hdr.sequence, "group past the declared end of track"); + let _ = entry.producer.clone().abort(Error::ProtocolViolation); + return Poll::Ready(Err(Error::ProtocolViolation)); + } + Err(err) => return Poll::Ready(Err(err)), + }; // The stream may carry only the tail of the group; number the frames // from where the publisher said they start so a reader splicing // across routes lines them up. group.start_at(hdr.frame_start)?; - (group, entry.producer.clone(), entry.timescale) + (group, entry.producer.clone(), entry.timescale, reading) }; // The timescale came from TRACK_INFO (read before this subscription was @@ -787,9 +813,12 @@ impl GroupRecv { group: crate::recv::Group::new(group), track, ingest: FrameIngest::new(self.subscriber.runtime.clone(), timescale), + _reading: reading, }; } - GroupRecvState::Serve { group, track, ingest } => { + GroupRecvState::Serve { + group, track, ingest, .. + } => { // The track or group dying cancels the stream; the peer's own close // arrives through the ingest's reads. let res = 'serve: { @@ -808,7 +837,10 @@ impl GroupRecv { // Held until the group settles below, so a frame the track or group cut // short drops into an already-aborted group instead of reporting a loss. let GroupRecvState::Serve { - group, ingest: _ingest, .. + group, + ingest: _ingest, + _reading, + .. } = std::mem::replace(&mut self.state, GroupRecvState::Done) else { unreachable!() @@ -1431,6 +1463,172 @@ mod tests { const VERSION: Version = Version::Lite05; + /// The owed groups start at the floor the demand last asked for, which an update can move + /// either way after SUBSCRIBE_START answered the SUBSCRIBE. + #[tokio::test] + async fn the_owed_floor_follows_the_demand() { + let mut session = crate::lite::test_transport::ScriptedSession::new(Vec::new()); + let stream = Stream::open(&mut session, VERSION).await.unwrap(); + let mut sub = SubStream { + stream, + id: 0, + max_age: Duration::ZERO, + start: Some(Position::group(2)), + priority: 0, + requested: Some(Position::group(2)), + tail: Default::default(), + served: None, + end: Some(lite::SubscribeEnd { group: 10, streams: 0 }), + }; + assert_eq!( + sub.owed(None), + Some(10..10), + "without SUBSCRIBE_START nothing was served" + ); + + sub.served = Some(4); + assert_eq!( + sub.owed(None), + Some(2..10), + "the groups below START are accounted for on arrival" + ); + sub.start = Some(Position::group(6)); + assert_eq!(sub.owed(None), Some(6..10), "a raised floor owes nothing below it"); + sub.start = Some(Position::group(1)); + assert_eq!( + sub.owed(None), + Some(1..10), + "a lowered floor owes what it newly asked for" + ); + sub.start = None; + assert_eq!( + sub.owed(Some(8)), + Some(4..8), + "a live-edge floor starts where START resolved it" + ); + } + + /// A group at or past the end the publisher declared contradicts that end, which no later + /// stream can repair, so the whole track fails rather than ending clean without it. lite-05 + /// specified an inclusive end, so there it costs only that group's stream. + #[tokio::test] + async fn a_group_past_the_declared_end_aborts_the_track() { + use crate::transport::poll::Session as _; + + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + let mut script = Vec::new(); + lite::Group { + subscribe: 7, + sequence: 3, + frame_start: 0, + } + .encode(&mut script, version) + .unwrap(); + let mut session = crate::lite::test_transport::ScriptedSession::eof(script); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::Clock::tokio(), + session: session.clone(), + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup: Default::default(), + peer_hop: None, + cost: None, + going_away: Default::default(), + }); + + let mut track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "video", None); + track.finish_at(3).unwrap(); + subscriber.subscribes.lock().insert( + 7, + TrackEntry { + producer: track.clone(), + timescale: Some(Timescale::default()), + tail: Default::default(), + }, + ); + + let (_, recv) = session.open_bi().await.unwrap(); + let mut group = GroupRecv::new(subscriber, Reader::new(recv, version)); + let res = kio::wait(|waiter| group.poll_serve(waiter)).await; + match version { + Version::Lite05 => { + assert!(matches!(res, Err(Error::Closed)), "{version:?}: {res:?}"); + assert!( + track.closed().now_or_never().is_none(), + "{version:?}: the track lives on" + ); + } + _ => { + assert!(matches!(res, Err(Error::ProtocolViolation)), "{version:?}: {res:?}"); + assert!(matches!(track.closed().now_or_never(), Some(Error::ProtocolViolation))); + } + } + } + } + + /// A SUBSCRIBE_END below a group already received contradicts that group. lite-05 + /// specified an inclusive end, and `@moq/net` 0.1.3 to 0.1.9 sent one, so there it only + /// costs the early boundary; later drafts abort the track. + #[tokio::test(start_paused = true)] + async fn a_subscribe_end_below_a_received_group() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + let mut responses = Vec::new(); + lite::SubscribeResponse::Start(lite::SubscribeStart { group: 0 }) + .encode(&mut responses, version) + .unwrap(); + lite::SubscribeResponse::End(lite::SubscribeEnd { group: 2, streams: 1 }) + .encode(&mut responses, version) + .unwrap(); + let session = crate::lite::test_transport::ScriptedSession::eof(responses); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::Clock::tokio(), + session, + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup: Default::default(), + peer_hop: None, + cost: None, + going_away: Default::default(), + }); + let serve = TrackServe { + subscriber, + path: Path::new("room").to_owned(), + name: "video".to_string(), + }; + let broadcast = crate::broadcast::Info::new().produce(); + let request = broadcast.reserve_track("video").unwrap(); + let serving = ServeLoop::new(&serve, request, Default::default(), Some(Timescale::default())); + let mut group = serving.serving.create_group(group::Info { sequence: 2 }).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"2".as_slice()).unwrap(); + group.finish().unwrap(); + let mut reader = broadcast + .consume() + .track("video") + .unwrap() + .subscribe(None) + .await + .unwrap(); + let mut running = TrackServeRun { + serve, + state: TrackRunState::Serve(serving), + }; + kio::wait(|waiter| kio::Task::poll(&mut running, waiter)).await; + + let end = loop { + match reader.recv_group().await { + Ok(Some(_)) => continue, + end => break end.map(|group| group.map(|group| group.sequence)), + } + }; + match version { + Version::Lite05 => assert!(matches!(end, Ok(None)), "{version:?}: {end:?}"), + _ => assert!(matches!(end, Err(Error::ProtocolViolation)), "{version:?}: {end:?}"), + } + } + } + /// Drive the subscriber with a peer's response bytes followed by FIN. async fn check_subscription_fin(version: Version, responses: Vec, clean: bool) { let session = crate::lite::test_transport::ScriptedSession::eof(responses); @@ -1623,6 +1821,65 @@ mod tests { ); } + /// A track still waiting on TRACK_INFO ends once nobody wants it, whether its TRACK + /// stream never opened (the peer's stream credit is spent), its request is stuck in + /// send, or its peer never answers. + /// Otherwise every request a relay's front abandons (a failover, a reader leaving) + /// holds a task, a stream, and the track until the peer answers, which may be never. + #[tokio::test] + async fn an_unused_track_stops_waiting_for_info() { + // A closed gate holds the TRACK request in its send; an open one sends it to a + // peer that never answers. + let (closed, open) = (kio::Producer::new(false), kio::Producer::new(true)); + for (stage, session) in [ + ("open", SinkSession::default()), + ("send", SinkSession::gated_bi(closed.consume())), + ("read", SinkSession::gated_bi(open.consume())), + ] { + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::Clock::tokio(), + session, + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version: VERSION, + peer_setup: Default::default(), + peer_hop: None, + cost: None, + going_away: Default::default(), + }); + + let broadcast = crate::broadcast::Info::new().produce(); + let mut dynamic = broadcast.dynamic(); + let consumer = broadcast.consume(); + let mut waiting = Box::pin(consumer.track("video").unwrap().subscribe(None)); + assert!( + futures::poll!(waiting.as_mut()).is_pending(), + "{stage}: waiting on the publisher" + ); + let request = dynamic.requested_track().now_or_never().unwrap().expect("request"); + + let mut run = TrackServeRun::new( + TrackServe { + subscriber, + path: Path::new("room").to_owned(), + name: "video".to_string(), + }, + request, + ); + let waiter = kio::Waiter::noop(); + assert!( + kio::Task::poll(&mut run, &waiter).is_pending(), + "{stage}: waits while the track is wanted" + ); + + drop(waiting); + assert!( + kio::Task::poll(&mut run, &waiter).is_ready(), + "{stage}: an unused track kept waiting on TRACK_INFO" + ); + } + } + /// `establish` puts exactly one SUBSCRIBE on the wire, and the id is registered /// before any of it reaches the transport. /// @@ -2470,8 +2727,9 @@ mod tests { ); } - /// A peer that declares no identity is marked anonymous (hop 0). The assigned - /// identity stays on `via` for split-horizon and is never written into the chain. + /// A peer that declares no identity has its publisher named by the connection's + /// stamp. The assigned identity stays on `via` for split-horizon and is never + /// written into the chain. #[tokio::test] async fn assigned_peer_hop_attributes_announces() { let session = SinkSession::new(Default::default()); @@ -2506,19 +2764,21 @@ mod tests { .unwrap(); assert!(accepted); - // The route is announced synchronously: hop 0 on the wire, assigned id local. + // The route is announced synchronously: the stamp in the chain, assigned id local. let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN]); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN]); + assert_ne!(subscriber.stamp, assigned); assert!(route.is_anonymous()); let mut hidden = consumer.excluding(assigned).announced(); hidden.assert_next_wait(); } - /// Lite03 hop-count placeholders stay 0 and count as anonymous; they are not - /// rewritten with the assigned identity. + /// Lite03 hop-count placeholders name nobody, so the connection's stamp goes in front; + /// the placeholders stay 0 and count as anonymous. None is rewritten with the + /// assigned identity. #[tokio::test] async fn lite03_placeholders_stay_anonymous() { let assigned = crate::Hop::new(777).unwrap(); @@ -2554,26 +2814,28 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN, crate::Hop::UNKNOWN]); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN, crate::Hop::UNKNOWN]); assert!(route.is_anonymous()); } - /// A peer with no assigned identity is attributed the reserved origin 0 - /// (UNKNOWN). This layer never mints one of its own: whether an anonymous peer - /// gets an identity, and whether two of its sessions share it, is the caller's - /// policy, and a minted id here would be indistinguishable from a declared one. + /// A publisher that names nobody is stamped with a random id fresh per connection, + /// never 0, ahead of the 0 that keeps it ranked as unknown: a restart on the same connection keeps the stamp and updates in place, + /// while the same publisher reconnecting reads as a new first hop. #[tokio::test] - async fn absent_peer_hop_stamps_unknown() { - let (mut subscriber, consumer) = restart_subscriber(SinkSession::new(Default::default())); + async fn an_unnamed_publisher_is_stamped_per_connection() { + let (mut first, consumer) = restart_subscriber(SinkSession::new(Default::default())); + let (second, _) = restart_subscriber(SinkSession::new(Default::default())); + assert_ne!(first.stamp, crate::Hop::UNKNOWN); + assert_ne!(first.stamp, second.stamp, "each connection stamps its own id"); let mut announced = Announced::default(); - subscriber + first .start_announce( Path::new("room/host").to_owned(), crate::Hops::new(), crate::origin::Cost::UNKNOWN, 0, - None, + Some(crate::Hop::UNKNOWN), &mut announced, ) .unwrap(); @@ -2581,7 +2843,22 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN]); + assert_eq!(hops, vec![first.stamp, crate::Hop::UNKNOWN]); + + // A reprice from the same unnamed publisher keeps the stamp, so it stays in place. + first + .restart_announce( + Path::new("room/host").to_owned(), + crate::Hops::new(), + crate::origin::Cost::UNKNOWN, + 4, + Some(crate::Hop::UNKNOWN), + &mut announced, + ) + .unwrap(); + let route = cursor.assert_next_active("room/host"); + let hops: Vec<_> = route.hops.iter().copied().collect(); + assert_eq!(hops, vec![first.stamp, crate::Hop::UNKNOWN]); } fn restart_subscriber(session: SinkSession) -> (Subscriber, crate::origin::Consumer) { @@ -2819,11 +3096,18 @@ impl SubStream { /// The groups the publisher still owes once it has ended the subscription. /// /// `None` when nothing says which: drafts before SUBSCRIBE_END only have the FIN. - /// Without a SUBSCRIBE_START the publisher served no group at all. + /// Without a SUBSCRIBE_START the publisher served no group at all. Otherwise they start + /// at the floor the demand last asked for, which an update can move either way, or + /// where SUBSCRIBE_START resolved a live-edge one. The groups the SUBSCRIBE asked for + /// below its SUBSCRIBE_START are accounted for as unavailable when it arrives. fn owed(&self, requested_end: Option) -> Option> { let end = self.end.as_ref()?.group; let end = requested_end.map_or(end, |requested| requested.min(end)); - Some(self.served.unwrap_or(end)..end) + let start = match self.served { + Some(served) => self.start.map_or(served, |start| start.group), + None => end, + }; + Some(start..end) } } @@ -3096,6 +3380,14 @@ impl TrackServe { let start_moved = active.start != subscription.start; active.priority = subscription.priority; active.max_age = subscription.max_age; + if let Ok(mut tail) = active.tail.write() { + tail.set_grace(tail::grace(subscription.max_age)); + // A lowered floor owes groups nobody asked for until now. + if let Some(start) = subscription.start { + let floor = active.start.map(|start| start.group).or(active.served); + tail.demand(start.group..floor.unwrap_or(u64::MAX), self.subscriber.runtime.now()); + } + } active.start = subscription.start; if supports_update { // The floor follows the requested start, in both directions: @@ -3168,7 +3460,7 @@ impl TrackServe { tracing::info!(id, broadcast = %self.subscriber.log_path(&self.path), track = %self.name, "subscribe started"); - let tail = kio::Producer::new(Tail::default()); + let tail = kio::Producer::new(Tail::new(tail::grace(subscription.max_age))); self.subscriber.subscribes.lock().insert( id, TrackEntry { @@ -3422,6 +3714,20 @@ impl kio::Task for TrackServeRun { loop { match &mut self.state { TrackRunState::Info { request, info } => { + // Nobody wants the track anymore (the origin failed over, the reader + // left): stop waiting on a peer that may never answer, which would + // otherwise hold this task, its TRACK stream, and the track for good. + // Dropping the fetch resets the stream. + let pending = request.as_ref().expect("request pending"); + if pending.poll_unused(waiter).is_ready() { + if pending.reject_unused(Error::Cancel) { + self.state = TrackRunState::Done; + return Poll::Ready(()); + } + // Demand returned in the gap and won inside `reject_unused`: poll + // again so the unused wait is armed for when it leaves. + continue; + } let res = ready!(info.poll_fetch(&self.serve, waiter)); let request = request.take().expect("request pending"); match res { @@ -3766,15 +4072,22 @@ impl ServeLoop { // consumers learn the boundary early; the later stream FIN // then finds the track already finished. lite::SubscribeResponse::End(end) => { - // finish_at rejects a boundary at or below the live - // edge, which is what a peer sending an inclusive bound - // looks like once the final group has already arrived. - // Don't abort: the stream FIN still finishes the track, - // so this only costs the early boundary. Warn anyway, - // since it's our only signal that a peer disagrees - // about the encoding. + // finish_at rejects a boundary at or below a group + // already received. lite-05 specified an inclusive end, + // and `@moq/net` 0.1.3 to 0.1.9 sent one, so there it + // only costs the early boundary: warn, and let the FIN + // finish the track. Later drafts made it exclusive, so + // the publisher contradicted its own end. if let Err(err) = self.serving.finish_at(end.group) { - tracing::warn!(track = %serve.name, group = end.group, %err, "invalid subscribe end"); + match serve.subscriber.version { + Version::Lite05 => { + tracing::warn!(track = %serve.name, group = end.group, %err, "invalid subscribe end") + } + _ => { + tracing::warn!(track = %serve.name, group = end.group, %err, "subscribe end below a received group"); + return Poll::Ready(ServeEnd::GiveBack(Error::ProtocolViolation)); + } + } } active.end = Some(end.clone()); } @@ -3794,12 +4107,22 @@ impl ServeLoop { let _ = self.serving.start_at(start.group); } active.served = Some(start.group); + // The groups the SUBSCRIBE asked for below it are + // unavailable, whatever the demand asks later. + if let Some(requested) = active.requested + && let Ok(mut tail) = active.tail.write() + { + tail.account(requested.group..start.group, serve.subscriber.runtime.now()); + } } // The publisher will never send these groups, so they // are accounted for without a stream. lite::SubscribeResponse::Drop(dropped) => { if let Ok(mut tail) = active.tail.write() { - tail.account(dropped.start..dropped.end.saturating_add(1)); + tail.account( + dropped.start..dropped.end.saturating_add(1), + serve.subscriber.runtime.now(), + ); } } // OK just resolves the range (the producer already orders @@ -3831,12 +4154,14 @@ impl ServeLoop { // The effective max age is the stopgap grace: the wrong clock // (it bounds presentation-time drift), but it is how long the // subscriber was willing to wait for a late group anyway. - let grace = subscription - .map(|sub| sub.max_age) - .filter(|max_age| !max_age.is_zero()) - .unwrap_or(tail::GRACE); + if let Ok(mut tail) = active.tail.write() { + tail.set_grace(tail::grace( + subscription.map(|sub| sub.max_age).unwrap_or_default(), + )); + tail.expire(serve.subscriber.runtime.now()); + } self.mode = ServeMode::Tail { - settle: Settle::new(&serve.subscriber.runtime, active.tail.consume(), grace), + settle: Settle::new(&serve.subscriber.runtime, active.tail.consume()), owed: active.owed(requested_end), streams: active .end diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index ca4c56735b6..fe9e1170de3 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -93,6 +93,8 @@ pub struct SinkSend { /// [`poll_closed`](poll::SendStream::poll_closed) waits on, mirroring a peer that /// acknowledges the FIN; an unfinished one parks like a peer that never answers. finished: bool, + /// A finished stream still parks, like a peer that has not acknowledged the FIN. + unacked_fin: bool, } impl SinkSend { @@ -102,6 +104,7 @@ impl SinkSend { gate: None, park: kio::Park::default(), finished: false, + unacked_fin: false, } } @@ -112,6 +115,7 @@ impl SinkSend { gate: Some(gate), park: kio::Park::default(), finished: false, + unacked_fin: false, } } } @@ -150,7 +154,7 @@ impl poll::SendStream for SinkSend { } fn poll_closed(&mut self, _cx: &mut Context<'_>) -> Poll> { - match self.finished { + match self.finished && !self.unacked_fin { true => Poll::Ready(Ok(())), // Nothing to acknowledge yet, so park like a peer that never answers. false => Poll::Pending, @@ -176,13 +180,18 @@ impl poll::RecvStream for PendingRecv { } } -/// A reset with stream code 0, decoded as `Error::Stream(StreamError::Internal)`. -#[derive(Debug, Clone, Default)] -pub struct ResetError; +/// A RESET_STREAM as the transport reports it. `Some(code)` decodes as +/// `Error::Stream`; `None` is a code the transport could not place in the stream +/// registry, which decodes as `Error::Transport`. +#[derive(Debug, Clone, Copy)] +pub struct ResetError(pub Option); impl std::fmt::Display for ResetError { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - write!(f, "stream reset by peer (code 0)") + match self.0 { + Some(code) => write!(f, "stream reset by peer (code {code})"), + None => write!(f, "stream reset by peer (unmapped code)"), + } } } @@ -194,27 +203,27 @@ impl web_transport_trait::Error for ResetError { } fn stream_error(&self) -> Option { - Some(0) + self.0 } } /// A stream that died before delivering a single byte: every read reports a -/// code-0 RESET_STREAM ([`ResetError`]), the wire shape of a reset arriving -/// ahead of any payload. QUIC does not order a reset behind the data, so this -/// reaches an accept loop in normal operation, not just from a misbehaving peer. -pub struct DeadRecv; +/// RESET_STREAM ([`ResetError`]), the wire shape of a reset arriving ahead of any +/// payload. QUIC does not order a reset behind the data, so this reaches an accept +/// loop in normal operation, not just from a misbehaving peer. +pub struct DeadRecv(ResetError); impl poll::RecvStream for DeadRecv { type Error = ResetError; fn poll_read(&mut self, _cx: &mut Context<'_>, _dst: &mut [u8]) -> Poll, Self::Error>> { - Poll::Ready(Err(ResetError)) + Poll::Ready(Err(self.0)) } fn stop(&mut self, _code: u32) {} fn poll_closed(&mut self, _cx: &mut Context<'_>) -> Poll> { - Poll::Ready(Err(ResetError)) + Poll::Ready(Err(self.0)) } } @@ -227,6 +236,7 @@ pub struct DeadStreamSession { pub log: Log, unis: Arc>, bis: Arc>, + reset: ResetError, } impl DeadStreamSession { @@ -236,6 +246,7 @@ impl DeadStreamSession { log: Log::default(), unis: Arc::new(Mutex::new(count)), bis: Arc::new(Mutex::new(0)), + reset: ResetError(Some(0)), } } @@ -245,9 +256,17 @@ impl DeadStreamSession { log: Log::default(), unis: Arc::new(Mutex::new(0)), bis: Arc::new(Mutex::new(count)), + reset: ResetError(Some(0)), } } + /// Reset with a code the transport cannot map, the way a raw QUIC moq-transport + /// peer's CANCELLED reads through the WebTransport code space. + pub fn unmapped(mut self) -> Self { + self.reset = ResetError(None); + self + } + fn take(counter: &Mutex) -> bool { let mut remaining = counter.lock().unwrap(); match *remaining { @@ -267,21 +286,21 @@ impl poll::Session for DeadStreamSession { fn poll_accept_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { match Self::take(&self.unis) { - true => Poll::Ready(Ok(DeadRecv)), + true => Poll::Ready(Ok(DeadRecv(self.reset))), false => Poll::Pending, } } fn poll_accept_bi(&mut self, _cx: &mut Context<'_>) -> Poll, Self::Error>> { match Self::take(&self.bis) { - true => Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv))), + true => Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv(self.reset)))), false => Poll::Pending, } } fn poll_open_bi(&mut self, _cx: &mut Context<'_>) -> Poll, Self::Error>> { self.log.bi_opens.fetch_add(1, Ordering::Relaxed); - Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv))) + Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv(self.reset)))) } fn poll_open_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { @@ -332,6 +351,8 @@ pub struct SinkSession { /// Set by [`Self::gated_open_uni`] to withhold unidirectional stream credit. uni_open_gate: Option>, uni_open_park: kio::Park, + /// Set by [`Self::with_unacked_fin`]. + unacked_fin: bool, /// The ALPN to report, for a test that needs a specific negotiated version rather /// than the SETUP-negotiated fallback an absent one selects. protocol: Option<&'static str>, @@ -345,16 +366,17 @@ impl SinkSession { pub fn new(log: Log) -> Self { Self { log, - bi_gate: None, - accept_gate: None, - uni_gate: None, - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } + /// Never acknowledge a unidirectional stream's FIN, like a congested peer, so a + /// finished group stays waiting on it. + pub fn with_unacked_fin(mut self) -> Self { + self.unacked_fin = true; + self + } + /// Report these connection statistics, as a real transport would. pub fn with_stats(self, stats: SinkStats) -> Self { self.set_stats(stats); @@ -379,14 +401,8 @@ impl SinkSession { /// into the test. pub fn gated_bi(gate: kio::Consumer) -> Self { Self { - log: Log::default(), bi_gate: Some(gate), - accept_gate: None, - uni_gate: None, - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } @@ -397,42 +413,24 @@ impl SinkSession { /// a reply reaches the wire needs a session that hands out accepted streams. pub fn accepted_bi(gate: kio::Consumer) -> Self { Self { - log: Log::default(), - bi_gate: None, accept_gate: Some(gate), - uni_gate: None, - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } /// Open unidirectional streams immediately, holding their writes until `gate` opens. pub fn gated_uni(gate: kio::Consumer) -> Self { Self { - log: Log::default(), - bi_gate: None, - accept_gate: None, uni_gate: Some(gate), - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } /// Hold unidirectional stream opens until `gate` grants stream credit. pub fn gated_open_uni(gate: kio::Consumer) -> Self { Self { - log: Log::default(), - bi_gate: None, - accept_gate: None, - uni_gate: None, uni_open_gate: Some(gate), - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } } @@ -456,6 +454,7 @@ impl poll::Session for SinkSession { gate: Some(gate), park: kio::Park::default(), finished: false, + unacked_fin: false, }; Poll::Ready(Ok((send, PendingRecv))) } @@ -471,6 +470,7 @@ impl poll::Session for SinkSession { gate: Some(gate), park: kio::Park::default(), finished: false, + unacked_fin: false, }; Poll::Ready(Ok((send, PendingRecv))) } @@ -483,10 +483,12 @@ impl poll::Session for SinkSession { Poll::Ready(Err(_)) | Poll::Pending => return Poll::Pending, } } - Poll::Ready(Ok(match &self.uni_gate { + let mut send = match &self.uni_gate { Some(gate) => SinkSend::gated(self.log.clone(), gate.clone()), None => SinkSend::new(self.log.clone()), - })) + }; + send.unacked_fin = self.unacked_fin; + Poll::Ready(Ok(send)) } fn poll_send_datagram(&mut self, _cx: &mut Context<'_>, _payload: &[u8]) -> Poll> { @@ -560,6 +562,8 @@ pub struct ScriptedRecv { /// Report EOF once the script is exhausted rather than parking, so a test can drive /// a read loop all the way through its exit path. See [`ScriptedSession::eof`]. eof: bool, + /// Report a reset once the script is exhausted. See [`ScriptedSession::per_stream_reset`]. + reset: bool, log: Log, } @@ -580,6 +584,7 @@ impl poll::RecvStream for ScriptedRecv { }; match take { + 0 if self.reset => Poll::Ready(Err(SinkError)), 0 if self.eof => Poll::Ready(Ok(None)), 0 => Poll::Pending, take => Poll::Ready(Ok(Some(take))), @@ -606,6 +611,8 @@ pub struct ScriptedSession { pub log: Log, /// Whether an exhausted script reports EOF instead of parking. eof: bool, + /// Whether an exhausted script reports a reset instead of parking. + reset: bool, script: Arc>>, /// Per-stream scripts popped by `open_bi` in order; `None` shares `script` /// across every stream. @@ -625,6 +632,7 @@ impl ScriptedSession { Self { log: Log::default(), eof: false, + reset: false, script: Arc::new(Mutex::new(script)), queue: None, open_gate: None, @@ -675,6 +683,15 @@ impl ScriptedSession { } } + /// Like [`Self::per_stream`], but an exhausted script resets the stream, as a peer + /// that fails after replying would. + pub fn per_stream_reset(scripts: Vec>) -> Self { + Self { + reset: true, + ..Self::per_stream(scripts) + } + } + /// Append to the shared script: the peer sending more on a stream it already opened. /// Nothing is woken, so the test re-polls the reader itself. pub fn push(&self, bytes: &[u8]) { @@ -703,6 +720,7 @@ impl poll::Session for ScriptedSession { Poll::Ready(Ok(ScriptedRecv { script: Arc::new(Mutex::new(script)), eof: self.eof, + reset: self.reset, log: self.log.clone(), })) } @@ -734,6 +752,7 @@ impl poll::Session for ScriptedSession { ScriptedRecv { script, eof: self.eof, + reset: self.reset, log: self.log.clone(), }, ))) diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 3e4fca45caa..a49e6d1dcec 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -211,7 +211,7 @@ mod test { assert_eq!( buf, [ - 0x0c, 0x00, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8 + 0x0c, 0x7f, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8 ] ); } diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index 01a93256e3c..eed936c2497 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -226,9 +226,9 @@ impl Allocator { /// decision about what to *produce*, and there is no single subscriber /// priority to read when several are watching one track. /// - /// That last part is what carries the common case, since publishers leave - /// `priority` at its default today: one tier of audio and video still serves - /// audio's small reservation in full before video takes the remainder. + /// That last part carries a publisher that leaves `priority` at its default: + /// one tier of audio and video still serves audio's small reservation in full + /// before video takes the remainder. /// /// The reservation lasts as long as the returned [`Reservation`]: hold it for as /// long as the sender is publishing, change the ceiling with @@ -657,9 +657,8 @@ mod tests { assert_eq!(allocate(bps(1_000_000), &wants, 1), Some(bps(0))); } - /// Publishers don't set [`track::Info::priority`] today (it defaults to 0 and - /// `hang::container::track_info` leaves it there), so audio and video land in - /// one tier. That has to come out right anyway, and it does: max-min fair + /// A publisher that doesn't set [`track::Info::priority`] puts audio and video + /// in one tier. That has to come out right anyway, and it does: max-min fair /// satisfies the small claim first, so audio still gets its full reservation /// and video takes the rest. Priority only changes the answer once a tier's /// smaller claims outgrow an even split. diff --git a/rs/moq-net/src/model/datagram.rs b/rs/moq-net/src/model/datagram.rs index f3055072079..a8c20b09796 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -8,10 +8,10 @@ //! //! Delivery is best-effort per hop: a session drops (with a debug log) any datagram whose encoded //! body exceeds the transport's datagram size, and sessions that can't carry datagrams at all -//! (IETF moq-transport, moq-lite before 05, or stream-only transports like WebSocket) never -//! deliver them. +//! (moq-lite before 05, or stream-only transports like WebSocket) never deliver them. //! -//! Wire counterpart: [`crate::lite::Datagram`]. +//! Wire counterparts: [`crate::lite::Datagram`], and on moq-transport an OBJECT_DATAGRAM at +//! object 0 whose Group ID is the sequence ([`crate::ietf::ObjectDatagram`]). use bytes::Bytes; diff --git a/rs/moq-net/src/model/front.rs b/rs/moq-net/src/model/front.rs index eba8ca277e7..dce21083f66 100644 --- a/rs/moq-net/src/model/front.rs +++ b/rs/moq-net/src/model/front.rs @@ -138,7 +138,8 @@ pub(super) enum Identity { Local, /// The serving route's first hop was absent or [`Hop::UNKNOWN`], which /// identifies nobody: the front cannot resume through any other route, so - /// its source ending, or `route` leaving the table, ends it. + /// its source ending, `route` leaving the table, or `route` gaining a first + /// hop ends it. Anonymous { route: u64 }, /// The first hop of the serving route. Routes sharing it are the same /// origin reached another way and safe to resume through. @@ -154,7 +155,8 @@ pub(super) enum Pin { Local, /// Only routes originated by this first hop. Publisher(Hop), - /// Only this route: the front never fails over. + /// Only this route, while its publisher stays unknown: the front never fails + /// over, and an update naming a publisher ends it. Route(u64), } diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index f458d076da4..870cd97b4ef 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -41,7 +41,7 @@ pub use timed::Timed; /// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { pub use super::origin_impl::{ - Config, Consumer, Cost, Driver, Dynamic, Producer, Request, Requesting, Route, Source, + Config, Consumer, Cost, DEFAULT_UPDATE_HOLD, Driver, Dynamic, Producer, Request, Requesting, Route, Source, }; } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 8e8833d9ac6..12a9c1459af 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -36,7 +36,7 @@ use crate::{ /// on the wire, names nobody, and marks the chain anonymous for route selection. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Hop { - /// 62-bit identifier. Encoded as a QUIC varint on the wire. + /// 62-bit identifier, so it fits a varint on every wire version. id: u64, } @@ -114,8 +114,24 @@ pub struct Config { /// [`expiry`](cache::Pool::expiry) window. [`Duration::MAX`] (the default) /// imposes no ceiling, leaving each track's own window in force. pub cache_duration: Duration, + + /// How long an announce cursor holds a changed route before delivering it. + /// + /// A new route and a removed one are delivered at once; only an update (a + /// prefix whose best route changes while it stays reachable) waits, and a + /// newer change during the wait replaces it. When a publisher withdraws, a + /// relay that loses its best route but still holds routes derived from the + /// withdrawn one sends nothing while the withdrawal wave removes them, then one + /// retraction, instead of advertising each stale path in turn. It must outlast + /// the wave's spread across the mesh. Defaults to [`DEFAULT_UPDATE_HOLD`]; + /// zero delivers updates at once. + pub update_hold: Duration, } +/// The default [`Config::update_hold`]: longer than a withdrawal takes to cross a +/// global mesh, with margin. +pub const DEFAULT_UPDATE_HOLD: Duration = Duration::from_millis(300); + impl Default for Config { /// A fresh random hop with no byte target and the default idle expiry. fn default() -> Self { @@ -124,6 +140,7 @@ impl Default for Config { hop: Hop::random(), pool, cache_duration: Duration::MAX, + update_hold: DEFAULT_UPDATE_HOLD, } } } @@ -252,6 +269,34 @@ impl Hops { Ok(()) } + /// Name an unknown original publisher: prefix `stamp`, the receiving session's own + /// per-connection id, to a chain that starts with 0, and turn an empty chain into + /// `[stamp, 0]`. + /// + /// A publisher that reconnects then reads downstream as a new first hop, which is + /// all anyone can say about it, while the 0 after the stamp keeps the route ranked + /// as anonymous. Fails with [`InvalidHop::TooMany`] if the chain is full, and with + /// [`InvalidHop::Duplicate`] if `stamp` already appears in it. + pub(crate) fn stamp(&mut self, stamp: Hop) -> Result<(), InvalidHop> { + match self.0.first() { + None => { + self.push(stamp)?; + self.push(Hop::UNKNOWN) + } + Some(first) if *first == Hop::UNKNOWN => { + if self.0.len() >= MAX_HOPS { + return Err(InvalidHop::TooMany); + } + if self.0.contains(&stamp) { + return Err(InvalidHop::Duplicate); + } + self.0.insert(0, stamp); + Ok(()) + } + Some(_) => Ok(()), + } + } + /// Returns true if any entry matches `hop`. pub fn contains(&self, hop: &Hop) -> bool { self.0.contains(hop) @@ -343,7 +388,8 @@ where /// /// The ceiling is the wire's, not the model's: lite-06 carries each cost as a QUIC /// varint, which tops out at 2^62-1, so a larger value could be selected on but -/// never forwarded. +/// never forwarded. It applies on every version, lite-07's 64-bit varints included, +/// so a cost stays forwardable to a QUIC-varint version. const MAX_COST: u64 = (1 << 62) - 1; /// What pulling content via a route costs, in two magnitudes that accumulate @@ -443,7 +489,8 @@ pub struct Route { /// The chain of origins the route has traversed, oldest first. Each relay /// appends its own [`crate::Hop`] when forwarding; used for loop detection /// and as the selection tie-break. A 0 entry is the anonymous mark and - /// travels unchanged; see [`Self::is_anonymous`]. + /// travels unchanged; a session receiving one as the first entry puts its own + /// per-connection stamp in front of it; see [`Self::is_anonymous`]. pub hops: Hops, /// What pulling content via this route costs, accumulated per link: lower wins @@ -591,6 +638,18 @@ fn route_order(prefix: &Path, entry: &RouteEntry) -> (bool, Cost, bool, usize, u /// The `(hops, cost, source)` metadata an announce cursor delivers alongside a prefix. type RouteMeta = (Hops, Cost, Source); +/// A pending update's hold, keyed by prefix in its [`AnnounceConsumer`]. +/// +/// A consumer reads the origin's clock outside the driver, where it holds the +/// driver's last reading, not the time the update arrived. So a hold first waits +/// for the driver's next reading (armed a nanosecond past the stale one, which +/// wakes the driver at once), and counts from there. +#[derive(Clone, Copy)] +enum Held { + Anchoring(Instant), + Until(Instant), +} + /// One coalesced update queued for an `AnnounceConsumer`. /// /// At most one entry exists per prefix, so a slow consumer's pending set is @@ -668,11 +727,6 @@ impl OriginConsumerState { matches!(&self.live, LiveState::Owed(owed) if owed.is_empty()) } - /// Whether [`Self::take`] has something to hand out, or the cursor ended. - fn ready(&self) -> bool { - !self.pending.is_empty() || self.ended || self.live_due() - } - fn apply_announce(&mut self, prefix: PathOwned, meta: RouteMeta, captures: Option>) { let meta = (meta, captures); let new = match self.pending.remove(&prefix) { @@ -705,14 +759,54 @@ impl OriginConsumerState { } } - /// Take one event to deliver to the consumer, if any: the marker as soon as - /// it is due, otherwise the next update. - fn take(&mut self) -> Option { - if self.live_due() { - self.live = LiveState::Done; - return Some(AnnounceEvent::Live); + /// Whether the pending entry at `prefix` changes a route the consumer holds + /// to another route, rather than adding or removing one. + fn is_update(&self, prefix: &PathOwned, update: &PendingUpdate) -> bool { + matches!(update, PendingUpdate::Announce(_)) && self.delivered.contains(prefix) + } + + /// The first pending prefix ready to deliver, or when the next held one is. + /// See [`Config::update_hold`]; a hold starts the first time a scan sees it. + fn scan( + &self, + held: &mut HashMap, + now: Option, + hold: Duration, + ) -> Result> { + let mut wake = None; + for (prefix, update) in &self.pending { + let holds = !hold.is_zero() && !self.ended && self.is_update(prefix, update); + let Some(now) = now.filter(|_| holds) else { + return Ok(prefix.clone()); + }; + // The clock reads the driver's last advance, which may be stale: anchor the + // hold on the first advance after the update arrived, by waking the driver. + let until = match held.get(prefix).copied() { + None => { + held.insert(prefix.clone(), Held::Anchoring(now)); + now + Duration::from_nanos(1) + } + Some(Held::Anchoring(seen)) if now <= seen => seen + Duration::from_nanos(1), + Some(Held::Anchoring(_)) => { + held.insert(prefix.clone(), Held::Until(now + hold)); + now + hold + } + Some(Held::Until(until)) if until <= now => return Ok(prefix.clone()), + Some(Held::Until(until)) => until, + }; + wake = Some(wake.map_or(until, |w: Instant| w.min(until))); } - let prefix = self.pending.keys().next()?.clone(); + Err(wake) + } + + /// Deliver the [`AnnounceEvent::Live`] marker, once it is due. + fn take_live(&mut self) -> AnnounceEvent { + self.live = LiveState::Done; + AnnounceEvent::Live + } + + /// Take the pending update at `prefix` for delivery. + fn take_prefix(&mut self, prefix: PathOwned) -> Option { let ((meta, captures), kind): (_, fn(Announce) -> AnnounceEvent) = match self.pending.remove(&prefix).unwrap() { PendingUpdate::Announce(meta) => { // The consumer has seen this prefix before, so it is a metadata update. @@ -822,7 +916,8 @@ impl RouteEntry { Pin::Any => true, Pin::Local => self.local, Pin::Publisher(first) => self.hops.iter().next() == Some(&first), - Pin::Route(id) => self.id == id, + // An update that names a publisher is a different one, even in place. + Pin::Route(id) => self.id == id && self.hops.iter().next().is_none_or(|first| *first == Hop::UNKNOWN), } } @@ -1012,6 +1107,50 @@ impl TableCursor { && self.named.as_ref().is_none_or(|(mount, _)| mount.names(&entry.prefix)) } + /// Deliver a changed winner at this presented prefix. + fn update(&mut self, presented: &PathOwned, best: Option<&RouteEntry>) { + match best { + Some(entry) => { + let meta = (entry.hops.clone(), entry.cost, entry.entered()); + let served = entry.server.is_some(); + let captures = self.captures(&entry.prefix); + let previous = self + .current + .insert(presented.clone(), (entry.id, meta.clone(), served, captures.clone())); + match previous { + // Unchanged metadata and servability: nothing the consumer could + // act on, even if the winning entry itself changed (a reconnect + // under an identical route is invisible, which is the point). A + // servability flip is delivered: a request that failed Unroutable + // under an advertise-only route retries on the update, and hiding + // it would park that waiter forever. + Some((_, prev, prev_served, prev_captures)) + if prev == meta && prev_served == served && prev_captures == captures => {} + // Captures are consumer identity, not route metadata. Replace the + // old identity explicitly so capture-keyed consumers can remove it. + Some((_, prev, _, prev_captures)) if prev_captures != captures => { + if let Ok(mut state) = self.state.write() { + state.apply_unannounce(self.under.join(presented), prev, prev_captures); + state.apply_announce(self.under.join(presented), meta, captures); + } + } + _ => { + if let Ok(mut state) = self.state.write() { + state.apply_announce(self.under.join(presented), meta, captures); + } + } + } + } + None => { + if let Some((_, last, _, captures)) = self.current.remove(presented) + && let Ok(mut state) = self.state.write() + { + state.apply_unannounce(self.under.join(presented), last, captures); + } + } + } + } + /// Whether the hidden rule lets this cursor discover a route at `prefix`. fn discovers(&self, prefix: &Path) -> bool { self.hidden.discovers(&self.heads, prefix) @@ -1181,6 +1320,8 @@ pub(crate) fn interest_prefixes(allowed: &Patterns) -> Vec { pub(crate) struct Hidden { /// Report hidden routes too. include: bool, + /// Measure visibility from the request prefix instead of authorization heads. + from: Option, /// Report only what a feed scoped to these heads hides, for a stream that tops /// up a feed already carrying everything visible from them. beyond: Option>, @@ -1189,7 +1330,8 @@ pub(crate) struct Hidden { impl Hidden { /// Whether a cursor hanging at `heads` reports a route at `prefix`. fn discovers(&self, heads: &[PathOwned], prefix: &Path) -> bool { - (self.include || !hides(heads, prefix)) && self.beyond.as_ref().is_none_or(|outer| hides(outer, prefix)) + (self.include || !hides(self.from.as_ref().map(std::slice::from_ref).unwrap_or(heads), prefix)) + && self.beyond.as_ref().is_none_or(|outer| hides(outer, prefix)) } /// This rule for a cursor reading through `mount`, whose heads sit on the @@ -1201,6 +1343,7 @@ impl Hidden { }); Self { include: self.include, + from: self.from.as_ref().and_then(|head| mount.translate_head(head)), beyond, } } @@ -1301,7 +1444,7 @@ impl Producer { pub fn new(config: Config) -> (Self, Driver) { let (tasks, set) = TaskSet::new(); let scope = OriginScope::default(); - let shared = kio::Shared::::default(); + let shared = kio::Shared::new(OriginState::new(config.update_hold)); let timers = Clock::default(); let pool = config.pool.clone(); let producer = Self { @@ -1354,6 +1497,7 @@ impl Producer { hop: self.hop, pool: self.pool.clone(), cache_duration: self.cache_duration, + update_hold: self.shared.lock().update_hold, } } @@ -1374,7 +1518,7 @@ impl Producer { hop, scope: OriginScope::empty(), root: PathOwned::default(), - shared: kio::Shared::default(), + shared: kio::Shared::new(OriginState::new(DEFAULT_UPDATE_HOLD)), pool: cache::Pool::default(), cache_duration: Duration::MAX, stats: stats::Session::default(), @@ -1869,6 +2013,13 @@ impl AnnounceProducer { let Some(entry) = shared.routes.entry_mut(prefix, *id) else { return Err(Error::Closed); }; + // A new first hop is a new publisher: a later request goes back to the + // handler rather than joining what the old one served. + if entry.hops.iter().next() != route.hops.iter().next() + && let Some(server) = &entry.server + { + drop(std::mem::take(&mut server.lock().served)); + } entry.hops = route.hops.clone(); entry.stale = stale; entry.cost = route.cost; @@ -1990,6 +2141,7 @@ impl Driver { /// has drained. pub fn poll(&mut self, now: Instant, waiter: &kio::Waiter) -> Result, Error> { self.timers.advance(now); + self.timers.register_driver(waiter); let result = self.state.poll(waiter); let gc = self.pool.gc(now); if result.is_ready() { @@ -2147,6 +2299,7 @@ fn warm_copy(source: &track::Consumer, head: Option<&WarmGroup>) -> Option) -> Option= latest); if head.is_finished() { let _ = track.adopt_group(head.clone(), true); + first = Some(head.sequence); if is_latest { edge = Some(WarmGroup(head.clone())); } } else if is_latest { edge = warm_rebuild(&track, head, None); + first = edge.as_ref().map(|_| head.sequence); } } @@ -2183,10 +2338,17 @@ fn warm_copy(source: &track::Consumer, head: Option<&WarmGroup>) -> Option Self { + Self { + update_hold, + routes: RouteTable::default(), + next_route: 0, + next_watch: 0, + cursors: HashMap::new(), + fronts: WeakCache::default(), + withdrawn: HashMap::new(), + replaying: HashMap::new(), + next_replaying: 0, + closed: false, + } + } + /// Whether a peer in `hops` withdrew `prefix`. fn withdrawn_through(&self, prefix: &Path, hops: &Hops) -> bool { if self.withdrawn.is_empty() { @@ -3217,12 +3399,32 @@ impl OriginState { fn sync_route(&mut self, prefix: &Path, claim: &Pattern) { // Split borrows: the recompute reads `routes` while mutating a cursor. let routes = &self.routes; + let mut candidates = None; for id in routes.cursors_touching(prefix) { let Some(cursor) = self.cursors.get_mut(&id) else { continue; }; if let Some(presented) = cursor.presented(prefix, claim) { - Self::sync_cursor(routes, cursor, &presented); + if presented.is_empty() { + // A cursor root can collapse several covering prefixes into one. + Self::sync_cursor(routes, cursor, &presented); + } else { + // Every non-root presentation refers to this exact prefix. Rank + // its routes once, then take each cursor's first visible entry. + let candidates = candidates.get_or_insert_with(|| { + let mut entries: Vec<_> = routes + .at(prefix) + .map(|entry| (route_order(prefix, entry), entry)) + .collect(); + entries.sort_unstable_by_key(|(order, _)| *order); + entries + }); + let best = candidates + .iter() + .map(|(_, entry)| *entry) + .find(|entry| cursor.visible(entry)); + cursor.update(&presented, best); + } } } // The fronts and requesters under the prefix re-select from the table. @@ -3268,46 +3470,7 @@ impl OriginState { .min_by_key(|entry| route_order(&entry.prefix, entry)) }); - match best { - Some(entry) => { - let meta = (entry.hops.clone(), entry.cost, entry.entered()); - let served = entry.server.is_some(); - let captures = cursor.captures(&entry.prefix); - let previous = cursor - .current - .insert(presented.clone(), (entry.id, meta.clone(), served, captures.clone())); - match previous { - // Unchanged metadata and servability: nothing the consumer could - // act on, even if the winning entry itself changed (a reconnect - // under an identical route is invisible, which is the point). A - // servability flip is delivered: a request that failed Unroutable - // under an advertise-only route retries on the update, and hiding - // it would park that waiter forever. - Some((_, prev, prev_served, prev_captures)) - if prev == meta && prev_served == served && prev_captures == captures => {} - // Captures are consumer identity, not route metadata. Replace the - // old identity explicitly so capture-keyed consumers can remove it. - Some((_, prev, _, prev_captures)) if prev_captures != captures => { - if let Ok(mut state) = cursor.state.write() { - state.apply_unannounce(cursor.under.join(presented), prev, prev_captures); - state.apply_announce(cursor.under.join(presented), meta, captures); - } - } - _ => { - if let Ok(mut state) = cursor.state.write() { - state.apply_announce(cursor.under.join(presented), meta, captures); - } - } - } - } - None => { - if let Some((_, last, _, captures)) = cursor.current.remove(presented) - && let Ok(mut state) = cursor.state.write() - { - state.apply_unannounce(cursor.under.join(presented), last, captures); - } - } - } + cursor.update(presented, best); } /// Register a cursor and replay the current best route per presented prefix. @@ -3496,8 +3659,10 @@ impl Dynamic { /// Re-price the route in place: replace its hops and cost. /// /// Consumers observe another active update for the same prefix; sessions - /// forward it as a restart, so route churn never looks like new content. The - /// prefix is fixed at announce time: to move a route, drop this and call + /// forward it as a restart, so route churn never looks like new content. A + /// new first hop is a new publisher: broadcasts already served from the old + /// one drain, and later requests reach the handler again. The prefix is fixed + /// at announce time: to move a route, drop this and call /// [`Producer::dynamic`] again. Fails with [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. pub fn update(&self, route: Route) -> Result<(), Error> { @@ -3903,7 +4068,21 @@ impl Consumer { /// A clone whose [`announced`](Self::announced) reports only the routes a feed /// from `outer` hides, for a stream topping up that feed. pub(crate) fn beyond(mut self, outer: &Consumer) -> Self { - self.hidden.beyond = Some(interest_prefixes(&outer.scope.allowed)); + self.hidden.beyond = Some( + outer + .hidden + .from + .clone() + .map(|head| vec![head]) + .unwrap_or_else(|| interest_prefixes(&outer.scope.allowed)), + ); + self + } + + /// Set wire discovery visibility relative to this consumer's requested root. + pub(crate) fn discovery(mut self, hidden: bool) -> Self { + self.hidden.include = hidden; + self.hidden.from = Some(self.root.clone()); self } @@ -3974,7 +4153,14 @@ impl Consumer { if let Some(mount) = self.scope.mount(&self.root) { // A root the mount resolves past the depth limit has nothing to announce. let Some(root) = mount.resolve(&self.root) else { - return AnnounceConsumer::new(self.root.clone(), Vec::new(), state, self.stats.clone(), &self.shared); + return AnnounceConsumer::new( + self.root.clone(), + Vec::new(), + state, + self.stats.clone(), + &self.shared, + self.timers.clone(), + ); }; let cursors = vec![cursor( root, @@ -3984,7 +4170,14 @@ impl Consumer { PathOwned::default(), Vec::new(), )]; - return AnnounceConsumer::new(self.root.clone(), cursors, state, self.stats.clone(), &self.shared); + return AnnounceConsumer::new( + self.root.clone(), + cursors, + state, + self.stats.clone(), + &self.shared, + self.timers.clone(), + ); } // Otherwise the consumer's own cursor, minus the mounted subtrees, plus one @@ -4000,7 +4193,12 @@ impl Consumer { let allowed = mount.translate(&self.scope.allowed); // Hidden at the mount point means hidden throughout: the dot segment is above // everything the mount holds. A top-up feed's rule moves onto the target. - if allowed.is_empty() || !(self.hidden.include || !hides(&heads, &mount.at)) { + if allowed.is_empty() + || !(self.hidden.include + || !hides( + self.hidden.from.as_ref().map(std::slice::from_ref).unwrap_or(&heads), + &mount.at, + )) { continue; } cursors.push(cursor( @@ -4023,7 +4221,14 @@ impl Consumer { holes, ), ); - AnnounceConsumer::new(self.root.clone(), cursors, state, self.stats.clone(), &self.shared) + AnnounceConsumer::new( + self.root.clone(), + cursors, + state, + self.stats.clone(), + &self.shared, + self.timers.clone(), + ) } /// Returns a cheap duplicate of this read handle. @@ -4327,6 +4532,13 @@ pub struct AnnounceConsumer { // Holds the waiter a `Stream` poll registered; disjoint from `state` so the // borrow never collides with the body's. park: kio::Park, + + // Held updates (see [`Config::update_hold`]): their holds by prefix, the + // clock they count on, and the timer that wakes the next. + update_hold: Duration, + held: HashMap, + timers: Clock, + hold: crate::runtime::Deadline, } impl AnnounceConsumer { @@ -4336,10 +4548,13 @@ impl AnnounceConsumer { state: kio::Producer, stats: stats::Session, shared: &kio::Shared, + timers: Clock, ) -> Self { let mut ids = Vec::with_capacity(cursors.len()); + let update_hold; { let mut table = shared.lock(); + update_hold = table.update_hold; if table.closed { // A cursor on a dead origin is born ended. if let Ok(mut state) = state.write() { @@ -4362,6 +4577,10 @@ impl AnnounceConsumer { stats, guards: HashMap::new(), park: kio::Park::default(), + update_hold, + held: HashMap::new(), + hold: crate::runtime::Deadline::new(&timers), + timers, } } @@ -4401,26 +4620,64 @@ impl AnnounceConsumer { /// cursor is closed, or `Poll::Pending` after registering `waiter` to be /// notified when the next event arrives. pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll> { - let event = { - let mut state = match ready!(self.state.poll(waiter, |state| match state.ready() { - true => Poll::Ready(()), - false => Poll::Pending, - })) { - Ok(state) => state, + loop { + let now = self.timers.try_now(); + let hold = self.update_hold; + let held = &mut self.held; + let mut live = false; + let mut ready = None; + let mut wake = None; + let event = match self.state.poll(waiter, |state| { + // The marker goes out as soon as it is due, ahead of any update. + live = state.live_due(); + if live { + return Poll::Ready(()); + } + if state.pending.is_empty() { + return match state.ended { + true => Poll::Ready(()), + false => Poll::Pending, + }; + } + match state.scan(held, now, hold) { + Ok(prefix) => { + ready = Some(prefix); + Poll::Ready(()) + } + Err(at) => { + wake = at; + Poll::Pending + } + } + }) { + Poll::Ready(Ok(mut state)) => match ready { + _ if live => Some(state.take_live()), + Some(prefix) => state.take_prefix(prefix), + None => { + // Ended by the origin's teardown, pending updates already + // drained; close the channel so every closure signal agrees. + state.close(); + None + } + }, // Closed: discard the Ref so its MutexGuard doesn't escape this call. - Err(_) => return Poll::Ready(None), - }; - match state.take() { - Some(event) => event, - None => { - // Ended by the origin's teardown, pending updates already - // drained; close the channel so every closure signal agrees. - state.close(); - return Poll::Ready(None); + Poll::Ready(Err(_)) => None, + Poll::Pending => { + self.hold.set(wake); + ready!(self.hold.poll(waiter)); + continue; } + }; + let Some(event) = event else { + return Poll::Ready(None); + }; + if let AnnounceEvent::Start(announce) | AnnounceEvent::Update(announce) | AnnounceEvent::End(announce) = + &event + { + self.held.remove(&announce.prefix); } - }; - Poll::Ready(Some(self.hand_out(event))) + return Poll::Ready(Some(self.hand_out(event))); + } } /// Returns the next event without blocking. @@ -4428,7 +4685,26 @@ impl AnnounceConsumer { /// Returns None if there is no event available; NOT because the cursor is closed. /// Use [`Self::is_closed`] to check if the cursor is closed. pub fn try_next(&mut self) -> Option { - let event = self.state.write().ok()?.take()?; + let now = self.timers.try_now(); + let mut state = self.state.write().ok()?; + if state.live_due() { + let event = state.take_live(); + drop(state); + return Some(self.hand_out(event)); + } + let prefix = match state.scan(&mut self.held, now, self.update_hold) { + Ok(prefix) => prefix, + Err(wake) => { + // Arm the hold even though nothing polls it: the armed timer wakes the + // driver, so its clock reaches the deadline for a later call to see. + drop(state); + self.hold.set(wake); + return None; + } + }; + self.held.remove(&prefix); + let event = state.take_prefix(prefix)?; + drop(state); Some(self.hand_out(event)) } @@ -5338,6 +5614,46 @@ mod tests { assert_eq!(route.cost, Cost::new(5)); } + /// A stamped route names its session but keeps the 0 behind the stamp, so it still + /// loses to a fully identified route of the same length, however cheap it is. + #[tokio::test] + async fn a_stamped_route_ranks_below_an_identified_one() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + + let mut stamped = Hops::new(); + stamped.stamp(origin(5)).unwrap(); + assert_eq!(stamped.as_slice(), &[origin(5), Hop::UNKNOWN]); + + let _legacy = producer + .announce("room", Route::default().with_hops(stamped).with_cost(0)) + .unwrap(); + let route = announced.assert_next_active("room"); + assert!(route.is_anonymous()); + + let _identified = producer + .announce("room", Route::default().with_hops(hops(&[10, 11])).with_cost(5)) + .unwrap(); + let route = announced.assert_next_active("room"); + assert_eq!(route.hops.as_slice(), hops(&[10, 11]).as_slice()); + } + + #[test] + fn stamping_keeps_the_leading_zero_and_names_nothing_else() { + let mut chain = hops(&[0, 7]); + chain.stamp(origin(5)).unwrap(); + assert_eq!(chain.as_slice(), hops(&[5, 0, 7]).as_slice()); + + // Already named: untouched. + let mut named = hops(&[7, 0]); + named.stamp(origin(5)).unwrap(); + assert_eq!(named.as_slice(), hops(&[7, 0]).as_slice()); + + // A full chain has no room for the stamp. + let mut full = Hops::try_from(vec![Hop::UNKNOWN; MAX_HOPS]).unwrap(); + assert_eq!(full.stamp(origin(5)), Err(InvalidHop::TooMany)); + } + #[tokio::test] async fn anonymous_routes_order_by_cost() { let producer = origin(1).produce(); @@ -5959,6 +6275,91 @@ mod tests { } } + #[tokio::test] + async fn warm_head_survives_another_takeover_before_park() { + tokio::time::pause(); + let producer = origin(1).produce(); + let _server = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(5)) + .unwrap(); + let pending = producer.consume().request_broadcast("room/alice"); + let upstream = broadcast::Info::new().produce(); + let mut dynamic = upstream.dynamic(); + queued(&_server).await.accept(&upstream); + let resolved = pending.await.unwrap(); + + let track = resolved.track("log").unwrap(); + let subscribing = tokio::spawn(async move { track.subscribe(None).await }); + let source = dynamic.requested_track().await.unwrap().accept(None); + let mut group = source.create_group(0u64.into()).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"a".as_ref()).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"b".as_ref()).unwrap(); + let mut subscription = subscribing.await.unwrap().unwrap(); + let mut reading = subscription.recv_group().await.unwrap().unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"a"); + drop(reading); + drop(subscription); + source.demand().unused().await.unwrap(); + drop(group); + drop(source); + + let track = resolved.track("log").unwrap(); + let subscribing = tokio::spawn(async move { track.subscribe(None).await }); + let mut resumed = dynamic.requested_track().await.unwrap().resolving_start().accept(None); + resumed.start_at(0).unwrap(); + let mut subscription = subscribing.await.unwrap().unwrap(); + let mut reading = subscription.recv_group().await.unwrap().unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"a"); + + let replacement_server = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[10]))) + .unwrap(); + let replacement = broadcast::Info::new().produce(); + let mut replacement_dynamic = replacement.dynamic(); + queued(&replacement_server).await.accept(&replacement); + let mut source = replacement_dynamic + .requested_track() + .await + .unwrap() + .resolving_start() + .accept(None); + source.start_at(0).unwrap(); + let mut group = source.create_group(0u64.into()).unwrap(); + group.start_at(2).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"c".as_ref()).unwrap(); + let mut continuation = reading.clone(); + continuation.start_at(2); + let frame = tokio::time::timeout(Duration::from_secs(1), continuation.read_frame()) + .await + .expect("replacement frame") + .unwrap() + .unwrap(); + assert_eq!(&frame.payload[..], b"c"); + drop(continuation); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"b"); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"c"); + drop(reading); + drop(subscription); + source.demand().unused().await.unwrap(); + drop(group); + drop(source); + + let track = resolved.track("log").unwrap(); + let subscribing = tokio::spawn(async move { track.subscribe(None).await }); + let mut next = replacement_dynamic + .requested_track() + .await + .unwrap() + .resolving_start() + .accept(None); + next.start_at(0).unwrap(); + let mut subscription = subscribing.await.unwrap().unwrap(); + let mut reading = subscription.recv_group().await.unwrap().unwrap(); + for expected in [b"a", b"b", b"c"] { + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], expected); + } + } + /// The same holds for a reader returning to a parked track: its warm cache /// does not stand in for the copy it is waiting on. #[tokio::test] @@ -6172,6 +6573,76 @@ mod tests { assert_eq!(video.assert_next_active("").cost, Cost::new(5)); } + #[tokio::test] + async fn route_changes_preserve_each_cursors_visible_winner() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let mut all = consumer.clone().announced(); + let mut excluded = consumer.clone().excluding(origin(7)).announced(); + let mut video = consumer + .clone() + .scope("", &scopes(&["room/live/video"])) + .unwrap() + .announced(); + let mut rooted = consumer + .scope("room/live", &Patterns::from(Pattern::all())) + .unwrap() + .announced(); + + let chat = producer + .scope("", &scopes(&["room/live/chat"])) + .unwrap() + .dynamic("room/live", Route::default().with_hops(hops(&[7])).with_cost(1)) + .unwrap(); + assert_eq!(all.assert_next_active("room/live").cost, Cost::new(1)); + assert_eq!(rooted.assert_next_active("").cost, Cost::new(1)); + excluded.assert_next_wait(); + video.assert_next_wait(); + + let video_route = producer + .scope("", &scopes(&["room/live/video"])) + .unwrap() + .dynamic("room/live", Route::default().with_hops(hops(&[8])).with_cost(5)) + .unwrap(); + all.assert_next_wait(); + rooted.assert_next_wait(); + assert_eq!(excluded.assert_next_active("room/live").cost, Cost::new(5)); + assert_eq!(video.assert_next_active("room/live").cost, Cost::new(5)); + + chat.update(Route::default().with_hops(hops(&[7])).with_cost(9)) + .unwrap(); + assert_eq!(all.assert_next_active("room/live").cost, Cost::new(5)); + assert_eq!(rooted.assert_next_active("").cost, Cost::new(5)); + excluded.assert_next_wait(); + video.assert_next_wait(); + + drop(video_route); + assert_eq!(all.assert_next_active("room/live").cost, Cost::new(9)); + assert_eq!(rooted.assert_next_active("").cost, Cost::new(9)); + excluded.assert_next_ended("room/live"); + video.assert_next_ended("room/live"); + } + + #[tokio::test] + async fn root_cursor_keeps_the_more_specific_covering_route() { + let producer = origin(1).produce(); + let broad = producer.dynamic("room", Route::default().with_cost(1)).unwrap(); + let narrow = producer.dynamic("room/live", Route::default().with_cost(9)).unwrap(); + let mut announced = producer + .consume() + .scope("room/live/video", &Patterns::from(Pattern::all())) + .unwrap() + .announced(); + assert_eq!(announced.assert_next_active("").cost, Cost::new(9)); + + broad.update(Route::default().with_cost(0)).unwrap(); + announced.assert_next_wait(); + narrow.update(Route::default().with_cost(8)).unwrap(); + assert_eq!(announced.assert_next_active("").cost, Cost::new(8)); + drop(narrow); + assert_eq!(announced.assert_next_active("").cost, Cost::new(0)); + } + #[tokio::test] async fn dynamic_accepts_a_max_depth_prefix() { let producer = origin(1).produce(); @@ -6408,6 +6879,78 @@ mod tests { assert_eq!(announced.assert_next_active("room/x").source(), Source::Peer(origin(8))); } + /// A caller that only polls with `try_next` still gets a held update once its + /// hold passes. Nothing else wakes the idle driver, so the hold's own timer + /// must, or the origin's clock never reaches the deadline. + #[tokio::test(start_paused = true)] + async fn try_next_delivers_a_held_update() { + // Let paused time pass and every task woken by it run. + async fn step(by: Duration) { + tokio::time::advance(by).await; + for _ in 0..10 { + tokio::task::yield_now().await; + } + } + + let producer = origin(1).produce(); + let peer = producer.clone().peer(); + let mut announced = producer.consume().announced(); + step(Duration::from_millis(1)).await; + + let route = |chain: &[u64], via| Route::default().with_hops(hops(chain)).with_via(origin(via)); + let near = peer.dynamic("room", route(&[9, 2], 2)).unwrap(); + announced.assert_try_next_active("room"); + + let _far = peer.dynamic("room", route(&[9, 3, 4], 4)).unwrap(); + drop(near); + assert!(announced.try_next_route().is_none(), "the update is held"); + step(Duration::from_millis(1)).await; + assert!(announced.try_next_route().is_none(), "the update is still held"); + step(DEFAULT_UPDATE_HOLD).await; + match announced.try_next_route().expect("the hold passed") { + AnnounceEvent::Update(update) => assert_eq!(update.route.hops, hops(&[9, 3, 4])), + other => panic!("should be an update: got {other:?}"), + } + } + + /// A new route and a removal are delivered at once. A change of the best route + /// waits out the update hold, and a newer change during the wait replaces it. + #[tokio::test(start_paused = true)] + async fn a_changed_route_waits_out_the_hold() { + let producer = origin(1).produce(); + let peer = producer.clone().peer(); + let mut announced = producer.consume().announced(); + // Holds count on the driver's clock, which starts at its first poll. + tokio::time::sleep(Duration::from_millis(1)).await; + + let route = |chain: &[u64], via| Route::default().with_hops(hops(chain)).with_via(origin(via)); + let near = peer.dynamic("room", route(&[9, 2], 2)).unwrap(); + announced.assert_next_active("room"); + + // The best route changes twice; the consumer sees only the last, once. + let far = peer.dynamic("room", route(&[9, 3, 4], 4)).unwrap(); + let farther = peer.dynamic("room", route(&[9, 5, 6, 7], 7)).unwrap(); + let start = tokio::time::Instant::now(); + drop(near); + drop(far); + let update = loop { + match announced.next().await.unwrap() { + AnnounceEvent::Live => continue, + event => break event, + } + }; + match update { + AnnounceEvent::Update(update) => assert_eq!(update.route.hops, hops(&[9, 5, 6, 7])), + other => panic!("should be an update: got {other:?}"), + } + assert_eq!(start.elapsed(), DEFAULT_UPDATE_HOLD); + announced.assert_next_wait(); + + // The last route goes: retracted at once. + drop(farther); + announced.assert_next_ended("room"); + } + /// A peer withdrawing a prefix hides the routes there through it, so the next /// best is never a path derived from the one withdrawn. Announcing again /// revives them, and nothing is remembered once no route passes through it. @@ -7060,6 +7603,86 @@ mod tests { pending.await.expect("re-request resolves through the rival"); } + /// A route updated in place to a new first hop names a new publisher, whether the + /// front started anonymous or named. The in-flight subscription drains the old copy + /// until it ends and never splices the new one; a new request gets a fresh front + /// through the new publisher, free of the old broadcast's track info. + #[tokio::test] + async fn a_first_hop_update_drains_the_old_publisher() { + for first in [&[][..], &[0][..], &[10][..]] { + let (mut rig, server, _source) = ResumeRig::new(first).await; + server.update(Route::default().with_hops(hops(&[11]))).unwrap(); + + // The old copy keeps flowing to the subscription already reading it. + let mut group = rig.incumbent_track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"draining".as_ref()).unwrap(); + group.finish().unwrap(); + let mut group = next_group(&mut rig.subscription) + .await + .expect("the in-flight subscription survives the update") + .expect("track ended early"); + let frame = group.read_frame().await.expect("read frame").expect("frame"); + assert_eq!(&frame.payload[..], b"draining", "first hop {first:?}"); + + // A new request is a new broadcast from the new publisher, whose track info + // differs from what the old front cached. + let consumer = rig.producer.consume(); + let pending = consumer.request_broadcast("room/alice"); + let request = queued(&server).await; + let replacement = broadcast::Info::new().produce(); + let track = replacement + .create_track("video", track::Info::default().with_priority(7)) + .unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"new".as_ref()).unwrap(); + group.finish().unwrap(); + request.accept(&replacement); + + let resolved = pending.await.expect("resolves through the new publisher"); + assert!( + !resolved.is_clone(&rig.resolved), + "first hop {first:?} joined the old front" + ); + let mut fresh = resolved + .track("video") + .unwrap() + .subscribe(None) + .await + .expect("the old publisher's track info does not apply"); + let mut group = next_group(&mut fresh) + .await + .expect("recv group") + .expect("track ended early"); + let frame = group.read_frame().await.expect("read frame").expect("frame"); + assert_eq!(&frame.payload[..], b"new"); + + // The old copy ending ends the drained subscription, without a group from + // the new publisher. + rig.incumbent_track.finish().unwrap(); + let end = next_group(&mut rig.subscription).await; + assert!( + !matches!(end, Ok(Some(_))), + "first hop {first:?} spliced the new publisher into a live subscription" + ); + } + } + + /// A named front whose route moves to a new publisher resumes through another route + /// from its own publisher, never through the updated one. + #[tokio::test] + async fn a_first_hop_update_resumes_through_the_same_publisher() { + let (mut rig, incumbent, _source) = ResumeRig::new(&[10]).await; + let standby_server = rig.standby(&[10, 20]); + + incumbent.update(Route::default().with_hops(hops(&[11]))).unwrap(); + + assert_resumes(&mut rig, &standby_server).await; + assert!( + incumbent.poll_requested_broadcast(&kio::Waiter::noop()).is_pending(), + "the front never asks the new publisher" + ); + } + #[tokio::test] async fn anonymous_routes_never_resume() { // An empty hop chain identifies nobody, so two of them must not pass for diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 66360e9d462..5620702cfb9 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -26,10 +26,8 @@ use std::collections::{BTreeMap, HashSet}; use std::ops::Bound; use std::task::{Poll, ready}; -#[cfg(test)] -use crate::Timestamp; -use crate::{Datagram, Error, Result, frame, group, track}; -use track::{Anchor, LiveEdge, Successor}; +use crate::{Datagram, Error, Result, Timestamp, frame, group, track}; +use track::{Anchor, LiveEdge}; use super::subscription::{Cap, Position, Subscription, max_some, min_some}; @@ -144,18 +142,60 @@ fn slice(prefs: &Subscription, start: Option, end: Option) - } } -/// The first servable group in `from..cap` across `segments`, with the slot identity a -/// later judgment needs. An unstamped group stops the search: skipping it for a later -/// start would shrink a reach that is not yet proven. -fn served_start(segments: &[Segment], from: u64, cap: Option) -> Option { - segments.iter().find_map(|segment| { +/// Where the first servable group in `from..cap` across `segments` starts presenting; +/// see [`track::Consumer::poll_first_start`]. An unstamped group stops the search: +/// skipping it for a later start would shrink a reach that is not yet proven. +fn poll_first_start<'a>( + segments: impl IntoIterator, + waiter: &kio::Waiter, + from: u64, + cap: Option, +) -> Option> { + segments.into_iter().find_map(|segment| { let start = segment.start.map_or(0, |start| start.group).max(from); segment .track - .served_start(start, min_some(cap, last_group(segment.end))) + .poll_first_start(waiter, start, min_some(cap, last_group(segment.end))) }) } +/// Where a splice continues past the exclusive group `boundary` of segment `after`, +/// below the reader's `cap`: the first group the later segments serve there. Holds the +/// question rather than a cached answer, so a group aborted or evicted before its first +/// frame hands the bound to whichever group serves there next. +#[derive(Clone)] +pub(crate) struct Successor { + state: kio::ConsumerWeak, + after: u64, + boundary: u64, + cap: Option, +} + +impl Successor { + /// Where the successor starts presenting: `None` while no later group is cached or + /// the first one is unstamped. Registers `waiter` for anything that could move it. + /// Takes the splice's and its segments' locks, so never call it under a track's. + pub(crate) fn poll_start(&self, waiter: &kio::Waiter) -> Option { + let mut start = None; + let _ = self.state.poll(waiter, |state| { + // A draining reader's own segment may already have been pruned. + let later = state.segments.iter().filter(|segment| segment.id > self.after); + start = poll_first_start(later, waiter, self.boundary, self.cap).flatten(); + Poll::<()>::Pending + }); + start + } +} + +impl PartialEq for Successor { + fn eq(&self, other: &Self) -> bool { + self.after == other.after + && self.boundary == other.boundary + && self.cap == other.cap + && self.state.same_channel(&other.state) + } +} + /// How many segments a logical track keeps before pruning terminal ones from the /// front: the live segment plus a couple of predecessors still draining to slow /// readers. Without a bound, every failover leaves one dead segment (pinning a @@ -248,14 +288,6 @@ impl ResumeState { .max_by_key(|edge| edge.sequence) } - /// Where the logical track continues past the exclusive group `boundary` of segment - /// `id`, below the reader's `cap`: the start of the first group the later segments - /// serve there. `None` while none is cached, or it has no frame yet. - fn successor(&self, id: u64, boundary: u64, cap: Option) -> Option { - let index = self.segments.iter().position(|segment| segment.id == id)?; - served_start(&self.segments[index + 1..], boundary, cap) - } - /// Append a segment serving the track from `start` onward, capping (or replacing) /// the previous segments so the ranges stay disjoint and ascending. fn switch(&mut self, track: track::Consumer, start: Option) -> Result<()> { @@ -695,6 +727,13 @@ impl Consumer { self.state.read().latest() } + /// The newest segment's declared exclusive end, where fetches are routed. + pub(crate) fn final_sequence(&self) -> Option { + // Copied out: the segment's track takes its own lock. + let track = self.state.read().segments.last().map(|segment| segment.track.clone())?; + track.final_sequence() + } + /// One past the newest position across the segments: where a route taking this /// logical track over would resume. pub(crate) fn resume_position(&self) -> Option { @@ -706,10 +745,20 @@ impl Consumer { self.state.read().live_edge(cap) } - /// Where the first servable group in `from..cap` starts, with the identity to - /// revalidate it; see [`track::Consumer::served_start`]. - pub(crate) fn served_start(&self, from: u64, cap: Option) -> Option { - served_start(&self.state.read().segments, from, cap) + /// Where the first servable group in `from..cap` starts presenting; see + /// [`track::Consumer::poll_first_start`]. + pub(crate) fn poll_first_start( + &self, + waiter: &kio::Waiter, + from: u64, + cap: Option, + ) -> Option> { + let mut start = None; + let _ = self.state.poll(waiter, |state| { + start = poll_first_start(&state.segments, waiter, from, cap); + Poll::<()>::Pending + }); + start } /// The newest cached group across every spliced segment; see @@ -801,11 +850,13 @@ impl kio::Task for Fetching { type Output = Result; fn poll(&mut self, waiter: &kio::Waiter) -> Poll { - if let Some(group) = (Consumer { + if let Some(mut group) = (Consumer { state: self.state.clone(), }) .cached_group(self.sequence, self.options.frame_start) { + // Sitting where the caller asked, as a fetch from the segment's own track would. + group.start_at(self.options.frame_start); return Poll::Ready(Ok(group)); } @@ -1721,16 +1772,21 @@ impl Subscriber { /// content the logical track holds, which a segment's own track never sees. /// /// When the boundary lowers the cap, the reader's next group past it lives in a - /// later segment, so `state` supplies where it starts ([`Anchor::successor`]). - /// Otherwise the logical anchor's own successor (a wrapping splice's) still holds. - fn segment_anchor(seg: &SegmentSub, anchor: Anchor, state: &ResumeState) -> Anchor { + /// later segment of `state` ([`Anchor::successor`]). Otherwise the logical anchor's + /// own successor (a wrapping splice's) still holds. + fn segment_anchor(seg: &SegmentSub, anchor: Anchor, state: &kio::Consumer) -> Anchor { let Some(boundary) = seg.last_group() else { return anchor; }; let cap = anchor.cap; let mut capped = anchor.capped(Some(boundary)); if capped.cap != cap { - capped.successor = state.successor(seg.id, boundary, cap); + capped.successor = Some(Successor { + state: state.weak(), + after: seg.id, + boundary, + cap, + }); } capped } @@ -1749,8 +1805,9 @@ impl Subscriber { /// logical edge moves whenever any of them grows. fn refresh_anchor(&mut self) { let outer = self.outer.clone().capped(self.end_sequence); - let state = self.state.read(); - let edge = state + let edge = self + .state + .read() .live_edge(outer.cap) .into_iter() .chain(outer.edge.clone()) @@ -1763,7 +1820,7 @@ impl Subscriber { *current = anchor.clone(); } for seg in &mut self.segments { - let anchor = Self::segment_anchor(seg, anchor.clone(), &state); + let anchor = Self::segment_anchor(seg, anchor.clone(), &self.state); seg.anchor = anchor.clone(); if let Some(sub) = seg.stale_sub_mut() { sub.set_anchor(anchor); @@ -2880,6 +2937,33 @@ mod test { assert_eq!(read(&mut group), b"b4"); } + /// A cached copy is handed back sitting at the requested frame, the same as a fetch + /// the segment's own track answers. + #[tokio::test] + async fn a_cached_fetch_starts_at_the_requested_frame() { + let (track_a, consumer_a) = track_pair("a"); + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + + let mut group = track_a.create_group(group::Info { sequence: 0 }).unwrap(); + for payload in ["f0", "f1", "f2"] { + group + .write_frame(crate::Timestamp::ZERO, payload.as_bytes().to_vec()) + .unwrap(); + } + group.finish().unwrap(); + + let mut group = producer + .consume() + .fetch_group(0, group::Fetch::default().with_frame_start(1)) + .now_or_never() + .expect("cached fetch should resolve") + .unwrap(); + assert_eq!(group.index(), 1); + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(frame.payload.as_ref(), b"f1"); + } + #[tokio::test] async fn fetch_waits_for_first_segment() { let (mut track_a, consumer_a) = track_pair("a"); @@ -3303,6 +3387,157 @@ mod test { assert_eq!(replayed, vec![0, 1, 2, 3], "a backlog inside the budget crosses whole"); } + #[tokio::test] + async fn unstamped_successor_segment_keeps_the_previous_group_unbounded() { + let (mut a, a_read) = track_pair("a"); + let (b, b_read) = track_pair("b"); + let (mut c, c_read) = track_pair("c"); + write_group_at(&mut a, 0, "a0", Duration::ZERO); + let _unstamped = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut c, 2, "c2", Duration::from_secs(10)); + write_group_at(&mut c, 3, "c3", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + producer.switch(c_read, Position::group(2)).unwrap(); + let mut sub = producer.consume().subscribe(None); + assert_eq!( + recv(&mut sub), + 0, + "the unstamped successor must not borrow segment C's start" + ); + } + + /// A handed-out group parked at its tail is re-judged once its unstamped successor in + /// the next segment presents a first frame. That frame touches only the successor's + /// group, not either track or the drift anchor, so the read has to watch it directly. + #[tokio::test] + async fn unstamped_successor_first_frame_wakes_a_parked_read() { + use std::task::Context; + + let (a, a_read) = track_pair("a"); + let (mut b, b_read) = track_pair("b"); + let mut head = a.create_group(0u64.into()).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let mut successor = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut b, 2, "edge", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + let mut sub = producer.consume().subscribe(None); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(reading.sequence, 0, "an unbounded reach is not stale"); + assert_eq!(read(&mut reading), b"a0"); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut next = std::pin::pin!(reading.read_frame()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + + let before = counter.count(); + successor + .write_frame(Duration::from_secs(1).try_into().unwrap(), b"b1".to_vec()) + .unwrap(); + assert!(counter.count() > before, "the successor's first frame lost its wakeup"); + let result = next.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); + } + + /// An unstamped successor aborted before its first frame no longer names where the + /// track continues, so a read parked at the previous group's tail re-resolves it: + /// first to a later group already cached, then to one that arrives after the abort. + #[tokio::test] + async fn aborted_unstamped_successor_re_resolves_a_parked_read() { + use std::task::Context; + + let (a, a_read) = track_pair("a"); + let (mut b, b_read) = track_pair("b"); + let mut head = a.create_group(0u64.into()).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let successor = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut b, 3, "edge", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + let budget = Subscription::default().with_max_age(Duration::from_secs(10)); + let mut sub = producer.consume().subscribe(budget); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(reading.sequence, 0, "an unbounded reach is not stale"); + assert_eq!(read(&mut reading), b"a0"); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut next = std::pin::pin!(reading.read_frame()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + + successor.abort(Error::Cancel).unwrap(); + // Group 3 is now the successor, and the edge itself: within the budget. + assert!(next.as_mut().poll(&mut cx).is_pending()); + + let before = counter.count(); + write_group_at(&mut b, 2, "b2", Duration::from_secs(1)); + assert!(counter.count() > before, "the replacement successor lost its wakeup"); + let result = next.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); + } + + /// The same across segments: once the next segment's only group is aborted, the + /// segment after it says where the track continues. + #[tokio::test] + async fn aborted_unstamped_successor_re_resolves_across_segments() { + use std::task::Context; + + let (a, a_read) = track_pair("a"); + let (b, b_read) = track_pair("b"); + let (mut c, c_read) = track_pair("c"); + let mut head = a.create_group(0u64.into()).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let successor = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut c, 2, "c2", Duration::from_secs(1)); + write_group_at(&mut c, 3, "c3", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + producer.switch(c_read, Position::group(2)).unwrap(); + let mut sub = producer.consume().subscribe(None); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(reading.sequence, 0, "an unbounded reach is not stale"); + assert_eq!(read(&mut reading), b"a0"); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut next = std::pin::pin!(reading.read_frame()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + + let before = counter.count(); + successor.abort(Error::Cancel).unwrap(); + assert!(counter.count() > before, "the successor's abort lost its wakeup"); + let result = next.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); + } + + #[tokio::test] + async fn pruned_segment_boundary_is_judged_against_later_segments() { + let (mut a, a_read) = track_pair("a"); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + // Keep A's cursor draining while its newest group advances beyond the late boundary group. + write_group_at(&mut a, 0, "a0", Duration::ZERO); + assert_eq!(recv(&mut sub), 0); + write_group_at(&mut a, 3, "past-boundary", Duration::from_secs(3)); + for sequence in 3..=(2 + MAX_SEGMENTS as u64) { + let (mut track, consumer) = track_pair("later"); + producer.switch(consumer, Position::group(sequence)).unwrap(); + write_group_at(&mut track, sequence, "later", Duration::from_secs(sequence * 10)); + assert_eq!(recv(&mut sub), sequence); + } + assert!(producer.state.read().pruned.is_some()); + // A's boundary group arrives after A was pruned; it is stale against group 3's start. + write_group_at(&mut a, 2, "a2", Duration::from_secs(2)); + recv_pending(&mut sub); + } + /// A segment's track never sees the groups of the segments after it: its own edge /// freezes once a takeover caps it, and its last group has no successor there. /// Both spliced cursors judge its backlog as one plain track holding the same groups diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index ab5fa660cb1..921c72af34e 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -19,6 +19,7 @@ use crate::{broadcast, cache, group, stats}; use super::{Datagram, Requests}; use super::Cap; +use super::resume::Successor; pub use super::subscription::{Position, Subscription}; use std::{ @@ -31,6 +32,10 @@ use std::{ time::Duration, }; +// The higher-first midpoint. IETF flips priority (lower first), so this goes out as 128, the +// draft's usual publisher priority, while moq-lite carries 127 as written: one urgency on both. +const DEFAULT_PRIORITY: u8 = 127; + /// Maximum number of datagrams retained in the per-track send buffer. /// /// Datagrams are a best-effort send buffer, not a replay cache (unlike groups): only the last @@ -70,7 +75,7 @@ pub(super) struct ExpiryScan { // Deliberately not `Copy`, even though it's now a plain value: adding `Copy` turns // every existing `info.clone()` in a consumer's code into a `clippy::clone_on_copy` // error under `-D warnings`. -#[derive(Clone, Debug, Default)] +#[derive(Clone, Debug)] #[non_exhaustive] pub struct Info { /// Units per second for per-frame timestamps on this track. @@ -104,9 +109,20 @@ pub struct Info { pub max_age: Option, /// The publisher's priority for this track, used only to break ties between /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). + /// Higher is more urgent. Defaults to 127, the midpoint. pub priority: u8, } +impl Default for Info { + fn default() -> Self { + Self { + timescale: Timescale::default(), + max_age: None, + priority: DEFAULT_PRIORITY, + } + } +} + impl Info { /// Set the per-frame timestamp scale, returning `self` for chaining. /// @@ -544,40 +560,20 @@ impl TrackState { /// and `beyond` is where it starts when another track serves it (a splice's next /// segment; see [`Anchor::successor`]). fn reach(&self, sequence: u64, cap: Option, beyond: Option) -> Option { - match self.first_start(sequence.saturating_add(1), cap) { - Some(start) => start, + match self.first_servable(sequence.saturating_add(1), cap) { + Some(group) => group.timestamp(), None => beyond, } } - /// Where the first servable group in `from..cap` starts presenting: `None` when no - /// such group is cached, `Some(None)` while it has no frame yet. - fn first_start(&self, from: u64, cap: Option) -> Option> { - let slot = self - .lookup - .range(from..) - .map(|(_, slot)| slot) - .take_while(|slot| super::subscription::before_end(slot.group.sequence, cap)) - .find(|slot| slot.visible && !slot.group.is_aborted())?; - Some(slot.group.timestamp()) - } - - /// The first servable group's start in `from..cap`, with the slot identity a later - /// judgment needs to tell that group from whatever replaces it. `None` when no such - /// group is cached or it has no frame yet: an unstamped successor leaves reach - /// unbounded, and this does not skip past it to a later group. - fn served_start(&self, from: u64, cap: Option) -> Option { - let slot = self - .lookup + /// The first servable group in `from..cap`, stamped or not. + fn first_servable(&self, from: u64, cap: Option) -> Option<&group::Producer> { + self.lookup .range(from..) .map(|(_, slot)| slot) .take_while(|slot| super::subscription::before_end(slot.group.sequence, cap)) - .find(|slot| slot.visible && !slot.group.is_aborted())?; - Some(ServedStart { - sequence: slot.group.sequence, - stamp: slot.stamp, - timestamp: slot.group.timestamp()?, - }) + .find(|slot| slot.visible && !slot.group.is_aborted()) + .map(|slot| &slot.group) } /// Whether the group at `sequence` has drifted further behind `edge` than `budget` @@ -618,9 +614,9 @@ impl TrackState { .presentation .filter(|live| self.holds(live.sequence, live.stamp)) .map(|live| (live.sequence, live.timestamp)); - // `outer` and `successor` were revalidated on their own tracks before this lock - // was taken ([`LiveEdge::is_live`], [`Successor::start`]). There is no slot for - // them here, and taking their locks here would nest. + // `outer` was revalidated and `successor` resolved on their own tracks before this + // lock was taken ([`LiveEdge::is_live`], [`Successor::poll_start`]). There is no + // slot for them here, and taking their locks here would nest. let Some((_, timestamp)) = local .into_iter() .chain(edge.outer) @@ -1377,9 +1373,8 @@ impl Producer { /// track's groups but drawing from the same sequence namespace (so interleaving with /// [`Self::append_group`] never reuses a number). There is no group fallback: each /// session drops (with a debug log) any datagram whose encoded body exceeds the - /// transport's datagram size, and sessions that can't carry datagrams at all (IETF - /// moq-transport, moq-lite before 05, or stream-only transports like WebSocket) never - /// deliver them. Keep payloads well under the 1200-byte minimum path MTU. An origin + /// transport's datagram size, and sessions that can't carry datagrams at all (moq-lite + /// before 05, or stream-only transports like WebSocket) never deliver them. Keep payloads well under the 1200-byte minimum path MTU. An origin /// publisher uses this; a relay preserving upstream numbering uses /// [`Self::insert_datagram`]. pub fn append_datagram(&mut self, timestamp: Timestamp, payload: B) -> Result { @@ -1728,22 +1723,7 @@ impl Producer { let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); - let prev = &self.prev_subscription; - let mut combined = None; - let mut guard = ready!(subs.poll(waiter, |subs| { - let next = combined_subscription(subs, bound, waiter); - if &next == prev { - Poll::Pending - } else { - combined = next; - Poll::Ready(()) - } - })); - // The aggregate changed: prune any closed subscribers now that we hold the lock. - guard.retain(|sub| !sub.is_closed()); - drop(guard); - self.prev_subscription = combined.clone(); - Poll::Ready(Ok(combined)) + poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter).map(Ok) } /// Create a [`Dynamic`] handle that serves on-demand fetches of uncached @@ -1979,19 +1959,60 @@ impl Drop for Alive { } } -/// Aggregate every live subscriber's preferences into the most demanding request. +/// Poll until the aggregate across `subs` differs from `prev`, then store and return it. +/// +/// Departed subscribers are pruned whenever the scan meets one, even when the aggregate +/// holds. Churn with a steady viewer's preferences never changes it, so otherwise every +/// wake would walk every departed entry the list has room for since its peak. +fn poll_combined_changed( + subs: &kio::Shared, + bound: Option, + prev: &mut Option, + waiter: &kio::Waiter, +) -> Poll> { + loop { + let mut next = None; + let mut departed = false; + let mut guard = ready!(subs.poll(waiter, |subs| { + (next, departed) = combined_subscription(subs, bound, waiter); + if departed || next != *prev { + Poll::Ready(()) + } else { + Poll::Pending + } + })); + if departed { + guard.retain(|sub| !sub.is_closed()); + } + drop(guard); + if next != *prev { + *prev = next.clone(); + return Poll::Ready(next); + } + // Only pruned: a ready poll skips registering, so poll again to park on the list. + } +} + +/// Aggregate every live subscriber's preferences into the most demanding request, and +/// report whether any departed subscriber is still listed. /// /// Read-only: iterates the subscriptions immutably and registers `waiter` on each, so a /// preference update (or a subscriber dropping) wakes the caller's poll. Callers decide /// readiness from the returned value, then prune closed subscribers through the `Mut`. -fn combined_subscription(subs: &Subscriptions, bound: Option, waiter: &kio::Waiter) -> Option { +fn combined_subscription( + subs: &Subscriptions, + bound: Option, + waiter: &kio::Waiter, +) -> (Option, bool) { let mut combined = None; + let mut departed = false; for sub in subs.iter() { // A closed consumer means the subscriber dropped: it holds no live demand. // `Consumer::poll` evaluates the closure before the closed flag, so it would // still replay the final value into the aggregate; skip it explicitly so a // departed subscriber can't keep the aggregate pinned to its last request. if sub.is_closed() { + departed = true; continue; } // Arm both waiters explicitly. `poll` registers on the value channel only @@ -2006,7 +2027,7 @@ fn combined_subscription(subs: &Subscriptions, bound: Option, waiter: combined = Some(merged); } } - clamp_combined(combined, bound) + (clamp_combined(combined, bound), departed) } /// A non-blocking aggregate of the current subscriptions, without arming any waiter. @@ -2080,13 +2101,24 @@ fn clamp_combined(combined: Option, bound: Option) -> Op /// Register a subscription if the track is live: clone the shared list out of the /// state, release the track lock, then push under the list's own lock. A closed /// track skips the push; nothing aggregates the preferences anymore. +/// +/// Departed subscribers are pruned here too, so the list stays bounded on a track whose +/// aggregate nobody polls. Pruning on every push would make a burst of N joins O(N^2), +/// so, like `kio::WaiterList::register`, it only sweeps when the list is about to grow. fn register_subscription(state: kio::Ref<'_, TrackState>, subscription: &kio::Producer) { if state.is_closed() { return; } let subs = state.subscriptions.clone(); drop(state); - subs.lock().push(subscription.consume()); + let mut subs = subs.lock(); + if subs.len() == subs.capacity() { + subs.retain(|sub| !sub.is_closed()); + // Leave at least half free, so each sweep is paid for by the pushes before it. + let live = subs.len(); + subs.reserve(live); + } + subs.push(subscription.consume()); } /// A weak reference to a track that doesn't prevent auto-close. @@ -2204,7 +2236,11 @@ impl Demand { /// The publisher's tie-break priority, as set in [`Info::priority`]. pub(crate) fn priority(&self) -> u8 { // Always Some once the track exists; a closed one reads its last value. - self.state.read().info.as_ref().map_or(0, |info| info.priority) + self.state + .read() + .info + .as_ref() + .map_or(DEFAULT_PRIORITY, |info| info.priority) } /// Whether the track is open and anyone is subscribed right now, without waiting. @@ -2490,20 +2526,29 @@ impl Consumer { } } - /// Where the first servable group in `from..cap` starts, with enough identity to - /// revalidate it later. A splice answers from the first segment holding one. - pub(crate) fn served_start(&self, from: u64, cap: Option) -> Option { + /// Where the first servable group in `from..cap` starts presenting: `None` while no + /// such group is cached, `Some(None)` while it has no frame yet. Registers `waiter` + /// for whatever could move that answer: a group arriving or leaving, or the unstamped + /// one's first frame. A splice answers from the first segment holding one. + pub(crate) fn poll_first_start( + &self, + waiter: &kio::Waiter, + from: u64, + cap: Option, + ) -> Option> { match &self.inner { ConsumerKind::Plain(state) => { - let served = state.read().served_start(from, cap)?; - Some(Successor { - sequence: served.sequence, - timestamp: served.timestamp, - stamp: served.stamp, - track: state.weak(), - }) + let mut start = None; + let _ = state.poll(waiter, |state| { + start = state.first_servable(from, cap).map(|group| { + let _ = group.poll_timestamp(waiter); + group.timestamp() + }); + Poll::<()>::Pending + }); + start } - ConsumerKind::Spliced(resume) => resume.served_start(from, cap), + ConsumerKind::Spliced(resume) => resume.poll_first_start(waiter, from, cap), } } @@ -2751,6 +2796,16 @@ impl Consumer { } } + /// The declared exclusive final sequence, or `None` while the track is open ended. + /// + /// A spliced track answers for its newest segment, which is where fetches go. + pub(crate) fn final_sequence(&self) -> Option { + match &self.inner { + ConsumerKind::Plain(state) => state.read().final_sequence, + ConsumerKind::Spliced(resume) => resume.final_sequence(), + } + } + /// The frame-precise point a replacement route should resume from: one past the /// last frame this copy produced. `None` if it produced nothing. /// @@ -2945,6 +3000,16 @@ impl group::Request { res } + /// Declare the track's exclusive final sequence, as the publisher answering this + /// fetch reported it. A no-op once the track declared one, or holds a later group. + pub(crate) fn finish_track_at(&self, final_sequence: u64) { + if let Ok(mut state) = TrackState::modify(&self.state) + && state.final_sequence.is_none() + { + let _ = state.set_final(final_sequence); + } + } + /// Reject the fetch, resolving every joined [`Consumer::fetch_group`] with `err`. pub fn reject(mut self, err: Error) { self.done = true; @@ -3117,8 +3182,8 @@ enum SubscriberKind { /// One poll's view of how far this subscription may drift: the clamped budget and the /// live edge to measure a candidate group against. Resolved once, then applied to every -/// group that poll considers. `outer` and `successor` are revalidated per candidate, -/// outside this track's lock. +/// group that poll considers. `outer` is revalidated and `successor` resolved per +/// candidate, outside this track's lock. #[derive(Clone)] struct Drift { budget: Duration, @@ -3161,7 +3226,10 @@ impl group::Expiry for GroupExpiry { .edge .filter(LiveEdge::is_live) .map(|live| (live.sequence, live.timestamp)); - let successor = anchor.successor.as_ref().and_then(Successor::start); + let successor = anchor + .successor + .as_ref() + .and_then(|successor| successor.poll_start(waiter)); let mut expired = false; let _ = self.state.poll(waiter, |state| { @@ -3250,8 +3318,8 @@ pub(crate) struct Anchor { /// Where the reader's next group past `cap` starts presenting, when another track /// serves it (a splice's next segment). The last group below the cap has no /// successor in its own track, so without this nothing bounds its reach and it is - /// never judged stale. `None` while unknown or unstamped. Revalidated like `edge`: - /// a cached start must not convict once that group is gone. + /// never judged stale. Resolved afresh on every judgment rather than cached, so a + /// group that goes away hands the bound to whichever group serves there next. pub successor: Option, } @@ -3297,48 +3365,6 @@ impl PartialEq for LiveEdge { } } -/// The first servable group past a segment boundary: where it starts, and which slot -/// that start was read from. -struct ServedStart { - sequence: u64, - stamp: u32, - timestamp: Timestamp, -} - -/// A successor pushed onto another track's cursor. The timestamp alone is not enough: -/// once the group is evicted, a later group can keep the outer edge valid while this -/// start is no longer where the track continues. -#[derive(Clone)] -pub(crate) struct Successor { - sequence: u64, - timestamp: Timestamp, - stamp: u32, - track: kio::ConsumerWeak, -} - -impl Successor { - /// The start this still names, re-read from its own track, or `None` once that - /// group is gone or no longer stamped. Takes that track's lock, so never call it - /// under another's. - fn start(&self) -> Option { - let state = self.track.read(); - let slot = state.lookup.get(&self.sequence)?; - if slot.stamp != self.stamp || slot.group.is_aborted() { - return None; - } - slot.group.timestamp() - } -} - -impl PartialEq for Successor { - fn eq(&self, other: &Self) -> bool { - self.sequence == other.sequence - && self.timestamp == other.timestamp - && self.stamp == other.stamp - && self.track.same_channel(&other.track) - } -} - /// The newest servable group that has presented at least one frame. #[derive(Clone, Copy)] struct PresentationEdge { @@ -3478,7 +3504,10 @@ impl PlainSubscriber { .as_ref() .filter(|live| live.is_live()) .map(|live| (live.sequence, live.timestamp)); - let successor = drift.successor.as_ref().and_then(Successor::start); + let successor = drift + .successor + .as_ref() + .and_then(|successor| successor.poll_start(waiter)); let presentation = drift.edge.presentation; let cap = drift.edge.cap; let budget = drift.budget; @@ -4402,22 +4431,7 @@ impl Request { let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); - let prev = &self.prev_subscription; - let mut combined = None; - let mut guard = ready!(subs.poll(waiter, |subs| { - let next = combined_subscription(subs, bound, waiter); - if &next == prev { - Poll::Pending - } else { - combined = next; - Poll::Ready(()) - } - })); - // The aggregate changed: prune any closed subscribers now that we hold the lock. - guard.retain(|sub| !sub.is_closed()); - drop(guard); - self.prev_subscription = combined.clone(); - Poll::Ready(combined) + poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter) } pub(super) fn weak(&self) -> TrackWeak { @@ -5548,6 +5562,44 @@ mod test { assert_eq!(producer.subscription().unwrap().max_age, Duration::from_secs(2)); } + #[test] + fn churned_subscribers_do_not_accumulate() { + let producer = track_producer("test", None); + let consumer = producer.consume(); + let _steady = producer.subscribe(None); + + // Nobody polls the aggregate here, so registration alone has to bound the list. + for _ in 0..100 { + drop(producer.subscribe(None)); + drop(consumer.subscribe(None)); + } + + // Registration sweeps only when the list is about to grow, so it holds a small + // multiple of the peak live count (2) rather than all 200 departures. + let subs = producer.state.read().subscriptions.clone(); + let len = subs.read().len(); + assert!(len <= 8, "departed subscribers accumulated: {len}"); + } + + #[test] + fn aggregate_poll_prunes_after_a_peak() { + let mut producer = track_producer("test", None); + let waiter = kio::Waiter::noop(); + let _steady = producer.subscribe(None); + assert!(producer.poll_subscription_changed(&waiter).is_ready()); + + // A departed burst leaves room for many entries, and identical preferences never + // change the aggregate, so each wake has to prune what it walks. + drop((0..1000).map(|_| producer.subscribe(None)).collect::>()); + for _ in 0..100 { + drop(producer.subscribe(None)); + assert!(producer.poll_subscription_changed(&waiter).is_pending()); + + let subs = producer.state.read().subscriptions.clone(); + assert_eq!(subs.read().len(), 1, "the poll walked past departed subscribers"); + } + } + /// Append a finished group presenting at `millis`, so the track carries a media /// timeline for the drift budget to measure against. fn append_at(producer: &mut Producer, millis: u64) -> u64 { @@ -6410,47 +6462,6 @@ mod test { open.finish().unwrap(); } - /// A pushed successor is the same kind of cached fact. Evicting it must not keep - /// bounding the previous segment's last group while a later group still anchors the - /// outer edge. - #[tokio::test] - async fn an_evicted_successor_convicts_nothing() { - let producer = track_producer("a", None); - let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(1))); - let mut open = producer.append_group().unwrap(); - open.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"a")) - .unwrap(); - let mut group = subscriber.recv_group().await.unwrap().expect("group"); - assert!(group.read_frame().await.unwrap().is_some()); - - let mut next = track_producer("b", None); - // Early enough that group 0 is already past the budget, and not itself the edge. - let successor = append_at(&mut next, 10); - append_at(&mut next, 30_000); - let consumer = next.consume(); - subscriber.set_anchor(Anchor { - cap: None, - edge: consumer.live_edge(None), - successor: consumer.served_start(successor, None), - }); - - let mut control = group.clone(); - assert!( - matches!(control.read_frame().now_or_never(), Some(Ok(None))), - "the open group ends against the successor" - ); - - let slot = next.modify().unwrap().lookup.remove(&successor).unwrap(); - let _ = slot.group.abort(Error::Evicted); - - assert!( - group.read_frame().now_or_never().is_none(), - "a vanished successor is no reason to drop what is left" - ); - assert!(!group.latency_expired()); - open.finish().unwrap(); - } - #[tokio::test] async fn a_lower_sequence_is_never_the_live_edge() { let producer = track_producer("test", None); diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 6a35f323941..a503d72bb54 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -532,6 +532,7 @@ where cost: None, version, path: None, + authority: None, peer_setup_stream: Some(peer_setup.stream), peer_declared: Some(peer_setup.declared), })?; @@ -639,6 +640,7 @@ where cost: None, version: v, path: None, + authority: None, peer_setup_stream: None, peer_declared: Some(peer_declared), })?; diff --git a/rs/moq-net/src/setup.rs b/rs/moq-net/src/setup.rs index 3a4a96cba09..24caaffebb7 100644 --- a/rs/moq-net/src/setup.rs +++ b/rs/moq-net/src/setup.rs @@ -10,6 +10,9 @@ use crate::{ ietf, lite, }; +// SETUP only carries negotiation parameters. Bound it independently of control messages. +pub(crate) const MAX_SETUP_SIZE: usize = 64 * 1024; + const CLIENT_SETUP: u8 = 0x20; const SERVER_SETUP: u8 = 0x21; @@ -72,6 +75,7 @@ impl Decode for Setup { if kind != SETUP_V17 { return Err(DecodeError::InvalidValue); } + // The fixed u16 length is already below MAX_SETUP_SIZE. let size = u16::decode(r, v)? as usize; if r.remaining() < size { return Err(DecodeError::Short); @@ -145,10 +149,17 @@ impl Decode for Client { let size = match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => u16::decode(r, v)? as usize, - SetupVersion::LiteLegacy => u64::decode(r, v)? as usize, + SetupVersion::LiteLegacy => usize::decode(r, v)?, SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; + if size > MAX_SETUP_SIZE { + return Err(DecodeError::MessageTooLarge { + size, + max: MAX_SETUP_SIZE, + }); + } + if r.remaining() < size { return Err(DecodeError::Short); } @@ -160,7 +171,9 @@ impl Decode for Client { // Draft15+: no versions list, parameters only. coding::Versions::from([v.into()]) } - SetupVersion::Draft14 | SetupVersion::LiteLegacy => coding::Versions::decode(&mut msg, v)?, + SetupVersion::Draft14 | SetupVersion::LiteLegacy => { + coding::Versions::decode(&mut msg, v).map_err(DecodeError::complete)? + } SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; @@ -179,6 +192,9 @@ impl Encode for Client { let mut sizer = Sizer::default(); self.encode_inner(&mut sizer, v)?; let size = sizer.size; + if size > MAX_SETUP_SIZE { + return Err(EncodeError::TooLarge); + } match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => { @@ -226,6 +242,9 @@ impl Encode for Server { let mut sizer = Sizer::default(); self.encode_inner(&mut sizer, v)?; let size = sizer.size; + if size > MAX_SETUP_SIZE { + return Err(EncodeError::TooLarge); + } match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => { @@ -249,10 +268,17 @@ impl Decode for Server { let size = match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => u16::decode(r, v)? as usize, - SetupVersion::LiteLegacy => u64::decode(r, v)? as usize, + SetupVersion::LiteLegacy => usize::decode(r, v)?, SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; + if size > MAX_SETUP_SIZE { + return Err(DecodeError::MessageTooLarge { + size, + max: MAX_SETUP_SIZE, + }); + } + if r.remaining() < size { return Err(DecodeError::Short); } @@ -260,7 +286,9 @@ impl Decode for Server { let mut msg = r.copy_to_bytes(size); let version = match SetupVersion::from_version(v) { SetupVersion::Draft15Plus => v.into(), - SetupVersion::Draft14 | SetupVersion::LiteLegacy => coding::Version::decode(&mut msg, v)?, + SetupVersion::Draft14 | SetupVersion::LiteLegacy => { + coding::Version::decode(&mut msg, v).map_err(DecodeError::complete)? + } SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; @@ -270,3 +298,29 @@ impl Decode for Server { }) } } + +#[cfg(test)] +mod tests { + use super::*; + + /// Never emit a legacy SETUP our own receiver would refuse. + #[test] + fn encode_enforces_the_setup_limit() { + let v = Version::Lite(lite::Version::Lite01); + let parameters = Bytes::from(vec![0; MAX_SETUP_SIZE]); + + let client = Client { + versions: coding::Versions::from([v.into()]), + parameters: parameters.clone(), + }; + let mut buf = Vec::new(); + assert!(matches!(client.encode(&mut buf, v), Err(EncodeError::TooLarge))); + + let server = Server { + version: v.into(), + parameters, + }; + let mut buf = Vec::new(); + assert!(matches!(server.encode(&mut buf, v), Err(EncodeError::TooLarge))); + } +} diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index 34e2ff6a292..b32a2f66487 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -5,10 +5,14 @@ //! it. The subscriber keeps the subscription routable until each owed group is accounted //! for, or a grace expires for a group whose stream was reset before its header arrived. //! A reset that keeps the header (reliable reset) would make the grace unnecessary. +//! +//! A stream whose header arrived is read to its end whatever the grace says: a group ends +//! on its own stream's FIN or reset, never because its track ended. A lost datagram is not +//! owed: it leaves a hole that waits out the grace like a stream reset before its header. use std::{ops::Range, task::Poll, time::Duration}; -use crate::runtime::Deadline; +use crate::runtime::{Deadline, Instant}; /// How long a subscriber waits for a group stream it cannot account for once the /// publisher has ended the subscription. @@ -17,52 +21,125 @@ use crate::runtime::Deadline; /// it with. Matches `@moq/net`, so a reader cannot tell which side it is talking to. pub(crate) const GRACE: Duration = Duration::from_secs(1); +/// The grace for a subscription with `max_age`: how long the subscriber was willing to +/// wait for a late group anyway, or [`GRACE`] without one. +pub(crate) fn grace(max_age: Duration) -> Duration { + match max_age.is_zero() { + true => GRACE, + false => max_age, + } +} + +/// A run of accounted sequences. +#[derive(Debug, Clone, PartialEq, Eq)] +struct Run { + groups: Range, + /// When the gap below this run opened, which is when its missing groups became late. + since: Instant, +} + /// The data streams a subscription has received, and the groups they account for. -#[derive(Default, Debug)] +#[derive(Debug)] pub(crate) struct Tail { - // Disjoint, sorted, non-adjacent ranges of accounted sequences, so this grows with the - // number of gaps rather than the number of groups. - accounted: Vec>, + // Disjoint, sorted, non-adjacent runs of accounted sequences. A gap older than the grace + // can no longer be waited for, so it folds into the runs around it, which bounds this by + // the gaps opened within the grace rather than every gap in the subscription. A fold is + // final: a later, longer grace or a lowered floor cannot reopen it. + runs: Vec, + grace: Duration, streams: u64, + // Streams whose header arrived and that are still being read. + active: u64, +} + +impl Default for Tail { + fn default() -> Self { + Self { + runs: Vec::new(), + grace: GRACE, + streams: 0, + active: 0, + } + } } impl Tail { - /// Record a group stream whose header arrived. - pub fn open(&mut self, sequence: u64) { - self.stream(); - self.account(sequence..sequence.saturating_add(1)); + /// A tail that gives up on a missing group after `grace`. + pub fn new(grace: Duration) -> Self { + Self { + grace, + ..Self::default() + } } - /// Record a data stream that names no single group, such as a fill. - pub fn stream(&mut self) { - self.streams += 1; + /// Change the grace, for a subscription whose max age changed. + pub fn set_grace(&mut self, grace: Duration) { + self.grace = grace; } /// Record groups as accounted for without a stream: dropped, or sent as a datagram. - pub fn account(&mut self, groups: Range) { + pub fn account(&mut self, groups: Range, now: Instant) { if groups.is_empty() { return; } - // Every range the insert overlaps or touches merges with it into one. - let first = self.accounted.partition_point(|range| range.end < groups.start); - let last = self.accounted.partition_point(|range| range.start <= groups.end); - let merged = match &self.accounted[first..last] { - [] => groups, - [head, .., tail] => head.start.min(groups.start)..tail.end.max(groups.end), - [only] => only.start.min(groups.start)..only.end.max(groups.end), + // Every run the insert overlaps or touches merges with it into one. + let first = self.runs.partition_point(|run| run.groups.end < groups.start); + let last = self.runs.partition_point(|run| run.groups.start <= groups.end); + let merged = match &self.runs[first..last] { + [] => Run { + groups, + // Splitting a gap leaves both halves as late as it was. A run past every + // other one opens a new gap. + since: self.runs.get(first).map_or(now, |above| above.since), + }, + [head, .., tail] => Run { + groups: head.groups.start.min(groups.start)..tail.groups.end.max(groups.end), + since: head.since, + }, + [only] => Run { + groups: only.groups.start.min(groups.start)..only.groups.end.max(groups.end), + since: only.since, + }, }; - self.accounted.splice(first..last, [merged]); + self.runs.splice(first..last, [merged]); + self.expire(now); + } + + /// Restart the age of every gap reaching into `groups`, which the demand newly asks for. + pub fn demand(&mut self, groups: Range, now: Instant) { + if groups.is_empty() { + return; + } + let mut below = 0; + for run in &mut self.runs { + if below < groups.end && groups.start < run.groups.start { + run.since = now; + } + below = run.groups.end; + } + } + + /// Fold every gap older than the grace into the runs around it. + pub fn expire(&mut self, now: Instant) { + let grace = self.grace; + self.runs.dedup_by(|run, below| { + let expired = now.duration_since(run.since) >= grace; + if expired { + below.groups.end = run.groups.end; + } + expired + }); } /// Whether every group in `groups` is accounted for. pub fn covers(&self, groups: Range) -> bool { - // Ranges merge on insert, so one range covers the span or none does. + // Runs merge on insert, so one run covers the span or none does. groups.is_empty() || self - .accounted + .runs .iter() - .any(|range| range.start <= groups.start && groups.end <= range.end) + .any(|run| run.groups.start <= groups.start && groups.end <= run.groups.end) } /// Data streams received, whether they finished or were reset. @@ -71,6 +148,65 @@ impl Tail { } } +/// A data stream whose header arrived, holding its subscription's end open until dropped. +pub(crate) struct Reading { + tail: Option>, + active: bool, +} + +impl Reading { + /// Count a data stream, accounting for `group` when it names one (a fill does not). + pub fn open(tail: &kio::Producer, group: Option, now: Instant) -> Self { + let Ok(mut state) = tail.write() else { + return Self { + tail: None, + active: false, + }; + }; + state.streams += 1; + state.active += 1; + if let Some(group) = group { + state.account(group..group.saturating_add(1), now); + } + Self { + tail: Some(tail.clone()), + active: true, + } + } + + /// Stop holding the end open while the stream waits on another one, which holds it + /// open itself if its header arrived. + pub fn park(&mut self) { + self.set_active(false); + } + + /// Hold the end open again once the stream resumes reading. + pub fn resume(&mut self) { + self.set_active(true); + } + + fn set_active(&mut self, active: bool) { + if self.active == active { + return; + } + self.active = active; + if let Some(tail) = &self.tail + && let Ok(mut state) = tail.write() + { + match active { + true => state.active += 1, + false => state.active -= 1, + } + } + } +} + +impl Drop for Reading { + fn drop(&mut self) { + self.set_active(false); + } +} + /// Waits out a subscription's tail: until the owed streams are accounted for, or the grace. pub(crate) struct Settle { tail: kio::Consumer, @@ -78,21 +214,21 @@ pub(crate) struct Settle { } impl Settle { - /// Start waiting on `tail`, giving up on missing streams after `grace`. - pub fn new(runtime: &crate::time::Clock, tail: kio::Consumer, grace: Duration) -> Self { + /// Start waiting on `tail`, giving up on missing streams after its grace. + pub fn new(runtime: &crate::time::Clock, tail: kio::Consumer) -> Self { + let grace = tail.read().grace; Self { tail, grace: Deadline::after(runtime, grace), } } - /// Ready once `complete` holds, the grace expires, or the subscription is gone. + /// Ready once no stream is being read and either `complete` holds or the grace + /// expired, or once the subscription is gone. pub fn poll(&mut self, waiter: &kio::Waiter, mut complete: impl FnMut(&Tail) -> bool) -> Poll<()> { - if self.grace.poll(waiter).is_ready() { - return Poll::Ready(()); - } + let expired = self.grace.poll(waiter).is_ready(); self.tail - .poll(waiter, |tail| match complete(tail) { + .poll(waiter, |tail| match tail.active == 0 && (expired || complete(tail)) { true => Poll::Ready(()), false => Poll::Pending, }) @@ -104,24 +240,129 @@ impl Settle { mod tests { use super::*; + fn groups(tail: &Tail) -> Vec> { + tail.runs.iter().map(|run| run.groups.clone()).collect() + } + #[test] - fn ranges_merge_across_gaps() { + fn runs_merge_across_gaps() { + let now = Instant::now(); let mut tail = Tail::default(); - tail.open(0); - tail.open(2); + tail.account(0..1, now); + tail.account(2..3, now); assert!(!tail.covers(0..3), "group 1 is missing"); - assert_eq!(tail.accounted, vec![0..1, 2..3]); + assert_eq!(groups(&tail), vec![0..1, 2..3]); - tail.account(1..2); - assert!(tail.covers(0..3) && tail.accounted.len() == 1, "adjacent ranges merge"); + tail.account(1..2, now); + assert!(tail.covers(0..3) && tail.runs.len() == 1, "adjacent runs merge"); - tail.account(5..7); - tail.account(9..10); - tail.account(4..9); - assert_eq!(tail.accounted, vec![0..3, 4..10], "one insert swallows several ranges"); + tail.account(5..7, now); + tail.account(9..10, now); + tail.account(4..9, now); + assert_eq!(groups(&tail), vec![0..3, 4..10], "one insert swallows several runs"); assert!(tail.covers(4..10)); assert!(!tail.covers(2..5)); assert!(tail.covers(7..7), "an empty range is always covered"); - assert_eq!(tail.streams(), 2, "only streams count, not drops"); + } + + /// A gap older than the grace folds away, so a lossy track keeps only the gaps it can + /// still wait for. + #[test] + fn a_gap_past_the_grace_folds_away() { + let start = Instant::now(); + let mut tail = Tail::new(GRACE); + tail.account(0..1, start); + tail.account(2..3, start); + tail.account(4..5, start + GRACE / 2); + assert_eq!(groups(&tail), vec![0..1, 2..3, 4..5]); + + // Splitting the younger gap keeps it as late as it was. + tail.account(6..7, start + GRACE / 2); + tail.account(8..9, start + GRACE); + assert_eq!( + groups(&tail), + vec![0..3, 4..5, 6..7, 8..9], + "only the oldest gap expired" + ); + + tail.expire(start + GRACE * 2); + assert_eq!(groups(&tail), vec![0..9]); + assert!(tail.covers(0..9)); + } + + /// Splitting a gap leaves both halves with its age. + #[test] + fn a_split_gap_keeps_its_age() { + let start = Instant::now(); + let mut tail = Tail::new(GRACE); + tail.account(0..1, start); + tail.account(9..10, start); + tail.account(5..6, start + GRACE / 2); + assert_eq!(groups(&tail), vec![0..1, 5..6, 9..10]); + + tail.expire(start + GRACE); + assert_eq!(groups(&tail), vec![0..10], "both halves opened at the start"); + } + + /// A gap the demand newly asks for is late only from then, however old the run above it. + #[test] + fn a_lowered_floor_restarts_the_gap_age() { + let start = Instant::now(); + let mut tail = Tail::new(GRACE); + tail.account(3..4, start); + tail.account(9..10, start); + + let lowered = start + GRACE * 2; + tail.demand(1..3, lowered); + tail.account(1..2, lowered); + assert_eq!( + groups(&tail), + vec![1..2, 3..10], + "only the gap the floor reached restarts" + ); + assert!(!tail.covers(1..4)); + + tail.expire(lowered + GRACE); + assert!(tail.covers(1..10)); + } + + /// The grace gives up on streams that never arrived, never on one still being read: + /// its group, or the END_OF_TRACK it carries, still belongs to the track. + #[tokio::test(start_paused = true)] + async fn the_grace_waits_for_a_stream_being_read() { + use crate::runtime::Timers as _; + + let runtime = crate::time::Clock::tokio(); + let tail = kio::Producer::new(Tail::default()); + let reading = Reading::open(&tail, Some(0), runtime.now()); + let mut settle = Settle::new(&runtime, tail.consume()); + let mut settled = std::pin::pin!(kio::wait(|waiter| settle.poll(waiter, |_| false))); + + tokio::time::sleep(GRACE * 2).await; + assert!( + futures::poll!(settled.as_mut()).is_pending(), + "a stream is still being read" + ); + + drop(reading); + settled.await; + } + + /// A stream parked on another one does not hold the end open. + #[tokio::test(start_paused = true)] + async fn a_parked_stream_does_not_hold_the_end() { + use crate::runtime::Timers as _; + + let runtime = crate::time::Clock::tokio(); + let tail = kio::Producer::new(Tail::default()); + let mut reading = Reading::open(&tail, None, runtime.now()); + reading.park(); + let mut settle = Settle::new(&runtime, tail.consume()); + kio::wait(|waiter| settle.poll(waiter, |tail| tail.streams() == 1)).await; + + reading.resume(); + assert_eq!(tail.read().active, 1); + drop(reading); + assert_eq!(tail.read().active, 0); } } diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 24d3d03abee..5b12c04544e 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -1,8 +1,8 @@ //! Bytes cross the language boundary to a Bun script under `test/interop`: subscription -//! responses for subscribers on a mock transport, and varint encodings. +//! responses for subscribers on a mock transport, varint encodings, and moq-lite messages. use crate::coding::{Decode, Encode, VarInt}; -use crate::ietf; +use crate::{ietf, lite}; // Runs a script with a JSON argument, returning its stdout. fn bun(script: &str, input: serde_json::Value) -> Vec { @@ -68,3 +68,106 @@ fn varint_interop() { assert!(buf.is_empty()); } } + +/// Every leading-ones length boundary, plus the JS safe-integer edge and the 62-bit ceiling. +fn lite_values() -> Vec { + let mut values = vec![0]; + for bits in [6, 7, 14, 21, 28, 30, 35, 42, 49, 53, 56] { + values.extend([(1u64 << bits) - 1, 1 << bits]); + } + values.push(VarInt::MAX.into_inner()); + values +} + +/// One GROUP header and its frames, as a publisher writes them: a zigzag timestamp delta, +/// the payload size, then the payload. +fn lite_group(version: lite::Version) -> Vec { + let mut buf = Vec::new(); + let header = lite::Group { + subscribe: 5, + sequence: 1 << 20, + frame_start: 200, + }; + header.encode(&mut buf, version).unwrap(); + for (delta, size) in [(0i64, 10usize), (33_333, 300), (-1_000, 20_000), (1 << 40, 1)] { + VarInt::from_zigzag(delta).unwrap().encode(&mut buf, version).unwrap(); + size.encode(&mut buf, version).unwrap(); + buf.extend(std::iter::repeat_n(0xAB, size)); + } + buf +} + +#[derive(serde::Deserialize)] +struct Echo { + values: Vec, + varints: Vec, + setup: Vec, + datagram: Vec, + group: Vec, + beyond: Vec, +} + +/// JS decodes what Rust encodes back to the same values, and its own encoding of those +/// values is byte for byte Rust's, on lite-06 (QUIC) and lite-07 (leading-ones). +/// +/// Past 2^62-1 the range is per version. JS writes lite-07's 64-bit values, which Rust +/// must refuse with a decode error until its `VarInt` widens; on lite-06 JS refuses them. +#[test] +#[ignore = "requires Bun; run by just test interop"] +fn lite_varint_interop() { + let values = lite_values(); + for version in [lite::Version::Lite06, lite::Version::Lite07] { + let mut varints = Vec::new(); + for value in &values { + value.encode(&mut varints, version).unwrap(); + } + + let setup = lite::Setup { + hop: Some(crate::Hop::new(VarInt::MAX.into_inner()).unwrap()), + ..Default::default() + } + .encode_bytes(version) + .unwrap(); + + let datagram = lite::Datagram { + subscribe: (1 << 40) + 1, + sequence: 300, + timestamp: (1 << 50) + 5, + payload: bytes::Bytes::from_static(b"x"), + } + .encode_bytes(version) + .unwrap(); + + let group = lite_group(version); + + let input = serde_json::json!({ + "version": crate::Version::from(version).alpn(), + "values": values.len(), + "varints": varints, + "setup": setup.to_vec(), + "datagram": datagram.to_vec(), + "group": group, + }); + let echo: Echo = serde_json::from_slice(&bun("lite-varint.ts", input)).expect("JS returned its encodings"); + + let decoded: Vec = echo.values.iter().map(|v| v.parse().unwrap()).collect(); + assert_eq!(decoded, values, "{version}: JS decoded different values"); + assert_eq!(echo.varints, varints, "{version}: JS encoded the values differently"); + assert_eq!(echo.setup, setup, "{version}: SETUP"); + assert_eq!(echo.datagram, datagram, "{version}: datagram"); + assert_eq!(echo.group, group, "{version}: group"); + + match version { + lite::Version::Lite07 => { + let mut expected = vec![0xFF, 0x40, 0, 0, 0, 0, 0, 0, 0]; + expected.extend([0xFF; 9]); + assert_eq!(echo.beyond, expected, "{version}: JS's 64-bit encodings"); + for wire in echo.beyond.chunks(9) { + let err = VarInt::decode(&mut &wire[..], version).unwrap_err(); + assert!(matches!(err, crate::coding::DecodeError::BoundsExceeded), "{err:?}"); + } + } + _ => assert!(echo.beyond.is_empty(), "{version}: JS wrote a value past 2^62-1"), + } + } +} diff --git a/rs/moq-net/src/time.rs b/rs/moq-net/src/time.rs index bef0ba27b41..d73b688d4e9 100644 --- a/rs/moq-net/src/time.rs +++ b/rs/moq-net/src/time.rs @@ -66,6 +66,9 @@ struct State { now: Option, next: u64, timers: BTreeMap<(Instant, u64), Arc>>, + /// The driver's poll, woken when a timer armed outside it becomes the earliest, + /// so the driver's sleep never outlasts a deadline it did not see. + driver: kio::WaiterList, } impl Clock { @@ -100,6 +103,21 @@ impl Clock { } } + /// The latest supplied instant, or `None` before the first. + pub(crate) fn try_now(&self) -> Option { + let state = self.0.lock().unwrap(); + #[cfg(test)] + if state.automatic { + return Some(tokio::time::Instant::now().into_std()); + } + state.now + } + + /// Register the driver's poll to be woken by a new earliest timer. + pub(crate) fn register_driver(&self, waiter: &kio::Waiter) { + waiter.register(&mut self.0.lock().unwrap().driver); + } + pub(crate) fn timeout(&self) -> Option { self.0.lock().unwrap().timers.first_key_value().map(|((at, _), _)| *at) } @@ -160,6 +178,15 @@ impl crate::runtime::Timer for Timer { && state.now.is_none_or(|now| at > now) { state.timers.insert((at, self.id), self.waiters.clone()); + if state + .timers + .first_key_value() + .is_some_and(|(key, _)| *key == (at, self.id)) + { + let mut driver = state.driver.take(); + drop(state); + driver.wake(); + } } } fn poll(&mut self, waiter: &kio::Waiter) -> Poll<()> { diff --git a/rs/moq-net/tests/datagram.rs b/rs/moq-net/tests/datagram.rs index 4cc78b1297d..d974cc580e5 100644 --- a/rs/moq-net/tests/datagram.rs +++ b/rs/moq-net/tests/datagram.rs @@ -1,4 +1,4 @@ -//! MoQ Lite datagram delivery over the in-memory mock transport. +//! Datagram delivery over the in-memory mock transport, on moq-lite and moq-transport. //! //! Covers the whole receive path end to end: publisher encoding, the transport's //! datagram channel, the subscriber's receive loop and `route_datagram`, and @@ -9,7 +9,6 @@ mod support; use std::time::Duration; -use futures::FutureExt as _; use moq_net::{Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, MockPair, connect_mock}; @@ -110,53 +109,74 @@ async fn datagrams_reach_the_subscriber_in_order() { .expect("timed out"); } -/// MoQ Transport has no datagram mapping: groups still flow, inserted datagrams do not. +/// MoQ Transport carries a datagram as an OBJECT_DATAGRAM at object 0, so it arrives as a +/// datagram with its sequence, alongside the groups on streams. #[tokio::test] -async fn ietf_does_not_deliver_datagrams() { - tokio::time::timeout(TEST_TIMEOUT, async { - let publisher = produce_origin(1); - let consumer_origin = produce_origin(2); +async fn ietf_delivers_datagrams() { + for version in [ + "moq-transport-14", + "moq-transport-16", + "moq-transport-17", + "moq-transport-20", + ] { + tokio::time::timeout(TEST_TIMEOUT, ietf_delivers_datagrams_on(version)) + .await + .unwrap_or_else(|_| panic!("{version}: timed out")); + } +} - let broadcast = publisher.create_broadcast("bench").unwrap(); - let mut producer = broadcast.create_track("datagrams", None).unwrap(); - broadcast.announce(Default::default()).unwrap(); +async fn ietf_delivers_datagrams_on(version: &str) { + let publisher = produce_origin(1); + let consumer_origin = produce_origin(2); - let mut options = MockConnectOptions::new("moq-transport-19".parse::().unwrap()); - options.server_publish = Some(publisher.consume()); - options.client_subscribe = Some(consumer_origin.clone()); - let _pair = connect_mock(options).await; + let broadcast = publisher.create_broadcast("bench").unwrap(); + let mut producer = broadcast.create_track("datagrams", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); - let consumer = consumer_origin.consume(); - consumer.routed("bench").await.unwrap(); - let remote = consumer.request_broadcast("bench").await.unwrap(); - let mut subscriber = remote.track("datagrams").unwrap().subscribe(None).await.unwrap(); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(consumer_origin.clone()); + let _pair = connect_mock(options).await; - producer - .write_frame(Timestamp::from_millis(0).unwrap(), &b"before"[..]) - .unwrap(); - let before = subscriber.recv_group().await.unwrap().unwrap(); - assert_eq!(before.sequence, 0); + let consumer = consumer_origin.consume(); + consumer.routed("bench").await.unwrap(); + let remote = consumer.request_broadcast("bench").await.unwrap(); + let mut subscriber = remote.track("datagrams").unwrap().subscribe(None).await.unwrap(); - producer - .insert_datagram( - 0, - Timestamp::from_millis(7).unwrap(), - bytes::Bytes::from_static(PAYLOAD), - ) - .unwrap(); - producer - .write_frame(Timestamp::from_millis(1).unwrap(), &b"after"[..]) - .unwrap(); - let after = subscriber.recv_group().await.unwrap().unwrap(); - assert_eq!(after.sequence, 1); + // A group first, so the subscription's alias is bound before any datagram lands. + producer + .write_frame(Timestamp::from_millis(0).unwrap(), &b"before"[..]) + .unwrap(); + let mut before = subscriber.recv_group().await.unwrap().unwrap(); + assert_eq!(before.sequence, 0, "{version}"); + // Drafts without a track timescale stamp objects on arrival, datagrams included. + let stamped = before.next_frame().await.unwrap().unwrap().timestamp.value() == 0; - assert!( - subscriber.recv_datagram().now_or_never().is_none(), - "MoQ Transport must not map datagrams" + producer + .insert_datagram( + 5, + Timestamp::from_millis(7).unwrap(), + bytes::Bytes::from_static(PAYLOAD), + ) + .unwrap(); + let datagram = subscriber.recv_datagram().await.unwrap().unwrap(); + assert_eq!(datagram.sequence, 5, "{version}: the relay must not renumber"); + assert_eq!(&datagram.payload[..], PAYLOAD, "{version}"); + if stamped { + let expected = Timestamp::from_millis(7).unwrap(); + assert_eq!( + datagram.timestamp.convert(expected.scale()).unwrap(), + expected, + "{version}" ); - }) - .await - .expect("timed out"); + } + + // The group sequence continues past the datagram. + producer + .write_frame(Timestamp::from_millis(8).unwrap(), &b"after"[..]) + .unwrap(); + let after = subscriber.recv_group().await.unwrap().unwrap(); + assert_eq!(after.sequence, 6, "{version}"); } /// Explicit insert keeps the origin sequence on the lite wire, including a gap. diff --git a/rs/moq-net/tests/history_groups.rs b/rs/moq-net/tests/history_groups.rs index 6ca71e65678..5a463c8efed 100644 --- a/rs/moq-net/tests/history_groups.rs +++ b/rs/moq-net/tests/history_groups.rs @@ -171,3 +171,94 @@ async fn a_fresh_subscriber_receives_the_finished_older_group() { } assert!(failures.is_empty(), "{failures:#?}"); } + +/// Read known frame counts so the open live group never advances paused time to +/// the relay's linger deadline while waiting for a FIN that will not arrive. +async fn read_history(sub: &mut moq_net::track::Subscriber) { + let mut sequences = Vec::new(); + for _ in 0..2 { + let mut group = sub.recv_group().await.unwrap().unwrap(); + let frames = match group.sequence { + 5 => 3, + 6 => 2, + sequence => panic!("unexpected group {sequence}"), + }; + for _ in 0..frames { + assert!(group.read_frame().await.unwrap().is_some()); + } + sequences.push(group.sequence); + } + sequences.sort(); + assert_eq!(sequences, [5, 6]); +} + +#[tokio::test] +async fn a_late_subscriber_receives_the_relays_cached_history() { + tokio::time::pause(); + // Older drafts canonicalize group 0 to the live edge instead of replay. + let version: Version = "moq-lite-07-wip".parse().unwrap(); + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let track = broadcast + .create_track("history", Info::default().with_max_age(FOREVER)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + let relay = produce_origin(2); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(relay.clone()); + let upstream = connect_mock(options).await; + let first = produce_origin(3); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(relay.consume()); + options.client_subscribe = Some(first.clone()); + let first_pair = connect_mock(options).await; + let consumer = first.consume(); + consumer.routed("bcast").await.unwrap(); + let remote = consumer.request_broadcast("bcast").await.unwrap(); + let subscription = Subscription::default() + .with_max_age(FOREVER) + .with_start(Position::group(0)); + let first_subscription = subscription.clone(); + let first_reader = tokio::spawn(async move { + let mut sub = remote + .track("history") + .unwrap() + .subscribe(first_subscription) + .await + .unwrap(); + read_history(&mut sub).await; + sub + }); + track.demand().used().await.unwrap(); + upstream.server_transport.hold_unis(); + let mut old = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + for _ in 0..3 { + old.write_frame(Timestamp::now(), &b"old"[..]).unwrap(); + } + old.finish().unwrap(); + let mut live = track.create_group(moq_net::group::Info { sequence: 6 }).unwrap(); + for _ in 0..2 { + live.write_frame(Timestamp::now(), &b"live"[..]).unwrap(); + } + // Both streams open before paused time advances; 10ms stays below linger. + tokio::time::sleep(Duration::from_millis(10)).await; + upstream.server_transport.release_unis_reversed(); + let first_sub = tokio::time::timeout(TIMEOUT, first_reader) + .await + .expect("first subscriber history") + .unwrap(); + let late = produce_origin(4); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(relay.consume()); + options.client_subscribe = Some(late.clone()); + let late_pair = connect_mock(options).await; + let consumer = late.consume(); + consumer.routed("bcast").await.unwrap(); + let remote = consumer.request_broadcast("bcast").await.unwrap(); + let mut late_sub = remote.track("history").unwrap().subscribe(subscription).await.unwrap(); + tokio::time::timeout(TIMEOUT, read_history(&mut late_sub)) + .await + .unwrap_or_else(|_| panic!("{version}: late subscriber history")); + drop((first_sub, late_sub, first_pair, late_pair, upstream, live)); +} diff --git a/rs/moq-net/tests/legacy_reconnect.rs b/rs/moq-net/tests/legacy_reconnect.rs new file mode 100644 index 00000000000..143f902f1e1 --- /dev/null +++ b/rs/moq-net/tests/legacy_reconnect.rs @@ -0,0 +1,81 @@ +//! A publisher on a wire with no hop ids, reconnecting through a relay, is a new source +//! downstream. +//! +//! moq-transport without the Cluster extension names no publisher, so the relay it +//! connects to stamps each connection with a random Hop ID of its own. A reconnect is a +//! new connection and so a new first hop, which a downstream relay reads as a new +//! source rather than splicing it onto the old one. + +mod support; + +use std::time::Duration; + +use moq_net::{Hop, Version, announce, origin}; +use support::harness::{MockConnectOptions, MockPair, connect_mock, peer}; + +const TEST_TIMEOUT: Duration = Duration::from_secs(10); +const PATH: &str = "room/cam"; + +fn produce_origin(hop: u64) -> origin::Producer { + let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + tokio::spawn(support::harness::run(driver)); + producer +} + +/// Connect `publisher` to `relay` over draft-14, which carries no hop ids. +async fn connect_legacy(publisher: &origin::Producer, relay: &origin::Producer) -> MockPair { + let mut options = MockConnectOptions::new("moq-transport-14".parse::().unwrap()); + options.client_publish = Some(publisher.consume()); + options.server_subscribe = Some(relay.clone()); + connect_mock(options).await +} + +/// The first hop of the next active update for [`PATH`]. A withdrawal in between is +/// skipped: whether the relay saw the new connection before the old one dropped is a +/// race, and either way the path comes back. +async fn next_first_hop(announced: &mut announce::Consumer) -> Hop { + loop { + let update = match announced.next().await.expect("announce cursor ended") { + announce::Event::Start(update) | announce::Event::Update(update) => update, + announce::Event::End(_) | announce::Event::Live => continue, + }; + if update.prefix.as_str() != PATH { + continue; + } + return *update.route.hops.iter().next().expect("a route names its first hop"); + } +} + +#[tokio::test] +async fn a_legacy_reconnect_is_a_new_first_hop_downstream() { + for mesh in ["moq-lite-06", "moq-transport-17"] { + tokio::time::timeout(TEST_TIMEOUT, async { + let publisher = produce_origin(9); + let relay = produce_origin(1); + let downstream = produce_origin(2); + let _mesh = peer(mesh.parse::().unwrap(), &relay, &downstream).await; + let mut announced = downstream.consume().announced(); + + let broadcast = publisher.create_broadcast(PATH).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let first = connect_legacy(&publisher, &relay).await; + let before = next_first_hop(&mut announced).await; + assert_ne!(before, Hop::UNKNOWN, "{mesh}: the relay stamps an unnamed publisher"); + assert_ne!(before, Hop::new(9).unwrap(), "{mesh}: draft-14 never carried the id"); + + // The publisher reconnects: the same content, but nothing on the wire says so. + let second = connect_legacy(&publisher, &relay).await; + drop(first); + let mut after = next_first_hop(&mut announced).await; + while after == before { + after = next_first_hop(&mut announced).await; + } + assert_ne!(after, Hop::UNKNOWN, "{mesh}: the relay stamps the new connection too"); + + drop(second); + }) + .await + .expect("test timed out"); + } +} diff --git a/rs/moq-net/tests/mesh_withdraw.rs b/rs/moq-net/tests/mesh_withdraw.rs index 0f3ec7bb8d4..92ba86756f4 100644 --- a/rs/moq-net/tests/mesh_withdraw.rs +++ b/rs/moq-net/tests/mesh_withdraw.rs @@ -9,8 +9,10 @@ mod support; use std::{collections::HashMap, time::Duration}; +use tokio::sync::mpsc; + use moq_net::{Hop, Version, announce, broadcast, origin}; -use support::harness::{MockConnectOptions, MockPair, connect_mock}; +use support::harness::{MockPair, peer, peer_with_latency}; fn produce_origin(hop: u64) -> origin::Producer { let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); @@ -18,18 +20,6 @@ fn produce_origin(hop: u64) -> origin::Producer { producer } -/// Peer two relays the way `moq-relay`'s cluster does: one session, both directions. -async fn peer(version: Version, a: &origin::Producer, b: &origin::Producer) -> MockPair { - let a = a.clone().peer(); - let b = b.clone().peer(); - let mut options = MockConnectOptions::new(version); - options.client_publish = Some(a.consume().with_hidden(true)); - options.client_subscribe = Some(a); - options.server_publish = Some(b.consume().with_hidden(true)); - options.server_subscribe = Some(b); - connect_mock(options).await -} - /// The kind of an [`announce::Event`] for a prefix. #[derive(Clone, Copy, Debug, PartialEq, Eq)] enum Kind { @@ -38,27 +28,42 @@ enum Kind { End, } -/// Every update per prefix until the cursor goes quiet. Time is paused, so the +/// Every update per prefix until the watcher goes quiet. Time is paused, so the /// timeout fires only once every task is idle. -async fn drain(announced: &mut announce::Consumer) -> HashMap> { +async fn drain(watched: &mut mpsc::UnboundedReceiver<(String, Kind)>) -> HashMap> { let mut updates = HashMap::>::new(); - while let Ok(Some(event)) = tokio::time::timeout(Duration::from_secs(1), announced.next()).await { - let (kind, announce) = match event { - announce::Event::Start(announce) => (Kind::Start, announce), - announce::Event::Update(announce) => (Kind::Update, announce), - announce::Event::End(announce) => (Kind::End, announce), - announce::Event::Live => continue, - }; - updates.entry(announce.prefix.to_string()).or_default().push(kind); + while let Ok(Some((prefix, kind))) = tokio::time::timeout(Duration::from_secs(1), watched.recv()).await { + updates.entry(prefix).or_default().push(kind); } updates } +/// Watch `announced` from its own task, the way a session's announce writer does: +/// it runs when woken, between the relays' own tasks, rather than only once the +/// test task is polled again, which would coalesce every intermediate update. +fn watch(mut announced: announce::Consumer) -> mpsc::UnboundedReceiver<(String, Kind)> { + let (tx, rx) = mpsc::unbounded_channel(); + tokio::spawn(async move { + while let Some(event) = announced.next().await { + let (kind, announce) = match event { + announce::Event::Start(announce) => (Kind::Start, announce), + announce::Event::Update(announce) => (Kind::Update, announce), + announce::Event::End(announce) => (Kind::End, announce), + announce::Event::Live => continue, + }; + if tx.send((announce.prefix.to_string(), kind)).is_err() { + break; + } + } + }); + rx +} + /// `n` relays meshed over `edges`, watched from the last one. struct Mesh { nodes: Vec, _pairs: Vec, - announced: announce::Consumer, + watched: mpsc::UnboundedReceiver<(String, Kind)>, } impl Mesh { @@ -69,11 +74,11 @@ impl Mesh { for &(a, b) in edges { pairs.push(peer(version, &nodes[a], &nodes[b]).await); } - let announced = nodes.last().unwrap().consume().announced(); + let watched = watch(nodes.last().unwrap().consume().announced()); Self { nodes, _pairs: pairs, - announced, + watched, } } @@ -90,7 +95,7 @@ impl Mesh { broadcast }) .collect(); - let updates = drain(&mut self.announced).await; + let updates = drain(&mut self.watched).await; assert_eq!(updates.len(), count); for (prefix, kinds) in updates { assert_eq!(kinds[0], Kind::Start, "{prefix}: {kinds:?}"); @@ -126,7 +131,7 @@ async fn full_mesh_withdraw_retracts_once(version: &str) { let mut mesh = Mesh::new(version, 8, &full_mesh(8)).await; let broadcasts = mesh.publish(100, 0).await; drop(broadcasts); - let updates = drain(&mut mesh.announced).await; + let updates = drain(&mut mesh.watched).await; assert_eq!(updates.len(), 100); for (prefix, kinds) in updates { assert_eq!(kinds, [Kind::End], "{prefix}"); @@ -144,10 +149,84 @@ async fn partial_mesh_withdraw_then_republish() { let mut mesh = Mesh::new("moq-lite-06", 12, &ring_with_chords(12)).await; let broadcasts = mesh.publish(100, 0).await; drop(broadcasts); - let updates = drain(&mut mesh.announced).await; + let updates = drain(&mut mesh.watched).await; assert_eq!(updates.len(), 100); for (prefix, kinds) in updates { assert_eq!(kinds.last(), Some(&Kind::End), "{prefix}: {kinds:?}"); } let _broadcasts = mesh.publish(100, 5).await; } + +/// A 34-relay partial mesh: moq.pro's production graph on 2026-09-30, where +/// relays in neighboring PoPs peer and most reach a publisher's relay through +/// others. +#[rustfmt::skip] +const PRODUCTION: &[(usize, usize)] = &[ + (0, 20), (0, 22), (0, 29), (1, 3), (1, 12), (1, 14), (1, 21), (2, 20), (2, 26), (2, 32), (3, 8), + (3, 11), (3, 15), (3, 16), (3, 17), (3, 18), (3, 21), (3, 22), (3, 23), (3, 24), (3, 29), (3, 30), + (3, 31), (4, 7), (4, 20), (4, 22), (4, 25), (4, 29), (5, 20), (5, 27), (5, 33), (6, 23), (6, 24), + (6, 30), (6, 31), (7, 22), (7, 25), (7, 29), (8, 15), (8, 17), (8, 21), (8, 23), (8, 30), (9, 19), + (9, 22), (9, 23), (9, 28), (9, 29), (9, 30), (10, 19), (10, 20), (10, 22), (10, 23), (10, 26), + (10, 27), (10, 28), (10, 29), (10, 30), (10, 32), (10, 33), (11, 15), (11, 16), (11, 21), + (12, 14), (12, 27), (12, 33), (13, 14), (13, 27), (13, 33), (14, 26), (14, 27), (14, 32), + (14, 33), (15, 21), (16, 18), (16, 21), (17, 21), (17, 24), (17, 31), (18, 21), (18, 22), + (18, 23), (18, 24), (18, 29), (18, 30), (18, 31), (19, 22), (19, 23), (19, 26), (19, 28), + (19, 29), (19, 30), (19, 32), (20, 22), (20, 26), (20, 27), (20, 29), (20, 32), (20, 33), + (21, 22), (21, 23), (21, 24), (21, 29), (21, 30), (21, 31), (22, 23), (22, 24), (22, 25), + (22, 26), (22, 27), (22, 28), (22, 29), (22, 30), (22, 31), (22, 32), (22, 33), (23, 24), + (23, 28), (23, 29), (23, 30), (23, 31), (24, 29), (24, 30), (24, 31), (25, 29), (26, 27), + (26, 28), (26, 29), (26, 32), (26, 33), (27, 29), (27, 32), (27, 33), (28, 29), (28, 30), + (28, 32), (29, 30), (29, 31), (29, 32), (29, 33), (30, 31), (32, 33), +]; + +/// One-way latency in ms for each [`PRODUCTION`] link, from the great-circle +/// distance between its PoPs at 200 km/ms over a path 1.5 times as long, plus 1 ms. +#[rustfmt::skip] +const PRODUCTION_LATENCY_MS: &[u64] = &[ + 10, 7, 7, 50, 30, 51, 50, 9, 13, 13, 5, 4, 6, 8, 3, 4, 1, 50, 6, 4, 50, 6, 4, 50, 63, 58, 50, 58, + 16, 5, 5, 10, 10, 10, 10, 12, 1, 12, 6, 3, 5, 8, 8, 5, 4, 43, 5, 4, 43, 6, 11, 8, 49, 22, 23, 6, + 8, 49, 22, 23, 3, 5, 4, 41, 103, 103, 60, 91, 91, 59, 64, 59, 64, 6, 9, 8, 3, 6, 6, 4, 48, 4, 3, + 48, 4, 3, 5, 44, 26, 1, 5, 44, 26, 15, 21, 18, 15, 21, 18, 50, 6, 4, 50, 6, 4, 45, 47, 12, 29, 30, + 5, 1, 45, 47, 29, 30, 2, 44, 45, 1, 2, 47, 2, 1, 12, 9, 26, 29, 1, 9, 30, 9, 1, 5, 44, 26, 45, 47, + 29, 30, 2, 9, +]; + +/// One withdrawal on a partial mesh retracts everywhere once. A relay two hops +/// from the publisher's hears only that its neighbor withdrew, and must not +/// fall back to, and re-advertise, another path derived from the same +/// announcement. Holding route updates (`origin::Config::update_hold`) lets the +/// withdrawal remove those paths first; with link latency and no hold, each +/// withdrawal here costs tens of thousands of announcements. +#[tokio::test(start_paused = true)] +async fn partial_mesh_withdraw_retracts_once() { + let version: Version = "moq-lite-06".parse().unwrap(); + let nodes: Vec<_> = (1..=34).map(produce_origin).collect(); + let mut pairs = Vec::new(); + for (&(a, b), &ms) in PRODUCTION.iter().zip(PRODUCTION_LATENCY_MS) { + pairs.push(peer_with_latency(version, &nodes[a], &nodes[b], Duration::from_millis(ms)).await); + } + let mut watched: Vec<_> = nodes.iter().map(|node| watch(node.consume().announced())).collect(); + + for publisher in [5, 13, 22, 26, 32] { + let broadcast = nodes[publisher].create_broadcast(format!("room/{publisher}")).unwrap(); + broadcast.announce(Default::default()).unwrap(); + for (relay, watched) in watched.iter_mut().enumerate() { + let updates = drain(watched).await; + assert!( + updates.values().all(|kinds| kinds.last() != Some(&Kind::End)), + "relay {relay}: {updates:?}" + ); + } + + drop(broadcast); + let mut hunted = Vec::new(); + for (relay, watched) in watched.iter_mut().enumerate() { + let updates = drain(watched).await; + let kinds = &updates[&format!("room/{publisher}")]; + if kinds != &[Kind::End] { + hunted.push((relay, kinds.clone())); + } + } + assert!(hunted.is_empty(), "publisher {publisher}: {hunted:?}"); + } +} diff --git a/rs/moq-net/tests/support/harness.rs b/rs/moq-net/tests/support/harness.rs index 4cd2cf254f0..3b8b5683f2b 100644 --- a/rs/moq-net/tests/support/harness.rs +++ b/rs/moq-net/tests/support/harness.rs @@ -29,6 +29,8 @@ pub struct MockConnectOptions { pub server_publish: Option, /// Origin the server inserts remote broadcasts into. pub server_subscribe: Option, + /// One-way delay for stream data in each direction. + pub latency: std::time::Duration, } impl MockConnectOptions { @@ -40,6 +42,7 @@ impl MockConnectOptions { client_subscribe: None, server_publish: None, server_subscribe: None, + latency: std::time::Duration::ZERO, } } } @@ -67,6 +70,7 @@ pub struct MockPair { pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { let protocol = opts.version.alpn(); let (client_transport, server_transport) = create_mock_session_pair(Some(protocol)); + client_transport.set_latency(opts.latency); let transports = (client_transport.clone(), server_transport.clone()); let mut client = Client::new().with_versions(opts.version.into()); @@ -114,3 +118,26 @@ pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { server_transport: transports.1, } } + +/// Peer two relays the way `moq-relay`'s cluster does: one session, both directions. +pub async fn peer(version: Version, a: &origin::Producer, b: &origin::Producer) -> MockPair { + peer_with_latency(version, a, b, std::time::Duration::ZERO).await +} + +/// [`peer`] over a link with a one-way `latency`. +pub async fn peer_with_latency( + version: Version, + a: &origin::Producer, + b: &origin::Producer, + latency: std::time::Duration, +) -> MockPair { + let a = a.clone().peer(); + let b = b.clone().peer(); + let mut options = MockConnectOptions::new(version); + options.client_publish = Some(a.consume().with_hidden(true)); + options.client_subscribe = Some(a); + options.server_publish = Some(b.consume().with_hidden(true)); + options.server_subscribe = Some(b); + options.latency = latency; + connect_mock(options).await +} diff --git a/rs/moq-net/tests/support/mock.rs b/rs/moq-net/tests/support/mock.rs index 6b5fa06d06a..bc7039d4bb0 100644 --- a/rs/moq-net/tests/support/mock.rs +++ b/rs/moq-net/tests/support/mock.rs @@ -13,11 +13,14 @@ //! its earlier data is read. use std::{ + future::Future, + pin::Pin, sync::{ Arc, Mutex, atomic::{AtomicBool, AtomicUsize, Ordering}, }, task::{Context, Poll}, + time::Duration, }; use bytes::Bytes; @@ -113,9 +116,12 @@ impl ClosedSignal { } } +/// A chunk in flight: readable by the peer once the link latency has passed. +type Flight = (tokio::time::Instant, StreamChunk); + /// A mock send stream backed by a queue to the peer's reader. pub struct MockSendStream { - tx: Option>, + tx: Option>, closed: Arc, park: kio::Park, /// Acknowledge the FIN as soon as it is sent, for a stream the peer's transport holds @@ -133,7 +139,8 @@ impl MockSendStream { return Err(err); } let tx = self.tx.as_ref().ok_or_else(MockError::closed)?; - tx.try_push(chunk).map_err(|_| MockError::closed()) + let arrival = tokio::time::Instant::now() + self.conn.latency(); + tx.try_push((arrival, chunk)).map_err(|_| MockError::closed()) } } @@ -197,7 +204,11 @@ impl Drop for MockSendStream { /// A mock receive stream backed by a queue from the peer's writer. pub struct MockRecvStream { - rx: kio::Queue, + rx: kio::Queue, + /// The next chunk, popped but still crossing the link. + flight: Option, + /// Wakes the reader when `flight` lands. + landing: Option>>, /// Buffered bytes from a chunk that was partially consumed. buf: Bytes, /// Whether we hit FIN or reset. @@ -212,15 +223,26 @@ impl MockRecvStream { /// Pop the next chunk, mapping queue closure to an implicit FIN. Once everything /// sent before a CONNECTION_CLOSE is read, an unfinished stream fails with it. fn poll_chunk(&mut self, cx: &mut Context<'_>) -> Poll> { - let waiter = self.park.hold(cx); - // Register on the close first so one racing the pop still wakes this poll. - let closed = self.conn.close_state.poll(waiter, is_set).is_ready(); - match self.rx.poll_pop(waiter) { - Poll::Ready(Ok(chunk)) => Poll::Ready(Some(chunk)), - Poll::Ready(Err(_)) => Poll::Ready(None), - Poll::Pending if closed => Poll::Ready(Some(StreamChunk::Closed)), - Poll::Pending => Poll::Pending, + if self.flight.is_none() { + let waiter = self.park.hold(cx); + // Register on the close first so one racing the pop still wakes this poll. + let closed = self.conn.close_state.poll(waiter, is_set).is_ready(); + match self.rx.poll_pop(waiter) { + Poll::Ready(Ok(flight)) => self.flight = Some(flight), + Poll::Ready(Err(_)) => return Poll::Ready(None), + Poll::Pending if closed => return Poll::Ready(Some(StreamChunk::Closed)), + Poll::Pending => return Poll::Pending, + } + } + let (arrival, _) = self.flight.as_ref().expect("flight set above"); + if *arrival > tokio::time::Instant::now() { + let landing = self + .landing + .get_or_insert_with(|| Box::pin(tokio::time::sleep_until(*arrival))); + landing.as_mut().reset(*arrival); + std::task::ready!(landing.as_mut().poll(cx)); } + Poll::Ready(self.flight.take().map(|(_, chunk)| chunk)) } } @@ -319,6 +341,8 @@ fn new_stream_pair(conn: &Arc) -> (MockSendStream, MockRecvStre }; let recv = MockRecvStream { rx: queue, + flight: None, + landing: None, buf: Bytes::new(), done: false, closed, @@ -341,9 +365,15 @@ struct ConnectionState { /// Set once by whichever side closes first. /// Setting it wakes both sides. close_state: kio::Shared>, + /// One-way delay for stream data in each direction. Zero by default. + latency: Mutex, } impl ConnectionState { + fn latency(&self) -> Duration { + *self.latency.lock().unwrap() + } + /// The close every stream and accept fails with, once the connection closed. fn error(&self) -> Option { self.close_state @@ -373,6 +403,10 @@ struct SessionSide { conn: Arc, /// Uni streams this side opened that the peer has not accepted yet, while held. held: Mutex>>, + /// Whether the peer has withheld uni stream credit, parking every open. + withheld: Mutex, + /// Whether the datagrams this side sends are lost. + lossy: Mutex, } /// An in-memory mock WebTransport session. @@ -389,6 +423,7 @@ pub struct MockSession { accept_bi: kio::Park, datagram: kio::Park, closed: kio::Park, + open_uni: kio::Park, } impl poll::Session for MockSession { @@ -436,7 +471,14 @@ impl poll::Session for MockSession { } } - fn poll_open_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { + fn poll_open_uni(&mut self, cx: &mut Context<'_>) -> Poll> { + if *self.side.withheld.lock().unwrap() { + drop(std::task::ready!( + self.side.conn.close_state.poll(self.open_uni.hold(cx), is_set) + )); + return Poll::Ready(Err(self.close_error())); + } + let (mut our_send, peer_recv) = new_stream_pair(&self.side.conn); if let Some(held) = self.side.held.lock().unwrap().as_mut() { @@ -453,6 +495,9 @@ impl poll::Session for MockSession { } fn poll_send_datagram(&mut self, _cx: &mut Context<'_>, payload: &[u8]) -> Poll> { + if *self.side.lossy.lock().unwrap() { + return Poll::Ready(Ok(())); + } match self.side.peer_datagrams.try_push(Bytes::copy_from_slice(payload)) { Ok(()) => Poll::Ready(Ok(())), Err(_) => Poll::Ready(Err(self.close_error())), @@ -549,6 +594,24 @@ impl MockSession { pub fn drop_unis(&self) { self.side.held.lock().unwrap().take(); } + + /// Park every uni stream this side opens from now on, like a peer that has granted + /// no more stream credit. + pub fn withhold_unis(&self) { + *self.side.withheld.lock().unwrap() = true; + } + + /// Lose every datagram this side sends from now on. + pub fn lose_datagrams(&self) { + *self.side.lossy.lock().unwrap() = true; + } + + /// Delay stream data sent from now on by `latency` in each direction, keeping + /// each stream in order. Measured on tokio's clock, so paused-time tests advance + /// through it without sleeping. + pub fn set_latency(&self, latency: Duration) { + *self.side.conn.latency.lock().unwrap() = latency; + } } impl MockSession { @@ -586,6 +649,8 @@ pub fn create_mock_session_pair(protocol: Option<&'static str>) -> (MockSession, protocol, conn: conn.clone(), held: Mutex::default(), + withheld: Mutex::default(), + lossy: Mutex::default(), }); let server_side = Arc::new(SessionSide { @@ -598,6 +663,8 @@ pub fn create_mock_session_pair(protocol: Option<&'static str>) -> (MockSession, protocol, conn, held: Mutex::default(), + withheld: Mutex::default(), + lossy: Mutex::default(), }); let new = |side| MockSession { @@ -606,6 +673,7 @@ pub fn create_mock_session_pair(protocol: Option<&'static str>) -> (MockSession, accept_bi: kio::Park::default(), datagram: kio::Park::default(), closed: kio::Park::default(), + open_uni: kio::Park::default(), }; (new(client_side), new(server_side)) diff --git a/rs/moq-net/tests/track_info_cancel.rs b/rs/moq-net/tests/track_info_cancel.rs new file mode 100644 index 00000000000..1f8be9be935 --- /dev/null +++ b/rs/moq-net/tests/track_info_cancel.rs @@ -0,0 +1,66 @@ +//! A track request nobody wants anymore is cancelled all the way to the publisher. +//! +//! Until a publisher answers TRACK_INFO, each relay on the path holds a task, a TRACK +//! stream, and the track for the request. When the reader gives up, every hop must +//! let go; otherwise a peer that never answers (one still hunting for a route, or +//! with its stream credit spent) pins them for good, and a relay retrying across +//! routes accumulates them until it runs out of memory. + +mod support; + +use std::time::Duration; + +use moq_net::{Hop, Version, origin}; +use support::harness::peer; + +fn produce_origin(hop: u64) -> origin::Producer { + let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + tokio::spawn(support::harness::run(driver)); + producer +} + +/// `relays` relays between the publisher and the reader. +async fn abandoned_request_reaches_the_publisher(version: &str, relays: u64) { + let version: Version = version.parse().unwrap(); + let nodes: Vec<_> = (1..=relays + 1).map(produce_origin).collect(); + let mut _pairs = Vec::new(); + for pair in nodes.windows(2) { + _pairs.push(peer(version, &pair[0], &pair[1]).await); + } + + let broadcast = nodes[0].create_broadcast("room").unwrap(); + let mut dynamic = broadcast.dynamic(); + broadcast.announce(Default::default()).unwrap(); + tokio::time::sleep(Duration::from_secs(1)).await; + + let consumer = nodes[relays as usize] + .consume() + .request_broadcast("room") + .await + .unwrap(); + let mut waiting = Box::pin(consumer.track("video").unwrap().subscribe(None)); + let request = tokio::select! { + request = dynamic.requested_track() => request.expect("the request reaches the publisher"), + _ = &mut waiting => panic!("nothing answered the track"), + }; + + // The publisher never answers; the reader gives up. + drop(waiting); + tokio::time::timeout(Duration::from_secs(5), kio::wait(|waiter| request.poll_unused(waiter))) + .await + .unwrap_or_else(|_| panic!("{version:?} over {relays} relays: the publisher's request is still wanted")); +} + +#[tokio::test(start_paused = true)] +async fn abandoned_request_reaches_the_publisher_lite05() { + for relays in [1, 2] { + abandoned_request_reaches_the_publisher("moq-lite-05", relays).await; + } +} + +#[tokio::test(start_paused = true)] +async fn abandoned_request_reaches_the_publisher_lite06() { + for relays in [1, 2] { + abandoned_request_reaches_the_publisher("moq-lite-06", relays).await; + } +} diff --git a/rs/moq-net/tests/track_tail.rs b/rs/moq-net/tests/track_tail.rs index c62d4917403..b0f72428534 100644 --- a/rs/moq-net/tests/track_tail.rs +++ b/rs/moq-net/tests/track_tail.rs @@ -56,12 +56,22 @@ struct Outcome { elapsed: Duration, } -/// Publish a group below the declared end (or none for an empty track), hold its stream -/// back until the subscription ends, then deliver or lose it. -async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { +/// A publisher and subscriber over the mock, with the subscriber holding `bcast`. +struct Pair { + pair: support::harness::MockPair, + track: moq_net::track::Producer, + remote: moq_net::broadcast::Consumer, + _keep: ( + moq_net::broadcast::Producer, + moq_net::origin::Producer, + moq_net::origin::Producer, + ), +} + +async fn connect(version: &str) -> Pair { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let mut track = broadcast.create_track("video", None).unwrap(); + let track = broadcast.create_track("video", None).unwrap(); broadcast.announce(Default::default()).unwrap(); let subscriber = produce_origin(2); @@ -80,6 +90,24 @@ async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { .expect("resolve timeout") .expect("broadcast resolves"); + Pair { + pair, + track, + remote, + _keep: (broadcast, publisher, subscriber), + } +} + +/// Publish a group below the declared end (or none for an empty track), hold its stream +/// back until the subscription ends, then deliver or lose it. +async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { + let Pair { + pair, + mut track, + remote, + _keep, + } = connect(version).await; + let reader = tokio::spawn(async move { let subscription = moq_net::track::Subscription::default().with_start(moq_net::track::Position::group(0)); let mut sub = remote @@ -140,7 +168,7 @@ async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { .await .expect("the subscription never ended") .expect("reader panicked"); - drop((pair, broadcast, publisher, subscriber)); + drop((pair, _keep)); Outcome { frames, err, @@ -214,3 +242,128 @@ async fn lite07_zero_streams_end_without_the_grace() { assert!(outcome.frames.is_empty()); assert!(outcome.elapsed < GRACE / 10, "ended after {:?}", outcome.elapsed); } + +/// IETF drafts over the control stream adapter (14), on their own streams (17), and with +/// subscription fills (20+). +const IETF: &[&str] = &[ + "moq-transport-14", + "moq-transport-17", + "moq-transport-20", + "moq-transport-22", +]; + +/// A subscriber that leaves while END_OF_TRACK waits for stream credit ends the publisher's +/// request, instead of parking it until credit that may never come. +#[tokio::test] +async fn ietf_leaving_cancels_a_blocked_end_of_track() { + tokio::time::pause(); + for version in IETF { + let Pair { + pair, + track, + remote, + _keep, + } = connect(version).await; + + let subscription = moq_net::track::Subscription::default().with_start(moq_net::track::Position::group(0)); + let mut sub = remote + .track("video") + .unwrap() + .subscribe(subscription) + .await + .expect("subscribe"); + tokio::time::timeout(TIMEOUT, track.demand().used()) + .await + .expect("no subscriber appeared") + .unwrap(); + + let mut group = track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, PAYLOAD).unwrap(); + group.finish().unwrap(); + let mut group = tokio::time::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .unwrap() + .expect("a group"); + while group.read_frame().await.unwrap().is_some() {} + + // Out of stream credit, so the marker cannot open. + pair.server_transport.withhold_unis(); + track.finish().unwrap(); + tokio::time::sleep(GRACE / 10).await; + assert!( + track.subscription().is_some(), + "{version}: the publisher is still ending the request" + ); + + // The request task holds the publisher's subscription until it ends. + drop((group, sub)); + tokio::time::timeout(TIMEOUT, async { + while track.subscription().is_some() { + tokio::time::sleep(GRACE / 100).await; + } + }) + .await + .unwrap_or_else(|_| panic!("{version}: the publisher's request never ended")); + drop((pair, _keep)); + } +} + +/// A lost datagram is not owed. Nothing tells the subscriber its sequence was a datagram, so +/// on the drafts that account for the owed range its hole keeps the subscription routable for +/// the grace, like a stream reset before its header. A reader never waits on it: the track +/// ends for readers once the live edge reaches the declared end. +#[tokio::test] +async fn a_lost_datagram_never_delays_the_end() { + tokio::time::pause(); + for version in ["moq-lite-05", "moq-lite-07-wip"] { + let Pair { + pair, + mut track, + remote, + _keep, + } = connect(version).await; + + let reader = tokio::spawn(async move { + let subscription = moq_net::track::Subscription::default().with_start(moq_net::track::Position::group(0)); + let mut sub = remote + .track("video") + .unwrap() + .subscribe(subscription) + .await + .expect("subscribe"); + let mut groups = Vec::new(); + while let Some(group) = sub.recv_group().await.expect("track aborted") { + groups.push(group.sequence); + } + (groups, tokio::time::Instant::now()) + }); + tokio::time::timeout(TIMEOUT, track.demand().used()) + .await + .expect("no subscriber appeared") + .unwrap(); + + for datagram in [false, true, false] { + if datagram { + pair.server_transport.lose_datagrams(); + track.append_datagram(Timestamp::ZERO, PAYLOAD).unwrap(); + } else { + let mut group = track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, PAYLOAD).unwrap(); + group.finish().unwrap(); + } + tokio::time::sleep(GRACE / 100).await; + } + let finished = tokio::time::Instant::now(); + track.finish().unwrap(); + + let (groups, ended) = tokio::time::timeout(TIMEOUT, reader) + .await + .expect("the subscription never ended") + .expect("reader panicked"); + assert_eq!(groups, [0, 2], "{version}"); + let elapsed = ended - finished; + assert!(elapsed < GRACE / 10, "{version}: ended after {elapsed:?}"); + drop((pair, _keep)); + } +} diff --git a/rs/moq-pattern/CHANGELOG.md b/rs/moq-pattern/CHANGELOG.md index 56c0b699cd8..d1dc2a02d59 100644 --- a/rs/moq-pattern/CHANGELOG.md +++ b/rs/moq-pattern/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.2](https://github.com/moq-dev/moq/compare/moq-pattern-v0.1.1...moq-pattern-v0.1.2) - 2026-09-30 + +### Fixed + +- *(pattern)* JS subtree of a max-depth path is the path itself ([#4360](https://github.com/moq-dev/moq/pull/4360)) + +### Other + +- *(quest)* drop suffix-based routing from the plans ([#4382](https://github.com/moq-dev/moq/pull/4382)) + ## [0.1.1](https://github.com/moq-dev/moq/compare/moq-pattern-v0.1.0...moq-pattern-v0.1.1) - 2026-09-27 ### Fixed diff --git a/rs/moq-pattern/Cargo.toml b/rs/moq-pattern/Cargo.toml index 6a3d8af3ba2..bd2f54d7d02 100644 --- a/rs/moq-pattern/Cargo.toml +++ b/rs/moq-pattern/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.1" +version = "0.1.2" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-relay/CHANGELOG.md b/rs/moq-relay/CHANGELOG.md index 01140559d4d..fc16d19fd0c 100644 --- a/rs/moq-relay/CHANGELOG.md +++ b/rs/moq-relay/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.16.0](https://github.com/moq-dev/moq/compare/moq-relay-v0.15.8...moq-relay-v0.16.0) - 2026-09-30 + +### Added + +- *(net)* relays stamp an unknown publisher with a per-connection hop +- *(net)* read a subtree through an origin mount ([#4271](https://github.com/moq-dev/moq/pull/4271)) + +### Fixed + +- *(relay)* pass packaged service config positionally ([#4469](https://github.com/moq-dev/moq/pull/4469)) +- *(sock)* resolve an ephemeral reuseport group's port with a plain bind ([#4409](https://github.com/moq-dev/moq/pull/4409)) +- *(auth)* make grant expiry exact, dropping the clock-skew grace ([#4368](https://github.com/moq-dev/moq/pull/4368)) +- *(cli)* refuse a client CA under --auth-public on a listener ([#4364](https://github.com/moq-dev/moq/pull/4364)) +- *(net)* refuse chained and wildcard origin mounts in any order ([#4362](https://github.com/moq-dev/moq/pull/4362)) +- *(auth)* [**breaking**] restore 0.14 auth parity ([#4319](https://github.com/moq-dev/moq/pull/4319)) + +### Other + +- one rpm repo command that works on DNF4 and DNF5 ([#4567](https://github.com/moq-dev/moq/pull/4567)) +- Merge remote-tracking branch 'origin/main' into quest/m1/cluster-publisher-in-place +- prove stopped relays and worker groups closed their sockets instead of racing a rebind ([#4408](https://github.com/moq-dev/moq/pull/4408)) + ## [0.15.8](https://github.com/moq-dev/moq/compare/moq-relay-v0.15.7...moq-relay-v0.15.8) - 2026-09-27 ### Added diff --git a/rs/moq-relay/Cargo.toml b/rs/moq-relay/Cargo.toml index 14b5c5c5675..2f77c34c965 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.15.8" +version = "0.16.0" 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-relay/README.md b/rs/moq-relay/README.md index 888b10a8d71..88edcfac41d 100644 --- a/rs/moq-relay/README.md +++ b/rs/moq-relay/README.md @@ -26,7 +26,7 @@ walkthrough. ### Fedora / RHEL / Rocky / AlmaLinux ```bash -sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo +sudo curl -fsSL https://rpm.moq.dev/moq.repo -o /etc/yum.repos.d/moq.repo sudo dnf install moq-relay ``` @@ -61,9 +61,10 @@ HTTPS is currently not supported. Relays can be joined together to proxy announcements and subscriptions. A viewer talks to whichever relay is closest; if their broadcast lives elsewhere in the cluster, the local relay fetches it from a neighbor and caches it. Hop tracking on every broadcast keeps loops out and picks the shortest path when there's more than one. - `--cluster-connect ` lists the peers this relay dials. Repeatable; defines the topology by hand. A simple chain like `eu-west <- us-east <- us-west` lets `us-east` cache and dedup the transatlantic fetches that fan out to many `us-west` viewers. -- `--cluster-mesh ` is optional. When set, this relay advertises its own URL to connected peers and dials any peers it learns about, so larger clusters don't need each node hand-configured. You still need at least one connection (in or out) so the advertisement has a path to flow. A relay with `--cluster-mesh` set and no `--cluster-connect` is a passive rendezvous. +- `--cluster-connect-api ` fetches that list from an endpoint or file instead, reloading it without a restart. +- `--cluster-lan` finds peers on the local network over mDNS. -`--cluster-root` and `--cluster-node` from earlier versions were removed. The relay errors at startup if either is set and points at the replacements. +A relay only dials peers listed this way or found on the LAN. `--cluster-mesh` gossip discovery was removed; the relay errors at startup if it is set. See [doc/bin/relay/cluster.md](https://github.com/moq-dev/moq/blob/main/doc/bin/relay/cluster.md) for the full walkthrough, including topology trade-offs and authentication. diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index e35414d1cbb..1c4c78f70b7 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -5,32 +5,23 @@ use std::{ Arc, Mutex, atomic::{AtomicU64, Ordering}, }, - time::{Duration, Instant}, + time::Duration, }; use anyhow::Context; use moq_net::origin; -use moq_net::{Hop, Path, stats::Tier}; +use moq_net::{Hop, stats::Tier}; use reqwest_middleware::ClientWithMiddleware; use tokio::task::AbortHandle; use tracing::Instrument as _; use url::Url; -use crate::{auth, nodes::MESH_PREFIX}; +use crate::auth; /// The request path prefix a LAN mesh dial presents, marking it as a peer rather /// than an ordinary publisher or viewer on the same listener. pub(crate) const CLUSTER_PATH: &str = "/.cluster"; -/// How often the discovery loop scans for stale entries. -const SWEEP_INTERVAL: Duration = Duration::from_secs(30); - -/// How long a peer must stay unannounced before we abort the dial. Must clear the -/// "prefer shorter hop" re-announce flap (which arrives as -/// unannounce-then-announce within sub-milliseconds) plus reasonable churn from -/// a peer restart. -const STALE_AFTER: Duration = Duration::from_secs(60); - /// How often the relay re-checks an http(s) `--cluster-connect-api` endpoint. The /// HTTP cache middleware suppresses the actual network round-trip while the cached /// list is still fresh (per the response's `Cache-Control`), so this is the floor @@ -38,16 +29,6 @@ const STALE_AFTER: Duration = Duration::from_secs(60); /// ticks turn into real conditional GETs. const CONNECT_API_POLL_INTERVAL: Duration = Duration::from_secs(30); -/// Mesh tiebreaker for gossip-discovered peers. In a full mesh both peers -/// discover each other and would each open a dial, leaving two redundant -/// sessions. The session is bidirectional (we publish *and* consume on it), so -/// one suffices. Break the symmetry on URL order: only dial peers that sort -/// after us, making the lexicographically-smaller node the client and the -/// larger the server. The skipped side still gets the connection inbound. -fn should_dial(self_url: &str, peer: &str) -> bool { - peer > self_url -} - /// One cluster peer to dial, as listed in [`Config::connect`] or returned /// by a `connect_api` endpoint. /// @@ -233,7 +214,7 @@ struct DialTarget { key: String, url: Url, /// Extra candidates after [`Self::url`], in dial order. Empty for a - /// static, gossip, or API peer, which has one address. + /// static or API peer, which has one address. urls: Vec, cost: Option, /// Advertised certificate fingerprint to pin. LAN only. @@ -245,6 +226,7 @@ struct DialTarget { impl DialTarget { /// Parse a bare peer URL, keeping its inline `?cost=` / `?jwt=`. + #[cfg(test)] fn parse(peer: &str) -> anyhow::Result { Self::from_peer(&Peer::new(peer)) } @@ -332,52 +314,6 @@ impl DialTarget { } } -/// Every currently-live gossip path for a canonical peer, in announcement order. -/// Query changes create a new path before the old path necessarily unannounces, -/// so the latest live path owns the dial configuration. -#[derive(Default)] -struct GossipTargets { - by_key: HashMap>, -} - -enum GossipUpdate { - /// The current advertisement changed to this target. - Current(DialTarget), - /// A non-current or unknown advertisement disappeared. - Unchanged, - /// The peer has no live advertisements left. - Gone, -} - -impl GossipTargets { - fn announce(&mut self, advertisement: String, target: DialTarget) -> DialTarget { - let targets = self.by_key.entry(target.key.clone()).or_default(); - targets.retain(|(existing, _)| existing != &advertisement); - targets.push((advertisement, target.clone())); - target - } - - fn unannounce(&mut self, advertisement: &str, key: &str) -> GossipUpdate { - let Some(targets) = self.by_key.get_mut(key) else { - return GossipUpdate::Unchanged; - }; - let was_current = targets.last().is_some_and(|(current, _)| current == advertisement); - let previous_len = targets.len(); - targets.retain(|(existing, _)| existing != advertisement); - if targets.len() == previous_len { - return GossipUpdate::Unchanged; - } - if targets.is_empty() { - self.by_key.remove(key); - return GossipUpdate::Gone; - } - if was_current { - return GossipUpdate::Current(targets.last().expect("live target exists").1.clone()); - } - GossipUpdate::Unchanged - } -} - /// Parse a complete dynamic peer list before mutating the live dial set. A bad /// entry or conflicting duplicate rejects the whole update, preserving the /// last-known-good topology. @@ -399,7 +335,7 @@ fn parse_peer_list(list: Vec, node: Option<&str>) -> anyhow::Result, - gossip: Option, api: Option, #[cfg(feature = "cluster-lan")] mdns: Option, @@ -434,7 +365,6 @@ impl DialSources { fn get(&self, source: DialSource) -> Option<&DialTarget> { match source { DialSource::Static => self.seeded.as_ref(), - DialSource::Gossip => self.gossip.as_ref(), DialSource::Api => self.api.as_ref(), #[cfg(feature = "cluster-lan")] DialSource::Mdns => self.mdns.as_ref(), @@ -444,7 +374,6 @@ impl DialSources { fn set(&mut self, source: DialSource, target: DialTarget) { match source { DialSource::Static => self.seeded = Some(target), - DialSource::Gossip => self.gossip = Some(target), DialSource::Api => self.api = Some(target), #[cfg(feature = "cluster-lan")] DialSource::Mdns => self.mdns = Some(target), @@ -454,7 +383,6 @@ impl DialSources { fn clear(&mut self, source: DialSource) { match source { DialSource::Static => self.seeded = None, - DialSource::Gossip => self.gossip = None, DialSource::Api => self.api = None, #[cfg(feature = "cluster-lan")] DialSource::Mdns => self.mdns = None, @@ -462,33 +390,29 @@ impl DialSources { } /// The source to fall back to when the active one is released, most durable - /// first: operator intent, then the API list, then the two discovery - /// mechanisms whose targets come and go on their own. + /// first: operator intent, then the API list, then LAN discovery, whose + /// targets come and go on their own. fn fallback(&self) -> Option<(DialSource, &DialTarget)> { let fallback = self .seeded .as_ref() .map(|target| (DialSource::Static, target)) - .or_else(|| self.api.as_ref().map(|target| (DialSource::Api, target))) - .or_else(|| self.gossip.as_ref().map(|target| (DialSource::Gossip, target))); + .or_else(|| self.api.as_ref().map(|target| (DialSource::Api, target))); #[cfg(feature = "cluster-lan")] let fallback = fallback.or_else(|| self.mdns.as_ref().map(|target| (DialSource::Mdns, target))); fallback } } -/// One entry in [`DialMap`]. `unannounced_at` carries the gossip stale timer; the -/// sweep uses it to decide when the gossip source has truly gone vs. is just -/// flapping between paths. It's only meaningful while `sources.gossip` is set. +/// One entry in [`DialMap`]. struct DialEntry { handle: AbortHandle, sources: DialSources, active: DialSource, - unannounced_at: Option, } /// Map of in-flight cluster dials, keyed by canonical peer identity. Cloneable: the inner -/// map is shared via `Arc>` so the discovery task and the static-seed +/// map is shared via `Arc>` so the discovery tasks and the static-seed /// phase write to the same set of entries. #[derive(Clone, Default)] struct DialMap { @@ -514,7 +438,7 @@ impl DialMap { /// Add or update one source's target, replacing the live dial only when that /// source already owns it. Other sources retain their latest target as a /// fallback without changing the first source's active configuration. - fn upsert(&self, target: DialTarget, source: DialSource, spawn: &mut F) -> bool + fn upsert(&self, target: DialTarget, source: DialSource, spawn: &mut F) where F: FnMut(DialTarget) -> AbortHandle, { @@ -522,12 +446,11 @@ impl DialMap { if let Some(entry) = map.get_mut(&target.key) { let replace = entry.active == source && entry.sources.get(source) != Some(&target); entry.sources.set(source, target.clone()); - let reannounced = source == DialSource::Gossip && entry.unannounced_at.take().is_some(); if replace { entry.handle.abort(); entry.handle = spawn(target); } - return reannounced; + return; } let key = target.key.clone(); @@ -540,10 +463,8 @@ impl DialMap { handle, sources, active: source, - unannounced_at: None, }, ); - false } /// Release one source. If it owned the live dial, switch to a remaining @@ -577,42 +498,6 @@ impl DialMap { entry.handle.abort(); } - /// Start the gossip stale timer on `peer` if it isn't already pending. No-op - /// unless the peer is currently wanted by gossip. Idempotent: a repeat - /// unannounce while a timestamp is pending doesn't reset the clock. - fn mark_unannounced(&self, peer: &str, now: Instant) { - let mut map = self.inner.lock().expect("dial map poisoned"); - if let Some(entry) = map.get_mut(peer) - && entry.sources.gossip.is_some() - { - entry.unannounced_at.get_or_insert(now); - } - } - - /// Release the gossip source from entries whose unannounce has stuck for at - /// least `threshold`, aborting the dial only if no other source still wants it. - fn sweep_stale(&self, now: Instant, threshold: Duration, spawn: &mut F) - where - F: FnMut(DialTarget) -> AbortHandle, - { - let mut map = self.inner.lock().expect("dial map poisoned"); - let expired: Vec = map - .iter_mut() - .filter_map(|(peer, entry)| { - let at = entry.unannounced_at?; - (now.duration_since(at) >= threshold).then(|| { - entry.unannounced_at = None; - peer.clone() - }) - }) - .collect(); - drop(map); - - for peer in expired { - self.release(&peer, DialSource::Gossip, spawn); - } - } - /// Reconcile the API source against `desired`, including changes to a peer's /// dial-affecting URL or link cost while its canonical identity stays fixed. fn reconcile_api(&self, desired: &HashMap, mut spawn: F) @@ -639,10 +524,10 @@ impl DialMap { /// Configuration for relay clustering. /// -/// [`Self::connect`] / [`Self::connect_api`] list peers to dial. [`Self::node`] is -/// this relay's own URL (identity); [`Self::mesh`] enables gossip, advertising that -/// URL so other peers discover and dial it. Set `node` + `mesh` with no `connect` -/// to act as a passive rendezvous. +/// [`Self::connect`] / [`Self::connect_api`] list peers to dial, and +/// [`Self::node`] is this relay's own URL (identity). A relay only dials peers +/// configured here or found on the LAN; it never dials a URL learned from an +/// announcement. /// /// Hop-based routing on broadcasts prevents announcement loops regardless of topology. #[serde_with::serde_as] @@ -703,7 +588,7 @@ pub struct Config { /// notifications (with a periodic re-check fallback). This relay's own /// [`Self::node`] value, when set, is sent as a `?node=` query param so the /// server can return this node's peers. The relay keeps the last good list if - /// a fetch fails. Composes with [`Self::connect`] and [`Self::mesh`]. + /// a fetch fails. Composes with [`Self::connect`]. #[usage( name = "cluster-connect-api", long = "cluster-connect-api", @@ -714,8 +599,8 @@ pub struct Config { /// This relay's own externally-reachable URL (identity). Sent to /// [`Self::connect_api`] as a `?node=` query param so the endpoint can return - /// this node's peers, and advertised to other relays when [`Self::mesh`] gossip - /// is enabled. On its own it neither opens nor accepts a connection. + /// this node's peers, and advertised over mDNS when LAN discovery is on. On + /// its own it neither opens nor accepts a connection. #[usage( name = "cluster-node", long = "cluster-node", @@ -724,15 +609,10 @@ pub struct Config { )] pub node: Option, - /// Enable gossip discovery: advertise this relay's [`Self::node`] URL on the - /// cluster origin so peers can find and dial it (and so this relay discovers - /// peers the same way). Requires [`Self::node`]. Boolean flag: pass - /// `--cluster-mesh` (or `=true` / `=false`). - /// - /// Kept as a string for backwards compatibility: `--cluster-mesh` used to take - /// this relay's URL. A non-boolean value is treated as a legacy [`Self::node`] - /// (with a deprecation warning), or an error if it conflicts with an explicit - /// `--cluster-node`. Accepts a TOML boolean or string. + /// Released spelling of the removed gossip discovery, kept so + /// [`Self::deprecated`] can refuse it. Any value, boolean or the older URL + /// form, is refused. + #[doc(hidden)] #[usage( name = "cluster-mesh", long = "cluster-mesh", @@ -741,6 +621,7 @@ pub struct Config { default_missing = "true", num_args = 0..=1, require_equals = true, + hide = true, )] #[serde(default, deserialize_with = "deserialize_bool_or_string")] pub mesh: Option, @@ -752,12 +633,10 @@ pub struct Config { pub lan: LanConfig, /// JWT presented on outbound cluster dials, read from this file. Applied to - /// any static, API, or gossip peer whose URL doesn't already carry a - /// `?jwt=` and whose object entry sets no `token`. An inline `?jwt=` or - /// object `token` provides a per-peer credential for static or `connect_api` - /// peers. Gossip should use this shared token or mTLS - /// because the advertised node URL is public. LAN peers never receive it; - /// they authenticate with their mDNS credential. + /// any static or API peer whose URL doesn't already carry a `?jwt=` and + /// whose object entry sets no `token`. An inline `?jwt=` or object `token` + /// provides a per-peer credential instead. LAN peers never receive it; they + /// authenticate with their mDNS credential. #[usage( name = "cluster-token", long = "cluster-token", @@ -804,6 +683,14 @@ impl Config { "a broadcast closes as soon as its last publisher is lost", ); } + if self.mesh.is_some() { + found.changed( + "--cluster-mesh", + Some("MOQ_CLUSTER_MESH"), + "--cluster-connect or --cluster-connect-api", + "gossip discovery is removed; list every peer this relay dials", + ); + } if self.connect.iter().any(|peer| is_legacy_peer(peer.url())) { found.changed( "--cluster-connect", @@ -1006,9 +893,7 @@ impl std::fmt::Debug for Started { /// The resolved settings behind a [`Started`] that has work to do. struct Work { - gossip: bool, node: Option, - can_dial: bool, token: String, /// The live mDNS advertisement, bound by [`Cluster::start`]. #[cfg(feature = "cluster-lan")] @@ -1029,7 +914,7 @@ struct Work { pub struct Cluster { config: Config, client: Option, - /// Dial template for LAN peers that pin a fingerprint; static and gossip + /// Dial template for LAN peers that pin a fingerprint; static and API /// dials keep [`Self::client`]. connect: Option, quic: Option, @@ -1125,7 +1010,7 @@ impl Cluster { origin_config.cache_duration = cache.duration; } let origin = moq_tokio::origin::spawn_config(origin_config); - let nodes = crate::nodes::Nodes::new(origin.clone()); + let nodes = crate::nodes::Nodes::default(); tracing::info!(hop_id = %origin.hop(), configured = config.id.is_some(), "cluster initialized"); Ok(Cluster { config, @@ -1187,8 +1072,7 @@ impl Cluster { // An authenticated cluster peer (a verified client certificate or the LAN // credential) discovers hidden routes whether or not it asks. A peer that // predates the hidden opt-in (below moq-lite-07-wip, or moq-transport without - // MoQ Hidden) would otherwise lose `.internal/origins` and every other dot - // path during a rolling upgrade. + // MoQ Hidden) would otherwise lose every dot path during a rolling upgrade. // TODO: drop the exemption once deployed peers all opt in. let cluster_peer = request.tls.is_some() || Self::is_lan_path(&request.path); let subscriber = match request.role { @@ -1306,36 +1190,6 @@ impl Cluster { Some(origin) } - /// Resolve whether gossip is on and which URL this relay advertises, from - /// `cluster.node` and the (string-typed) `cluster.mesh` toggle. - /// - /// `mesh` is `"true"` / `"false"` normally. For backwards compatibility a - /// non-boolean value is the legacy "advertise this URL" form: it turns gossip - /// on and supplies the node URL (with a deprecation warning), unless it - /// conflicts with an explicit `cluster.node`, which is an error. - fn resolve_mesh(&self) -> anyhow::Result<(bool, Option)> { - let node = self.config.node.clone(); - match self.config.mesh.as_deref() { - None => Ok((false, node)), - Some("true") => Ok((true, node)), - Some("false") => Ok((false, node)), - Some(legacy) => { - tracing::warn!( - value = %legacy, - "`--cluster-mesh` is now a boolean; treating the value as `--cluster-node` for backwards \ - compatibility. Set `--cluster-node ` and `--cluster-mesh` instead." - ); - match &node { - Some(node) if node != legacy => anyhow::bail!( - "`--cluster-mesh` was given URL {legacy:?}, which conflicts with `--cluster-node` {node:?}. \ - `--cluster-mesh` is now a boolean; set the address only via `--cluster-node`." - ), - _ => Ok((true, Some(legacy.to_owned()))), - } - } - } - } - /// Whether `--cluster-lan` asked this relay to discover peers over mDNS. fn lan(&self) -> bool { #[cfg(feature = "cluster-lan")] @@ -1423,16 +1277,10 @@ impl Cluster { /// would release systemd's dependent units on a relay that is about to exit. /// Call this before signalling readiness, and hand the result to `run`. /// - /// Bails when `mesh` gossip is on without `node`, or when peers are configured - /// to dial but no client was attached via [`with_client`](Self::with_client). + /// Bails when peers are configured to dial but no client was attached via + /// [`with_client`](Self::with_client). pub async fn start(self) -> anyhow::Result { - let (gossip, node) = self.resolve_mesh()?; - anyhow::ensure!( - !gossip || node.is_some(), - "`--cluster-mesh` (gossip) requires `--cluster-node ` so there's an address to advertise. \ - See https://doc.moq.dev/bin/relay/cluster." - ); - + let node = self.config.node.clone(); let lan = self.lan(); #[cfg(feature = "cluster-lan")] self.config.lan.validate()?; @@ -1459,12 +1307,8 @@ impl Cluster { } } - let has_outbound = !self.config.connect.is_empty() || self.config.connect_api.is_some(); - // Every mechanism that opens a dial, so gossip discovery runs whenever - // there is something to dial with, not only when a peer was listed. - let can_dial = has_outbound || lan; - let has_work = can_dial || gossip; - if !has_work { + let can_dial = !self.config.connect.is_empty() || self.config.connect_api.is_some() || lan; + if !can_dial { tracing::info!("no cluster peers configured; running standalone"); return Ok(Started { work: None, @@ -1472,12 +1316,10 @@ impl Cluster { }); } - if can_dial { - anyhow::ensure!( - self.client.is_some(), - "cluster peers configured but no QUIC client attached (call Cluster::with_client)" - ); - } + anyhow::ensure!( + self.client.is_some(), + "cluster peers configured but no QUIC client attached (call Cluster::with_client)" + ); // Only http(s) sources need the TLS client; a local file doesn't. if let Some(source) = &self.config.connect_api { @@ -1521,9 +1363,7 @@ impl Cluster { Ok(Started { work: Some(Work { - gossip, node, - can_dial, token, #[cfg(feature = "cluster-lan")] discovery, @@ -1533,29 +1373,18 @@ impl Cluster { } /// Runs the cluster event loop against the work [`start`](Self::start) - /// resolved. - /// - /// Modes are derived from config: passive rendezvous (`node` + `mesh` gossip, - /// no peers to dial) parks after publishing self-registration and does not - /// require a QUIC client; active (`connect` / `connect_api` set) dials peers - /// and, when `mesh` gossip is on, also advertises `node` and runs discovery. + /// resolved: dials the static peers, then keeps the `connect_api` list and + /// LAN discovery reconciled into the same dial set. async fn run_work(self, work: Work) -> anyhow::Result<()> { let Work { - gossip, node, - can_dial, token, #[cfg(feature = "cluster-lan")] discovery, } = work; - // Static `--cluster-connect` peers and gossip-discovered peers share one - // dial map so a peer reached via both paths only opens a single dial. - // Gossip-driven unannounces don't abort immediately. The discovery loop - // runs a periodic sweep that only aborts entries whose unannounce has - // stuck for [`STALE_AFTER`]. That filters out the prefer-shorter-hop flap - // (sub-millisecond unannounce-then-announce) while still cleaning up - // peers that truly left. + // Every source shares one dial map so a peer reached via several only + // opens a single dial. let dialed = DialMap::default(); let mut tasks = tokio::task::JoinSet::new(); // Tasks whose ending is a failure rather than an ordinary lifecycle event, @@ -1594,45 +1423,6 @@ impl Cluster { supervised.spawn(async move { this.run_mdns(dialed, discovery).await }); } - // Held in scope so the registration stays announced until `run` exits. - // Discovery is paired with it: a gossip-only relay (passive rendezvous) has - // nothing to discover, so we only run it when we also have an outbound peer. - // The path itself is the advertisement: an empty broadcast, announced. - let mut self_registration: Option = if gossip { - // Checked above: gossip requires `node`. - let node = node.as_deref().expect("gossip requires --cluster-node"); - let path = Path::new(MESH_PREFIX).join(node); - let registration = self - .origin - .create_broadcast(&path) - .expect(".internal/origins is within the relay origin's root"); - registration - .announce(moq_net::origin::Route::default()) - .expect("the origin driver outlives the cluster"); - tracing::info!(%node, %path, "advertising cluster node URL"); - - if can_dial { - let this = self.clone(); - let token = token.clone(); - let dialed = dialed.clone(); - // Canonical, so the tiebreaker compares the same spelling both sides do. - let self_url = canonicalize_peer_key(node); - tasks.spawn(async move { - this.run_discovery(self_url, token, dialed).await; - }); - } - - Some(registration) - } else { - None - }; - - if tasks.is_empty() && supervised.is_empty() { - // Passive rendezvous: park to keep `self_registration` alive. The - // process still exits via the other arms of `tokio::select!` in main. - std::future::pending::<()>().await - } - loop { tokio::select! { // A supervised task ending at all is a failure, so its result decides @@ -1643,109 +1433,16 @@ impl Cluster { else => break, } } - - // Deliberate shutdown: closing the registration retracts the route. - if let Some(registration) = self_registration.as_mut() { - registration.close(); - } Ok(()) } - /// Watch `.internal/origins/*` for peer registrations and dial each newly- - /// announced URL that sorts after our own (see [`should_dial`]); the peer on - /// the other side of that comparison dials us, so each pair opens one session - /// instead of two. Unannounces don't abort immediately. They just mark the - /// entry as "pending cleanup" with a timestamp. A periodic sweep evicts - /// entries whose unannounce has stuck for [`STALE_AFTER`]. The "prefer - /// shorter hop" path in origin::Producer delivers re-announces as - /// unannounce-then-announce within sub-milliseconds, which clears the - /// pending-cleanup timestamp long before the sweep fires. - async fn run_discovery(self, self_url: String, token: String, dialed: DialMap) { - let Ok(consumer) = self - .origin - .consume() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - else { - tracing::warn!("could not scope cluster origin to {MESH_PREFIX}; discovery disabled"); - return; - }; - let mut announced = consumer.announced(); - let mut live = GossipTargets::default(); - - let mut sweep = tokio::time::interval(SWEEP_INTERVAL); - sweep.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip); - // Skip the first immediate tick; nothing has had a chance to go stale yet. - sweep.tick().await; - - loop { - tokio::select! { - ann = announced.next() => { - let (update, active) = match ann { - Some(moq_net::announce::Event::Start(update) | moq_net::announce::Event::Update(update)) => (update, true), - Some(moq_net::announce::Event::End(update)) => (update, false), - Some(moq_net::announce::Event::Live) => continue, - None => return, - }; - let relative = update.prefix; - // The address to dial, which keeps its query: `run_remote` reads - // `?cost=` and `?jwt=` off it. The key is only its identity. - let peer = advertised_node_url(relative.as_str()); - let target = match DialTarget::parse(&peer) { - Ok(target) => target, - Err(err) => { - tracing::warn!(%err, "invalid gossiped cluster peer URL; ignoring update"); - continue; - } - }; - // Skip self and any peer we lose the tiebreaker to; that side - // dials us instead, so each pair forms a single session. - if !should_dial(&self_url, &target.key) { - continue; - } - let advertisement = relative.as_str().to_owned(); - match active { - true => { - let target = live.announce(advertisement, target); - let mut spawn = |target: DialTarget| { - tracing::info!(peer = %target.key, "discovered cluster peer; dialing"); - tokio::spawn(self.clone().supervise_remote(target, token.clone())).abort_handle() - }; - let key = target.key.clone(); - if dialed.upsert(target, DialSource::Gossip, &mut spawn) { - tracing::debug!(peer = %key, "reannounce within sweep window; keeping dial"); - } - } - false => match live.unannounce(&advertisement, &target.key) { - GossipUpdate::Current(target) => { - let mut spawn = |target: DialTarget| { - tracing::info!(peer = %target.key, "cluster peer advertisement changed; redialing"); - tokio::spawn(self.clone().supervise_remote(target, token.clone())).abort_handle() - }; - dialed.upsert(target, DialSource::Gossip, &mut spawn); - } - GossipUpdate::Unchanged => {} - GossipUpdate::Gone => dialed.mark_unannounced(&target.key, Instant::now()), - }, - } - } - _ = sweep.tick() => { - let mut spawn = |target: DialTarget| { - tracing::info!(peer = %target.key, "cluster peer source changed; redialing"); - tokio::spawn(self.clone().supervise_remote(target, token.clone())).abort_handle() - }; - dialed.sweep_stale(Instant::now(), STALE_AFTER, &mut spawn); - } - } - } - } - /// Dial every process that advertises itself on the LAN. /// /// Each candidate is [`Peer::urls`](moq_tokio::mdns::Peer::urls) in order /// (node first) on `/.cluster/`, with the advertised fingerprint /// pinned. The lower discovery id dials; the other waits inbound. A LAN dial - /// never carries `?jwt=` — [`Config::token`] is for static and gossip - /// peers only. + /// never carries `?jwt=`: [`Config::token`] is for static and API peers + /// only. #[cfg(feature = "cluster-lan")] async fn run_mdns(self, dialed: DialMap, mut discovery: moq_tokio::mdns::Discovery) -> anyhow::Result<()> { use moq_tokio::mdns::Event; @@ -2212,8 +1909,8 @@ fn connect_api_is_http(source: &str) -> bool { /// /// The modern form is a full URL, e.g. `https://host/?jwt=TOKEN`, which is used /// verbatim. A bare host or `host:port` is wrapped in `https://.../` for -/// gossip and `--cluster-connect-api` lists; user-supplied `--cluster-connect` -/// entries refuse that form through [`Config::deprecated`]. +/// `--cluster-connect-api` lists; user-supplied `--cluster-connect` entries +/// refuse that form through [`Config::deprecated`]. fn peer_url(peer: &str) -> anyhow::Result { // A full URL has a scheme separator; a bare host or `host:port` does not // (and `Url::parse` would otherwise mis-read `host:port` as scheme `host`). @@ -2224,33 +1921,6 @@ fn peer_url(peer: &str) -> anyhow::Result { Url::parse(&format!("https://{peer}/")).context("invalid cluster peer host") } -/// The address to dial for a node advertised under `MESH_PREFIX`. -/// -/// A relay advertises its URL as a broadcast path, and [`Path`] collapses slash -/// runs, so `https://relay-b.example/` arrives as `https:/relay-b.example`. The -/// scheme is put back here rather than read as a hostname. -/// -/// The trailing colon on the leading segment is what marks a scheme: a bare -/// `host:port` carries its colon in the middle of the segment, never at the end, -/// so the two spellings can't be mistaken for each other and no list of known -/// schemes is needed. A scheme-less advertisement means `https`, exactly as -/// [`peer_url`] reads a bare host. -/// -/// The query survives, because [`Cluster::run_remote`] reads `?cost=` and `?jwt=` -/// off the address it dials. Pass the result through [`canonicalize_peer_key`] -/// for an identity key; don't dial the key, which drops the query. -/// -/// A trailing slash on a non-empty URL path does not survive, since a path has no -/// way to spell one. `https://a.example/edge/` advertises the same as -/// `https://a.example/edge`. -pub(crate) fn advertised_node_url(advertised: &str) -> String { - match advertised.split_once('/') { - // The segment already ends in `:`, so this restores the `//` the path ate. - Some((scheme, rest)) if scheme.ends_with(':') => format!("{scheme}//{rest}"), - _ => advertised.to_owned(), - } -} - /// Whether a peer string uses the released bare-host / `host:port` form rather /// than a full URL. Used so [`Config::deprecated`] can refuse /// `--cluster-connect` entries that still use it. @@ -2276,10 +1946,9 @@ pub(crate) fn canonicalize_peer_key(peer: &str) -> String { url.set_fragment(None); url.set_username("").ok(); url.set_password(None).ok(); - // Gossip round-trips the URL through `Path`, which trims slashes and - // collapses runs of them, so the key normalizes the path the same way. - // A non-special scheme like `moqt` keeps its trailing slash otherwise, - // and `moqt://a.example:4443/` is an ordinary way to spell a node. + // Trim and collapse path slashes: a non-special scheme like `moqt` keeps + // its trailing slash otherwise, and `moqt://a.example:4443/` is an + // ordinary way to spell the same node as `moqt://a.example:4443`. let segments: Vec<&str> = url.path().split('/').filter(|s| !s.is_empty()).collect(); let path = match segments.is_empty() { true => String::new(), @@ -2293,8 +1962,9 @@ pub(crate) fn canonicalize_peer_key(peer: &str) -> String { } /// Deserialize a field that accepts either a TOML boolean or string into an -/// `Option` (booleans become `"true"` / `"false"`). Lets `cluster.mesh` -/// take the modern `mesh = true` form or the legacy `mesh = ""` form. +/// `Option` (booleans become `"true"` / `"false"`). Lets the removed +/// `cluster.mesh` parse in both its released forms, `mesh = true` and +/// `mesh = ""`, so it is refused by name rather than as an unknown type. fn deserialize_bool_or_string<'de, D>(deserializer: D) -> Result, D::Error> where D: serde::Deserializer<'de>, @@ -2497,138 +2167,20 @@ mod tests { keys.iter().map(|key| ((*key).to_string(), target(key))).collect() } - /// A query change creates a new gossip path before the old path necessarily - /// unannounces. Removing that old path must not stale the replacement. - #[test] - fn gossip_old_unannounce_keeps_new_target() { - let mut live = GossipTargets::default(); - let old = DialTarget::parse("https://peer.example/?cost=1").unwrap(); - let new = DialTarget::parse("https://peer.example/?cost=2").unwrap(); - live.announce("peer.example/?cost=1".to_string(), old.clone()); - live.announce("peer.example/?cost=2".to_string(), new.clone()); - - assert!(matches!( - live.unannounce("peer.example/?cost=1", &old.key), - GossipUpdate::Unchanged - )); - assert!(matches!( - live.unannounce("peer.example/?cost=2", &new.key), - GossipUpdate::Gone - )); - } - - /// If the current gossip path disappears while an older one is still live, - /// the remaining target becomes current again. - #[test] - fn gossip_current_unannounce_restores_live_fallback() { - let mut live = GossipTargets::default(); - let old = DialTarget::parse("https://peer.example/?cost=1").unwrap(); - let new = DialTarget::parse("https://peer.example/?cost=2").unwrap(); - live.announce("peer.example/?cost=1".to_string(), old.clone()); - live.announce("peer.example/?cost=2".to_string(), new.clone()); - - let GossipUpdate::Current(current) = live.unannounce("peer.example/?cost=2", &new.key) else { - panic!("older live advertisement must become current"); - }; - assert!(current == old); - } - - /// `mark_unannounced` is a no-op for static peers (operator intent says - /// "always dial"), so the sweep never has a stale timestamp to act on. - #[tokio::test] - async fn sweep_preserves_static_peer() { - let dialed = DialMap::default(); - dialed.insert(target("static-peer:4443"), placeholder_handle(), DialSource::Static); - - let long_ago = Instant::now() - Duration::from_secs(3600); - dialed.mark_unannounced("static-peer:4443", long_ago); - dialed.sweep_stale(Instant::now(), STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("static-peer:4443")); - } - - /// A gossip-discovered peer whose unannounce has stuck longer than the - /// threshold gets aborted and removed. - #[tokio::test] - async fn sweep_evicts_stale_gossip_peer() { - let dialed = DialMap::default(); - let now = Instant::now(); - dialed.insert(target("gone:4443"), placeholder_handle(), DialSource::Gossip); - dialed.mark_unannounced("gone:4443", now - STALE_AFTER - Duration::from_secs(1)); - - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(!dialed.contains("gone:4443")); - } - - /// A gossip-discovered peer whose unannounce is recent stays in the map; the - /// sweep is only allowed to evict entries past the full threshold so that the - /// prefer-shorter-hop flap (sub-millisecond unannounce-then-announce) doesn't - /// trip it. - #[tokio::test] - async fn sweep_keeps_recently_unannounced_peer() { - let dialed = DialMap::default(); - let now = Instant::now(); - dialed.insert(target("flapping:4443"), placeholder_handle(), DialSource::Gossip); - dialed.mark_unannounced("flapping:4443", now - Duration::from_millis(50)); - - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("flapping:4443")); - } - - /// A peer that's currently announced (no pending unannounce) is never swept. - #[tokio::test] - async fn sweep_keeps_currently_announced_peer() { - let dialed = DialMap::default(); - dialed.insert(target("healthy:4443"), placeholder_handle(), DialSource::Gossip); - // No mark_unannounced -> stays announced. - - dialed.sweep_stale(Instant::now(), STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("healthy:4443")); - } - - /// A re-announce after an unannounce clears the pending-sweep timestamp, so - /// the entry survives even if the original unannounce was old enough to - /// otherwise trigger eviction. - #[tokio::test] - async fn reannounce_cancels_pending_sweep() { - let dialed = DialMap::default(); - let now = Instant::now(); - let target = target("flap:4443"); - dialed.insert(target.clone(), placeholder_handle(), DialSource::Gossip); - dialed.mark_unannounced("flap:4443", now - STALE_AFTER - Duration::from_secs(1)); - - // Re-adding the gossip source (a reannounce) clears the pending sweep. - assert!( - dialed.upsert(target.clone(), DialSource::Gossip, &mut |_| panic!("must not redial")), - "should report a cleared pending-sweep" - ); - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("flap:4443")); - // A second reannounce has nothing to clear. - assert!(!dialed.upsert(target, DialSource::Gossip, &mut |_| panic!("must not redial"))); - } - - /// A peer wanted by both gossip and the API survives losing either source: the - /// dial is only torn down once the last source releases it. + /// A peer wanted by both a static seed and the API survives losing either + /// source: the dial is only torn down once the last source releases it. #[tokio::test] async fn multi_source_peer_survives_until_last_release() { let dialed = DialMap::default(); - let now = Instant::now(); - // Gossiped first, then also appears in the API list. - dialed.insert(target("both:4443"), placeholder_handle(), DialSource::Gossip); + // Seeded first, then also appears in the API list. + dialed.insert(target("both:4443"), placeholder_handle(), DialSource::Static); dialed.reconcile_api(&desired(&["both:4443"]), |_| panic!("already dialed")); - // Dropped from the API list -> still wanted by gossip. - dialed.reconcile_api(&HashMap::new(), |_| panic!("gossip dial stays active")); - assert!(dialed.contains("both:4443"), "gossip still wants it"); + // Dropped from the API list -> still wanted by the seed. + dialed.reconcile_api(&HashMap::new(), |_| panic!("static dial stays active")); + assert!(dialed.contains("both:4443"), "the seed still wants it"); - // Now gossip goes stale too -> the dial is finally released. - dialed.mark_unannounced("both:4443", now - STALE_AFTER - Duration::from_secs(1)); - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); + dialed.release("both:4443", DialSource::Static, &mut |_| panic!("must not redial")); assert!(!dialed.contains("both:4443")); } @@ -2637,27 +2189,26 @@ mod tests { #[tokio::test] async fn insert_merges_redundant_dial() { let dialed = DialMap::default(); - dialed.insert(target("p:4443"), placeholder_handle(), DialSource::Gossip); + dialed.insert(target("p:4443"), placeholder_handle(), DialSource::Static); dialed.insert(target("p:4443"), placeholder_handle(), DialSource::Api); - // Dropping the API source leaves the gossip source holding the dial. - dialed.reconcile_api(&HashMap::new(), |_| panic!("gossip dial stays active")); - assert!(dialed.contains("p:4443"), "gossip source still holds the dial"); + // Dropping the API source leaves the static source holding the dial. + dialed.reconcile_api(&HashMap::new(), |_| panic!("static dial stays active")); + assert!(dialed.contains("p:4443"), "static source still holds the dial"); } /// `reconcile_api` drops API dials missing from the desired set, reports the - /// newly desired ones for the caller to spawn, and never touches Static or - /// Gossip dials (even when they're absent from the API list). + /// newly desired ones for the caller to spawn, and never touches Static dials + /// (even when they're absent from the API list). #[tokio::test] async fn reconcile_api_adds_and_removes_only_api() { let dialed = DialMap::default(); dialed.insert(target("static:4443"), placeholder_handle(), DialSource::Static); - dialed.insert(target("gossip:4443"), placeholder_handle(), DialSource::Gossip); dialed.insert(target("api-keep:4443"), placeholder_handle(), DialSource::Api); dialed.insert(target("api-drop:4443"), placeholder_handle(), DialSource::Api); // Desired: keep one existing API peer, drop the other, add a new one. - // Static/Gossip peers are not in the list but must survive. + // The static peer is not in the list but must survive. let mut to_add = Vec::new(); dialed.reconcile_api(&desired(&["api-keep:4443", "api-new:4443"]), |target| { to_add.push(target.key); @@ -2669,7 +2220,6 @@ mod tests { assert!(dialed.contains("api-keep:4443")); assert!(!dialed.contains("api-drop:4443"), "dropped API peer must be removed"); assert!(dialed.contains("static:4443"), "static peer must survive reconcile"); - assert!(dialed.contains("gossip:4443"), "gossip peer must survive reconcile"); } /// A peer already dialed via another source is not re-reported for dialing, @@ -2689,19 +2239,17 @@ mod tests { #[tokio::test] async fn inactive_source_update_applies_on_takeover() { let dialed = DialMap::default(); - let gossip = DialTarget::parse("https://peer.example/?cost=1").unwrap(); + let seeded = DialTarget::parse("https://peer.example/?cost=1").unwrap(); let api = DialTarget::parse("https://peer.example/?cost=3").unwrap(); let old_task = tokio::spawn(std::future::pending::<()>()); - dialed.insert(gossip.clone(), old_task.abort_handle(), DialSource::Gossip); + dialed.insert(seeded.clone(), old_task.abort_handle(), DialSource::Static); let desired = [(api.key.clone(), api.clone())].into_iter().collect(); dialed.reconcile_api(&desired, |_| panic!("inactive source must not redial")); assert!(!old_task.is_finished()); - let now = Instant::now(); - dialed.mark_unannounced(&gossip.key, now - STALE_AFTER - Duration::from_secs(1)); let mut spawned = Vec::new(); - dialed.sweep_stale(now, STALE_AFTER, &mut |target| { + dialed.release(&seeded.key, DialSource::Static, &mut |target| { spawned.push(target); placeholder_handle() }); @@ -2719,14 +2267,14 @@ mod tests { let dialed = DialMap::default(); let target = DialTarget::parse("https://peer.example/?cost=1").unwrap(); let task = tokio::spawn(std::future::pending::<()>()); - dialed.insert(target.clone(), task.abort_handle(), DialSource::Gossip); + dialed.insert(target.clone(), task.abort_handle(), DialSource::Static); let desired = [(target.key.clone(), target.clone())].into_iter().collect(); dialed.reconcile_api(&desired, |_| panic!("inactive source must not redial")); - let now = Instant::now(); - dialed.mark_unannounced(&target.key, now - STALE_AFTER - Duration::from_secs(1)); - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("identical fallback must not redial")); + dialed.release(&target.key, DialSource::Static, &mut |_| { + panic!("identical fallback must not redial") + }); assert!(!task.is_finished(), "healthy dial must be preserved"); let map = dialed.inner.lock().expect("dial map"); @@ -3034,30 +2582,22 @@ mod tests { task.abort(); } - /// The mesh tiebreaker only dials peers that sort after us, so exactly one - /// side of each pair opens the dial. Self never dials self. - #[test] - fn should_dial_prefers_larger_url() { - // Smaller hostname is the client: it dials the larger. - assert!(should_dial("a.example.com:4443", "b.example.com:4443")); - // Larger hostname is the server: it waits for the inbound dial. - assert!(!should_dial("b.example.com:4443", "a.example.com:4443")); - // Never dial self. - assert!(!should_dial("self.example.com:4443", "self.example.com:4443")); - } - - /// Enabling gossip (`--cluster-mesh`) without `--cluster-node` has no address to - /// advertise, so it must fail fast with a message naming the missing flag. + /// Gossip discovery is removed, so every released `--cluster-mesh` form, the + /// boolean and the older self-URL, stops construction and names the + /// replacement instead of leaving a relay without the peers it expected. #[tokio::test] - async fn gossip_without_node_errors() { - let config = Config { - mesh: Some("true".to_string()), - ..Default::default() - }; - let err = new_cluster(config).unwrap().start().await.expect_err("should error"); - let msg = format!("{err}"); - assert!(msg.contains("--cluster-node"), "missing --cluster-node in: {msg}"); - assert!(msg.contains("--cluster-mesh"), "missing --cluster-mesh in: {msg}"); + async fn removed_mesh_is_refused() { + for value in ["true", "false", "rendezvous.example.com:4443"] { + let err = new_cluster(Config { + mesh: Some(value.to_string()), + ..Default::default() + }) + .err() + .expect("mesh must be refused"); + let msg = format!("{err}"); + assert!(msg.contains("--cluster-mesh / MOQ_CLUSTER_MESH"), "{value}: {msg}"); + assert!(msg.contains("--cluster-connect"), "{value}: {msg}"); + } } /// A valid `cluster.id` is used verbatim as the relay's Hop ID, giving the @@ -3072,8 +2612,8 @@ mod tests { assert_eq!(cluster.origin.hop().id(), 42); } - /// Cache settings land on the one origin serving, node discovery, and stats - /// share. A handle cloned at construction stays on that origin. + /// Cache settings land on the one origin serving and stats share. A handle + /// cloned at construction stays on that origin. #[tokio::test] async fn constructed_origin_keeps_cache_and_handles() { let duration = Duration::from_secs(5); @@ -3120,26 +2660,7 @@ mod tests { .expect("broadcast resolves") .expect("broadcast present"); - let path = Path::new(MESH_PREFIX).join("https://peer.example/"); - let mut announced = consumer - .clone() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - .expect("mesh prefix") - .announced(); - let registration = origin.create_broadcast(&path).expect("node advertise"); - registration.announce(Default::default()).expect("announce node"); - let (_, active) = tokio::time::timeout(Duration::from_secs(2), next_update(&mut announced)) - .await - .expect("node advertised") - .expect("announce"); - assert!(active); - let snapshot = cluster.nodes.snapshot(); - assert!( - snapshot.nodes.iter().any(|node| node.node.contains("peer.example")), - "node discovery reads the constructed origin: {snapshot:?}" - ); - - let stats_path = Path::new(".stats").join("node").join("test"); + let stats_path = moq_net::Path::new(".stats").join("node").join("test"); tokio::time::timeout(Duration::from_secs(5), consumer.routed(&stats_path)) .await .expect("stats announced") @@ -3161,74 +2682,49 @@ mod tests { } } - /// A relay configured with `cluster.node` + `cluster.mesh` gossip and no peers - /// (passive rendezvous) must run without a QUIC client, publish its - /// self-registration on the cluster origin, and keep that registration alive - /// (i.e. not exit and drop the broadcast). - #[tokio::test(start_paused = true)] - async fn passive_rendezvous_runs_without_client_and_advertises_self() { - let cluster = new_cluster(Config { - node: Some("rendezvous.example.com:4443".to_string()), - mesh: Some("true".to_string()), - ..Default::default() - }) - .unwrap(); - - // Snapshot a consumer on the cluster origin before run() takes ownership of - // `cluster` so we can later check that the registration was published. - let mut watcher = cluster.origin.consume().with_hidden(true).announced(); - - let started = cluster.clone().start().await.expect("cluster start"); - let mut handle = tokio::spawn(async move { started.run().await }); - - // Give the runtime a moment to execute the synchronous setup work. - tokio::time::sleep(tokio::time::Duration::from_millis(10)).await; - - // The self-registration route must be visible on the origin. - // The watcher subscribed to an empty origin, so its marker comes first. - assert!(matches!(watcher.try_next(), Some(moq_net::announce::Event::Live))); - let Some(moq_net::announce::Event::Start(update)) = watcher.try_next() else { - panic!("self-registration must be published"); - }; - assert_eq!(update.prefix.as_str(), ".internal/origins/rendezvous.example.com:4443"); - - // run() must NOT have returned: dropping the broadcast (via run returning) - // would unannounce the registration immediately. Use a short timeout to - // confirm we're still parked. - let still_running = tokio::time::timeout(tokio::time::Duration::from_millis(50), &mut handle) - .await - .is_err(); - assert!(still_running, "passive rendezvous run() should park, not return"); - - handle.abort(); - } - - /// `cluster.node` (identity) and `cluster.mesh` (gossip toggle) round-trip - /// through TOML and survive the CLI re-parse when no flags override them. - /// `mesh` is a string that accepts a TOML boolean for compatibility. + /// `cluster.node` (identity) round-trips through TOML and survives the CLI + /// re-parse when no flags override it. #[test] - fn cluster_node_and_mesh_round_trip() { + fn cluster_node_round_trip() { // Usage reads the environment while parsing, so serialize with the tests // that mutate it. let _env = crate::test_env::EnvGuard::lock(); - let toml = "[cluster]\nnode = \"us-east.example.com:4443\"\nmesh = true\nconnect = [\"https://root.example.com:4443/\"]\n"; + let toml = "[cluster]\nnode = \"us-east.example.com:4443\"\nconnect = [\"https://root.example.com:4443/\"]\n"; let dir = std::env::temp_dir().join("moq-relay-cluster-test"); std::fs::create_dir_all(&dir).unwrap(); - let path = dir.join("cluster-node-mesh-toml.toml"); + let path = dir.join("cluster-node-toml.toml"); std::fs::write(&path, toml).unwrap(); let args = vec![std::ffi::OsString::from("moq-relay"), std::ffi::OsString::from(&path)]; let config = RelayConfig::parse_and_merge(args).expect("config load"); assert_eq!(config.cluster.node.as_deref(), Some("us-east.example.com:4443")); - // A TOML boolean deserializes into the string form. - assert_eq!(config.cluster.mesh.as_deref(), Some("true")); assert_eq!( config.cluster.connect, vec![Peer::new("https://root.example.com:4443/")] ); } + /// A TOML `mesh` in either released type is refused by name at load, so a + /// config file that relied on gossip stops instead of starting without peers. + #[test] + fn toml_mesh_is_refused() { + // Usage reads the environment while parsing, so serialize with the tests + // that mutate it. + let _env = crate::test_env::EnvGuard::lock(); + + let dir = std::env::temp_dir().join("moq-relay-cluster-test"); + std::fs::create_dir_all(&dir).unwrap(); + for (name, value) in [("bool", "true"), ("url", "\"us-east.example.com:4443\"")] { + let path = dir.join(format!("cluster-mesh-{name}-toml.toml")); + std::fs::write(&path, format!("[cluster]\nmesh = {value}\n")).unwrap(); + + let args = vec![std::ffi::OsString::from("moq-relay"), std::ffi::OsString::from(&path)]; + let err = RelayConfig::parse_and_merge(args).expect_err("mesh must be refused"); + assert!(err.to_string().contains("--cluster-mesh"), "{name}: {err}"); + } + } + /// Static config accepts the object form beside bare URLs, through the same /// type the connect API parses. #[test] @@ -3260,20 +2756,6 @@ mod tests { assert_eq!(desired.len(), 2); } - /// The legacy `--cluster-mesh ` form (now a boolean) is honored for - /// backwards compatibility: it enables gossip and supplies the node URL. - #[tokio::test] - async fn legacy_mesh_url_enables_gossip_as_node() { - let cluster = new_cluster(Config { - mesh: Some("rendezvous.example.com:4443".to_string()), - ..Default::default() - }) - .unwrap(); - let (gossip, node) = cluster.resolve_mesh().expect("legacy mesh url resolves"); - assert!(gossip); - assert_eq!(node.as_deref(), Some("rendezvous.example.com:4443")); - } - /// `--cluster-connect` accepts a full URL verbatim (preserving its `?jwt=`) /// and falls back to wrapping a bare host / `host:port` in `https://.../`. #[test] @@ -3322,117 +2804,6 @@ mod tests { assert!(!format!("{err:#}").contains("top-secret")); } - /// What a discovering relay reads off `announced()` for this node. - fn advertised(node: &str) -> String { - Path::new(MESH_PREFIX) - .join(node) - .as_str() - .strip_prefix(&format!("{MESH_PREFIX}/")) - .expect("advertised under the mesh prefix") - .to_owned() - } - - /// A node URL is advertised as a broadcast path, which collapses the `//` after - /// the scheme. It has to come back as the same address anyway, or every - /// gossip-discovered peer is dialed as the hostname `https`. - #[test] - fn a_node_url_survives_a_broadcast_path() { - for node in [ - "https://a.example/", - "https://b.example:4443/", - "tcp://c.example:4443", - "https://d.example/?cost=7", - "https://e.example/deep/path", - // Legacy bare forms, which carry no scheme and default to https. - "rendezvous.example.com:4443", - "cdn.example.com", - ] { - let dialed = advertised_node_url(&advertised(node)); - assert_eq!( - peer_url(&dialed).unwrap(), - peer_url(node).unwrap(), - "{node} did not survive a round trip through a broadcast path" - ); - } - } - - /// The dialed address keeps its query. `run_remote` reads `?cost=` off it to - /// price the link, so canonicalizing first (which drops the query) would leave - /// every gossip-discovered link silently at the default cost. - #[test] - fn an_advertised_url_keeps_the_query_it_is_dialed_with() { - let dialed = advertised_node_url(&advertised("https://a.example/?cost=10")); - assert_eq!(dialed, "https://a.example/?cost=10"); - - // The value has to reach where `run_remote` reads it. - let mut url = peer_url(&dialed).unwrap(); - assert_eq!(take_cost(&mut url).unwrap(), Some(10)); - assert_eq!(url.as_str(), "https://a.example/"); - } - - /// The colon that ends a scheme is the only signal, so a bare `host:port` (whose - /// colon sits mid-segment) must not be read as one. - #[test] - fn a_bare_host_port_is_not_read_as_a_scheme() { - assert_eq!( - advertised_node_url("rendezvous.example.com:4443"), - "rendezvous.example.com:4443" - ); - assert_eq!( - canonicalize_peer_key(&advertised_node_url("rendezvous.example.com:4443")), - "https://rendezvous.example.com:4443/" - ); - } - - /// What a discovering relay reads off an mDNS record for this node, mirroring - /// [`lan_discovery`] and `moq_tokio::mdns::Config::with_node`. - fn advertised_lan(node: &str) -> String { - let mut url = peer_url(node).expect("valid node"); - url.set_fragment(None); - url.set_username("").ok(); - url.set_password(None).ok(); - url.to_string() - } - - /// The two discovery paths must land on the same peer key, or one relay gets - /// two [`DialMap`] entries and is dialed twice. This is self-triggering: the - /// session the mDNS dial opens is what carries the peer's gossip - /// advertisement, so the second dial follows the first. - /// - /// Gossip round-trips the node URL through a [`Path`] (slashes trimmed and - /// collapsed) while mDNS strips the fragment and userinfo, so the key has to - /// absorb both. The realistic trigger is a trailing slash: `moqt` is not a - /// special scheme, so `Url` keeps one that `Path` would have dropped. - #[test] - fn gossip_and_mdns_agree_on_a_peer_key() { - for node in [ - "moqt://a.example:4443/", - "https://a.example/edge/", - "https://a.example/#pos", - "https://user:pw@a.example/", - // Controls: spellings both paths already agreed on. - "https://a.example/", - "https://b.example:4443/deep/path", - "tcp://c.example:4443", - "rendezvous.example.com:4443", - ] { - let gossip = canonicalize_peer_key(&advertised_node_url(&advertised(node))); - let mdns = canonicalize_peer_key(&advertised_lan(node)); - assert_eq!(gossip, mdns, "{node} has two peer keys, so it is dialed twice"); - } - } - - /// With both sides canonical, exactly one of a pair dials. - #[test] - fn gossiped_urls_keep_the_tiebreaker_symmetric() { - let a = canonicalize_peer_key("https://a.example/"); - let b = canonicalize_peer_key(&advertised_node_url("https:/b.example")); - assert!( - should_dial(&a, &b) != should_dial(&b, &a), - "exactly one side of a pair must dial" - ); - } - /// The same relay spelled as a bare `host:port`, a full URL, or a URL with an /// inline jwt all canonicalize to one key, so they share a single dial entry. #[tokio::test] @@ -3455,20 +2826,6 @@ mod tests { assert_ne!(canonicalize_peer_key("host:4443"), canonicalize_peer_key("host:5555")); } - /// A legacy mesh URL that disagrees with an explicit `--cluster-node` is a - /// conflict, not a silent pick. - #[tokio::test] - async fn legacy_mesh_url_conflicting_with_node_errors() { - let cluster = new_cluster(Config { - mesh: Some("a.example.com:4443".to_string()), - node: Some("b.example.com:4443".to_string()), - ..Default::default() - }) - .unwrap(); - let err = cluster.resolve_mesh().expect_err("conflict should error"); - assert!(format!("{err}").contains("conflicts with"), "got: {err}"); - } - /// The nested `[cluster.lan]` table survives the TOML-to-CLI merge. #[cfg(feature = "cluster-lan")] #[test] diff --git a/rs/moq-relay/src/config.rs b/rs/moq-relay/src/config.rs index 658a3e00357..98ad54e9373 100644 --- a/rs/moq-relay/src/config.rs +++ b/rs/moq-relay/src/config.rs @@ -346,6 +346,17 @@ mod tests { use super::*; use crate::test_env::EnvGuard; + #[test] + fn packaged_service_arguments() { + let unit = include_str!("../../../packaging/moq-relay/moq-relay.service"); + let command = unit.lines().find_map(|line| line.strip_prefix("ExecStart=")).unwrap(); + let mut args = command.split_whitespace(); + assert_eq!(args.next(), Some("/usr/bin/moq-relay")); + let args: Vec<_> = args.map(std::ffi::OsStr::new).collect(); + let cli = Cli::parse_from(&args).expect("packaged service arguments must parse"); + assert_eq!(cli.config.file.as_deref(), Some("/etc/moq-relay/relay.toml")); + } + /// The relay's own default still applies once the released spellings are gone. #[test] fn the_relay_default_applies() { diff --git a/rs/moq-relay/src/connection.rs b/rs/moq-relay/src/connection.rs index f3bea95262c..bdace30947c 100644 --- a/rs/moq-relay/src/connection.rs +++ b/rs/moq-relay/src/connection.rs @@ -79,7 +79,6 @@ impl Connection { /// Admits and serves this connection until it closes. #[tracing::instrument("conn", skip_all, fields(id = self.id, remote = self.request.remote_addr().map(tracing::field::display), session = tracing::field::Empty))] pub async fn run(self) -> anyhow::Result<()> { - let peer_hop = self.request.peer_hop(); let (admitted, registration) = match self.admit().await { Ok(admitted) => admitted, Err(err) => { @@ -116,7 +115,6 @@ impl Connection { request = request.with_subscriber(publisher); } let session = request.ok().await?; - let _node_connection = peer_hop.map(|origin| self.cluster.nodes.connect_inbound(self.id, origin)); tracing::info!(version = %session.version(), %transport, "negotiated"); diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index c56f4f5ad61..dc13fde0099 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -17,8 +17,7 @@ //! crossing it, so they have no place on the `moq-stats` wire. //! - `/health` - a liveness mirror of the public probe, for internal checks //! that don't want to hit the customer port. -//! - `/nodes` - the cluster nodes visible through gossip plus established -//! direct relay connections. +//! - `/nodes` - the cluster peers this relay dialed and holds a session with. //! - `/sessions` and `/sessions/revalidate` - list or nudge live sessions on //! this node. A push only causes a re-check, so a caller on this trusted //! plane gains nothing a scheduled cadence would not do. @@ -292,11 +291,8 @@ async fn serve_metrics(State(state): State) -> Response { ([(http::header::CONTENT_TYPE, "text/plain; version=0.0.4")], body).into_response() } -/// Cluster nodes currently visible through gossip or a direct outbound dial. -/// -/// Inbound connections appear only after their SETUP origin identity resolves -/// to a unique `.internal/origins` node advertisement. Sessions without a -/// unique match are omitted. +/// Cluster peers this relay dialed and currently holds a session with. Accepted +/// peer sessions are omitted, since a peer declares no URL to list it under. async fn serve_nodes(State(state): State) -> Json { Json(state.nodes.map(|nodes| nodes.snapshot()).unwrap_or_default()) } @@ -886,8 +882,7 @@ mod tests { #[tokio::test] async fn nodes_endpoint_uses_the_attached_cluster_registry() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(moq_net::Hop::new(100).unwrap())); - let nodes = crate::nodes::Nodes::new(origin); + let nodes = crate::nodes::Nodes::default(); let _connection = nodes.connect_outbound(0, "https://relay-b.example/"); let state = InternalState { stats: moq_net::stats::Registry::disabled(), diff --git a/rs/moq-relay/src/nodes.rs b/rs/moq-relay/src/nodes.rs index 70823e9e8d2..3a0596fde5e 100644 --- a/rs/moq-relay/src/nodes.rs +++ b/rs/moq-relay/src/nodes.rs @@ -1,253 +1,84 @@ -//! The local cluster topology view behind the internal `/nodes` endpoint. +//! The local cluster view behind the internal `/nodes` endpoint. //! -//! Combines the node advertisements gossiped under [`MESH_PREFIX`] with the -//! direct relay sessions this process currently holds, so an operator can see -//! which peers are visible, which are connected, and who dialed whom. +//! Lists the peers this relay dialed and currently holds a session with, keyed +//! by the URL it dialed. Accepted peer sessions are not listed: a peer declares +//! no URL, so there is nothing to name it by. use std::{ collections::{BTreeMap, HashMap}, sync::{Arc, Mutex}, }; -use moq_net::{Hop, origin}; use serde::Serialize; -/// Namespace containing the empty broadcasts used to advertise cluster nodes. -pub(crate) const MESH_PREFIX: &str = ".internal/origins"; - -/// A local view of announced cluster nodes and established direct connections. -#[derive(Clone)] +/// Established outbound cluster connections, by `conn` id. +#[derive(Clone, Default)] pub(crate) struct Nodes { - origin: origin::Producer, - connections: Arc, -} - -#[derive(Default)] -struct Connections { - entries: Mutex>, -} - -#[derive(Clone)] -struct ConnectionRecord { - direction: Direction, - target: ConnectionTarget, -} - -#[derive(Clone)] -enum ConnectionTarget { - Node(String), - Hop(Hop), + connections: Arc>>, } /// The JSON document returned by the internal `/nodes` endpoint. #[derive(Debug, Default, Serialize)] pub(crate) struct Snapshot { - /// Announced or directly connected cluster nodes. + /// Dialed cluster nodes with a live session. pub nodes: Vec, } -/// One known cluster node in the local topology view. +/// One dialed cluster node. #[derive(Debug, Serialize)] pub(crate) struct Node { - /// Canonical URL advertised for the node. + /// Canonical URL this relay dialed, without its query. pub node: String, - /// Hop identity from the node's announcement, when available. - pub origin_id: Option, - /// Selected route for the node's internal advertisement. - pub announced: Option, - /// Established direct connections to this node. + /// Established connections to this node. pub connections: Vec, } -/// The selected route for a node advertisement. -#[derive(Debug, Serialize)] -pub(crate) struct Announcement { - /// Hop identities in traversal order, oldest first. - pub hops: Vec, - /// Number of hops in the selected route. - pub hop_count: usize, - /// Accumulated cost of the selected route as the mesh stands: zero at any relay - /// already carrying the broadcast. - pub cost: u64, - /// The same route priced with every warm discount removed, which is what ranks - /// two relays that both discounted to zero. - pub cold_cost: u64, -} - -/// An established direct cluster connection. +/// An established outbound cluster connection. #[derive(Debug, Serialize)] pub(crate) struct Connection { /// The session's `conn` id, matching the `conn{id}` span its log lines carry. /// Process-local, and only meaningful while the session lasts. pub id: u64, - /// Whether this relay accepted or initiated the connection. - pub direction: Direction, -} - -/// Direction of an established cluster connection. -#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)] -#[serde(rename_all = "lowercase")] -pub(crate) enum Direction { - /// A connection accepted from another relay. - Inbound, - /// A connection initiated by this relay. - Outbound, -} - -struct NodeBuilder { - origin_id: Option, - announced: Option, - connections: Vec, -} - -/// The advertisements one scan of the discovery namespace turned up. -#[derive(Default)] -struct Announced { - nodes: BTreeMap, - /// Hop id to the single node advertising it, or `None` once more than one - /// does and the id no longer identifies a peer. - origins: HashMap>, } -/// Removes a live connection from the topology view when its session ends. +/// Removes a live connection from the view when its session ends. pub(crate) struct ConnectionGuard { nodes: Nodes, id: u64, } impl Nodes { - pub(crate) fn new(origin: origin::Producer) -> Self { - Self { - origin, - connections: Arc::default(), - } - } - /// Record a dial this relay initiated, keyed by the URL it dialed. /// /// `id` is the session's `conn` id from /// [`Cluster::next_connection_id`](crate::cluster::Cluster::next_connection_id). pub(crate) fn connect_outbound(&self, id: u64, node: impl Into) -> ConnectionGuard { - self.connect(id, Direction::Outbound, ConnectionTarget::Node(node.into())) - } - - /// Record a session this relay accepted, keyed by the origin the peer declared. - /// - /// `id` is the session's `conn` id from - /// [`Cluster::next_connection_id`](crate::cluster::Cluster::next_connection_id). - pub(crate) fn connect_inbound(&self, id: u64, origin: Hop) -> ConnectionGuard { - self.connect(id, Direction::Inbound, ConnectionTarget::Hop(origin)) - } - - fn connect(&self, id: u64, direction: Direction, target: ConnectionTarget) -> ConnectionGuard { self.connections - .entries .lock() .expect("node connection registry poisoned") - .insert(id, ConnectionRecord { direction, target }); + .insert(id, node.into()); ConnectionGuard { nodes: self.clone(), id, } } - /// The node advertisements currently visible under [`MESH_PREFIX`]. - fn announced(&self) -> Announced { - match self - .origin - .consume() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - { - Ok(consumer) => self.scan_announced(&mut consumer.announced()), - Err(_) => Announced::default(), - } - } - - /// Drain every update the cursor has buffered into a node map. - fn scan_announced(&self, announced: &mut moq_net::announce::Consumer) -> Announced { - let mut scanned = Announced::default(); - - while let Some(event) = announced.try_next() { - // A retraction can land mid-drain (a re-announce is a metadata update, - // not a retract-and-announce). Skip it rather than end the scan, which - // would drop every node still queued behind it. - let (moq_net::announce::Event::Start(update) | moq_net::announce::Event::Update(update)) = event else { - continue; - }; - - let key = canonical_announced_node(update.prefix.as_str()); - let route = update.route; - let hop_ids = route.hops.iter().map(|origin| origin.id()).collect::>(); - // An advertisement with no hops never crossed a link, so it is our own. - let origin_id = hop_ids.first().copied().unwrap_or_else(|| self.origin.hop().id()); - - scanned - .origins - .entry(origin_id) - .and_modify(|current| { - if current.as_deref() != Some(&key) { - *current = None; - } - }) - .or_insert_with(|| Some(key.clone())); - - scanned.nodes.insert( - key, - NodeBuilder { - origin_id: Some(origin_id.to_string()), - announced: Some(Announcement { - hop_count: hop_ids.len(), - hops: hop_ids.into_iter().map(|origin| origin.to_string()).collect(), - cost: route.cost.warm, - cold_cost: route.cost.cold, - }), - connections: Vec::new(), - }, - ); - } - - scanned - } - pub(crate) fn snapshot(&self) -> Snapshot { - let Announced { mut nodes, origins } = self.announced(); - - let connections = self - .connections - .entries - .lock() - .expect("node connection registry poisoned"); - let mut connections = connections.iter().collect::>(); - connections.sort_by_key(|(id, _)| **id); - for (&id, connection) in connections { - let key = match &connection.target { - ConnectionTarget::Node(node) => canonical_node(node), - ConnectionTarget::Hop(origin) => { - let Some(Some(node)) = origins.get(&origin.id()) else { - continue; - }; - node.clone() - } - }; - let node = nodes.entry(key).or_insert_with(|| NodeBuilder { - origin_id: None, - announced: None, - connections: Vec::new(), - }); - node.connections.push(Connection { - id, - direction: connection.direction, - }); + let mut nodes = BTreeMap::>::new(); + let connections = self.connections.lock().expect("node connection registry poisoned"); + for (&id, node) in connections.iter() { + nodes + .entry(crate::cluster::canonicalize_peer_key(node)) + .or_default() + .push(Connection { id }); } Snapshot { nodes: nodes .into_iter() - .map(|(key, node)| Node { - node: key, - origin_id: node.origin_id, - announced: node.announced, - connections: node.connections, + .map(|(node, mut connections)| { + connections.sort_by_key(|connection| connection.id); + Node { node, connections } }) .collect(), } @@ -258,97 +89,37 @@ impl Drop for ConnectionGuard { fn drop(&mut self) { self.nodes .connections - .entries .lock() .expect("node connection registry poisoned") .remove(&self.id); } } -fn canonical_node(node: &str) -> String { - crate::cluster::canonicalize_peer_key(node) -} - -fn canonical_announced_node(node: &str) -> String { - canonical_node(&crate::cluster::advertised_node_url(node)) -} - #[cfg(test)] mod tests { use super::*; - use moq_net::{Hop, Hops}; - - async fn announced_node( - origin: &moq_net::origin::Producer, - node: &str, - hops: &[u64], - cost: u64, - ) -> moq_net::origin::Dynamic { - let hops = Hops::try_from( - hops.iter() - .map(|id| Hop::new(*id).expect("valid test origin")) - .collect::>(), - ) - .unwrap(); - let path = moq_net::Path::new(MESH_PREFIX).join(node); - let announcement = origin - .dynamic(&path, moq_net::origin::Route::default().with_hops(hops).with_cost(cost)) - .unwrap(); - origin.consume().routed(&path).await.expect("test node announced"); - announcement - } - - #[tokio::test] - async fn snapshot_combines_announcements_and_live_connections() { - const REMOTE_ID: u64 = 9_007_199_254_740_993; - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin.clone()); - let _remote = announced_node(&origin, "https://relay-b.example/", &[REMOTE_ID], 7).await; - let _outbound = nodes.connect_outbound(0, "https://relay-b.example/"); - let _inbound = nodes.connect_inbound(1, Hop::new(REMOTE_ID).unwrap()); + #[test] + fn snapshot_groups_live_connections_by_node() { + let nodes = Nodes::default(); + let _second = nodes.connect_outbound(1, "https://relay-b.example/"); + let _first = nodes.connect_outbound(0, "https://relay-b.example"); + let _other = nodes.connect_outbound(2, "https://relay-a.example/"); - let snapshot = nodes.snapshot(); - assert_eq!(snapshot.nodes.len(), 1); - let node = &snapshot.nodes[0]; - assert_eq!(node.node, "https://relay-b.example/"); - assert_eq!(node.origin_id.as_deref(), Some("9007199254740993")); - assert_eq!(node.announced.as_ref().unwrap().hops, vec!["9007199254740993"]); - assert_eq!(node.announced.as_ref().unwrap().hop_count, 1); - assert_eq!(node.announced.as_ref().unwrap().cost, 7); - assert_eq!(node.announced.as_ref().unwrap().cold_cost, 7); - assert_eq!(node.connections.len(), 2); - assert_eq!(node.connections[0].direction, Direction::Outbound); - assert_eq!(node.connections[1].direction, Direction::Inbound); assert_eq!( - serde_json::to_value(&snapshot).unwrap(), + serde_json::to_value(nodes.snapshot()).unwrap(), serde_json::json!({ - "nodes": [{ - "node": "https://relay-b.example/", - "origin_id": "9007199254740993", - "announced": { "hops": ["9007199254740993"], "hop_count": 1, "cost": 7, "cold_cost": 7 }, - "connections": [ - { "id": 0, "direction": "outbound" }, - { "id": 1, "direction": "inbound" } - ] - }] + "nodes": [ + { "node": "https://relay-a.example/", "connections": [{ "id": 2 }] }, + { "node": "https://relay-b.example/", "connections": [{ "id": 0 }, { "id": 1 }] } + ] }), ); } - #[tokio::test] - async fn snapshot_omits_unresolved_inbound_connections() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin); - let _inbound = nodes.connect_inbound(0, Hop::new(200).unwrap()); - - assert!(nodes.snapshot().nodes.is_empty()); - } - - #[tokio::test] - async fn snapshot_stops_reporting_closed_outbound_connections() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin); + #[test] + fn snapshot_stops_reporting_closed_outbound_connections() { + let nodes = Nodes::default(); let connection = nodes.connect_outbound(0, "https://relay-b.example/"); assert_eq!(nodes.snapshot().nodes.len(), 1); @@ -356,60 +127,11 @@ mod tests { assert!(nodes.snapshot().nodes.is_empty()); } - #[tokio::test] - async fn outbound_node_omits_credentials_from_url() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin); + #[test] + fn outbound_node_omits_credentials_from_url() { + let nodes = Nodes::default(); let _connection = nodes.connect_outbound(0, "https://relay-b.example/?jwt=secret"); assert_eq!(nodes.snapshot().nodes[0].node, "https://relay-b.example/"); } - - /// A re-announce reaches the cursor as unannounce-then-announce, so a bare - /// unannounce can sit ahead of nodes still queued behind it. Treating that as - /// the end of the scan would silently truncate `/nodes` whenever the cluster - /// churned mid-request. - #[tokio::test(start_paused = true)] - async fn scan_skips_an_unannounce_queued_ahead_of_another_node() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin.clone()); - let first = announced_node(&origin, "https://relay-a.example/", &[200], 1).await; - let _second = announced_node(&origin, "https://relay-b.example/", &[300], 1).await; - - let consumer = origin - .consume() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - .expect("mesh prefix is in root"); - let mut announced = consumer.announced(); - - // Take relay-a's replayed announce, then retire it so the cursor queues a - // bare unannounce ahead of relay-b's still-pending announce. - let Some(moq_net::announce::Event::Start(first_update)) = announced.try_next() else { - panic!("replayed announce"); - }; - assert_eq!( - canonical_announced_node(first_update.prefix.as_str()), - "https://relay-a.example/" - ); - drop(first); - - let scanned = nodes.scan_announced(&mut announced); - assert!( - scanned.nodes.contains_key("https://relay-b.example/"), - "the unannounce ahead of relay-b truncated the scan" - ); - } - - #[tokio::test] - async fn duplicate_origin_ids_do_not_resolve_inbound_connections() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin.clone()); - let _first = announced_node(&origin, "https://relay-b.example/", &[200], 1).await; - let _second = announced_node(&origin, "https://relay-c.example/", &[200], 1).await; - let _inbound = nodes.connect_inbound(0, Hop::new(200).unwrap()); - - let snapshot = nodes.snapshot(); - assert_eq!(snapshot.nodes.len(), 2); - assert!(snapshot.nodes.iter().all(|node| node.connections.is_empty())); - } } diff --git a/rs/moq-relay/src/uring.rs b/rs/moq-relay/src/uring.rs index 5119292b9b5..b7eabf5a433 100644 --- a/rs/moq-relay/src/uring.rs +++ b/rs/moq-relay/src/uring.rs @@ -757,7 +757,6 @@ async fn serve_connection( stats, } = admitted; - let peer_hop = request.peer_hop(); let mut request = request.with_stats(stats); if let Some(subscriber) = subscriber { request = request.with_publisher(subscriber); @@ -773,7 +772,6 @@ async fn serve_connection( err => tracing::debug!(%err, "session driver ended"), } }); - let node_connection = peer_hop.map(|origin| serve.cluster.nodes.connect_inbound(id, origin)); tracing::info!(id, version = %session.version(), transport = %moq_tokio::server::Transport::Quic, "negotiated"); @@ -782,7 +780,6 @@ async fn serve_connection( // and the shutdown broadcast on the shared runtime. let shutdown = serve.shutdown.clone(); serve.tokio.spawn(async move { - let _node_connection = node_connection; if let Err(err) = crate::connection::supervise(session, lease, shutdown, registration).await { tracing::warn!(id, %err, "connection closed"); } diff --git a/rs/moq-relay/src/web.rs b/rs/moq-relay/src/web.rs index 769ebf0a68b..c3fbd498946 100644 --- a/rs/moq-relay/src/web.rs +++ b/rs/moq-relay/src/web.rs @@ -917,7 +917,7 @@ async fn serve_fetch( let result = tokio::time::timeout_at(deadline, async { // NOTE: The auth token is already scoped to the broadcast. // Block until a route covers the broadcast (within the fetch deadline) so - // freshly-connected subscribers don't get a spurious 404 before gossip arrives. + // freshly-connected subscribers don't get a spurious 404 before the announce arrives. let consumer = origin.consume(); let broadcast = consumer.routed_broadcast("").await.map_err(|_| StatusCode::NOT_FOUND)?; let sequence = match params.group { diff --git a/rs/moq-relay/tests/auth_lifetime.rs b/rs/moq-relay/tests/auth_lifetime.rs index 3f33562ed95..0c35d93accc 100644 --- a/rs/moq-relay/tests/auth_lifetime.rs +++ b/rs/moq-relay/tests/auth_lifetime.rs @@ -4,10 +4,11 @@ //! or QUIC) or its axum WebSocket path (`serve_ws` over `ws://`), points it at a //! scripted auth server, connects a publisher and a subscriber, confirms media //! flows, then asserts the relay follows the server's word: a re-check that moves -//! the tier retags the live session's stats, a narrower grant or a refusal closes it, an outage -//! keeps it until `expires`, and every close reports `end` with what it moved. +//! the tier retags the live session's stats, a narrower grant or a refusal closes it, +//! and every close reports `end` with what it moved. //! The last tests swap the server for an in-process decider answering -//! `Admissions`, and prove the lease it drives reaches the session the same way. +//! `Admissions`, and prove the lease it drives reaches the session the same way, +//! including an outage that keeps it until `expires`, on Tokio's paused clock. use std::sync::{Arc, Mutex}; use std::time::{Duration, SystemTime}; @@ -748,60 +749,6 @@ async fn http_routes_hold_a_lease() { relay.abort(); } -/// An outage keeps the session until `expires`, then closes it as expired. -/// -/// On the real clock: a paused one jumps to the next timer whenever the runtime -/// waits on a socket, and macOS delivers loopback asynchronously, so a virtual -/// timeout can fire before the relay answers. Load only delays the close, so -/// asserting it never lands before `expires` holds on a busy machine. -#[tokio::test] -async fn an_outage_keeps_the_session_until_expires() { - // Whole seconds, as the grant crosses the wire, so the relay sees this exact instant. - let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap(); - let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(now.as_secs() + 3); - - let mut grant = grant(Duration::ZERO); - grant.expires = Some(expires); - let script = Script::new(grant); - script.on_revalidate(Answer::Status(503)); - let (port, relay) = spawn_relay(build_auth(script.spawn().await)).await; - let (pub_session, sub_session) = connect_and_round_trip(&room_url("tcp", port)).await; - - assert_closed(pub_session, TIMEOUT, "publisher").await; - assert!( - SystemTime::now() >= expires, - "an outage must not close the publisher before expires" - ); - let outages = script - .seen - .lock() - .unwrap() - .iter() - .filter(|r| r.event == Event::Revalidate) - .count(); - assert!(outages > 0, "no re-check reached the server during the outage"); - assert_closed(sub_session, TIMEOUT, "subscriber").await; - - let ends = tokio::time::timeout(TIMEOUT, async { - loop { - let ends = script.ends(); - if ends.len() == 2 { - return ends; - } - tokio::time::sleep(Duration::from_millis(10)).await; - } - }) - .await - .expect("both sessions report their end"); - for end in ends { - let Event::End { reason, .. } = &end.event else { - unreachable!() - }; - assert_eq!(*reason, moq_auth::lease::Reason::Expired); - } - relay.abort(); -} - /// A session the client closes reports `end` with its duration and byte counters. /// Over QUIC, the one transport whose connection reports its totals. #[tokio::test] @@ -1043,6 +990,98 @@ async fn a_fixed_lease_still_expires() { } } +/// A connected `(client, server)` session pair over an in-memory byte stream, so a +/// test on Tokio's paused clock never waits on a socket: the clock only advances +/// once every byte in flight has landed. +async fn memory_sessions() -> (moq_net::Session, moq_net::Session) { + let config = || { + let mut config = qmux::Config::new(qmux::Version::QMux01); + config.protocol = qmux::Protocol::Negotiate(moq_net::ALPNS.iter().map(|alpn| alpn.to_string()).collect()); + config + }; + let stream = |io| qmux::transport::Stream::new(io, qmux::Version::QMux01, config().max_record_size); + let (client, server) = tokio::io::duplex(64 * 1024); + let (client, server) = tokio::try_join!( + qmux::Session::connect(stream(client), config()), + qmux::Session::accept(stream(server), config()), + ) + .expect("qmux handshake"); + + let now = tokio::time::Instant::now().into_std(); + let client = async { + let (session, driver) = moq_net::Client::new() + .connect(now, moq_tokio::transport::Session::new(client)) + .await + .expect("client handshake"); + tokio::spawn(moq_net::time::run(driver)); + session + }; + let server = async { + let (session, driver) = moq_net::Server::new() + .accept(now, moq_tokio::transport::Session::new(server)) + .await + .expect("server handshake"); + tokio::spawn(moq_net::time::run(driver)); + session + }; + tokio::join!(client, server) +} + +/// An outage keeps the session until `expires`, then closes it as expired and +/// reports that as its end. A decider that never answers again is an outage as +/// far as the relay can tell, so the relay enforces `expires` itself; how an auth +/// server's outage keeps the grant is `moq_auth::Client`'s to test. +#[tokio::test(start_paused = true)] +async fn an_outage_keeps_the_session_until_expires() { + let expires = SystemTime::now() + Duration::from_secs(3); + let (auth, mut admissions) = moq_relay::auth::Auth::embedded("test-relay"); + let decider = tokio::spawn(async move { + let admission = admissions.next().await.expect("an admission"); + let mut grant = Grant::new(all(), all()); + grant.expires = Some(expires); + let (producer, consumer) = moq_auth::lease::Producer::new(grant); + admission.grant(consumer); + producer + }); + + // `expires` is wall-clock time, which the relay maps onto Tokio's clock + // somewhere inside `admit`, so bracket it: the bounds hold however long it takes. + let (wall, tick) = (SystemTime::now(), tokio::time::Instant::now()); + let lease = auth + .admit(auth.request(moq_auth::Transport::Tcp, "/room")) + .await + .expect("admitted"); + let earliest = tick + expires.duration_since(SystemTime::now()).unwrap(); + let latest = tokio::time::Instant::now() + expires.duration_since(wall).unwrap(); + let producer = decider.await.expect("decider"); + + let (client, server) = memory_sessions().await; + let supervised = tokio::spawn(moq_relay::supervise( + server, + lease, + moq_relay::shutdown::Observer::disabled(), + None, + )); + + // A millisecond either side for Tokio's timer resolution. + let tolerance = Duration::from_millis(1); + assert!( + tokio::time::timeout_at(earliest - tolerance, client.closed()) + .await + .is_err(), + "an outage must not close the session before expires" + ); + tokio::time::timeout_at(latest + tolerance, client.closed()) + .await + .expect("closed at expires, not later"); + let (reason, _) = producer.closed().await; + assert_eq!(reason, moq_auth::lease::Reason::Expired); + supervised + .await + .expect("supervisor") + .expect("a lease end is not a session error"); +} + /// A relay whose config names no auth source is the embedder's to decide: `run` /// refuses to start until the admissions are taken, and once they are, the /// decider's grant admits sessions through the assembled relay. diff --git a/rs/moq-relay/tests/cluster_unknown.rs b/rs/moq-relay/tests/cluster_unknown.rs index e6b9c5b33a7..cf750a24f67 100644 --- a/rs/moq-relay/tests/cluster_unknown.rs +++ b/rs/moq-relay/tests/cluster_unknown.rs @@ -1,6 +1,6 @@ //! Regression for an external publisher whose protocol does not declare a Hop ID. -//! The relay records that publisher as `Hop::UNKNOWN`; reflected cluster paths -//! must not replace it while gossiping around a redundant mesh. +//! The relay stamps that publisher with a random Hop ID of the connection's own; +//! reflected cluster paths must not replace it while propagating around a redundant mesh. use std::time::Duration; @@ -105,8 +105,8 @@ async fn publish_version(port: u16, version: &str) -> Publisher { } async fn publish_unknown(port: u16) -> Publisher { - // Draft-14 has no Cluster extension, so the accepting relay must represent - // this external publisher with the wire-defined UNKNOWN Hop ID. + // Draft-14 has no Cluster extension, so the accepting relay must name this + // external publisher with a stamp of its own. publish_version(port, "moq-transport-14").await } @@ -226,7 +226,7 @@ async fn assert_unknown_publisher_stays_announced(cluster_version: Option