justfile

#!/usr/bin/env just --justfile
#
# Language-specific recipes for the Rust workspace under rs/. Invoked from
# the repo root as `just rs <recipe>` via the `mod rs` import.
#
# The Rust crates form a single workspace whose root Cargo.toml lives at
# the repository root, so these recipes run from the repo root rather than
# from rs/ (cargo resolves paths relative to the workspace root either way).

set working-directory := '..'

default:
    just check

# Default features only, here and in CI. The permutations (`--all-features`,
# `--no-default-features`) each cost a full extra workspace compile that shares
# almost nothing with this one, which is too slow for a per-PR gate; `features`
# below covers them nightly.
#
# 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.
#
# A bare `just rs check` is default-members, which skips libmoq, 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.

# Compile, lint, format-check, doc-check, and verify dependency hygiene.
check *args:
    just rs _select-test
    just rs _publish-test
    cargo clippy --locked --all-targets {{ args }} -- -D warnings
    cargo fmt --all --check
    RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps {{ args }}
    cargo shear
    cargo sort --workspace --check --no-format

# Auto-fix clippy/format/shear/sort.
fix *args:
    cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets {{ args }}
    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/<crate>/...`), 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)

    # Every 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 (libmoq, 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/libmoq 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 <id>` 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 <name>` literally and silently stopped
# firing the moment the spec form changed. Ids are `path+file://<dir>#<version>`
# and `_select` has already verified every crate directory matches its 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")"

# 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' ' '

# 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

    # 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"

    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.
[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

    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.
check-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 check --workspace ;;
    	*)     echo "rs: checking $(just rs _names "$packages")"; just rs check $packages ;;
    esac

    # 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

# 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 ;;
    	*)     echo "rs: fixing $(just rs _names "$packages")"; just rs fix $packages ;;
    esac

    # 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(target_os = "windows")]` code past the compiler: moq-video's
# Media Foundation capture/encode/decode and its D3D11 frames, which the Linux
# gate skips entirely. Cross-compiling can't stand in, because openh264-sys2
# builds vendored C++ that needs an MSVC toolchain and openh264 is a
# non-optional dependency.
#
# Nothing in CI runs this. Windows runners cost too much for a per-PR gate, so
# the code compiles for the first time in a tag-triggered release build unless
# someone runs this by hand on a Windows host.
#
# Default features rather than `--all-features`: jemalloc and the quiche
# backend don't build on MSVC, while moq-video's Linux-only `nvidia` default
# are already no-ops off Linux. moq-gst is excluded because it links
# GStreamer via pkg-config, which the Windows runner doesn't have.
#
# `moq-cli/play` is named explicitly because it's off by default and is what
# turns on moq-video's wgpu renderer and moq-audio's cpal output, neither of
# which any default-feature build compiles.

# Compile the whole workspace on a Windows host. Must run ON Windows.
windows *args:
    cargo check --locked --workspace --exclude moq-gst --all-targets --features "moq-cli/play moq-cli/capture" {{ args }}

# Runs the `#[cfg(target_os = "macos")]` code past the compiler: moq-video's
# VideoToolbox encode/decode and its ScreenCaptureKit / AVFoundation capture,
# plus moq-audio's ScreenCaptureKit system audio and TCC permission pre-check.
#
# Nothing in CI runs this either; Mac runners cost too much for a per-PR gate.
# The moq-video half has a release-time backstop, since libmoq's `libmoq-v*` tag
# build compiles it on Apple Silicon. The moq-audio half has none: its
# capture backend is behind an off-by-default feature no release build enables,
# so this recipe is the only thing that ever compiles it.
#
# Scoped to those two crates instead of the workspace, because they hold all
# the Apple-gated code the Linux gate misses. moq-ffi (and through it the
# Swift/Kotlin/Go wrappers) already compiles on macOS in swift.yml.
# `--all-features` is required, not just tidy: moq-audio's capture backend sits
# behind an off-by-default feature, so a plain check would skip the very code
# this recipe exists for. moq-video's Linux-only nvidia/vaapi/pipewire
# deps are no-ops here.

# Compile the Apple-only code paths. Must run ON macOS.
macos *args:
    cargo check --locked -p moq-video -p moq-audio --all-targets --all-features {{ 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.

# `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.

# Compile and lint the browser/WASM bindings, which the host-target check skips.
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.

# Auto-fix the browser/WASM bindings.
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 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:
    cargo deny check --show-stats

# 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,
# moq-audio's capture backend, quiche, and jemalloc. `--no-default-features` is
# the only thing that compiles the `#[cfg(not(feature = ...))]` arms.

# Compile the workspace at the feature extremes.
features:
    cargo check --locked --workspace --no-default-features
    cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
    RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
    cargo nextest run --locked --workspace --all-targets --all-features

# 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 test` dispatches to.
#
# clippy-driver as the compiler wrapper is rustc plus the lint passes, so this
# one compilation both builds the test binaries and reports clippy findings.
# `cargo clippy` can't be reused here: it asks cargo for metadata only, and a
# metadata build and a codegen build have different fingerprints, so running
# both compiles the dependency tree twice. Linting here is free, which makes
# `just test` a single-compile substitute for `check` + `test` on a laptop.
#
# RUSTC_WORKSPACE_WRAPPER, not RUSTC_WRAPPER, for two reasons. Cargo folds it
# into the fingerprint, so a crate already built by a plain `cargo test` is
# rebuilt through clippy rather than silently reported as fresh with no
# findings. And it applies to workspace crates only, so dependencies keep the
# artifacts they share with plain cargo instead of duplicating the whole tree.
# It is also what `cargo clippy` sets internally.
#
# Findings stay warnings rather than errors. `check` is the gate (it runs
# `clippy -D warnings`), and a hard failure here would block running the tests
# over an unused import while you are mid-edit.
#
# No RUSTFLAGS: it is part of cargo's fingerprint too, so setting it here would
# split the artifact cache against every other cargo invocation, including CI's
# warm cache. Skips the wrapper entirely when clippy-driver is absent.

# Run the test suite, reporting clippy findings from the same compile.
test *args:
    RUSTC_WORKSPACE_WRAPPER="$(command -v clippy-driver || true)" cargo nextest run --locked --all-targets {{ args }}

# Same selection as `check-changed`: compiling a crate's test binaries is the
# expensive half of a test run, so scoping matters more here than anywhere else.
#
# `--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 ;;
    	*)     echo "rs: testing $(just rs _names "$packages")"; just rs test --no-tests=pass $packages ;;
    esac

# Compile and run the `/// ```` examples, which nextest skips.
doctest *args:
    cargo test --locked --doc {{ args }}

# 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).
#
# The search is deliberately unbounded (no `preemption_bound`), so it covers
# every interleaving rather than just the short ones.
#
# kio's own unit tests are `cfg(not(loom))`: they'd construct loom primitives
# outside `loom::model`, which panics.
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 }}

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' --client-connect '{{ url }}' {{ 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

# 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
package crate packager:
    #!/usr/bin/env bash
    set -euo pipefail
    case "{{ crate }}" in
    	moq-relay)      bin=moq-relay  ;;
    	moq-cli)        bin=moq        ;;
        moq-token-cli)  bin=moq-token  ;;
    	*) echo "Unknown crate: {{ crate }} (use moq-relay, moq-cli, or moq-token-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" \
    	nfpm pkg --packager {{ packager }} \
    		--config packaging/{{ crate }}/nfpm.yaml \
    		--target dist/
    ls -1 dist/