diff --git a/CLAUDE.md b/CLAUDE.md index 8aa57b357bc..88edf221d0b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -67,6 +67,8 @@ The API is the most important thing to get right. A bad shape costs a breaking c - No em dashes. - Match the existing conventions, patterns, and naming when possible. - Fix any outdated docs and comments inline; don't add a separate PR for it. +- Add the AI marker `(Written by )` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers. +- Any AI comments may be challenged, and not confused with human maintainers. # Guidelines diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a481094ba1..c2946bce3cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,11 +9,13 @@ PRs are squash-merged, so the PR title becomes the commit subject and the PR des # PRs Keep the body short and structured, not narrated. +Have at least these sections: - **Problem**: a summary of the problem and why this PR is needed. - **Approach**: a summary of the approach taken to solve the problem. - **Impact**: a bullet point for every public API/wire change made. - **Alternatives**: any alternative approaches considered. +- **Follow-ups**: any issues encountered or quests created. When pushing additional commits to an existing PR, update the title and description if needed. When taking over someone else's PR, push commits on top of theirs so they keep credit. @@ -25,9 +27,10 @@ Fix any merge conflicts and failing CI checks. # AI AI-assisted issues, pull requests, reviews, and comments are welcome. -GitHub issues are the public front door for brainstorming. Prefer a quest for work needing durable scope or coordination. +Especially bug reports; dive deep into the root issue before proposing a solution. -Add the AI marker `(Written by )` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers. +GitHub issues are the public front door for brainstorming. +Prefer a quest for work needing durable scope or coordination. # Reviews diff --git a/Cargo.lock b/Cargo.lock index 67fc4a08622..c95da714f8f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1891,7 +1891,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c54e03a951783e8b327515db3f2a2fd0e3bed362a96b066f341ce66ed49b4ead" dependencies = [ "data-encoding", - "syn 1.0.109", + "syn 3.0.5", ] [[package]] @@ -3174,9 +3174,9 @@ dependencies = [ [[package]] name = "h264-parser" -version = "0.4.1" +version = "0.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "253b313319f7109de64e480ffb606f89475cd758bae82e096e00c5d95341d30e" +checksum = "c16ee729d5d4a75be0f5181682a17cf0fce29497d0fa5273d57fe477409f02e6" [[package]] name = "h264-reader" @@ -9396,7 +9396,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" dependencies = [ "fastrand", - "getrandom 0.3.4", + "getrandom 0.4.3", "once_cell", "rustix 1.1.4", "windows-sys 0.61.2", diff --git a/README.md b/README.md index d6261b35084..63b25a0daac 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The core networking is delegated to a QUIC library but the rest is in applicatio Full documentation lives at **[doc.moq.dev](https://doc.moq.dev)**. - **[Run the demo](https://doc.moq.dev/setup/)** - try MoQ locally with a relay, demo media, and the web UI. -- **[Agent setup](https://doc.moq.dev/setup/agent)** - teach your AI coding agent (Claude Code, Cursor, etc.) how to build with MoQ. +- **[Agent setup](https://doc.moq.dev/setup/agent)** - teach your AI coding agent (Claude Code, Cursor, etc.) how to build with MoQ. The docs are also served as markdown via [llms.txt](https://doc.moq.dev/llms.txt). - **[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. diff --git a/bun.lock b/bun.lock index 274eb0f2c79..c6c0e682995 100644 --- a/bun.lock +++ b/bun.lock @@ -67,6 +67,7 @@ "@types/node": "^26.4.1", "typescript": "7.0.2", "vitepress": "^1.6.4", + "vitepress-plugin-llms": "^1.14.0", "wrangler": "^4.129.0", "yaml": "^2.9.0", }, @@ -384,6 +385,8 @@ "@fails-components/webtransport-transport-http3-quiche", ], "packages": { + "@11ty/gray-matter": ["@11ty/gray-matter@2.1.0", "", { "dependencies": { "js-yaml": "^4.2.0", "section-matter": "^1.0.0" } }, "sha512-fNdBOb3MgDz/1UCIoeY4wDuGbp+/3s5y6UrsyfMabECbh/CVycj7Er33JXqSxRwxrRKXcGE1Jipuq/1mODInsQ=="], + "@algolia/abtesting": ["@algolia/abtesting@1.21.1", "", { "dependencies": { "@algolia/client-common": "5.55.1", "@algolia/requester-browser-xhr": "5.55.1", "@algolia/requester-fetch": "5.55.1", "@algolia/requester-node-http": "5.55.1" } }, "sha512-Wia5/mNTfiU0PIUN25UMfAGGdASkkwuCS9nBAdmhqrNPY/ff7U/6MgBVdwFDPsa3sA1msutPtO50gvOzx6MOXA=="], "@algolia/autocomplete-core": ["@algolia/autocomplete-core@1.17.7", "", { "dependencies": { "@algolia/autocomplete-plugin-algolia-insights": "1.17.7", "@algolia/autocomplete-shared": "1.17.7" } }, "sha512-BjiPOW6ks90UKl7TwMv7oNQMnzU+t/wk9mgIDi6b1tXpUek7MW0lbNOUHpvam9pe3lVCf4xPFT+lK7s+e+fs7Q=="], @@ -1008,6 +1011,8 @@ "anymatch": ["anymatch@3.1.3", "", { "dependencies": { "normalize-path": "^3.0.0", "picomatch": "^2.0.4" } }, "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw=="], + "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="], + "async": ["async@3.2.6", "", {}, "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA=="], "async-mutex": ["async-mutex@0.5.0", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-1A94B18jkJ3DYq284ohPxoXbfTA5HsQ7/Mf4DEhcyLx3Bz27Rh59iScbB6EPiP+B+joue6YCxcMXSbFC1tZKwA=="], @@ -1038,7 +1043,7 @@ "bowser": ["bowser@2.14.1", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="], - "brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="], + "brace-expansion": ["brace-expansion@5.0.12", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ=="], "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="], @@ -1166,7 +1171,7 @@ "enhanced-resolve": ["enhanced-resolve@5.24.2", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.3" } }, "sha512-rpsZEGT1jFuve6QlpyRp9ckQ+kN61hvF9BzCPyMdaKTm8UJce96KBn3sorXOFXlzjPrs3Vc4T1NsSroZ3PxlFw=="], - "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="], + "entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="], "err-code": ["err-code@2.0.3", "", {}, "sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA=="], @@ -1186,6 +1191,8 @@ "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="], + "extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="], + "fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="], "fastq": ["fastq@1.20.1", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="], @@ -1270,6 +1277,8 @@ "is-empty": ["is-empty@1.2.0", "", {}, "sha512-F2FnH/otLNJv0J6wc73A5Xo7oHLNnqplYqZhUu01tD54DIPvxIRSTSLkrUB/M0nHO4vo1O9PDfN4KoTxCzLh/w=="], + "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="], + "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="], "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="], @@ -1302,6 +1311,8 @@ "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="], + "js-yaml": ["js-yaml@4.3.2", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA=="], + "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="], "json-parse-even-better-errors": ["json-parse-even-better-errors@3.0.2", "", {}, "sha512-fi0NG4bPjCHunUJffmLd0gxssIgkNmArMvis4iNah6Owg1MCJjWhEcDLmsK6iGkJq3tHwbDkTlce70/tmXN4cQ=="], @@ -1310,6 +1321,8 @@ "jsonfile": ["jsonfile@6.2.1", "", { "dependencies": { "universalify": "^2.0.0" }, "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q=="], + "kind-of": ["kind-of@6.0.3", "", {}, "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="], + "kleur": ["kleur@4.1.5", "", {}, "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ=="], "lightningcss": ["lightningcss@1.33.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.33.0", "lightningcss-darwin-arm64": "1.33.0", "lightningcss-darwin-x64": "1.33.0", "lightningcss-freebsd-x64": "1.33.0", "lightningcss-linux-arm-gnueabihf": "1.33.0", "lightningcss-linux-arm64-gnu": "1.33.0", "lightningcss-linux-arm64-musl": "1.33.0", "lightningcss-linux-x64-gnu": "1.33.0", "lightningcss-linux-x64-musl": "1.33.0", "lightningcss-win32-arm64-msvc": "1.33.0", "lightningcss-win32-x64-msvc": "1.33.0" } }, "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA=="], @@ -1338,6 +1351,8 @@ "lines-and-columns": ["lines-and-columns@2.0.4", "", {}, "sha512-wM1+Z03eypVAVUCE7QdSqpVIvelbOakn1M0bPDoA4SGWPx3sNDVUiMo3L6To6WWGClB7VyXnhQ4Sn7gxiJbE6A=="], + "linkify-it": ["linkify-it@5.0.2", "", { "dependencies": { "uc.micro": "^2.0.0" } }, "sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q=="], + "load-plugin": ["load-plugin@6.0.3", "", { "dependencies": { "@npmcli/config": "^8.0.0", "import-meta-resolve": "^4.0.0" } }, "sha512-kc0X2FEUZr145odl68frm+lMJuQ23+rTXYmR6TImqPtbpmXC4vVXbWKDQ9IzndA0HfyQamWfKLhzsqGSTxE63w=="], "longest-streak": ["longest-streak@3.1.0", "", {}, "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g=="], @@ -1352,6 +1367,10 @@ "markdown-extensions": ["markdown-extensions@2.0.0", "", {}, "sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q=="], + "markdown-it": ["markdown-it@14.3.2", "", { "dependencies": { "argparse": "^2.0.1", "entities": "^4.5.0", "linkify-it": "^5.0.2", "mdurl": "^2.0.0", "punycode.js": "^2.3.1", "uc.micro": "^2.1.0" }, "bin": { "markdown-it": "bin/markdown-it.mjs" } }, "sha512-sHHjZ5fJKlgrG4qns2YwVcdNep35h5fERrfkD2YNsb9UFk0UIHarbiTaHKVMlPuWAoiilyK8Fv/jAm11slsY7Q=="], + + "markdown-title": ["markdown-title@1.0.2", "", {}, "sha512-MqIQVVkz+uGEHi3TsHx/czcxxCbRIL7sv5K5DnYw/tI+apY54IbPefV/cmgxp6LoJSEx/TqcHdLs/298afG5QQ=="], + "mdast-comment-marker": ["mdast-comment-marker@3.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-mdx-expression": "^2.0.0" } }, "sha512-bt08sLmTNg00/UtVDiqZKocxqvQqqyQZAg1uaRuO/4ysXV5motg7RolF5o5yy/sY1rG0v2XgZEqFWho1+2UquA=="], "mdast-util-directive": ["mdast-util-directive@3.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "devlop": "^1.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0", "parse-entities": "^4.0.0", "stringify-entities": "^4.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-I3fNFt+DHmpWCYAT7quoM6lHf9wuqtI+oCOfvILnoicNIqjh5E3dEJWiXuYME2gNe8vl1iMQwyUHa7bgFmak6Q=="], @@ -1382,6 +1401,8 @@ "mediabunny": ["mediabunny@1.54.0", "", { "dependencies": { "@types/dom-mediacapture-transform": "^0.1.11", "@types/dom-webcodecs": "0.1.13" } }, "sha512-L7yaV6iS6SYtHAs0FPQsAy1fprwvoX39WqbAD7GaCQVXKj/7zwxlAQkCkL2K52XakuDES8lbRRNpUlGWUOnv8Q=="], + "mdurl": ["mdurl@2.1.0", "", {}, "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg=="], + "merge-anything": ["merge-anything@5.1.7", "", { "dependencies": { "is-what": "^4.1.8" } }, "sha512-eRtbOb1N5iyH0tkQDAoQ4Ipsp/5qSR79Dzrz8hEPxRX10RWWR/iQXdoKmBSRCThY1Fh5EhISDtpSc93fpxUniQ=="], "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="], @@ -1432,11 +1453,13 @@ "micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="], + "millify": ["millify@6.1.0", "", { "dependencies": { "yargs": "^17.0.1" }, "bin": { "millify": "bin/millify" } }, "sha512-H/E3J6t+DQs/F2YgfDhxUVZz/dF8JXPPKTLHL/yHCcLZLtCXJDUaqvhJXQwqOVBvbyNn4T0WjLpIHd7PAw7fBA=="], + "mimic-response": ["mimic-response@3.1.0", "", {}, "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ=="], "miniflare": ["miniflare@5.20260903.0-alpha", "", { "dependencies": { "@cspotcode/source-map-support": "0.8.1", "sharp": "0.35.2", "undici": "7.29.0", "workerd": "1.20260903.1", "ws": "8.21.0", "youch": "4.1.0-beta.10" } }, "sha512-VCZIFxOqFXeibRBJWwTlppqbv2lkeO10IX3QBRGK9j1QiMAfH/OSsCvbjp1MslBMhVZmy2VTRlVaVnsKnbDp6A=="], - "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="], + "minimatch": ["minimatch@10.2.6", "", { "dependencies": { "brace-expansion": "^5.0.8" } }, "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A=="], "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="], @@ -1540,6 +1563,8 @@ "prebuild-install": ["prebuild-install@7.1.3", "", { "dependencies": { "detect-libc": "^2.0.0", "expand-template": "^2.0.3", "github-from-package": "0.0.0", "minimist": "^1.2.3", "mkdirp-classic": "^0.5.3", "napi-build-utils": "^2.0.0", "node-abi": "^3.3.0", "pump": "^3.0.0", "rc": "^1.2.7", "simple-get": "^4.0.0", "tar-fs": "^2.0.0", "tunnel-agent": "^0.6.0" }, "bin": { "prebuild-install": "bin.js" } }, "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug=="], + "pretty-bytes": ["pretty-bytes@7.1.3", "", {}, "sha512-U2KZ675nqba6XSBppSjU2pRgc9Ffx9+uUtd/RTWYmOawVkZuUbBYuwdtFZQmLv+yMgQ2TQxWWuOpyNje67J9tg=="], + "proc-log": ["proc-log@4.2.0", "", {}, "sha512-g8+OnU/L2v+wyiVK+D5fA34J7EH8jZ8DDlvwhRCMxmMj7UCBvxiO1mGeN+36JXIKF4zevU4kRBd8lVgG9vLelA=="], "promise-inflight": ["promise-inflight@1.0.1", "", {}, "sha512-6zWPyEOFaQBJYcGMHBKTKJ3u6TBsnMFOIZSa6ce1e/ZrrsOlnHRHbabMjLiBYKp+n44X9eUI6VUPaukCXHuG4g=="], @@ -1552,6 +1577,8 @@ "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="], + "punycode.js": ["punycode.js@2.3.1", "", {}, "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA=="], + "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="], "rc": ["rc@1.2.8", "", { "dependencies": { "deep-extend": "^0.6.0", "ini": "~1.3.0", "minimist": "^1.2.0", "strip-json-comments": "~2.0.1" }, "bin": { "rc": "./cli.js" } }, "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw=="], @@ -1670,6 +1697,8 @@ "search-insights": ["search-insights@2.17.3", "", {}, "sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ=="], + "section-matter": ["section-matter@1.0.0", "", { "dependencies": { "extend-shallow": "^2.0.1", "kind-of": "^6.0.0" } }, "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA=="], + "semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="], "seroval": ["seroval@1.5.4", "", {}, "sha512-46uFvgrXTVxZcUorgSSRZ4y+ieqLLQRMlG4bnCZKW3qI6BZm7Rg4ntMW4p1mILEEBZWrFlcpp0AyIIlM6jD9iw=="], @@ -1756,6 +1785,8 @@ "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="], + "tokenx": ["tokenx@1.6.0", "", {}, "sha512-CKTjk345ajvBAUp5xUI9a5KKN0zU0lBueVHQbCskH1Hp6WkUKsPW2qGCYNs0pxNyfzxfo+IIjdt2W4sMbw/qBw=="], + "tree-kill": ["tree-kill@1.2.2", "", { "bin": { "tree-kill": "cli.js" } }, "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A=="], "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="], @@ -1774,6 +1805,8 @@ "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="], + "uc.micro": ["uc.micro@2.1.0", "", {}, "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A=="], + "undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="], "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="], @@ -1796,6 +1829,8 @@ "unist-util-position": ["unist-util-position@5.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA=="], + "unist-util-remove": ["unist-util-remove@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg=="], + "unist-util-stringify-position": ["unist-util-stringify-position@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ=="], "unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="], @@ -1836,6 +1871,8 @@ "vitepress": ["vitepress@1.6.4", "", { "dependencies": { "@docsearch/css": "3.8.2", "@docsearch/js": "3.8.2", "@iconify-json/simple-icons": "^1.2.21", "@shikijs/core": "^2.1.0", "@shikijs/transformers": "^2.1.0", "@shikijs/types": "^2.1.0", "@types/markdown-it": "^14.1.2", "@vitejs/plugin-vue": "^5.2.1", "@vue/devtools-api": "^7.7.0", "@vue/shared": "^3.5.13", "@vueuse/core": "^12.4.0", "@vueuse/integrations": "^12.4.0", "focus-trap": "^7.6.4", "mark.js": "8.11.1", "minisearch": "^7.1.1", "shiki": "^2.1.0", "vite": "^5.4.14", "vue": "^3.5.13" }, "peerDependencies": { "markdown-it-mathjax3": "^4", "postcss": "^8" }, "optionalPeers": ["markdown-it-mathjax3", "postcss"], "bin": { "vitepress": "bin/vitepress.js" } }, "sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg=="], + "vitepress-plugin-llms": ["vitepress-plugin-llms@1.14.0", "", { "dependencies": { "@11ty/gray-matter": "^2.1.0", "markdown-it": "^14.1.0", "markdown-title": "^1.0.2", "mdast-util-from-markdown": "^2.0.3", "millify": "^6.1.0", "minimatch": "^10.2.6", "path-to-regexp": "^6.3.0", "picocolors": "^1.1.1", "pretty-bytes": "^7.1.1", "remark": "^15.0.1", "remark-frontmatter": "^5.0.0", "tokenx": "^1.6.0", "unist-util-remove": "^4.0.0", "unist-util-visit": "^5.1.0" } }, "sha512-Qb42p9pYoRlMRbv+Yvh3reS4GInyr+ToU3G1tEC1Euz+gyBNywXkZIQPV/AoltizaakAeuI89Bkhkd7Y0jaM/w=="], + "vue": ["vue@3.5.39", "", { "dependencies": { "@vue/compiler-dom": "3.5.39", "@vue/compiler-sfc": "3.5.39", "@vue/runtime-dom": "3.5.39", "@vue/server-renderer": "3.5.39", "@vue/shared": "3.5.39" }, "peerDependencies": { "typescript": "*" }, "optionalPeers": ["typescript"] }, "sha512-xmZCYabFGcirU8r0fTuvl/LICc1OU620rnqepaJDL/a141ZigkG7AyaxQLdqJ02ZRYzWe6YPaDHeQx7MfknQfA=="], "walk-up-path": ["walk-up-path@3.0.1", "", {}, "sha512-9YlCL/ynK3CTlrSRrDxZvUauLzAswPCrsaCgilqFevUYpeEW0/3ScEjaa3kbW/T0ghhkEr7mv+fpjqn1Y1YuTA=="], @@ -1986,12 +2023,16 @@ "filelist/minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="], + "glob/minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="], + "hosted-git-info/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="], "html-minifier-terser/commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="], "micromatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="], + "millify/yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="], + "node-abi/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], "normalize-package-data/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], @@ -2004,6 +2045,8 @@ "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="], + "parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="], + "readdirp/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="], "sharp/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], @@ -2142,6 +2185,14 @@ "filelist/minimatch/brace-expansion": ["brace-expansion@2.1.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA=="], + "glob/minimatch/brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="], + + "millify/yargs/cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="], + + "millify/yargs/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="], + + "millify/yargs/yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="], + "solid-refresh/@babel/types/@babel/helper-string-parser": ["@babel/helper-string-parser@7.29.7", "", {}, "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw=="], "solid-refresh/@babel/types/@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.29.7", "", {}, "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg=="], @@ -2240,6 +2291,14 @@ "filelist/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="], + "millify/yargs/cliui/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="], + + "millify/yargs/cliui/wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="], + + "millify/yargs/string-width/emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="], + + "millify/yargs/string-width/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="], + "unified-engine/glob/minimatch/brace-expansion": ["brace-expansion@2.1.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA=="], "unified-engine/glob/path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="], @@ -2300,6 +2359,12 @@ "cmake-js/yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], + "millify/yargs/cliui/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], + + "millify/yargs/cliui/wrap-ansi/ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="], + + "millify/yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], + "unified-engine/glob/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="], } } diff --git a/doc/.vitepress/config.ts b/doc/.vitepress/config.ts index 299b9a9a1e9..40e7471d566 100644 --- a/doc/.vitepress/config.ts +++ b/doc/.vitepress/config.ts @@ -1,4 +1,5 @@ import { defineConfig } from "vitepress"; +import llmstxt from "vitepress-plugin-llms"; import { syncDrafts } from "./drafts"; // Generated before VitePress enumerates routes, so the pages and this sidebar @@ -232,6 +233,18 @@ export default defineConfig({ lineNumbers: true, }, + // Serves /llms.txt (an index), /llms-full.txt (every page inline), and a + // .md twin of every page so agents can read the docs without the HTML. + vite: { + plugins: [ + llmstxt({ + domain: "https://doc.moq.dev", + // Static files are already served verbatim. + ignoreFiles: ["public/**"], + }), + ], + }, + ignoreDeadLinks: [ // Localhost URLs are intentional for development examples and aren't // reachable at build time (e.g. the relay on :4443, the dev server on :5173). diff --git a/doc/.vitepress/drafts.ts b/doc/.vitepress/drafts.ts index 87d61520ee5..01e8f5293e5 100644 --- a/doc/.vitepress/drafts.ts +++ b/doc/.vitepress/drafts.ts @@ -383,9 +383,16 @@ function render(source: string, routes: Map): { meta: Metadata; return out; }; + // The abstract's first line doubles as the page description for llms.txt + // and the meta tag, with citations reduced to their labels. + const description = cite(abstract.find((line) => line.trim() !== "") ?? "") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + const page = [ "---", `title: ${JSON.stringify(meta.title)}`, + `description: ${JSON.stringify(description)}`, "outline: deep", "---", "", diff --git a/doc/index.md b/doc/index.md index e217716fcf2..99cad74bd59 100644 --- a/doc/index.md +++ b/doc/index.md @@ -101,7 +101,7 @@ If everything works, a browser window will pop up demoing how to both publish an - Keep reading the [development guide](/setup/dev) to run more advanced demos. - Skip ahead to the [production guide](/setup/prod) to see what it takes to deploy this bad boy. -- Using an AI coding agent? [Teach it MoQ](/setup/agent) with a one-line prompt. +- Using an AI coding agent? [Teach it MoQ](/setup/agent) with a one-line prompt, or point it at [llms.txt](/llms.txt). ## Applications diff --git a/doc/package.json b/doc/package.json index 508a639a492..53dc554a2bc 100644 --- a/doc/package.json +++ b/doc/package.json @@ -16,6 +16,7 @@ "@types/node": "^26.4.1", "typescript": "7.0.2", "vitepress": "^1.6.4", + "vitepress-plugin-llms": "^1.14.0", "wrangler": "^4.129.0", "yaml": "^2.9.0" } diff --git a/doc/public/setup/agent/prompt.md b/doc/public/setup/agent/prompt.md index 825f0fc41f5..fdce4b16055 100644 --- a/doc/public/setup/agent/prompt.md +++ b/doc/public/setup/agent/prompt.md @@ -15,7 +15,7 @@ Notes: - Add `--global` to install user-level instead of project-level. - Add `-a ` (e.g. `-a claude-code`) to target a specific agent instead of auto-detection. -The skill teaches the agent the MoQ architecture, the `@moq/*` npm packages and `moq-*` Rust crates, the web components, relay setup, and common pitfalls. +The skill tells the agent what MoQ is and how to read the documentation as markdown (https://doc.moq.dev/llms.txt) instead of guessing APIs. ## Verify diff --git a/doc/setup/agent.md b/doc/setup/agent.md index 6f2a10fa8b5..46e05f6d55b 100644 --- a/doc/setup/agent.md +++ b/doc/setup/agent.md @@ -11,7 +11,7 @@ Using an AI coding agent like Claude Code, Cursor, or Codex? Teach it MoQ by pas Follow the instructions at https://doc.moq.dev/setup/agent/prompt.md ``` -The agent will fetch the instructions and install the [MoQ skill](https://github.com/moq-dev/moq/tree/main/skills/moq) into your project. The skill is an index of the MoQ ecosystem: what you can build (live streaming, conferencing, voice AI, real-time data, and more) and which [`@moq/*`](/lib/js/) packages, [`moq-*`](/lib/rs/) crates, gateways, and plugins to reach for, so the agent starts from the right layer instead of hallucinating an API. +The agent will fetch the instructions and install the [MoQ skill](https://github.com/moq-dev/moq/tree/main/skills/moq) into your project. The skill tells the agent what MoQ is and to read this site as markdown (see below) instead of hallucinating an API. ## Manual Installation @@ -25,6 +25,10 @@ Add `--global` for a user-level install, or `-a ` to target a specific ag ## What's in the Skill? -The skill is a single markdown file, [`skills/moq/SKILL.md`](https://github.com/moq-dev/moq/blob/main/skills/moq/SKILL.md), that your agent loads when a task involves MoQ. It's a map rather than a manual: use cases matched to the libraries, binaries, and gateways that implement them, plus links back to [doc.moq.dev](https://doc.moq.dev) for the details. +The skill is a single markdown file, [`skills/moq/SKILL.md`](https://github.com/moq-dev/moq/blob/main/skills/moq/SKILL.md), that your agent loads when a task involves MoQ. It's deliberately short: what MoQ is, a pointer to this site, and the few facts that don't change, so it never goes stale as the packages evolve. Contributions welcome; it's just markdown. + +## Reading the Docs + +Every page on this site is also served as plain markdown: drop any trailing `/` and append `.md`, so `/bin/relay/` becomes `/bin/relay.md` and `/lib/js/watch` becomes `/lib/js/watch.md`. [`/llms.txt`](/llms.txt) indexes every page with a one-line description, and [`/llms-full.txt`](/llms-full.txt) bundles them all into one file, following the [llms.txt](https://llmstxt.org) convention. diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 50783cd3c46..474d2cb429d 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -32,13 +32,18 @@ informative: --- abstract This document defines a clustering extension for MoQ Transport {{moqt}}, used to build a mesh of relays. -Each namespace advertisement carries the ordered list of Hop IDs it has traversed, starting with the original publisher, plus the accumulated cost of that path. -A receiver uses the list to detect routing loops and to identify which advertisements come from the same publisher, and the cost to choose between paths. -Each endpoint declares its own Hop ID during setup, and the peer uses it to avoid advertising or serving a path that already passed through that endpoint. -Pattern advertisements are defined and negotiated independently by {{I-D.lcurley-moq-pattern}}; this extension supplies their routing metadata when both are enabled. +Each namespace advertisement carries the list of Hop IDs it has passed through, starting with the original publisher, and the accumulated cost of that path. +A receiver uses the list to detect loops and to tell which advertisements come from the same publisher, and the cost to choose between paths. +Each endpoint declares its own Hop ID at setup, so a peer never advertises or serves it a path that already passed through it. +Pattern advertisements are defined and negotiated separately by {{I-D.lcurley-moq-pattern}}; this extension supplies their routing metadata when both are enabled. --- middle +# Note to Readers +This document was written with the assistance of Claude, an AI model by Anthropic. +The author reviewed every revision and is responsible for its content. + + # Conventions and Definitions {::boilerplate bcp14-tagged} @@ -47,40 +52,36 @@ The same pair of relays can be upstream of each other for different namespaces. # Introduction -{{moqt}} is designed to deliver content through a mesh of relays, but is deliberately vague about how that mesh is built, and the base transport does not carry enough information to build one. +{{moqt}} is designed to deliver content through a mesh of relays but does not say how to build one, and the base protocol does not carry enough information to do so. +Relays that simply forward PUBLISH_NAMESPACE to each other break down: advertisements loop forever, and a relay that hears one namespace from two peers has no basis for choosing where to send a SUBSCRIBE. -Relays that gossip namespaces with PUBLISH_NAMESPACE quickly break down: advertisements loop between relays forever, and when two connections advertise the same namespace, a relay has no basis for deciding which one to route a SUBSCRIBE toward. +This extension adds two parameters to PUBLISH_NAMESPACE and NAMESPACE. +HOP_PATH lists every endpoint an advertisement has passed through, starting with the original publisher, which breaks loops and lets paths be compared. +ROUTE_COST is the accumulated price of the path: the publisher seeds it, and each hop adds the RELAY_COST its upstream declared at setup, so an unpriced mesh ranks by hop count. +A relay that already carries a namespace advertises a lower cost, steering subscribers toward its warm copy. -This extension adds the HOP_PATH parameter to PUBLISH_NAMESPACE and NAMESPACE. -It lists every node an advertisement has passed through, starting with the original publisher, which is enough to break loops and to compare paths. -Each connection also declares its own Hop ID at SETUP, so loops are avoided even across multiple connections between the same pair of relays. - -Not every route is equal: one crossing a metered backbone costs more than one inside a datacenter. -The RELAY_COST Setup Option prices what subscribing from an endpoint costs, defaulting to 1 so an unpriced mesh simply ranks by hop count. -The ROUTE_COST parameter carries the accumulated price per namespace, and a relay may lower it to advertise that it already has the content cached, steering subscribers toward a warm copy. +Each endpoint also declares its own Hop ID at setup, so a peer can leave it out of every path it advertises or serves to it, even across several connections between the same two relays. +An advertisement is one path, so a relay forwards only the best path it knows per namespace and serves a subscription from one source at a time ({{publishers}}). # Setup Negotiation -## Relay Hops -The extension is negotiated during the SETUP exchange ({{moqt}} Section 10.3). -An endpoint indicates support with the following Setup Option, whose value is its own Hop ID: +## Hop ID {#hop-id} +The extension is negotiated during SETUP ({{moqt}} Section 10.3). +An endpoint offers it by declaring its own Hop ID: ~~~ -RELAY_HOPS Setup Option { - Option Key (vi64) = 0x40B55 - Option Value Length (vi64) +HOP_ID Setup Option { + Option Key (vi64) = 0x40B54 Hop ID (vi64) } ~~~ -Negotiation is per session; a relay MUST NOT assume that because one of its sessions negotiated Relay Hops, another did. -It also enables the extended NAMESPACE message ({{namespace}}), which is what lets a NAMESPACE carry these parameters at all. - -On a session that negotiated the extension, an endpoint MUST include HOP_PATH on every PUBLISH_NAMESPACE and NAMESPACE it sends, and a receiver MUST close the session with a PROTOCOL_VIOLATION if one arrives without it. +Negotiation is per session; a relay MUST NOT assume that because one session negotiated the extension, another did. +On a session that did, every PUBLISH_NAMESPACE and NAMESPACE MUST carry HOP_PATH, NAMESPACE takes the extended form in {{namespace}}, and a receiver MUST close the session with a PROTOCOL_VIOLATION if either arrives without HOP_PATH. -## Relay Cost -An endpoint MAY declare what subscribing from it costs: +## Relay Cost {#relay-cost} +An endpoint MAY declare what it charges for sending content: ~~~ RELAY_COST Setup Option { @@ -89,61 +90,64 @@ RELAY_COST Setup Option { } ~~~ -The option prices one direction, the sender's own egress, so each endpoint declares its own and the two need not match. -A receiver adds the value the sender declared to the ROUTE_COST of every advertisement that sender forwards. -An absent option means 1, under which the accumulated cost equals the hop count. -0 is meaningful and distinct from absent: it makes that direction free, which is how a deployment describes two relays in the same datacenter. +The value prices the sender's own egress, so each endpoint declares its own and the two need not match, as OSPF prices each router's own output interfaces ({{?RFC2328, Section 9}}). +A receiver adds it to the ROUTE_COST of every advertisement that peer forwards ({{accumulating}}). +Absent means 1, so an unpriced mesh ranks by hop count. +0 is distinct from absent: it makes the link free, which is how to describe two relays in the same datacenter. -A declared cost is an assertion, not an instruction: a receiver MAY charge a locally configured value instead, so a peer cannot reprice its neighbours by declaring itself cheap. +A declared cost is an assertion, not an instruction: a receiver MAY charge a locally configured value instead, so a peer cannot make itself cheap by saying so. +The cost is one dimensionless integer, as in every deployed routing metric: RIP's hop count ({{?RFC2453, Section 3.5}}), OSPF's interface cost, and IS-IS's default metric, whose delay, expense, and error metrics went unimplemented ({{?RFC5305, Section 3}}), as did OSPF's per-type-of-service metrics ({{?RFC2178, Appendix G.10}}). +A deployment that weighs latency, hop count, and price folds them into the one value. +Like BGP's MULTI_EXIT_DISC ({{?RFC4271, Section 5.1.4}}), the value only means something within the deployment that chose its units, so a trust boundary clamps or replaces it ({{security}}). -# Hop IDs -A **Hop ID** is a variable-length integer identifying one endpoint within an advertisement's path. + +# Hop IDs {#hop-ids} +A **Hop ID** is a variable-length integer naming one endpoint in a path. Hop IDs SHOULD be unique among the endpoints an advertisement can traverse. -An endpoint MAY generate one randomly, since collisions across a 64-bit space are unlikely, or use a stable configured identifier that survives restarts. +An endpoint MAY pick one at random, since collisions in a 64-bit space are unlikely, or use a configured identifier that survives restarts. -Loop detection and origin identification compare Hop IDs for equality, so two endpoints sharing a Hop ID are indistinguishable. +Loops and origins are detected by comparing Hop IDs for equality, so two endpoints sharing one are indistinguishable. +Redundant publishers of interchangeable content MAY share one deliberately, so the mesh treats their paths as failover options for the same content ({{selection}}). ## The Reserved Hop ID 0 {#zero} **0 means "no identity"** and is reserved. -It is used for an endpoint that did not negotiate this extension, and an endpoint MAY also declare 0 to withhold its identity. +It stands for an endpoint that did not negotiate this extension, and an endpoint MAY declare it to withhold its identity. -Because any number of endpoints can be 0, it identifies nothing, which constrains all three uses: +Since any number of endpoints can be 0, it identifies nothing: -- **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself, and MUST NOT discard an advertisement merely because the path contains 0. -- **Origin identity**: an advertisement whose first entry is 0 has an unknown origin. Updating one advertisement is not two ({{updating}}). -- **Filtering**: a peer that declared 0 declared no identity, so there is nothing on the wire to filter that session on. A receiver MAY assign one ({{assigned}}), which covers what it attributes to that session itself but not an advertisement that arrived carrying its own HOP_PATH. +- **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself and MUST NOT discard an advertisement merely because the path contains 0. +- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher. A receiver MUST NOT treat two such advertisements as interchangeable ({{selection}}). +- **Filtering**: a peer that declared 0 gave the receiver nothing to filter that session on. The receiver MAY assign an ID of its own ({{assigned}}). Duplicate *non-zero* Hop IDs in one HOP_PATH are a loop; duplicate zeros are not. -Declaring 0 therefore trades loop detection and failover for anonymity, except against a receiver that assigns an identity of its own. +Declaring 0 trades loop detection and failover for anonymity, except against a receiver that assigns an identity of its own. ## Assigned Identities {#assigned} -A receiver MAY assign a Hop ID of its own to a peer that declared none, whether by declaring 0 or by not negotiating this extension at all. -It uses that ID wherever it would otherwise have nothing to name the peer with: as the entry it creates for an upstream that sent no HOP_PATH, and as what it filters that session on. +A receiver MAY assign a Hop ID to a peer that declared none, whether by declaring 0 or by not negotiating the extension. +It uses that ID wherever it has nothing else to name the peer with: as the first entry of a HOP_PATH it creates for an upstream that sent none, and as what it filters that session on. -The ID is the receiver's own, not the peer's. -An advertisement that arrives carrying its own HOP_PATH names the sender there, as 0 if the sender withheld it, and this document does not define rewriting that entry. -So an assigned ID governs the advertisements a receiver attributed itself, and a peer that both declares 0 and sends its own HOP_PATH keeps the consequences in {{zero}}. +The ID is the receiver's own. +An advertisement that arrives with its own HOP_PATH already names the sender there, as 0 if withheld, and this document does not define rewriting that entry. +So an assigned ID covers what the receiver itself attributes to the session; a peer that declares 0 and sends its own HOP_PATH keeps the consequences in {{zero}}. An assigned ID MUST NOT be shared between peers not known to be the same endpoint. -Sharing one suppresses each one's advertisements to the other, so two unrelated publishers would starve each other of routes. +Sharing one makes their content interchangeable ({{selection}}) and suppresses each one's advertisements to the other, so two unrelated publishers would be merged into one and starve each other of routes. -How an endpoint scopes the ID follows from what it can establish about the peer. -One it authenticated, or one it dialed and therefore chose, SHOULD get a single stable ID; assigning per connection there would make one peer look like several. -An endpoint accepting an anonymous session can establish nothing and cannot correlate it with any other, so it SHOULD assign a distinct ID per session: less than an identity, but enough to keep routes it attributed to that session from being advertised back to it, which is the loop 0 cannot prevent. +A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one stable ID, so its reconnects and redundant sessions are recognized as the same content; a fresh ID per connection would make one peer look like several. +An anonymous accepted session cannot be correlated with anything, so it SHOULD get a distinct ID per session: not an identity, but enough to keep routes learned from it from being advertised back to it, which is the loop 0 cannot prevent. -An assigned ID is indistinguishable on the wire from a declared one, so it identifies the peer to everyone the receiver forwards to; a peer that declared 0 for anonymity did not ask for that. +An assigned ID looks like a declared one on the wire, so it identifies the peer to everyone downstream; a peer that declared 0 for anonymity did not ask for that. # Namespace Advertisements {#namespace} -This extension carries HOP_PATH and ROUTE_COST as Key-Value-Pair parameters ({{moqt}} Section 2.5). -PUBLISH_NAMESPACE ({{moqt}} Section 10.15) already has a Parameters field. - -NAMESPACE ({{moqt}} Section 10.16) does not, and a subscriber-driven mesh propagates advertisements as NAMESPACE messages, so this extension defines a parameter block enabled by Relay Hops. The pattern extension can independently enable the same block: +HOP_PATH and ROUTE_COST are Key-Value-Pair parameters ({{moqt}} Section 2.5). +PUBLISH_NAMESPACE ({{moqt}} Section 10.15) already carries parameters. +NAMESPACE ({{moqt}} Section 10.16) does not, and a subscriber-driven mesh propagates advertisements as NAMESPACE, so this extension appends a parameter block to it: ~~~ -NAMESPACE Message (Relay Hops) { +NAMESPACE Message (Cluster) { Type (vi64) = 0x8, Length (16), Track Namespace Suffix (..), @@ -152,17 +156,17 @@ NAMESPACE Message (Relay Hops) { } ~~~ -The appended fields are encoded exactly as in PUBLISH_NAMESPACE. -Negotiating either Relay Hops or the pattern extension {{I-D.lcurley-moq-pattern}} enables this same parameter block on every NAMESPACE message, including a zero parameter count when empty. When both are negotiated, an endpoint appends one block containing the parameters from both extensions, not two blocks. -An endpoint MUST NOT append the block when neither extension is negotiated, and MUST NOT include HOP_PATH or ROUTE_COST unless Relay Hops is negotiated. +The added fields are encoded exactly as in PUBLISH_NAMESPACE. +Negotiating either this extension or {{I-D.lcurley-moq-pattern}} enables the block on every NAMESPACE, with a parameter count of 0 when it is empty; when both are negotiated an endpoint appends one block holding the parameters of both, not two blocks. +An endpoint MUST NOT append the block when neither is negotiated, and MUST NOT include HOP_PATH or ROUTE_COST unless this extension is. -NAMESPACE_DONE ({{moqt}} Section 10.17) carries no state from this extension. Its pattern parameter block is present only when {{I-D.lcurley-moq-pattern}} is negotiated, irrespective of Relay Hops. +NAMESPACE_DONE ({{moqt}} Section 10.17) carries no state from this extension; its pattern block is present only when {{I-D.lcurley-moq-pattern}} is negotiated. -An advertisement is a claim of capability, not inventory: it says namespaces beneath the advertised one can be served, never that any exists. +An advertisement claims capability, not inventory: namespaces beneath the advertised one can be served, not that any exists. Patterns and per-request refusals follow {{I-D.lcurley-moq-pattern}}. ## HOP_PATH Parameter {#hop-path} -HOP_PATH is the ordered list of Hop IDs an advertisement has traversed, from the original publisher to the relay immediately upstream of the receiver: +HOP_PATH is the ordered list of Hop IDs an advertisement has passed through, from the original publisher to the peer sending it: ~~~ HOP_PATH Parameter { @@ -172,11 +176,11 @@ HOP_PATH Parameter { } ~~~ -The list always has at least one entry, the original publisher, which is 0 if that publisher is unknown ({{zero}}). -A receiver MUST close the session with a PROTOCOL_VIOLATION if the entries do not exactly fill `Length`, if the list is empty, or if a non-zero Hop ID appears twice. +The list always has at least one entry, the original publisher, 0 if unknown ({{zero}}). +A receiver MUST close the session with a PROTOCOL_VIOLATION if the list is empty, if the entries do not exactly fill `Length`, or if a non-zero Hop ID appears twice. -## ROUTE_COST Parameter -ROUTE_COST is the marginal cost of subscribing via this advertisement: the price of the transfers a new subscription would actually cause. +## ROUTE_COST Parameter {#route-cost} +ROUTE_COST is the marginal cost of subscribing through this advertisement: the price of the transfers a new subscription would cause. ~~~ ROUTE_COST Parameter { @@ -185,89 +189,111 @@ ROUTE_COST Parameter { } ~~~ -It is OPTIONAL and absent means 0, so an endpoint that prices nothing sends nothing. -Costs still accumulate across such a mesh, because each receiver adds the price for the direction it received over ({{relay-cost}}) regardless. +It is OPTIONAL and absent means 0. +Costs still accumulate across a mesh that sends none, because each receiver adds the RELAY_COST of the link it received over ({{accumulating}}). + +The original publisher seeds the value with its production cost: 0 for content it already produces, higher for content it would have to start on demand, such as a standby transcoder advertising everything it could serve. + +A standby seed only ranks last if no live path can accumulate past it, which is a property of the deployment, not of the number. +A deployment relying on standby ordering within one specificity tier ({{selection}}) MUST bound the charged links on an admitted path by H and each link's cost by C, including the receiving link, and MUST enforce both when admitting paths and links. +Its live publishers MUST seed 0 and its standby publishers MUST seed above H * C and below saturation; 2^32 is RECOMMENDED where H * C < 2^32. +Unknown, out-of-budget, and saturated routes are outside the guarantee: a receiver MUST NOT rank them above standby capacity on the guess that they already carry content. -The original publisher seeds the value with its production cost: 0 for content it is already producing, higher for content it would have to spin up on demand, such as a standby transcoder advertising everything it *could* serve. -Standby ordering is a deployment guarantee within one specificity tier, not a bound on every representable Route Cost. -A deployment relying on it MUST bound the number of charged links on an admitted path by H and each charged link cost by C, including the receiving link, and MUST enforce those bounds when admitting paths and links. -Already-producing origins in that deployment MUST seed their cost at 0; standby origins MUST choose a seed S satisfying `H * C < S < saturation ceiling`. -A seed of `2^32` is RECOMMENDED only when `H * C < 2^32`; otherwise the deployment must choose a larger seed or tighter bounds. -Unknown, out-of-budget, and saturated routes are outside this guarantee; a receiver MUST NOT infer that they outrank standby capacity merely because they might already carry content. # Relay Behavior -When forwarding an advertisement downstream, a relay MUST append its own Hop ID to the HOP_PATH it received, so its own ID is always the last entry. -An advertisement arriving from an upstream that did not negotiate the extension has no HOP_PATH; the relay creates one containing a single entry for that upstream, 0 ({{zero}}) or an ID it assigned ({{assigned}}), then appends its own. +A relay forwarding an advertisement MUST append its own Hop ID to the HOP_PATH it received, so its ID is always the last entry. +An upstream that did not negotiate the extension sends no HOP_PATH; the relay creates one with a single entry for that upstream, 0 ({{zero}}) or an assigned ID ({{assigned}}), then appends its own. -On receipt, a relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. -This receiver-side check catches loops of any length and is the only loop defense required. -A conforming sender never sends one ({{selection}}), so a receiver MAY instead close the session with a PROTOCOL_VIOLATION; discarding is what keeps a mesh working when one member does not conform. +A relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. +This check catches loops of any length and is the only loop defense required. +A conforming sender never sends one ({{selection}}), so a receiver MAY close the session with a PROTOCOL_VIOLATION instead; discarding is what keeps the mesh working when one member does not conform. -## Accumulating Cost -A relay MUST add the cost the sending endpoint declared ({{relay-cost}}) to the ROUTE_COST it received before forwarding or acting on an advertisement. -The addition MUST saturate rather than wrap, so an absurd upstream value ranks last instead of overflowing to best. +## Accumulating Cost {#accumulating} +Before forwarding or acting on an advertisement, a relay MUST add the RELAY_COST the sender declared ({{relay-cost}}) to the ROUTE_COST it received. +The addition MUST saturate rather than wrap, so an absurd value ranks last instead of overflowing to best. -A relay actively carrying the namespace (a live subscription exists for at least one of its tracks) SHOULD advertise 0 instead of the accumulated value: its ingress is already paid for, so one more subscriber costs only the links below it. -This is what lets a cluster deduplicate onto a warm copy. -The discount applies only to the advertisement for the path it actually serves from; a standby path keeps its accumulated value, since serving from it means opening a fresh ingest. +A relay actively carrying the namespace (a live subscription exists for at least one of its tracks) SHOULD advertise 0 instead: its ingress is already paid for, so another subscriber costs only the links below it. +This is what lets a cluster converge on a warm copy. +The discount applies only to the path it actually serves from; a standby path keeps its accumulated value, since serving from it means opening a fresh ingest. When it stops carrying the namespace it SHOULD restore the accumulated value, optionally after a grace period so brief churn does not flap routing. -Two relays that independently begin carrying the same namespace would each see the other's 0 as cheaper than its own source, and both switching at once would leave the namespace with no source. +Two relays that each begin carrying the same namespace would each see the other's 0 as cheaper than its own source, and if both switched at once the namespace would have no source. Before re-parenting onto a 0-cost advertisement from another actively-carrying relay (one whose HOP_PATH has two or more entries), a relay SHOULD apply a deterministic tie-break, such as comparing a hash of the namespace and each Hop ID, so exactly one side moves. -Equal Hop IDs (including two relays that both declared 0) cannot be ordered, and neither side SHOULD move. -Cheaper advertisements from anything else carry no such hazard and SHOULD be adopted immediately. +Equal Hop IDs, including two relays that both declared 0, cannot be ordered, and neither side SHOULD move. +Cheaper advertisements from anything else carry no such hazard and SHOULD be adopted at once. ## Updating an Advertisement {#updating} -An endpoint updates an advertisement by re-sending it with new parameters **on the stream that already carries it**: the original PUBLISH_NAMESPACE request stream, or the SUBSCRIBE_NAMESPACE response stream the NAMESPACE arrived on. +An endpoint updates a PUBLISH_NAMESPACE with REQUEST_UPDATE ({{moqt}} Section 9.5) on its request stream, carrying the HOP_PATH or ROUTE_COST that changed. +An omitted parameter keeps its value, so a relay that starts carrying a namespace sends an explicit ROUTE_COST of 0. +The receiver answers REQUEST_OK, or REQUEST_ERROR and closes the stream, which withdraws the advertisement. + +NAMESPACE has no REQUEST_UPDATE, so an endpoint updates one by re-sending it with new parameters on the same SUBSCRIBE_NAMESPACE response stream. A receiver MUST NOT treat the repeat as a duplicate or a protocol violation. -In {{moqt}} an advertisement lives for the lifetime of its stream, so an update on a *new* stream would leave two streams claiming one namespace and let the superseded one retract its replacement. -An endpoint MUST NOT open a second stream for an advertisement identity it already maintains on this session. For patterns, identity includes the segment kinds as specified by {{I-D.lcurley-moq-pattern}}; identical tuple bytes with different kinds are distinct advertisements. +An advertisement lives as long as its stream, so an update on a new stream would leave two streams claiming one namespace. +An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session. +A pattern advertisement's identity includes its segment kinds ({{I-D.lcurley-moq-pattern}}), so identical bytes with different kinds are distinct advertisements. -An update is metadata only: it re-prices or re-routes the advertisement and carries no content claim, so a receiver MUST NOT tear down subscriptions or drop cached state merely because one arrived. +An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. +If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. +If the publisher did change, the endpoint MUST withdraw the advertisement (PUBLISH_NAMESPACE_DONE or NAMESPACE_DONE) and advertise again rather than update in place. -The expected case is a ROUTE_COST-only change, which is how a relay signals that it started or stopped carrying the namespace. +The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. # Path Selection {#selection} -A receiver resolving a request against the advertisements covering its namespace, prefixes and patterns alike, consults only the most specific. -For prefix advertisements, prefer the longest covering prefix. When patterns are enabled, specificity and refusal follow {{I-D.lcurley-moq-pattern}}. -Pattern support does not follow from negotiating Relay Hops; advertisements to a session without the pattern capability MUST remain prefixes. +A receiver resolving a request consults only the most specific advertisements covering it: the longest prefix, or, when patterns are enabled, the specificity {{I-D.lcurley-moq-pattern}} defines. +Pattern support does not follow from this extension; advertisements to a session without it MUST remain prefixes. -Within the tier, a receiver SHOULD prefer the lowest ROUTE_COST, breaking ties toward the shorter HOP_PATH and then toward the most recently received. -Pattern advertisements tied at the lowest cost are a pool: a deterministic hash of the requested namespace against each advertiser distributes distinct namespaces across them. -The hash is FNV-1a from the basis `0x420C0DECB00B`: encode each requested namespace field as its byte length in eight little-endian bytes followed by its bytes, then append the advertiser's first Hop ID in eight little-endian bytes. For each encoded byte, XOR the byte in and multiply by `0x100000001B3`, wrapping at 64 bits; the highest result wins. -A first Hop ID of 0 makes the advertisement a pool member keyed by its incoming session: the receiver assigns each such session a distinct local 64-bit key, stable for that session's lifetime, and appends its eight little-endian bytes after the zero Hop ID when hashing. This key is local selection state, not an origin identity, and MUST NOT be forwarded as a Hop ID. -This is advisory: a receiver MAY apply local policy such as measured RTT instead. +Within that tier, a receiver SHOULD prefer the lowest ROUTE_COST, breaking ties toward the shorter HOP_PATH and then toward the most recently received. +This is advisory: a receiver MAY apply local policy, such as measured RTT, instead. -NO_CAPACITY and its single re-resolution are defined by {{I-D.lcurley-moq-pattern}}. Excluding the refusing advertiser excludes every route with its non-zero first Hop ID, or its incoming session when that ID is 0. +Pattern advertisements tied at the lowest cost form a pool, and a deterministic hash spreads distinct namespaces across them. +The hash is FNV-1a from the basis 0x420C0DECB00B over each requested namespace field, encoded as its byte length in eight little-endian bytes then its bytes, followed by the advertiser's first Hop ID in eight little-endian bytes: for each byte, XOR it in and multiply by 0x100000001B3 wrapping at 64 bits. +The highest result wins. +An advertisement whose first Hop ID is 0 is keyed by the session it arrived on instead: the receiver gives each such session a distinct 64-bit key, stable for its lifetime, and appends its eight little-endian bytes after the zero. +That key is local selection state, not an identity, and MUST NOT be forwarded as a Hop ID. -An advertisement carries no content identity: nothing promises that two paths to one namespace serve interchangeable bytes. -A receiver MUST NOT splice an active subscription across sessions; when the serving session's advertisement goes away, subscriptions through it end, and the receiver re-subscribes through the best remaining path. +NO_CAPACITY and its single re-resolution are defined by {{I-D.lcurley-moq-pattern}}. +Excluding the refusing advertiser excludes every route with its non-zero first Hop ID, or its session when that ID is 0. -A publisher MUST NOT advertise a path whose HOP_PATH contains the Hop ID that peer declared. -The receiver can only discard it, and acting on it would form a loop, so sending one is never useful. -Of the paths that remain a publisher SHOULD advertise the best, and advertises nothing when every known path contains that Hop ID. -Because selection is per session, a peer that the serving path flows through still receives the best standby, which is what lets it fail over if its own copy dies. +Two advertisements whose HOP_PATH begins with the same non-zero Hop ID come from the same publisher and carry interchangeable content: a receiver MAY hold them as redundant paths and fail an active subscription over to the survivor at a group boundary. +If the first entries differ, or either is 0, they are distinct publishers reusing a namespace ({{publishers}}). -When serving a subscription, a publisher MUST select the source by that same rule. +An endpoint MUST NOT advertise a path whose HOP_PATH contains the Hop ID the peer declared: the peer could only discard it, and acting on it would form a loop. +Of the paths that remain it SHOULD advertise the best, and advertises nothing when every path contains that Hop ID. +Because selection is per session, a peer that the serving path runs through still receives the best standby, which is what lets it fail over if its own copy dies. + +An endpoint MUST select the source for a subscription by the same rule. If only excluded sources remain the subscription is unroutable, since serving it would hand the subscriber data that already flowed through itself. -Applying one rule to both advertisement and dispatch keeps advertised paths truthful and prevents subscription cycles of any length. +One rule for advertisement and dispatch keeps advertised paths truthful and prevents subscription cycles of any length. + + +# Several Publishers of One Namespace {#publishers} +{{moqt}} lets several publishers advertise one namespace and leaves to the relay how it serves a SUBSCRIBE among them. +Under this extension an advertisement is a path, so a session advertises a namespace at most once, a relay forwards only the best path it knows ({{selection}}), and a subscription is served from one source at a time. + +A receiver MAY still hold paths to several publishers of one namespace and choose between them as it sees fit: serve from the cheapest and move to the next when it fails or refuses the request, or try each in cost order until one accepts. +The advertised path and the served source stay the same publisher: a relay that moves to another MUST withdraw its advertisement and advertise the new path ({{updating}}), so the first Hop ID downstream always names the publisher whose Objects flow. +Moving between distinct publishers is a discontinuity: their groups are not one sequence, so a subscriber sees an unrelated Location, and a FETCH that succeeds against one may fail against the other. + +Redundant publishers of the same content avoid this by sharing a Hop ID ({{hop-ids}}), which makes their paths interchangeable and lets a subscription fail over at a group boundary. +Publishers that do not share one are treated as reusing a name. -# Security Considerations -A Hop ID reveals nothing beyond what its operator encodes in it, and a deployment that considers its identifiers sensitive can use random values or declare 0 ({{zero}}). -Declaring 0 hides an identity from the mesh but not from the peer itself, which MAY assign one and forward it onward ({{assigned}}); an endpoint that needs to stay unlinkable past its first hop cannot get that from this extension. -A HOP_PATH does expose how many hops an advertisement crossed, which hints at the size of a deployment; a relay MAY coalesce its internal hops into one entry, or strip HOP_PATH, before forwarding across a trust boundary. +# Security Considerations {#security} +A Hop ID reveals nothing beyond what its operator encodes in it; a deployment that considers its identifiers sensitive can use random values or declare 0 ({{zero}}). +Declaring 0 hides an identity from the mesh but not from the peer, which MAY assign one and forward it onward ({{assigned}}); an endpoint that must stay unlinkable past its first hop cannot get that from this extension. +A HOP_PATH does reveal how many hops an advertisement crossed, which hints at the size of a deployment; a relay MAY collapse its internal hops into one entry, or strip HOP_PATH, before forwarding across a trust boundary. Because a relay only appends to HOP_PATH, it cannot make a competing path look shorter than it is; the worst it can do is under-report its own upstream portion to win an advisory tie-break. -ROUTE_COST has no such structural protection: it is a single value the sender chooses, so a relay can advertise 0 for content it is not carrying and attract subscriptions it then has to fetch. +ROUTE_COST has no such protection: it is a single value the sender chooses, so a relay can advertise 0 for content it is not carrying and attract subscriptions it then has to fetch. Both cost only a suboptimal path choice, and the latter is self-limiting, since the traffic won this way must then be served. A receiver MUST NOT make security decisions based on Hop IDs, and a deployment spanning a trust boundary SHOULD treat a peer's ROUTE_COST as a hint to clamp or ignore rather than an accounting figure. -# IANA Considerations {#iana} +# IANA Considerations This document requests the following registrations. High, distinctive values are requested to avoid the low ranges reserved by {{moqt}} and to minimize collisions with provisional registrations by other extensions. @@ -278,25 +304,29 @@ This document requests two registrations in the "MOQT Setup Options" registry ({ | Value | Name | Reference | |:--------|:-----------|:--------------| -| 0x40B55 | RELAY_HOPS | This Document | +| 0x40B54 | HOP_ID | This Document | | 0x40B56 | RELAY_COST | This Document | ## MOQT Message Parameters This document requests two registrations in the "MOQT Message Parameters" registry ({{moqt}} Section 15.7). -All are carried in PUBLISH_NAMESPACE and in the extended NAMESPACE message ({{namespace}}). +Both are carried in PUBLISH_NAMESPACE, in REQUEST_UPDATE of a PUBLISH_NAMESPACE ({{updating}}), and in the extended NAMESPACE message ({{namespace}}). -| Value | Name | Carried In | Reference | -|:--------|:------------------|:-----------------------------|:--------------| -| 0x40B57 | HOP_PATH | PUBLISH_NAMESPACE, NAMESPACE | This Document | -| 0x40B58 | ROUTE_COST | PUBLISH_NAMESPACE, NAMESPACE | This Document | +| Value | Name | Carried In | Reference | +|:--------|:------------|:---------------------------------------------|:--------------| +| 0x40B57 | HOP_PATH | PUBLISH_NAMESPACE, REQUEST_UPDATE, NAMESPACE | This Document | +| 0x40B58 | ROUTE_COST | PUBLISH_NAMESPACE, REQUEST_UPDATE, NAMESPACE | This Document | -The Key-Value-Pair parity is load-bearing: HOP_PATH and RELAY_HOPS are odd, so their values are length-prefixed byte strings, while ROUTE_COST and RELAY_COST are even, so their values are bare varints. +The Key-Value-Pair parity is load-bearing: HOP_PATH is odd, so its value is a length-prefixed byte string, while HOP_ID, RELAY_COST, and ROUTE_COST are even, so their values are bare varints. --- back -# Acknowledgments -{:numbered="false"} +# Appendix A: Changelog -This document was drafted with the assistance of Claude, an AI assistant by Anthropic. +## moq-cluster-01 +- Renamed the RELAY_HOPS Setup Option to HOP_ID and moved it to the even key 0x40B54, so its value is a bare varint rather than a length-prefixed one. +- A PUBLISH_NAMESPACE is updated with REQUEST_UPDATE on its request stream instead of a repeated PUBLISH_NAMESPACE; HOP_PATH and ROUTE_COST are registered for REQUEST_UPDATE. A NAMESPACE is still re-sent on its stream. +- A session advertises a namespace at most once and a subscription is served from one source at a time. A receiver chooses among several publishers of one namespace; moving between them is a discontinuity unless they share a Hop ID. +- Named the routing protocols whose single per-direction metric RELAY_COST follows. +- Pattern advertisements ({{I-D.lcurley-moq-pattern}}) share the NAMESPACE parameter block. Path selection consults the most specific advertisement first and spreads pattern advertisers tied on cost with a namespace hash. Standby seeds are bounded by deployment limits. diff --git a/js/watch/src/ui/components/hidden-indicator.ts b/js/watch/src/ui/components/hidden-indicator.ts new file mode 100644 index 00000000000..1cc2a475ce7 --- /dev/null +++ b/js/watch/src/ui/components/hidden-indicator.ts @@ -0,0 +1,39 @@ +import { type Effect, Signal } from "@moq/signals"; +import type MoqWatch from "../../element"; + +/** Explains why video isn't downloading when the `visible` gate holds it back. */ +export function hiddenIndicator(parent: Effect, watch: MoqWatch): HTMLElement { + const container = document.createElement("div"); + container.className = "watch-ui__notice watch-ui__hidden-indicator"; + container.setAttribute("role", "status"); + container.setAttribute("aria-live", "polite"); + + const text = document.createElement("span"); + text.className = "watch-ui__notice-text"; + container.appendChild(text); + + // The renderer folds tab visibility into one boolean, so track it separately to name the cause. + const hidden = new Signal(document.hidden); + parent.event(document, "visibilitychange", () => hidden.set(document.hidden)); + + parent.run((effect) => { + const gated = !effect.get(watch.renderer.out.visible); + const playing = !effect.get(watch.controls.paused); + const video = effect.get(watch.video.source.out.catalog) !== undefined; + const online = effect.get(watch.broadcast.out.status) !== "offline"; + const supported = effect.get(watch.video.source.out.error) !== "unsupported"; + // `never` is a deliberate choice, not a surprise worth explaining. + const chosen = effect.get(watch.controls.visible) === "never"; + const show = gated && playing && video && online && supported && !chosen; + container.style.display = show ? "" : "none"; + if (!show) return; + + if (effect.get(hidden)) { + text.textContent = 'Video paused while the tab is hidden. Set visible="always" to keep downloading.'; + } else { + text.textContent = 'Video paused while off-screen. Set visible="always" to keep downloading.'; + } + }); + + return container; +} diff --git a/js/watch/src/ui/components/unsupported-indicator.ts b/js/watch/src/ui/components/unsupported-indicator.ts index 755acc95741..f90442678db 100644 --- a/js/watch/src/ui/components/unsupported-indicator.ts +++ b/js/watch/src/ui/components/unsupported-indicator.ts @@ -4,12 +4,12 @@ import type MoqWatch from "../../element"; /** Shows why video cannot start when every catalog rendition is unsupported. */ export function unsupportedIndicator(parent: Effect, watch: MoqWatch): HTMLElement { const container = document.createElement("div"); - container.className = "watch-ui__unsupported-indicator"; + container.className = "watch-ui__notice watch-ui__unsupported-indicator"; container.setAttribute("role", "status"); container.setAttribute("aria-live", "polite"); const text = document.createElement("span"); - text.className = "watch-ui__unsupported-text"; + text.className = "watch-ui__notice-text"; container.appendChild(text); parent.run((effect) => { diff --git a/js/watch/src/ui/element.ts b/js/watch/src/ui/element.ts index 4be21c35cf9..ade4148bbe3 100644 --- a/js/watch/src/ui/element.ts +++ b/js/watch/src/ui/element.ts @@ -11,6 +11,7 @@ import type MoqWatch from "../element"; import { bufferingIndicator } from "./components/buffering-indicator"; import { centerPlay } from "./components/center-play"; import { controlBar } from "./components/control-bar"; +import { hiddenIndicator } from "./components/hidden-indicator"; import { offlineIndicator } from "./components/offline-indicator"; import { settingsPanel } from "./components/settings-panel"; import { unsupportedIndicator } from "./components/unsupported-indicator"; @@ -86,13 +87,14 @@ export default class MoqWatchUi extends HTMLElement { // The slotted (canvas/video) sits at the base of the stack. player.appendChild(DOM.create("slot")); - // Center affordances: play prompt + buffering spinner + offline / unsupported-codec notice. + // Center affordances: play prompt + buffering spinner + offline / unsupported-codec / hidden notices. const center = DOM.create("div", { className: "center" }); center.append( centerPlay(effect, watch), bufferingIndicator(effect, watch), offlineIndicator(effect, watch), unsupportedIndicator(effect, watch), + hiddenIndicator(effect, watch), ); // Top scrim keeps the bottom bar legible and hosts ambient gradient. diff --git a/js/watch/src/ui/styles/index.css b/js/watch/src/ui/styles/index.css index c40dd84c5d9..402a9e75a5a 100644 --- a/js/watch/src/ui/styles/index.css +++ b/js/watch/src/ui/styles/index.css @@ -5,4 +5,4 @@ @import "./buffer-control.css"; @import "./buffering-indicator.css"; @import "./offline-indicator.css"; -@import "./unsupported-indicator.css"; +@import "./notice.css"; diff --git a/js/watch/src/ui/styles/unsupported-indicator.css b/js/watch/src/ui/styles/notice.css similarity index 77% rename from js/watch/src/ui/styles/unsupported-indicator.css rename to js/watch/src/ui/styles/notice.css index 7e98bb3d807..4e7887871b2 100644 --- a/js/watch/src/ui/styles/unsupported-indicator.css +++ b/js/watch/src/ui/styles/notice.css @@ -1,4 +1,5 @@ -.watch-ui__unsupported-indicator { +/* A centered text notice explaining why video isn't playing. */ +.watch-ui__notice { position: absolute; top: 50%; left: 50%; @@ -15,7 +16,7 @@ pointer-events: auto; } -.watch-ui__unsupported-text { +.watch-ui__notice-text { font-size: 0.875rem; font-weight: 600; line-height: 1.4; @@ -23,12 +24,12 @@ } @media (max-width: 480px) { - .watch-ui__unsupported-indicator { + .watch-ui__notice { max-width: 90%; padding: 0.625rem 0.875rem; } - .watch-ui__unsupported-text { + .watch-ui__notice-text { font-size: 0.75rem; } } diff --git a/quest/m1/README.md b/quest/m1/README.md index 15eaefe1dad..861569b35dc 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -44,6 +44,8 @@ does not require it. - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - a marker group of one empty frame declares a break and moves the live edge; producers refuse a rewind; consumers jump the playhead on an unproven hole and drop rewind detection - [Joining FETCH](/quest/m1/joining-fetch.md) - moq-net: every subscribe to a draft-14 to draft-19 relay joins at a group boundary, with contiguous history for an explicit start, via Largest Object plus a joining FETCH - [Anonymous rank](/quest/m1/anonymous-route-rank.md) - moq-net: a route through an anonymous hop ranks below every identified route at any cost, and hop 0 travels the chain to say so +- [Cluster -01](/quest/m1/cluster-01/README.md) - rs/moq-net and js/net speak the revised cluster extension (HOP_ID, REQUEST_UPDATE repricing) and -01 is published +- [Track demand](/quest/m1/libmoq-track-demand.md) - a C publisher sees used/unused per track and serves dynamic track and group requests, so an encoder runs only while someone watches - [Native Go context](/quest/m1/go-native-context.md) - the Go generator emits context.Context itself, retiring the hand-rolled cancellation token - [Merge dev](/quest/m1/merge-dev.md) - dev lands on main with a closing keyword for every issue it fixed - [Release](/quest/m1/release.md) - the release moq.pro adopts: binding parity, an upgrade page, and a staging soak gate it rather than the merge diff --git a/quest/m1/cluster-01/README.md b/quest/m1/cluster-01/README.md new file mode 100644 index 00000000000..ae8f78d2926 --- /dev/null +++ b/quest/m1/cluster-01/README.md @@ -0,0 +1,38 @@ +# Cluster extension -01 + +## Goal + +`rs/moq-net` and `js/net` speak draft-lcurley-moq-cluster-01 as +`drafts/draft-lcurley-moq-cluster.md` now reads: the HOP_ID Setup Option +replaces RELAY_HOPS on an even key, and a PUBLISH_NAMESPACE reprices with +REQUEST_UPDATE instead of a repeated PUBLISH_NAMESPACE. Once both land the +revision is published to the datatracker, answering afrind's review of -00 +([#3693](https://github.com/moq-dev/moq/issues/3693), +[#3695](https://github.com/moq-dev/moq/issues/3695), +[#3697](https://github.com/moq-dev/moq/issues/3697), +[#3698](https://github.com/moq-dev/moq/issues/3698)). + +## Plan + +The draft moved first, on main. The text-only halves of that review, one +publisher per namespace and the single per-direction cost metric, needed no +code and are already answered there. What remains is the two wire changes. + +Nothing deployed speaks -00: cluster sessions run moq-lite-06 (see +[PoP skipping](/quest/m2/pop-skipping/README.md)), and a -00 peer meeting a +-01 peer sees an unknown Setup Option on each side, so neither negotiates and +the session runs as plain moq-transport. + +The draft on dev carries pattern-extension and selection changes main does +not. The merge keeps dev's text and this revision's wire changes together; +neither quest touches the draft again except the changelog. + +## Quests + +- [HOP_ID option](/quest/m1/cluster-01/hop-id.md) - both implementations negotiate with HOP_ID at 0x40B54, a bare varint +- [Cost update](/quest/m1/cluster-01/cost-update.md) - a PUBLISH_NAMESPACE reprices with REQUEST_UPDATE, and -01 is published + +## Related + +- [Anonymous rank](/quest/m1/anonymous-route-rank.md) - edits the same draft's identity sections +- [Warm advertise](/quest/m2/pop-skipping/warm-advertise.md) - the repricing this update path carries diff --git a/quest/m1/cluster-01/cost-update.md b/quest/m1/cluster-01/cost-update.md new file mode 100644 index 00000000000..abf447add5d --- /dev/null +++ b/quest/m1/cluster-01/cost-update.md @@ -0,0 +1,56 @@ +# [M] Cost update + +## Goal + +A relay that starts or stops carrying a namespace it advertised with +PUBLISH_NAMESPACE reprices it with REQUEST_UPDATE on that request stream, +carrying ROUTE_COST and, when the route changed, HOP_PATH. The receiver +answers REQUEST_OK, or REQUEST_ERROR and closes the stream, which withdraws +the advertisement. A repeated PUBLISH_NAMESPACE on a live stream is the base +draft's duplicate again. A NAMESPACE on a SUBSCRIBE_NAMESPACE stream is still +re-sent to update it. With both wire changes in, +draft-lcurley-moq-cluster-01 is on the datatracker. + +## Plan + +Today `sync_namespace` in `rs/moq-net/src/ietf/publisher.rs` re-sends +PUBLISH_NAMESPACE on the stream that carries it, and +`run_publish_namespace_updates` in `rs/moq-net/src/ietf/subscriber.rs` +decodes the repeat as an update. + +- Sender: a repricing writes REQUEST_UPDATE (type 0x2, Request ID plus + parameters) with the changed parameters. REQUEST_UPDATE keeps an omitted + parameter, so a change to 0 sends ROUTE_COST as an explicit 0, unlike the + initial advertisement where absent means 0. Reuse the REQUEST_UPDATE codec + the subscribe path has in `rs/moq-net/src/ietf/subscribe.rs`, extended to + carry HOP_PATH and ROUTE_COST. MAX_REQUEST_UPDATES bounds the outstanding + updates per stream, so wait for REQUEST_OK before the next one or coalesce + to the latest value. +- Receiver: `run_publish_namespace_updates` accepts REQUEST_UPDATE, merges + the parameters onto the held advertisement, and replies REQUEST_OK. A + repeated PUBLISH_NAMESPACE on the stream is a duplicate. An update it + cannot apply gets REQUEST_ERROR and a closed stream, per moq-transport + Section 9.5.1, which withdraws the advertisement. +- Draft-17 through draft-21 all allow REQUEST_UPDATE on PUBLISH_NAMESPACE, + which is every version the extension negotiates on, so no per-version + branch. +- js/net is a leaf that seeds cost 0 and never reprices, so it needs no + sender. Where it reads a repeated PUBLISH_NAMESPACE as an update today, it + reads REQUEST_UPDATE instead and treats the repeat as the duplicate. +- Branch from dev: the announce loops in `publisher.rs` and `subscriber.rs` + were rewritten there and m1 is the dev line. Main keeps the repeat until + the merge. +- Tests: a repricing round trip over REQUEST_UPDATE, including an explicit + 0; a repeated PUBLISH_NAMESPACE on its own stream is refused; a failed + update withdraws the advertisement; a NAMESPACE re-send still updates. +- Publish: `just drafts publish draft-lcurley-moq-cluster 01 `, then + the maintainer clicks the confirmation link. Reply on the four issues with + the -01 link. + +## Required + +- [HOP_ID option](/quest/m1/cluster-01/hop-id.md) - -01 publishes with both wire changes in + +## Closes + +- [#3698](https://github.com/moq-dev/moq/issues/3698) - close this issue when the quest finishes diff --git a/quest/m1/cluster-01/hop-id.md b/quest/m1/cluster-01/hop-id.md new file mode 100644 index 00000000000..c090597c53a --- /dev/null +++ b/quest/m1/cluster-01/hop-id.md @@ -0,0 +1,29 @@ +# [S] HOP_ID option + +## Goal + +A session negotiates the cluster extension with the HOP_ID Setup Option: key +0x40B54, even, so its value is the sender's Hop ID as a bare varint. Neither +implementation recognizes RELAY_HOPS (0x40B55) any more. rs/moq-net and +js/net agree byte for byte, and a peer that sends only the old option is not +negotiated with rather than misread. + +## Plan + +- `rs/moq-net/src/ietf/cluster.rs`: `RELAY_HOPS` becomes `HOP_ID = 0x40B54`. + `peer_from_setup` reads it with `get_varint` and `peer_into_setup` writes it + with `set_varint`, deleting the byte-string round trip and its + `TrailingBytes` check. `rs/moq-net/src/ietf/parameters.rs` moves the key + from `ParameterBytes::RelayHops` to `ParameterVarInt::HopId`. The parity + test asserts even. +- `js/net/src/ietf/parameters.ts` and `cluster.ts`: `SetupOption.RelayHops` + becomes `HopId = 0x40b54n`, decoded as a varint; the byte fixtures in + `cluster.test.ts` follow. +- Module docs in both name HOP_ID as the option. No comment records the old + name. +- Branch from main: the constants and setup codecs are identical on dev, so + the merge carries it. A wire change, so run `just test smoke-full`. + +## Closes + +- [#3693](https://github.com/moq-dev/moq/issues/3693) - close this issue when the quest finishes diff --git a/quest/m1/libmoq-track-demand.md b/quest/m1/libmoq-track-demand.md new file mode 100644 index 00000000000..70a90074f93 --- /dev/null +++ b/quest/m1/libmoq-track-demand.md @@ -0,0 +1,99 @@ +# [L] libmoq: track demand and dynamic track requests + +## Goal + +A C publisher learns when a published track gains its first subscriber and +when it loses its last, and can serve track requests it did not declare up +front, so an encoder on a battery-powered device runs only while someone is +watching. The C ABI mirrors what moq-ffi already has: `used`/`unused` on +`MoqTrackProducer` and single-track `MoqMediaProducer`, and +`MoqBroadcastDynamic::requested_track` with `MoqTrackRequest::accept`/`abort`, +`publish_media_on_track` for accepting a request as media, and the group +request path (`MoqTrackDynamic::requested_group`, `MoqGroupRequest`) that +keeps a FETCH-driven request serviceable across acceptance. + +Non-goals: no wire or public Rust API change; the OBS plugin does not adopt +the signal (OBS owns its encoders and cannot pause them from an output); +a multi-track container handle has no single demand and errors, as in moq-ffi; +broadcast-level request serving stays with the announce handle quests. + +## Plan + +Branch from dev, where libmoq already serves broadcast requests through +`moq_origin_dynamic` and `moq_broadcast_request_*`; follow that callback +convention exactly (a positive handle per event, then exactly one terminal +`<= 0` call, after which `user_data` is never touched). + +Demand, one level-triggered watcher per handle: + +- `moq_publish_track_demand(track, on_demand, user_data)`, + `moq_publish_media_demand(media, on_demand, user_data)`, and the same on + the built-in encoder handles, `moq_publish_video_raw_demand` and + `moq_publish_audio_raw_demand` (moq-ffi's `MoqVideoProducer` and + `MoqAudioProducer` carry `used`/`unused` too), return a watcher handle; + `moq_publish_demand_close(watcher)` stops it. +- `on_demand(user_data, int32_t status)` fires immediately with the current + state, again on every observed change, then once with a terminal `<= 0`. Positive + values come from a `moq_demand` enum (`MOQ_DEMAND_USED`, + `MOQ_DEMAND_UNUSED`). Seeding with the current state is what closes the + race the issue calls out: a track that went unused before registration + still reports it. +- Neither `Producer` nor `Demand` exposes the current state, only the + level-triggered waits `used()` and `unused()`, and exactly one of them is + ready at any instant. The watcher task races the two to learn the initial + state, reports it, then loops waiting on the opposite wait. A flip between + reporting and arming resolves the next wait immediately, so no edge is + lost; a double flip collapses into no report, which is correct for a level + signal. Do not add an `is_used` getter to moq-net for this. +- The media watcher refuses a container handle with the same error moq-ffi + uses. + +Requests, mirroring the broadcast path one level down: + +- `moq_publish_dynamic(broadcast, on_request, user_data)` registers the + handler and returns a handle; `moq_publish_dynamic_close` drops it. Without + a live handler an unknown track name is refused, as today. +- `moq_track_request_name(request, dst)`, `moq_track_request_accept(request, + info)` returning a `moq_publish_track` handle (the demand watcher attaches + to it like any other), `moq_track_request_abort(request, error_code)`, and + `moq_track_request_free(request)`. `info` is the existing `moq_track_info`, + NULL for the microsecond default. +- `moq_track_request_video(request, init)` and + `moq_track_request_audio(request, init)` mirror `publish_media_on_track`, + split by kind the way `moq_publish_video`/`_audio` are: the importer + accepts the request, sets the timescale, and returns the same media handle + those return, so the demand watcher and frame writes work unchanged. + Single-track formats only, as in moq-ffi. + +Group requests, so a track requested by FETCH is served rather than resolving +`NotFound` once accepted: + +- `moq_track_request_dynamic(request, on_group, user_data)` mirrors + `MoqTrackRequest::dynamic`: obtain it before accepting when the track was + requested by a fetch, so the pending group request survives the transition. + `moq_publish_track_dynamic(track, on_group, user_data)` is the same handler + on an already-published track (`MoqTrackProducer::dynamic`). Both return a + handle closed by `moq_publish_dynamic_close`, and `on_group` follows the + request callback convention. +- `moq_group_request_sequence`, `moq_group_request_priority`, + `moq_group_request_accept(request)` returning a `moq_publish_group` handle, + `moq_group_request_abort(request, error_code)`, and + `moq_group_request_free`. Cached groups never reach the handler. + +Landing: regenerate `moq.h` (build.rs does not regenerate it on src-only +changes), document every new symbol in `doc/lib/c`, and add tests in +`rs/libmoq/src/test.rs`: a consumer subscribing then closing drives +used -> unused; a watcher registered after the last consumer left is told +unused first; one dynamic request is accepted and the returned track +carries frames, a second is aborted and its subscriber sees the code. +Remove the dynamic-track bullet from #2152 when this lands. + +## Closes + +- [#3678](https://github.com/moq-dev/moq/issues/3678) - close this issue when the quest finishes + +## Related + +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - the wider C ABI catch-up this splits out of +- [#3190](https://github.com/moq-dev/moq/issues/3190) - broadcast-level request serving on the C ABI, shipped on dev in #3577 +- [#3000](https://github.com/moq-dev/moq/issues/3000) - an unused edge is not terminal; the watcher must keep reporting after it (fixed on dev in #3455) diff --git a/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md b/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md index 8e7ce9784cc..7e836caeff6 100644 --- a/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md +++ b/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md @@ -1,11 +1,10 @@ -# [M] libmoq: dynamic track serving and server-side accept +# [S] libmoq: server-side accept ## Goal -A C embedder serves tracks on demand inside a broadcast it publishes, and -accepts sessions itself through the same two-phase SETUP the FFI exposes. -These are the two `moq-ffi` capabilities `rs/libmoq` still lacks that ride -the request records the origin dynamic handle already exposes. +A C embedder accepts sessions itself through the same two-phase SETUP the +FFI exposes. Dynamic track serving, the other `moq-ffi` capability +`rs/libmoq` still lacks, moved to the track demand quest linked below. ## Plan @@ -13,26 +12,19 @@ Most of the catch-up #2152 lists has landed in dev's `rs/libmoq/src/api.rs`: subscription options, track info, abort codes, client TLS roots, datagrams (`moq_datagram` :462-468, `moq_publish_track_datagram` :1948, and `moq_consume_datagrams` with its read, free, and close :2599-2650), and raw -frame timestamps (:2538-2541). Two gaps remain: - -- Dynamic track serving. moq-ffi's `MoqBroadcastProducer::requested_track` - yields a `MoqTrackRequest` whose `accept(info)` returns the producer - (rs/moq-ffi/src/producer.rs:483, :624); api.rs has no `requested` symbol. - Mirror it as a callback-delivered request handle with accept and reject, - on the datagram task's handle and terminal-status contract. Broadcast - requests are not in this quest: `requested_broadcast` reaches C through - the origin dynamic handle, so do not add a separate path here. -- Server-side accept. moq-ffi's `MoqServer::accept` yields a `MoqRequest` - whose own `accept()` completes SETUP (rs/moq-ffi/src/server.rs:54, :144, - :186, :259); a C embedder cannot accept sessions at all. - -Each addition regenerates `moq.h`, touches `cpp/obs/src` only if used, and -updates `doc/lib/c/index.md`. That page's capability list (:39) already -claims dynamic tracks for C; the request handle makes it true. - -Branch from main after the dev merge. These new request entry points and -group fetch are additive. The C output-configuration layout change is owned -by its separate M1 quest. +frame timestamps (:2538-2541). One gap remains: moq-ffi's +`MoqServer::accept` yields a `MoqRequest` whose own `accept()` completes +SETUP (rs/moq-ffi/src/server.rs:54, :144, :186, :259); a C embedder cannot +accept sessions at all. Mirror it on the datagram task's handle and +terminal-status contract. Broadcast requests are not in this quest: +`requested_broadcast` reaches C through the origin dynamic handle, so do +not add a separate path here. + +The addition regenerates `moq.h`, touches `cpp/obs/src` only if used, and +updates `doc/lib/c/index.md`. + +Branch from main after the dev merge. The new entry point is additive. The +C output-configuration layout change is owned by its separate M1 quest. ## Required @@ -44,4 +36,5 @@ by its separate M1 quest. ## Related +- [Track demand](/quest/m1/libmoq-track-demand.md) - track requests and used/unused on the C ABI - [libmoq fetch](/quest/m2/libmoq-fetch.md) - additive group fetch, on main diff --git a/quest/m2/README.md b/quest/m2/README.md index b4b013fb74b..1fb78ce6169 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -63,7 +63,7 @@ before format-specific metadata. Unrelated areas can proceed in parallel. - [JavaScript FETCH](/quest/m2/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers - [Archive](/quest/m2/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS, on the catalog and store the release ships - [Wildcard](/quest/m2/wildcard/README.md) - a relay resolves subscriptions against advertised patterns, a service advertises a path pattern it could serve instead of enumerating broadcasts, and the browser player treats a covering pattern as availability -- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq serves tracks on demand and accepts sessions, the two moq-ffi calls C still lacks +- [#2152](/quest/m2/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq accepts sessions, the moq-ffi call C still lacks - [js/publish discontinuity](/quest/m2/js-publish-discontinuity.md) - the JS container producer and js/publish emit the same marker group on encoder restart - [Failure artifacts](/quest/m2/qa-failure-artifacts.md) - a failing harness run keeps its run directory and a Playwright trace, and CI uploads them - [Listening kind field](/quest/m2/harness-drive-bys.md) - revert the relay's `kind` field on the listening log lines; nothing reads it diff --git a/quest/m3/README.md b/quest/m3/README.md index 04762a5599f..4f316d313bf 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -45,3 +45,4 @@ worth settling now. Deferral does not by itself abandon a feature. - [Carrier voice](/quest/m3/carrier-voice/README.md) - determine whether MoQ should be the call fabric for programmable carrier voice - [LiveKit WebRTC bridge](/quest/m3/livekit-webrtc-bridge.md) - a go/no-go verdict, backed by a spike, on per-track LiveKit-to-MoQ bridging - [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract +- [Common Access Tokens](/quest/m3/cat/README.md) - a moq-transport client presents a CAT in SETUP and `moq auth serve` admits it with the scope its `moqt` claim names diff --git a/quest/m3/cat/README.md b/quest/m3/cat/README.md new file mode 100644 index 00000000000..91197f34dc8 --- /dev/null +++ b/quest/m3/cat/README.md @@ -0,0 +1,66 @@ +# Common Access Tokens + +## Goal + +A moq-transport client presents a Common Access Token +([draft-ietf-moq-c4m](https://datatracker.ietf.org/doc/draft-ietf-moq-c4m/)) +in the SETUP `AUTHORIZATION TOKEN` option and the relay admits it with the +scope the token's `moqt` claim names, through the same +`moq-auth` request contract every other credential uses. Our own clients can present one; `moq auth serve` verifies one; the +relay stays crypto-free and forwards the bytes. This is moq-transport only: +a CAT scopes itself by moq-transport message (`SUBSCRIBE`, `FETCH`, +`PUBLISH_NAMESPACE`, ...), which moq-lite has no equivalent for, so it rides +the SETUP option and nothing else. Nothing changes on the moq-lite wire or in +the URL, and the JWT stays the URL credential. + +Boundaries decided while planning: + +- SETUP only. A token on SUBSCRIBE, PUBLISH, FETCH, or any other request is + refused; per-operation authorization is not planned. The relay authorizes + per session through origin scopes, and a token that arrives after SETUP is + the [in-band auth](/quest/m2/auth/README.md) line's problem. +- A token whose `moqt` scope restricts the track name is refused naming the + token. Grants are broadcast-path patterns and tracks are not scoped. +- Core CWT claims plus `moqt` and `moqt-reval` are enforced; any other CAT + claim present (`catu`, `catm`, `catnip`, `catreplay`, `catdpop`, `cnf`, + geo, composite `or`/`and`/`nor`) refuses the token naming the claim, so a + restriction we do not evaluate never widens silently. DPoP (c4m section 3) + is out of scope. +- Wire codes follow c4m-01: Token Type `0x01` is the value the draft + registers for CAT. The `moqt` and `moqt-reval` claim keys are still + `TBD_MOQT`, so they are hard-coded constants with a doc comment saying so. + We do not expect to interop on these until the draft registers them. +- Rust only. `@moq/auth` gains nothing; `js/net` only carries bytes it was + handed into SETUP. +- [draft-ietf-moq-privacy-pass-auth](https://datatracker.ietf.org/doc/draft-ietf-moq-privacy-pass-auth/) + was considered and dropped. A Privacy Pass token carries only the digest of + its `TokenChallenge`, the draft never says how a relay hands a client the + challenge whose `origin_info` scopes the token, VOPRF tokens need the + issuer's secret at the verifier, and nobody is asking. Do not re-plan it + until the draft has a challenge exchange and a registered token type. + +## Plan + +Order: the wire first so a token reaches the auth server; verification; +then our clients present one. Everything rides `moq_auth::Request` and +`moq auth serve`, which shipped on dev. The JWT types sit at the crate root; +the verify quest moves them under `moq_auth::jwt` so `cat` is a sibling +module rather than a set of prefixed names. + +## Quests + +- [Setup token](/quest/m3/cat/setup-token.md) - the SETUP `AUTHORIZATION + TOKEN` option is decoded on both IETF stacks, reaches `moq_auth::Request` + as `token`, and is refused on every other message +- [Verify](/quest/m3/cat/verify.md) - `moq_auth::cat` turns a CAT into a + grant and `moq auth serve` admits one; `moq auth sign|verify` mint and + check the format +- [Present](/quest/m3/cat/present.md) - a CAT is one kind of configured + token, riding the SETUP option the in-band token quest already writes + +## Related + +- [In-band auth](/quest/m2/auth/README.md) - credentials presented after + SETUP, which this line refuses on the IETF wire; its [Token in + band](/quest/m2/auth/token-in-band.md) quest owns the client token + configuration a CAT joins diff --git a/quest/m3/cat/present.md b/quest/m3/cat/present.md new file mode 100644 index 00000000000..f66617d8935 --- /dev/null +++ b/quest/m3/cat/present.md @@ -0,0 +1,42 @@ +# [S] A CAT is one kind of configured token + +## Goal + +`moq_tokio::connect::Config.tokens` and `js/net`'s connect `tokens` accept a +Common Access Token beside the JWTs they already hold, and a moq-transport +session carries it in the SETUP `AUTHORIZATION TOKEN` option with Token Type +`0x01`. The library does not read the bytes. A CAT never rides the URL or an +AUTH stream, so a client that configures one while offering a version without +the option fails loud instead of dropping the credential. + +## Plan + +- [Token in band](/quest/m2/auth/token-in-band.md) defines the client token + configuration and writes the first configured token into the setup option + as type 0. This quest makes the kind explicit: each configured token is a + `moq_net::setup::Token { kind, value }`, a JWT keeps kind `0x0` and its + URL and AUTH stream behavior, and a CAT is kind `0x01`. `--connect-token` + keeps taking a JWT; `--connect-cat ` (and `MOQ_CONNECT_CAT`) + adds a CAT. One CAT per connection: it is the connection credential, so a + configured CAT takes the setup option and the JWT that would have gone + there rides its AUTH stream instead. +- A CAT with any offered version that lacks the setup option (every lite + version) fails `init` with `Unsupported` naming the token; `js/net` + rejects the same way before dialing. +- `moq` CLI publish and subscribe get the flag through the shared connect + config; `doc/bin/cli.md` and `doc/lib/rs/moq-net.md` gain it. +- Tests: the server request sees kind `0x01` and the bytes on every draft + in Rust, JS, and across; a JWT still goes to the URL or AUTH stream when + a CAT holds the option; a lite offer with a CAT refuses at init; end to + end against `moq auth serve` with a CAT from `moq auth sign --format cat`. + +Public API: additive on `moq-tokio` and `js/net`. Wire: none. + +## Required + +- [Setup token](/quest/m3/cat/setup-token.md) - the server-side exposure + and the shared `setup::Token` +- [Verify](/quest/m3/cat/verify.md) - the server that admits the token the + end-to-end test presents +- [Token in band](/quest/m2/auth/token-in-band.md) - the token + configuration and setup-option writer this adds a kind to diff --git a/quest/m3/cat/setup-token.md b/quest/m3/cat/setup-token.md new file mode 100644 index 00000000000..82cf6d4a418 --- /dev/null +++ b/quest/m3/cat/setup-token.md @@ -0,0 +1,67 @@ +# [M] The SETUP AUTHORIZATION TOKEN option reaches the auth server + +## Goal + +A moq-transport peer's SETUP `AUTHORIZATION TOKEN` option (type `0x03`, +draft-14 through the newest supported draft) is decoded by `rs/moq-net` and +`js/net` into a token type and value, exposed on the accepted request, and +forwarded by the relay in `moq_auth::Request` as `token`, so an auth server +can verify it. The same parameter on any other message is refused. Today the +option is stored as opaque bytes and ignored, and the message parameter fails +decode as an unknown key. + +## Plan + +- `moq_net::setup::Token { kind: u64, value: Vec }`, `kind` being the + wire Token Type: `Token::OUT_OF_BAND` is `0x0` and `Token::CAT` is the + `0x01` c4m-01 registers. This is the type [Token in + band](/quest/m2/auth/token-in-band.md) writes for a configured JWT + (`USE_VALUE`, type 0), so the two quests share one struct and one encoder; + whichever lands first adds them. Decode the draft-21 section 8.9 + structure: Alias Type `USE_VALUE` yields the token; `REGISTER` is treated + as `USE_VALUE` because we advertise no `MAX_AUTH_TOKEN_CACHE_SIZE` (the + default of 0 makes that the draft's own rule), so no alias state exists; + `DELETE` or `USE_ALIAS` in SETUP closes with `PROTOCOL_VIOLATION`; an + undecodable structure closes with `KEY_VALUE_FORMATTING_ERROR`. More than + one token in SETUP is refused: one credential per connection is the shape + the contract has. +- Encode side: `Parameters` learns to write a `USE_VALUE` token so + [Present](/quest/m3/cat/present.md) has nothing to add on the wire. +- Message parameter `0x03` on SUBSCRIBE, REQUEST_UPDATE, PUBLISH, FETCH, + PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, TRACK_STATUS, and every other + message whose decoder reads parameters decodes and is refused with the + request's error path (`Unsupported`, mapped through `to_code` for the + draft) naming the parameter, so the session survives and the log says why. + Both decoder families change: the strict `decode_params!` path on newer + drafts, which rejects the key today, and the generic KVP path the legacy + drafts use, which keeps an odd key and lets the caller ignore it. +- `moq_net::Request::token() -> Option<&setup::Token>` on the accepted + request, carried through the `Legacy` (draft-14 to 16) and `PeerSetup` + (draft-17+) paths; `moq_tokio::server::Request` forwards it; lite sessions + return `None`. +- `moq_auth::Request.token: Option`, + serialized with `serde_with` base64 like the rest of the request. The relay + fills it where it builds the request, beside the URL query it already + forwards. `moq auth serve` treats kind `0x0` as the JWT the deployment + negotiated out of band, verified exactly like `?jwt=`, refuses a kind it + does not know naming the code, and hands `0x01` to + [Verify](/quest/m3/cat/verify.md). A request carrying both a SETUP token + and a `jwt` query is refused naming both. +- `js/net/src/ietf/parameters.ts` mirrors the decode and encode, and the + `SetupOption.AuthorizationToken` handling in `handshake.ts`; the JS accept + side exposes the token on its request the same way. +- Docs: `doc/concept` on the IETF binding gains the option and the refusal; + `doc/lib/rs/moq-auth.md` gains the request field. +- Tests: decode and encode round trips for every alias type on every draft + in Rust and JS; `DELETE`/`USE_ALIAS` in SETUP close the session; + `REGISTER` is accepted as a value; a token on SUBSCRIBE is refused and the + session continues, on one legacy draft and one strict draft; the relay forwards the bytes to a wiremock auth server + byte for byte; a lite session reports none. + +Public API: additive on `moq-net`, `moq-tokio`, `moq-auth`, and `js/net`. +Wire: none new; the option already exists in every supported draft. + +## Related + +- [Token in band](/quest/m2/auth/token-in-band.md) - writes the same option + from the client side with the shared `setup::Token` diff --git a/quest/m3/cat/verify.md b/quest/m3/cat/verify.md new file mode 100644 index 00000000000..980f6d28ede --- /dev/null +++ b/quest/m3/cat/verify.md @@ -0,0 +1,91 @@ +# [M] moq auth serve admits a Common Access Token + +## Goal + +`moq_auth::cat` verifies a CAT (CTA-5007-B, a CWT under COSE_Mac0 or +COSE_Sign1) and turns its `moqt` and `moqt-reval` claims into a `Grant`, and +`moq auth serve` admits a connection whose SETUP token is one, with keys the +operator hands it. `moq auth sign --format cat` mints one and `moq auth +verify --format cat` checks one, so tests and operators have a way to make +tokens. Every claim we do not evaluate refuses the token naming the claim. + +## Plan + +The JWT types (`Claims`, `Key`, `Jwk`, `KeyId`, `Algorithm`, the key set, +`authorize`) sit at the `moq_auth` root today. Move them under +`moq_auth::jwt` first, keeping their names, so `cat` is a sibling module +rather than a set of prefixed names; `@moq/auth` stays flat. + +- Crates: `coset` for COSE and CWT claims, `ciborium` for CBOR; HMAC through + the `aws-lc-rs` the crate already links, ES256 through `p256`. Keys reuse + `moq_auth::jwt::Key` files: a JWK with `alg` maps to the COSE algorithm + (`HS256` to HMAC 256/256, `ES256` to -7, `EdDSA` to -8, `RS256` to -257); + a JWK whose algorithm has no COSE mapping is refused at load naming it. +- `cat::Claims { issuer, audience, subject, expires, not_before, issued, + id, scopes: Vec, revalidate: Option }` where + `cat::Scope { actions: Vec, namespace: Option>, + exact_depth: bool, track: Option }` follows the c4m-01 CDDL: + `cat::Match` is `Exact(bytes)`, `Prefix(bytes)`, or `Suffix(bytes)`, one + per namespace field in order, the trailing `nil` becomes `exact_depth`, + and `nil` anywhere else refuses the token. `cat::Action` is the c4m-01 + table 1 enum (`ClientSetup`, `ServerSetup`, `PublishNamespace`, + `SubscribeNamespace`, `Subscribe`, `RequestUpdate`, `Publish`, `Fetch`, + `TrackStatus`). Claim keys `moqt` and `moqt-reval` are provisional + constants in the CWT private-use range with a doc comment; they change + when the draft registers them. +- `Claims::verify(token, keys)` checks the signature or MAC against the key + set by `kid`, then `exp`, `nbf`, and `iat` against now, then walks the + claim set: anything outside `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, + `cti`, `moqt`, and `moqt-reval` refuses the token naming the label. +- `Claims::grant(&self, root) -> Result`: for every scope, + `Publish` adds the namespace pattern to `publish` and `Subscribe` adds it + to `subscribe`. The grant has no narrower verbs, so `PublishNamespace` is + accepted only beside `Publish`, and `SubscribeNamespace`, `RequestUpdate`, + `Fetch`, and `TrackStatus` only beside `Subscribe`; a scope whose actions + are narrower than either verb refuses the token naming the scope rather + than widening a fetch-only token into a live subscription. `ClientSetup` + and `ServerSetup` add nothing. The namespace fields become one `moq_pattern::Pattern` segment + each, the mapping `rs/moq-pattern` documents under "CAT / C4M", relative + to the dialed path exactly as `jwt::Claims::root` is: `Exact(f)` is the + literal segment, `Prefix(f)` is `f*`, `Suffix(f)` is `*f`, a named + namespace without `exact_depth` appends `/**`, and an absent namespace is + bare `**` with nothing appended. A field value containing `/` or `*` + cannot be a segment and refuses the token naming the scope. `f*` and `*f` + are patterns the relay only admits once [Origin + scopes](/quest/m2/path-patterns/origin.md) lifts its prefix-shaped + adapter, which is why that quest is required here. A scope with a track match is refused naming the scope. + `exp` is `expires`, `moqt-reval` is + `revalidate`, and `Grant::validate` keeps refusing a cadence without an + expiry, so the serve default `--expires` applies to a token without `exp` + the way it does for a JWT. A token that grants nothing is refused. +- `moq auth serve`: `--cat-key ` and `--cat-key-dir ` beside + `--key`, `--cat-issuer ` and `--cat-audience ` required to + match `iss` and `aud` when set. Policy order: a SETUP `token` is decided + first and never falls through; then the existing `jwt` query, mTLS, + public. +- `moq auth sign --format cat` and `verify --format cat` in `rs/moq-cli`, + sharing `--publish`/`--subscribe` patterns with the JWT form and emitting + one `moqt` scope per pattern through the inverse of the mapping above (a + literal segment is `Exact`, `f*` is `Prefix`, `*f` is `Suffix`, a trailing + `**` drops `nil`, a pattern with `**` elsewhere or `a*b` is refused naming + it) with the actions each verb implies; `--revalidate ` sets + `moqt-reval`. Output is the raw CWT bytes, or base64url with `--base64`. +- Docs: `doc/lib/rs/moq-auth.md` gains the module, `doc/bin/cli.md` the + flags, `doc/bin/relay/auth.md` a CAT section with the provisional codes + and the refused-claims list. +- Tests: sign and verify under each mapped algorithm; each refused claim; + each match kind mapped or refused, `nil` placement, and the moq-pattern + vectors round-tripped both ways; expiry and not-before; the grant + produced from every c4m-01 example; serve admitting a CAT over a real + moq-transport session on every supported draft and refusing an unknown + token kind, a bad MAC, and a token plus `jwt`; the CLI round trip. + +Public API: `moq_auth::cat` new, `moq auth serve` and `moq auth sign|verify` +gain flags. Wire: none. + +## Required + +- [Origin scopes](/quest/m2/path-patterns/origin.md) - the relay admits + `f*` and `*f` grants only after it +- [Setup token](/quest/m3/cat/setup-token.md) - the token reaches the + server's request diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index 641bc05b799..632e6429999 100644 --- a/rs/moq-mux/Cargo.toml +++ b/rs/moq-mux/Cargo.toml @@ -16,7 +16,7 @@ categories = ["multimedia", "network-programming", "web-programming"] anyhow = { workspace = true } base64 = { workspace = true } bytes = { workspace = true } -h264-parser = { version = "0.4.0" } +h264-parser = { version = "0.4.2" } hang = { workspace = true } kio = { workspace = true } memchr = "2" diff --git a/skills/moq/SKILL.md b/skills/moq/SKILL.md index 91cab54cb51..d77a8e4b42f 100644 --- a/skills/moq/SKILL.md +++ b/skills/moq/SKILL.md @@ -1,64 +1,26 @@ --- name: moq -description: Build live video, audio, and real-time data apps with Media over QUIC (MoQ). Use when adding live streaming, conferencing, voice AI, or real-time pub/sub to an app; when integrating the @moq/* npm packages, moq-* Rust crates, or the Python/Kotlin/Swift/Go/C bindings; or when running a moq-relay server or a gateway (RTMP, SRT, WebRTC, HLS, OBS, GStreamer, ffmpeg). +description: Build live video, audio, and real-time data apps with Media over QUIC (MoQ). Use when adding live streaming, conferencing, voice AI, or real-time pub/sub to an app; when integrating the @moq/* npm packages, moq-* Rust crates, or the Python/Kotlin/Swift/Go/C/Dart bindings; or when running a moq-relay server or a gateway (RTMP, SRT, WebRTC, HLS, OBS, GStreamer, ffmpeg). --- # Media over QUIC (MoQ) -MoQ is a live media protocol delivering real-time (sub-second) latency at CDN scale. -It is generic pub/sub over QUIC: video and audio are the flagship use case, but any live data rides the same relays (chat, game input, JSON state, AI output). +MoQ is generic real-time pub/sub over QUIC: relays fan out named tracks of groups of frames without understanding the payload. +Video and audio are the flagship use case, but chat, game input, JSON state, and AI output ride the same relays. -This skill is an index of the moq-dev monorepo (https://github.com/moq-dev/moq): what you can build and which pieces to reach for. Fetch the linked docs for details instead of guessing APIs. +## Read the live docs -## Layering +The project moves quickly and your training data is stale: it describes the IETF `moq-transport` draft and crates that no longer exist. +Do not guess APIs, package names, or flags. Read https://doc.moq.dev as part of the task. -The stack from the wire up. Reach for the highest layer that fits and drop down only when you need control: +1. Fetch https://doc.moq.dev/llms.txt, an index of every page with a one-line description. +2. Fetch the pages you need as markdown: drop any trailing `/` and append `.md`, e.g. https://doc.moq.dev/lib/js/watch.md. +3. For an API, read that package's page before writing code. For a design question, start at https://doc.moq.dev/concept.md. -1. **QUIC**: does all the networking. Provided by the browser or a QUIC library (`moq-tokio` configures one for you in Rust). -2. **WebTransport**: a thin layer over QUIC/HTTP3 so browsers can speak it. Provided by the browser or the `web-transport` crates. -3. **moq-lite** (Rust `moq-net`, TypeScript `@moq/net`): generic real-time pub/sub. A *broadcast* contains named *tracks*; tracks carry *groups* of *frames*. Relays cache, deduplicate, and fan out without understanding the payload, so anything can be end-to-end encrypted. This is the layer CDNs implement. -4. **hang** (Rust `hang`, TypeScript `@moq/hang`): media on top. A catalog track describes codecs/renditions; containers carry timestamped codec bitstream. Think of hang as HLS/DASH and moq-lite as HTTP. -5. **Your application**: business logic, auth, custom tracks. Extend hang with your own tracks or replace it entirely. +## Durable facts -Everything below builds on these layers. - -## What you can build - -**Live streaming (Twitch-style)**. Ingest via the OBS plugin (`cpp/obs`), RTMP (`rs/moq-rtmp`), SRT (`rs/moq-srt`), GStreamer (`rs/moq-gst`), or pipe ffmpeg into the `moq` CLI (`rs/moq-cli`, a media router bridging fMP4/CMAF, MPEG-TS, FLV, HLS, RTMP, SRT, WebRTC). Distribute through `moq-relay` and watch in the browser with `` (`@moq/watch`). Serve legacy players via the HLS/LL-HLS gateway (`rs/moq-hls`) and build a rendition ladder with just-in-time transcoding (`rs/moq-transcode`). Docs: https://doc.moq.dev/bin/ - -**Conferencing (Zoom-style)**. Browser capture and playback with `@moq/publish` + `@moq/watch`; each participant is a broadcast, discovered via announcements. Bridge existing WebRTC clients with the WHIP/WHEP gateway (`rs/moq-rtc`). Why MoQ over WebRTC: https://doc.moq.dev/concept/use-case/conferencing - -**Voice/video AI agents**. Server-side media without a browser, straight from Rust: `moq-mux` publishes and decodes media containers (fMP4/CMAF, MPEG-TS, FLV), while `rs/moq-video` and `rs/moq-audio` capture/encode and decode/render with hardware codecs (VideoToolbox, D3D11, NVENC, VAAPI). Python bindings fit ML stacks, and the Pipecat voice-agent framework ships MoQ transport support (https://github.com/pipecat-ai/pipecat). TTS output written faster than real-time plays smoothly via `@moq/watch` buffered playback (`buffer`). Background: https://moq.dev/blog/webrtc-is-the-problem and https://doc.moq.dev/concept/use-case/ai - -**Real-time data, no media at all**. Chat, multiplayer game state, telemetry, collaborative apps: publish raw tracks with `@moq/net` or `moq-net`. Helpers: `moq-json` / `@moq/json` (JSON snapshots, merge-patch deltas, append logs) and `moq-flate` / `@moq/flate` (compression). A synchronized-clock example lives in `js/clock`. Same relays, same auth as media. Rule of thumb: anything that can be delta encoded or dropped when stale is a good fit for MoQ. - -**Interactive streams and teleoperation**. Combine both directions: media down, input tracks up. MoQ Boy (`rs/moq-boy`, `demo/boy`) is a crowd-controlled Game Boy doing exactly this: https://moq.dev/blog/moq-boy. The same shape covers flying drones, controlling robots, and remote vehicle operation; some companies start from MoQ Boy and replace the emulator with a robot. - -**Cloud gaming / remote desktop**. Screen capture and low-latency hardware encoding via `rs/moq-video` (camera and display sources on macOS/Windows/Linux, plus window capture), sub-100ms playback in the browser. - -**Native and mobile apps**. One Rust core (`rs/moq-ffi`) with idiomatic bindings: Python (asyncio), Kotlin (coroutines/Flow, Android), Swift (async sequences, iOS/macOS), Go, and C (`rs/libmoq` for C/C++ build systems). Index: https://doc.moq.dev/lib/ - -**Global delivery, hosted or self-hosted**. Don't want to run infrastructure? https://moq.pro offers most of these libraries behind an API and a global CDN, with more CDN providers to come; moq-lite is also forwards-compatible with IETF moq-transport, so it runs over third-party CDNs like Cloudflare (https://moq.dev/blog/first-cdn). To self-host: `moq-relay` clusters across regions (https://doc.moq.dev/bin/relay/cluster), authenticates with path-scoped JWTs (`moq-auth`, https://doc.moq.dev/bin/relay/auth), and exposes live traffic stats as MoQ tracks (`rs/moq-stats`). Load-test with `rs/moq-bench`. Native apps can also connect P2P via Iroh. - -**Web playback/capture on any site**. `` and `` are plain web components with optional UI overlays; embeddable with no build step. Docs: https://doc.moq.dev/lib/js/watch and https://doc.moq.dev/lib/js/publish - -## Repo map - -- `rs/` Rust: `moq-net` (pub/sub), `hang` (media), `moq-relay`, `moq-cli` (installs a `moq` binary), `moq-tokio` (QUIC/TLS setup), `moq-mux` (container muxing), `moq-auth` (auth), gateways (`moq-rtmp`, `moq-srt`, `moq-rtc`, `moq-hls`), native codecs (`moq-video`, `moq-audio`, `moq-nvenc`), `moq-ffi`/`libmoq` (bindings core). -- `js/` TypeScript, published as `@moq/*`: `net`, `hang`, `watch`, `publish`, `token`, `json`, `signals`. -- `py/`, `swift/`, `kt/`, `go/` bindings; `cpp/obs` OBS plugin; `demo/` runnable demos. - -## Getting started - -- Every client connects to a relay URL; the path scopes auth and broadcast names append to it. Public dev relay: `https://cdn.moq.dev/anon` (unauthenticated, testing only, pick a unique name). Hosted production relays: https://moq.pro. Local: `cargo install moq-relay`, or clone the repo and `nix develop -c just` to run a relay, demo media, and web UI together. -- Media broadcast names end in `.hang` (selects the hang catalog; `.msf` selects the IETF MSF format). -- Browsers need WebTransport (Chrome/Edge; Firefox/Safari experimental) and, outside localhost, a real TLS certificate. -- Auth is a JWT in the `?jwt=` query parameter, signed by `moq auth sign` (the `moq-auth` crate and `@moq/auth` package). - -## Reference - -- Documentation: https://doc.moq.dev (concepts, apps, libraries, relay ops) -- Rust API docs: https://docs.rs/moq-net and https://docs.rs/hang -- Runnable examples: https://github.com/moq-dev/moq/tree/main/js/net/examples and https://github.com/moq-dev/moq/tree/main/rs/hang/examples -- Protocol drafts: https://moq-dev.github.io/drafts/draft-lcurley-moq-lite.html -- Inspiration: https://moq.dev/blog/ +- Two layers: `moq-lite` (`moq-net` / `@moq/net`) is the generic pub/sub the relays implement; `hang` (`hang` / `@moq/hang`) is the media catalog and container on top. Use the highest layer that fits: web components, then `@moq/*` / `moq-*` packages, then the wire protocol. +- Every client connects to a relay URL. The path scopes authorization, and broadcast names append to it. +- Media broadcast names end in `.hang`. +- Browsers need WebTransport and, outside localhost, a real TLS certificate. +- Source, examples, and issues: https://github.com/moq-dev/moq