Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
66a209c
quest: claim quest/m0/audit-docs
kixelated Oct 20, 2026
73e6f04
docs(hang): document every public item and warn on missing docs
kixelated Oct 20, 2026
366ac23
docs(moq-archive): document every public item and warn on missing docs
kixelated Oct 20, 2026
ddfd7ac
chore(rs): warn on missing docs in crates that already document every…
kixelated Oct 20, 2026
c770a80
docs(moq-auth): document every public item and warn on missing docs
kixelated Oct 20, 2026
1fc03df
docs(moq-sock): document UdpSocketState::new, recv, and may_fragment …
kixelated Oct 20, 2026
4af575e
docs(moq-video): document the encoder config's size, rate, and kind
kixelated Oct 20, 2026
bc172b4
docs(moq-nvenc): document the CUVID entry points and warn on missing …
kixelated Oct 20, 2026
4d171fd
docs(moq-gst): add crate docs and document plugin_init
kixelated Oct 20, 2026
c07e6b3
docs(js): document the remaining auth, hang, json, and net exports
kixelated Oct 20, 2026
2bc3e7a
Merge remote-tracking branch 'origin/main' into quest-m0-audit-docs-2
kixelated Oct 20, 2026
0bab9e7
docs(go): name TrackDemand.WantedChanged, not the removed Used/Unused
kixelated Oct 20, 2026
26b8681
docs(stats): include the expired refusal counter in the totals example
kixelated Oct 20, 2026
c83d7dd
docs: link the official NixOS wiki for flakes
kixelated Oct 20, 2026
2047f4a
docs(moq-relay): document every public item and warn on missing docs
kixelated Oct 20, 2026
fc731d3
docs(moq-auth): document the server's refusal variants
kixelated Oct 20, 2026
37aa4c8
quest: finish the m0 documentation audit and plan its follow-ups
kixelated Oct 20, 2026
3f9923d
style(rs): format the new missing_docs attributes
kixelated Oct 20, 2026
c43fd50
docs(kio): document the wasm MaybeSend
kixelated Oct 20, 2026
87aa913
quest: note the wasm lint pass in the docs audit baseline
kixelated Oct 20, 2026
cb09e7e
Merge branch 'main' of github.com:moq-dev/moq into quest-m0-audit-docs-2
kixelated Oct 20, 2026
02e2adf
docs(moq-auth): describe when InvalidUrl and InsecureUrl actually fire
kixelated Oct 20, 2026
b72a6a4
fix(moq-gst): keep a host's tracing subscriber instead of panicking
kixelated Oct 20, 2026
5c4a93b
docs: correct the OKP key bytes and WASI socket setup docs
kixelated Oct 20, 2026
4778359
quest: name the all-features rustdoc as moq-mux docs' verification
kixelated Oct 20, 2026
0a5e189
Merge branch 'main' of github.com:moq-dev/moq into quest-m0-audit-docs-2
kixelated Oct 20, 2026
b9c2dcc
Merge branch 'main' of github.com:moq-dev/moq into quest-m0-audit-docs-2
kixelated Oct 20, 2026
8934c74
Merge remote-tracking branch 'origin/main' into quest-m0-audit-docs-m…
kixelated Oct 20, 2026
5327bfc
docs(moq-auth): cover every key source in the missing and unknown key…
kixelated Oct 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/concept/stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 3 additions & 2 deletions go/wrapper/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions js/auth/src/algorithm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,5 @@ export const AlgorithmSchema = z.enum([
"PS512",
"EdDSA",
]);
/** A value parsed by {@link AlgorithmSchema}. */
export type Algorithm = z.infer<typeof AlgorithmSchema>;
1 change: 1 addition & 0 deletions js/auth/src/claims.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ export const ScopeSchema = z
}),
);

/** A value parsed by {@link ScopeSchema}. */
export type Scope = z.output<typeof ScopeSchema>;

const ClaimsFields = {
Expand Down
7 changes: 7 additions & 0 deletions js/auth/src/contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,12 @@ export const TransportSchema = z.pipe(
"unknown",
),
);
/** A value parsed by {@link TransportSchema}. */
export type Transport = z.infer<typeof TransportSchema>;

/** 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<typeof RoleSchema>;

/**
Expand All @@ -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<typeof PeerSchema>;

/** A credential from a moq-transport SETUP's `AUTHORIZATION TOKEN` option, unparsed. */
Expand All @@ -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<typeof TokenSchema>;

/** Byte totals for a session, both directions from the relay's point of view. */
Expand All @@ -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<typeof BytesSchema>;

const BaseRequestSchema = z.object({
Expand Down Expand Up @@ -143,6 +148,7 @@ export const RequestSchema = z.discriminatedUnion("event", [
bytes: BytesSchema,
}),
]);
/** A value parsed by {@link RequestSchema}. */
export type Request = z.infer<typeof RequestSchema>;

/**
Expand Down Expand Up @@ -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<typeof GrantSchema>;

/** The reason and verified attribution an auth server returns with HTTP 403. */
Expand Down
7 changes: 7 additions & 0 deletions js/auth/src/key.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<typeof KeyIdSchema>;

/**
* 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<typeof OperationSchema>;

const MIN_HMAC_SECRET_BYTES = 32;
Expand Down Expand Up @@ -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<typeof KeySchema>;
/** An RSA, EC, or OKP key. */
export type AsymmetricKey = Exclude<Key, { kty: "oct" }>;
/** An oct (HMAC secret) key. */
export type SymmetricKey = Extract<Key, { kty: "oct" }>;
/** An asymmetric key without its private parameters. */
export type PublicKey = Omit<AsymmetricKey, "d" | "p" | "q" | "dp" | "dq" | "qi">;

/** Derive a verify-only copy of this key, dropping the private material. */
Expand Down
3 changes: 3 additions & 0 deletions js/hang/src/catalog/root.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
15 changes: 9 additions & 6 deletions js/json/src/diff.ts
Original file line number Diff line number Diff line change
@@ -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;
}

Expand Down
3 changes: 3 additions & 0 deletions js/net/src/auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Grant | undefined> = new Signal<Grant | undefined>(undefined);

/** Always rejects with {@link Unsupported}. */
add(_token: string | Uint8Array): Promise<Auth> {
return Promise.reject(new Unsupported());
}

/** A stream that never yields a request. */
requests(): Requests {
return { next: async () => undefined, close: () => {} };
}
Expand Down
1 change: 1 addition & 0 deletions js/net/src/hop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<typeof HopSchema>;

// pending: /quest/m1/public-model/answer.md
Expand Down
1 change: 0 additions & 1 deletion quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
61 changes: 0 additions & 61 deletions quest/m0/audit-docs.md

This file was deleted.

4 changes: 4 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
57 changes: 57 additions & 0 deletions quest/m1/audit-docs.md
Original file line number Diff line number Diff line change
@@ -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 <crate> --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/<package>` 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.
Loading