diff --git a/README.md b/README.md index fc4220c10cb..7b43df709d6 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Full documentation lives at **[doc.moq.dev](https://doc.moq.dev)**. - **[Linux packages](https://doc.moq.dev/setup/install)** - install the relay and GStreamer plugin from `apt.moq.dev` / `rpm.moq.dev`. - **[Production setup](https://doc.moq.dev/setup/prod)** - deploy a relay with a real domain and TLS. -The quickest way to see it in action (requires [Nix](https://nixos.org/download.html) with [flakes](https://nixos.wiki/wiki/Flakes)): +The quickest way to see it in action (requires [Nix](https://nixos.org/download.html) with [flakes](https://wiki.nixos.org/wiki/Flakes)): ```sh # Runs a relay, demo media, and the web server diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 8960b1a7da4..d236918bde0 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -243,7 +243,7 @@ should prefer the canonical name and fall back to the legacy one. "requests": 3, "sessions_started": 12, "sessions_ended": 10, "sessions": 12, "sessions_closed": 10, "sent_bytes": 1048576, "received_bytes": 524288, - "sessions_refused": { "refused": 0, "unavailable": 0, "request": 0, "forbidden": 0, "lan": 0 }, + "sessions_refused": { "refused": 0, "unavailable": 0, "request": 0, "forbidden": 0, "lan": 0, "expired": 0 }, "sessions_failed": { "idle_timeout": 1, "transport": 0, "application": 0, "expired": 0 }, "announces_peak": 40, "subscriptions_peak": 900, "wire_tx": 2048, "wire_rx": 1024 diff --git a/doc/index.md b/doc/index.md index 5997d10855d..1e4fcafa10a 100644 --- a/doc/index.md +++ b/doc/index.md @@ -90,7 +90,7 @@ See the [concepts](/concept/) page for a breakdown of the layering, rationale, a ## Setup -Get up and running in seconds with [Nix](https://nixos.org/download.html) ([+Flakes](https://nixos.wiki/wiki/Flakes)), or be lame and [install stuff manually](/setup/install): +Get up and running in seconds with [Nix](https://nixos.org/download.html) ([+Flakes](https://wiki.nixos.org/wiki/Flakes)), or be lame and [install stuff manually](/setup/install): ```bash # Runs a relay, media publisher, and the web server diff --git a/go/wrapper/README.md b/go/wrapper/README.md index f109e62cb54..049e1af44e8 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -130,7 +130,7 @@ the session closed, i.e. not a real failure) and `moq.IsAuthError(err)` (HTTP Every call that can block takes a `context.Context` and aborts cleanly when it is cancelled, leaving nothing running in the background. A one-shot call (a subscribe, -a fetch, `RequestBroadcast`, `Resolve`, `Used`/`Unused`, `Server.Accept`) aborts on +a fetch, `RequestBroadcast`, `Resolve`, `WantedChanged`, `Used`/`Unused`, `Server.Accept`) aborts on its own and leaves the object usable; a stream read cancels the stream it reads. See the package doc for details. diff --git a/go/wrapper/doc.go b/go/wrapper/doc.go index 867586ccbbc..e8294ca06e9 100644 --- a/go/wrapper/doc.go +++ b/go/wrapper/doc.go @@ -24,8 +24,9 @@ // owner. // // What a cancel tears down depends on the call. A one-shot call (a subscribe, a -// fetch, RequestBroadcast, Resolve, a TrackDemand's Used/Unused, Server.Accept) -// aborts on its own and leaves the object it was made on usable, so the same +// fetch, RequestBroadcast, Resolve, a TrackDemand's WantedChanged, a +// GroupDemand's Used/Unused, Server.Accept) aborts on its own and leaves the +// object it was made on usable, so the same // broadcast, producer, or server takes the next call. A stream read (any Next, // RecvGroup, ReadFrame, or the iterators over them) instead cancels the stream // it reads, which is what a range loop over a cancelled context wants: the diff --git a/js/auth/src/algorithm.ts b/js/auth/src/algorithm.ts index 6f822b25c63..1e0197dcde5 100644 --- a/js/auth/src/algorithm.ts +++ b/js/auth/src/algorithm.ts @@ -17,4 +17,5 @@ export const AlgorithmSchema = z.enum([ "PS512", "EdDSA", ]); +/** A value parsed by {@link AlgorithmSchema}. */ export type Algorithm = z.infer; diff --git a/js/auth/src/claims.ts b/js/auth/src/claims.ts index 363a978afc5..ddb8fdb9371 100644 --- a/js/auth/src/claims.ts +++ b/js/auth/src/claims.ts @@ -50,6 +50,7 @@ export const ScopeSchema = z }), ); +/** A value parsed by {@link ScopeSchema}. */ export type Scope = z.output; const ClaimsFields = { diff --git a/js/auth/src/contract.ts b/js/auth/src/contract.ts index 85b8aee9624..62f9a03651b 100644 --- a/js/auth/src/contract.ts +++ b/js/auth/src/contract.ts @@ -45,10 +45,12 @@ export const TransportSchema = z.pipe( "unknown", ), ); +/** A value parsed by {@link TransportSchema}. */ export type Transport = z.infer; /** The single direction a client declared at SETUP. */ export const RoleSchema = z.enum(["publisher", "subscriber"]); +/** A value parsed by {@link RoleSchema}. */ export type Role = z.infer; /** @@ -67,6 +69,7 @@ export const PeerSchema = z.object({ /** The issuer's distinguished name. */ issuer: z.string(), }); +/** A value parsed by {@link PeerSchema}. */ export type Peer = z.infer; /** A credential from a moq-transport SETUP's `AUTHORIZATION TOKEN` option, unparsed. */ @@ -78,6 +81,7 @@ export const TokenSchema = z.object({ .string() .check(z.regex(/^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-][AQgw]|[A-Za-z0-9_-]{2}[AEIMQUYcgkosw048])?$/)), }); +/** A value parsed by {@link TokenSchema}. */ export type Token = z.infer; /** Byte totals for a session, both directions from the relay's point of view. */ @@ -87,6 +91,7 @@ export const BytesSchema = z.object({ /** Bytes the relay received from the peer. */ received: z.int().check(z.nonnegative()), }); +/** A value parsed by {@link BytesSchema}. */ export type Bytes = z.infer; const BaseRequestSchema = z.object({ @@ -143,6 +148,7 @@ export const RequestSchema = z.discriminatedUnion("event", [ bytes: BytesSchema, }), ]); +/** A value parsed by {@link RequestSchema}. */ export type Request = z.infer; /** @@ -186,6 +192,7 @@ export const GrantSchema = z message: "an upstream grant must be a peer", }), ); +/** A value parsed by {@link GrantSchema}. */ export type Grant = z.infer; /** The reason and verified attribution an auth server returns with HTTP 403. */ diff --git a/js/auth/src/key.ts b/js/auth/src/key.ts index 82e090801ae..ab16e0ab450 100644 --- a/js/auth/src/key.ts +++ b/js/auth/src/key.ts @@ -15,12 +15,14 @@ export const KeyIdSchema = z.string().check( message: "Key ID must contain only alphanumeric characters, hyphens, and underscores", }), ); +/** A value parsed by {@link KeyIdSchema}. */ export type KeyId = z.infer; /** * Key operations that can be performed */ export const OperationSchema = z.enum(["sign", "verify", "decrypt", "encrypt"]); +/** A value parsed by {@link OperationSchema}. */ export type Operation = z.infer; const MIN_HMAC_SECRET_BYTES = 32; @@ -108,10 +110,15 @@ const OkpKeySchema = z.extend(BaseKeySchema, { }); const CanonicalKeySchema = z.discriminatedUnion("kty", [OctKeySchema, RsaKeySchema, EcKeySchema, OkpKeySchema]); +/** A JSON Web Key of any supported type: oct, RSA, EC, or OKP. */ export const KeySchema = CanonicalKeySchema; +/** A value parsed by {@link KeySchema}. */ export type Key = z.infer; +/** An RSA, EC, or OKP key. */ export type AsymmetricKey = Exclude; +/** An oct (HMAC secret) key. */ export type SymmetricKey = Extract; +/** An asymmetric key without its private parameters. */ export type PublicKey = Omit; /** Derive a verify-only copy of this key, dropping the private material. */ diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 6856709b65e..1ed0d54a86e 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -22,6 +22,7 @@ export const VERSION = 4; /** A catalog needs a newer moq-hang draft than this reader implements. */ export class UnsupportedVersion extends Error { + /** The catalog version that was read. */ readonly version: number; constructor(version: number) { @@ -114,6 +115,7 @@ export const MAX_RENDITIONS = 64; /** A catalog update announced more media renditions than a reader will retain. */ export class TooManyRenditions extends Error { + /** How many renditions the catalog lists. */ readonly count: number; constructor(count: number) { @@ -125,6 +127,7 @@ export class TooManyRenditions extends Error { /** A catalog update used one rendition ID for both a video and an audio rendition. */ export class DuplicateRendition extends Error { + /** The rendition ID used for both video and audio. */ readonly id: string; constructor(id: string) { diff --git a/js/json/src/diff.ts b/js/json/src/diff.ts index e399572f392..9c860acc5d2 100644 --- a/js/json/src/diff.ts +++ b/js/json/src/diff.ts @@ -1,14 +1,17 @@ // RFC 7396 JSON Merge Patch: generate a patch between two values, and apply one. +/** The result of diffing two values. */ export interface Diff { - // A merge patch transforming the old value into the new one. + /** A merge patch transforming the old value into the new one. */ patch: unknown; - // Set when the change can't be faithfully expressed as a merge patch, so the caller should - // publish a full snapshot instead. This happens when a value is set to null, or an object - // holding a null is written whole, since merge patch reads a null as a key deletion. Arrays are - // fine: merge patch replaces them wholesale, which is still typically smaller than a full - // snapshot. + /** + * Set when the change can't be faithfully expressed as a merge patch, so the caller should + * publish a full snapshot instead. This happens when a value is set to null, or an object + * holding a null is written whole, since merge patch reads a null as a key deletion. Arrays are + * fine: merge patch replaces them wholesale, which is still typically smaller than a full + * snapshot. + */ forcedSnapshot: boolean; } diff --git a/js/net/src/auth.ts b/js/net/src/auth.ts index ca0a4f90507..6a191369d5d 100644 --- a/js/net/src/auth.ts +++ b/js/net/src/auth.ts @@ -123,12 +123,15 @@ export interface Handle { /** The {@link Handle} of a session without AUTH: no grant, and no tokens. */ export class None implements Handle { + /** Always undefined: no token is ever granted. */ readonly grant: Getter = new Signal(undefined); + /** Always rejects with {@link Unsupported}. */ add(_token: string | Uint8Array): Promise { return Promise.reject(new Unsupported()); } + /** A stream that never yields a request. */ requests(): Requests { return { next: async () => undefined, close: () => {} }; } diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index 9017b38e936..f5e3a83391c 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -28,6 +28,7 @@ export const HopSchema = z .check(z.refine((value) => value >= 0n && value < 1n << 62n, "Hop must be a non-negative 62-bit integer")) .brand("Hop"); +/** A relay's hop id, validated by {@link HopSchema}. */ export type Hop = z.infer; // pending: /quest/m1/public-model/answer.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 6b14f225f7e..12f1d05cda8 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -95,7 +95,6 @@ Each lands its fixes in its own PR and plans only what needs a decision. - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - every first-party publisher that can restart mints a fresh route epoch, the newest wins a path, and only routes with the same epoch resume a subscription - [Performance audit](/quest/m0/audit-perf.md) - benchmarks that regressed since the last run are explained, fixed, or planned, and unbenched hot paths get coverage - [Compile time audit](/quest/m0/audit-compile-time.md) - build-time hotspots are measured against a baseline and the worst are fixed or planned -- [Documentation audit](/quest/m0/audit-docs.md) - stale pages, examples, links, and undocumented exports are fixed or planned - [Dependency and alternatives audit](/quest/m0/audit-deps.md) - dependencies are current, deduplicated, needed, and the best maintained option - [Artifact size audit](/quest/m0/audit-size.md) - binary, FFI, WASM, and bundle growth since the last run is explained, fixed, or planned - [Simplification audit](/quest/m0/audit-simplify.md) - overbuilt code and APIs are collapsed, merged, or narrowed into a net simpler whole diff --git a/quest/m0/audit-docs.md b/quest/m0/audit-docs.md deleted file mode 100644 index d50ec4ffa3d..00000000000 --- a/quest/m0/audit-docs.md +++ /dev/null @@ -1,61 +0,0 @@ -# [M] Documentation audit - -## Goal - -Docs match the code: stale pages, broken examples, broken links, and -undocumented exported symbols are fixed or planned. - -## Plan - -Recurs once per major release (decided 2026-10-19). The PR that finishes -this run also adds the next one with the same file name at the end of the next -milestone's `Required` (m0 to m1, m1 to m2). The successor keeps the Goal -and this paragraph; the rest of its Plan is rewritten with what this run -learned: baselines, results, and what to check first. A successor placed in m2 -also lists the [release cut](/quest/m2/release/cut.md) under `Required`, so it -waits for the release in flight to ship. Only `/quest-delete` ends the -recurrence. Fixes land in the run's PR, one commit each, rather than as follow-ups. -Only a change that needs a maintainer decision (public API, scope) or is -independently landable and too large to review alongside the rest becomes a -follow-up through `/quest-plan`. - -Follow `doc/AGENTS.md` for what belongs in `doc/`. Starting points -(2026-10-19): check every CLI example against `--help`, and walk the -Cross-Package Sync table in AGENTS.md for changes merged since the previous -run that skipped a target. `#![warn(missing_docs)]` is set in 12 of 42 -crates; find the published ones without it. VitePress -checks internal links only; nothing checks external ones (try `lychee`). - -Audit checkpoint (2026-10-19, base `82c2d5dde`): - -- Corrected TS Opus and FLV/RTMP codec support, including the stale claim that - MP3 is dropped. Corrected Rust browser-driver setup, the net type example, - and the spawned connection lifecycle. Corrected JSON/flate snapshot docs: - untimed groups are subject to wall-clock staleness too. -- Replaced the production recipe's retired `[auth].key` with an auth-server - URL and the `moq auth serve --key` process it needs. -- Checked 259 distinct external URLs from 69 documentation pages: 217 - answered successfully. Verified unavailable RTSP/ICE, RTC wire, C, Python, - and Swift references and replaced them with current repository source. - Crates.io's HTML routes return 404 to this checker even for existing - packages, whose API routes work; protocol endpoints and example hosts are - not website health checks. Sixteen sites refused HEAD with 403 and still - need manual verification. Every GitHub `main` source path in the pages exists. -- Built the default-feature `moq` binary and checked 34 help contexts. - All 37 complete, supported shell examples parsed with `--help`; seven - examples need optional capture/play/transcode/iroh features. Gateway and - inspection pages use supported flags. Feature-only flags were checked - against their declarations, but those builds and GStreamer inspection - remain to be exercised. -- The stats documentation validator, `quest check` (438 documents), and - `git diff --check` passed, and so did `just check` on the changed packages - (the doc site and the JS packages). -- The exported-symbol audit is incomplete. Of 38 Rust library roots, 12 - enable `missing_docs`; 24 publishable roots do not: hang, kio, libmoq, - moq-archive, moq-audio, moq-auth, moq-c, moq-clock, moq-ffi, moq-flate, - moq-gst, moq-json, moq-loc, moq-msf, moq-mux, moq-native, moq-nvenc, - moq-relay, moq-sock, moq-stats, moq-transcode, moq-uring, moq-v4l, and - moq-video. This is lint coverage, not a claim that each has missing docs. - Run rustdoc with missing-doc diagnostics, review public TypeScript exports, - and finish the Cross-Package Sync walk before calling this run complete. - Do not add the successor until that work and the remaining checks pass. diff --git a/quest/m1/README.md b/quest/m1/README.md index c04d1716770..b644de46934 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -122,6 +122,9 @@ lands before the cut. - [Exporters follow a rendition to a new track](/quest/m1/export-rendition-rebind.md) - the fMP4, TS, MKV and FLV exporters rebuild a rendition whose resolved `track` or `broadcast` changes under the same ID - [lite-06 max sequence](/quest/m1/lite06-max-sequence.md) - group sequence 2^62-1 reaches a lite-06 subscriber or is refused loudly, instead of vanishing - [Track live signal](/quest/m1/track-live.md) - a reader can wait for its track's feed to be live, so a player skips old cached groups while a fresh upstream subscription starts +- [moq-mux docs](/quest/m1/docs-mux.md) - every public moq-mux item has rustdoc and the crate warns on missing docs +- [Binding docs](/quest/m1/docs-bindings.md) - every public moq-ffi and moq-c item has rustdoc, carried into the generated bindings and `moq.h` +- [JS export docs](/quest/m1/docs-js.md) - every public JS export and class member has TSDoc, and `just check` enforces it - [C++ and OBS package proof](/quest/m1/cpp-package-check.md) - the installed artifacts pass before their first release @@ -130,6 +133,7 @@ lands before the cut. - [Dead code and API surface audit](/quest/m1/audit-dead-code.md) - repeat the removal audit before the next major release - [Test coverage audit](/quest/m1/audit-test-coverage.md) - repeat the coverage audit against the m0 baselines before the next major release - [Test and CI cost audit](/quest/m1/audit-test-cost.md) - the slowest, flakiest, and least valuable tests and CI jobs are fixed, deleted, or planned +- [Documentation audit](/quest/m1/audit-docs.md) - stale pages, examples, links, and undocumented exports are fixed or planned ## Related diff --git a/quest/m1/audit-docs.md b/quest/m1/audit-docs.md new file mode 100644 index 00000000000..2d42dc72f42 --- /dev/null +++ b/quest/m1/audit-docs.md @@ -0,0 +1,57 @@ +# [M] Documentation audit + +## Goal + +Docs match the code: stale pages, broken examples, broken links, and +undocumented exported symbols are fixed or planned. + +## Plan + +Recurs once per major release (decided 2026-10-19). The PR that finishes +this run also adds the next one with the same file name at the end of the next +milestone's `Required` (m0 to m1, m1 to m2). The successor keeps the Goal +and this paragraph; the rest of its Plan is rewritten with what this run +learned: baselines, results, and what to check first. A successor placed in m2 +also lists the [release cut](/quest/m2/release/cut.md) under `Required`, so it +waits for the release in flight to ship. Only `/quest-delete` ends the +recurrence. Fixes land in the run's PR, one commit each, rather than as follow-ups. +Only a change that needs a maintainer decision (public API, scope) or is +independently landable and too large to review alongside the rest becomes a +follow-up through `/quest-plan`. + +Follow `doc/AGENTS.md` for what belongs in `doc/`. The m0 run (2026-10-19) +fixed stale codec, driver, auth, snapshot, Go wrapper, and stats-example +claims, documented every public item in hang, moq-archive, moq-auth, +moq-relay, and moq-nvenc, and filled the core JS packages' gaps. Start by +comparing against these baselines: + +- Rust: 26 crates set `#![warn(missing_docs)]`. Count the rest with + `cargo rustdoc -p --lib --all-features -- -W missing_docs`; only + `--all-features` reaches feature-gated items, which is how the m0 run found + moq-auth's undocumented server refusals, and `just rs wasm` reaches + wasm-only items such as kio's `MaybeSend`. `moq-mux`, `moq-ffi`, and `moq-c` + have follow-ups. `moq-video`, `moq-audio`, and `moq-sock` are documented on + Linux but stay unlinted: they gate public items on macOS, Windows, and + Android, and the dev shell has no std for those targets, so a lint could + only be verified in the merge queue's platform jobs. `moq-gst` cannot lint + because `gst::plugin_define!` emits undocumented public items. `moq-v4l` + is a fork of the `v4l` crate with 222 undocumented hand-written items beside + its generated `sys` bindings; decide whether a fork earns docs before + writing them. `libmoq` and the `moq-native` tombstone export nothing. +- JS: no tool checks doc comments; the [follow-up](/quest/m1/docs-js.md) adds + one. Until it lands, walk each published package's `exports` with the + TypeScript compiler API. The m0 baseline was 608 exports with 84 + undocumented and 676 public class members with 159 undocumented, nearly all + in `@moq/publish`, `@moq/watch`, and `@moq/boy`. +- Links: GET (not HEAD) every external URL in `doc/` with a browser user + agent; 262 answered except npmjs.com package pages, which refuse + non-browser clients (check `registry.npmjs.org/` instead), and + placeholder hosts. crates.io answers 200 to such a GET. +- CLI: all complete shell examples parse with `--help` appended against a + build with `capture,play,transcode,iroh,openh264`, which unknown flags fail + but bad values do not. `gst-inspect-1.0` of a debug `moq-gst` build lists + every element and pad property `doc/bin/gstreamer.md` names. +- Cross-Package Sync: walked from the 2026-10-16 release cut (`d0b086e71b`) + through `9b90cdd569`. Walk the next run from there. The table's Go row + and `rs/moq-ffi/AGENTS.md` name `go/wrapper/moq`, which does not exist; + the wrapper is `go/wrapper/*.go` and its subpackages. diff --git a/quest/m1/docs-bindings.md b/quest/m1/docs-bindings.md new file mode 100644 index 00000000000..c89a595def3 --- /dev/null +++ b/quest/m1/docs-bindings.md @@ -0,0 +1,22 @@ +# [M] Document the moq-ffi and moq-c APIs + +## Goal + +Every public item in `moq-ffi` and `moq-c` has a one-line rustdoc, so the +generated bindings and `moq.h` carry it, and both crates set +`#![warn(missing_docs)]`. + +## Plan + +The m0 documentation audit (2026-10-19) found 116 undocumented public items +in `moq-ffi` (42 in `error.rs`, the rest across `media`, `audio`, `origin`, +`video`, and the producer and consumer types) and 133 in `moq-c` (39 in +`error.rs`, 63 in `api.rs`, plus `audio` and `video`). Error codes and +variants make up most of it. + +Count them with `cargo rustdoc -p --lib --all-features -- -W +missing_docs`. Check that the docs reach the outputs a binding user reads: +UniFFI copies rustdoc into the generated Python, Swift, Kotlin, and Go code, +and cbindgen copies it into `moq.h`. The hand-written wrappers listed in the +Cross-Package Sync table keep their own docs; align them where they restate +the same item. diff --git a/quest/m1/docs-js.md b/quest/m1/docs-js.md new file mode 100644 index 00000000000..c4900dfc968 --- /dev/null +++ b/quest/m1/docs-js.md @@ -0,0 +1,25 @@ +# [M] Document and enforce the JS public exports + +## Goal + +Every export reachable from a published JS package's `exports`, and every +public member of an exported class, has a TSDoc comment, and `just check` +fails when a new one lacks it. + +## Plan + +The m0 documentation audit (2026-10-19) documented the gaps in `@moq/auth`, +`@moq/hang`, `@moq/json`, and `@moq/net`. What remains is in the UI packages: +`@moq/publish` (37 exports, 54 class members), `@moq/watch` (28 exports, 64 +members), and `@moq/boy` (2 exports, 30 members). About 40 of those have a +`//` comment that only needs to become `/** */`. + +Nothing enforces doc comments for JS: Biome has no such rule, and there is no +TypeDoc or TSDoc config. Recommended: a TypeScript compiler API check in +`js/common` beside `deps.ts` and `declarations.ts`, run from +`sh/js/workspace.py check`. It walks each package's `exports` through its +re-export chains, so it sees the public surface rather than every `export` +in a file, and needs no new dependency. Exempt symbol-keyed brand members +such as `@moq/signals`' `[SIGNAL_BRAND]`. `deno doc --lint` also covers this +but cannot disable its slow-types rule, and `eslint-plugin-jsdoc` would add a +second linter that only sees per-file exports. diff --git a/quest/m1/docs-mux.md b/quest/m1/docs-mux.md new file mode 100644 index 00000000000..fd149e3caf3 --- /dev/null +++ b/quest/m1/docs-mux.md @@ -0,0 +1,22 @@ +# [M] Document the moq-mux public API + +## Goal + +Every public item in `moq-mux` has a one-line rustdoc, and the crate sets +`#![warn(missing_docs)]` so new items stay documented. + +## Plan + +The m0 documentation audit (2026-10-19) found 205 undocumented public items +with default features, too many to review alongside its other fixes. They +cluster in `container/fmp4` (43), `catalog/msf` (28), `container/mkv` (36), +and the `codec` modules (h264 27, h265 19, av1, annexb, aac, vp8, vp9). + +Count them with +`cargo rustdoc -p moq-mux --lib --all-features -- -W missing_docs` and keep +it clean. `just check` does not pass `--all-features`; the nightly `just rs +features` recipe does, so run that rustdoc command before landing. Struct +fields that mirror a spec (ISO BMFF boxes, Matroska elements, SPS fields) can +name the spec field instead of restating it. An item that exists only for +tests or another crate's internals is a candidate for `pub(crate)` instead of +a doc; narrowing one is a breaking change, so list it in `MIGRATE.md`. diff --git a/rs/hang/src/catalog/audio/mod.rs b/rs/hang/src/catalog/audio/mod.rs index 01382bb0ea6..c11c985154e 100644 --- a/rs/hang/src/catalog/audio/mod.rs +++ b/rs/hang/src/catalog/audio/mod.rs @@ -115,19 +115,19 @@ pub struct AudioConfig { #[serde(default)] pub label: Option, - // The codec, see the registry for details: - // https://w3c.github.io/webcodecs/codec_registry.html + /// The codec, see the registry for details: + /// #[serde_as(as = "DisplayFromStr")] pub codec: AudioCodec, - // The sample rate of the audio in Hz + /// The sample rate of the audio in Hz. pub sample_rate: u32, - // The number of channels in the audio + /// The number of channels in the audio. #[serde(rename = "numberOfChannels")] pub channel_count: u32, - // The maximum bitrate of the audio track in bits per second. + /// The maximum bitrate of the audio track in bits per second. #[serde(default)] pub bitrate: Option, @@ -139,8 +139,8 @@ pub struct AudioConfig { )] pub enabled: bool, - // Some codecs include a description so the decoder can be initialized without extra data. - // If not provided, there may be in-band metadata (marginally higher overhead). + /// Some codecs include a description so the decoder can be initialized without extra data. + /// If not provided, there may be in-band metadata (marginally higher overhead). #[serde(default)] #[serde_as(as = "Option")] pub description: Option, diff --git a/rs/hang/src/catalog/video/av1.rs b/rs/hang/src/catalog/video/av1.rs index 06db4d37f7b..0870fa3786d 100644 --- a/rs/hang/src/catalog/video/av1.rs +++ b/rs/hang/src/catalog/video/av1.rs @@ -38,6 +38,7 @@ pub struct AV1 { } impl AV1 { + /// The codec string prefix that identifies AV1. pub const PREFIX: &'static str = "av01"; } diff --git a/rs/hang/src/catalog/video/codec.rs b/rs/hang/src/catalog/video/codec.rs index 8fa206b8e8a..f4e65bc7569 100644 --- a/rs/hang/src/catalog/video/codec.rs +++ b/rs/hang/src/catalog/video/codec.rs @@ -33,11 +33,17 @@ pub enum VideoCodec { #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum VideoCodecKind { + /// H.264 / AVC. H264, + /// H.265 / HEVC. H265, + /// VP8. VP8, + /// VP9. VP9, + /// AV1. AV1, + /// Any codec not listed above. Unknown, } diff --git a/rs/hang/src/catalog/video/color.rs b/rs/hang/src/catalog/video/color.rs index 957f77abc07..f02e2bdb852 100644 --- a/rs/hang/src/catalog/video/color.rs +++ b/rs/hang/src/catalog/video/color.rs @@ -62,7 +62,9 @@ pub struct Mastering { /// A CIE 1931 xy chromaticity coordinate. #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq)] pub struct Chromaticity { + /// The x coordinate. pub x: f64, + /// The y coordinate. pub y: f64, } diff --git a/rs/hang/src/catalog/video/mod.rs b/rs/hang/src/catalog/video/mod.rs index 14ac4172d04..f0a5a1615f7 100644 --- a/rs/hang/src/catalog/video/mod.rs +++ b/rs/hang/src/catalog/video/mod.rs @@ -150,7 +150,9 @@ impl Video { #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] pub struct Display { + /// Width in pixels. pub width: u32, + /// Height in pixels. pub height: u32, } @@ -216,6 +218,7 @@ pub struct VideoConfig { /// The picture resizes in band at a keyframe below these ceilings, unless the /// `description` pins it. Absent means unknown; a publisher may fill it once. pub coded_width: Option, + /// The height counterpart of `coded_width`. pub coded_height: Option, /// The aspect ratio the whole picture is displayed at, as WebCodecs' @@ -228,6 +231,7 @@ pub struct VideoConfig { /// rename to `displayAspect*`; the current name is what we emit. #[serde(alias = "displayRatioWidth")] pub display_aspect_width: Option, + /// The height counterpart of `display_aspect_width`. #[serde(alias = "displayRatioHeight")] pub display_aspect_height: Option, diff --git a/rs/hang/src/error.rs b/rs/hang/src/error.rs index 43cfdf90043..7fe37deb4de 100644 --- a/rs/hang/src/error.rs +++ b/rs/hang/src/error.rs @@ -15,7 +15,12 @@ pub enum Error { /// A catalog has more media renditions than a consumer will hold. #[error("catalog has {count} renditions, over the limit of {max}")] - TooManyRenditions { count: usize, max: usize }, + TooManyRenditions { + /// How many renditions the catalog lists. + count: usize, + /// The most renditions the consumer accepts. + max: usize, + }, /// A catalog uses one rendition ID for both a video and an audio rendition. #[error("catalog rendition ID is both video and audio: {0}")] diff --git a/rs/hang/src/lib.rs b/rs/hang/src/lib.rs index adc5354ec1a..420dcd4d2b5 100644 --- a/rs/hang/src/lib.rs +++ b/rs/hang/src/lib.rs @@ -14,6 +14,9 @@ //! - **CMAF**: Fragmented MP4 container (moof+mdat pair) //! //! See the [moq-mux](https://crates.io/crates/moq-mux) crate for importing existing media formats into hang broadcasts. + +#![warn(missing_docs)] + mod error; mod snapshot; diff --git a/rs/kio/src/lib.rs b/rs/kio/src/lib.rs index 50bb0def9a8..d37334651ea 100644 --- a/rs/kio/src/lib.rs +++ b/rs/kio/src/lib.rs @@ -16,6 +16,8 @@ //! [`coop`] bounds the passes a loop makes per poll, so one that always finds //! work ready still yields. +#![warn(missing_docs)] + use std::{ fmt, ops::{Deref, DerefMut}, diff --git a/rs/kio/src/send.rs b/rs/kio/src/send.rs index 136f9e34cbf..33eebedc44f 100644 --- a/rs/kio/src/send.rs +++ b/rs/kio/src/send.rs @@ -16,6 +16,7 @@ pub trait MaybeSend: Send {} #[cfg(not(target_family = "wasm"))] impl MaybeSend for T {} +/// `Send` on native targets, no bound at all on wasm. #[cfg(target_family = "wasm")] pub trait MaybeSend {} diff --git a/rs/moq-archive/src/error.rs b/rs/moq-archive/src/error.rs index 9be3e081ad7..e33439b030a 100644 --- a/rs/moq-archive/src/error.rs +++ b/rs/moq-archive/src/error.rs @@ -24,12 +24,19 @@ pub enum Error { /// An existing `.info` has a different priority. #[error("priority {existing} does not match {intended}")] - Priority { existing: u8, intended: u8 }, + Priority { + /// The priority already recorded. + existing: u8, + /// The priority the caller wanted to record. + intended: u8, + }, /// An existing `.info` has a different timescale, `None` when untimed. #[error("timescale {existing:?} does not match {intended:?}")] TimescaleMismatch { + /// The timescale already recorded. existing: Option, + /// The timescale the caller wanted to record. intended: Option, }, @@ -41,7 +48,9 @@ pub enum Error { epoch_text(existing) )] EpochMismatch { + /// The epoch already recorded. existing: Option, + /// The epoch of the source being recorded now. intended: Option, }, diff --git a/rs/moq-archive/src/lib.rs b/rs/moq-archive/src/lib.rs index 07aa606b8d8..94ec612132b 100644 --- a/rs/moq-archive/src/lib.rs +++ b/rs/moq-archive/src/lib.rs @@ -13,9 +13,12 @@ //! # Ok::<(), moq_archive::Error>(()) //! ``` +#![warn(missing_docs)] + pub use object_store; mod error; +/// The `.info` object holding a track's immutable properties. pub mod info; #[cfg(test)] mod mock; @@ -25,7 +28,9 @@ mod path; mod proof; pub mod reader; mod recover; +/// The binary segment object holding a record's groups and frames. pub mod segment; +/// Put, get, list, and delete recording objects on an object store. pub mod store; pub mod writer; diff --git a/rs/moq-auth/src/algorithm.rs b/rs/moq-auth/src/algorithm.rs index 9a5102ff772..8a0a4d7c1a2 100644 --- a/rs/moq-auth/src/algorithm.rs +++ b/rs/moq-auth/src/algorithm.rs @@ -8,17 +8,29 @@ use std::{fmt, str::FromStr}; /// #[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize, PartialEq, Eq, Hash)] pub enum Algorithm { + /// HMAC with SHA-256. HS256, + /// HMAC with SHA-384. HS384, + /// HMAC with SHA-512. HS512, + /// ECDSA on P-256 with SHA-256. ES256, + /// ECDSA on P-384 with SHA-384. ES384, + /// RSASSA-PKCS1-v1_5 with SHA-256. RS256, + /// RSASSA-PKCS1-v1_5 with SHA-384. RS384, + /// RSASSA-PKCS1-v1_5 with SHA-512. RS512, + /// RSASSA-PSS with SHA-256. PS256, + /// RSASSA-PSS with SHA-384. PS384, + /// RSASSA-PSS with SHA-512. PS512, + /// EdDSA on Ed25519. EdDSA, } diff --git a/rs/moq-auth/src/error.rs b/rs/moq-auth/src/error.rs index 097124bbbf5..ac88a04e0ce 100644 --- a/rs/moq-auth/src/error.rs +++ b/rs/moq-auth/src/error.rs @@ -19,45 +19,59 @@ pub(crate) fn message(err: impl std::error::Error) -> String { #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum KeyError { + /// The algorithm does not match the key type. #[error("invalid algorithm for key type")] InvalidAlgorithm, + /// The algorithm does not match the named curve. #[error("invalid algorithm for {0} curve")] InvalidAlgorithmForCurve(&'static str), + /// An EC coordinate has the wrong length for the named curve. #[error("invalid coordinate length for {0}")] InvalidCoordinateLength(&'static str), + /// The curve does not fit the named key type. #[error("invalid curve for {0} key")] InvalidCurve(&'static str), + /// Signing needs a private key, but the key is public. #[error("missing private key")] MissingPrivateKey, + /// A symmetric secret is shorter than the minimum length in bytes. #[error("oct key secret must be at least {0} bytes")] SecretTooShort(usize), + /// A symmetric key has no public half to export. #[error("OCT key cannot be converted to public key")] NoPublicKey, + /// The key's operations exclude verification. #[error("key does not support verification")] VerifyUnsupported, + /// The key's operations exclude signing. #[error("key does not support signing")] SignUnsupported, + /// The key set has no key that can sign. #[error("cannot find signing key")] NoSigningKey, + /// The key set has no key with this `kid`. #[error("cannot find key with kid {0}")] KeyNotFound(String), + /// The JWT header has no `kid` to select a key with. #[error("missing kid in JWT header")] MissingKid, + /// An EC key has no x coordinate. #[error("missing x() point in EC key")] MissingEcX, + /// An EC key has no y coordinate. #[error("missing y() point in EC key")] MissingEcY, } @@ -66,69 +80,91 @@ pub enum KeyError { #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { + /// A key could not be configured or used. #[error(transparent)] Key(#[from] KeyError), + /// The token grants neither publish nor subscribe. #[error("no publish or subscribe allowed; token is useless")] UselessToken, + /// The path does not overlap the token's root. #[error("path `{0}` does not overlap the token root")] RootMismatch(String), + /// The token grants no access to this path. #[error("token grants no access to path `{0}`")] NoAccess(String), + /// The key scope allows neither publish nor subscribe. #[error("no publish or subscribe allowed; key scope is useless")] UselessScope, + /// The token claims more than the key's scope allows. #[error("token capabilities exceed the key scope")] ScopeExceeded, + /// The algorithm name is not supported. #[error("invalid algorithm: {0}")] InvalidAlgorithm(String), + /// The token's expiry has passed. #[error("token has expired")] TokenExpired, + /// The token's not-before time has not arrived. #[error("token is not valid yet")] TokenNotYetValid, + /// A path pattern did not parse. #[error(transparent)] Pattern(#[from] moq_pattern::InvalidPattern), + /// The grant allows nothing, so the session is refused. #[error("grant names nothing; the session is refused")] UselessGrant, + /// The grant marks an upstream but not a peer. #[error("grant marks an upstream that is not a peer")] UpstreamWithoutPeer, + /// The grant asks to be revalidated but never expires. #[error("grant asks to be revalidated but never expires")] UnboundedRevalidate, + /// The grant sets session limits without a revalidate cadence. #[error("session limits need a revalidate cadence, which ages out the slots of a relay that died")] LimitsWithoutRevalidate, + /// The grant's expiry is beyond what the system clock can represent. #[error("the grant bound reaches past the system clock's range")] ExpiresOutOfRange, + /// The grant's revalidate interval is zero. #[error("grant asks to be revalidated at no interval")] ZeroRevalidate, + /// The grant's expiry has passed. #[error("grant has already expired")] GrantExpired, + /// A stats label is not a literal path. #[error("invalid stats label: {0}")] InvalidLabel(moq_pattern::InvalidPattern), + /// The auth server refused the session. #[error(transparent)] Refused(#[from] crate::Refusal), + /// The auth server could not be reached or answered with an error. #[error("auth server unavailable: {0}")] Unavailable(String), + /// The auth URL is plain http:// to a host other than loopback. #[error("auth URL must be https://, unix://, or http:// to a loopback address: {0}")] InsecureUrl(String), + /// The auth URL has an unsupported scheme, or is a `unix:` URL that names no socket path. #[error("invalid auth URL: {0}")] InvalidUrl(String), @@ -136,6 +172,7 @@ pub enum Error { #[error("{0}")] Json(String), + /// A local file could not be read or written. #[error(transparent)] Io(#[from] std::io::Error), @@ -143,6 +180,7 @@ pub enum Error { #[error("{0}")] Base64(String), + /// A decoded field is not valid UTF-8. #[error(transparent)] Utf8(#[from] std::string::FromUtf8Error), @@ -195,6 +233,7 @@ impl From for Error { } } +/// A [`Result`](std::result::Result) with this crate's [`Error`]. pub type Result = std::result::Result; #[cfg(test)] diff --git a/rs/moq-auth/src/key.rs b/rs/moq-auth/src/key.rs index edc86c8629a..a5a61c8d074 100644 --- a/rs/moq-auth/src/key.rs +++ b/rs/moq-auth/src/key.rs @@ -15,9 +15,13 @@ use std::{collections::HashSet, fmt, path::Path as StdPath}; #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, PartialOrd, Ord)] #[serde(rename_all = "camelCase")] pub enum KeyOperation { + /// Compute a signature. Sign, + /// Verify a signature. Verify, + /// Decrypt content. Decrypt, + /// Encrypt content. Encrypt, } @@ -27,6 +31,7 @@ pub enum KeyOperation { pub enum KeyMaterial { /// EC { + /// The curve the point lies on. #[serde(rename = "crv")] curve: EllipticCurve, /// The X-coordinate of an EC key @@ -46,8 +51,10 @@ pub enum KeyMaterial { }, /// RSA { + /// The public modulus and exponent. #[serde(flatten)] public: RsaPublicKey, + /// The private parameters, absent for a public key. #[serde(flatten, skip_serializing_if = "Option::is_none")] private: Option, }, @@ -64,10 +71,13 @@ pub enum KeyMaterial { }, /// OKP { + /// The curve the key belongs to. #[serde(rename = "crv")] curve: EllipticCurve, + /// The public key bytes, base64url encoded in the JWK. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] x: Vec, + /// The private key bytes, base64url encoded in the JWK, absent for a public key. #[serde( rename = "d", default, @@ -84,13 +94,16 @@ pub enum KeyMaterial { /// See #[derive(Clone, Serialize, Deserialize, PartialEq, Eq, Debug)] pub enum EllipticCurve { + /// NIST P-256. #[serde(rename = "P-256")] P256, + /// NIST P-384. #[serde(rename = "P-384")] P384, // jsonwebtoken doesn't support the ES512 algorithm, so we can't implement this // #[serde(rename = "P-521")] // P521, + /// Ed25519, for OKP keys. #[serde(rename = "Ed25519")] Ed25519, } @@ -100,8 +113,10 @@ pub enum EllipticCurve { /// See #[derive(Clone, Serialize, Deserialize)] pub struct RsaPublicKey { + /// The modulus. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub n: Vec, + /// The public exponent. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub e: Vec, } @@ -111,18 +126,25 @@ pub struct RsaPublicKey { /// See #[derive(Clone, Serialize, Deserialize)] pub struct RsaPrivateKey { + /// The private exponent. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub d: Vec, + /// The first prime factor. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub p: Vec, + /// The second prime factor. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub q: Vec, + /// The first factor's CRT exponent. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub dp: Vec, + /// The second factor's CRT exponent. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub dq: Vec, + /// The first CRT coefficient. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub qi: Vec, + /// Other prime information, for keys with more than two primes. #[serde(skip_serializing_if = "Option::is_none")] pub oth: Option>, } @@ -130,10 +152,13 @@ pub struct RsaPrivateKey { /// Additional prime information for multi-prime RSA keys. #[derive(Clone, Serialize, Deserialize)] pub struct RsaAdditionalPrime { + /// The prime factor. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub r: Vec, + /// The factor's CRT exponent. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub d: Vec, + /// The factor's CRT coefficient. #[serde(serialize_with = "serialize_base64url", deserialize_with = "deserialize_base64url")] pub t: Vec, } diff --git a/rs/moq-auth/src/key_id.rs b/rs/moq-auth/src/key_id.rs index ff2ba241194..e91647e6411 100644 --- a/rs/moq-auth/src/key_id.rs +++ b/rs/moq-auth/src/key_id.rs @@ -75,15 +75,19 @@ impl TryFrom for KeyId { } } +/// Why a string is not a valid key ID. #[derive(Debug, Clone, thiserror::Error)] #[non_exhaustive] pub enum KeyIdError { + /// The key ID is empty. #[error("key ID must not be empty")] Empty, + /// The key ID is longer than 128 characters. #[error("key ID exceeds maximum length of 128 characters")] TooLong, + /// The key ID has a character other than an ASCII letter, digit, hyphen, or underscore. #[error("key ID contains invalid characters (only alphanumeric, hyphens, underscores allowed)")] Invalid, } diff --git a/rs/moq-auth/src/lib.rs b/rs/moq-auth/src/lib.rs index b1d85f8edb6..808b02bcc2b 100644 --- a/rs/moq-auth/src/lib.rs +++ b/rs/moq-auth/src/lib.rs @@ -16,6 +16,8 @@ //! Grants and claims name paths with [`Pattern`]s from `moq-pattern`, re-exported here: //! `foo` is one broadcast, `foo/**` is a subtree, `**` is everything. +#![warn(missing_docs)] + mod access; mod algorithm; mod claims; diff --git a/rs/moq-auth/src/serve.rs b/rs/moq-auth/src/serve.rs index 36f54186217..b007f594d46 100644 --- a/rs/moq-auth/src/serve.rs +++ b/rs/moq-auth/src/serve.rs @@ -104,36 +104,70 @@ pub struct Policy { #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] #[non_exhaustive] pub enum Refusal { + /// No keys are configured, so no token can be verified. #[error("no keys are configured, so a token cannot be verified")] NoKeys, - #[error("the token names no key and the key directory needs one")] + /// The token has no `kid`, and the configured keys need one to choose a key. + #[error("the token names no key and the configured keys need one")] MissingKeyId, + /// The token's key could not be found or loaded: its `kid` is malformed or matches no key, or the key source is unreadable. #[error("the token's key is unknown")] UnknownKey, + /// The token failed to decode, verify, or authorize. #[error("the token is invalid: {0}")] InvalidToken(String), + /// The token's root does not overlap the dialed path. #[error("the token root `{root}` does not overlap the dialed path `{path}`")] - RootMismatch { root: String, path: String }, + RootMismatch { + /// The token's root. + root: String, + /// The dialed path. + path: String, + }, + /// Nothing is granted at the dialed path. #[error("nothing is granted at `{path}`")] - NoAccess { path: String, root: Option }, + NoAccess { + /// The dialed path. + path: String, + /// The verified token's root, absent without a token. + root: Option, + }, + /// A client certificate was presented, but the policy grants nothing to certificates. #[error("a certificate was presented but nothing is granted to certificates")] NoMtlsGrant, + /// Neither a token nor a certificate was presented, and anonymous access is not granted. #[error("anonymous access is not granted")] NoPublicGrant, + /// The token already holds its limit of live sessions. #[error("too many live sessions for this token")] - TokenLimit { root: Option }, + TokenLimit { + /// The verified token's root, absent without a token. + root: Option, + }, + /// The remote address already holds its limit of live sessions. #[error("too many live sessions from this address")] - RemoteLimit { root: Option }, + RemoteLimit { + /// The verified token's root, absent without a token. + root: Option, + }, + /// A SETUP token and a different `jwt` query were both presented. #[error("a SETUP token and a different `jwt` query were presented; present one")] TwoTokens, + /// The SETUP token type is not 0, a JWT. #[error("SETUP token type {0:#x} is not supported; only type 0 (a JWT) is")] UnsupportedToken(u64), + /// Both a JWT and a client certificate were presented. #[error("both a JWT and a client certificate were presented; present one")] TokenAndCertificate, + /// The policy's grant bound is beyond what the system clock can represent. #[error("the policy's grant bound reaches past the system clock's range")] ExpiresOutOfRange, + /// The token's expiry has passed. #[error("the token has expired")] - Expired { root: String }, + Expired { + /// The token's root. + root: String, + }, } impl Refusal { diff --git a/rs/moq-auth/src/set.rs b/rs/moq-auth/src/set.rs index 94c82770506..39b3ed85bcb 100644 --- a/rs/moq-auth/src/set.rs +++ b/rs/moq-auth/src/set.rs @@ -72,6 +72,7 @@ impl KeySet { Ok(()) } + /// Copy the set with each key's private parts removed, failing on a symmetric key, which has no public half. pub fn to_public_set(&self) -> crate::Result { Ok(KeySet { keys: self diff --git a/rs/moq-clock/src/lib.rs b/rs/moq-clock/src/lib.rs index f26b39436b2..6882c7df13d 100644 --- a/rs/moq-clock/src/lib.rs +++ b/rs/moq-clock/src/lib.rs @@ -23,6 +23,8 @@ //! starts at [`Instant::ZERO`], and the `#[moq_clock::test]` attribute that runs an //! `async fn` test on it. Enable it for dev-dependencies only. +#![warn(missing_docs)] + mod deadline; #[cfg(feature = "manual")] mod installed; diff --git a/rs/moq-flate/src/lib.rs b/rs/moq-flate/src/lib.rs index 479cd8e02b2..53170f4780d 100644 --- a/rs/moq-flate/src/lib.rs +++ b/rs/moq-flate/src/lib.rs @@ -51,6 +51,7 @@ //! [RFC 1951]: https://www.rfc-editor.org/rfc/rfc1951.html //! [RFC 7692]: https://www.rfc-editor.org/rfc/rfc7692.html#section-7.2.1 +#![warn(missing_docs)] // The browser transport is `!Send`, so on wasm the shared state behind the track modes' `Arc`s is // too and clippy suggests `Rc`. The same code is genuinely cross-thread on native, so `Arc` stays // and the lint is unactionable here. diff --git a/rs/moq-gst/src/lib.rs b/rs/moq-gst/src/lib.rs index aaaa5f1f89a..547187b7adb 100644 --- a/rs/moq-gst/src/lib.rs +++ b/rs/moq-gst/src/lib.rs @@ -1,3 +1,6 @@ +//! GStreamer plugin with a `moqsink` element that publishes a pipeline to a MoQ relay +//! and a `moqsrc` element that subscribes to a broadcast, one source pad per rendition. + use gst::glib; mod block; @@ -14,6 +17,8 @@ pub use sink::MediaContainer; use tracing::level_filters::LevelFilter; use tracing_subscriber::EnvFilter; +/// Registers `moqsink` and `moqsrc` with `plugin` and installs a stderr tracing subscriber +/// filtered by `RUST_LOG`, unless the host process already installed one. pub fn plugin_init(plugin: &gst::Plugin) -> Result<(), glib::BoolError> { sink::register(plugin)?; source::register(plugin)?; @@ -31,7 +36,8 @@ pub fn plugin_init(plugin: &gst::Plugin) -> Result<(), glib::BoolError> { .with_env_filter(filter) .finish(); - tracing::subscriber::set_global_default(logger).unwrap(); + // An embedding application that installed its own subscriber keeps it. + let _ = tracing::subscriber::set_global_default(logger); Ok(()) } diff --git a/rs/moq-gst/tests/subscriber.rs b/rs/moq-gst/tests/subscriber.rs new file mode 100644 index 00000000000..86a98ee9393 --- /dev/null +++ b/rs/moq-gst/tests/subscriber.rs @@ -0,0 +1,13 @@ +//! A host that installed its own tracing subscriber can still load the plugin. +//! +//! Its own test binary, since the global subscriber is process-wide. + +#[test] +fn registers_under_a_host_subscriber() { + tracing::subscriber::set_global_default(tracing_subscriber::FmtSubscriber::new()) + .expect("no subscriber is installed yet"); + + gst::init().unwrap(); + gstmoq::plugin_register_static().expect("register moq plugin"); + assert!(gst::ElementFactory::find("moqsink").is_some()); +} diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index 42c095d9766..f64c30715a2 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -17,6 +17,8 @@ //! when something else already owns the track, such as a `moq_mux::container::Producer` also //! managing a timeline and a catalog estimate. +#![warn(missing_docs)] + mod diff; mod merge; pub mod snapshot; diff --git a/rs/moq-loc/src/lib.rs b/rs/moq-loc/src/lib.rs index 1d19e7ab37e..2eb5a7bb867 100644 --- a/rs/moq-loc/src/lib.rs +++ b/rs/moq-loc/src/lib.rs @@ -25,6 +25,8 @@ //! //! Varint encoding is QUIC-style throughout via [`moq_net::varint`]. +#![warn(missing_docs)] + use bytes::{Buf, Bytes, BytesMut}; use moq_net::{BoundsExceeded, DecodeError, EncodeError, varint}; diff --git a/rs/moq-msf/src/lib.rs b/rs/moq-msf/src/lib.rs index 63a54043e35..d335f486ae6 100644 --- a/rs/moq-msf/src/lib.rs +++ b/rs/moq-msf/src/lib.rs @@ -17,6 +17,8 @@ //! - //! - +#![warn(missing_docs)] + use std::fmt; use std::str::FromStr; use std::time::Duration; diff --git a/rs/moq-nvenc/src/cuvid.rs b/rs/moq-nvenc/src/cuvid.rs index 122599e8b40..a795942f1bb 100644 --- a/rs/moq-nvenc/src/cuvid.rs +++ b/rs/moq-nvenc/src/cuvid.rs @@ -37,22 +37,31 @@ type UnmapVideoFrame64 = unsafe extern "C" fn(CUvideodecoder, c_ulonglong) -> CU /// and map/unmap the decoded frames. All calls require a current CUDA context. #[allow(missing_debug_implementations)] pub struct Api { + /// Creates a bitstream parser. #[doc(alias = "cuvidCreateVideoParser")] pub create_video_parser: CreateVideoParser, + /// Feeds a bitstream packet to a parser. #[doc(alias = "cuvidParseVideoData")] pub parse_video_data: ParseVideoData, + /// Destroys a parser. #[doc(alias = "cuvidDestroyVideoParser")] pub destroy_video_parser: DestroyVideoParser, + /// Queries what the decoder supports for a codec and format. #[doc(alias = "cuvidGetDecoderCaps")] pub get_decoder_caps: GetDecoderCaps, + /// Creates a decoder. #[doc(alias = "cuvidCreateDecoder")] pub create_decoder: CreateDecoder, + /// Destroys a decoder. #[doc(alias = "cuvidDestroyDecoder")] pub destroy_decoder: DestroyDecoder, + /// Submits one picture to a decoder. #[doc(alias = "cuvidDecodePicture")] pub decode_picture: DecodePicture, + /// Maps a decoded frame for reading. #[doc(alias = "cuvidMapVideoFrame64")] pub map_video_frame: MapVideoFrame64, + /// Unmaps a frame mapped by `map_video_frame`. #[doc(alias = "cuvidUnmapVideoFrame64")] pub unmap_video_frame: UnmapVideoFrame64, } diff --git a/rs/moq-nvenc/src/lib.rs b/rs/moq-nvenc/src/lib.rs index 8c10187be80..a81e53c4de2 100644 --- a/rs/moq-nvenc/src/lib.rs +++ b/rs/moq-nvenc/src/lib.rs @@ -27,6 +27,7 @@ //! [`cuvid`] exposes the NVDEC (CUVID) entry points as a dlopen'd function //! table; there is no higher-level safe wrapper yet. +#![warn(missing_docs)] // Vendored third-party bindings: keep the workspace's `clippy -D warnings` and // `rustdoc -D warnings` from churning upstream code (broken intra-doc links, the // strict clippy lints the crate opted into, etc.). diff --git a/rs/moq-relay/src/lib.rs b/rs/moq-relay/src/lib.rs index 01a4d317f58..6e6ba162372 100644 --- a/rs/moq-relay/src/lib.rs +++ b/rs/moq-relay/src/lib.rs @@ -10,9 +10,12 @@ //! which keeps the listeners, workers, and shutdown joins. `main.rs` is a thin //! wrapper over the two. +#![warn(missing_docs)] + pub mod acme; pub mod auth; pub mod cache; +/// Joining other relays into a cluster that shares one origin. pub mod cluster; mod config; mod connection; @@ -39,6 +42,7 @@ mod test_env; mod test_support; #[cfg(all(target_os = "linux", feature = "_uring"))] pub mod uring; +/// The HTTP/HTTPS server: health, certificate fingerprint, announcements, fetch, and WebSocket sessions. pub mod web; #[cfg(feature = "websocket")] mod websocket; diff --git a/rs/moq-relay/src/session.rs b/rs/moq-relay/src/session.rs index 716fcb4a2eb..167569b6600 100644 --- a/rs/moq-relay/src/session.rs +++ b/rs/moq-relay/src/session.rs @@ -175,7 +175,12 @@ pub enum Remote { /// A single address; IPv4-mapped IPv6 folds to IPv4. Ip(IpAddr), /// A network; the session IP is folded the same way, then prefix-matched. - Cidr { addr: IpAddr, prefix: u8 }, + Cidr { + /// The network address. + addr: IpAddr, + /// The prefix length in bits. + prefix: u8, + }, } impl std::str::FromStr for Remote { @@ -382,7 +387,12 @@ pub enum Error { /// A field the routes do not filter on, including `query`. Unknown(String), /// A known field whose value did not parse. - Invalid { field: &'static str, value: String }, + Invalid { + /// The field name. + field: &'static str, + /// The value that did not parse. + value: String, + }, } impl std::fmt::Display for Error { diff --git a/rs/moq-sock/src/udp/unix.rs b/rs/moq-sock/src/udp/unix.rs index 9897a10bb4e..3f86e2c2f24 100644 --- a/rs/moq-sock/src/udp/unix.rs +++ b/rs/moq-sock/src/udp/unix.rs @@ -48,6 +48,7 @@ pub struct UdpSocketState { } impl UdpSocketState { + /// Configures `sock` for this platform's offloads and ancillary data and returns its state. pub fn new(sock: UdpSockRef<'_>) -> io::Result { let io = sock.0; let mut cmsg_platform_space = 0; @@ -207,6 +208,7 @@ impl UdpSocketState { send(self, socket.0, transmit) } + /// Receives datagrams into `bufs`, filling one [`RecvMeta`] per message, and returns how many messages arrived. #[cfg(not(any( apple, target_os = "openbsd", @@ -225,6 +227,7 @@ impl UdpSocketState { recv_via_recvmmsg(socket.0, bufs, meta) } + /// Receives datagrams into `bufs`, filling one [`RecvMeta`] per message, and returns how many messages arrived. #[cfg(apple_fast)] pub fn recv( &self, @@ -239,6 +242,7 @@ impl UdpSocketState { } } + /// Receives datagrams into `bufs`, filling one [`RecvMeta`] per message, and returns how many messages arrived. #[cfg(any( target_os = "openbsd", target_os = "netbsd", diff --git a/rs/moq-sock/src/udp/wasi.rs b/rs/moq-sock/src/udp/wasi.rs index 7a3b455160c..47fd5d3bea0 100644 --- a/rs/moq-sock/src/udp/wasi.rs +++ b/rs/moq-sock/src/udp/wasi.rs @@ -14,6 +14,7 @@ pub struct UdpSocketState { } impl UdpSocketState { + /// Sets `socket` non-blocking and returns its state; WASI has no offloads to configure. pub fn new(socket: UdpSockRef<'_>) -> io::Result { socket.set_nonblocking(true)?; @@ -25,6 +26,7 @@ impl UdpSocketState { send(socket, transmit) } + /// Receives datagrams into `bufs`, filling one [`RecvMeta`] per message, and returns how many messages arrived. pub fn recv( &self, socket: UdpSockRef<'_>, @@ -82,6 +84,7 @@ impl UdpSocketState { socket.0.recv_buffer_size() } + /// Whether transmitted datagrams might get fragmented by the IP layer #[inline] pub fn may_fragment(&self) -> bool { true diff --git a/rs/moq-sock/src/udp/windows.rs b/rs/moq-sock/src/udp/windows.rs index 5773905c30f..6d5ac1e6c59 100644 --- a/rs/moq-sock/src/udp/windows.rs +++ b/rs/moq-sock/src/udp/windows.rs @@ -37,6 +37,7 @@ pub struct UdpSocketState { } impl UdpSocketState { + /// Configures `socket` for this platform's offloads and ancillary data and returns its state. pub fn new(socket: UdpSockRef<'_>) -> io::Result { assert!( CMSG_LEN @@ -186,6 +187,7 @@ impl UdpSocketState { ) } + /// Receives datagrams into `bufs`, filling one [`RecvMeta`] per message, and returns how many messages arrived. pub fn recv( &self, socket: UdpSockRef<'_>, @@ -334,6 +336,7 @@ impl UdpSocketState { socket.0.recv_buffer_size() } + /// Whether transmitted datagrams might get fragmented by the IP layer #[inline] pub fn may_fragment(&self) -> bool { false diff --git a/rs/moq-stats/src/lib.rs b/rs/moq-stats/src/lib.rs index 448e8aac6a9..d4a358fca7a 100644 --- a/rs/moq-stats/src/lib.rs +++ b/rs/moq-stats/src/lib.rs @@ -1,4 +1,5 @@ #![cfg_attr(test, allow(clippy::disallowed_methods))] +#![warn(missing_docs)] //! Publish and consume MoQ traffic stats. //! diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index d247aa5d1d1..ece4aa834b3 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -26,6 +26,8 @@ //! the GPU; set [`Config::resize`]'s output to `Output::Cpu` to decode to CPU //! pixels and resize there. +#![warn(missing_docs)] + pub mod active; pub mod ladder; diff --git a/rs/moq-uring/src/lib.rs b/rs/moq-uring/src/lib.rs index 24ab7690c56..9ba152d82b7 100644 --- a/rs/moq-uring/src/lib.rs +++ b/rs/moq-uring/src/lib.rs @@ -33,6 +33,8 @@ //! //! Requires Linux 6.12; [`Worker::new`] refuses older kernels with a legible //! error instead of degrading. The crate compiles to nothing off Linux. + +#![warn(missing_docs)] // Off Linux the crate compiles to nothing, so these doc links have no target. #![cfg_attr(not(target_os = "linux"), allow(rustdoc::broken_intra_doc_links))] #![cfg(target_os = "linux")] diff --git a/rs/moq-video/src/encode/encoder.rs b/rs/moq-video/src/encode/encoder.rs index dff0fc26f62..9fb6858a9fb 100644 --- a/rs/moq-video/src/encode/encoder.rs +++ b/rs/moq-video/src/encode/encoder.rs @@ -177,8 +177,11 @@ impl Applied { #[derive(Clone, Debug)] #[non_exhaustive] pub struct Config { + /// Encoded width in pixels. pub width: u32, + /// Encoded height in pixels. pub height: u32, + /// Encoded frame rate. pub framerate: Rate, /// Target bitrate. `None` derives a sane default /// from resolution and framerate (~0.07 bits per pixel per second). @@ -188,6 +191,7 @@ pub struct Config { pub gop: Gop, /// Output codec. Defaults to [`Codec::H264`]. pub codec: Codec, + /// Which encoder implementation to use. Defaults to [`Kind::Auto`]. pub kind: Kind, /// How the encoder trades latency for compression. Defaults to /// [`Preset::LowLatency`].