Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(media): add bounded automatic hybrid routing
AAA96b2d4f1e63c
diff --git a/package-lock.json b/package-lock.jsonindex 73f295b7..e22da31f 100644--- a/package-lock.json+++ b/package-lock.json@@ -8,6 +8,8 @@"name": "screener","version": "0.1.0","dependencies": {+ "livekit-client": "2.22.0",+ "livekit-server-sdk": "2.17.0","lucide-react": "1.31.0","react": "19.2.8","react-dom": "19.2.8",@@ -30,6 +32,12 @@"node": ">=24.0.0 <27"}},+ "node_modules/@bufbuild/protobuf": {+ "version": "1.10.1",+ "resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-1.10.1.tgz",+ "integrity": "sha512-wJ8ReQbHxsAfXhrf9ixl0aYbZorRuOWpBNzm8pL8ftmSxQx/wnJD5Eg861NwJU/czy2VXFIebCeZnZrI9rktIQ==",+ "license": "(Apache-2.0 AND BSD-3-Clause)"+ },"node_modules/@esbuild/aix-ppc64": {"version": "0.28.2","resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",@@ -479,6 +487,21 @@"dev": true,"license": "MIT"},+ "node_modules/@livekit/mutex": {+ "version": "1.1.1",+ "resolved": "https://registry.npmjs.org/@livekit/mutex/-/mutex-1.1.1.tgz",+ "integrity": "sha512-EsshAucklmpuUAfkABPxJNhzj9v2sG7JuzFDL4ML1oJQSV14sqrpTYnsaOudMAw9yOaW53NU3QQTlUQoRs4czw==",+ "license": "Apache-2.0"+ },+ "node_modules/@livekit/protocol": {+ "version": "1.50.4",+ "resolved": "https://registry.npmjs.org/@livekit/protocol/-/protocol-1.50.4.tgz",+ "integrity": "sha512-L1uggNQAqyY21smQY8AllyOYbcv9Me9TaxwuLytL1R8ck9nbYPmQLNwEDi3pOFGAMa5F8I2nUi2Jc59W5awxlA==",+ "license": "Apache-2.0",+ "dependencies": {+ "@bufbuild/protobuf": "^1.10.0"+ }+ },"node_modules/@oxc-project/types": {"version": "0.144.0","resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.144.0.tgz",@@ -783,6 +806,13 @@"dev": true,"license": "MIT"},+ "node_modules/@types/dom-mediacapture-record": {+ "version": "1.0.22",+ "resolved": "https://registry.npmjs.org/@types/dom-mediacapture-record/-/dom-mediacapture-record-1.0.22.tgz",+ "integrity": "sha512-mUMZLK3NvwRLcAAT9qmcK+9p7tpU2FHdDsntR3YI4+GY88XrgG4XiE7u1Q2LAN2/FZOz/tdMDC3GQCR4T8nFuw==",+ "license": "MIT",+ "peer": true+ },"node_modules/@types/estree": {"version": "1.0.9","resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",@@ -1072,6 +1102,15 @@"@types/estree": "^1.0.0"}},+ "node_modules/events": {+ "version": "3.3.0",+ "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz",+ "integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",+ "license": "MIT",+ "engines": {+ "node": ">=0.8.x"+ }+ },"node_modules/expect-type": {"version": "1.4.0","resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",@@ -1115,6 +1154,15 @@"node": "^8.16.0 || ^10.6.0 || >=11.0.0"}},+ "node_modules/jose": {+ "version": "6.2.9",+ "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.9.tgz",+ "integrity": "sha512-XrchZOFZUl/T3vTwRe8XK+cJrGtMF4th1ARnDfwbBXFKThGhlsxEE4Zu03AD/bjJSt/9jT/mxrOCkJWOg77aPA==",+ "license": "MIT",+ "funding": {+ "url": "https://github.com/sponsors/panva"+ }+ },"node_modules/lightningcss": {"version": "1.33.0","resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",@@ -1388,6 +1436,62 @@"url": "https://opencollective.com/parcel"}},+ "node_modules/livekit-client": {+ "version": "2.22.0",+ "resolved": "https://registry.npmjs.org/livekit-client/-/livekit-client-2.22.0.tgz",+ "integrity": "sha512-GLtYQfRh/RsvXaOX1x609bFZ17yyKmKWDqu9JmkMKn9vIFLi2GsapRv9gT8OJO/1R2dsitrkbGmloyUfxWQsaA==",+ "license": "Apache-2.0",+ "dependencies": {+ "@livekit/mutex": "1.1.1",+ "@livekit/protocol": "1.50.4",+ "events": "^3.3.0",+ "jose": "^6.1.0",+ "loglevel": "^1.9.2",+ "sdp-transform": "^2.15.0",+ "tslib": "2.8.1",+ "typed-emitter": "^2.1.0",+ "webrtc-adapter": "9.0.6"+ },+ "peerDependencies": {+ "@types/dom-mediacapture-record": "^1"+ }+ },+ "node_modules/livekit-server-sdk": {+ "version": "2.17.0",+ "resolved": "https://registry.npmjs.org/livekit-server-sdk/-/livekit-server-sdk-2.17.0.tgz",+ "integrity": "sha512-GWNEQrUD13UwZNrmosyTVFPgeBvSU2lFKGxdA4DaUI5F4sMb1cGeep/PPEE9vvRNELJYpxWS0ImS4gQmovKUDA==",+ "license": "Apache-2.0",+ "dependencies": {+ "@bufbuild/protobuf": "^1.10.1",+ "@livekit/protocol": "^1.48.0",+ "jose": "^5.1.2"+ },+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/livekit-server-sdk/node_modules/jose": {+ "version": "5.10.0",+ "resolved": "https://registry.npmjs.org/jose/-/jose-5.10.0.tgz",+ "integrity": "sha512-s+3Al/p9g32Iq+oqXxkW//7jk2Vig6FF1CFqzVXoTUXt2qz89YWbL+OwS17NFYEvxC35n0FKeGO2LGYSxeM2Gg==",+ "license": "MIT",+ "funding": {+ "url": "https://github.com/sponsors/panva"+ }+ },+ "node_modules/loglevel": {+ "version": "1.9.2",+ "resolved": "https://registry.npmjs.org/loglevel/-/loglevel-1.9.2.tgz",+ "integrity": "sha512-HgMmCqIJSAKqo68l0rS2AanEWfkxaZ5wNiEFb5ggm08lDs9Xl2KxBlX3PTcaD2chBM1gXAYf491/M2Rv8Jwayg==",+ "license": "MIT",+ "engines": {+ "node": ">= 0.6.0"+ },+ "funding": {+ "type": "tidelift",+ "url": "https://tidelift.com/funding/github/npm/loglevel"+ }+ },"node_modules/lucide-react": {"version": "1.31.0","resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.31.0.tgz",@@ -1559,12 +1663,37 @@"@rolldown/binding-win32-x64-msvc": "1.2.4"}},+ "node_modules/rxjs": {+ "version": "7.8.2",+ "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",+ "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",+ "license": "Apache-2.0",+ "optional": true,+ "dependencies": {+ "tslib": "^2.1.0"+ }+ },"node_modules/scheduler": {"version": "0.27.0","resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz","integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==","license": "MIT"},+ "node_modules/sdp": {+ "version": "3.2.2",+ "resolved": "https://registry.npmjs.org/sdp/-/sdp-3.2.2.tgz",+ "integrity": "sha512-xZocWwfyp4hkbN4hLWxMjmv2Q8aNa9MhmOZ7L9aCZPT+dZsgRr6wZRrSYE3HTdyk/2pZKPSgqI7ns7Een1xMSA==",+ "license": "MIT"+ },+ "node_modules/sdp-transform": {+ "version": "2.15.0",+ "resolved": "https://registry.npmjs.org/sdp-transform/-/sdp-transform-2.15.0.tgz",+ "integrity": "sha512-KrOH82c/W+GYQ0LHqtr3caRpM3ITglq3ljGUIb8LTki7ByacJZ9z+piSGiwZDsRyhQbYBOBJgr2k6X4BZXi3Kw==",+ "license": "MIT",+ "bin": {+ "sdp-verify": "checker.js"+ }+ },"node_modules/siginfo": {"version": "2.0.0","resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",@@ -1663,6 +1792,12 @@"node": ">=6"}},+ "node_modules/tslib": {+ "version": "2.8.1",+ "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",+ "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",+ "license": "0BSD"+ },"node_modules/tsx": {"version": "4.23.12","resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.12.tgz",@@ -1682,6 +1817,15 @@"fsevents": "~2.3.3"}},+ "node_modules/typed-emitter": {+ "version": "2.1.0",+ "resolved": "https://registry.npmjs.org/typed-emitter/-/typed-emitter-2.1.0.tgz",+ "integrity": "sha512-g/KzbYKbH5C2vPkaXGu8DJlHrGKHLsM25Zg9WuC9pMGfuvT+X25tZQWo5fK1BjBm8+UrVE9LDCvaY0CQk+fXDA==",+ "license": "MIT",+ "optionalDependencies": {+ "rxjs": "*"+ }+ },"node_modules/typescript": {"version": "6.0.3","resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",@@ -1871,6 +2015,19 @@}}},+ "node_modules/webrtc-adapter": {+ "version": "9.0.6",+ "resolved": "https://registry.npmjs.org/webrtc-adapter/-/webrtc-adapter-9.0.6.tgz",+ "integrity": "sha512-CHbl2ZQbxx164IgWRgzJno4hWtM4tFbRam1QfI3Yxhs3w/DvqluVxVWeXs3oL5/fbGkSNLKo0Ty5MgUWceNhog==",+ "license": "BSD-3-Clause",+ "dependencies": {+ "sdp": "^3.2.0"+ },+ "engines": {+ "node": ">=6.0.0",+ "npm": ">=3.10.0"+ }+ },"node_modules/why-is-node-running": {"version": "2.3.0","resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",diff --git a/package.json b/package.jsonindex 5c1d674b..0c9586db 100644--- a/package.json+++ b/package.json@@ -20,6 +20,8 @@"check": "npm run typecheck && npm test && npm run build"},"dependencies": {+ "livekit-client": "2.22.0",+ "livekit-server-sdk": "2.17.0","lucide-react": "1.31.0","react": "19.2.8","react-dom": "19.2.8",diff --git a/public/third-party-licenses.txt b/public/third-party-licenses.txtnew file mode 100644index 00000000..ffba06d8--- /dev/null+++ b/public/third-party-licenses.txt@@ -0,0 +1,212 @@+Third-party software notices+============================++This distribution includes:++- livekit-client 2.22.0 (https://github.com/livekit/client-sdk-js)+- livekit-server-sdk 2.17.0 (https://github.com/livekit/node-sdks)++Both packages are licensed under the Apache License, Version 2.0. Neither+package includes a separate NOTICE file in the installed distribution.++ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work+ (an example is provided in the Appendix below).++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONS++ APPENDIX: How to apply the Apache License to your work.++ To apply the Apache License to your work, attach the following+ boilerplate notice, with the fields enclosed by brackets "[]"+ replaced with your own identifying information. (Don't include+ the brackets!) The text should be enclosed in the appropriate+ comment syntax for the file format. We also recommend that a+ file or class name and description of purpose be included on the+ same "printed page" as the copyright notice for easier+ identification within third-party archives.++ Copyright [yyyy] [name of copyright owner]++ Licensed under the Apache License, Version 2.0 (the "License");+ you may not use this file except in compliance with the License.+ You may obtain a copy of the License at++ http://www.apache.org/licenses/LICENSE-2.0++ Unless required by applicable law or agreed to in writing, software+ distributed under the License is distributed on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ See the License for the specific language governing permissions and+ limitations under the License.diff --git a/src/client/media/host-sfu-route.ts b/src/client/media/host-sfu-route.tsnew file mode 100644index 00000000..106d7f7a--- /dev/null+++ b/src/client/media/host-sfu-route.ts@@ -0,0 +1,520 @@+import type {+ ClientMessage,+ MediaRoutePhase,+ ParticipantRouteAssignment,+ ServerMessage,+} from "../../shared/protocol";+import { SfuPublisher, type SfuConnectionConfig } from "../sfu/publisher";+import type { QualityProfile } from "./quality";+import {+ MediaRouteTransition,+ type RouteOperationToken,+ type RouteUpdateInput,+ type RouteUpdateResult,+} from "./route-transition";++interface HostPublisherTransport {+ connect(config: SfuConnectionConfig): Promise<boolean>;+ activate(stream: MediaStream, profile: QualityProfile): Promise<boolean>;+ deactivate(): Promise<boolean>;+ replaceStream(stream: MediaStream): Promise<boolean>;+ updateProfile(profile: QualityProfile): Promise<boolean>;+ disconnect(): Promise<void>;+}++interface HostPublisherSlot {+ revision: number;+ publicationGeneration: string;+ publisher: HostPublisherTransport;+ connected: boolean;+ active: boolean;+ failed: boolean;+ acknowledgeActive: boolean;+}++interface HostSfuRouteEvents {+ getStream: () => MediaStream | null;+ getProfile: () => QualityProfile;+ reconcileChildren: (childPeerIds: string[]) => void;+ send: (message: ClientMessage) => boolean;+ createPublisher?: (onDisconnected: () => void) => HostPublisherTransport;+}++export class HostSfuRoute {+ private readonly route = new MediaRouteTransition();+ private pending: HostPublisherSlot | null = null;+ private active: HostPublisherSlot | null = null;+ private recovery: { revision: number; refreshed: boolean } | null = null;+ private transitionTail: Promise<void> = Promise.resolve();+ private resyncGeneration = 0;+ private resyncing = false;+ private closed = false;++ constructor(private readonly events: HostSfuRouteEvents) {}++ accept(update: RouteUpdateInput, acknowledge = true): RouteUpdateResult {+ if (this.closed) {+ return "stale";+ }+ const previousRevision = this.route.getRevision();+ const result = this.route.accept(update);+ if (result === "stale") {+ return result;+ }+ if (previousRevision !== update.revision) {+ this.recovery = null;+ }+ if (update.phase === "prepare") {+ if (+ this.pending &&+ (this.pending.revision !== update.revision ||+ this.pending.publicationGeneration !==+ update.assignment.sfuPublicationGeneration)+ ) {+ this.clearPending();+ }+ if (update.assignment.sfuPublicationGeneration === null) {+ this.clearPending();+ }+ return result;+ }++ const token = this.route.token();+ if (token && !this.resyncing) {+ void this.queueActivation(token, acknowledge);+ }+ return result;+ }++ async resyncAuthoritative(+ update: RouteUpdateInput,+ ): Promise<RouteUpdateResult> {+ const result = this.accept(update, false);+ if (result !== "stale" || this.closed) {+ return result;+ }++ const resyncGeneration = ++this.resyncGeneration;+ this.resyncing = true;+ this.route.reset();+ this.recovery = null;+ const pending = this.pending;+ const active = this.active;+ this.pending = null;+ this.active = null;+ if (pending) {+ pending.failed = true;+ }+ if (active) {+ active.failed = true;+ }+ const accepted = this.route.accept(update);+ this.events.reconcileChildren([]);++ await this.queueTransition(async () => {+ if (active?.active) {+ await active.publisher.deactivate().catch(() => false);+ }+ if (active) {+ await disconnectPublisher(active.publisher);+ }+ if (pending && pending !== active) {+ await disconnectPublisher(pending.publisher);+ }+ });++ if (this.closed || this.resyncGeneration !== resyncGeneration) {+ return "stale";+ }+ this.resyncing = false;+ const token = this.route.token();+ if (token && this.route.getPhase() === "active") {+ await this.queueActivation(token, false);+ }+ return accepted;+ }++ async acceptConfig(+ message: Extract<ServerMessage, { type: "sfu-config" }>,+ ): Promise<void> {+ if (this.closed || !this.route.acceptsConfig(message.revision)) {+ return;+ }+ const token = this.route.token();+ const assignment = this.route.getPlannedAssignment();+ const phase = this.route.getPhase();+ const publicationGeneration = assignment?.sfuPublicationGeneration;+ if (!token || !phase || !assignment || !publicationGeneration) {+ return;+ }++ if (this.active?.publicationGeneration === publicationGeneration) {+ this.active.revision = message.revision;+ if (phase === "prepare" && this.active.connected) {+ this.ready(message.revision, "prepare");+ } else if (phase === "active" && this.active.active) {+ await this.queueActivation(token, true);+ }+ return;+ }+ if (+ this.pending?.revision === message.revision &&+ this.pending.publicationGeneration === publicationGeneration &&+ !this.pending.failed+ ) {+ if (this.pending.connected && phase === "prepare") {+ this.ready(message.revision, "prepare");+ }+ return;+ }++ this.clearPending();+ let slot: HostPublisherSlot;+ const publisher =+ this.events.createPublisher?.(() => this.handleFailure(slot)) ??+ new SfuPublisher({ onDisconnected: () => this.handleFailure(slot) });+ slot = {+ revision: message.revision,+ publicationGeneration,+ publisher,+ connected: false,+ active: false,+ failed: false,+ acknowledgeActive: false,+ };+ this.pending = slot;+ try {+ const connected = await publisher.connect({+ url: message.url,+ token: message.token,+ });+ if (!connected) {+ if (this.pending === slot && this.route.owns(token)) {+ this.handleFailure(slot);+ }+ await disconnectPublisher(publisher);+ return;+ }+ if (this.pending !== slot || !this.route.owns(token)) {+ await disconnectPublisher(publisher);+ return;+ }+ slot.connected = true;+ if (phase === "prepare") {+ this.ready(message.revision, "prepare");+ } else if (!this.resyncing) {+ await this.queueActivation(token, true);+ }+ } catch {+ await disconnectPublisher(publisher);+ this.handleFailure(slot);+ }+ }++ updateProfile(profile: QualityProfile): Promise<boolean> {+ return this.active?.active+ ? this.active.publisher.updateProfile(profile).catch(() => false)+ : Promise.resolve(true);+ }++ replaceStream(stream: MediaStream): Promise<boolean> {+ return this.active+ ? this.active.publisher.replaceStream(stream).catch(() => false)+ : Promise.resolve(true);+ }++ async failActivePublisher(): Promise<void> {+ await this.queueTransition(async () => {+ const slot = this.active;+ if (!slot) {+ return;+ }+ this.active = null;+ await disconnectPublisher(slot.publisher);+ this.handleFailure(slot);+ });+ }++ async disconnect(): Promise<void> {+ if (this.closed) {+ return;+ }+ this.closed = true;+ this.resyncGeneration += 1;+ this.resyncing = false;+ this.route.reset();+ this.recovery = null;+ await this.queueTransition(async () => {+ const pending = this.pending;+ const active = this.active;+ this.pending = null;+ this.active = null;+ if (active?.active) {+ await active.publisher.deactivate().catch(() => false);+ }+ await Promise.all([+ pending ? disconnectPublisher(pending.publisher) : undefined,+ active && active !== pending+ ? disconnectPublisher(active.publisher)+ : undefined,+ ]);+ });+ }++ private queueActivation(+ token: RouteOperationToken,+ acknowledge: boolean,+ ): Promise<void> {+ return this.queueTransition(async () => {+ if (this.closed || this.resyncing || !this.route.owns(token, "active")) {+ return;+ }+ const assignment = this.route.getActiveAssignment();+ if (assignment) {+ await this.activate(assignment, token, acknowledge);+ }+ });+ }++ private queueTransition(work: () => Promise<void>): Promise<void> {+ const next = this.transitionTail.then(work, work);+ this.transitionTail = next.catch(() => undefined);+ return this.transitionTail;+ }++ private async activate(+ assignment: ParticipantRouteAssignment,+ token: RouteOperationToken,+ acknowledge: boolean,+ ): Promise<void> {+ const publicationGeneration = assignment.sfuPublicationGeneration;+ if (publicationGeneration === null) {+ this.clearPending();+ await this.retireActive();+ if (!this.route.owns(token, "active")) {+ return;+ }+ this.events.reconcileChildren(assignment.childPeerIds);+ this.commitMedia(token, acknowledge);+ return;+ }++ this.events.reconcileChildren(assignment.childPeerIds);+ if (+ this.active &&+ !this.active.failed &&+ this.active.publicationGeneration === publicationGeneration+ ) {+ this.active.revision = token.revision;+ this.clearPending();+ if (this.active.active) {+ this.commitMedia(token, acknowledge);+ } else {+ this.active.acknowledgeActive ||= acknowledge;+ }+ return;+ }++ const pending = this.pending;+ if (+ !pending ||+ pending.revision !== token.revision ||+ pending.publicationGeneration !== publicationGeneration ||+ !pending.connected+ ) {+ await this.retireActive();+ if (acknowledge && this.route.owns(token, "active")) {+ this.requestRecovery(token.revision);+ }+ return;+ }++ await this.retireActive(pending);+ if (!this.route.owns(token, "active")) {+ this.clearPending(pending);+ return;+ }+ this.pending = null;+ this.active = pending;+ pending.acknowledgeActive ||= acknowledge;+ const publishedStream = this.events.getStream();+ const publishedProfile = this.events.getProfile();+ if (!publishedStream) {+ await disconnectPublisher(pending.publisher);+ this.handleFailure(pending);+ return;+ }++ try {+ const activated = await pending.publisher.activate(+ publishedStream,+ publishedProfile,+ );+ const activeToken = this.currentActiveToken(pending);+ if (!activated || !activeToken) {+ if (this.active === pending) {+ this.active = null;+ }+ await disconnectPublisher(pending.publisher);+ if (!activated && activeToken) {+ this.handleFailure(pending);+ }+ return;+ }+ pending.active = true;++ const latestStream = this.events.getStream();+ if (+ latestStream &&+ latestStream !== publishedStream &&+ !(await pending.publisher.replaceStream(latestStream))+ ) {+ await disconnectPublisher(pending.publisher);+ this.handleFailure(pending);+ return;+ }+ const latestProfile = this.events.getProfile();+ if (+ latestProfile !== publishedProfile &&+ !(await pending.publisher.updateProfile(latestProfile))+ ) {+ await disconnectPublisher(pending.publisher);+ this.handleFailure(pending);+ return;+ }+ } catch {+ await disconnectPublisher(pending.publisher);+ this.handleFailure(pending);+ return;+ }++ const activeToken = this.currentActiveToken(pending);+ if (!activeToken) {+ if (this.active === pending) {+ this.active = null;+ }+ await disconnectPublisher(pending.publisher);+ return;+ }+ if (!this.route.owns(token, "active")) {+ pending.acknowledgeActive = false;+ return;+ }+ const acknowledgeActive = pending.acknowledgeActive;+ pending.acknowledgeActive = false;+ this.commitMedia(activeToken, acknowledgeActive);+ }++ private currentActiveToken(+ slot: HostPublisherSlot,+ ): RouteOperationToken | null {+ const token = this.route.token();+ const assignment = this.route.getActiveAssignment();+ if (+ this.active !== slot ||+ !token ||+ this.route.getPhase() !== "active" ||+ assignment?.sfuPublicationGeneration !== slot.publicationGeneration+ ) {+ return null;+ }+ return token;+ }++ private commitMedia(token: RouteOperationToken, acknowledge: boolean): void {+ if (!this.route.markMediaActive(token)) {+ return;+ }+ this.recovery = null;+ if (acknowledge) {+ this.ready(token.revision, "active");+ }+ }++ private clearPending(expected?: HostPublisherSlot): void {+ if (!this.pending || (expected && this.pending !== expected)) {+ return;+ }+ const pending = this.pending;+ this.pending = null;+ void disconnectPublisher(pending.publisher);+ }++ private async retireActive(except?: HostPublisherSlot): Promise<void> {+ if (!this.active || this.active === except) {+ return;+ }+ const active = this.active;+ this.active = null;+ if (active.active) {+ await active.publisher.deactivate().catch(() => false);+ }+ await disconnectPublisher(active.publisher);+ }++ private handleFailure(slot: HostPublisherSlot): void {+ if (this.closed || slot.failed) {+ return;+ }+ const wasActive = this.active === slot;+ slot.failed = true;+ if (this.pending === slot) {+ this.pending = null;+ }+ if (wasActive) {+ this.active = null;+ }++ const assignment = this.route.getPlannedAssignment();+ const revision = this.route.getRevision();+ const phase = this.route.getPhase();+ const matchesPlannedRoute =+ revision === slot.revision &&+ assignment?.sfuPublicationGeneration === slot.publicationGeneration;+ if (revision === null || phase === null) {+ return;+ }+ if (phase === "prepare") {+ if (matchesPlannedRoute || wasActive) {+ this.routeFailed(revision, "prepare");+ }+ return;+ }+ if (!matchesPlannedRoute) {+ return;+ }+ this.requestRecovery(revision);+ }++ private requestRecovery(revision: number): void {+ if (!this.recovery || this.recovery.revision !== revision) {+ this.recovery = { revision, refreshed: false };+ }+ if (!this.recovery.refreshed) {+ this.recovery.refreshed = true;+ if (this.events.send({ type: "refresh-sfu", revision })) {+ return;+ }+ }+ this.routeFailed(revision, "active");+ }++ private routeFailed(revision: number, phase: MediaRoutePhase): void {+ this.events.send({+ type: "route-failed",+ revision,+ phase,+ connectionId: null,+ });+ }++ private ready(revision: number, phase: MediaRoutePhase): void {+ this.events.send({ type: "route-ready", revision, phase });+ }+}++async function disconnectPublisher(+ publisher: HostPublisherTransport,+): Promise<void> {+ await publisher.disconnect().catch(() => undefined);+}diff --git a/src/client/media/relay-capability.ts b/src/client/media/relay-capability.tsnew file mode 100644index 00000000..7140c09a--- /dev/null+++ b/src/client/media/relay-capability.ts@@ -0,0 +1,51 @@+import type { ClientMessage } from "../../shared/protocol";++export interface BrowserRelayEnvironment {+ userAgent: string;+ userAgentDataMobile?: boolean;+ maxTouchPoints: number;+}++type RelayCapacityMessage = Extract<+ ClientMessage,+ { type: "relay-capacity" }+>;++export function detectBrowserRelayCapacity(+ environment: BrowserRelayEnvironment,+): 0 | 1 {+ if (+ environment.userAgentDataMobile === true ||+ /Android|iPhone|iPad|iPod|Mobile/i.test(environment.userAgent) ||+ (/Macintosh/i.test(environment.userAgent) &&+ environment.maxTouchPoints > 1)+ ) {+ return 0;+ }+ return 1;+}++export function relayCapacityMessageForBrowser(+ peerAssisted: boolean,+ environment?: BrowserRelayEnvironment,+): RelayCapacityMessage | null {+ if (!peerAssisted) {+ return null;+ }+ const browser = environment ?? currentBrowserEnvironment();+ return {+ type: "relay-capacity",+ downstreamEdges: detectBrowserRelayCapacity(browser),+ };+}++function currentBrowserEnvironment(): BrowserRelayEnvironment {+ const browserNavigator = navigator as Navigator & {+ userAgentData?: { mobile?: boolean };+ };+ return {+ userAgent: browserNavigator.userAgent,+ userAgentDataMobile: browserNavigator.userAgentData?.mobile,+ maxTouchPoints: browserNavigator.maxTouchPoints,+ };+}diff --git a/src/client/media/route-transition.ts b/src/client/media/route-transition.tsnew file mode 100644index 00000000..fb478689--- /dev/null+++ b/src/client/media/route-transition.ts@@ -0,0 +1,164 @@+import type {+ ClientMessage,+ MediaRoutePhase,+ ParticipantRouteAssignment,+} from "../../shared/protocol";++export interface RouteUpdateInput {+ revision: number;+ phase: MediaRoutePhase;+ assignment: ParticipantRouteAssignment;+}++export interface RouteOperationToken {+ revision: number;+ generation: number;+}++export type RouteUpdateResult = "accepted" | "duplicate" | "stale";++export class MediaRouteTransition {+ private revision = -1;+ private phase: MediaRoutePhase | null = null;+ private plannedAssignment: ParticipantRouteAssignment | null = null;+ private activeAssignment: ParticipantRouteAssignment | null = null;+ private mediaAssignment: ParticipantRouteAssignment | null = null;+ private generation = 0;++ accept(update: RouteUpdateInput): RouteUpdateResult {+ if (update.revision < this.revision) {+ return "stale";+ }+ if (update.revision === this.revision) {+ if (+ !this.plannedAssignment ||+ !sameAssignment(this.plannedAssignment, update.assignment) ||+ (this.phase === "active" && update.phase === "prepare")+ ) {+ return "stale";+ }+ if (this.phase === update.phase) {+ return "duplicate";+ }+ }++ this.revision = update.revision;+ this.phase = update.phase;+ this.plannedAssignment = cloneAssignment(update.assignment);+ if (update.phase === "active") {+ this.activeAssignment = cloneAssignment(update.assignment);+ }+ this.generation += 1;+ return "accepted";+ }++ acceptsConfig(revision: number): boolean {+ return revision === this.revision && this.phase !== null;+ }++ token(): RouteOperationToken | null {+ if (this.revision < 0 || this.phase === null) {+ return null;+ }+ return { revision: this.revision, generation: this.generation };+ }++ owns(token: RouteOperationToken, phase?: MediaRoutePhase): boolean {+ return (+ token.revision === this.revision &&+ token.generation === this.generation &&+ (phase === undefined || this.phase === phase)+ );+ }++ markMediaActive(token: RouteOperationToken): boolean {+ if (!this.owns(token, "active") || !this.activeAssignment) {+ return false;+ }+ this.mediaAssignment = cloneAssignment(this.activeAssignment);+ return true;+ }++ getRevision(): number | null {+ return this.revision < 0 ? null : this.revision;+ }++ getPhase(): MediaRoutePhase | null {+ return this.phase;+ }++ getPlannedAssignment(): ParticipantRouteAssignment | null {+ return this.plannedAssignment+ ? cloneAssignment(this.plannedAssignment)+ : null;+ }++ getActiveAssignment(): ParticipantRouteAssignment | null {+ return this.activeAssignment ? cloneAssignment(this.activeAssignment) : null;+ }++ getMediaAssignment(): ParticipantRouteAssignment | null {+ return this.mediaAssignment ? cloneAssignment(this.mediaAssignment) : null;+ }++ reset(): void {+ this.revision = -1;+ this.phase = null;+ this.plannedAssignment = null;+ this.activeAssignment = null;+ this.mediaAssignment = null;+ this.generation += 1;+ }+}++export function reportActivePeerRouteFailure(+ route: MediaRouteTransition,+ parentPeerId: string,+ connectionId: string,+ send: (message: ClientMessage) => boolean,+): boolean {+ const assignment = route.getActiveAssignment();+ const revision = route.getRevision();+ if (+ route.getPhase() !== "active" ||+ revision === null ||+ assignment?.upstream.kind !== "peer" ||+ assignment.upstream.peerId !== parentPeerId+ ) {+ return true;+ }+ return send({+ type: "route-failed",+ revision,+ phase: "active",+ connectionId,+ });+}++function sameAssignment(+ left: ParticipantRouteAssignment,+ right: ParticipantRouteAssignment,+): boolean {+ return (+ left.upstream.kind === right.upstream.kind &&+ (left.upstream.kind !== "peer" ||+ (right.upstream.kind === "peer" &&+ left.upstream.peerId === right.upstream.peerId)) &&+ left.sfuPublicationGeneration === right.sfuPublicationGeneration &&+ left.childPeerIds.length === right.childPeerIds.length &&+ left.childPeerIds.every((peerId, index) => peerId === right.childPeerIds[index])+ );+}++function cloneAssignment(+ assignment: ParticipantRouteAssignment,+): ParticipantRouteAssignment {+ return {+ upstream:+ assignment.upstream.kind === "peer"+ ? { kind: "peer", peerId: assignment.upstream.peerId }+ : { kind: assignment.upstream.kind },+ childPeerIds: [...assignment.childPeerIds],+ sfuPublicationGeneration: assignment.sfuPublicationGeneration,+ };+}diff --git a/src/client/media/viewer-message-authority.ts b/src/client/media/viewer-message-authority.tsnew file mode 100644index 00000000..3d990c3a--- /dev/null+++ b/src/client/media/viewer-message-authority.ts@@ -0,0 +1,29 @@+import type { ServerMessage } from "../../shared/protocol";++const AUTHORITY_MESSAGE_TYPES = new Set<ServerMessage["type"]>([+ "authenticated",+ "ice-config",+ "host-status",+ "sharing-stopped",+ "room-closed",+ "error",+]);++export class ViewerMessageAuthority {+ private generation = 0;++ tokenFor(message: ServerMessage): number {+ if (AUTHORITY_MESSAGE_TYPES.has(message.type)) {+ this.generation += 1;+ }+ return this.generation;+ }++ invalidate(): void {+ this.generation += 1;+ }++ owns(token: number): boolean {+ return token === this.generation;+ }+}diff --git a/src/client/media/viewer-sfu-route.ts b/src/client/media/viewer-sfu-route.tsnew file mode 100644index 00000000..b5e21c9d--- /dev/null+++ b/src/client/media/viewer-sfu-route.ts@@ -0,0 +1,495 @@+import type {+ ClientMessage,+ MediaRoutePhase,+ ParticipantRouteAssignment,+ ServerMessage,+} from "../../shared/protocol";+import { SfuSubscriber } from "../sfu/subscriber";+import type { SfuConnectionConfig } from "../sfu/publisher";+import {+ MediaRouteTransition,+ reportActivePeerRouteFailure,+ type RouteOperationToken,+ type RouteUpdateInput,+ type RouteUpdateResult,+} from "./route-transition";++interface ViewerSubscriberTransport {+ connect(config: SfuConnectionConfig): Promise<boolean>;+ activate(): boolean;+ deactivate(): boolean;+ disconnect(): Promise<void>;+}++interface ViewerSubscriberSlot {+ revision: number;+ subscriber: ViewerSubscriberTransport;+ connected: boolean;+ activated: boolean;+ failed: boolean;+ activationToken: RouteOperationToken | null;+}++interface ViewerSfuRouteEvents {+ activatePeer: (+ assignment: ParticipantRouteAssignment,+ ) => void | Promise<void>;+ preparePeer?: (assignment: ParticipantRouteAssignment | null) => void;+ resetMedia?: () => void;+ reconcileSfuChildren: (childPeerIds: string[]) => void;+ onSfuStream: (+ stream: MediaStream,+ assignment: ParticipantRouteAssignment,+ initialVideoStream: boolean,+ ) => void;+ send: (message: ClientMessage) => boolean;+ createSubscriber?: (+ events: {+ onStream: (stream: MediaStream | null) => void;+ onDisconnected: () => void;+ },+ ) => ViewerSubscriberTransport;+}++export class ViewerSfuRoute {+ private readonly route = new MediaRouteTransition();+ private pending: ViewerSubscriberSlot | null = null;+ private active: ViewerSubscriberSlot | null = null;+ private recovery: { revision: number; refreshed: boolean } | null = null;+ private transitionTail: Promise<void> = Promise.resolve();+ private resyncGeneration = 0;+ private resyncing = false;+ private closed = false;++ constructor(private readonly events: ViewerSfuRouteEvents) {}++ accept(update: RouteUpdateInput, acknowledge = true): RouteUpdateResult {+ if (this.closed) {+ return "stale";+ }+ const previousRevision = this.route.getRevision();+ const result = this.route.accept(update);+ if (result === "stale") {+ return result;+ }+ if (previousRevision !== update.revision) {+ this.recovery = null;+ }+ if (update.phase === "prepare") {+ if (this.pending?.revision !== update.revision) {+ this.clearPending();+ }+ if (update.assignment.upstream.kind !== "sfu") {+ this.clearPending();+ }+ return result;+ }++ const token = this.route.token();+ if (!token) {+ return result;+ }+ this.preparePeer(update.assignment);+ if (this.resyncing) {+ return result;+ }+ void this.queueActiveRoute(token, acknowledge);+ return result;+ }++ async resyncAuthoritative(+ update: RouteUpdateInput,+ ): Promise<RouteUpdateResult> {+ const result = this.accept(update, false);+ if (result !== "stale" || this.closed) {+ return result;+ }++ const resyncGeneration = ++this.resyncGeneration;+ this.resyncing = true;+ this.route.reset();+ this.recovery = null;+ const pending = this.pending;+ const active = this.active;+ this.pending = null;+ this.active = null;+ if (pending) {+ pending.failed = true;+ }+ if (active) {+ active.failed = true;+ }+ const accepted = this.route.accept(update);+ this.preparePeer(update.assignment);+ this.events.resetMedia?.();++ await this.queueTransition(async () => {+ if (active?.activated) {+ try {+ active.subscriber.deactivate();+ } catch {+ // Disconnect remains the fail-closed cleanup path.+ }+ }+ if (active) {+ await disconnectSubscriber(active.subscriber);+ }+ if (pending && pending !== active) {+ await disconnectSubscriber(pending.subscriber);+ }+ });++ if (this.closed || this.resyncGeneration !== resyncGeneration) {+ return "stale";+ }+ this.resyncing = false;+ const token = this.route.token();+ if (token && this.route.getPhase() === "active") {+ await this.queueActiveRoute(token, false);+ }+ return accepted;+ }++ async acceptConfig(+ message: Extract<ServerMessage, { type: "sfu-config" }>,+ ): Promise<void> {+ if (this.closed || !this.route.acceptsConfig(message.revision)) {+ return;+ }+ const token = this.route.token();+ const assignment = this.route.getPlannedAssignment();+ const phase = this.route.getPhase();+ if (!token || !phase || assignment?.upstream.kind !== "sfu") {+ return;+ }++ if (this.active?.revision === message.revision && this.active.activated) {+ if (phase === "prepare") {+ this.ready(message.revision, "prepare");+ }+ return;+ }+ if (this.pending?.revision === message.revision && !this.pending.failed) {+ if (this.pending.connected && phase === "prepare") {+ this.ready(message.revision, "prepare");+ }+ return;+ }++ this.clearPending();+ let slot: ViewerSubscriberSlot;+ const subscriberEvents = {+ onStream: (stream: MediaStream | null) => {+ if (stream) {+ this.handleStream(slot, stream);+ }+ },+ onDisconnected: () => this.handleFailure(slot),+ };+ const subscriber =+ this.events.createSubscriber?.(subscriberEvents) ??+ new SfuSubscriber(subscriberEvents);+ slot = {+ revision: message.revision,+ subscriber,+ connected: false,+ activated: false,+ failed: false,+ activationToken: null,+ };+ this.pending = slot;+ try {+ const connected = await subscriber.connect({+ url: message.url,+ token: message.token,+ });+ if (!connected) {+ if (this.pending === slot && this.route.owns(token)) {+ this.handleFailure(slot);+ }+ await disconnectSubscriber(subscriber);+ return;+ }+ if (this.pending !== slot || !this.route.owns(token)) {+ await disconnectSubscriber(subscriber);+ return;+ }+ slot.connected = true;+ if (phase === "prepare") {+ this.ready(message.revision, "prepare");+ } else if (!this.resyncing) {+ await this.queueActiveRoute(token, true);+ }+ } catch {+ await disconnectSubscriber(subscriber);+ this.handleFailure(slot);+ }+ }++ reportPeerFailure(parentPeerId: string, connectionId: string): boolean {+ return reportActivePeerRouteFailure(+ this.route,+ parentPeerId,+ connectionId,+ this.events.send,+ );+ }++ async disconnect(): Promise<void> {+ if (this.closed) {+ return;+ }+ this.closed = true;+ this.resyncGeneration += 1;+ this.resyncing = false;+ this.route.reset();+ this.recovery = null;+ this.events.preparePeer?.(null);+ await this.queueTransition(async () => {+ const pending = this.pending;+ const active = this.active;+ this.pending = null;+ this.active = null;+ if (active?.activated) {+ try {+ active.subscriber.deactivate();+ } catch {+ // Disconnect remains the fail-closed cleanup path.+ }+ }+ await Promise.all([+ pending ? disconnectSubscriber(pending.subscriber) : undefined,+ active && active !== pending+ ? disconnectSubscriber(active.subscriber)+ : undefined,+ ]);+ });+ }++ private preparePeer(assignment: ParticipantRouteAssignment): void {+ this.events.preparePeer?.(+ assignment.upstream.kind === "peer" ? assignment : null,+ );+ }++ private queueActiveRoute(+ token: RouteOperationToken,+ acknowledge: boolean,+ ): Promise<void> {+ return this.queueTransition(async () => {+ if (this.closed || this.resyncing || !this.route.owns(token, "active")) {+ return;+ }+ const assignment = this.route.getActiveAssignment();+ if (!assignment) {+ return;+ }+ if (assignment.upstream.kind === "sfu") {+ this.events.reconcileSfuChildren(assignment.childPeerIds);+ const mediaAssignment = this.route.getMediaAssignment();+ if (+ mediaAssignment?.upstream.kind === "sfu" &&+ this.active?.activated &&+ this.pending?.revision !== token.revision+ ) {+ this.clearPending();+ this.active.revision = token.revision;+ this.commitMedia(token, acknowledge);+ return;+ }+ await this.activateSfu(token, acknowledge);+ return;+ }++ this.clearPending();+ if (this.active) {+ await this.retireActive();+ }+ if (!this.route.owns(token, "active")) {+ return;+ }+ await this.events.activatePeer(assignment);+ if (!this.route.owns(token, "active")) {+ return;+ }+ this.commitMedia(token, acknowledge);+ });+ }++ private queueTransition(work: () => Promise<void>): Promise<void> {+ const next = this.transitionTail.then(work, work);+ this.transitionTail = next.catch(() => undefined);+ return this.transitionTail;+ }++ private async activateSfu(+ token: RouteOperationToken,+ acknowledge: boolean,+ ): Promise<void> {+ if (this.active?.revision === token.revision && this.active.activated) {+ return;+ }+ const pending = this.pending;+ if (!pending || pending.revision !== token.revision || !pending.connected) {+ if (acknowledge && this.route.owns(token, "active")) {+ this.requestRecovery(token.revision);+ }+ return;+ }+ pending.activationToken = token;+ try {+ if (!pending.subscriber.activate()) {+ await disconnectSubscriber(pending.subscriber);+ this.handleFailure(pending);+ return;+ }+ pending.activated = true;+ } catch {+ await disconnectSubscriber(pending.subscriber);+ this.handleFailure(pending);+ }+ }++ private handleStream(slot: ViewerSubscriberSlot, stream: MediaStream): void {+ if (this.closed || slot.failed || !slot.activated) {+ return;+ }+ if (this.active === slot) {+ const assignment = this.route.getMediaAssignment();+ if (assignment?.upstream.kind === "sfu") {+ this.events.onSfuStream(stream, assignment, false);+ }+ return;+ }+ const token = slot.activationToken;+ const assignment = this.route.getActiveAssignment();+ if (+ this.pending !== slot ||+ !token ||+ !this.route.owns(token, "active") ||+ assignment?.upstream.kind !== "sfu"+ ) {+ return;+ }++ this.pending = null;+ const previous = this.active;+ this.active = slot;+ if (!this.route.markMediaActive(token)) {+ this.active = previous;+ void disconnectSubscriber(slot.subscriber);+ return;+ }+ this.recovery = null;+ this.events.onSfuStream(stream, assignment, true);+ if (previous && previous !== slot) {+ try {+ previous.subscriber.deactivate();+ } catch {+ // Disconnect remains the fail-closed cleanup path.+ }+ void disconnectSubscriber(previous.subscriber);+ }+ this.ready(token.revision, "active");+ }++ private commitMedia(token: RouteOperationToken, acknowledge: boolean): void {+ if (!this.route.markMediaActive(token)) {+ return;+ }+ this.recovery = null;+ if (acknowledge) {+ this.ready(token.revision, "active");+ }+ }++ private clearPending(): void {+ if (!this.pending) {+ return;+ }+ const pending = this.pending;+ this.pending = null;+ void disconnectSubscriber(pending.subscriber);+ }++ private async retireActive(): Promise<void> {+ if (!this.active) {+ return;+ }+ const active = this.active;+ this.active = null;+ if (active.activated) {+ try {+ active.subscriber.deactivate();+ } catch {+ // Disconnect remains the fail-closed cleanup path.+ }+ }+ await disconnectSubscriber(active.subscriber);+ }++ private handleFailure(slot: ViewerSubscriberSlot): void {+ if (this.closed || slot.failed) {+ return;+ }+ const wasActive = this.active === slot;+ slot.failed = true;+ if (this.pending === slot) {+ this.pending = null;+ }+ if (wasActive) {+ this.active = null;+ }++ const assignment = this.route.getPlannedAssignment();+ const revision = this.route.getRevision();+ const phase = this.route.getPhase();+ const matchesPlannedRoute =+ revision === slot.revision && assignment?.upstream.kind === "sfu";+ if (revision === null || phase === null) {+ return;+ }+ if (phase === "prepare") {+ if (matchesPlannedRoute || wasActive) {+ this.routeFailed(revision, "prepare");+ }+ return;+ }+ if (!matchesPlannedRoute) {+ return;+ }+ this.requestRecovery(revision);+ }++ private requestRecovery(revision: number): void {+ if (!this.recovery || this.recovery.revision !== revision) {+ this.recovery = { revision, refreshed: false };+ }+ if (!this.recovery.refreshed) {+ this.recovery.refreshed = true;+ if (this.events.send({ type: "refresh-sfu", revision })) {+ return;+ }+ }+ this.routeFailed(revision, "active");+ }++ private routeFailed(revision: number, phase: MediaRoutePhase): void {+ this.events.send({+ type: "route-failed",+ revision,+ phase,+ connectionId: null,+ });+ }++ private ready(revision: number, phase: MediaRoutePhase): void {+ this.events.send({ type: "route-ready", revision, phase });+ }+}++async function disconnectSubscriber(+ subscriber: ViewerSubscriberTransport,+): Promise<void> {+ await subscriber.disconnect().catch(() => undefined);+}diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex bcae8a92..38d268e0 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -25,6 +25,7 @@ import {} from "../components/StatusBadge";import { StatsGrid } from "../components/StatsGrid";import { ApiError, createRoom } from "../lib/api";+import { createOpaqueId } from "../lib/opaque-id";import {clearHostRoom,getStableClientId,@@ -40,6 +41,7 @@ import {setVideoPaused,type QualityProfileId,} from "../media/quality";+import { HostSfuRoute } from "../media/host-sfu-route";import type {PeerSnapshot,SignalConnectionState,@@ -85,6 +87,7 @@ function closeAbandonedRoom(room: CreateRoomResponse): void {role: "host",token: room.hostToken,clientId: getStableClientId("host", room.roomId),+ shareGeneration: createOpaqueId(),},{onMessage: () => undefined,@@ -113,6 +116,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const [qualityId, setQualityId] = useState<QualityProfileId>(DEFAULT_QUALITY_PROFILE_ID,);+ const shareGenerationRef = useRef<string | null>(null);const [phase, setPhase] = useState<HostPhase>("idle");const [signalStatus, setSignalStatus] =useState<SignalConnectionState>("offline");@@ -143,6 +147,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const qualityIdRef = useRef<QualityProfileId>(DEFAULT_QUALITY_PROFILE_ID);const picturePausedRef = useRef(false);const retiringStreamRef = useRef<MediaStream | null>(null);+ const hostSfuRouteRef = useRef<HostSfuRoute | null>(null);const viewers = useMemo(() => Array.from(peerSnapshots.values()),@@ -164,6 +169,8 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {signalRef.current?.stop();peersRef.current.forEach((peer) => peer.dispose());peersRef.current.clear();+ void hostSfuRouteRef.current?.disconnect();+ hostSfuRouteRef.current = null;streamRef.current?.getTracks().forEach((track) => track.stop());retiringStreamRef.current?.getTracks().forEach((track) => track.stop());streamRef.current = null;@@ -179,21 +186,59 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {);}+ function ensureHostSfuRoute(generation: number): HostSfuRoute {+ const existing = hostSfuRouteRef.current;+ if (existing) {+ return existing;+ }+ let route: HostSfuRoute;+ route = new HostSfuRoute({+ getStream: () => streamRef.current,+ getProfile: () => QUALITY_PROFILES[qualityIdRef.current],+ reconcileChildren: (childPeerIds) => {+ if (+ isCurrentGeneration(generation) &&+ hostSfuRouteRef.current === route+ ) {+ reconcilePeerAssistedChildren(childPeerIds, generation);+ }+ },+ send: (message) =>+ isCurrentGeneration(generation) && hostSfuRouteRef.current === route+ ? signalRef.current?.send(message) === true+ : false,+ });+ hostSfuRouteRef.current = route;+ return route;+ }++ function clearHostSfuRoute(): void {+ const route = hostSfuRouteRef.current;+ hostSfuRouteRef.current = null;+ void route?.disconnect();+ }+function disposeResources(notifyServer: boolean): void {sourceSwitchRef.current = null;qualityChangeRef.current = null;const signal = signalRef.current;if (signal) {if (notifyServer) {- signal.send({ type: "stop-sharing" });+ const shareGeneration = shareGenerationRef.current;+ if (shareGeneration) {+ signal.send({ type: "stop-sharing", shareGeneration });+ }}// Never carry a terminal message into a later authentication: the next// sharing generation may already be reusing this room.signal.stop();}signalRef.current = null;+ shareGenerationRef.current = null;peersRef.current.forEach((peer) => peer.dispose());peersRef.current.clear();+ void hostSfuRouteRef.current?.disconnect();+ hostSfuRouteRef.current = null;streamRef.current?.getTracks().forEach((track) => track.stop());retiringStreamRef.current?.getTracks().forEach((track) => track.stop());streamRef.current = null;@@ -311,17 +356,20 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {qualityProfileId: nextId,});}- const results = await Promise.all(- [...peersRef.current.values()].map((peer) => peer.updateProfile(profile)),- );+ const [results, sfuUpdated] = await Promise.all([+ Promise.all(+ [...peersRef.current.values()].map((peer) => peer.updateProfile(profile)),+ ),+ hostSfuRouteRef.current?.updateProfile(profile) ?? Promise.resolve(true),+ ]);if (isCurrentGeneration(generation) &&qualityChangeRef.current === token) {const failed = results.filter((updated) => !updated).length;setNotice(- failed > 0- ? `画质已切换,${failed} 位观众未能应用新的发送参数`+ failed > 0 || !sfuUpdated+ ? "画质已切换,但部分观看连接未能应用新参数": `画质已切换为 ${profile.label}`,);}@@ -520,13 +568,17 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {type: "set-quality-profile",qualityProfileId: qualityIdRef.current,});- reconcilePeerAssistedChildren(- message.mediaAssignment.childPeerIds,- generation,+ void ensureHostSfuRoute(generation).resyncAuthoritative(+ {+ revision: message.routeRevision,+ phase: "active",+ assignment: message.routeAssignment,+ },);return;}peerAssistedRef.current = false;+ clearHostSfuRoute();const currentViewerIds = new Set(message.viewerPeerIds);for (const peerId of peersRef.current.keys()) {if (!currentViewerIds.has(peerId)) {@@ -535,8 +587,20 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}return;}- if (message.type === "media-assignment") {+ if (message.type === "route-update") {+ if (peerAssistedRef.current) {+ ensureHostSfuRoute(generation).accept(message);+ }+ return;+ }+ if (message.type === "sfu-config") {if (peerAssistedRef.current) {+ void ensureHostSfuRoute(generation).acceptConfig(message);+ }+ return;+ }+ if (message.type === "media-assignment") {+ if (peerAssistedRef.current && !hostSfuRouteRef.current) {reconcilePeerAssistedChildren(message.mediaAssignment.childPeerIds,generation,@@ -621,8 +685,10 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {return;}const generation = generationRef.current + 1;+ const shareGeneration = createOpaqueId();generationRef.current = generation;activeGenerationRef.current = generation;+ shareGenerationRef.current = shareGeneration;setNotice(null);setCopied(false);setPhase("starting");@@ -636,6 +702,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {return;}activeGenerationRef.current = null;+ shareGenerationRef.current = null;setNotice(readableError(error));setPhase("error");return;@@ -681,6 +748,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {role: "host",token: activeRoom.hostToken,clientId: getStableClientId("host", activeRoom.roomId),+ shareGeneration,},{onStatus: (status) => {@@ -819,19 +887,23 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {watchCaptureEnd(captured, generation);try {- const replacements = await Promise.all(- [...peersRef.current.entries()].map(async ([peerId, peer]) => {- try {- return {- peerId,- peer,- replaced: await peer.replaceStream(captured),- };- } catch {- return { peerId, peer, replaced: false };- }- }),- );+ const activeSfuRoute = hostSfuRouteRef.current;+ const [replacements, sfuReplaced] = await Promise.all([+ Promise.all(+ [...peersRef.current.entries()].map(async ([peerId, peer]) => {+ try {+ return {+ peerId,+ peer,+ replaced: await peer.replaceStream(captured),+ };+ } catch {+ return { peerId, peer, replaced: false };+ }+ }),+ ),+ activeSfuRoute?.replaceStream(captured) ?? Promise.resolve(true),+ ]);if (!isCurrentGeneration(generation) ||@@ -848,6 +920,13 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {failedPeerIds.push(peerId);}}+ if (+ !sfuReplaced &&+ activeSfuRoute &&+ hostSfuRouteRef.current === activeSfuRoute+ ) {+ await activeSfuRoute.failActivePublisher();+ }previousStream.getTracks().forEach((track) => track.stop());if (retiringStreamRef.current === previousStream) {diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex aaa903dc..c25be611 100644--- a/src/client/pages/ViewerPage.tsx+++ b/src/client/pages/ViewerPage.tsx@@ -27,6 +27,9 @@ import {QUALITY_PROFILES,type QualityProfileId,} from "../media/quality";+import { relayCapacityMessageForBrowser } from "../media/relay-capability";+import { ViewerMessageAuthority } from "../media/viewer-message-authority";+import { ViewerSfuRoute } from "../media/viewer-sfu-route";import type {PeerSnapshot,SignalConnectionState,@@ -75,6 +78,12 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)childPeerIds: [],};let viewerRelay: ViewerRelay | null = null;+ let viewerSfuRoute: ViewerSfuRoute | null = null;+ let preparedParentPeerId: string | null = null;+ let preparedParentSignals: Array<+ Extract<ServerMessage, { type: "signal" }>+ > = [];+ const messageAuthority = new ViewerMessageAuthority();const signal = new SignalingClient({@@ -90,6 +99,7 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)},onProtocolError: (message) => {if (active) {+ messageAuthority.invalidate();setStatusText(message);}},@@ -97,11 +107,14 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)if (!active) {return;}+ messageAuthority.invalidate();+ clearViewerSfuRoute();clearPeerState();setStatusText(message);},onAccessRequired: () => {if (active) {+ messageAuthority.invalidate();onAuthorizationRequired();}},@@ -109,7 +122,7 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)if (!active) {return;}- void handleMessage(message);+ void handleMessage(message, messageAuthority.tokenFor(message));},},);@@ -147,6 +160,122 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)return viewerRelay;}+ function ensureViewerSfuRoute(): ViewerSfuRoute {+ if (viewerSfuRoute) {+ return viewerSfuRoute;+ }+ let route: ViewerSfuRoute;+ route = new ViewerSfuRoute({+ activatePeer: (assignment) => {+ if (!active || viewerSfuRoute !== route) {+ return;+ }+ applyMediaAssignment({+ parentPeerId:+ assignment.upstream.kind === "peer"+ ? assignment.upstream.peerId+ : null,+ childPeerIds: assignment.childPeerIds,+ });+ if (assignment.upstream.kind === "peer") {+ return drainPreparedParentSignals(assignment.upstream.peerId);+ }+ },+ preparePeer: (assignment) => {+ if (!active || viewerSfuRoute !== route) {+ return;+ }+ prepareParent(+ assignment?.upstream.kind === "peer"+ ? assignment.upstream.peerId+ : null,+ );+ },+ resetMedia: () => {+ if (!active || viewerSfuRoute !== route) {+ return;+ }+ currentAssignment = { parentPeerId: null, childPeerIds: [] };+ clearPeerState();+ viewerRelay?.setChild(null);+ },+ reconcileSfuChildren: (childPeerIds) => {+ if (!active || viewerSfuRoute !== route) {+ return;+ }+ currentAssignment = limitMediaAssignment(+ {+ parentPeerId: currentAssignment.parentPeerId,+ childPeerIds,+ },+ MAX_VIEWER_MEDIA_CHILDREN,+ );+ ensureViewerRelay()?.setChild(+ currentAssignment.childPeerIds[0] ?? null,+ );+ },+ onSfuStream: (nextStream, assignment, initialVideoStream) => {+ if (!active || viewerSfuRoute !== route) {+ return;+ }+ currentAssignment = limitMediaAssignment(+ { parentPeerId: null, childPeerIds: assignment.childPeerIds },+ MAX_VIEWER_MEDIA_CHILDREN,+ );+ const relay = ensureViewerRelay();+ relay?.setChild(currentAssignment.childPeerIds[0] ?? null);+ relay?.setStream(nextStream);+ setRemoteStream(nextStream);+ setStatusText("正在播放");+ if (initialVideoStream) {+ peerRef.current?.dispose();+ peerRef.current = null;+ setPeerSnapshot(null);+ }+ },+ send: (message) =>+ active && viewerSfuRoute === route ? signal.send(message) : false,+ });+ viewerSfuRoute = route;+ return route;+ }++ function clearViewerSfuRoute(): void {+ const route = viewerSfuRoute;+ viewerSfuRoute = null;+ prepareParent(null);+ void route?.disconnect();+ }++ function prepareParent(parentPeerId: string | null): void {+ if (preparedParentPeerId === parentPeerId) {+ return;+ }+ preparedParentPeerId = parentPeerId;+ preparedParentSignals = [];+ }++ async function drainPreparedParentSignals(+ parentPeerId: string,+ ): Promise<void> {+ while (+ active &&+ peerAssisted &&+ preparedParentPeerId === parentPeerId+ ) {+ const message = preparedParentSignals.shift();+ if (!message) {+ preparedParentPeerId = null;+ return;+ }+ const peer = ensurePeer();+ if (!peer) {+ return;+ }+ await peer.acceptSignal(message.fromPeerId, message.payload);+ }+ }+function clearUpstreamState(): void {peerRef.current?.dispose();peerRef.current = null;@@ -232,6 +361,8 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)}}},+ onRecoveryExhausted: (parentPeerId, connectionId) =>+ viewerSfuRoute?.reportPeerFailure(parentPeerId, connectionId) ?? true,},forceRelay,);@@ -239,17 +370,25 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)return peer;}- async function handleMessage(message: ServerMessage): Promise<void> {+ async function handleMessage(+ message: ServerMessage,+ authorityToken: number,+ ): Promise<void> {if (message.type === "authenticated") {const nextPeerAssisted ="mediaMode" in message && message.mediaMode === "peer-assisted";if (!nextPeerAssisted && peerAssisted) {+ clearViewerSfuRoute();clearPeerState();viewerRelay?.dispose();viewerRelay = null;currentAssignment = { parentPeerId: null, childPeerIds: [] };}peerAssisted = nextPeerAssisted;+ const relayCapacity = relayCapacityMessageForBrowser(nextPeerAssisted);+ if (relayCapacity) {+ signal.send(relayCapacity);+ }currentIceConfig = message.iceConfig;currentHostOnline = message.hostOnline;setRelayAvailable(message.iceConfig.relayAvailable);@@ -259,7 +398,16 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)void viewerRelay?.updateProfile(QUALITY_PROFILES[currentQualityProfileId],);- applyMediaAssignment(message.mediaAssignment);+ await ensureViewerSfuRoute().resyncAuthoritative(+ {+ revision: message.routeRevision,+ phase: "active",+ assignment: message.routeAssignment,+ },+ );+ if (!active || !messageAuthority.owns(authorityToken)) {+ return;+ }}if (!message.hostOnline &&@@ -298,8 +446,20 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)}return;}- if (message.type === "media-assignment") {+ if (message.type === "route-update") {+ if (peerAssisted) {+ ensureViewerSfuRoute().accept(message);+ }+ return;+ }+ if (message.type === "sfu-config") {if (peerAssisted) {+ await ensureViewerSfuRoute().acceptConfig(message);+ }+ return;+ }+ if (message.type === "media-assignment") {+ if (peerAssisted && !viewerSfuRoute) {applyMediaAssignment(message.mediaAssignment);}return;@@ -314,6 +474,13 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)return;}if (message.type === "signal") {+ if (+ peerAssisted &&+ preparedParentPeerId === message.fromPeerId+ ) {+ preparedParentSignals.push(message);+ return;+ }if (peerAssisted &¤tAssignment.childPeerIds[0] === message.fromPeerId@@ -367,12 +534,14 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)}if (message.type === "sharing-stopped") {currentHostOnline = false;+ clearViewerSfuRoute();clearPeerState();setHostOnline(false);setStatusText("分享已停止,等待分享者再次开始");return;}if (message.type === "room-closed") {+ clearViewerSfuRoute();clearPeerState();setStatusText(message.reason === "expired" ? "房间已过期" : "分享已结束");signal.stop();@@ -392,6 +561,7 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)"ROOM_FULL",].includes(message.code)) {+ clearViewerSfuRoute();clearPeerState();}setStatusText(message.message);@@ -402,6 +572,10 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)return () => {active = false;signal.stop();+ void viewerSfuRoute?.disconnect();+ viewerSfuRoute = null;+ preparedParentPeerId = null;+ preparedParentSignals = [];peerRef.current?.dispose();peerRef.current = null;viewerRelay?.dispose();diff --git a/src/client/sfu/publisher.ts b/src/client/sfu/publisher.tsnew file mode 100644index 00000000..43cabd7e--- /dev/null+++ b/src/client/sfu/publisher.ts@@ -0,0 +1,481 @@+import type {+ LocalTrackPublication,+ Room,+ Track,+ TrackPublishOptions,+} from "livekit-client";++import {+ configureVideoSender,+ type QualityProfile,+} from "../media/quality";++export interface SfuConnectionConfig {+ url: string;+ token: string;+}++interface PublisherEvents {+ onDisconnected?: () => void;+}++interface PublishedTrack {+ publication: LocalTrackPublication;+ rawTrack: MediaStreamTrack;+}++type LiveKit = typeof import("livekit-client");+type PublisherState =+ | "idle"+ | "connecting"+ | "prepared"+ | "active"+ | "disconnected";++const roomDisconnects = new WeakMap<Room, Promise<void>>();++export class SfuPublisher {+ private room: Room | null = null;+ private sdk: LiveKit | null = null;+ private video: PublishedTrack | null = null;+ private audio: PublishedTrack | null = null;+ private profile: QualityProfile | null = null;+ private state: PublisherState = "idle";+ private generation = 0;+ private operationTail: Promise<void> = Promise.resolve();+ private terminalNotified = false;++ constructor(private readonly events: PublisherEvents = {}) {}++ async connect(config: SfuConnectionConfig): Promise<boolean> {+ if (this.state !== "idle") {+ throw new Error("SFU publisher cannot be connected twice");+ }++ const generation = ++this.generation;+ this.state = "connecting";++ try {+ const sdk = await import("livekit-client");+ if (!this.ownsGeneration(generation)) {+ return false;+ }++ const room = new sdk.Room();+ this.room = room;+ this.sdk = sdk;+ room.on(sdk.RoomEvent.Disconnected, () => {+ if (this.owns(room, generation)) {+ const notify = this.state !== "connecting";+ this.invalidate();+ if (notify) {+ this.notifyTerminalDisconnect();+ }+ }+ });++ await room.connect(config.url, config.token, { autoSubscribe: false });+ if (!this.owns(room, generation)) {+ await safeDisconnect(room);+ return false;+ }++ this.state = "prepared";+ return true;+ } catch (error) {+ if (!this.ownsGeneration(generation)) {+ return false;+ }+ const room = this.invalidate();+ if (room) {+ await safeDisconnect(room);+ }+ throw error;+ }+ }++ activate(stream: MediaStream, profile: QualityProfile): Promise<boolean> {+ const generation = this.generation;+ return this.enqueue(async () => {+ const room = this.requireOwnedRoom(generation, "prepared");+ if (!room) {+ return false;+ }+ const sdk = this.sdk;+ if (!sdk) {+ throw new Error("SFU publisher SDK is unavailable");+ }++ const videoTrack = requiredVideoTrack(stream);+ const audioTrack = stream.getAudioTracks()[0] ?? null;++ try {+ const video = await publishTrack(+ room,+ videoTrack,+ sdk.Track.Source.ScreenShare,+ videoPublishOptions(profile),+ );+ if (!this.owns(room, generation)) {+ return false;+ }++ let audio: PublishedTrack | null = null;+ if (audioTrack) {+ audio = await publishTrack(+ room,+ audioTrack,+ sdk.Track.Source.ScreenShareAudio,+ { dtx: false },+ );+ if (!this.owns(room, generation)) {+ return false;+ }+ }++ this.video = video;+ this.audio = audio;+ this.profile = profile;+ this.state = "active";+ return true;+ } catch (error) {+ if (this.owns(room, generation)) {+ await this.failClosed(room, generation);+ }+ throw error;+ }+ });+ }++ deactivate(): Promise<boolean> {+ const generation = this.generation;+ return this.enqueue(async () => {+ const room = this.requireOwnedRoom(generation, ["prepared", "active"]);+ if (!room) {+ return false;+ }+ if (this.state === "prepared") {+ return true;+ }++ const video = this.video;+ const audio = this.audio;+ try {+ if (audio) {+ await unpublishTrack(room, audio);+ if (!this.owns(room, generation)) {+ return false;+ }+ }+ if (video) {+ await unpublishTrack(room, video);+ if (!this.owns(room, generation)) {+ return false;+ }+ }+ } catch (error) {+ if (this.owns(room, generation)) {+ await this.failClosed(room, generation);+ }+ throw error;+ }++ this.video = null;+ this.audio = null;+ this.profile = null;+ this.state = "prepared";+ return true;+ });+ }++ replaceStream(stream: MediaStream): Promise<boolean> {+ const generation = this.generation;+ return this.enqueue(async () => {+ const room = this.requireOwnedRoom(generation, "active");+ if (!room) {+ return false;+ }+ const sdk = this.sdk;+ const previousVideo = this.video;+ if (!sdk || !previousVideo) {+ throw new Error("SFU publisher has no active video publication");+ }++ const nextVideoTrack = requiredVideoTrack(stream);+ const nextAudioTrack = stream.getAudioTracks()[0] ?? null;+ const previousAudio = this.audio;+ let videoReplaceAttempted = false;+ let audioReplaceAttempted = false;++ try {+ videoReplaceAttempted = true;+ await replacePublishedTrack(previousVideo, nextVideoTrack);+ if (!this.owns(room, generation)) {+ return false;+ }++ if (previousAudio && nextAudioTrack) {+ audioReplaceAttempted = true;+ await replacePublishedTrack(previousAudio, nextAudioTrack);+ if (!this.owns(room, generation)) {+ return false;+ }+ } else if (previousAudio) {+ await unpublishTrack(room, previousAudio);+ if (!this.owns(room, generation)) {+ return false;+ }+ this.audio = null;+ } else if (nextAudioTrack) {+ const nextAudio = await publishTrack(+ room,+ nextAudioTrack,+ sdk.Track.Source.ScreenShareAudio,+ { dtx: false },+ );+ if (!this.owns(room, generation)) {+ return false;+ }+ this.audio = nextAudio;+ }++ previousVideo.rawTrack = nextVideoTrack;+ if (previousAudio && nextAudioTrack) {+ previousAudio.rawTrack = nextAudioTrack;+ }+ return true;+ } catch (error) {+ if (!this.owns(room, generation)) {+ return false;+ }++ // A rejected publish/unpublish may have changed server state without+ // returning enough ownership information to undo it safely.+ if (+ (previousAudio === null && nextAudioTrack !== null) ||+ (previousAudio !== null && nextAudioTrack === null)+ ) {+ await this.failClosed(room, generation);+ throw error;+ }++ try {+ if (audioReplaceAttempted && previousAudio) {+ await replacePublishedTrack(previousAudio, previousAudio.rawTrack);+ if (!this.owns(room, generation)) {+ return false;+ }+ }+ if (videoReplaceAttempted) {+ await replacePublishedTrack(previousVideo, previousVideo.rawTrack);+ if (!this.owns(room, generation)) {+ return false;+ }+ }+ return false;+ } catch (rollbackError) {+ if (this.owns(room, generation)) {+ await this.failClosed(room, generation);+ }+ throw rollbackError;+ }+ }+ });+ }++ updateProfile(profile: QualityProfile): Promise<boolean> {+ const generation = this.generation;+ return this.enqueue(async () => {+ const room = this.requireOwnedRoom(generation, "active");+ if (!room) {+ return false;+ }+ const video = this.video;+ const previousProfile = this.profile;+ if (!video || !previousProfile) {+ throw new Error("SFU publisher has no active video publication");+ }++ try {+ await configurePublishedVideo(video, profile);+ if (!this.owns(room, generation)) {+ return false;+ }+ this.profile = profile;+ return true;+ } catch (error) {+ if (!this.owns(room, generation)) {+ return false;+ }+ try {+ await configurePublishedVideo(video, previousProfile);+ if (!this.owns(room, generation)) {+ return false;+ }+ return false;+ } catch (rollbackError) {+ if (this.owns(room, generation)) {+ await this.failClosed(room, generation);+ }+ throw rollbackError;+ }+ }+ });+ }++ async disconnect(): Promise<void> {+ const room = this.invalidate();+ if (room) {+ await safeDisconnect(room);+ }+ }++ private enqueue<T>(operation: () => Promise<T>): Promise<T> {+ const result = this.operationTail.then(operation, operation);+ this.operationTail = result.then(+ () => undefined,+ () => undefined,+ );+ return result;+ }++ private requireOwnedRoom(+ generation: number,+ expectedState: PublisherState | PublisherState[],+ ): Room | null {+ if (!this.ownsGeneration(generation)) {+ return null;+ }+ const expected = Array.isArray(expectedState)+ ? expectedState+ : [expectedState];+ if (!expected.includes(this.state)) {+ throw new Error(`SFU publisher is ${this.state}, expected ${expected.join(" or ")}`);+ }+ if (!this.room) {+ throw new Error("SFU publisher room is unavailable");+ }+ return this.room;+ }++ private ownsGeneration(generation: number): boolean {+ return this.generation === generation && this.state !== "disconnected";+ }++ private owns(room: Room, generation: number): boolean {+ return this.room === room && this.ownsGeneration(generation);+ }++ private invalidate(): Room | null {+ if (this.state === "disconnected") {+ return null;+ }+ ++this.generation;+ this.state = "disconnected";+ const room = this.room;+ this.room = null;+ this.sdk = null;+ this.video = null;+ this.audio = null;+ this.profile = null;+ return room;+ }++ private async failClosed(room: Room, generation: number): Promise<void> {+ if (!this.owns(room, generation)) {+ return;+ }+ this.invalidate();+ await safeDisconnect(room);+ this.notifyTerminalDisconnect();+ }++ private notifyTerminalDisconnect(): void {+ if (this.terminalNotified) {+ return;+ }+ this.terminalNotified = true;+ this.events.onDisconnected?.();+ }+}++async function publishTrack(+ room: Room,+ rawTrack: MediaStreamTrack,+ source: Track.Source,+ options: TrackPublishOptions,+): Promise<PublishedTrack> {+ const publication = await room.localParticipant.publishTrack(rawTrack, {+ source,+ ...options,+ });+ if (!publication.track) {+ throw new Error("SFU did not retain the published track");+ }+ return { publication, rawTrack };+}++async function replacePublishedTrack(+ published: PublishedTrack,+ nextTrack: MediaStreamTrack,+): Promise<void> {+ const localTrack = published.publication.track;+ if (!localTrack) {+ throw new Error("SFU publication has no local track");+ }+ await localTrack.replaceTrack(nextTrack);+}++async function unpublishTrack(room: Room, published: PublishedTrack): Promise<void> {+ const localTrack = published.publication.track;+ if (!localTrack) {+ throw new Error("SFU publication has no local track");+ }+ await room.localParticipant.unpublishTrack(localTrack, false);+}++async function configurePublishedVideo(+ published: PublishedTrack,+ profile: QualityProfile,+): Promise<void> {+ const videoTrack = published.publication.videoTrack;+ const sender = videoTrack?.sender;+ if (!sender) {+ throw new Error("SFU video publication has no RTP sender");+ }+ await configureVideoSender(sender, profile);+ videoTrack.publishOptions = {+ ...videoTrack.publishOptions,+ ...videoPublishOptions(profile),+ };+}++function videoPublishOptions(profile: QualityProfile): TrackPublishOptions {+ return {+ simulcast: false,+ screenShareEncoding: {+ maxBitrate: profile.maxBitrate,+ maxFramerate: profile.frameRate,+ },+ degradationPreference: "balanced",+ };+}++async function safeDisconnect(room: Room): Promise<void> {+ const existing = roomDisconnects.get(room);+ if (existing) {+ await existing;+ return;+ }+ const disconnecting = room.disconnect(false).catch(() => undefined);+ roomDisconnects.set(room, disconnecting);+ await disconnecting;+}++function requiredVideoTrack(stream: MediaStream): MediaStreamTrack {+ const track = stream.getVideoTracks()[0];+ if (!track) {+ throw new Error("屏幕共享没有视频轨道");+ }+ return track;+}diff --git a/src/client/sfu/subscriber.ts b/src/client/sfu/subscriber.tsnew file mode 100644index 00000000..06066da5--- /dev/null+++ b/src/client/sfu/subscriber.ts@@ -0,0 +1,355 @@+import type {+ RemoteParticipant,+ RemoteTrack,+ RemoteTrackPublication,+ Room,+ Track,+} from "livekit-client";++import type { SfuConnectionConfig } from "./publisher";++interface SubscriberEvents {+ onStream: (stream: MediaStream | null) => void;+ onDisconnected?: () => void;+}++interface SubscribedTrack {+ sid: string;+ track: MediaStreamTrack;+}++type SubscriberState =+ | "idle"+ | "connecting"+ | "prepared"+ | "active"+ | "disconnected";+type LiveKit = typeof import("livekit-client");++const HOST_IDENTITY = "host";+const roomDisconnects = new WeakMap<Room, Promise<void>>();++export class SfuSubscriber {+ private room: Room | null = null;+ private sdk: LiveKit | null = null;+ private video: SubscribedTrack | null = null;+ private audio: SubscribedTrack | null = null;+ private readonly desiredTrackSids = new Set<string>();+ private state: SubscriberState = "idle";+ private generation = 0;+ private terminalNotified = false;++ constructor(private readonly events: SubscriberEvents) {}++ async connect(config: SfuConnectionConfig): Promise<boolean> {+ if (this.state !== "idle") {+ throw new Error("SFU subscriber cannot be connected twice");+ }++ const generation = ++this.generation;+ this.state = "connecting";++ try {+ const sdk = await import("livekit-client");+ if (!this.ownsGeneration(generation)) {+ return false;+ }++ const room = new sdk.Room();+ this.room = room;+ this.sdk = sdk;+ this.bindRoomEvents(room, sdk, generation);++ await room.connect(config.url, config.token, { autoSubscribe: false });+ if (!this.owns(room, generation)) {+ await safeDisconnect(room);+ return false;+ }++ this.state = "prepared";+ return true;+ } catch (error) {+ if (!this.ownsGeneration(generation)) {+ return false;+ }+ const room = this.invalidate(false);+ if (room) {+ await safeDisconnect(room);+ }+ throw error;+ }+ }++ activate(): boolean {+ if (this.state === "active") {+ return true;+ }+ if (this.state !== "prepared" || !this.room || !this.sdk) {+ throw new Error(`SFU subscriber is ${this.state}, expected prepared`);+ }++ const room = this.room;+ const generation = this.generation;+ this.state = "active";+ try {+ const host = room.remoteParticipants.get(HOST_IDENTITY);+ if (host) {+ for (const publication of host.trackPublications.values()) {+ this.subscribeIfAllowed(publication, host, this.sdk.Track);+ }+ }+ return true;+ } catch (error) {+ if (this.owns(room, generation)) {+ try {+ this.rollbackSubscriptions(room);+ this.state = "prepared";+ this.clearMedia(true);+ } catch {+ void this.failClosed(room, generation);+ }+ }+ throw error;+ }+ }++ deactivate(): boolean {+ if (this.state === "prepared") {+ return true;+ }+ if (this.state !== "active" || !this.room) {+ if (this.state === "disconnected") {+ return false;+ }+ throw new Error(`SFU subscriber is ${this.state}, expected active`);+ }++ const room = this.room;+ try {+ this.rollbackSubscriptions(room);+ } catch (error) {+ void this.failClosed(room, this.generation);+ throw error;+ }+ this.state = "prepared";+ this.clearMedia(true);+ return true;+ }++ async disconnect(): Promise<void> {+ const room = this.invalidate(true);+ if (room) {+ await safeDisconnect(room);+ }+ }++ private bindRoomEvents(+ room: Room,+ sdk: LiveKit,+ generation: number,+ ): void {+ room.on(+ sdk.RoomEvent.TrackPublished,+ (publication: RemoteTrackPublication, participant: RemoteParticipant) => {+ if (this.state !== "active" || !this.owns(room, generation)) {+ return;+ }+ try {+ this.subscribeIfAllowed(publication, participant, sdk.Track);+ } catch {+ void this.failClosed(room, generation);+ }+ },+ );+ room.on(+ sdk.RoomEvent.TrackSubscribed,+ (+ track: RemoteTrack,+ publication: RemoteTrackPublication,+ participant: RemoteParticipant,+ ) => {+ if (+ this.state !== "active" ||+ !this.owns(room, generation) ||+ participant.identity !== HOST_IDENTITY ||+ !this.desiredTrackSids.has(publication.trackSid)+ ) {+ return;+ }+ this.addTrack(+ publication.trackSid,+ publication.source,+ track.mediaStreamTrack,+ sdk.Track,+ );+ },+ );+ room.on(+ sdk.RoomEvent.TrackUnsubscribed,+ (+ _track: RemoteTrack,+ publication: RemoteTrackPublication,+ participant: RemoteParticipant,+ ) => {+ if (this.owns(room, generation) && participant.identity === HOST_IDENTITY) {+ this.removeTrack(publication.trackSid);+ }+ },+ );+ room.on(+ sdk.RoomEvent.TrackUnpublished,+ (publication: RemoteTrackPublication, participant: RemoteParticipant) => {+ if (this.owns(room, generation) && participant.identity === HOST_IDENTITY) {+ this.desiredTrackSids.delete(publication.trackSid);+ this.removeTrack(publication.trackSid);+ }+ },+ );+ room.on(+ sdk.RoomEvent.ParticipantDisconnected,+ (participant: RemoteParticipant) => {+ if (this.owns(room, generation) && participant.identity === HOST_IDENTITY) {+ this.desiredTrackSids.clear();+ this.clearMedia(true);+ }+ },+ );+ room.on(sdk.RoomEvent.Disconnected, () => {+ if (this.owns(room, generation)) {+ const notify = this.state !== "connecting";+ this.invalidate(true);+ if (notify) {+ this.notifyTerminalDisconnect();+ }+ }+ });+ }++ private subscribeIfAllowed(+ publication: RemoteTrackPublication,+ participant: RemoteParticipant,+ trackType: typeof Track,+ ): void {+ if (+ participant.identity !== HOST_IDENTITY ||+ !isScreenSource(publication.source, trackType)+ ) {+ return;+ }+ this.desiredTrackSids.add(publication.trackSid);+ publication.setSubscribed(true);+ }++ private rollbackSubscriptions(room: Room): void {+ const host = room.remoteParticipants.get(HOST_IDENTITY);+ for (const publication of host?.trackPublications.values() ?? []) {+ if (this.desiredTrackSids.has(publication.trackSid)) {+ publication.setSubscribed(false);+ }+ }+ this.desiredTrackSids.clear();+ }++ private addTrack(+ sid: string,+ source: Track.Source,+ track: MediaStreamTrack,+ trackType: typeof Track,+ ): void {+ if (source === trackType.Source.ScreenShare) {+ this.video = { sid, track };+ } else if (source === trackType.Source.ScreenShareAudio) {+ this.audio = { sid, track };+ } else {+ return;+ }+ this.emitStream();+ }++ private removeTrack(sid: string): void {+ if (this.video?.sid === sid) {+ this.video = null;+ }+ if (this.audio?.sid === sid) {+ this.audio = null;+ }+ this.emitStream();+ }++ private emitStream(): void {+ if (!this.video) {+ return;+ }+ const tracks = [this.video.track];+ if (this.audio) {+ tracks.push(this.audio.track);+ }+ this.events.onStream(new MediaStream(tracks));+ }++ private clearMedia(notify: boolean): void {+ const hadVideo = this.video !== null;+ this.video = null;+ this.audio = null;+ if (notify && hadVideo) {+ this.events.onStream(null);+ }+ }++ private ownsGeneration(generation: number): boolean {+ return this.generation === generation && this.state !== "disconnected";+ }++ private owns(room: Room, generation: number): boolean {+ return this.room === room && this.ownsGeneration(generation);+ }++ private invalidate(notifyStream: boolean): Room | null {+ if (this.state === "disconnected") {+ return null;+ }+ ++this.generation;+ this.state = "disconnected";+ const room = this.room;+ this.room = null;+ this.sdk = null;+ this.desiredTrackSids.clear();+ this.clearMedia(notifyStream);+ return room;+ }++ private async failClosed(room: Room, generation: number): Promise<void> {+ if (!this.owns(room, generation)) {+ return;+ }+ this.invalidate(true);+ await safeDisconnect(room);+ this.notifyTerminalDisconnect();+ }++ private notifyTerminalDisconnect(): void {+ if (this.terminalNotified) {+ return;+ }+ this.terminalNotified = true;+ this.events.onDisconnected?.();+ }+}++function isScreenSource(source: Track.Source, trackType: typeof Track): boolean {+ return (+ source === trackType.Source.ScreenShare ||+ source === trackType.Source.ScreenShareAudio+ );+}++async function safeDisconnect(room: Room): Promise<void> {+ const existing = roomDisconnects.get(room);+ if (existing) {+ await existing;+ return;+ }+ const disconnecting = room.disconnect(false).catch(() => undefined);+ roomDisconnects.set(room, disconnecting);+ await disconnecting;+}diff --git a/src/client/webrtc/viewer-peer.ts b/src/client/webrtc/viewer-peer.tsindex b24a34dc..54b2d814 100644--- a/src/client/webrtc/viewer-peer.ts+++ b/src/client/webrtc/viewer-peer.ts@@ -10,6 +10,8 @@ import {} from "./stats";const MAX_PENDING_CANDIDATES = 64;+const MAX_AUTOMATIC_RECOVERY_REQUESTS = 2;+const AUTOMATIC_RECOVERY_TIMEOUT_MS = 3_000;type SignalCandidate = Extract<SignalPayload,{ kind: "candidate" }@@ -24,6 +26,10 @@ interface ViewerPeerEvents {) => boolean;onStream: (stream: MediaStream) => void;onUpdate: (snapshot: PeerSnapshot) => void;+ onRecoveryExhausted?: (+ parentPeerId: string,+ connectionId: string,+ ) => boolean;}export class ViewerPeer {@@ -39,8 +45,10 @@ export class ViewerPeer {private statsTimer: number | null = null;private statsInFlightConnection: RTCPeerConnection | null = null;private disconnectTimer: number | null = null;- private restartRequested = false;+ private recoveryTimer: number | null = null;private offerRecoveryAttempts = 0;+ private automaticRecoveryRequests = 0;+ private recoveryExhaustedReported = false;private disposed = false;private currentIceConfig: IceConfig;private snapshot: PeerSnapshot | null = null;@@ -101,15 +109,16 @@ export class ViewerPeer {if (!connection.localDescription) {throw new Error("Local description was not created");}- this.events.sendSignal(parentPeerId, {+ if (!this.events.sendSignal(parentPeerId, {kind: "description",connectionId,description: {type: "answer",sdp: connection.localDescription.sdp,},- });- this.restartRequested = false;+ })) {+ throw new Error("Signaling is unavailable while sending the answer");+ }this.offerRecoveryAttempts = 0;} else if (this.connection &&@@ -147,7 +156,10 @@ export class ViewerPeer {)) {this.offerRecoveryAttempts += 1;- this.restartRequested = true;+ this.automaticRecoveryRequests = MAX_AUTOMATIC_RECOVERY_REQUESTS;+ this.scheduleRecoveryDeadline();+ } else if (payload.kind === "description") {+ this.reportRecoveryExhausted();}}}@@ -177,7 +189,11 @@ export class ViewerPeer {false,);if (sent) {- this.restartRequested = true;+ this.automaticRecoveryRequests = Math.max(+ this.automaticRecoveryRequests,+ 1,+ );+ this.scheduleRecoveryDeadline();}return sent;}@@ -199,6 +215,7 @@ export class ViewerPeer {return;}this.disposed = true;+ this.clearRecoveryTimer();this.disposeConnection();this.pendingByConnection.clear();}@@ -209,12 +226,12 @@ export class ViewerPeer {this.disposeConnection();if (parentChanged) {this.offerRecoveryAttempts = 0;+ this.resetAutomaticRecovery();}this.parentPeerId = parentPeerId;this.connectionId = connectionId;this.remoteStream = new MediaStream();this.statsAccumulator = createStatsAccumulator();- this.restartRequested = false;const connection = new RTCPeerConnection({iceServers: this.currentIceConfig.iceServers,@@ -280,27 +297,92 @@ export class ViewerPeer {private handleConnectionState(state: RTCPeerConnectionState): void {if (state === "connected") {- this.restartRequested = false;this.clearDisconnectTimer();+ this.resetAutomaticRecovery();return;}if (state === "failed") {this.clearDisconnectTimer();- if (!this.restartRequested) {- this.requestRecovery();- }+ this.attemptAutomaticRecovery();return;}if (state === "disconnected" && this.disconnectTimer === null) {this.disconnectTimer = window.setTimeout(() => {this.disconnectTimer = null;if (this.connection?.connectionState === "disconnected") {- this.requestRecovery();+ this.attemptAutomaticRecovery();}}, 3_000);}}+ private attemptAutomaticRecovery(): void {+ if (+ this.disposed ||+ this.recoveryTimer !== null ||+ this.recoveryExhaustedReported ||+ this.connection?.connectionState === "connected" ||+ !this.connectionId ||+ !this.parentPeerId+ ) {+ return;+ }+ if (this.automaticRecoveryRequests >= MAX_AUTOMATIC_RECOVERY_REQUESTS) {+ this.reportRecoveryExhausted();+ return;+ }+ const rebuild = this.automaticRecoveryRequests > 0;+ if (+ !this.events.sendRestartRequest(+ this.parentPeerId,+ this.connectionId,+ rebuild,+ )+ ) {+ this.reportRecoveryExhausted();+ return;+ }+ this.automaticRecoveryRequests += 1;+ this.scheduleRecoveryDeadline();+ }++ private scheduleRecoveryDeadline(): void {+ this.clearRecoveryTimer();+ this.recoveryTimer = window.setTimeout(() => {+ this.recoveryTimer = null;+ if (this.connection?.connectionState !== "connected") {+ this.attemptAutomaticRecovery();+ }+ }, AUTOMATIC_RECOVERY_TIMEOUT_MS);+ }++ private reportRecoveryExhausted(): void {+ if (+ this.recoveryExhaustedReported ||+ !this.parentPeerId ||+ !this.connectionId+ ) {+ return;+ }+ this.clearRecoveryTimer();+ const reported =+ this.events.onRecoveryExhausted?.(+ this.parentPeerId,+ this.connectionId,+ ) ?? true;+ if (reported) {+ this.recoveryExhaustedReported = true;+ } else {+ this.scheduleRecoveryDeadline();+ }+ }++ private resetAutomaticRecovery(): void {+ this.clearRecoveryTimer();+ this.automaticRecoveryRequests = 0;+ this.recoveryExhaustedReported = false;+ }+private queueCandidate(connectionId: string,candidate: SignalCandidate,@@ -416,6 +498,13 @@ export class ViewerPeer {}}+ private clearRecoveryTimer(): void {+ if (this.recoveryTimer !== null) {+ window.clearTimeout(this.recoveryTimer);+ this.recoveryTimer = null;+ }+ }+private disposeConnection(): void {this.clearDisconnectTimer();if (this.statsTimer !== null) {diff --git a/src/server/app.ts b/src/server/app.tsindex fc589c88..d5b87f96 100644--- a/src/server/app.ts+++ b/src/server/app.ts@@ -7,6 +7,7 @@ import type { ViteDevServer } from "vite";import type { CreateRoomResponse } from "../shared/protocol.js";import { AccessSession } from "./access-session.js";import { loadConfig, type ServerConfig } from "./config.js";+import type { SfuTokenIssuer } from "./livekit-token.js";import { RoomDatabase } from "./room-database.js";import { RoomStore, RoomStoreError } from "./room-store.js";import { SignalingServer } from "./signaling.js";@@ -24,6 +25,7 @@ export interface CreateServerOptions {maxSignalConnections?: number;maxUnauthenticatedSignalConnections?: number;accessSessionTtlSeconds?: number;+ sfuTokenIssuer?: SfuTokenIssuer;}export interface ScreenerServer {@@ -40,6 +42,21 @@ export async function createScreenerServer(): Promise<ScreenerServer> {const config = options.config ?? loadConfig();const now = options.now ?? Date.now;+ const livekitFallback = config.livekitFallback;+ const sfuFallback = livekitFallback+ ? {+ url: livekitFallback.url,+ tokenIssuer:+ options.sfuTokenIssuer ??+ new (await import("./livekit-token.js")).LiveKitTokenIssuer({+ apiKey: livekitFallback.apiKey,+ apiSecret: livekitFallback.apiSecret,+ maxViewersPerRoom: config.maxViewersPerRoom,+ maxSfuRootsPerRoom: livekitFallback.maxSfuRootsPerRoom,+ }),+ maxRoots: livekitFallback.maxSfuRootsPerRoom,+ }+ : undefined;const roomStore =options.roomStore ??new RoomStore({@@ -94,6 +111,7 @@ export async function createScreenerServer(server: httpServer,roomStore,peerAssistedMedia: config.peerAssistedMedia,+ ...(sfuFallback ? { sfuFallback } : {}),ice: iceOptions,allowedOrigins: config.allowedOrigins,authorizeUpgrade: (request) =>diff --git a/src/server/config.ts b/src/server/config.tsindex 48ba5034..4ea1e935 100644--- a/src/server/config.ts+++ b/src/server/config.ts@@ -5,10 +5,20 @@ export type RuntimeEnvironment = "development" | "test" | "production";const MAX_TURN_CREDENTIAL_TTL_SECONDS = 3_600;const MAX_ACCESS_PASSWORD_BYTES = 128;const MIN_TURN_SECRET_BYTES = 32;+const MIN_LIVEKIT_API_SECRET_BYTES = 32;const MAX_PEER_ASSISTED_VIEWERS = 8;const DEFAULT_MAX_VIEWERS_PER_ROOM = 8;+const DEFAULT_MAX_SFU_ROOTS_PER_ROOM = 2;+const MAX_SFU_ROOTS_PER_ROOM = 2;const VISIBLE_ASCII_PATTERN = /^[\x21-\x7e]+$/;+export interface LiveKitFallbackConfig {+ url: string;+ apiKey: string;+ apiSecret: string;+ maxSfuRootsPerRoom: number;+}+export interface ServerConfig {nodeEnv: RuntimeEnvironment;port: number;@@ -21,6 +31,7 @@ export interface ServerConfig {maxRooms: number;maxViewersPerRoom: number;peerAssistedMedia: boolean;+ livekitFallback?: LiveKitFallbackConfig;stunUrls: readonly string[];turnUrls: readonly string[];turnSharedSecret?: string;@@ -88,6 +99,65 @@ function parseEnvironment(value: string | undefined): RuntimeEnvironment {return environment;}+function parseLiveKitFallback(+ environment: NodeJS.ProcessEnv,+ nodeEnv: RuntimeEnvironment,+): LiveKitFallbackConfig | undefined {+ const url = environment.LIVEKIT_URL?.trim() || undefined;+ const apiKey = environment.LIVEKIT_API_KEY?.trim() || undefined;+ const apiSecret = environment.LIVEKIT_API_SECRET?.trim() || undefined;+ const configuredValues = [url, apiKey, apiSecret].filter(Boolean).length;++ if (configuredValues === 0) {+ return undefined;+ }+ if (configuredValues !== 3) {+ throw new Error(+ "LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET must be configured together",+ );+ }+ if (Buffer.byteLength(apiSecret!) < MIN_LIVEKIT_API_SECRET_BYTES) {+ throw new Error("LIVEKIT_API_SECRET must contain at least 32 bytes");+ }++ let parsedUrl: URL;+ try {+ parsedUrl = new URL(url!);+ } catch {+ throw new Error("LIVEKIT_URL must be a valid ws or wss origin");+ }+ if (parsedUrl.protocol !== "ws:" && parsedUrl.protocol !== "wss:") {+ throw new Error("LIVEKIT_URL must use ws or wss");+ }+ if (+ parsedUrl.username ||+ parsedUrl.password ||+ parsedUrl.pathname !== "/" ||+ parsedUrl.search ||+ parsedUrl.hash+ ) {+ throw new Error(+ "LIVEKIT_URL must be an origin without credentials, path, query, or fragment",+ );+ }+ if (nodeEnv === "production" && parsedUrl.protocol !== "wss:") {+ throw new Error("LIVEKIT_URL must use wss in production");+ }++ return {+ url: parsedUrl.origin,+ apiKey: apiKey!,+ apiSecret: apiSecret!,+ maxSfuRootsPerRoom: parseBoundedInteger(+ environment.MAX_SFU_ROOTS_PER_ROOM,+ DEFAULT_MAX_SFU_ROOTS_PER_ROOM,+ "MAX_SFU_ROOTS_PER_ROOM",+ 1,+ MAX_SFU_ROOTS_PER_ROOM,+ ),+ };+}+function parseUrlList(value: string | undefined, name: string): string[] {if (!value?.trim()) {return [];@@ -287,12 +357,27 @@ export function loadConfig(false,"PEER_ASSISTED_MEDIA",);+ const livekitFallback = parseLiveKitFallback(environment, nodeEnv);+ if (livekitFallback && !peerAssistedMedia) {+ throw new Error("LiveKit fallback requires PEER_ASSISTED_MEDIA=true");+ }if ((turnUrls.length > 0) !== Boolean(turnSharedSecret)) {throw new Error("TURN_URLS and TURN_SHARED_SECRET must either both be configured or both be absent",);}+ const configuredSecrets = [+ accessPassword,+ turnSharedSecret,+ livekitFallback?.apiKey,+ livekitFallback?.apiSecret,+ ].filter((secret): secret is string => secret !== undefined);+ if (new Set(configuredSecrets).size !== configuredSecrets.length) {+ throw new Error(+ "ACCESS_PASSWORD, TURN_SHARED_SECRET, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET must use independent values",+ );+ }if (accessPassword &&(!VISIBLE_ASCII_PATTERN.test(accessPassword) ||@@ -347,6 +432,7 @@ export function loadConfig(maxRooms: parsePositiveInteger(environment.MAX_ROOMS, 1_000, "MAX_ROOMS"),maxViewersPerRoom,peerAssistedMedia,+ livekitFallback,stunUrls,turnUrls,turnSharedSecret,diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsnew file mode 100644index 00000000..e6fe6521--- /dev/null+++ b/src/server/hybrid-media-router.ts@@ -0,0 +1,1605 @@+import { randomBytes } from "node:crypto";++import {+ MAX_MEDIA_ROUTE_REVISION,+ type ClientMessage,+ type MediaAssignment,+ type ParticipantRouteAssignment,+ type RelayDownstreamEdges,+ type Role,+ type ServerMessage,+} from "../shared/protocol.js";+import type { SfuTokenIssuer } from "./livekit-token.js";+import {+ MediaRouteController,+ type RoomMediaRoute,+} from "./media-route-controller.js";+import {+ MAX_PEER_RELAY_DEPTH,+ PeerRelayTopology,+ type MediaAssignmentChange,+} from "./peer-relay-topology.js";+import type { RoomStore } from "./room-store.js";++type ErrorCode = Extract<ServerMessage, { type: "error" }>["code"];++const DEFAULT_SFU_PREPARE_TIMEOUT_MS = 5_000;+interface PendingRoutePreparation {+ revision: number;+ intentPeerId: string;+ expectedSessionIds: ReadonlyMap<string, string>;+ grantsIssued: boolean;+ timer: NodeJS.Timeout;+}++interface ViewerRouteIntent {+ failedParentPeerId: string | null;+ sessionId: string;+ sfuAttempts: number;+ unavailableReported: boolean;+}++type SfuPrepareResult = "started" | "busy" | "unavailable";++export interface SfuFallbackOptions {+ url: string;+ tokenIssuer: SfuTokenIssuer;+ maxRoots: number;+ prepareTimeoutMs?: number;+}++export interface HybridMediaRouterOptions {+ roomStore: RoomStore;+ sfuFallback?: SfuFallbackOptions;+ sendToSession: (sessionId: string, message: ServerMessage) => void;+ getConnectionId: (roomId: string, viewerPeerId: string) => string | undefined;+ deleteConnectionId: (roomId: string, viewerPeerId: string) => void;+}++export interface HybridAuthenticationState {+ routeRevision: number;+ routeAssignment: ParticipantRouteAssignment;+ mediaAssignment: MediaAssignment;+ assignmentChanges: readonly MediaAssignmentChange[];+ activeRoute?: RoomMediaRoute;+}++export interface AuthenticatedRouteParticipant {+ roomId: string;+ role: Role;+ peerId: string;+ sessionId: string;+}++export class HybridMediaRouter {+ private readonly peerRelayTopology = new PeerRelayTopology();+ private readonly mediaRouteControllers = new Map<+ string,+ MediaRouteController+ >();+ private readonly pendingRoutePreparations = new Map<+ string,+ PendingRoutePreparation+ >();+ private readonly failedParentPeerIdsByViewer = new Map<+ string,+ Set<string>+ >();+ private readonly viewerRouteIntentsByRoom = new Map<+ string,+ Map<string, ViewerRouteIntent>+ >();+ private readonly consumedSfuRefreshesByRoom = new Map<string, Set<string>>();+ private readonly relayCapacitySessionsByRoom = new Map<+ string,+ Map<string, string>+ >();+ private readonly sfuDisabledRoomIds = new Set<string>();++ constructor(private readonly options: HybridMediaRouterOptions) {+ const fallback = options.sfuFallback;+ if (!fallback) {+ return;+ }+ if (+ !Number.isSafeInteger(fallback.maxRoots) ||+ fallback.maxRoots < 1 ||+ fallback.maxRoots > Math.min(2, options.roomStore.maxViewersPerRoom) ||+ (fallback.prepareTimeoutMs !== undefined &&+ (!Number.isSafeInteger(fallback.prepareTimeoutMs) ||+ fallback.prepareTimeoutMs <= 0))+ ) {+ throw new Error("SFU fallback limits are invalid");+ }+ new URL(fallback.url);+ }++ close(): void {+ for (const pending of this.pendingRoutePreparations.values()) {+ clearTimeout(pending.timer);+ }+ this.pendingRoutePreparations.clear();+ this.mediaRouteControllers.clear();+ this.failedParentPeerIdsByViewer.clear();+ this.viewerRouteIntentsByRoom.clear();+ this.consumedSfuRefreshesByRoom.clear();+ this.relayCapacitySessionsByRoom.clear();+ this.sfuDisabledRoomIds.clear();+ }++ connectParticipant(input: AuthenticatedRouteParticipant): HybridAuthenticationState {+ this.clearSfuRefreshesForPeer(input.roomId, input.peerId);+ if (input.role === "viewer") {+ this.failedParentPeerIdsByViewer.delete(+ viewerConnectionKey(input.roomId, input.peerId),+ );+ this.viewerRouteIntentsByRoom.get(input.roomId)?.delete(input.peerId);+ this.relayCapacitySessionsByRoom.get(input.roomId)?.delete(input.peerId);+ }+ this.abortPendingRouteForTopologyChange(input.roomId, input.peerId);+ const assignmentChanges =+ input.role === "host"+ ? this.peerRelayTopology.setHost(+ input.roomId,+ input.peerId,+ this.connectedPeerIds(input.roomId),+ )+ : this.peerRelayTopology.addViewer(+ input.roomId,+ input.peerId,+ this.connectedPeerIds(input.roomId),+ );+ this.clearChangedConnectionIds(input.roomId, assignmentChanges);+ const controller = this.reconcileMediaRoute(input.roomId, input.peerId);+ const activeRoute = controller?.getActiveRoute();+ const routeAssignment =+ activeRoute?.assignments.get(input.peerId) ??+ participantRouteFromMediaAssignment(+ this.peerRelayTopology.getAssignment(input.roomId, input.peerId),+ );+ if (!routeAssignment) {+ throw new Error("Peer relay topology has no participant assignment");+ }+ return {+ routeRevision: activeRoute?.revision ?? 0,+ routeAssignment,+ mediaAssignment: mediaAssignmentFromParticipantRoute(routeAssignment),+ assignmentChanges,+ activeRoute,+ };+ }++ completeAuthentication(+ participant: AuthenticatedRouteParticipant,+ state: HybridAuthenticationState,+ ): void {+ const activeParentPeerId =+ state.routeAssignment.upstream.kind === "peer"+ ? state.routeAssignment.upstream.peerId+ : undefined;+ this.sendMediaAssignmentChanges(+ participant.roomId,+ state.assignmentChanges,+ participant.peerId,+ );+ if (+ participant.role === "viewer" &&+ activeParentPeerId &&+ !state.assignmentChanges.some(+ ({ peerId }) => peerId === activeParentPeerId,+ )+ ) {+ this.sendCurrentParentAssignment(participant.roomId, participant.peerId);+ }+ if (state.activeRoute?.sfu.publicationGeneration) {+ void this.sendFreshSfuConfig(+ participant.roomId,+ participant.peerId,+ participant.sessionId,+ state.activeRoute.revision,+ );+ }+ this.drainViewerRouteIntents(participant.roomId);+ }++ isActivePeerParentOf(+ roomId: string,+ parentPeerId: string,+ childPeerId: string,+ ): boolean {+ const controller = this.mediaRouteControllers.get(roomId);+ if (!controller) {+ return false;+ }+ const assignments = controller.getActiveRoute().assignments;+ const child = assignments.get(childPeerId);+ return (+ child?.upstream.kind === "peer" &&+ child.upstream.peerId === parentPeerId &&+ assignments.get(parentPeerId)?.childPeerIds.includes(childPeerId) === true+ );+ }++ setViewerRelayCapacity(+ participant: AuthenticatedRouteParticipant,+ downstreamEdges: RelayDownstreamEdges,+ ): void {+ if (participant.role !== "viewer") {+ return;+ }+ let advertised = this.relayCapacitySessionsByRoom.get(participant.roomId);+ if (!advertised) {+ advertised = new Map();+ this.relayCapacitySessionsByRoom.set(participant.roomId, advertised);+ }+ advertised.set(participant.peerId, participant.sessionId);+ const changes = this.peerRelayTopology.setViewerRelayCapacity(+ participant.roomId,+ participant.peerId,+ downstreamEdges,+ this.connectedPeerIds(participant.roomId),+ );+ if (changes.length > 0) {+ this.clearChangedConnectionIds(participant.roomId, changes);+ this.reconcileMediaRoute(participant.roomId);+ this.sendMediaAssignmentChanges(participant.roomId, changes);+ }+ const assignment = this.mediaRouteControllers+ .get(participant.roomId)+ ?.getActiveRoute()+ .assignments.get(participant.peerId);+ let roomIntents = this.viewerRouteIntentsByRoom.get(participant.roomId);+ if (assignment?.upstream.kind === "none") {+ if (!roomIntents) {+ roomIntents = new Map();+ this.viewerRouteIntentsByRoom.set(participant.roomId, roomIntents);+ }+ const existing = roomIntents.get(participant.peerId);+ if (+ existing?.sessionId !== participant.sessionId ||+ existing.failedParentPeerId !== null+ ) {+ roomIntents.set(participant.peerId, {+ failedParentPeerId: null,+ sessionId: participant.sessionId,+ sfuAttempts: 0,+ unavailableReported: false,+ });+ }+ } else if (+ roomIntents?.get(participant.peerId)?.failedParentPeerId === null+ ) {+ roomIntents.delete(participant.peerId);+ }+ this.drainViewerRouteIntents(participant.roomId);+ }++ handleRouteReady(+ participant: AuthenticatedRouteParticipant,+ message: Extract<ClientMessage, { type: "route-ready" }>,+ ): void {+ const controller = this.mediaRouteControllers.get(participant.roomId);+ if (!controller) {+ return;+ }+ if (message.phase === "active") {+ const active = controller.getActiveRoute();+ if (+ active.revision === message.revision &&+ active.assignments.has(participant.peerId)+ ) {+ return;+ }+ return;+ }++ const pending = this.pendingRoutePreparations.get(participant.roomId);+ const pendingRoute = controller.getPendingRoute();+ if (+ !pending ||+ !pendingRoute ||+ pending.revision !== message.revision ||+ pendingRoute.route.revision !== message.revision ||+ !pending.grantsIssued+ ) {+ return;+ }+ const expectedSessionId = pending.expectedSessionIds.get(participant.peerId);+ if (!expectedSessionId) {+ this.sendError(+ participant.sessionId,+ "FORBIDDEN",+ "Participant is not part of this route plan",+ );+ return;+ }+ if (participant.sessionId !== expectedSessionId) {+ return;+ }++ controller.ready(participant.peerId, message.revision, "prepare");+ this.commitPendingRoute(participant.roomId, message.revision);+ }++ handleRouteFailed(+ participant: AuthenticatedRouteParticipant,+ message: Extract<ClientMessage, { type: "route-failed" }>,+ ): void {+ if (message.phase === "prepare") {+ this.handlePrepareRouteFailed(participant, message);+ return;+ }+ const controller = this.mediaRouteControllers.get(participant.roomId);+ const active = controller?.getActiveRoute();+ if (!controller || !active || active.revision !== message.revision) {+ return;+ }+ if (message.connectionId === null) {+ const assignment = active.assignments.get(participant.peerId);+ const hostOwnsGeneration =+ participant.role === "host" &&+ active.sfu.publicationGeneration !== null &&+ assignment?.sfuPublicationGeneration ===+ active.sfu.publicationGeneration;+ const isSfuRoot =+ assignment?.upstream.kind === "sfu" &&+ active.sfu.rootPeerIds.includes(participant.peerId);+ if (!hostOwnsGeneration && !isSfuRoot) {+ this.sendError(+ participant.sessionId,+ "FORBIDDEN",+ "Participant does not own an active SFU route",+ );+ return;+ }+ this.failBackToPeerBaseline(participant.roomId);+ return;+ }+ if (participant.role !== "viewer") {+ this.sendError(+ participant.sessionId,+ "FORBIDDEN",+ "Only an active viewer route may fail",+ );+ return;+ }+ const assignment = active.assignments.get(participant.peerId);+ if (!assignment) {+ return;+ }+ if (assignment.upstream.kind !== "peer") {+ this.sendError(+ participant.sessionId,+ "FORBIDDEN",+ "The active route has no peer edge to recover",+ );+ return;+ }+ const connectionKey = viewerConnectionKey(+ participant.roomId,+ participant.peerId,+ );+ if (+ this.options.getConnectionId(participant.roomId, participant.peerId) !==+ message.connectionId+ ) {+ return;+ }++ let failedParents = this.failedParentPeerIdsByViewer.get(connectionKey);+ if (!failedParents) {+ failedParents = new Set();+ this.failedParentPeerIdsByViewer.set(connectionKey, failedParents);+ }+ if (failedParents.has(assignment.upstream.peerId)) {+ return;+ }+ failedParents.add(assignment.upstream.peerId);+ let roomIntents = this.viewerRouteIntentsByRoom.get(participant.roomId);+ if (!roomIntents) {+ roomIntents = new Map();+ this.viewerRouteIntentsByRoom.set(participant.roomId, roomIntents);+ }+ roomIntents.set(participant.peerId, {+ failedParentPeerId: assignment.upstream.peerId,+ sessionId: participant.sessionId,+ sfuAttempts: 0,+ unavailableReported: false,+ });+ this.drainViewerRouteIntents(participant.roomId);+ }++ refreshSfu(+ participant: AuthenticatedRouteParticipant,+ revision: number,+ ): void {+ void this.sendFreshSfuConfig(+ participant.roomId,+ participant.peerId,+ participant.sessionId,+ revision,+ true,+ true,+ );+ }++ disconnectParticipant(roomId: string): void {+ const pending = this.pendingRoutePreparations.get(roomId);+ if (!pending || this.pendingSessionsAreCurrent(roomId, pending)) {+ return;+ }+ this.abortPendingRouteForTopologyChange(roomId);+ }++ removeViewer(roomId: string, peerId: string): void {+ this.abortPendingRouteForTopologyChange(roomId);+ const changes = this.peerRelayTopology.removeViewer(+ roomId,+ peerId,+ this.connectedPeerIds(roomId),+ );+ this.clearChangedConnectionIds(roomId, changes);+ this.reconcileMediaRoute(roomId);+ this.sendMediaAssignmentChanges(roomId, changes);+ this.failedParentPeerIdsByViewer.delete(viewerConnectionKey(roomId, peerId));+ this.viewerRouteIntentsByRoom.get(roomId)?.delete(peerId);+ this.relayCapacitySessionsByRoom.get(roomId)?.delete(peerId);+ this.clearSfuRefreshesForPeer(roomId, peerId);+ this.drainViewerRouteIntents(roomId);+ }++ stopRoom(roomId: string): void {+ this.clearRoomMediaRouteState(roomId);+ }++ deleteRoom(roomId: string): void {+ this.peerRelayTopology.deleteRoom(roomId);+ this.relayCapacitySessionsByRoom.delete(roomId);+ this.clearRoomMediaRouteState(roomId);+ }++ private handlePrepareRouteFailed(+ participant: AuthenticatedRouteParticipant,+ message: Extract<ClientMessage, { type: "route-failed" }>,+ ): void {+ const controller = this.mediaRouteControllers.get(participant.roomId);+ const pending = this.pendingRoutePreparations.get(participant.roomId);+ const pendingRoute = controller?.getPendingRoute();+ if (+ !controller ||+ !pending ||+ !pendingRoute ||+ pending.revision !== message.revision ||+ pendingRoute.route.revision !== message.revision ||+ !pending.grantsIssued+ ) {+ return;+ }+ if (message.connectionId !== null) {+ this.sendError(+ participant.sessionId,+ "FORBIDDEN",+ "Prepare failures do not identify a peer connection",+ );+ return;+ }+ const expectedSessionId = pending.expectedSessionIds.get(participant.peerId);+ if (!expectedSessionId) {+ this.sendError(+ participant.sessionId,+ "FORBIDDEN",+ "Participant is not part of this route plan",+ );+ return;+ }+ if (participant.sessionId !== expectedSessionId) {+ return;+ }+ this.abortPendingRoute(participant.roomId);+ }++ private failBackToPeerBaseline(roomId: string): void {+ this.abortPendingRoute(roomId, undefined, false);+ const controller = this.mediaRouteControllers.get(roomId);+ const hostPeerId = this.peerRelayTopology.getHostPeerId(roomId);+ if (!controller || !hostPeerId) {+ return;+ }+ const before = controller.getActiveRoute();+ const fillChanges = this.peerRelayTopology.setHost(+ roomId,+ hostPeerId,+ this.connectedPeerIds(roomId),+ );+ this.clearChangedConnectionIds(roomId, fillChanges);+ const assignments = participantRoutesFromTopology(+ this.peerRelayTopology.getAssignments(roomId),+ hostPeerId,+ null,+ [],+ );+ const revision = controller.reconcileBaseline({+ assignments,+ sfuPublicationGeneration: null,+ sfuRootPeerIds: [],+ });+ if (revision === undefined) {+ return;+ }+ this.sfuDisabledRoomIds.add(roomId);+ this.clearRoomFailedParents(roomId);+ const active = controller.getActiveRoute();+ this.consumedSfuRefreshesByRoom.delete(roomId);+ this.clearChangedRouteConnectionIds(roomId, before, active);+ this.broadcastActiveRoute(roomId, active);+ this.drainViewerRouteIntents(roomId);+ }++ private retireShrinkingSfuRoute(+ roomId: string,+ survivingRootPeerIds: readonly string[],+ ): void {+ this.abortPendingRoute(roomId, undefined, false);+ const controller = this.mediaRouteControllers.get(roomId);+ const hostPeerId = this.peerRelayTopology.getHostPeerId(roomId);+ if (!controller || !hostPeerId) {+ return;+ }+ const before = controller.getActiveRoute();+ const assignments = participantRoutesFromTopology(+ this.peerRelayTopology.getAssignments(roomId),+ hostPeerId,+ null,+ [],+ );+ const revision = controller.reconcileBaseline({+ assignments,+ sfuPublicationGeneration: null,+ sfuRootPeerIds: [],+ });+ if (revision === undefined) {+ return;+ }+ this.consumedSfuRefreshesByRoom.delete(roomId);+ const active = controller.getActiveRoute();+ this.clearChangedRouteConnectionIds(roomId, before, active);+ this.broadcastActiveRoute(roomId, active);++ for (const peerId of survivingRootPeerIds) {+ const viewer = this.options.roomStore.getConnectedViewer(roomId, peerId);+ const assignment = active.assignments.get(peerId);+ if (!viewer || !assignment || assignment.upstream.kind === "sfu") {+ continue;+ }+ const failedParentPeerId =+ assignment.upstream.kind === "peer" &&+ this.failedParentPeerIdsByViewer+ .get(viewerConnectionKey(roomId, peerId))+ ?.has(assignment.upstream.peerId)+ ? assignment.upstream.peerId+ : assignment.upstream.kind === "none"+ ? null+ : undefined;+ if (failedParentPeerId === undefined) {+ continue;+ }+ let intents = this.viewerRouteIntentsByRoom.get(roomId);+ if (!intents) {+ intents = new Map();+ this.viewerRouteIntentsByRoom.set(roomId, intents);+ }+ intents.set(peerId, {+ failedParentPeerId,+ sessionId: viewer.sessionId,+ sfuAttempts: 0,+ unavailableReported: false,+ });+ }+ this.drainViewerRouteIntents(roomId);+ }++ private drainViewerRouteIntents(roomId: string): void {+ this.enqueueUnassignedViewerIntents(roomId);+ if (this.pendingRoutePreparations.has(roomId)) {+ return;+ }+ const intents = this.viewerRouteIntentsByRoom.get(roomId);+ if (!intents) {+ return;+ }++ for (const [viewerPeerId, intent] of [...intents]) {+ const viewer = this.options.roomStore.getConnectedViewer(+ roomId,+ viewerPeerId,+ );+ const controller = this.mediaRouteControllers.get(roomId);+ const assignment = controller+ ?.getActiveRoute()+ .assignments.get(viewerPeerId);+ if (viewer?.sessionId !== intent.sessionId || !assignment) {+ intents.delete(viewerPeerId);+ continue;+ }+ if (intent.failedParentPeerId === null) {+ if (assignment.upstream.kind !== "none") {+ intents.delete(viewerPeerId);+ continue;+ }+ const active = controller!.getActiveRoute();+ const excludedParents = new Set<string>();+ const baselineParentPeerId = this.peerRelayTopology.getAssignment(+ roomId,+ viewerPeerId,+ )?.parentPeerId;+ if (baselineParentPeerId) {+ excludedParents.add(baselineParentPeerId);+ }+ const hostPeerId = this.peerRelayTopology.getHostPeerId(roomId);+ if (+ active.sfu.publicationGeneration &&+ hostPeerId &&+ (active.assignments.get(hostPeerId)?.childPeerIds.length ?? 0) >= 1+ ) {+ excludedParents.add(hostPeerId);+ }+ const changes = this.peerRelayTopology.reassignViewer(+ roomId,+ viewerPeerId,+ this.connectedPeerIds(roomId),+ excludedParents,+ MAX_PEER_RELAY_DEPTH,+ );+ if (changes) {+ intents.delete(viewerPeerId);+ this.clearChangedConnectionIds(roomId, changes);+ this.reconcileMediaRoute(roomId);+ this.sendMediaAssignmentChanges(roomId, changes);+ continue;+ }+ } else {+ if (+ assignment.upstream.kind !== "peer" ||+ assignment.upstream.peerId !== intent.failedParentPeerId+ ) {+ intents.delete(viewerPeerId);+ continue;+ }+ const failedParents = this.failedParentPeerIdsByViewer.get(+ viewerConnectionKey(roomId, viewerPeerId),+ );+ if (!failedParents?.has(intent.failedParentPeerId)) {+ intents.delete(viewerPeerId);+ continue;+ }+ const changes = this.peerRelayTopology.reassignViewer(+ roomId,+ viewerPeerId,+ this.connectedPeerIds(roomId),+ failedParents,+ MAX_PEER_RELAY_DEPTH,+ );+ if (changes) {+ intents.delete(viewerPeerId);+ this.clearChangedConnectionIds(roomId, changes);+ this.reconcileMediaRoute(roomId);+ this.sendMediaAssignmentChanges(roomId, changes);+ continue;+ }+ }++ if (+ intent.sfuAttempts === 0 &&+ this.options.sfuFallback &&+ !this.sfuDisabledRoomIds.has(roomId)+ ) {+ const result = this.prepareSfuFallback(+ roomId,+ viewerPeerId,+ intent.sessionId,+ );+ if (result === "started") {+ intent.sfuAttempts += 1;+ return;+ }+ if (result === "busy") {+ return;+ }+ intent.unavailableReported = true;+ }++ if (!intent.unavailableReported) {+ this.sendError(+ intent.sessionId,+ "PEER_NOT_FOUND",+ "No media fallback route is available",+ );+ intent.unavailableReported = true;+ }+ }+ if (intents.size === 0) {+ this.viewerRouteIntentsByRoom.delete(roomId);+ }+ }++ private prepareSfuFallback(+ roomId: string,+ failedPeerId: string,+ sourceSessionId: string,+ ): SfuPrepareResult {+ const fallback = this.options.sfuFallback;+ const controller = this.mediaRouteControllers.get(roomId);+ if (!fallback || !controller) {+ return "unavailable";+ }+ if (controller.getPendingRoute()) {+ return "busy";+ }+ if (this.sfuDisabledRoomIds.has(roomId)) {+ this.sendError(+ sourceSessionId,+ "PEER_NOT_FOUND",+ "No media fallback route is available",+ );+ return "unavailable";+ }+ const active = controller.getActiveRoute();+ const requestedAssignment = active.assignments.get(failedPeerId);+ if (+ !requestedAssignment ||+ requestedAssignment.upstream.kind === "sfu" ||+ failedPeerId === this.peerRelayTopology.getHostPeerId(roomId)+ ) {+ this.sendError(+ sourceSessionId,+ "PEER_NOT_FOUND",+ "Viewer has no SFU fallback route",+ );+ return "unavailable";+ }+ const hostPeerId = this.peerRelayTopology.getHostPeerId(roomId);+ if (!hostPeerId) {+ this.sendError(+ sourceSessionId,+ "SERVER_ERROR",+ "SFU fallback plan is invalid",+ );+ return "unavailable";+ }++ const rootPeerIds = [+ ...new Set([...active.sfu.rootPeerIds, failedPeerId]),+ ];+ const assignments = cloneAssignments(active.assignments);+ if (!promoteSfuRoots(assignments, rootPeerIds)) {+ this.sendError(+ sourceSessionId,+ "SERVER_ERROR",+ "SFU fallback plan is invalid",+ );+ return "unavailable";+ }++ let host = assignments.get(hostPeerId);+ if (!host) {+ this.sendError(sourceSessionId, "SERVER_ERROR", "Media route has no host");+ return "unavailable";+ }++ if (host.childPeerIds.length > 1) {+ const budgetRootPeerId =+ requestedAssignment.upstream.kind === "peer"+ ? findHostBranchRoot(active.assignments, failedPeerId, hostPeerId)+ : host.childPeerIds[0];+ if (+ !budgetRootPeerId ||+ budgetRootPeerId === hostPeerId ||+ (!rootPeerIds.includes(budgetRootPeerId) &&+ rootPeerIds.length >= fallback.maxRoots)+ ) {+ this.sendError(+ sourceSessionId,+ "PEER_NOT_FOUND",+ "SFU fallback root budget is exhausted",+ );+ return "unavailable";+ }+ if (!rootPeerIds.includes(budgetRootPeerId)) {+ rootPeerIds.push(budgetRootPeerId);+ }+ if (!promoteSfuRoots(assignments, [budgetRootPeerId])) {+ this.sendError(+ sourceSessionId,+ "SERVER_ERROR",+ "SFU fallback plan is invalid",+ );+ return "unavailable";+ }+ host = assignments.get(hostPeerId);+ }++ if (+ rootPeerIds.length > fallback.maxRoots ||+ !host ||+ host.childPeerIds.length + 1 > 2+ ) {+ this.sendError(+ sourceSessionId,+ "PEER_NOT_FOUND",+ "SFU fallback root budget is exhausted",+ );+ return "unavailable";+ }++ const generation = randomBytes(16).toString("base64url");+ assignments.set(hostPeerId, {+ ...host,+ sfuPublicationGeneration: generation,+ });++ const expectedSessionIds = new Map<string, string>();+ for (const peerId of [hostPeerId, ...rootPeerIds]) {+ const peer = this.connectedPeer(roomId, peerId);+ if (!peer) {+ this.sendError(+ sourceSessionId,+ "PEER_NOT_FOUND",+ "SFU route participant is offline",+ );+ return "unavailable";+ }+ expectedSessionIds.set(peerId, peer.sessionId);+ }+ let revision: number | undefined;+ try {+ revision = controller.prepare({+ assignments,+ expectedParticipantIds: new Set(expectedSessionIds.keys()),+ sfuPublicationGeneration: generation,+ sfuRootPeerIds: rootPeerIds,+ });+ } catch {+ this.sendError(+ sourceSessionId,+ "SERVER_ERROR",+ "SFU fallback plan is invalid",+ );+ return "unavailable";+ }+ if (revision === undefined) {+ return "unavailable";+ }++ const timer = setTimeout(+ () => this.abortPendingRoute(roomId),+ fallback.prepareTimeoutMs ?? DEFAULT_SFU_PREPARE_TIMEOUT_MS,+ );+ timer.unref();+ this.pendingRoutePreparations.set(roomId, {+ revision,+ intentPeerId: failedPeerId,+ expectedSessionIds,+ grantsIssued: false,+ timer,+ });+ void this.issueSfuPrepareGrants(+ roomId,+ controller,+ revision,+ generation,+ rootPeerIds,+ expectedSessionIds,+ );+ return "started";+ }++ private async issueSfuPrepareGrants(+ roomId: string,+ controller: MediaRouteController,+ revision: number,+ generation: string,+ rootPeerIds: readonly string[],+ expectedSessionIds: ReadonlyMap<string, string>,+ ): Promise<void> {+ const fallback = this.options.sfuFallback;+ if (!fallback) {+ return;+ }+ try {+ const grants = await Promise.all(+ [...expectedSessionIds].map(async ([peerId, sessionId]) => ({+ peerId,+ sessionId,+ token: await fallback.tokenIssuer.issueToken({+ roomId,+ role:+ peerId === this.peerRelayTopology.getHostPeerId(roomId)+ ? "host"+ : "viewer",+ peerId,+ publicationGeneration: generation,+ allowlistedRootPeerIds: rootPeerIds,+ }),+ })),+ );+ const pending = this.pendingRoutePreparations.get(roomId);+ const pendingRoute = controller.getPendingRoute();+ if (+ this.mediaRouteControllers.get(roomId) !== controller ||+ pending?.revision !== revision ||+ pendingRoute?.route.revision !== revision+ ) {+ return;+ }+ if (!this.pendingSessionsAreCurrent(roomId, pending)) {+ this.abortPendingRoute(roomId);+ return;+ }+ for (const { peerId, sessionId, token } of grants) {+ const assignment = pendingRoute.route.assignments.get(peerId);+ if (!assignment) {+ this.abortPendingRoute(roomId);+ return;+ }+ this.options.sendToSession(sessionId, {+ type: "route-update",+ revision,+ phase: "prepare",+ assignment,+ });+ this.options.sendToSession(sessionId, {+ type: "sfu-config",+ revision,+ url: fallback.url,+ token,+ });+ }+ pending.grantsIssued = true;+ } catch {+ console.error("SFU route preparation failed");+ const pending = this.pendingRoutePreparations.get(roomId);+ if (+ this.mediaRouteControllers.get(roomId) === controller &&+ pending?.revision === revision+ ) {+ this.abortPendingRoute(roomId);+ }+ }+ }++ private commitPendingRoute(roomId: string, revision: number): void {+ const controller = this.mediaRouteControllers.get(roomId);+ const pending = this.pendingRoutePreparations.get(roomId);+ if (+ !controller ||+ !pending ||+ pending.revision !== revision ||+ !this.pendingSessionsAreCurrent(roomId, pending)+ ) {+ if (pending?.revision === revision) {+ this.abortPendingRoute(roomId);+ }+ return;+ }+ const before = controller.getActiveRoute();+ if (!controller.commit(revision)) {+ return;+ }+ clearTimeout(pending.timer);+ this.pendingRoutePreparations.delete(roomId);+ const active = controller.getActiveRoute();+ this.clearChangedRouteConnectionIds(roomId, before, active);+ this.broadcastActiveRoute(roomId, active);+ this.drainViewerRouteIntents(roomId);+ }++ private abortPendingRoute(+ roomId: string,+ excludedPeerId?: string,+ drainFailureIntents = true,+ ): void {+ const controller = this.mediaRouteControllers.get(roomId);+ const pending = this.pendingRoutePreparations.get(roomId);+ if (!controller || !pending) {+ return;+ }+ clearTimeout(pending.timer);+ this.pendingRoutePreparations.delete(roomId);+ if (controller.abort(pending.revision)) {+ this.broadcastActiveRoute(+ roomId,+ controller.getActiveRoute(),+ excludedPeerId,+ );+ }+ if (drainFailureIntents) {+ this.drainViewerRouteIntents(roomId);+ }+ }++ private abortPendingRouteForTopologyChange(+ roomId: string,+ excludedPeerId?: string,+ ): void {+ const pending = this.pendingRoutePreparations.get(roomId);+ const intent = pending+ ? this.viewerRouteIntentsByRoom+ .get(roomId)+ ?.get(pending.intentPeerId)+ : undefined;+ if (intent) {+ intent.sfuAttempts = 0;+ intent.unavailableReported = false;+ }+ this.abortPendingRoute(roomId, excludedPeerId, false);+ }++ private pendingSessionsAreCurrent(+ roomId: string,+ pending: PendingRoutePreparation,+ ): boolean {+ for (const [peerId, sessionId] of pending.expectedSessionIds) {+ if (this.connectedPeer(roomId, peerId)?.sessionId !== sessionId) {+ return false;+ }+ }+ return true;+ }++ private async sendFreshSfuConfig(+ roomId: string,+ peerId: string,+ sessionId: string,+ revision: number,+ reportError = false,+ consumeRefresh = false,+ ): Promise<void> {+ const fallback = this.options.sfuFallback;+ const controller = this.mediaRouteControllers.get(roomId);+ const active = controller?.getActiveRoute();+ if (+ !fallback ||+ !controller ||+ !active ||+ active.revision !== revision ||+ !active.sfu.publicationGeneration ||+ (peerId !== this.peerRelayTopology.getHostPeerId(roomId) &&+ !active.sfu.rootPeerIds.includes(peerId))+ ) {+ if (reportError) {+ this.sendError(+ sessionId,+ "FORBIDDEN",+ "Participant has no active SFU grant",+ );+ }+ return;+ }+ if (consumeRefresh) {+ let consumed = this.consumedSfuRefreshesByRoom.get(roomId);+ if (!consumed) {+ consumed = new Set();+ this.consumedSfuRefreshesByRoom.set(roomId, consumed);+ }+ const refreshKey = sfuRefreshKey(+ active.sfu.publicationGeneration,+ peerId,+ sessionId,+ );+ if (consumed.has(refreshKey)) {+ this.sendError(+ sessionId,+ "FORBIDDEN",+ "The active SFU grant was already refreshed",+ );+ return;+ }+ consumed.add(refreshKey);+ }+ try {+ const token = await fallback.tokenIssuer.issueToken({+ roomId,+ role:+ peerId === this.peerRelayTopology.getHostPeerId(roomId)+ ? "host"+ : "viewer",+ peerId,+ publicationGeneration: active.sfu.publicationGeneration,+ allowlistedRootPeerIds: active.sfu.rootPeerIds,+ });+ const current = controller.getActiveRoute();+ if (+ this.mediaRouteControllers.get(roomId) !== controller ||+ this.connectedPeer(roomId, peerId)?.sessionId !== sessionId ||+ current.revision !== revision ||+ current.sfu.publicationGeneration !==+ active.sfu.publicationGeneration+ ) {+ return;+ }+ this.options.sendToSession(sessionId, {+ type: "sfu-config",+ revision,+ url: fallback.url,+ token,+ });+ } catch {+ console.error("SFU token refresh failed");+ const current = controller.getActiveRoute();+ if (+ this.mediaRouteControllers.get(roomId) === controller &&+ this.connectedPeer(roomId, peerId)?.sessionId === sessionId &&+ current.revision === revision &&+ current.sfu.publicationGeneration ===+ active.sfu.publicationGeneration+ ) {+ this.failBackToPeerBaseline(roomId);+ }+ }+ }++ private reconcileMediaRoute(+ roomId: string,+ excludedPeerId?: string,+ ): MediaRouteController | undefined {+ const hostPeerId = this.peerRelayTopology.getHostPeerId(roomId);+ if (!hostPeerId) {+ return undefined;+ }++ let controller = this.mediaRouteControllers.get(roomId);+ if (controller?.getPendingRoute()) {+ this.abortPendingRouteForTopologyChange(roomId, excludedPeerId);+ controller = this.mediaRouteControllers.get(roomId);+ }+ let initialRevision = 0;+ if (controller && !controller.getActiveRoute().assignments.has(hostPeerId)) {+ initialRevision = controller.getActiveRoute().revision;+ if (initialRevision >= MAX_MEDIA_ROUTE_REVISION) {+ throw new Error("Media route revision space exhausted");+ }+ initialRevision += 1;+ this.clearRoomMediaRouteState(roomId);+ controller = undefined;+ }+ const previousSfu = controller?.getActiveRoute().sfu;+ let topologyAssignments = this.peerRelayTopology.getAssignments(roomId);+ let rootPeerIds =+ previousSfu?.rootPeerIds.filter((peerId) =>+ topologyAssignments.has(peerId),+ ) ?? [];+ if (+ previousSfu?.publicationGeneration &&+ rootPeerIds.length !== previousSfu.rootPeerIds.length+ ) {+ this.retireShrinkingSfuRoute(roomId, rootPeerIds);+ return controller;+ }+ const assignments = participantRoutesFromTopology(+ topologyAssignments,+ hostPeerId,+ previousSfu?.publicationGeneration ?? null,+ rootPeerIds,+ );+ if (!controller && initialRevision === 0 && assignments.size > 1) {+ initialRevision = 1;+ }++ if (!controller) {+ controller = new MediaRouteController({+ hostPeerId,+ assignments,+ revision: initialRevision,+ sfuPublicationGeneration:+ assignments.get(hostPeerId)?.sfuPublicationGeneration ?? null,+ sfuRootPeerIds: [...assignments]+ .filter(([, assignment]) => assignment.upstream.kind === "sfu")+ .map(([peerId]) => peerId),+ });+ this.mediaRouteControllers.set(roomId, controller);+ this.broadcastActiveRoute(+ roomId,+ controller.getActiveRoute(),+ excludedPeerId,+ );+ return controller;+ }++ const publicationGeneration =+ rootPeerIds.length > 0+ ? (previousSfu?.publicationGeneration ?? null)+ : null;+ const revision = controller.reconcileBaseline({+ assignments,+ sfuPublicationGeneration: publicationGeneration,+ sfuRootPeerIds: rootPeerIds,+ });+ if (revision !== undefined) {+ this.broadcastActiveRoute(+ roomId,+ controller.getActiveRoute(),+ excludedPeerId,+ );+ }+ return controller;+ }++ private broadcastActiveRoute(+ roomId: string,+ route: RoomMediaRoute,+ excludedPeerId?: string,+ ): void {+ for (const [peerId, assignment] of route.assignments) {+ if (peerId === excludedPeerId) {+ continue;+ }+ const peer = this.connectedPeer(roomId, peerId);+ if (peer) {+ this.options.sendToSession(peer.sessionId, {+ type: "route-update",+ revision: route.revision,+ phase: "active",+ assignment,+ });+ }+ }+ }++ private clearChangedRouteConnectionIds(+ roomId: string,+ before: RoomMediaRoute,+ after: RoomMediaRoute,+ ): void {+ for (const [peerId, assignment] of after.assignments) {+ const previous = before.assignments.get(peerId);+ if (!previous || !sameUpstream(previous, assignment)) {+ this.options.deleteConnectionId(roomId, peerId);+ }+ }+ }++ private clearChangedConnectionIds(+ roomId: string,+ changes: readonly MediaAssignmentChange[],+ ): void {+ for (const change of changes) {+ if (+ change.previousParentPeerId !== undefined &&+ change.previousParentPeerId !== change.mediaAssignment.parentPeerId+ ) {+ this.options.deleteConnectionId(roomId, change.peerId);+ }+ }+ }++ private sendMediaAssignmentChanges(+ roomId: string,+ changes: readonly MediaAssignmentChange[],+ excludedPeerId?: string,+ ): void {+ const active = this.mediaRouteControllers.get(roomId)?.getActiveRoute();+ for (const change of changes) {+ if (change.peerId === excludedPeerId) {+ continue;+ }+ const peer = this.connectedPeer(roomId, change.peerId);+ if (peer) {+ const activeAssignment = active?.assignments.get(change.peerId);+ this.options.sendToSession(peer.sessionId, {+ type: "media-assignment",+ mediaAssignment: activeAssignment+ ? mediaAssignmentFromParticipantRoute(activeAssignment)+ : change.mediaAssignment,+ });+ }+ }+ }++ private sendCurrentParentAssignment(roomId: string, childPeerId: string): void {+ const active = this.mediaRouteControllers.get(roomId)?.getActiveRoute();+ const child = active?.assignments.get(childPeerId);+ const parentPeerId =+ child?.upstream.kind === "peer" ? child.upstream.peerId : undefined;+ if (!parentPeerId) {+ return;+ }+ const parent = this.connectedPeer(roomId, parentPeerId);+ const parentAssignment = active?.assignments.get(parentPeerId);+ if (parent && parentAssignment && active) {+ this.options.sendToSession(parent.sessionId, {+ type: "route-update",+ revision: active.revision,+ phase: "active",+ assignment: parentAssignment,+ });+ this.options.sendToSession(parent.sessionId, {+ type: "media-assignment",+ mediaAssignment: mediaAssignmentFromParticipantRoute(parentAssignment),+ });+ }+ }++ private connectedPeerIds(roomId: string): Set<string> {+ const peerIds = new Set(+ this.options.roomStore+ .getConnectedViewers(roomId)+ .map((viewer) => viewer.peerId),+ );+ const host = this.options.roomStore.getConnectedHost(roomId);+ if (host) {+ peerIds.add(host.peerId);+ }+ return peerIds;+ }++ private connectedPeer(roomId: string, peerId: string) {+ const host = this.options.roomStore.getConnectedHost(roomId);+ if (host?.peerId === peerId) {+ return host;+ }+ return this.options.roomStore.getConnectedViewer(roomId, peerId);+ }++ private sendError(sessionId: string, code: ErrorCode, message: string): void {+ this.options.sendToSession(sessionId, { type: "error", code, message });+ }++ private clearRoomFailedParents(roomId: string): void {+ const prefix = `${roomId}:`;+ for (const key of this.failedParentPeerIdsByViewer.keys()) {+ if (key.startsWith(prefix)) {+ this.failedParentPeerIdsByViewer.delete(key);+ }+ }+ }++ private clearRoomMediaRouteState(roomId: string): void {+ const pending = this.pendingRoutePreparations.get(roomId);+ if (pending) {+ clearTimeout(pending.timer);+ this.pendingRoutePreparations.delete(roomId);+ }+ this.mediaRouteControllers.delete(roomId);+ this.clearRoomFailedParents(roomId);+ this.viewerRouteIntentsByRoom.delete(roomId);+ this.consumedSfuRefreshesByRoom.delete(roomId);+ this.sfuDisabledRoomIds.delete(roomId);+ }++ private clearSfuRefreshesForPeer(roomId: string, peerId: string): void {+ const consumed = this.consumedSfuRefreshesByRoom.get(roomId);+ if (!consumed) {+ return;+ }+ const marker = `\u0000${peerId}\u0000`;+ for (const key of consumed) {+ if (key.includes(marker)) {+ consumed.delete(key);+ }+ }+ if (consumed.size === 0) {+ this.consumedSfuRefreshesByRoom.delete(roomId);+ }+ }++ private enqueueUnassignedViewerIntents(roomId: string): void {+ const advertised = this.relayCapacitySessionsByRoom.get(roomId);+ const assignments = this.mediaRouteControllers+ .get(roomId)+ ?.getActiveRoute().assignments;+ if (!advertised || !assignments) {+ return;+ }+ let intents = this.viewerRouteIntentsByRoom.get(roomId);+ for (const [peerId, sessionId] of advertised) {+ const viewer = this.options.roomStore.getConnectedViewer(roomId, peerId);+ if (viewer?.sessionId !== sessionId) {+ advertised.delete(peerId);+ intents?.delete(peerId);+ continue;+ }+ if (assignments.get(peerId)?.upstream.kind !== "none") {+ continue;+ }+ if (!intents) {+ intents = new Map();+ this.viewerRouteIntentsByRoom.set(roomId, intents);+ }+ const existing = intents.get(peerId);+ if (+ existing?.sessionId === sessionId &&+ existing.failedParentPeerId === null+ ) {+ continue;+ }+ intents.set(peerId, {+ failedParentPeerId: null,+ sessionId,+ sfuAttempts: 0,+ unavailableReported: false,+ });+ }+ }+}++function viewerConnectionKey(roomId: string, peerId: string): string {+ return `${roomId}:${peerId}`;+}++function sfuRefreshKey(+ publicationGeneration: string,+ peerId: string,+ sessionId: string,+): string {+ return `${publicationGeneration}\u0000${peerId}\u0000${sessionId}`;+}++function participantRouteFromMediaAssignment(+ assignment: MediaAssignment | undefined,+): ParticipantRouteAssignment | undefined {+ return assignment+ ? {+ upstream: assignment.parentPeerId+ ? { kind: "peer", peerId: assignment.parentPeerId }+ : { kind: "none" },+ childPeerIds: [...assignment.childPeerIds],+ sfuPublicationGeneration: null,+ }+ : undefined;+}++function mediaAssignmentFromParticipantRoute(+ assignment: ParticipantRouteAssignment,+): MediaAssignment {+ return {+ parentPeerId:+ assignment.upstream.kind === "peer"+ ? assignment.upstream.peerId+ : null,+ childPeerIds: [...assignment.childPeerIds],+ };+}++function participantRoutesFromTopology(+ topologyAssignments: ReadonlyMap<string, MediaAssignment>,+ hostPeerId: string,+ publicationGeneration: string | null,+ requestedRootPeerIds: readonly string[],+): Map<string, ParticipantRouteAssignment> {+ // Keep the peer tree intact underneath the active SFU overlay so prepare+ // aborts and one-shot failback never need to reconstruct a lost baseline.+ const assignments = new Map<string, ParticipantRouteAssignment>();+ for (const [peerId, assignment] of topologyAssignments) {+ assignments.set(peerId, {+ upstream:+ peerId === hostPeerId || !assignment.parentPeerId+ ? { kind: "none" }+ : { kind: "peer", peerId: assignment.parentPeerId },+ childPeerIds: [...assignment.childPeerIds],+ sfuPublicationGeneration: null,+ });+ }++ const rootPeerIds = publicationGeneration+ ? requestedRootPeerIds.filter(+ (peerId) => peerId !== hostPeerId && assignments.has(peerId),+ )+ : [];+ for (const rootPeerId of rootPeerIds) {+ const root = assignments.get(rootPeerId)!;+ if (root.upstream.kind === "peer") {+ const parent = assignments.get(root.upstream.peerId);+ if (parent) {+ assignments.set(root.upstream.peerId, {+ ...parent,+ childPeerIds: parent.childPeerIds.filter(+ (childPeerId) => childPeerId !== rootPeerId,+ ),+ });+ }+ }+ assignments.set(rootPeerId, {+ ...root,+ upstream: { kind: "sfu" },+ });+ }+ const host = assignments.get(hostPeerId);+ if (host && rootPeerIds.length > 0) {+ const directChildPeerIds = host.childPeerIds.slice(0, 1);+ for (const suppressedPeerId of host.childPeerIds.slice(1)) {+ const suppressed = assignments.get(suppressedPeerId);+ if (suppressed?.upstream.kind === "peer") {+ assignments.set(suppressedPeerId, {+ ...suppressed,+ upstream: { kind: "none" },+ });+ }+ }+ assignments.set(hostPeerId, {+ ...host,+ childPeerIds: directChildPeerIds,+ sfuPublicationGeneration: publicationGeneration,+ });+ }+ return assignments;+}++function cloneAssignments(+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>,+): Map<string, ParticipantRouteAssignment> {+ return new Map(+ [...assignments].map(([peerId, assignment]) => [+ peerId,+ {+ upstream:+ assignment.upstream.kind === "peer"+ ? { kind: "peer" as const, peerId: assignment.upstream.peerId }+ : { kind: assignment.upstream.kind },+ childPeerIds: [...assignment.childPeerIds],+ sfuPublicationGeneration: assignment.sfuPublicationGeneration,+ },+ ]),+ );+}++function promoteSfuRoots(+ assignments: Map<string, ParticipantRouteAssignment>,+ rootPeerIds: readonly string[],+): boolean {+ for (const rootPeerId of rootPeerIds) {+ const root = assignments.get(rootPeerId);+ if (!root) {+ return false;+ }+ if (root.upstream.kind === "peer") {+ const parent = assignments.get(root.upstream.peerId);+ if (!parent) {+ return false;+ }+ assignments.set(root.upstream.peerId, {+ ...parent,+ childPeerIds: parent.childPeerIds.filter(+ (childPeerId) => childPeerId !== rootPeerId,+ ),+ });+ }+ assignments.set(rootPeerId, {+ ...root,+ upstream: { kind: "sfu" },+ });+ }+ return true;+}++function findHostBranchRoot(+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>,+ peerId: string,+ hostPeerId: string,+): string | undefined {+ const visited = new Set<string>();+ let branchPeerId = peerId;+ while (!visited.has(branchPeerId)) {+ visited.add(branchPeerId);+ const assignment = assignments.get(branchPeerId);+ if (assignment?.upstream.kind !== "peer") {+ return undefined;+ }+ if (assignment.upstream.peerId === hostPeerId) {+ return branchPeerId;+ }+ branchPeerId = assignment.upstream.peerId;+ }+ return undefined;+}++function sameUpstream(+ left: ParticipantRouteAssignment,+ right: ParticipantRouteAssignment,+): boolean {+ return (+ left.upstream.kind === right.upstream.kind &&+ (left.upstream.kind !== "peer" ||+ (right.upstream.kind === "peer" &&+ left.upstream.peerId === right.upstream.peerId))+ );+}diff --git a/src/server/livekit-token.ts b/src/server/livekit-token.tsnew file mode 100644index 00000000..88f729a8--- /dev/null+++ b/src/server/livekit-token.ts@@ -0,0 +1,129 @@+import {+ AccessToken,+ RoomConfiguration,+ TrackSource,+} from "livekit-server-sdk";++import {+ MAX_VIEWERS_PER_ROOM_LIMIT,+ type Role,+} from "../shared/protocol.js";++const LIVEKIT_TOKEN_TTL_SECONDS = 5 * 60;+const MAX_SFU_ROOTS_PER_ROOM_LIMIT = 2;+const ROOM_ID_PATTERN = /^[1-9]\d{0,11}$/;+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;++export interface SfuTokenRequest {+ roomId: string;+ role: Role;+ peerId: string;+ publicationGeneration: string;+ allowlistedRootPeerIds: readonly string[];+}++export interface SfuTokenIssuer {+ issueToken(request: SfuTokenRequest): Promise<string>;+}++export interface LiveKitTokenIssuerOptions {+ apiKey: string;+ apiSecret: string;+ maxViewersPerRoom: number;+ maxSfuRootsPerRoom: number;+}++export class LiveKitTokenIssuer implements SfuTokenIssuer {+ constructor(private readonly options: LiveKitTokenIssuerOptions) {+ if (!options.apiKey || Buffer.byteLength(options.apiSecret) < 32) {+ throw new Error("LiveKit API credentials are invalid");+ }+ if (+ !Number.isSafeInteger(options.maxViewersPerRoom) ||+ options.maxViewersPerRoom < 1 ||+ options.maxViewersPerRoom > MAX_VIEWERS_PER_ROOM_LIMIT+ ) {+ throw new Error("LiveKit viewer limit is invalid");+ }+ if (+ !Number.isSafeInteger(options.maxSfuRootsPerRoom) ||+ options.maxSfuRootsPerRoom < 1 ||+ options.maxSfuRootsPerRoom > MAX_SFU_ROOTS_PER_ROOM_LIMIT+ ) {+ throw new Error("LiveKit SFU root limit is invalid");+ }+ }++ async issueToken(request: SfuTokenRequest): Promise<string> {+ validateTokenRequest(request, this.options.maxSfuRootsPerRoom);++ const isHost = request.role === "host";+ const room = liveKitRoomName(+ request.roomId,+ request.publicationGeneration,+ );+ const token = new AccessToken(+ this.options.apiKey,+ this.options.apiSecret,+ {+ identity: isHost ? "host" : `viewer:${request.peerId}`,+ ttl: LIVEKIT_TOKEN_TTL_SECONDS,+ },+ );+ token.addGrant({+ roomJoin: true,+ room,+ canPublish: isHost,+ canPublishSources: isHost+ ? [TrackSource.SCREEN_SHARE, TrackSource.SCREEN_SHARE_AUDIO]+ : undefined,+ canSubscribe: !isHost,+ canPublishData: false,+ canUpdateOwnMetadata: false,+ });+ token.roomConfig = new RoomConfiguration({+ name: room,+ maxParticipants: this.options.maxViewersPerRoom + 1,+ });++ return await token.toJwt();+ }+}++function validateTokenRequest(+ request: SfuTokenRequest,+ maxSfuRootsPerRoom: number,+): void {+ if (!ROOM_ID_PATTERN.test(request.roomId)) {+ throw new Error("LiveKit room ID is invalid");+ }+ if (+ !OPAQUE_ID_PATTERN.test(request.peerId) ||+ !OPAQUE_ID_PATTERN.test(request.publicationGeneration)+ ) {+ throw new Error("LiveKit participant identity is invalid");+ }+ if (+ request.allowlistedRootPeerIds.length > maxSfuRootsPerRoom ||+ request.allowlistedRootPeerIds.some(+ (peerId) => !OPAQUE_ID_PATTERN.test(peerId),+ )+ ) {+ throw new Error("LiveKit SFU root allowlist is invalid");+ }++ const roots = new Set(request.allowlistedRootPeerIds);+ if (roots.size !== request.allowlistedRootPeerIds.length) {+ throw new Error("LiveKit SFU root allowlist contains duplicates");+ }+ if (request.role === "viewer" && !roots.has(request.peerId)) {+ throw new Error("LiveKit viewer is not an allowlisted SFU root");+ }+}++function liveKitRoomName(+ roomId: string,+ publicationGeneration: string,+): string {+ return `screener-${roomId}-${publicationGeneration}`;+}diff --git a/src/server/media-route-controller.ts b/src/server/media-route-controller.tsnew file mode 100644index 00000000..581c60da--- /dev/null+++ b/src/server/media-route-controller.ts@@ -0,0 +1,425 @@+import {+ MAX_MEDIA_ROUTE_REVISION,+ MAX_VIEWERS_PER_ROOM_LIMIT,+ participantRouteAssignmentSchema,+ sfuPublicationGenerationSchema,+ type MediaRoutePhase,+ type ParticipantRouteAssignment,+} from "../shared/protocol.js";++const MAX_PARTICIPANTS_PER_ROOM = MAX_VIEWERS_PER_ROOM_LIMIT + 1;++export interface RoomSfuRoute {+ publicationGeneration: string | null;+ rootPeerIds: readonly string[];+}++export interface RoomMediaRoute {+ revision: number;+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>;+ sfu: RoomSfuRoute;+}++export interface PendingRoomMediaRoute {+ route: RoomMediaRoute;+ expectedParticipantIds: ReadonlySet<string>;+ readyParticipantIds: ReadonlySet<string>;+}++export interface MediaRouteControllerOptions {+ hostPeerId: string;+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>;+ revision?: number;+ sfuPublicationGeneration?: string | null;+ sfuRootPeerIds?: readonly string[];+}++export interface PrepareMediaRouteInput {+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>;+ expectedParticipantIds: ReadonlySet<string>;+ sfuPublicationGeneration?: string | null;+ sfuRootPeerIds?: readonly string[];+}++export interface ReconcileBaselineInput {+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>;+ sfuPublicationGeneration?: string | null;+ sfuRootPeerIds?: readonly string[];+}++interface StoredPendingRoute {+ route: RoomMediaRoute;+ expectedParticipantIds: Set<string>;+ readyParticipantIds: Set<string>;+}++export class MediaRouteController {+ private activeRoute: RoomMediaRoute;+ private pendingRoute: StoredPendingRoute | undefined;+ private latestRevision: number;+ private readonly hostPeerId: string;++ constructor(options: MediaRouteControllerOptions) {+ this.hostPeerId = options.hostPeerId;+ const revision = options.revision ?? 0;+ assertRevision(revision);+ this.activeRoute = createRoute(+ revision,+ options.assignments,+ options.sfuPublicationGeneration ?? null,+ options.sfuRootPeerIds ?? [],+ this.hostPeerId,+ );+ this.latestRevision = revision;+ }++ getActiveRoute(): RoomMediaRoute {+ return cloneRoute(this.activeRoute);+ }++ getPendingRoute(): PendingRoomMediaRoute | undefined {+ const pending = this.pendingRoute;+ return pending+ ? {+ route: cloneRoute(pending.route),+ expectedParticipantIds: new Set(pending.expectedParticipantIds),+ readyParticipantIds: new Set(pending.readyParticipantIds),+ }+ : undefined;+ }++ reconcileBaseline(input: ReconcileBaselineInput): number | undefined {+ if (this.pendingRoute) {+ return undefined;+ }++ const revision = this.nextRevision();+ const route = createRoute(+ revision,+ input.assignments,+ input.sfuPublicationGeneration === undefined+ ? this.activeRoute.sfu.publicationGeneration+ : input.sfuPublicationGeneration,+ input.sfuRootPeerIds ?? this.activeRoute.sfu.rootPeerIds,+ this.hostPeerId,+ );+ if (hasSameTopology(route, this.activeRoute)) {+ return undefined;+ }++ this.activeRoute = route;+ this.latestRevision = revision;+ return revision;+ }++ prepare(input: PrepareMediaRouteInput): number | undefined {+ if (this.pendingRoute) {+ return undefined;+ }++ const revision = this.nextRevision();+ const route = createRoute(+ revision,+ input.assignments,+ input.sfuPublicationGeneration ?? null,+ input.sfuRootPeerIds ?? [],+ this.hostPeerId,+ );+ const expectedParticipantIds = new Set(input.expectedParticipantIds);+ if (expectedParticipantIds.size > MAX_PARTICIPANTS_PER_ROOM) {+ throw new Error("Too many expected media route participants");+ }+ for (const peerId of expectedParticipantIds) {+ if (!route.assignments.has(peerId)) {+ throw new Error(`Expected participant ${peerId} has no route assignment`);+ }+ }++ this.latestRevision = revision;+ this.pendingRoute = {+ route,+ expectedParticipantIds,+ readyParticipantIds: new Set(),+ };+ return revision;+ }++ ready(peerId: string, revision: number, phase: MediaRoutePhase): boolean {+ const pending = this.pendingRoute;+ if (+ phase !== "prepare" ||+ !pending ||+ pending.route.revision !== revision ||+ !pending.expectedParticipantIds.has(peerId) ||+ pending.readyParticipantIds.has(peerId)+ ) {+ return false;+ }++ pending.readyParticipantIds.add(peerId);+ return true;+ }++ commit(revision: number): boolean {+ const pending = this.pendingRoute;+ if (!pending || pending.route.revision !== revision) {+ return false;+ }+ for (const peerId of pending.expectedParticipantIds) {+ if (!pending.readyParticipantIds.has(peerId)) {+ return false;+ }+ }++ this.activeRoute = pending.route;+ this.pendingRoute = undefined;+ return true;+ }++ abort(revision: number): boolean {+ const pending = this.pendingRoute;+ if (!pending || pending.route.revision !== revision) {+ return false;+ }++ const rollbackRevision = this.nextRevision();+ this.activeRoute = cloneRoute(this.activeRoute, rollbackRevision);+ this.latestRevision = rollbackRevision;+ this.pendingRoute = undefined;+ return true;+ }++ hostActiveMediaEdges(): number {+ const edgeCount = hostMediaEdges(this.activeRoute, this.hostPeerId);+ if (edgeCount > 2) {+ throw new Error("Host active media edge budget exceeded");+ }+ return edgeCount;+ }++ private nextRevision(): number {+ if (this.latestRevision >= MAX_MEDIA_ROUTE_REVISION) {+ throw new Error("Media route revision space exhausted");+ }+ return this.latestRevision + 1;+ }+}++function createRoute(+ revision: number,+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>,+ publicationGeneration: string | null,+ rootPeerIds: readonly string[],+ hostPeerId: string,+): RoomMediaRoute {+ assertRevision(revision);+ if (+ assignments.size === 0 ||+ assignments.size > MAX_PARTICIPANTS_PER_ROOM+ ) {+ throw new Error("Media route participant count is outside room bounds");+ }+ if (publicationGeneration !== null) {+ sfuPublicationGenerationSchema.parse(publicationGeneration);+ }++ const clonedAssignments = new Map<string, ParticipantRouteAssignment>();+ for (const [peerId, assignment] of assignments) {+ const parsed = participantRouteAssignmentSchema.parse(assignment);+ clonedAssignments.set(peerId, cloneAssignment(parsed));+ }+ const route: RoomMediaRoute = {+ revision,+ assignments: clonedAssignments,+ sfu: {+ publicationGeneration,+ rootPeerIds: [...rootPeerIds],+ },+ };+ assertRouteInvariants(route, hostPeerId);+ return route;+}++function assertRouteInvariants(+ route: RoomMediaRoute,+ hostPeerId: string,+): void {+ const hostAssignment = route.assignments.get(hostPeerId);+ if (!hostAssignment) {+ throw new Error("Media route is missing its host assignment");+ }+ if (hostAssignment.upstream.kind !== "none") {+ throw new Error("The host cannot have a media upstream");+ }+ if (+ hostAssignment.sfuPublicationGeneration !==+ route.sfu.publicationGeneration+ ) {+ throw new Error("Host and room SFU publication generations differ");+ }++ const rootPeerIds = new Set(route.sfu.rootPeerIds);+ if (+ rootPeerIds.size !== route.sfu.rootPeerIds.length ||+ rootPeerIds.size > MAX_VIEWERS_PER_ROOM_LIMIT+ ) {+ throw new Error("SFU root participants must be unique and bounded");+ }+ if (+ (route.sfu.publicationGeneration === null) !== (rootPeerIds.size === 0)+ ) {+ throw new Error("SFU roots and publication generation must be active together");+ }++ for (const [peerId, assignment] of route.assignments) {+ if (+ peerId !== hostPeerId &&+ assignment.sfuPublicationGeneration !== null+ ) {+ throw new Error("Only the host may own an SFU publication generation");+ }+ if (assignment.childPeerIds.includes(peerId)) {+ throw new Error("A participant cannot be its own media child");+ }++ for (const childPeerId of assignment.childPeerIds) {+ const childAssignment = route.assignments.get(childPeerId);+ if (!childAssignment) {+ throw new Error(`Media child ${childPeerId} has no assignment`);+ }+ if (+ childAssignment.upstream.kind !== "peer" ||+ childAssignment.upstream.peerId !== peerId+ ) {+ throw new Error("Peer media edges must be reciprocal");+ }+ }++ if (assignment.upstream.kind === "peer") {+ const parentAssignment = route.assignments.get(+ assignment.upstream.peerId,+ );+ if (!parentAssignment?.childPeerIds.includes(peerId)) {+ throw new Error("Peer media edges must be reciprocal");+ }+ }+ if (assignment.upstream.kind === "sfu" && !rootPeerIds.has(peerId)) {+ throw new Error("Every SFU upstream must belong to the root allowlist");+ }+ }++ for (const rootPeerId of rootPeerIds) {+ const rootAssignment = route.assignments.get(rootPeerId);+ if (!rootAssignment || rootAssignment.upstream.kind !== "sfu") {+ throw new Error("Every SFU root must have the SFU as its upstream");+ }+ }++ assertAcyclicPeerEdges(route.assignments);+ if (hostMediaEdges(route, hostPeerId) > 2) {+ throw new Error("Host active media edge budget exceeded");+ }+}++function assertAcyclicPeerEdges(+ assignments: ReadonlyMap<string, ParticipantRouteAssignment>,+): void {+ for (const startPeerId of assignments.keys()) {+ const ancestors = new Set([startPeerId]);+ let assignment = assignments.get(startPeerId);+ while (assignment?.upstream.kind === "peer") {+ const parentPeerId = assignment.upstream.peerId;+ if (ancestors.has(parentPeerId)) {+ throw new Error("Peer media route contains a cycle");+ }+ ancestors.add(parentPeerId);+ assignment = assignments.get(parentPeerId);+ }+ }+}++function hostMediaEdges(route: RoomMediaRoute, hostPeerId: string): number {+ const directChildren = route.assignments.get(hostPeerId)?.childPeerIds.length;+ if (directChildren === undefined) {+ throw new Error("Media route is missing its host assignment");+ }+ return directChildren + (route.sfu.publicationGeneration === null ? 0 : 1);+}++function hasSameTopology(left: RoomMediaRoute, right: RoomMediaRoute): boolean {+ if (+ left.sfu.publicationGeneration !== right.sfu.publicationGeneration ||+ left.sfu.rootPeerIds.length !== right.sfu.rootPeerIds.length ||+ left.sfu.rootPeerIds.some(+ (peerId, index) => peerId !== right.sfu.rootPeerIds[index],+ ) ||+ left.assignments.size !== right.assignments.size+ ) {+ return false;+ }++ for (const [peerId, leftAssignment] of left.assignments) {+ const rightAssignment = right.assignments.get(peerId);+ if (+ !rightAssignment ||+ leftAssignment.sfuPublicationGeneration !==+ rightAssignment.sfuPublicationGeneration ||+ leftAssignment.upstream.kind !== rightAssignment.upstream.kind ||+ (leftAssignment.upstream.kind === "peer" &&+ (rightAssignment.upstream.kind !== "peer" ||+ leftAssignment.upstream.peerId !==+ rightAssignment.upstream.peerId)) ||+ leftAssignment.childPeerIds.length !==+ rightAssignment.childPeerIds.length ||+ leftAssignment.childPeerIds.some(+ (childPeerId, index) =>+ childPeerId !== rightAssignment.childPeerIds[index],+ )+ ) {+ return false;+ }+ }+ return true;+}++function cloneRoute(+ route: RoomMediaRoute,+ revision = route.revision,+): RoomMediaRoute {+ return {+ revision,+ assignments: new Map(+ [...route.assignments].map(([peerId, assignment]) => [+ peerId,+ cloneAssignment(assignment),+ ]),+ ),+ sfu: {+ publicationGeneration: route.sfu.publicationGeneration,+ rootPeerIds: [...route.sfu.rootPeerIds],+ },+ };+}++function cloneAssignment(+ assignment: ParticipantRouteAssignment,+): ParticipantRouteAssignment {+ return {+ upstream:+ assignment.upstream.kind === "peer"+ ? { kind: "peer", peerId: assignment.upstream.peerId }+ : { kind: assignment.upstream.kind },+ childPeerIds: [...assignment.childPeerIds],+ sfuPublicationGeneration: assignment.sfuPublicationGeneration,+ };+}++function assertRevision(revision: number): void {+ if (+ !Number.isSafeInteger(revision) ||+ revision < 0 ||+ revision > MAX_MEDIA_ROUTE_REVISION+ ) {+ throw new Error("Media route revision is outside protocol bounds");+ }+}diff --git a/src/server/peer-relay-topology.ts b/src/server/peer-relay-topology.tsindex ccaf9b84..e99b6ff4 100644--- a/src/server/peer-relay-topology.ts+++ b/src/server/peer-relay-topology.ts@@ -1,4 +1,7 @@-import type { MediaAssignment } from "../shared/protocol.js";+import type {+ MediaAssignment,+ RelayDownstreamEdges,+} from "../shared/protocol.js";export interface MediaAssignmentChange {peerId: string;@@ -6,10 +9,13 @@ export interface MediaAssignmentChange {mediaAssignment: MediaAssignment;}+export const MAX_PEER_RELAY_DEPTH = 4;+interface RelayViewer {order: number;parentPeerId: string | null;childPeerIds: string[];+ downstreamEdges: RelayDownstreamEdges;}interface RelayRoom {@@ -56,13 +62,17 @@ export class PeerRelayTopology {): MediaAssignmentChange[] {const room = this.room(roomId);const before = snapshot(room);- if (!room.viewers.has(peerId)) {+ const existingViewer = room.viewers.get(peerId);+ if (!existingViewer) {room.viewers.set(peerId, {order: room.nextOrder,parentPeerId: null,childPeerIds: [],+ downstreamEdges: 0,});room.nextOrder += 1;+ } else {+ existingViewer.downstreamEdges = 0;}for (const [candidatePeerId, viewer] of orderedViewers(room)) {if (viewer.parentPeerId === null) {@@ -72,6 +82,28 @@ export class PeerRelayTopology {return changedAssignments(before, snapshot(room));}+ setViewerRelayCapacity(+ roomId: string,+ peerId: string,+ downstreamEdges: RelayDownstreamEdges,+ connectedPeerIds: ReadonlySet<string>,+ ): MediaAssignmentChange[] {+ const room = this.rooms.get(roomId);+ const viewer = room?.viewers.get(peerId);+ if (!room || !viewer) {+ return [];+ }++ const before = snapshot(room);+ viewer.downstreamEdges = downstreamEdges;+ for (const [candidatePeerId, candidate] of orderedViewers(room)) {+ if (candidate.parentPeerId === null) {+ this.assignViewer(room, candidatePeerId, connectedPeerIds);+ }+ }+ return changedAssignments(before, snapshot(room));+ }+removeViewer(roomId: string,peerId: string,@@ -128,6 +160,62 @@ export class PeerRelayTopology {: undefined;}+ getAssignments(roomId: string): Map<string, MediaAssignment> {+ const room = this.rooms.get(roomId);+ return room ? snapshot(room) : new Map();+ }++ getHostPeerId(roomId: string): string | undefined {+ return this.rooms.get(roomId)?.hostPeerId;+ }++ reassignViewer(+ roomId: string,+ peerId: string,+ connectedPeerIds: ReadonlySet<string>,+ excludedParentPeerIds: ReadonlySet<string>,+ maxDepth = MAX_PEER_RELAY_DEPTH,+ ): MediaAssignmentChange[] | undefined {+ const room = this.rooms.get(roomId);+ const viewer = room?.viewers.get(peerId);+ if (+ !room?.hostPeerId ||+ !viewer ||+ !connectedPeerIds.has(peerId) ||+ !Number.isSafeInteger(maxDepth) ||+ maxDepth < 1+ ) {+ return undefined;+ }++ const subtreePeerIds = collectSubtreePeerIds(room, peerId);+ const subtreeHeight = maximumSubtreeDepth(room, peerId);+ if (maximumDepthOutsideSubtree(room, subtreePeerIds) > maxDepth) {+ return undefined;+ }+ const parentPeerId = findReassignmentParent(+ room,+ connectedPeerIds,+ excludedParentPeerIds,+ subtreePeerIds,+ maxDepth - subtreeHeight - 1,+ );+ if (!parentPeerId || parentPeerId === viewer.parentPeerId) {+ return undefined;+ }++ const before = snapshot(room);+ this.detach(room, peerId, viewer.parentPeerId);+ viewer.parentPeerId = parentPeerId;+ const children = childPeerIds(room, parentPeerId);+ children.push(peerId);+ children.sort(+ (left, right) =>+ room.viewers.get(left)!.order - room.viewers.get(right)!.order,+ );+ return changedAssignments(before, snapshot(room));+ }+isParentOf(roomId: string, parentPeerId: string, childPeerId: string): boolean {return (this.rooms.get(roomId)?.viewers.get(childPeerId)?.parentPeerId ===@@ -165,7 +253,11 @@ export class PeerRelayTopology {) {return;}- const parentPeerId = findShallowestAvailableParent(room, connectedPeerIds);+ const parentPeerId = findShallowestAvailableParent(+ room,+ connectedPeerIds,+ MAX_PEER_RELAY_DEPTH - maximumSubtreeDepth(room, peerId) - 1,+ );if (!parentPeerId) {return;}@@ -197,28 +289,128 @@ export class PeerRelayTopology {function findShallowestAvailableParent(room: RelayRoom,connectedPeerIds: ReadonlySet<string>,+ maximumParentDepth: number,): string | undefined {const hostPeerId = room.hostPeerId;if (!hostPeerId || !connectedPeerIds.has(hostPeerId)) {return undefined;}- const queue = [hostPeerId];+ const queue: Array<{ peerId: string; depth: number }> = [+ { peerId: hostPeerId, depth: 0 },+ ];while (queue.length > 0) {- const peerId = queue.shift()!;- if (!connectedPeerIds.has(peerId)) {+ const { peerId, depth } = queue.shift()!;+ if (depth > maximumParentDepth || !connectedPeerIds.has(peerId)) {continue;}const children = childPeerIds(room, peerId);- const capacity = peerId === hostPeerId ? 2 : 1;+ const capacity = downstreamCapacity(room, peerId);if (children.length < capacity) {return peerId;}- queue.push(...children);+ for (const childPeerId of children) {+ queue.push({ peerId: childPeerId, depth: depth + 1 });+ }+ }+ return undefined;+}++function findReassignmentParent(+ room: RelayRoom,+ connectedPeerIds: ReadonlySet<string>,+ excludedParentPeerIds: ReadonlySet<string>,+ subtreePeerIds: ReadonlySet<string>,+ maximumParentDepth: number,+): string | undefined {+ const hostPeerId = room.hostPeerId;+ if (!hostPeerId || !connectedPeerIds.has(hostPeerId)) {+ return undefined;+ }++ const queue: Array<{ peerId: string; depth: number }> = [+ { peerId: hostPeerId, depth: 0 },+ ];+ while (queue.length > 0) {+ const { peerId, depth } = queue.shift()!;+ if (depth > maximumParentDepth || !connectedPeerIds.has(peerId)) {+ continue;+ }+ const children = childPeerIds(room, peerId);+ const capacity = downstreamCapacity(room, peerId);+ if (+ children.length < capacity &&+ !excludedParentPeerIds.has(peerId) &&+ !subtreePeerIds.has(peerId)+ ) {+ return peerId;+ }+ for (const childPeerId of children) {+ queue.push({ peerId: childPeerId, depth: depth + 1 });+ }}return undefined;}+function downstreamCapacity(room: RelayRoom, peerId: string): number {+ return room.hostPeerId === peerId+ ? 2+ : (room.viewers.get(peerId)?.downstreamEdges ?? 0);+}++function collectSubtreePeerIds(room: RelayRoom, rootPeerId: string): Set<string> {+ const peerIds = new Set<string>();+ const queue = [rootPeerId];+ while (queue.length > 0) {+ const peerId = queue.shift()!;+ if (peerIds.has(peerId)) {+ continue;+ }+ peerIds.add(peerId);+ queue.push(...(room.viewers.get(peerId)?.childPeerIds ?? []));+ }+ return peerIds;+}++function maximumSubtreeDepth(room: RelayRoom, rootPeerId: string): number {+ let maximumDepth = 0;+ const queue: Array<{ peerId: string; depth: number }> = [+ { peerId: rootPeerId, depth: 0 },+ ];+ while (queue.length > 0) {+ const { peerId, depth } = queue.shift()!;+ maximumDepth = Math.max(maximumDepth, depth);+ for (const childPeerId of room.viewers.get(peerId)?.childPeerIds ?? []) {+ queue.push({ peerId: childPeerId, depth: depth + 1 });+ }+ }+ return maximumDepth;+}++function maximumDepthOutsideSubtree(+ room: RelayRoom,+ excludedPeerIds: ReadonlySet<string>,+): number {+ const hostPeerId = room.hostPeerId;+ if (!hostPeerId) {+ return 0;+ }+ let maximumDepth = 0;+ const queue: Array<{ peerId: string; depth: number }> = [+ { peerId: hostPeerId, depth: 0 },+ ];+ while (queue.length > 0) {+ const { peerId, depth } = queue.shift()!;+ maximumDepth = Math.max(maximumDepth, depth);+ for (const childPeerId of childPeerIds(room, peerId)) {+ if (!excludedPeerIds.has(childPeerId)) {+ queue.push({ peerId: childPeerId, depth: depth + 1 });+ }+ }+ }+ return maximumDepth;+}+function childPeerIds(room: RelayRoom, peerId: string): string[] {if (room.hostPeerId === peerId) {return room.hostChildPeerIds;diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex 5951a24a..6811a1b1 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -15,9 +15,9 @@ import {} from "../shared/protocol.js";import { RoomStore, RoomStoreError } from "./room-store.js";import {- PeerRelayTopology,- type MediaAssignmentChange,-} from "./peer-relay-topology.js";+ HybridMediaRouter,+ type SfuFallbackOptions,+} from "./hybrid-media-router.js";import { createIceConfig, type IceConfigOptions } from "./turn.js";type ErrorCode = Extract<ServerMessage, { type: "error" }>["code"];@@ -31,6 +31,7 @@ interface AuthenticatedSession {role: Role;peerId: string;roomExpiresAtMs: number | null;+ shareGeneration: string | null;}interface SocketState {@@ -44,6 +45,7 @@ export interface SignalingOptions {server: HttpServer;roomStore: RoomStore;peerAssistedMedia: boolean;+ sfuFallback?: SfuFallbackOptions;ice: IceConfigOptions;allowedOrigins: ReadonlySet<string>;authorizeUpgrade: (request: IncomingMessage) => boolean;@@ -71,7 +73,8 @@ export class SignalingServer {string,QualityProfileId>();- private readonly peerRelayTopology = new PeerRelayTopology();+ private readonly shareGenerationsByRoom = new Map<string, string>();+ private readonly hybridMediaRouter?: HybridMediaRouter;private readonly now: () => number;private readonly authenticationTimeoutMs: number;private readonly viewerDisconnectGraceMs: number;@@ -100,6 +103,25 @@ export class SignalingServer {) {throw new Error("WebSocket connection limits are invalid");}+ if (options.sfuFallback && !options.peerAssistedMedia) {+ throw new Error("SFU fallback requires peer-assisted media");+ }+ if (options.peerAssistedMedia) {+ this.hybridMediaRouter = new HybridMediaRouter({+ roomStore: options.roomStore,+ sfuFallback: options.sfuFallback,+ sendToSession: (sessionId, message) =>+ this.sendToSession(sessionId, message),+ getConnectionId: (roomId, viewerPeerId) =>+ this.connectionIdsByViewer.get(+ viewerConnectionKey(roomId, viewerPeerId),+ ),+ deleteConnectionId: (roomId, viewerPeerId) =>+ this.connectionIdsByViewer.delete(+ viewerConnectionKey(roomId, viewerPeerId),+ ),+ });+ }this.upgradeHandler = (request, socket, head) => {let requestUrl: URL;@@ -157,6 +179,8 @@ export class SignalingServer {clearTimeout(timer);}this.viewerGraceTimers.clear();+ this.hybridMediaRouter?.close();+ this.shareGenerationsByRoom.clear();this.options.server.off("upgrade", this.upgradeHandler);for (const socket of this.webSocketServer.clients) {@@ -285,6 +309,21 @@ export class SignalingServer {clearTimeout(state.authenticationTimer);this.unauthenticatedConnections -= 1;+ let shareGeneration: string | null = null;+ if (participant.role === "host" && message.role === "host") {+ const currentGeneration = this.shareGenerationsByRoom.get(+ participant.roomId,+ );+ shareGeneration =+ message.shareGeneration ?? currentGeneration ?? state.sessionId;+ if (+ currentGeneration !== undefined &&+ currentGeneration !== shareGeneration+ ) {+ this.stopSharing(participant.roomId);+ }+ this.shareGenerationsByRoom.set(participant.roomId, shareGeneration);+ }state.authenticated = {roomId: participant.roomId,role: participant.role,@@ -293,29 +332,19 @@ export class SignalingServer {participant.expiresAt === null? null: Date.parse(participant.expiresAt),+ shareGeneration,};this.clearViewerGrace(participant.roomId, participant.peerId);- const assignmentChanges = this.options.peerAssistedMedia- ? participant.role === "host"- ? this.peerRelayTopology.setHost(- participant.roomId,- participant.peerId,- this.connectedPeerIds(participant.roomId),- )- : this.peerRelayTopology.addViewer(- participant.roomId,- participant.peerId,- this.connectedPeerIds(participant.roomId),- )- : [];- this.clearChangedConnectionIds(participant.roomId, assignmentChanges);- const mediaAssignment = this.options.peerAssistedMedia- ? this.peerRelayTopology.getAssignment(- participant.roomId,- participant.peerId,- )- : undefined;- if (this.options.peerAssistedMedia && !mediaAssignment) {+ const routeParticipant = {+ roomId: participant.roomId,+ role: participant.role,+ peerId: participant.peerId,+ sessionId: state.sessionId,+ };+ let hybridState;+ try {+ hybridState = this.hybridMediaRouter?.connectParticipant(routeParticipant);+ } catch {console.error("Peer relay topology did not assign an authenticated participant");this.sendError(socket, "SERVER_ERROR", "Media assignment failed");socket.close(1011, "Media assignment failed");@@ -349,11 +378,13 @@ export class SignalingServer {: Date.parse(participant.expiresAt),),};- if (mediaAssignment) {+ if (hybridState) {this.send(socket, {...authenticatedMessage,mediaMode: "peer-assisted",- mediaAssignment,+ mediaAssignment: hybridState.mediaAssignment,+ routeRevision: hybridState.routeRevision,+ routeAssignment: hybridState.routeAssignment,qualityProfileId:this.qualityProfileIdsByRoom.get(participant.roomId) ??DEFAULT_QUALITY_PROFILE_ID,@@ -369,24 +400,11 @@ export class SignalingServer {}}- if (this.options.peerAssistedMedia) {- this.sendMediaAssignmentChanges(- participant.roomId,- assignmentChanges,- participant.peerId,+ if (hybridState) {+ this.hybridMediaRouter!.completeAuthentication(+ routeParticipant,+ hybridState,);- if (- participant.role === "viewer" &&- mediaAssignment?.parentPeerId &&- !assignmentChanges.some(- ({ peerId }) => peerId === mediaAssignment.parentPeerId,- )- ) {- this.sendCurrentParentAssignment(- participant.roomId,- participant.peerId,- );- }}if (participant.role === "host") {@@ -477,12 +495,82 @@ export class SignalingServer {});}return;+ case "relay-capacity":+ if (+ !this.options.peerAssistedMedia ||+ authenticated.role !== "viewer"+ ) {+ this.sendError(+ socket,+ "FORBIDDEN",+ "Only a peer-assisted viewer may advertise relay capacity",+ );+ return;+ }+ this.hybridMediaRouter!.setViewerRelayCapacity(+ {+ ...authenticated,+ sessionId: this.socketStates.get(socket)!.sessionId,+ },+ message.downstreamEdges,+ );+ return;+ case "route-ready":+ if (!this.options.peerAssistedMedia) {+ this.sendError(socket, "FORBIDDEN", "Media routes are not enabled");+ return;+ }+ this.hybridMediaRouter!.handleRouteReady(+ {+ ...authenticated,+ sessionId: this.socketStates.get(socket)!.sessionId,+ },+ message,+ );+ return;+ case "route-failed":+ if (!this.options.peerAssistedMedia) {+ this.sendError(socket, "FORBIDDEN", "Media routes are not enabled");+ return;+ }+ this.hybridMediaRouter!.handleRouteFailed(+ {+ ...authenticated,+ sessionId: this.socketStates.get(socket)!.sessionId,+ },+ message,+ );+ return;+ case "refresh-sfu":+ if (!this.options.sfuFallback) {+ this.sendError(socket, "FORBIDDEN", "SFU fallback is not enabled");+ return;+ }+ this.hybridMediaRouter!.refreshSfu(+ {+ ...authenticated,+ sessionId: this.socketStates.get(socket)!.sessionId,+ },+ message.revision,+ );+ return;case "stop-sharing":case "close-room":if (authenticated.role !== "host") {this.sendError(socket, "FORBIDDEN", "Only the host may stop sharing");return;}+ if (+ authenticated.shareGeneration === null ||+ this.shareGenerationsByRoom.get(authenticated.roomId) !==+ authenticated.shareGeneration ||+ (message.type === "stop-sharing" &&+ message.shareGeneration !== undefined &&+ message.shareGeneration !== authenticated.shareGeneration)+ ) {+ socket.close(4001, "Sharing generation replaced");+ return;+ }const state = this.socketStates.get(socket);if (state?.authenticated === authenticated) {this.options.roomStore.disconnectParticipant(@@ -580,12 +668,12 @@ export class SignalingServer {return;}- const parentToChild = this.peerRelayTopology.isParentOf(+ const parentToChild = this.hybridMediaRouter!.isActivePeerParentOf(source.roomId,source.peerId,targetPeerId,);- const childToParent = this.peerRelayTopology.isParentOf(+ const childToParent = this.hybridMediaRouter!.isActivePeerParentOf(source.roomId,targetPeerId,source.peerId,@@ -629,7 +717,7 @@ export class SignalingServer {const targetPeerId = message.targetPeerId;if (!targetPeerId ||- !this.peerRelayTopology.isParentOf(+ !this.hybridMediaRouter!.isActivePeerParentOf(source.roomId,targetPeerId,source.peerId,@@ -694,6 +782,7 @@ export class SignalingServer {if (!disconnected) {return;}+ this.hybridMediaRouter?.disconnectParticipant(disconnected.roomId);if (disconnected.role === "host") {for (const viewer of this.options.roomStore.getConnectedViewers(disconnected.roomId,@@ -715,19 +804,10 @@ export class SignalingServer {this.connectionIdsByViewer.delete(viewerConnectionKey(disconnected.roomId, disconnected.peerId),);- if (this.options.peerAssistedMedia) {- const assignmentChanges = this.peerRelayTopology.removeViewer(+ if (this.hybridMediaRouter) {+ this.hybridMediaRouter.removeViewer(disconnected.roomId,disconnected.peerId,- this.connectedPeerIds(disconnected.roomId),- );- this.clearChangedConnectionIds(- disconnected.roomId,- assignmentChanges,- );- this.sendMediaAssignmentChanges(- disconnected.roomId,- assignmentChanges,);return;}@@ -746,6 +826,7 @@ export class SignalingServer {private stopSharing(roomId: string): void {this.clearRoomConnectionIds(roomId);+ this.hybridMediaRouter?.stopRoom(roomId);for (const viewer of this.options.roomStore.getConnectedViewers(roomId)) {this.sendToSession(viewer.sessionId, { type: "sharing-stopped" });this.sendToSession(viewer.sessionId, { type: "host-status", online: false });@@ -759,8 +840,9 @@ export class SignalingServer {}this.clearRoomGraceTimers(roomId);this.clearRoomConnectionIds(roomId);- this.peerRelayTopology.deleteRoom(roomId);+ this.hybridMediaRouter?.deleteRoom(roomId);this.qualityProfileIdsByRoom.delete(roomId);+ this.shareGenerationsByRoom.delete(roomId);for (const sessionId of abandoned.sessionIds) {const socket = this.socketsBySessionId.get(sessionId);if (!socket) {@@ -775,8 +857,9 @@ export class SignalingServer {for (const expired of this.options.roomStore.expireRooms(this.now())) {this.clearRoomGraceTimers(expired.roomId);this.clearRoomConnectionIds(expired.roomId);- this.peerRelayTopology.deleteRoom(expired.roomId);+ this.hybridMediaRouter?.deleteRoom(expired.roomId);this.qualityProfileIdsByRoom.delete(expired.roomId);+ this.shareGenerationsByRoom.delete(expired.roomId);for (const sessionId of expired.sessionIds) {const socket = this.socketsBySessionId.get(sessionId);if (!socket) {@@ -847,19 +930,6 @@ export class SignalingServer {);}- private connectedPeerIds(roomId: string): Set<string> {- const peerIds = new Set(- this.options.roomStore- .getConnectedViewers(roomId)- .map((viewer) => viewer.peerId),- );- const host = this.options.roomStore.getConnectedHost(roomId);- if (host) {- peerIds.add(host.peerId);- }- return peerIds;- }-private connectedPeer(roomId: string, peerId: string) {const host = this.options.roomStore.getConnectedHost(roomId);if (host?.peerId === peerId) {@@ -868,66 +938,6 @@ export class SignalingServer {return this.options.roomStore.getConnectedViewer(roomId, peerId);}- private clearChangedConnectionIds(- roomId: string,- changes: readonly MediaAssignmentChange[],- ): void {- for (const change of changes) {- if (- change.previousParentPeerId !== undefined &&- change.previousParentPeerId !==- change.mediaAssignment.parentPeerId- ) {- this.connectionIdsByViewer.delete(- viewerConnectionKey(roomId, change.peerId),- );- }- }- }-- private sendMediaAssignmentChanges(- roomId: string,- changes: readonly MediaAssignmentChange[],- excludedPeerId?: string,- ): void {- for (const change of changes) {- if (change.peerId === excludedPeerId) {- continue;- }- const peer = this.connectedPeer(roomId, change.peerId);- if (peer) {- this.sendToSession(peer.sessionId, {- type: "media-assignment",- mediaAssignment: change.mediaAssignment,- });- }- }- }-- private sendCurrentParentAssignment(- roomId: string,- childPeerId: string,- ): void {- const parentPeerId = this.peerRelayTopology.getAssignment(- roomId,- childPeerId,- )?.parentPeerId;- if (!parentPeerId) {- return;- }- const parent = this.connectedPeer(roomId, parentPeerId);- const parentAssignment = this.peerRelayTopology.getAssignment(- roomId,- parentPeerId,- );- if (parent && parentAssignment) {- this.sendToSession(parent.sessionId, {- type: "media-assignment",- mediaAssignment: parentAssignment,- });- }- }-private sendToSession(sessionId: string, message: ServerMessage): void {const socket = this.socketsBySessionId.get(sessionId);if (socket) {diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex 77f52bd7..c5ec5046 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -3,6 +3,8 @@ import { z } from "zod";export const MAX_VIEWERS_PER_ROOM_LIMIT = 16;export const MAX_SIGNAL_BYTES = 64 * 1024;export const ROOM_CODE_LENGTH = 12;+export const MAX_MEDIA_ROUTE_REVISION = Number.MAX_SAFE_INTEGER;+export const MAX_SFU_TOKEN_LENGTH = 8 * 1024;const opaqueIdSchema = z.string()@@ -33,6 +35,12 @@ export const qualityProfileIdSchema = z.enum([export type QualityProfileId = z.infer<typeof qualityProfileIdSchema>;export const DEFAULT_QUALITY_PROFILE_ID: QualityProfileId = "1080p60";+export const relayDownstreamEdgesSchema = z.union([+ z.literal(0),+ z.literal(1),+]);+export type RelayDownstreamEdges = z.infer<typeof relayDownstreamEdgesSchema>;+const iceServerSchema = z.object({urls: z.union([@@ -95,6 +103,43 @@ export const mediaAssignmentSchema = z.strict();export type MediaAssignment = z.infer<typeof mediaAssignmentSchema>;+export const mediaRouteRevisionSchema = z+ .number()+ .int()+ .min(0)+ .max(MAX_MEDIA_ROUTE_REVISION);++export const mediaRoutePhaseSchema = z.enum(["prepare", "active"]);+export type MediaRoutePhase = z.infer<typeof mediaRoutePhaseSchema>;++export const mediaRouteUpstreamSchema = z.discriminatedUnion("kind", [+ z.object({ kind: z.literal("none") }).strict(),+ z+ .object({+ kind: z.literal("peer"),+ peerId: opaqueIdSchema,+ })+ .strict(),+ z.object({ kind: z.literal("sfu") }).strict(),+]);+export type MediaRouteUpstream = z.infer<typeof mediaRouteUpstreamSchema>;++export const sfuPublicationGenerationSchema = opaqueIdSchema;++export const participantRouteAssignmentSchema = z+ .object({+ upstream: mediaRouteUpstreamSchema,+ childPeerIds: z+ .array(opaqueIdSchema)+ .max(2)+ .refine((peerIds) => new Set(peerIds).size === peerIds.length),+ sfuPublicationGeneration: sfuPublicationGenerationSchema.nullable(),+ })+ .strict();+export type ParticipantRouteAssignment = z.infer<+ typeof participantRouteAssignmentSchema+>;+const authenticateMessageSchema = z.discriminatedUnion("role", [z.object({@@ -103,6 +148,7 @@ const authenticateMessageSchema = z.discriminatedUnion("role", [role: z.literal("host"),token: tokenSchema,clientId: opaqueIdSchema,+ shareGeneration: opaqueIdSchema.optional(),}).strict(),z@@ -139,7 +185,39 @@ export const clientMessageSchema = z.union([qualityProfileId: qualityProfileIdSchema,}).strict(),- z.object({ type: z.literal("stop-sharing") }).strict(),+ z+ .object({+ type: z.literal("relay-capacity"),+ downstreamEdges: relayDownstreamEdgesSchema,+ })+ .strict(),+ z+ .object({+ type: z.literal("route-ready"),+ revision: mediaRouteRevisionSchema,+ phase: mediaRoutePhaseSchema,+ })+ .strict(),+ z+ .object({+ type: z.literal("route-failed"),+ revision: mediaRouteRevisionSchema,+ phase: mediaRoutePhaseSchema,+ connectionId: opaqueIdSchema.nullable(),+ })+ .strict(),+ z+ .object({+ type: z.literal("refresh-sfu"),+ revision: mediaRouteRevisionSchema,+ })+ .strict(),+ z+ .object({+ type: z.literal("stop-sharing"),+ shareGeneration: opaqueIdSchema.optional(),+ })+ .strict(),// Kept as a compatibility alias while previously deployed clients age out.z.object({ type: z.literal("close-room") }).strict(),z.object({ type: z.literal("abandon-room") }).strict(),@@ -177,6 +255,8 @@ const authenticatedMessageSchema = z.union([...authenticatedMessageShape,mediaMode: z.literal("peer-assisted"),mediaAssignment: mediaAssignmentSchema,+ routeRevision: mediaRouteRevisionSchema,+ routeAssignment: participantRouteAssignmentSchema,qualityProfileId: qualityProfileIdSchema,}).strict(),@@ -217,6 +297,22 @@ export const serverMessageSchema = z.union([mediaAssignment: mediaAssignmentSchema,}).strict(),+ z+ .object({+ type: z.literal("route-update"),+ revision: mediaRouteRevisionSchema,+ phase: mediaRoutePhaseSchema,+ assignment: participantRouteAssignmentSchema,+ })+ .strict(),+ z+ .object({+ type: z.literal("sfu-config"),+ revision: mediaRouteRevisionSchema,+ url: z.string().url().max(2048),+ token: z.string().min(1).max(MAX_SFU_TOKEN_LENGTH),+ })+ .strict(),z.object({type: z.literal("quality-profile"),diff --git a/tests/livekit-token.test.ts b/tests/livekit-token.test.tsnew file mode 100644index 00000000..e230daa8--- /dev/null+++ b/tests/livekit-token.test.ts@@ -0,0 +1,141 @@+import { describe, expect, it } from "vitest";+import { TokenVerifier } from "livekit-server-sdk";++import { LiveKitTokenIssuer } from "../src/server/livekit-token.ts";++const apiKey = "test-api-key";+const apiSecret = "s".repeat(32);+const publicationGeneration = "publication_12345678";+const rootPeerId = "viewer_root_12345678";++function issuer(+ maxViewersPerRoom = 8,+ maxSfuRootsPerRoom = 2,+): LiveKitTokenIssuer {+ return new LiveKitTokenIssuer({+ apiKey,+ apiSecret,+ maxViewersPerRoom,+ maxSfuRootsPerRoom,+ });+}++describe("LiveKitTokenIssuer", () => {+ it("issues a generation-bound host token limited to screen sharing", async () => {+ const claims = await new TokenVerifier(apiKey, apiSecret).verify(+ await issuer().issueToken({+ roomId: "42",+ role: "host",+ peerId: "host_peer_12345678",+ publicationGeneration,+ allowlistedRootPeerIds: [rootPeerId],+ }),+ );++ expect(claims.sub).toBe("host");+ expect(claims.exp! - claims.nbf!).toBe(5 * 60);+ expect(claims.video).toMatchObject({+ roomJoin: true,+ room: `screener-42-${publicationGeneration}`,+ canPublish: true,+ canSubscribe: false,+ canPublishData: false,+ canUpdateOwnMetadata: false,+ canPublishSources: ["screen_share", "screen_share_audio"],+ });+ expect(claims.roomConfig).toMatchObject({+ name: `screener-42-${publicationGeneration}`,+ maxParticipants: 9,+ });+ });++ it("issues a subscribe-only token to a current fallback root", async () => {+ const claims = await new TokenVerifier(apiKey, apiSecret).verify(+ await issuer(3).issueToken({+ roomId: "7",+ role: "viewer",+ peerId: rootPeerId,+ publicationGeneration,+ allowlistedRootPeerIds: [rootPeerId],+ }),+ );++ expect(claims.sub).toBe(`viewer:${rootPeerId}`);+ expect(claims.video).toMatchObject({+ roomJoin: true,+ room: `screener-7-${publicationGeneration}`,+ canPublish: false,+ canSubscribe: true,+ canPublishData: false,+ canUpdateOwnMetadata: false,+ });+ expect(claims.video?.canPublishSources).toBeUndefined();+ expect(claims.roomConfig?.maxParticipants).toBe(4);+ });++ it("does not issue viewer tokens outside the current root allowlist", async () => {+ await expect(+ issuer().issueToken({+ roomId: "7",+ role: "viewer",+ peerId: "viewer_other_12345678",+ publicationGeneration,+ allowlistedRootPeerIds: [rootPeerId],+ }),+ ).rejects.toThrow("viewer is not an allowlisted SFU root");+ });++ it("rejects duplicate, excessive, and malformed root allowlists", async () => {+ const tokenIssuer = issuer(8, 1);+ const request = {+ roomId: "7",+ role: "host" as const,+ peerId: "host_peer_12345678",+ publicationGeneration,+ };++ await expect(+ tokenIssuer.issueToken({+ ...request,+ allowlistedRootPeerIds: [rootPeerId, rootPeerId],+ }),+ ).rejects.toThrow("root allowlist is invalid");+ await expect(+ issuer().issueToken({+ ...request,+ allowlistedRootPeerIds: [rootPeerId, rootPeerId],+ }),+ ).rejects.toThrow("root allowlist contains duplicates");+ await expect(+ issuer().issueToken({+ ...request,+ allowlistedRootPeerIds: ["not valid"],+ }),+ ).rejects.toThrow("root allowlist is invalid");+ });++ it("isolates publication generations in separate LiveKit rooms", async () => {+ const tokenIssuer = issuer();+ const verifier = new TokenVerifier(apiKey, apiSecret);+ const baseRequest = {+ roomId: "7",+ role: "host" as const,+ peerId: "host_peer_12345678",+ allowlistedRootPeerIds: [rootPeerId],+ };+ const first = await verifier.verify(+ await tokenIssuer.issueToken({+ ...baseRequest,+ publicationGeneration: "generation_first_12345678",+ }),+ );+ const second = await verifier.verify(+ await tokenIssuer.issueToken({+ ...baseRequest,+ publicationGeneration: "generation_second_12345678",+ }),+ );++ expect(first.video?.room).not.toBe(second.video?.room);+ });+});diff --git a/tests/media-route-controller.test.ts b/tests/media-route-controller.test.tsnew file mode 100644index 00000000..cb9dbc73--- /dev/null+++ b/tests/media-route-controller.test.ts@@ -0,0 +1,335 @@+import { describe, expect, it } from "vitest";++import {+ MediaRouteController,+ type PrepareMediaRouteInput,+} from "../src/server/media-route-controller.ts";+import type { ParticipantRouteAssignment } from "../src/shared/protocol.ts";++const HOST = "host_12345678";+const DIRECT_ROOT = "viewer_direct_12345678";+const SFU_ROOT_A = "viewer_sfu_a_12345678";+const SFU_ROOT_B = "viewer_sfu_b_12345678";+const GENERATION_A = "generation_a_12345678";+const GENERATION_B = "generation_b_12345678";++function assignment(+ upstream: ParticipantRouteAssignment["upstream"],+ childPeerIds: string[] = [],+ sfuPublicationGeneration: string | null = null,+): ParticipantRouteAssignment {+ return { upstream, childPeerIds, sfuPublicationGeneration };+}++function directAssignments(): Map<string, ParticipantRouteAssignment> {+ return new Map([+ [HOST, assignment({ kind: "none" }, [DIRECT_ROOT, SFU_ROOT_A])],+ [DIRECT_ROOT, assignment({ kind: "peer", peerId: HOST })],+ [SFU_ROOT_A, assignment({ kind: "peer", peerId: HOST })],+ [SFU_ROOT_B, assignment({ kind: "none" })],+ ]);+}++function hybridPlan(+ generation = GENERATION_A,+ rootPeerId = SFU_ROOT_A,+): PrepareMediaRouteInput {+ const otherRootPeerId =+ rootPeerId === SFU_ROOT_A ? SFU_ROOT_B : SFU_ROOT_A;+ return {+ assignments: new Map([+ [+ HOST,+ assignment({ kind: "none" }, [DIRECT_ROOT], generation),+ ],+ [DIRECT_ROOT, assignment({ kind: "peer", peerId: HOST })],+ [rootPeerId, assignment({ kind: "sfu" })],+ [otherRootPeerId, assignment({ kind: "none" })],+ ]),+ expectedParticipantIds: new Set([HOST, rootPeerId]),+ sfuPublicationGeneration: generation,+ sfuRootPeerIds: [rootPeerId],+ };+}++function controller(+ assignments = directAssignments(),+): MediaRouteController {+ return new MediaRouteController({ hostPeerId: HOST, assignments });+}++function chainedAssignments(): Map<string, ParticipantRouteAssignment> {+ return new Map([+ [HOST, assignment({ kind: "none" }, [DIRECT_ROOT])],+ [+ DIRECT_ROOT,+ assignment({ kind: "peer", peerId: HOST }, [SFU_ROOT_A]),+ ],+ [SFU_ROOT_A, assignment({ kind: "peer", peerId: DIRECT_ROOT })],+ [SFU_ROOT_B, assignment({ kind: "none" })],+ ]);+}++describe("MediaRouteController", () => {+ it("atomically commits only after every expected participant is ready", () => {+ const routes = controller();+ const revision = routes.prepare(hybridPlan())!;++ expect(revision).toBe(1);+ expect(routes.getActiveRoute().sfu.publicationGeneration).toBeNull();+ expect(routes.ready(HOST, revision, "prepare")).toBe(true);+ expect(routes.ready(HOST, revision, "prepare")).toBe(false);+ expect(routes.commit(revision)).toBe(false);+ expect(routes.getActiveRoute().revision).toBe(0);++ expect(routes.ready(SFU_ROOT_A, revision, "prepare")).toBe(true);+ expect(routes.getActiveRoute().sfu.publicationGeneration).toBeNull();+ expect(routes.commit(revision)).toBe(true);+ expect(routes.getPendingRoute()).toBeUndefined();+ expect(routes.getActiveRoute()).toMatchObject({+ revision,+ sfu: {+ publicationGeneration: GENERATION_A,+ rootPeerIds: [SFU_ROOT_A],+ },+ });+ expect(routes.hostActiveMediaEdges()).toBe(2);+ });++ it("allows only one pending plan and ignores stale or wrong-phase messages", () => {+ const routes = controller();+ const revision = routes.prepare(hybridPlan())!;++ expect(routes.prepare(hybridPlan(GENERATION_B, SFU_ROOT_B))).toBeUndefined();+ expect(routes.ready(HOST, revision - 1, "prepare")).toBe(false);+ expect(routes.ready(HOST, revision, "active")).toBe(false);+ expect(routes.commit(revision - 1)).toBe(false);+ expect(routes.abort(revision - 1)).toBe(false);+ expect(routes.getPendingRoute()?.route.revision).toBe(revision);+ expect(routes.getActiveRoute().revision).toBe(0);+ });++ it("aborts to the unchanged active topology with a newer revision", () => {+ const routes = controller();+ const before = routes.getActiveRoute();+ const preparedRevision = routes.prepare(hybridPlan())!;++ expect(routes.abort(preparedRevision)).toBe(true);+ const after = routes.getActiveRoute();+ expect(after.revision).toBe(preparedRevision + 1);+ expect(after.assignments).toEqual(before.assignments);+ expect(after.sfu).toEqual(before.sfu);+ expect(routes.getPendingRoute()).toBeUndefined();+ expect(routes.abort(preparedRevision)).toBe(false);++ expect(routes.prepare(hybridPlan())).toBe(after.revision + 1);+ });++ it("reconciles complete baseline snapshots without resetting revisions", () => {+ const routes = controller();+ const reconciledRevision = routes.reconcileBaseline({+ assignments: chainedAssignments(),+ });++ expect(reconciledRevision).toBe(1);+ expect(routes.getActiveRoute().revision).toBe(1);+ expect(+ routes.getActiveRoute().assignments.get(SFU_ROOT_A)?.upstream,+ ).toEqual({ kind: "peer", peerId: DIRECT_ROOT });+ expect(+ routes.reconcileBaseline({ assignments: chainedAssignments() }),+ ).toBeUndefined();+ expect(routes.getActiveRoute().revision).toBe(1);++ const preparedRevision = routes.prepare(hybridPlan())!;+ expect(+ routes.reconcileBaseline({ assignments: directAssignments() }),+ ).toBeUndefined();+ expect(routes.getActiveRoute().revision).toBe(1);+ expect(routes.abort(preparedRevision)).toBe(true);+ expect(routes.getActiveRoute().revision).toBe(3);++ expect(+ routes.reconcileBaseline({ assignments: directAssignments() }),+ ).toBe(4);+ expect(routes.getActiveRoute().revision).toBe(4);+ expect(routes.hostActiveMediaEdges()).toBe(2);+ });++ it("preserves active SFU state while reconciling peer topology", () => {+ const activePlan = hybridPlan(GENERATION_A, SFU_ROOT_A);+ const routes = new MediaRouteController({+ hostPeerId: HOST,+ assignments: activePlan.assignments,+ revision: 6,+ sfuPublicationGeneration: GENERATION_A,+ sfuRootPeerIds: [SFU_ROOT_A],+ });+ const assignments = new Map(activePlan.assignments);+ assignments.set(+ DIRECT_ROOT,+ assignment({ kind: "peer", peerId: HOST }, [SFU_ROOT_B]),+ );+ assignments.set(+ SFU_ROOT_B,+ assignment({ kind: "peer", peerId: DIRECT_ROOT }),+ );++ expect(routes.reconcileBaseline({ assignments })).toBe(7);+ expect(routes.getActiveRoute().sfu).toEqual({+ publicationGeneration: GENERATION_A,+ rootPeerIds: [SFU_ROOT_A],+ });+ expect(routes.hostActiveMediaEdges()).toBe(2);+ });++ it("never overlaps old and new SFU publication generations", () => {+ const initialPlan = hybridPlan(GENERATION_A, SFU_ROOT_A);+ const routes = new MediaRouteController({+ hostPeerId: HOST,+ assignments: initialPlan.assignments,+ revision: 4,+ sfuPublicationGeneration: GENERATION_A,+ sfuRootPeerIds: [SFU_ROOT_A],+ });+ const preparedRevision = routes.prepare(+ hybridPlan(GENERATION_B, SFU_ROOT_B),+ )!;++ expect(routes.getActiveRoute().sfu).toEqual({+ publicationGeneration: GENERATION_A,+ rootPeerIds: [SFU_ROOT_A],+ });+ expect(routes.getPendingRoute()?.route.sfu).toEqual({+ publicationGeneration: GENERATION_B,+ rootPeerIds: [SFU_ROOT_B],+ });+ expect(routes.hostActiveMediaEdges()).toBe(2);++ routes.ready(HOST, preparedRevision, "prepare");+ routes.ready(SFU_ROOT_B, preparedRevision, "prepare");+ expect(routes.commit(preparedRevision)).toBe(true);+ expect(routes.getActiveRoute().sfu).toEqual({+ publicationGeneration: GENERATION_B,+ rootPeerIds: [SFU_ROOT_B],+ });+ expect(routes.hostActiveMediaEdges()).toBe(2);+ });++ it("rejects host fanout above two and inconsistent SFU ownership", () => {+ const tooManyHostEdges = new Map(hybridPlan().assignments);+ tooManyHostEdges.set(+ HOST,+ assignment(+ { kind: "none" },+ [DIRECT_ROOT, SFU_ROOT_B],+ GENERATION_A,+ ),+ );+ tooManyHostEdges.set(+ SFU_ROOT_B,+ assignment({ kind: "peer", peerId: HOST }),+ );++ expect(() =>+ new MediaRouteController({+ hostPeerId: HOST,+ assignments: tooManyHostEdges,+ sfuPublicationGeneration: GENERATION_A,+ sfuRootPeerIds: [SFU_ROOT_A],+ }),+ ).toThrow("Host active media edge budget exceeded");++ const nonHostPublisher = directAssignments();+ nonHostPublisher.set(+ DIRECT_ROOT,+ assignment({ kind: "peer", peerId: HOST }, [], GENERATION_A),+ );+ expect(() => controller(nonHostPublisher)).toThrow(+ "Only the host may own an SFU publication generation",+ );++ const missingRoot = hybridPlan().assignments;+ expect(() =>+ new MediaRouteController({+ hostPeerId: HOST,+ assignments: missingRoot,+ sfuPublicationGeneration: GENERATION_A,+ sfuRootPeerIds: [SFU_ROOT_B],+ }),+ ).toThrow("Every SFU upstream must belong to the root allowlist");++ const generationWithoutRoots = directAssignments();+ generationWithoutRoots.set(+ HOST,+ assignment(+ { kind: "none" },+ [DIRECT_ROOT, SFU_ROOT_A],+ GENERATION_A,+ ),+ );+ expect(() =>+ new MediaRouteController({+ hostPeerId: HOST,+ assignments: generationWithoutRoots,+ sfuPublicationGeneration: GENERATION_A,+ }),+ ).toThrow("SFU roots and publication generation must be active together");+ });++ it("rejects reciprocal peer cycles", () => {+ const assignments = new Map<string, ParticipantRouteAssignment>([+ [HOST, assignment({ kind: "none" })],+ [+ SFU_ROOT_A,+ assignment({ kind: "peer", peerId: SFU_ROOT_B }, [SFU_ROOT_B]),+ ],+ [+ SFU_ROOT_B,+ assignment({ kind: "peer", peerId: SFU_ROOT_A }, [SFU_ROOT_A]),+ ],+ ]);++ expect(() => controller(assignments)).toThrow(+ "Peer media route contains a cycle",+ );+ });++ it("preserves budgets and monotonic revisions across mixed sequences", () => {+ const routes = controller();+ let previousRevision = routes.getActiveRoute().revision;++ for (let index = 0; index < 60; index += 1) {+ const plan =+ index % 2 === 0+ ? hybridPlan(GENERATION_A, SFU_ROOT_A)+ : {+ assignments: directAssignments(),+ expectedParticipantIds: new Set([HOST]),+ };+ const revision = routes.prepare(plan)!;+ expect(revision).toBeGreaterThan(previousRevision);+ expect(routes.prepare(plan)).toBeUndefined();+ expect(routes.ready(HOST, revision - 1, "prepare")).toBe(false);+ expect(routes.commit(revision - 1)).toBe(false);+ expect(routes.hostActiveMediaEdges()).toBeLessThanOrEqual(2);++ expect(routes.ready(HOST, revision, "prepare")).toBe(true);+ expect(routes.ready(HOST, revision, "prepare")).toBe(false);+ if (index % 3 === 0) {+ expect(routes.abort(revision)).toBe(true);+ } else {+ if (plan.expectedParticipantIds.has(SFU_ROOT_A)) {+ expect(routes.ready(SFU_ROOT_A, revision, "prepare")).toBe(true);+ }+ expect(routes.commit(revision)).toBe(true);+ }++ const active = routes.getActiveRoute();+ expect(active.revision).toBeGreaterThan(previousRevision);+ expect(routes.getPendingRoute()).toBeUndefined();+ expect(routes.hostActiveMediaEdges()).toBeLessThanOrEqual(2);+ previousRevision = active.revision;+ }+ });+});diff --git a/tests/peer-relay-topology.test.ts b/tests/peer-relay-topology.test.tsindex 5d5c7a9a..3213388d 100644--- a/tests/peer-relay-topology.test.ts+++ b/tests/peer-relay-topology.test.ts@@ -6,6 +6,24 @@ function connected(...peerIds: string[]): Set<string> {return new Set(peerIds);}+function addRelayViewer(+ topology: PeerRelayTopology,+ roomId: string,+ peerId: string,+ connectedPeerIds: ReadonlySet<string>,+) {+ const changes = topology.addViewer(roomId, peerId, connectedPeerIds);+ return [+ ...changes,+ ...topology.setViewerRelayCapacity(+ roomId,+ peerId,+ 1,+ connectedPeerIds,+ ),+ ];+}+function expectValidTree(topology: PeerRelayTopology,roomId: string,@@ -42,6 +60,98 @@ function expectValidTree(}describe("PeerRelayTopology", () => {+ it("keeps viewers as leaves until a relay slot is explicitly advertised", () => {+ const topology = new PeerRelayTopology();+ const peers = connected("host", "viewer-a", "viewer-b", "viewer-c");+ topology.setHost("room", "host", peers);+ topology.addViewer("room", "viewer-a", peers);+ topology.addViewer("room", "viewer-b", peers);+ topology.addViewer("room", "viewer-c", peers);++ expect(topology.getAssignment("room", "viewer-c")?.parentPeerId).toBeNull();+ expect(+ topology.setViewerRelayCapacity("room", "viewer-a", 0, peers),+ ).toEqual([]);++ const changes = topology.setViewerRelayCapacity(+ "room",+ "viewer-a",+ 1,+ peers,+ );+ expect(changes.map(({ peerId }) => peerId).sort()).toEqual([+ "viewer-a",+ "viewer-c",+ ]);+ expect(topology.getAssignment("room", "viewer-a")).toEqual({+ parentPeerId: "host",+ childPeerIds: ["viewer-c"],+ });+ expect(topology.getAssignment("room", "viewer-b")?.parentPeerId).toBe(+ "host",+ );+ });++ it("does not migrate healthy edges when a relay withdraws capacity", () => {+ const topology = new PeerRelayTopology();+ const peers = connected("host", "viewer-a", "viewer-b", "viewer-c", "viewer-d");+ topology.setHost("room", "host", peers);+ topology.addViewer("room", "viewer-a", peers);+ topology.addViewer("room", "viewer-b", peers);+ topology.setViewerRelayCapacity("room", "viewer-a", 1, peers);+ topology.addViewer("room", "viewer-c", peers);++ expect(+ topology.setViewerRelayCapacity("room", "viewer-a", 0, peers),+ ).toEqual([]);+ topology.addViewer("room", "viewer-d", peers);++ expect(topology.getAssignment("room", "viewer-c")?.parentPeerId).toBe(+ "viewer-a",+ );+ expect(topology.getAssignment("room", "viewer-d")?.parentPeerId).toBeNull();+ });++ it("does not reassign a failed edge through a viewer leaf", () => {+ const topology = new PeerRelayTopology();+ const peers = connected("host", "viewer-a", "viewer-b", "viewer-c");+ topology.setHost("room", "host", peers);+ topology.addViewer("room", "viewer-a", peers);+ topology.addViewer("room", "viewer-b", peers);+ topology.setViewerRelayCapacity("room", "viewer-a", 1, peers);+ topology.addViewer("room", "viewer-c", peers);++ expect(+ topology.reassignViewer(+ "room",+ "viewer-c",+ peers,+ new Set(["viewer-a"]),+ ),+ ).toBeUndefined();+ expect(topology.getAssignment("room", "viewer-c")?.parentPeerId).toBe(+ "viewer-a",+ );+ });++ it("requires a reconnecting viewer to advertise capacity again", () => {+ const topology = new PeerRelayTopology();+ const peers = connected("host", "viewer-a", "viewer-b", "viewer-c", "viewer-d");+ topology.setHost("room", "host", peers);+ topology.addViewer("room", "viewer-a", peers);+ topology.addViewer("room", "viewer-b", peers);+ topology.setViewerRelayCapacity("room", "viewer-a", 1, peers);+ topology.addViewer("room", "viewer-c", peers);++ topology.addViewer("room", "viewer-a", peers);+ topology.addViewer("room", "viewer-d", peers);++ expect(topology.getAssignment("room", "viewer-c")?.parentPeerId).toBe(+ "viewer-a",+ );+ expect(topology.getAssignment("room", "viewer-d")?.parentPeerId).toBeNull();+ });+it("fills the shallowest stable slots with bounded fanout", () => {const topology = new PeerRelayTopology();const roomId = "room";@@ -50,7 +160,7 @@ describe("PeerRelayTopology", () => {const viewers = ["viewer-a", "viewer-b", "viewer-c", "viewer-d", "viewer-e"];for (const viewer of viewers) {- topology.addViewer(roomId, viewer, connected(host, ...viewers));+ addRelayViewer(topology, roomId, viewer, connected(host, ...viewers));}expect(topology.getAssignment(roomId, host)).toEqual({@@ -81,7 +191,8 @@ describe("PeerRelayTopology", () => {);topology.setHost(roomId, hostPeerId, connected(hostPeerId));for (const peerId of viewerPeerIds) {- topology.addViewer(+ addRelayViewer(+ topology,roomId,peerId,connected(hostPeerId, ...viewerPeerIds),@@ -91,23 +202,63 @@ describe("PeerRelayTopology", () => {expect(expectValidTree(topology, roomId, hostPeerId, viewerPeerIds)).toBe(4);});+ it("uses the same depth-four bound for initial admission", () => {+ const topology = new PeerRelayTopology();+ const roomId = "room";+ const peerIds = [+ "host",+ "viewer-a",+ "viewer-b",+ "viewer-c",+ "viewer-d",+ "viewer-e",+ "viewer-f",+ ];+ const peers = connected(...peerIds);+ topology.setHost(roomId, "host", peers);+ topology.addViewer(roomId, "viewer-a", peers);+ topology.setViewerRelayCapacity(roomId, "viewer-a", 1, peers);+ topology.addViewer(roomId, "viewer-b", peers);+ for (const peerId of ["viewer-c", "viewer-d", "viewer-e"]) {+ topology.addViewer(roomId, peerId, peers);+ topology.setViewerRelayCapacity(roomId, peerId, 1, peers);+ }+ topology.addViewer(roomId, "viewer-f", peers);++ expect(topology.getAssignment(roomId, "viewer-e")?.parentPeerId).toBe(+ "viewer-d",+ );+ expect(topology.getAssignment(roomId, "viewer-f")?.parentPeerId).toBeNull();+ expect(+ expectValidTree(+ topology,+ roomId,+ "host",+ peerIds.slice(1, -1),+ ),+ ).toBe(4);+ });+it("leaves a disconnected viewer subtree sticky during its grace window", () => {const topology = new PeerRelayTopology();const roomId = "room";topology.setHost(roomId, "host", connected("host"));- topology.addViewer(roomId, "viewer-a", connected("host", "viewer-a"));- topology.addViewer(+ addRelayViewer(topology, roomId, "viewer-a", connected("host", "viewer-a"));+ addRelayViewer(+ topology,roomId,"viewer-b",connected("host", "viewer-a", "viewer-b"),);- topology.addViewer(+ addRelayViewer(+ topology,roomId,"viewer-c",connected("host", "viewer-a", "viewer-b", "viewer-c"),);- topology.addViewer(+ addRelayViewer(+ topology,roomId,"viewer-d",connected("host", "viewer-b", "viewer-c", "viewer-d"),@@ -125,23 +276,27 @@ describe("PeerRelayTopology", () => {const topology = new PeerRelayTopology();const roomId = "room";topology.setHost(roomId, "host", connected("host"));- topology.addViewer(roomId, "viewer-a", connected("host", "viewer-a"));- topology.addViewer(+ addRelayViewer(topology, roomId, "viewer-a", connected("host", "viewer-a"));+ addRelayViewer(+ topology,roomId,"viewer-b",connected("host", "viewer-a", "viewer-b"),);- topology.addViewer(+ addRelayViewer(+ topology,roomId,"viewer-c",connected("host", "viewer-a", "viewer-b", "viewer-c"),);- topology.addViewer(+ addRelayViewer(+ topology,roomId,"viewer-d",connected("host", "viewer-a", "viewer-b", "viewer-c", "viewer-d"),);- topology.addViewer(+ addRelayViewer(+ topology,roomId,"viewer-e",connected(@@ -180,13 +335,15 @@ describe("PeerRelayTopology", () => {const topology = new PeerRelayTopology();const roomId = "room";topology.setHost(roomId, "host", connected("host"));- topology.addViewer(roomId, "viewer-a", connected("host", "viewer-a"));- topology.addViewer(+ addRelayViewer(topology, roomId, "viewer-a", connected("host", "viewer-a"));+ addRelayViewer(+ topology,roomId,"viewer-b",connected("host", "viewer-a", "viewer-b"),);- topology.addViewer(+ addRelayViewer(+ topology,roomId,"viewer-c",connected("host", "viewer-a", "viewer-b", "viewer-c"),@@ -203,7 +360,8 @@ describe("PeerRelayTopology", () => {"viewer-b",]);- const reconnectChanges = topology.addViewer(+ const reconnectChanges = addRelayViewer(+ topology,roomId,"viewer-c",connected("host", "viewer-b", "viewer-c"),@@ -223,14 +381,15 @@ describe("PeerRelayTopology", () => {const roomId = "room";topology.setHost(roomId, "host", connected("host"));for (const peerId of ["a", "b", "c", "d"]) {- topology.addViewer(+ addRelayViewer(+ topology,roomId,peerId,connected("host", "a", "b", "c", "d"),);}- topology.addViewer(roomId, "e", connected("host", "c", "d", "e"));+ addRelayViewer(topology, roomId, "e", connected("host", "c", "d", "e"));expect(topology.getAssignment(roomId, "e")?.parentPeerId).toBeNull();topology.removeViewer(roomId, "a", connected("host", "c", "d", "e"));@@ -242,7 +401,7 @@ describe("PeerRelayTopology", () => {it("keeps pending viewers unassigned until a host arrives", () => {const topology = new PeerRelayTopology();- topology.addViewer("room", "viewer-a", connected("viewer-a"));+ addRelayViewer(topology, "room", "viewer-a", connected("viewer-a"));expect(topology.getAssignment("room", "viewer-a")?.parentPeerId).toBeNull();topology.setHost(@@ -258,17 +417,20 @@ describe("PeerRelayTopology", () => {it("updates only direct root parents when the host identity changes", () => {const topology = new PeerRelayTopology();topology.setHost("room", "host-a", connected("host-a"));- topology.addViewer(+ addRelayViewer(+ topology,"room","viewer-a",connected("host-a", "viewer-a"),);- topology.addViewer(+ addRelayViewer(+ topology,"room","viewer-b",connected("host-a", "viewer-a", "viewer-b"),);- topology.addViewer(+ addRelayViewer(+ topology,"room","viewer-c",connected("host-a", "viewer-a", "viewer-b", "viewer-c"),@@ -291,10 +453,123 @@ describe("PeerRelayTopology", () => {);});+ it("reassigns a failed edge deterministically without entering its subtree", () => {+ const topology = new PeerRelayTopology();+ const peers = ["host", "a", "b", "c", "d", "e"];+ topology.setHost("room", "host", connected(...peers));+ for (const peerId of peers.slice(1)) {+ addRelayViewer(topology, "room", peerId, connected(...peers));+ }++ expect(topology.getAssignment("room", "e")?.parentPeerId).toBe("c");+ const changes = topology.reassignViewer(+ "room",+ "e",+ connected(...peers),+ new Set(["c"]),+ 4,+ );++ expect(changes?.map(({ peerId }) => peerId).sort()).toEqual([+ "c",+ "d",+ "e",+ ]);+ expect(topology.getAssignment("room", "e")?.parentPeerId).toBe("d");+ expect(expectValidTree(topology, "room", "host", peers.slice(1))).toBe(3);+ });++ it("does not mutate when every bounded reparent candidate is excluded", () => {+ const topology = new PeerRelayTopology();+ topology.setHost("room", "host", connected("host", "a", "b", "c"));+ for (const peerId of ["a", "b", "c"]) {+ addRelayViewer(+ topology,+ "room",+ peerId,+ connected("host", "a", "b", "c"),+ );+ }+ const before = topology.getAssignments("room");++ expect(+ topology.reassignViewer(+ "room",+ "c",+ connected("host", "a", "b", "c"),+ new Set(["host", "a", "b"]),+ 4,+ ),+ ).toBeUndefined();+ expect(topology.getAssignments("room")).toEqual(before);+ });++ it("rejects a reparent whose deepest descendant would exceed max depth", () => {+ const topology = new PeerRelayTopology();+ const peers = ["host", "a", "b", "c", "d", "e", "f", "g", "h"];+ topology.setHost("room", "host", connected(...peers));+ for (const peerId of peers.slice(1)) {+ addRelayViewer(topology, "room", peerId, connected(...peers));+ }+ const before = topology.getAssignments("room");++ expect(topology.getAssignment("room", "g")?.parentPeerId).toBe("e");+ expect(+ topology.reassignViewer(+ "room",+ "g",+ connected(...peers),+ new Set(["e"]),+ 4,+ ),+ ).toBeUndefined();+ expect(topology.getAssignments("room")).toEqual(before);+ });++ it("does not attach a pending subtree beyond the initial-admission depth bound", () => {+ const topology = new PeerRelayTopology();+ const initialPeers = ["host", "a", "b", "c", "d", "e", "f", "g", "h"];+ topology.setHost("room", "host", connected(...initialPeers));+ for (const peerId of initialPeers.slice(1)) {+ addRelayViewer(topology, "room", peerId, connected(...initialPeers));+ }+ expect(topology.getAssignment("room", "e")).toMatchObject({+ parentPeerId: "c",+ childPeerIds: ["g"],+ });++ topology.removeViewer(+ "room",+ "c",+ connected("host", "a", "b", "d", "f", "h"),+ );+ topology.removeViewer(+ "room",+ "h",+ connected("host", "a", "b", "d", "f"),+ );+ topology.addViewer(+ "room",+ "x",+ connected("host", "a", "b", "d", "f", "x"),+ );++ topology.addViewer(+ "room",+ "e",+ connected("host", "a", "b", "d", "e", "f", "g", "x"),+ );++ expect(topology.getAssignment("room", "e")?.parentPeerId).toBeNull();+ expect(topology.getAssignment("room", "g")?.parentPeerId).toBe("e");+ expect(topology.getAssignment("room", "f")?.childPeerIds).toEqual([]);+ });+it("drops all assignments when a room is deleted", () => {const topology = new PeerRelayTopology();topology.setHost("room", "host-a", connected("host-a"));- topology.addViewer(+ addRelayViewer(+ topology,"room","viewer-a",connected("host-a", "viewer-a"),diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex d8f605ce..b0de1797 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -1,9 +1,12 @@import { describe, expect, it } from "vitest";import {+ MAX_MEDIA_ROUTE_REVISION,+ MAX_SFU_TOKEN_LENGTH,MAX_VIEWERS_PER_ROOM_LIMIT,clientMessageSchema,decodeClientMessage,+ participantRouteAssignmentSchema,serverMessageSchema,} from "../src/shared/protocol.js";@@ -125,6 +128,22 @@ describe("client signaling protocol", () => {expect(clientMessageSchema.safeParse({ type: "stop-sharing" }).success).toBe(true,);+ expect(+ clientMessageSchema.safeParse({+ type: "stop-sharing",+ shareGeneration: "share_generation_12345678",+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "authenticate",+ roomId,+ role: "host",+ token,+ clientId: "client_12345678",+ shareGeneration: "share_generation_12345678",+ }).success,+ ).toBe(true);expect(clientMessageSchema.safeParse({ type: "close-room" }).success).toBe(true,);@@ -154,6 +173,79 @@ describe("client signaling protocol", () => {}).success,).toBe(false);});++ it("accepts only a binary browser relay capacity", () => {+ expect(+ clientMessageSchema.safeParse({+ type: "relay-capacity",+ downstreamEdges: 0,+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "relay-capacity",+ downstreamEdges: 1,+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "relay-capacity",+ downstreamEdges: 2,+ }).success,+ ).toBe(false);+ expect(+ clientMessageSchema.safeParse({+ type: "relay-capacity",+ downstreamEdges: 1,+ score: 100,+ }).success,+ ).toBe(false);+ });++ it("accepts bounded route acknowledgements, failures, and SFU refreshes", () => {+ expect(+ clientMessageSchema.safeParse({+ type: "route-ready",+ revision: 7,+ phase: "prepare",+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "route-failed",+ revision: 7,+ phase: "active",+ connectionId: null,+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "refresh-sfu",+ revision: MAX_MEDIA_ROUTE_REVISION,+ }).success,+ ).toBe(true);++ expect(+ clientMessageSchema.safeParse({+ type: "route-ready",+ revision: -1,+ phase: "prepare",+ }).success,+ ).toBe(false);+ expect(+ clientMessageSchema.safeParse({+ type: "route-failed",+ revision: 7,+ phase: "active",+ }).success,+ ).toBe(false);+ expect(+ clientMessageSchema.safeParse({+ type: "refresh-sfu",+ revision: 1.5,+ }).success,+ ).toBe(false);+ });});describe("server signaling protocol", () => {@@ -209,6 +301,12 @@ describe("server signaling protocol", () => {parentPeerId: null,childPeerIds: ["viewer_12345678", "viewer_87654321"],},+ routeRevision: 0,+ routeAssignment: {+ upstream: { kind: "none" },+ childPeerIds: ["viewer_12345678", "viewer_87654321"],+ sfuPublicationGeneration: null,+ },qualityProfileId: "1080p60",};@@ -223,6 +321,8 @@ describe("server signaling protocol", () => {serverMessageSchema.safeParse({...authenticatedMessage(8),mediaMode: "peer-assisted",+ routeRevision: 0,+ routeAssignment: peerAssisted.routeAssignment,qualityProfileId: "1080p60",}).success,).toBe(false);@@ -231,6 +331,8 @@ describe("server signaling protocol", () => {...authenticatedMessage(8),mediaMode: "peer-assisted",mediaAssignment: peerAssisted.mediaAssignment,+ routeRevision: 0,+ routeAssignment: peerAssisted.routeAssignment,}).success,).toBe(false);expect(@@ -272,6 +374,91 @@ describe("server signaling protocol", () => {).toBe(false);});+ it("keeps hybrid route messages strict and separate from ordinary P2P auth", () => {+ const assignment = {+ upstream: { kind: "peer", peerId: "parent_12345678" },+ childPeerIds: ["child_12345678", "child_87654321"],+ sfuPublicationGeneration: null,+ };++ expect(participantRouteAssignmentSchema.safeParse(assignment).success).toBe(+ true,+ );+ expect(+ serverMessageSchema.safeParse({+ type: "route-update",+ revision: 9,+ phase: "prepare",+ assignment,+ }).success,+ ).toBe(true);+ expect(+ serverMessageSchema.safeParse({+ type: "sfu-config",+ revision: 9,+ url: "wss://sfu.example.com",+ token: "header.payload.signature",+ }).success,+ ).toBe(true);++ expect(+ participantRouteAssignmentSchema.safeParse({+ ...assignment,+ childPeerIds: [+ "child_12345678",+ "child_87654321",+ "child_overflow",+ ],+ }).success,+ ).toBe(false);+ expect(+ participantRouteAssignmentSchema.safeParse({+ ...assignment,+ childPeerIds: ["child_12345678", "child_12345678"],+ }).success,+ ).toBe(false);+ expect(+ serverMessageSchema.safeParse({+ type: "route-update",+ revision: 9,+ phase: "prepare",+ assignment,+ roomAssignments: [],+ }).success,+ ).toBe(false);+ expect(+ serverMessageSchema.safeParse({+ type: "sfu-config",+ revision: 9,+ url: "wss://sfu.example.com",+ token: "x".repeat(MAX_SFU_TOKEN_LENGTH + 1),+ }).success,+ ).toBe(false);+ expect(+ serverMessageSchema.safeParse({+ ...authenticatedMessage(8),+ routeRevision: 9,+ }).success,+ ).toBe(false);+ });++ it("accepts every bounded hybrid upstream shape", () => {+ for (const upstream of [+ { kind: "none" },+ { kind: "peer", peerId: "parent_12345678" },+ { kind: "sfu" },+ ]) {+ expect(+ participantRouteAssignmentSchema.safeParse({+ upstream,+ childPeerIds: [],+ sfuPublicationGeneration:+ upstream.kind === "none" ? "generation_12345678" : null,+ }).success,+ ).toBe(true);+ }+ });+it.each([0, 1.5, MAX_VIEWERS_PER_ROOM_LIMIT + 1])("rejects viewer limit %s outside the protocol boundary",(maxViewers) => {diff --git a/tests/relay-capability.test.ts b/tests/relay-capability.test.tsnew file mode 100644index 00000000..64cf4105--- /dev/null+++ b/tests/relay-capability.test.ts@@ -0,0 +1,51 @@+import { describe, expect, it } from "vitest";++import {+ detectBrowserRelayCapacity,+ relayCapacityMessageForBrowser,+} from "../src/client/media/relay-capability.ts";++const desktop = {+ userAgent:+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/140 Safari/537.36",+ userAgentDataMobile: false,+ maxTouchPoints: 0,+};++describe("browser relay capability", () => {+ it("allows one downstream edge on a desktop browser", () => {+ expect(detectBrowserRelayCapacity(desktop)).toBe(1);+ expect(relayCapacityMessageForBrowser(true, desktop)).toEqual({+ type: "relay-capacity",+ downstreamEdges: 1,+ });+ });++ it.each([+ {+ userAgent: desktop.userAgent,+ userAgentDataMobile: true,+ maxTouchPoints: 0,+ },+ {+ userAgent: "Mozilla/5.0 (Linux; Android 16; Mobile)",+ userAgentDataMobile: false,+ maxTouchPoints: 5,+ },+ {+ userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 19_0 like Mac OS X)",+ maxTouchPoints: 5,+ },+ {+ userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15)",+ userAgentDataMobile: false,+ maxTouchPoints: 5,+ },+ ])("keeps mobile and touch iPadOS browsers as leaves", (environment) => {+ expect(detectBrowserRelayCapacity(environment)).toBe(0);+ });++ it("does not create a relay message for ordinary P2P", () => {+ expect(relayCapacityMessageForBrowser(false)).toBeNull();+ });+});diff --git a/tests/route-transition.test.ts b/tests/route-transition.test.tsnew file mode 100644index 00000000..c71bbde7--- /dev/null+++ b/tests/route-transition.test.ts@@ -0,0 +1,1029 @@+import { describe, expect, it, vi } from "vitest";++import type {+ ClientMessage,+ ParticipantRouteAssignment,+} from "../src/shared/protocol.ts";+import {+ MediaRouteTransition,+ reportActivePeerRouteFailure,+} from "../src/client/media/route-transition.ts";+import { HostSfuRoute } from "../src/client/media/host-sfu-route.ts";+import { ViewerSfuRoute } from "../src/client/media/viewer-sfu-route.ts";+import { QUALITY_PROFILES } from "../src/client/media/quality.ts";++const peerAssignment = (+ parentPeerId: string,+ childPeerIds: string[] = [],+): ParticipantRouteAssignment => ({+ upstream: { kind: "peer", peerId: parentPeerId },+ childPeerIds,+ sfuPublicationGeneration: null,+});++const sfuAssignment = (childPeerIds: string[] = []): ParticipantRouteAssignment => ({+ upstream: { kind: "sfu" },+ childPeerIds,+ sfuPublicationGeneration: null,+});++const hostAssignment = (+ publicationGeneration: string | null,+ childPeerIds: string[] = [],+): ParticipantRouteAssignment => ({+ upstream: { kind: "none" },+ childPeerIds,+ sfuPublicationGeneration: publicationGeneration,+});++function sfuConfig(revision: number) {+ return {+ type: "sfu-config" as const,+ revision,+ url: "wss://sfu.example.test",+ token: `token-${revision}`,+ };+}++function createFakePublisher(log: string[], label: string) {+ return {+ connect: vi.fn(async () => {+ log.push(`${label}:connect`);+ return true;+ }),+ activate: vi.fn(async () => {+ log.push(`${label}:activate`);+ return true;+ }),+ deactivate: vi.fn(async () => {+ log.push(`${label}:deactivate`);+ return true;+ }),+ replaceStream: vi.fn(async () => true),+ updateProfile: vi.fn(async () => true),+ disconnect: vi.fn(async () => {+ log.push(`${label}:disconnect`);+ }),+ };+}++interface FakeSubscriberEvents {+ onStream: (stream: MediaStream | null) => void;+ onDisconnected: () => void;+}++function createFakeSubscriber(+ events: FakeSubscriberEvents,+ log: string[],+ label: string,+) {+ return {+ events,+ connect: vi.fn(async () => {+ log.push(`${label}:connect`);+ return true;+ }),+ activate: vi.fn(() => {+ log.push(`${label}:activate`);+ return true;+ }),+ deactivate: vi.fn(() => {+ log.push(`${label}:deactivate`);+ return true;+ }),+ disconnect: vi.fn(async () => {+ log.push(`${label}:disconnect`);+ }),+ };+}++describe("MediaRouteTransition", () => {+ it("keeps current media through prepare and until an active SFU video track", () => {+ const route = new MediaRouteTransition();+ const direct = peerAssignment("host_12345678", ["child_a_12345678"]);+ const sfu = sfuAssignment(["child_a_12345678"]);++ expect(route.accept({ revision: 1, phase: "active", assignment: direct })).toBe(+ "accepted",+ );+ const directToken = route.token()!;+ expect(route.markMediaActive(directToken)).toBe(true);++ expect(route.accept({ revision: 2, phase: "prepare", assignment: sfu })).toBe(+ "accepted",+ );+ expect(route.getActiveAssignment()).toEqual(direct);+ expect(route.getMediaAssignment()).toEqual(direct);++ expect(route.accept({ revision: 2, phase: "active", assignment: sfu })).toBe(+ "accepted",+ );+ const sfuToken = route.token()!;+ expect(route.getActiveAssignment()).toEqual(sfu);+ expect(route.getMediaAssignment()).toEqual(direct);++ expect(route.markMediaActive(sfuToken)).toBe(true);+ expect(route.getMediaAssignment()).toEqual(sfu);+ });++ it("rejects stale config and async work after a rollback revision", () => {+ const route = new MediaRouteTransition();+ const sfu = sfuAssignment();+ const direct = peerAssignment("host_12345678");++ route.accept({ revision: 4, phase: "prepare", assignment: sfu });+ const staleToken = route.token()!;+ expect(route.acceptsConfig(4)).toBe(true);++ route.accept({ revision: 5, phase: "active", assignment: direct });++ expect(route.acceptsConfig(4)).toBe(false);+ expect(route.owns(staleToken)).toBe(false);+ expect(route.markMediaActive(staleToken)).toBe(false);+ });++ it("is idempotent for duplicates and rejects conflicting same revisions", () => {+ const route = new MediaRouteTransition();+ const direct = peerAssignment("host_12345678");++ expect(route.accept({ revision: 7, phase: "prepare", assignment: direct })).toBe(+ "accepted",+ );+ const token = route.token();+ expect(route.accept({ revision: 7, phase: "prepare", assignment: direct })).toBe(+ "duplicate",+ );+ expect(route.token()).toEqual(token);+ expect(+ route.accept({+ revision: 7,+ phase: "prepare",+ assignment: peerAssignment("other_12345678"),+ }),+ ).toBe("stale");+ });++ it("returns signaling failure so ViewerPeer can retry its route report", () => {+ const route = new MediaRouteTransition();+ const assignment = peerAssignment("host_12345678");+ route.accept({ revision: 9, phase: "active", assignment });+ const send = vi.fn(() => false);++ expect(+ reportActivePeerRouteFailure(+ route,+ "host_12345678",+ "connection_12345678",+ send,+ ),+ ).toBe(false);+ expect(send).toHaveBeenCalledWith({+ type: "route-failed",+ revision: 9,+ phase: "active",+ connectionId: "connection_12345678",+ });+ });+});++describe("HostSfuRoute", () => {+ it("reports a publisher prepare failure without requesting refresh", async () => {+ const messages: ClientMessage[] = [];+ const publisher = createFakePublisher([], "publisher");+ publisher.connect.mockResolvedValue(false);+ const route = new HostSfuRoute({+ getStream: () => ({}) as MediaStream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: () => undefined,+ send: (message) => {+ messages.push(message);+ return true;+ },+ createPublisher: () => publisher,+ });++ route.accept({+ revision: 1,+ phase: "prepare",+ assignment: hostAssignment("generation-a"),+ });+ await route.acceptConfig(sfuConfig(1));++ expect(messages).toEqual([+ {+ type: "route-failed",+ revision: 1,+ phase: "prepare",+ connectionId: null,+ },+ ]);+ });++ it("never overlaps more than two host media edges while changing route kinds", async () => {+ const log: string[] = [];+ const edgeCounts: number[] = [];+ const publishers: Array<{+ connect: ReturnType<typeof vi.fn>;+ activate: ReturnType<typeof vi.fn>;+ deactivate: ReturnType<typeof vi.fn>;+ replaceStream: ReturnType<typeof vi.fn>;+ updateProfile: ReturnType<typeof vi.fn>;+ disconnect: ReturnType<typeof vi.fn>;+ }> = [];+ let directEdges = 0;+ let sfuEdges = 0;+ const record = (event: string) => {+ log.push(event);+ edgeCounts.push(directEdges + sfuEdges);+ };+ const route = new HostSfuRoute({+ getStream: () => ({}) as MediaStream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: (children) => {+ directEdges = children.length;+ record(`children:${children.join(",")}`);+ },+ send: () => true,+ createPublisher: () => {+ const label = `publisher-${publishers.length + 1}`;+ const publisher = {+ connect: vi.fn(async () => true),+ activate: vi.fn(async () => {+ sfuEdges = 1;+ record(`${label}:activate`);+ return true;+ }),+ deactivate: vi.fn(async () => {+ sfuEdges = 0;+ record(`${label}:deactivate`);+ return true;+ }),+ replaceStream: vi.fn(async () => true),+ updateProfile: vi.fn(async () => true),+ disconnect: vi.fn(async () => record(`${label}:disconnect`)),+ };+ publishers.push(publisher);+ return publisher;+ },+ });++ route.accept({+ revision: 1,+ phase: "active",+ assignment: hostAssignment(null, ["direct-a", "direct-b"]),+ });+ await vi.waitFor(() => expect(log).toContain("children:direct-a,direct-b"));++ const generationA = hostAssignment("generation-a", ["direct-a"]);+ route.accept({ revision: 2, phase: "prepare", assignment: generationA });+ await route.acceptConfig(sfuConfig(2));+ log.length = 0;+ route.accept({ revision: 2, phase: "active", assignment: generationA });+ await vi.waitFor(() => expect(publishers[0]?.activate).toHaveBeenCalledOnce());+ expect(log.slice(0, 2)).toEqual([+ "children:direct-a",+ "publisher-1:activate",+ ]);++ const generationB = hostAssignment("generation-b", ["direct-b"]);+ route.accept({ revision: 3, phase: "prepare", assignment: generationB });+ await route.acceptConfig(sfuConfig(3));+ log.length = 0;+ route.accept({ revision: 3, phase: "active", assignment: generationB });+ await vi.waitFor(() => expect(publishers[1]?.activate).toHaveBeenCalledOnce());+ expect(log.slice(0, 4)).toEqual([+ "children:direct-b",+ "publisher-1:deactivate",+ "publisher-1:disconnect",+ "publisher-2:activate",+ ]);++ log.length = 0;+ route.accept({+ revision: 4,+ phase: "active",+ assignment: hostAssignment(null, ["direct-a", "direct-b"]),+ });+ await vi.waitFor(() =>+ expect(log).toContain("children:direct-a,direct-b"),+ );+ expect(log.slice(0, 3)).toEqual([+ "publisher-2:deactivate",+ "publisher-2:disconnect",+ "children:direct-a,direct-b",+ ]);+ expect(Math.max(...edgeCounts)).toBeLessThanOrEqual(2);+ });++ it("serializes continuous active revisions while the old publisher retires", async () => {+ const publishers: ReturnType<typeof createFakePublisher>[] = [];+ const route = new HostSfuRoute({+ getStream: () => ({}) as MediaStream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: () => undefined,+ send: () => true,+ createPublisher: () => {+ const publisher = createFakePublisher(+ [],+ `publisher-${publishers.length + 1}`,+ );+ publishers.push(publisher);+ return publisher;+ },+ });++ const generationA = hostAssignment("generation-a", ["direct-a"]);+ route.accept({ revision: 1, phase: "prepare", assignment: generationA });+ await route.acceptConfig(sfuConfig(1));+ route.accept({ revision: 1, phase: "active", assignment: generationA });+ await vi.waitFor(() => expect(publishers[0]?.activate).toHaveBeenCalledOnce());++ let finishOldDeactivate!: () => void;+ let oldDeactivateFinished = false;+ const oldDeactivateGate = new Promise<void>((resolve) => {+ finishOldDeactivate = resolve;+ });+ publishers[0]?.deactivate.mockImplementation(async () => {+ await oldDeactivateGate;+ oldDeactivateFinished = true;+ return true;+ });++ const generationB = hostAssignment("generation-b", ["direct-b"]);+ route.accept({ revision: 2, phase: "prepare", assignment: generationB });+ await route.acceptConfig(sfuConfig(2));+ route.accept({ revision: 2, phase: "active", assignment: generationB });+ await vi.waitFor(() => expect(publishers[0]?.deactivate).toHaveBeenCalled());++ const generationC = hostAssignment("generation-c", ["direct-c"]);+ route.accept({ revision: 3, phase: "prepare", assignment: generationC });+ await route.acceptConfig(sfuConfig(3));+ route.accept({ revision: 3, phase: "active", assignment: generationC });++ expect(publishers[2]?.disconnect).not.toHaveBeenCalled();+ expect(publishers[1]?.activate).not.toHaveBeenCalled();+ expect(publishers[2]?.activate).not.toHaveBeenCalled();++ finishOldDeactivate();+ await vi.waitFor(() => expect(oldDeactivateFinished).toBe(true));+ expect(publishers[2]?.disconnect).not.toHaveBeenCalled();+ await vi.waitFor(() => expect(publishers[2]?.activate).toHaveBeenCalledOnce());+ expect(publishers[1]?.activate).not.toHaveBeenCalled();+ });++ it("releases active ownership when a published activation becomes stale", async () => {+ const streamA = {} as MediaStream;+ const streamB = {} as MediaStream;+ let currentStream = streamA;+ const publishers: ReturnType<typeof createFakePublisher>[] = [];+ const route = new HostSfuRoute({+ getStream: () => currentStream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: () => undefined,+ send: () => true,+ createPublisher: () => {+ const publisher = createFakePublisher(+ [],+ `publisher-${publishers.length + 1}`,+ );+ publishers.push(publisher);+ return publisher;+ },+ });++ const generationA = hostAssignment("generation-a");+ route.accept({ revision: 1, phase: "prepare", assignment: generationA });+ await route.acceptConfig(sfuConfig(1));++ let finishReplace!: () => void;+ const replaceGate = new Promise<void>((resolve) => {+ finishReplace = resolve;+ });+ publishers[0]?.activate.mockImplementation(async () => {+ currentStream = streamB;+ return true;+ });+ publishers[0]?.replaceStream.mockImplementation(async () => {+ await replaceGate;+ return true;+ });++ route.accept({ revision: 1, phase: "active", assignment: generationA });+ await vi.waitFor(() => expect(publishers[0]?.replaceStream).toHaveBeenCalled());++ const generationB = hostAssignment("generation-b");+ route.accept({ revision: 2, phase: "prepare", assignment: generationB });+ await route.acceptConfig(sfuConfig(2));+ finishReplace();+ await vi.waitFor(() => expect(publishers[0]?.disconnect).toHaveBeenCalled());++ await expect(+ route.updateProfile(QUALITY_PROFILES["1080p30"]),+ ).resolves.toBe(true);+ expect(publishers[0]?.updateProfile).not.toHaveBeenCalled();+ expect(publishers[1]?.disconnect).not.toHaveBeenCalled();++ route.accept({ revision: 2, phase: "active", assignment: generationB });+ await vi.waitFor(() => expect(publishers[1]?.activate).toHaveBeenCalledOnce());+ });++ it("keeps an activating publisher on a duplicate active update", async () => {+ const messages: ClientMessage[] = [];+ const publisher = createFakePublisher([], "publisher");+ let finishActivate!: () => void;+ const activateGate = new Promise<void>((resolve) => {+ finishActivate = resolve;+ });+ publisher.activate.mockImplementation(async () => {+ await activateGate;+ return true;+ });+ const route = new HostSfuRoute({+ getStream: () => ({}) as MediaStream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: () => undefined,+ send: (message) => {+ messages.push(message);+ return true;+ },+ createPublisher: () => publisher,+ });+ const assignment = hostAssignment("generation-a");++ route.accept({ revision: 1, phase: "prepare", assignment });+ await route.acceptConfig(sfuConfig(1));+ route.accept({ revision: 1, phase: "active", assignment });+ await vi.waitFor(() => expect(publisher.activate).toHaveBeenCalledOnce());++ expect(+ route.accept({ revision: 1, phase: "active", assignment }),+ ).toBe("duplicate");+ expect(publisher.activate).toHaveBeenCalledOnce();+ expect(publisher.disconnect).not.toHaveBeenCalled();++ finishActivate();+ await vi.waitFor(() =>+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 1,+ phase: "active",+ }),+ );+ expect(publisher.disconnect).not.toHaveBeenCalled();+ });++ it("prepares without media, commits in order, and reuses a publication generation", async () => {+ const log: string[] = [];+ const messages: ClientMessage[] = [];+ const publishers: ReturnType<typeof createFakePublisher>[] = [];+ const stream = {} as MediaStream;+ const route = new HostSfuRoute({+ getStream: () => stream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: (children) => log.push(`children:${children.join(",")}`),+ send: (message) => {+ messages.push(message);+ return true;+ },+ createPublisher: () => {+ const publisher = createFakePublisher(+ log,+ `publisher-${publishers.length + 1}`,+ );+ publishers.push(publisher);+ return publisher;+ },+ });++ const generationA = hostAssignment("generation-a", ["direct-a"]);+ route.accept({ revision: 1, phase: "prepare", assignment: generationA });+ await route.acceptConfig(sfuConfig(1));++ expect(publishers[0]?.activate).not.toHaveBeenCalled();+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 1,+ phase: "prepare",+ });++ route.accept({ revision: 1, phase: "active", assignment: generationA });+ await vi.waitFor(() => expect(publishers[0]?.activate).toHaveBeenCalledOnce());++ const generationB = hostAssignment("generation-b", ["direct-b"]);+ route.accept({ revision: 2, phase: "prepare", assignment: generationB });+ await route.acceptConfig(sfuConfig(2));+ expect(publishers[0]?.deactivate).not.toHaveBeenCalled();+ expect(publishers[1]?.activate).not.toHaveBeenCalled();++ log.length = 0;+ route.accept({ revision: 2, phase: "active", assignment: generationB });+ await vi.waitFor(() => expect(publishers[1]?.activate).toHaveBeenCalledOnce());+ expect(log.slice(0, 4)).toEqual([+ "children:direct-b",+ "publisher-1:deactivate",+ "publisher-1:disconnect",+ "publisher-2:activate",+ ]);++ route.accept({+ revision: 3,+ phase: "active",+ assignment: hostAssignment("generation-b", ["direct-c"]),+ });+ await vi.waitFor(() =>+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 3,+ phase: "active",+ }),+ );+ expect(publishers).toHaveLength(2);+ expect(publishers[1]?.deactivate).not.toHaveBeenCalled();++ route.accept({+ revision: 4,+ phase: "prepare",+ assignment: hostAssignment("generation-c"),+ });+ await route.acceptConfig(sfuConfig(4));+ route.accept({+ revision: 5,+ phase: "active",+ assignment: hostAssignment("generation-b", ["direct-c"]),+ });+ await vi.waitFor(() => expect(publishers[2]?.disconnect).toHaveBeenCalled());+ expect(publishers[1]?.deactivate).not.toHaveBeenCalled();+ });++ it("retires old media before applying a lower authoritative host revision", async () => {+ const log: string[] = [];+ const publisher = createFakePublisher(log, "publisher");+ const route = new HostSfuRoute({+ getStream: () => ({}) as MediaStream,+ getProfile: () => QUALITY_PROFILES["720p30"],+ reconcileChildren: (children) =>+ log.push(`children:${children.join(",")}`),+ send: () => true,+ createPublisher: () => publisher,+ });++ const oldAssignment = hostAssignment("generation-old");+ route.accept({ revision: 10, phase: "prepare", assignment: oldAssignment });+ await route.acceptConfig(sfuConfig(10));+ route.accept({ revision: 10, phase: "active", assignment: oldAssignment });+ await vi.waitFor(() => expect(publisher.activate).toHaveBeenCalledOnce());++ let finishDeactivate!: () => void;+ const deactivateGate = new Promise<void>((resolve) => {+ finishDeactivate = resolve;+ });+ publisher.deactivate.mockImplementation(async () => {+ log.push("publisher:deactivate");+ await deactivateGate;+ return true;+ });+ log.length = 0;++ const authoritative = hostAssignment(null, ["new-child-a", "new-child-b"]);+ const resync = route.resyncAuthoritative({+ revision: 1,+ phase: "active",+ assignment: authoritative,+ });+ await vi.waitFor(() => expect(publisher.deactivate).toHaveBeenCalledOnce());+ expect(log).toEqual(["children:", "publisher:deactivate"]);++ finishDeactivate();+ await expect(resync).resolves.toBe("accepted");+ expect(log).toEqual([+ "children:",+ "publisher:deactivate",+ "publisher:disconnect",+ "children:new-child-a,new-child-b",+ ]);++ await expect(+ route.resyncAuthoritative({+ revision: 1,+ phase: "active",+ assignment: authoritative,+ }),+ ).resolves.toBe("duplicate");+ expect(publisher.disconnect).toHaveBeenCalledOnce();+ });+});++describe("ViewerSfuRoute", () => {+ it("reports a subscriber prepare failure without requesting refresh", async () => {+ const messages: ClientMessage[] = [];+ const subscriber = createFakeSubscriber(+ { onStream: () => undefined, onDisconnected: () => undefined },+ [],+ "subscriber",+ );+ subscriber.connect.mockResolvedValue(false);+ const route = new ViewerSfuRoute({+ activatePeer: () => undefined,+ reconcileSfuChildren: () => undefined,+ onSfuStream: () => undefined,+ send: (message) => {+ messages.push(message);+ return true;+ },+ createSubscriber: () => subscriber,+ });++ route.accept({+ revision: 1,+ phase: "prepare",+ assignment: sfuAssignment(),+ });+ await route.acceptConfig(sfuConfig(1));++ expect(messages).toEqual([+ {+ type: "route-failed",+ revision: 1,+ phase: "prepare",+ connectionId: null,+ },+ ]);+ });++ it("buffers an assigned parent offer until SFU fallback retirement completes", async () => {+ const log: string[] = [];+ const bufferedSignals: string[] = [];+ const deliveredSignals: string[] = [];+ let preparedParentPeerId: string | null = null;+ const subscribers: ReturnType<typeof createFakeSubscriber>[] = [];+ const route = new ViewerSfuRoute({+ activatePeer: (assignment) => {+ const peerId =+ assignment.upstream.kind === "peer"+ ? assignment.upstream.peerId+ : "none";+ log.push(`peer:${peerId}`);+ if (peerId === preparedParentPeerId) {+ deliveredSignals.push(...bufferedSignals.splice(0));+ preparedParentPeerId = null;+ }+ },+ preparePeer: (assignment) => {+ preparedParentPeerId =+ assignment?.upstream.kind === "peer"+ ? assignment.upstream.peerId+ : null;+ },+ reconcileSfuChildren: () => undefined,+ onSfuStream: () => undefined,+ send: () => true,+ createSubscriber: (events) => {+ const subscriber = createFakeSubscriber(+ events,+ log,+ `subscriber-${subscribers.length + 1}`,+ );+ subscribers.push(subscriber);+ return subscriber;+ },+ });+ const sfu = sfuAssignment();++ route.accept({ revision: 1, phase: "prepare", assignment: sfu });+ await route.acceptConfig(sfuConfig(1));+ route.accept({ revision: 1, phase: "active", assignment: sfu });+ await vi.waitFor(() =>+ expect(subscribers[0]?.activate).toHaveBeenCalledOnce(),+ );+ subscribers[0]?.events.onStream({} as MediaStream);++ let finishDisconnect!: () => void;+ const disconnectGate = new Promise<void>((resolve) => {+ finishDisconnect = resolve;+ });+ subscribers[0]?.disconnect.mockImplementation(async () => {+ log.push("subscriber-1:disconnect");+ await disconnectGate;+ });++ log.length = 0;+ route.accept({+ revision: 2,+ phase: "active",+ assignment: peerAssignment("host-peer"),+ });+ expect(preparedParentPeerId).toBe("host-peer");+ bufferedSignals.push("early-offer");+ expect(deliveredSignals).toEqual([]);+ await vi.waitFor(() =>+ expect(subscribers[0]?.disconnect).toHaveBeenCalledOnce(),+ );+ expect(log).toEqual([+ "subscriber-1:deactivate",+ "subscriber-1:disconnect",+ ]);++ finishDisconnect();+ await vi.waitFor(() => expect(log).toContain("peer:host-peer"));+ expect(log.slice(0, 3)).toEqual([+ "subscriber-1:deactivate",+ "subscriber-1:disconnect",+ "peer:host-peer",+ ]);+ expect(deliveredSignals).toEqual(["early-offer"]);+ });++ it("keeps peer media through prepare and switches on the first video stream callback", async () => {+ const log: string[] = [];+ const messages: ClientMessage[] = [];+ const peerAssignments: ParticipantRouteAssignment[] = [];+ const streams: Array<{+ stream: MediaStream;+ initialVideoStream: boolean;+ assignment: ParticipantRouteAssignment;+ }> = [];+ const subscribers: ReturnType<typeof createFakeSubscriber>[] = [];+ const route = new ViewerSfuRoute({+ activatePeer: (assignment) => {+ peerAssignments.push(assignment);+ },+ reconcileSfuChildren: (children) => log.push(`children:${children.join(",")}`),+ onSfuStream: (stream, assignment, initialVideoStream) => {+ streams.push({ stream, assignment, initialVideoStream });+ },+ send: (message) => {+ messages.push(message);+ return true;+ },+ createSubscriber: (events) => {+ const subscriber = createFakeSubscriber(+ events,+ log,+ `subscriber-${subscribers.length + 1}`,+ );+ subscribers.push(subscriber);+ return subscriber;+ },+ });++ route.accept({+ revision: 1,+ phase: "active",+ assignment: peerAssignment("host-peer"),+ });+ await vi.waitFor(() => expect(peerAssignments).toHaveLength(1));+ const nextAssignment = sfuAssignment(["relay-child"]);+ route.accept({ revision: 2, phase: "prepare", assignment: nextAssignment });+ await route.acceptConfig(sfuConfig(2));++ expect(peerAssignments).toHaveLength(1);+ expect(streams).toHaveLength(0);+ expect(subscribers[0]?.activate).not.toHaveBeenCalled();+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 2,+ phase: "prepare",+ });++ route.accept({ revision: 2, phase: "active", assignment: nextAssignment });+ await vi.waitFor(() =>+ expect(subscribers[0]?.activate).toHaveBeenCalledOnce(),+ );+ expect(streams).toHaveLength(0);+ expect(messages).not.toContainEqual({+ type: "route-ready",+ revision: 2,+ phase: "active",+ });++ const stream = {} as MediaStream;+ subscribers[0]?.events.onStream(stream);+ expect(streams).toEqual([+ { stream, assignment: nextAssignment, initialVideoStream: true },+ ]);+ expect(messages).toContainEqual({+ type: "route-ready",+ revision: 2,+ phase: "active",+ });++ route.accept({+ revision: 3,+ phase: "active",+ assignment: sfuAssignment(["other-child"]),+ });+ expect(subscribers).toHaveLength(1);+ expect(subscribers[0]?.deactivate).not.toHaveBeenCalled();++ route.accept({+ revision: 4,+ phase: "prepare",+ assignment: sfuAssignment(),+ });+ await route.acceptConfig(sfuConfig(4));+ route.accept({+ revision: 5,+ phase: "active",+ assignment: sfuAssignment(["other-child"]),+ });+ await vi.waitFor(() => expect(subscribers[1]?.disconnect).toHaveBeenCalled());+ expect(subscribers[0]?.deactivate).not.toHaveBeenCalled();+ expect(streams).toHaveLength(1);+ });++ it("disconnects a subscriber whose connect completes after rollback", async () => {+ let finishConnect!: () => void;+ const connectGate = new Promise<void>((resolve) => {+ finishConnect = resolve;+ });+ const messages: ClientMessage[] = [];+ const subscriber = {+ connect: vi.fn(async () => {+ await connectGate;+ return true;+ }),+ activate: vi.fn(() => true),+ deactivate: vi.fn(() => true),+ disconnect: vi.fn(async () => undefined),+ };+ const route = new ViewerSfuRoute({+ activatePeer: () => undefined,+ reconcileSfuChildren: () => undefined,+ onSfuStream: () => undefined,+ send: (message) => {+ messages.push(message);+ return true;+ },+ createSubscriber: () => subscriber,+ });++ route.accept({+ revision: 10,+ phase: "prepare",+ assignment: sfuAssignment(),+ });+ const connecting = route.acceptConfig(sfuConfig(10));+ route.accept({+ revision: 11,+ phase: "active",+ assignment: peerAssignment("host-peer"),+ });+ finishConnect();+ await connecting;++ expect(subscriber.activate).not.toHaveBeenCalled();+ expect(subscriber.disconnect).toHaveBeenCalled();+ expect(messages).not.toContainEqual({+ type: "route-ready",+ revision: 10,+ phase: "prepare",+ });+ });++ it("refreshes once after terminal loss and reports a failed rebuild", async () => {+ const messages: ClientMessage[] = [];+ const subscribers: ReturnType<typeof createFakeSubscriber>[] = [];+ const route = new ViewerSfuRoute({+ activatePeer: () => undefined,+ reconcileSfuChildren: () => undefined,+ onSfuStream: () => undefined,+ send: (message) => {+ messages.push(message);+ return true;+ },+ createSubscriber: (events) => {+ const subscriber = createFakeSubscriber(+ events,+ [],+ `subscriber-${subscribers.length + 1}`,+ );+ if (subscribers.length === 1) {+ subscriber.connect.mockResolvedValue(false);+ }+ subscribers.push(subscriber);+ return subscriber;+ },+ });+ const assignment = sfuAssignment();++ route.accept({ revision: 20, phase: "prepare", assignment });+ await route.acceptConfig(sfuConfig(20));+ route.accept({ revision: 20, phase: "active", assignment });+ await vi.waitFor(() =>+ expect(subscribers[0]?.activate).toHaveBeenCalledOnce(),+ );+ subscribers[0]?.events.onStream({} as MediaStream);+ messages.length = 0;++ subscribers[0]?.events.onDisconnected();+ expect(messages).toEqual([{ type: "refresh-sfu", revision: 20 }]);++ await route.acceptConfig(sfuConfig(20));+ expect(messages).toEqual([+ { type: "refresh-sfu", revision: 20 },+ {+ type: "route-failed",+ revision: 20,+ phase: "active",+ connectionId: null,+ },+ ]);+ });++ it("retires old media before applying a lower authoritative viewer revision", async () => {+ const log: string[] = [];+ const bufferedSignals: string[] = [];+ const deliveredSignals: string[] = [];+ let preparedParentPeerId: string | null = null;+ const subscribers: ReturnType<typeof createFakeSubscriber>[] = [];+ const route = new ViewerSfuRoute({+ activatePeer: (assignment) => {+ const upstream = assignment.upstream;+ log.push(+ `peer:${upstream.kind === "peer" ? upstream.peerId : upstream.kind}`,+ );+ if (+ upstream.kind === "peer" &&+ upstream.peerId === preparedParentPeerId+ ) {+ deliveredSignals.push(...bufferedSignals.splice(0));+ preparedParentPeerId = null;+ }+ },+ preparePeer: (assignment) => {+ preparedParentPeerId =+ assignment?.upstream.kind === "peer"+ ? assignment.upstream.peerId+ : null;+ },+ resetMedia: () => log.push("reset-media"),+ reconcileSfuChildren: () => undefined,+ onSfuStream: () => undefined,+ send: () => true,+ createSubscriber: (events) => {+ const subscriber = createFakeSubscriber(+ events,+ log,+ `subscriber-${subscribers.length + 1}`,+ );+ subscribers.push(subscriber);+ return subscriber;+ },+ });++ route.accept({ revision: 10, phase: "prepare", assignment: sfuAssignment() });+ await route.acceptConfig(sfuConfig(10));+ route.accept({ revision: 10, phase: "active", assignment: sfuAssignment() });+ await vi.waitFor(() =>+ expect(subscribers[0]?.activate).toHaveBeenCalledOnce(),+ );+ subscribers[0]?.events.onStream({} as MediaStream);+ log.length = 0;++ let finishDisconnect!: () => void;+ const disconnectGate = new Promise<void>((resolve) => {+ finishDisconnect = resolve;+ });+ subscribers[0]?.disconnect.mockImplementation(async () => {+ log.push("subscriber-1:disconnect");+ await disconnectGate;+ });++ const authoritative = peerAssignment("new-host-peer");+ const resync = route.resyncAuthoritative({+ revision: 1,+ phase: "active",+ assignment: authoritative,+ });+ expect(preparedParentPeerId).toBe("new-host-peer");+ bufferedSignals.push("early-resync-offer");+ expect(deliveredSignals).toEqual([]);+ await vi.waitFor(() =>+ expect(subscribers[0]?.disconnect).toHaveBeenCalledOnce(),+ );+ expect(log).toEqual([+ "reset-media",+ "subscriber-1:deactivate",+ "subscriber-1:disconnect",+ ]);++ finishDisconnect();+ await expect(resync).resolves.toBe("accepted");+ expect(log).toEqual([+ "reset-media",+ "subscriber-1:deactivate",+ "subscriber-1:disconnect",+ "peer:new-host-peer",+ ]);+ expect(deliveredSignals).toEqual(["early-resync-offer"]);++ await expect(+ route.resyncAuthoritative({+ revision: 1,+ phase: "active",+ assignment: authoritative,+ }),+ ).resolves.toBe("duplicate");+ expect(subscribers[0]?.disconnect).toHaveBeenCalledOnce();+ });+});diff --git a/tests/server-config.test.ts b/tests/server-config.test.tsindex 81205eee..ee8a0f00 100644--- a/tests/server-config.test.ts+++ b/tests/server-config.test.ts@@ -15,6 +15,165 @@ describe("server configuration", () => {expect(config.turnUrls).toEqual([]);expect(config.maxViewersPerRoom).toBe(8);expect(config.peerAssistedMedia).toBe(false);+ expect(config.livekitFallback).toBeUndefined();+ });++ it("enables LiveKit fallback only for a complete credential tuple", () => {+ const config = loadConfig({+ PEER_ASSISTED_MEDIA: "true",+ LIVEKIT_URL: " ws://livekit.test:7880 ",+ LIVEKIT_API_KEY: " test-key ",+ LIVEKIT_API_SECRET: ` ${"s".repeat(32)} `,+ });++ expect(config.livekitFallback).toEqual({+ url: "ws://livekit.test:7880",+ apiKey: "test-key",+ apiSecret: "s".repeat(32),+ maxSfuRootsPerRoom: 2,+ });+ });++ it.each(["1", "2"])(+ "accepts an SFU root limit of %s when fallback is configured",+ (maxSfuRootsPerRoom) => {+ const config = loadConfig({+ PEER_ASSISTED_MEDIA: "true",+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "s".repeat(32),+ MAX_SFU_ROOTS_PER_ROOM: maxSfuRootsPerRoom,+ });++ expect(config.livekitFallback?.maxSfuRootsPerRoom).toBe(+ Number(maxSfuRootsPerRoom),+ );+ },+ );++ it("does not activate fallback from the root limit alone", () => {+ expect(+ loadConfig({ MAX_SFU_ROOTS_PER_ROOM: "2" }).livekitFallback,+ ).toBeUndefined();+ });++ it("requires peer-assisted media for LiveKit fallback", () => {+ expect(() =>+ loadConfig({+ PEER_ASSISTED_MEDIA: "false",+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "s".repeat(32),+ }),+ ).toThrow("LiveKit fallback requires PEER_ASSISTED_MEDIA=true");+ });++ it.each([+ { LIVEKIT_URL: "wss://livekit.test" },+ { LIVEKIT_API_KEY: "test-key" },+ { LIVEKIT_API_SECRET: "s".repeat(32) },+ {+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ },+ ])("rejects a partial LiveKit credential tuple", (partial) => {+ expect(() => loadConfig(partial)).toThrow(+ "LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET must be configured together",+ );+ });++ it.each([+ "https://livekit.test",+ "wss://user:[email protected]",+ "wss://livekit.test/rtc",+ "wss://livekit.test?token=value",+ "wss://livekit.test#fragment",+ ])("rejects an invalid LiveKit origin: %s", (url) => {+ expect(() =>+ loadConfig({+ LIVEKIT_URL: url,+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "s".repeat(32),+ }),+ ).toThrow("LIVEKIT_URL");+ });++ it("requires wss for LiveKit fallback in production", () => {+ expect(() =>+ loadConfig({+ NODE_ENV: "production",+ PUBLIC_BASE_URL: "https://share.test",+ LIVEKIT_URL: "ws://livekit.test:7880",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "s".repeat(32),+ }),+ ).toThrow("LIVEKIT_URL must use wss in production");+ });++ it("rejects a short LiveKit API secret and invalid root limits", () => {+ const fallback = {+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "s".repeat(32),+ };++ expect(() =>+ loadConfig({ ...fallback, LIVEKIT_API_SECRET: "too-short" }),+ ).toThrow("LIVEKIT_API_SECRET must contain at least 32 bytes");+ for (const maxSfuRootsPerRoom of ["0", "3", "1.5"]) {+ expect(() =>+ loadConfig({+ ...fallback,+ MAX_SFU_ROOTS_PER_ROOM: maxSfuRootsPerRoom,+ }),+ ).toThrow("MAX_SFU_ROOTS_PER_ROOM");+ }+ });++ it("keeps production STUN and TURN mandatory with LiveKit configured", () => {+ expect(() =>+ loadConfig({+ NODE_ENV: "production",+ PUBLIC_BASE_URL: "https://share.test",+ PEER_ASSISTED_MEDIA: "true",+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "s".repeat(32),+ }),+ ).toThrow("TURN is required in production");+ });++ it.each([+ {+ ACCESS_PASSWORD: "x".repeat(32),+ TURN_URLS: "turn:turn.test:3478",+ TURN_SHARED_SECRET: "x".repeat(32),+ },+ {+ ACCESS_PASSWORD: "x".repeat(32),+ PEER_ASSISTED_MEDIA: "true",+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "x".repeat(32),+ },+ {+ TURN_URLS: "turn:turn.test:3478",+ TURN_SHARED_SECRET: "x".repeat(32),+ PEER_ASSISTED_MEDIA: "true",+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "test-key",+ LIVEKIT_API_SECRET: "x".repeat(32),+ },+ {+ PEER_ASSISTED_MEDIA: "true",+ LIVEKIT_URL: "wss://livekit.test",+ LIVEKIT_API_KEY: "x".repeat(32),+ LIVEKIT_API_SECRET: "x".repeat(32),+ },+ ])("rejects reused infrastructure secrets", (environment) => {+ expect(() => loadConfig(environment)).toThrow(+ "ACCESS_PASSWORD, TURN_SHARED_SECRET, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET must use independent values",+ );});it("requires an explicit boolean to enable peer-assisted media", () => {diff --git a/tests/server-http.test.ts b/tests/server-http.test.tsindex 80636a30..8980ead0 100644--- a/tests/server-http.test.ts+++ b/tests/server-http.test.ts@@ -52,7 +52,10 @@ function testConfig(overrides: Partial<ServerConfig> = {}): ServerConfig {async function start(config = testConfig(),- options: Pick<CreateServerOptions, "now" | "accessSessionTtlSeconds"> = {},+ options: Pick<+ CreateServerOptions,+ "now" | "accessSessionTtlSeconds" | "sfuTokenIssuer"+ > = {},): Promise<string> {runningServer = await createScreenerServer({...options,@@ -335,6 +338,28 @@ describe("room HTTP API", () => {});describe("server HTTP listener and health", () => {+ it("starts with an injected optional SFU token issuer", async () => {+ const baseUrl = await start(+ testConfig({+ peerAssistedMedia: true,+ livekitFallback: {+ url: "ws://livekit.test:7880",+ apiKey: "test-key",+ apiSecret: "s".repeat(32),+ maxSfuRootsPerRoom: 2,+ },+ }),+ {+ sfuTokenIssuer: {+ issueToken: async () => "unused-test-token",+ },+ },+ );++ const response = await fetch(`${baseUrl}/healthz`);+ expect(response.status).toBe(200);+ });+it("uses the configured listen host by default", async () => {runningServer = await createScreenerServer({config: testConfig(),diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 0604b0b6..b2ae694c 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -1,4 +1,5 @@import { connect } from "node:net";+import { createServer } from "node:http";import { afterEach, describe, expect, it } from "vitest";import WebSocket from "ws";@@ -16,6 +17,8 @@ import {import type { ServerConfig } from "../src/server/config.ts";import { RoomDatabase } from "../src/server/room-database.ts";import { RoomStore, type CreatedRoom } from "../src/server/room-store.ts";+import { SignalingServer } from "../src/server/signaling.ts";+import type { SfuTokenIssuer } from "../src/server/livekit-token.ts";const allowedOrigin = "http://allowed.test";let runningServer: ScreenerServer | undefined;@@ -27,6 +30,7 @@ afterEach(async () => {class MessageInbox {private readonly messages: ServerMessage[] = [];+ private readonly ignoredTypes = new Set<ServerMessage["type"]>();private readonly waiters: Array<{type: ServerMessage["type"];resolve: (message: ServerMessage) => void;@@ -37,6 +41,9 @@ class MessageInbox {constructor(socket: WebSocket) {socket.on("message", (data) => {const message = decodeServerMessage(data.toString());+ if (this.ignoredTypes.has(message.type)) {+ return;+ }const waiterIndex = this.waiters.findIndex((waiter) => waiter.type === message.type);if (waiterIndex === -1) {this.messages.push(message);@@ -85,6 +92,15 @@ class MessageInbox {throw new Error(`Unexpected message: ${this.messages[0].type}`);}}++ ignore(type: ServerMessage["type"]): void {+ this.ignoredTypes.add(type);+ for (let index = this.messages.length - 1; index >= 0; index -= 1) {+ if (this.messages[index]?.type === type) {+ this.messages.splice(index, 1);+ }+ }+ }}interface TestClient {@@ -161,6 +177,77 @@ async function startHarness(};}+async function startSfuHarness(options: {+ tokenIssuer: SfuTokenIssuer;+ prepareTimeoutMs?: number;+ maxRoots?: number;+ viewerDisconnectGraceMs?: number;+}): Promise<SignalHarness> {+ const roomStore = new RoomStore({+ ttlMs: 14_400_000,+ maxRooms: 10,+ maxViewersPerRoom: 8,+ });+ const room = roomStore.createRoom();+ const httpServer = createServer((_request, response) => {+ response.statusCode = 404;+ response.end();+ });+ const signaling = new SignalingServer({+ server: httpServer,+ roomStore,+ peerAssistedMedia: true,+ sfuFallback: {+ url: "wss://sfu.example.test",+ tokenIssuer: options.tokenIssuer,+ maxRoots: options.maxRoots ?? 2,+ prepareTimeoutMs: options.prepareTimeoutMs,+ },+ ice: {+ stunUrls: [],+ turnUrls: [],+ credentialTtlSeconds: 3_600,+ },+ allowedOrigins: new Set([allowedOrigin]),+ authorizeUpgrade: () => true,+ authenticationTimeoutMs: 500,+ viewerDisconnectGraceMs: options.viewerDisconnectGraceMs ?? 50,+ heartbeatIntervalMs: 60_000,+ cleanupIntervalMs: 60_000,+ });+ runningServer = {+ httpServer,+ roomStore,+ listen: (port = 0, host = "127.0.0.1") =>+ new Promise<number>((resolve, reject) => {+ httpServer.once("error", reject);+ httpServer.listen(port, host, () => {+ httpServer.off("error", reject);+ const address = httpServer.address();+ if (!address || typeof address === "string") {+ reject(new Error("Test HTTP server has no TCP address"));+ return;+ }+ resolve(address.port);+ });+ }),+ async close() {+ await signaling.close();+ await new Promise<void>((resolve, reject) => {+ httpServer.close((error) => (error ? reject(error) : resolve()));+ });+ roomStore.close();+ },+ };+ const port = await runningServer.listen();+ return {+ baseUrl: `http://127.0.0.1:${port}`,+ webSocketUrl: `ws://127.0.0.1:${port}/signal`,+ roomStore,+ room,+ };+}+async function openClient(webSocketUrl: string,cookie?: string,@@ -229,6 +316,8 @@ async function authenticate(room: CreatedRoom,role: Role,clientId: string,+ relayCapacity: 0 | 1 | null = 1,+ shareGeneration?: string,) {client.socket.send(JSON.stringify(@@ -239,6 +328,7 @@ async function authenticate(role,token: room.hostToken,clientId,+ ...(shareGeneration ? { shareGeneration } : {}),}: {type: "authenticate",@@ -248,7 +338,20 @@ async function authenticate(},),);- return client.inbox.next("authenticated");+ const authenticated = await client.inbox.next("authenticated");+ if (+ role === "viewer" &&+ relayCapacity !== null &&+ "mediaMode" in authenticated+ ) {+ client.socket.send(+ JSON.stringify({+ type: "relay-capacity",+ downstreamEdges: relayCapacity,+ }),+ );+ }+ return authenticated;}function peerAssisted(@@ -260,6 +363,219 @@ function peerAssisted(return message;}+async function nextActiveRouteAfter(+ client: TestClient,+ revision: number,+) {+ while (true) {+ const message = await client.inbox.next("route-update");+ if (message.phase === "active" && message.revision > revision) {+ return message;+ }+ }+}++async function nextPreparedRoute(client: TestClient) {+ while (true) {+ const message = await client.inbox.next("route-update");+ if (message.phase === "prepare") {+ return message;+ }+ }+}++async function nextActiveRouteRevision(client: TestClient, revision: number) {+ while (true) {+ const message = await client.inbox.next("route-update");+ if (message.phase === "active" && message.revision === revision) {+ return message;+ }+ }+}++async function prepareFallbackForTwoViewers(+ webSocketUrl: string,+ room: CreatedRoom,+ prefix: string,+ shareGeneration?: string,+) {+ const host = await openClient(webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(+ host,+ room,+ "host",+ `${prefix}-host-client`,+ 1,+ shareGeneration,+ ),+ );+ const failedViewer = await openClient(webSocketUrl);+ const failedAuth = peerAssisted(+ await authenticate(+ failedViewer,+ room,+ "viewer",+ `${prefix}-failed-client`,+ ),+ );+ const rootViewer = await openClient(webSocketUrl);+ const rootAuth = peerAssisted(+ await authenticate(+ rootViewer,+ room,+ "viewer",+ `${prefix}-root-client`,+ ),+ );+ const directRoute = await nextActiveRouteAfter(+ failedViewer,+ failedAuth.routeRevision,+ );+ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: failedAuth.peerId,+ payload: {+ kind: "description",+ connectionId: `${prefix}-direct-connection`,+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await failedViewer.inbox.next("signal");+ failedViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: directRoute.revision,+ phase: "active",+ connectionId: `${prefix}-direct-connection`,+ }),+ );+ const reparented = await nextActiveRouteAfter(+ failedViewer,+ directRoute.revision,+ );+ rootViewer.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: failedAuth.peerId,+ payload: {+ kind: "description",+ connectionId: `${prefix}-deep-connection`,+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await failedViewer.inbox.next("signal");+ failedViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: reparented.revision,+ phase: "active",+ connectionId: `${prefix}-deep-connection`,+ }),+ );+ const hostPrepare = await nextPreparedRoute(host);+ const rootPrepare = await nextPreparedRoute(failedViewer);+ await host.inbox.next("sfu-config");+ await failedViewer.inbox.next("sfu-config");+ return {+ host,+ hostAuth,+ failedViewer,+ failedAuth,+ rootViewer,+ rootAuth,+ hostPrepare,+ rootPrepare,+ };+}++async function exhaustDeepViewerPeerRoutes(+ webSocketUrl: string,+ room: CreatedRoom,+ prefix: string,+) {+ const host = await openClient(webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, room, "host", `${prefix}-host`),+ );+ const firstRoot = await openClient(webSocketUrl);+ const firstRootAuth = peerAssisted(+ await authenticate(firstRoot, room, "viewer", `${prefix}-root-a`),+ );+ const secondRoot = await openClient(webSocketUrl);+ const secondRootAuth = peerAssisted(+ await authenticate(secondRoot, room, "viewer", `${prefix}-root-b`),+ );+ const failedViewer = await openClient(webSocketUrl);+ const failedAuth = peerAssisted(+ await authenticate(failedViewer, room, "viewer", `${prefix}-failed`),+ );++ firstRoot.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: failedAuth.peerId,+ payload: {+ kind: "description",+ connectionId: `${prefix}-edge-a`,+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await failedViewer.inbox.next("signal");+ failedViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: failedAuth.routeRevision,+ phase: "active",+ connectionId: `${prefix}-edge-a`,+ }),+ );+ const reparented = await nextActiveRouteAfter(+ failedViewer,+ failedAuth.routeRevision,+ );+ expect(reparented.assignment.upstream).toEqual({+ kind: "peer",+ peerId: secondRootAuth.peerId,+ });++ secondRoot.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: failedAuth.peerId,+ payload: {+ kind: "description",+ connectionId: `${prefix}-edge-b`,+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await failedViewer.inbox.next("signal");+ failedViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: reparented.revision,+ phase: "active",+ connectionId: `${prefix}-edge-b`,+ }),+ );++ return {+ host,+ hostAuth,+ firstRoot,+ firstRootAuth,+ secondRoot,+ secondRootAuth,+ failedViewer,+ failedAuth,+ };+}+async function closeClient(client: TestClient): Promise<void> {if (client.socket.readyState === WebSocket.CLOSED) {return;@@ -303,6 +619,7 @@ describe("WebSocket signaling", () => {);expect(viewerAuth.hostOnline).toBe(false);expect("mediaMode" in viewerAuth).toBe(false);+ expect("routeRevision" in viewerAuth).toBe(false);const host = await openClient(harness.webSocketUrl);await authenticate(host, harness.room, "host", "host-client-stable");@@ -313,6 +630,35 @@ describe("WebSocket signaling", () => {});});+ it("advances a provisional peer route when the host arrives after viewers", async () => {+ const harness = await startHarness({ peerAssistedMedia: true });+ const viewer = await openClient(harness.webSocketUrl);+ const viewerAuth = peerAssisted(+ await authenticate(+ viewer,+ harness.room,+ "viewer",+ "early-relay-viewer",+ ),+ );+ expect(viewerAuth).toMatchObject({+ routeRevision: 0,+ routeAssignment: { upstream: { kind: "none" } },+ });++ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "early-relay-host"),+ );+ expect(hostAuth.routeRevision).toBeGreaterThan(viewerAuth.routeRevision);+ expect(await nextActiveRouteAfter(viewer, viewerAuth.routeRevision)).toMatchObject({+ revision: hostAuth.routeRevision,+ assignment: {+ upstream: { kind: "peer", peerId: hostAuth.peerId },+ },+ });+ });+it("authenticates a persistent room without a room expiry", async () => {const harness = await startHarness({ persistent: true });expect(harness.room).toMatchObject({ roomId: "1", expiresAt: null });@@ -376,6 +722,79 @@ describe("WebSocket signaling", () => {await lateViewer.inbox.expectNone(30);});+ it("uses only explicitly advertised viewer relay slots without moving healthy edges", async () => {+ const harness = await startHarness({ peerAssistedMedia: true });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "capacity-host"),+ );+ const first = await openClient(harness.webSocketUrl);+ const firstAuth = peerAssisted(+ await authenticate(+ first,+ harness.room,+ "viewer",+ "capacity-first",+ null,+ ),+ );+ const second = await openClient(harness.webSocketUrl);+ const secondAuth = peerAssisted(+ await authenticate(+ second,+ harness.room,+ "viewer",+ "capacity-second",+ null,+ ),+ );+ const pending = await openClient(harness.webSocketUrl);+ const pendingAuth = peerAssisted(+ await authenticate(+ pending,+ harness.room,+ "viewer",+ "capacity-pending",+ null,+ ),+ );++ expect(firstAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });+ expect(secondAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });+ expect(pendingAuth.routeAssignment.upstream).toEqual({ kind: "none" });++ first.socket.send(+ JSON.stringify({ type: "relay-capacity", downstreamEdges: 1 }),+ );+ const pendingRoute = await nextActiveRouteAfter(+ pending,+ pendingAuth.routeRevision,+ );+ expect(pendingRoute.assignment.upstream).toEqual({+ kind: "peer",+ peerId: firstAuth.peerId,+ });+ const secondRoute = await nextActiveRouteAfter(+ second,+ secondAuth.routeRevision,+ );+ expect(secondRoute.assignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });++ host.socket.send(+ JSON.stringify({ type: "relay-capacity", downstreamEdges: 1 }),+ );+ expect((await host.inbox.next("error")).code).toBe("FORBIDDEN");+ });+it("keeps the P2P authenticated wire unchanged and forbids profile updates", async () => {const harness = await startHarness();const host = await openClient(harness.webSocketUrl);@@ -413,6 +832,10 @@ describe("WebSocket signaling", () => {}),);expect((await viewer.inbox.next("error")).code).toBe("FORBIDDEN");+ viewer.socket.send(+ JSON.stringify({ type: "relay-capacity", downstreamEdges: 1 }),+ );+ expect((await viewer.inbox.next("error")).code).toBe("FORBIDDEN");await viewer.inbox.expectNone(30);});@@ -501,6 +924,14 @@ describe("WebSocket signaling", () => {parentPeerId: null,childPeerIds: [],});+ expect(hostAuth).toMatchObject({+ routeRevision: 0,+ routeAssignment: {+ upstream: { kind: "none" },+ childPeerIds: [],+ sfuPublicationGeneration: null,+ },+ });const firstViewer = await openClient(harness.webSocketUrl);const firstAuth = peerAssisted(@@ -512,6 +943,10 @@ describe("WebSocket signaling", () => {),);expect(firstAuth.mediaAssignment.parentPeerId).toBe(hostAuth.peerId);+ expect(firstAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });expect((await host.inbox.next("media-assignment")).mediaAssignment).toEqual({parentPeerId: null,childPeerIds: [firstAuth.peerId],@@ -671,106 +1106,1208 @@ describe("WebSocket signaling", () => {await foreignViewer.inbox.expectNone(30);});- it("keeps relay assignments through grace and reattaches only the direct child subtree", async () => {- const harness = await startHarness({- peerAssistedMedia: true,- viewerDisconnectGraceMs: 200,+ it("reparents failed peer edges before committing a bounded SFU fallback", async () => {+ const issued: Array<+ Parameters<SfuTokenIssuer["issueToken"]>[0]+ > = [];+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ issued.push(request);+ return `token-${request.peerId}`;+ },+ },});const host = await openClient(harness.webSocketUrl);const hostAuth = peerAssisted(- await authenticate(host, harness.room, "host", "relay-grace-host"),+ await authenticate(host, harness.room, "host", "hybrid-host"),);-const firstViewer = await openClient(harness.webSocketUrl);const firstAuth = peerAssisted(await authenticate(firstViewer,harness.room,"viewer",- "relay-grace-a",+ "hybrid-viewer-a",),);- await host.inbox.next("media-assignment");-const secondViewer = await openClient(harness.webSocketUrl);const secondAuth = peerAssisted(await authenticate(secondViewer,harness.room,"viewer",- "relay-grace-b",+ "hybrid-viewer-b",),);- await host.inbox.next("media-assignment");-- const thirdViewer = await openClient(harness.webSocketUrl);- const thirdAuth = peerAssisted(- await authenticate(- thirdViewer,- harness.room,- "viewer",- "relay-grace-c",- ),+ const firstBeforeFailure = await nextActiveRouteAfter(+ firstViewer,+ firstAuth.routeRevision,);- await firstViewer.inbox.next("media-assignment");- const fourthViewer = await openClient(harness.webSocketUrl);- await authenticate(- fourthViewer,- harness.room,- "viewer",- "relay-grace-d",+ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "hybrid-direct-connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await firstViewer.inbox.next("signal");+ firstViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: firstBeforeFailure.revision,+ phase: "active",+ connectionId: "hybrid-direct-connection",+ }),);- await secondViewer.inbox.next("media-assignment");- const fifthViewer = await openClient(harness.webSocketUrl);- const fifthAuth = peerAssisted(- await authenticate(- fifthViewer,- harness.room,- "viewer",- "relay-grace-e",- ),+ const firstReparented = await nextActiveRouteAfter(+ firstViewer,+ firstBeforeFailure.revision,);- const thirdWithChild = await thirdViewer.inbox.next("media-assignment");- expect(thirdWithChild.mediaAssignment).toEqual({- parentPeerId: firstAuth.peerId,- childPeerIds: [fifthAuth.peerId],+ expect(firstReparented.assignment.upstream).toEqual({+ kind: "peer",+ peerId: secondAuth.peerId,+ });+ const hostAfterReparent = await nextActiveRouteAfter(+ host,+ firstBeforeFailure.revision,+ );+ expect(hostAfterReparent.assignment).toMatchObject({+ childPeerIds: [secondAuth.peerId],+ sfuPublicationGeneration: null,});- await closeClient(firstViewer);- await host.inbox.expectNone(30);- await thirdViewer.inbox.expectNone(30);-- host.socket.send(+ secondViewer.socket.send(JSON.stringify({type: "signal",targetPeerId: firstAuth.peerId,payload: {kind: "description",- connectionId: "offer-while-child-offline",+ connectionId: "hybrid-deep-connection",description: { type: "offer", sdp: "v=0\r\n" },},}),);- expect((await host.inbox.next("error")).code).toBe("PEER_NOT_FOUND");-- const reconnectedFirstViewer = await openClient(harness.webSocketUrl);- const reconnectedFirstAuth = peerAssisted(- await authenticate(- reconnectedFirstViewer,- harness.room,- "viewer",- "relay-grace-a",- ),+ await firstViewer.inbox.next("signal");+ firstViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: firstReparented.revision,+ phase: "active",+ connectionId: "hybrid-deep-connection",+ }),);- expect(reconnectedFirstAuth).toMatchObject({- peerId: firstAuth.peerId,- connectionId: null,- mediaAssignment: {- parentPeerId: hostAuth.peerId,- childPeerIds: [thirdAuth.peerId],- },++ const hostPrepare = await nextPreparedRoute(host);+ const rootPrepare = await nextPreparedRoute(firstViewer);+ expect(rootPrepare.revision).toBe(hostPrepare.revision);+ expect(hostPrepare.assignment).toMatchObject({+ upstream: { kind: "none" },+ childPeerIds: [secondAuth.peerId],+ });+ expect(rootPrepare.assignment).toMatchObject({+ upstream: { kind: "sfu" },+ childPeerIds: [],+ });+ expect(await host.inbox.next("sfu-config")).toMatchObject({+ revision: hostPrepare.revision,+ url: "wss://sfu.example.test",+ });+ expect(await firstViewer.inbox.next("sfu-config")).toMatchObject({+ revision: hostPrepare.revision,+ });+ await expect(secondViewer.inbox.next("sfu-config", 30)).rejects.toThrow(+ "Timed out",+ );++ secondViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: hostPrepare.revision,+ phase: "prepare",+ }),+ );+ expect((await secondViewer.inbox.next("error")).code).toBe("FORBIDDEN");+ host.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: hostPrepare.revision,+ phase: "prepare",+ }),+ );+ firstViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: hostPrepare.revision,+ phase: "prepare",+ }),+ );++ const hostActive = await nextActiveRouteAfter(+ host,+ hostPrepare.revision - 1,+ );+ const rootActive = await nextActiveRouteAfter(+ firstViewer,+ hostPrepare.revision - 1,+ );+ expect(hostActive.revision).toBe(hostPrepare.revision);+ expect(hostActive.assignment.childPeerIds).toEqual([secondAuth.peerId]);+ expect(hostActive.assignment.sfuPublicationGeneration).toBeTruthy();+ expect(rootActive.assignment.upstream).toEqual({ kind: "sfu" });+ expect(new Set(issued.map(({ peerId }) => peerId))).toEqual(+ new Set([hostAuth.peerId, firstAuth.peerId]),+ );+ expect(new Set(issued.map(({ publicationGeneration }) => publicationGeneration)).size).toBe(1);++ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "candidate",+ connectionId: "no-longer-direct",+ candidate: null,+ },+ }),+ );+ expect((await host.inbox.next("error")).code).toBe("FORBIDDEN");++ await closeClient(firstViewer);+ const reconnectedRoot = await openClient(harness.webSocketUrl);+ const reconnectedRootAuth = peerAssisted(+ await authenticate(+ reconnectedRoot,+ harness.room,+ "viewer",+ "hybrid-viewer-a",+ ),+ );+ expect(reconnectedRootAuth).toMatchObject({+ peerId: firstAuth.peerId,+ routeRevision: hostPrepare.revision,+ routeAssignment: { upstream: { kind: "sfu" } },+ mediaAssignment: { parentPeerId: null },+ });+ expect(await reconnectedRoot.inbox.next("sfu-config")).toMatchObject({+ revision: hostPrepare.revision,+ });++ const issuedBeforeRefresh = issued.length;+ for (let requestIndex = 0; requestIndex < 2; requestIndex += 1) {+ reconnectedRoot.socket.send(+ JSON.stringify({+ type: "refresh-sfu",+ revision: hostPrepare.revision,+ }),+ );+ }+ expect(await reconnectedRoot.inbox.next("sfu-config")).toMatchObject({+ revision: hostPrepare.revision,+ });+ expect((await reconnectedRoot.inbox.next("error")).code).toBe("FORBIDDEN");+ expect(issued).toHaveLength(issuedBeforeRefresh + 1);+ const issuedBeforeFailback = issued.length;+ reconnectedRoot.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: hostPrepare.revision,+ phase: "active",+ connectionId: null,+ }),+ );+ const peerBaseline = await nextActiveRouteAfter(+ reconnectedRoot,+ hostPrepare.revision,+ );+ const hostPeerBaseline = await nextActiveRouteAfter(+ host,+ hostPrepare.revision,+ );+ expect(peerBaseline.assignment.upstream).toEqual({+ kind: "peer",+ peerId: secondAuth.peerId,+ });+ expect(hostPeerBaseline.assignment).toMatchObject({+ childPeerIds: [secondAuth.peerId],+ sfuPublicationGeneration: null,+ });++ secondViewer.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "after-sfu-root-connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await reconnectedRoot.inbox.next("signal");+ reconnectedRoot.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: peerBaseline.revision,+ phase: "active",+ connectionId: "after-sfu-root-connection",+ }),+ );+ const directAgain = await nextActiveRouteAfter(+ reconnectedRoot,+ peerBaseline.revision,+ );+ expect(directAgain.assignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });+ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "after-sfu-host-connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await reconnectedRoot.inbox.next("signal");+ reconnectedRoot.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: directAgain.revision,+ phase: "active",+ connectionId: "after-sfu-host-connection",+ }),+ );+ expect((await reconnectedRoot.inbox.next("error")).code).toBe("PEER_NOT_FOUND");+ expect(issued).toHaveLength(issuedBeforeFailback);++ host.socket.send(JSON.stringify({ type: "stop-sharing" }));+ await reconnectedRoot.inbox.next("sharing-stopped");+ const resumedHost = await openClient(harness.webSocketUrl);+ const resumedHostAuth = peerAssisted(+ await authenticate(resumedHost, harness.room, "host", "hybrid-host"),+ );+ expect(resumedHostAuth.routeAssignment).toMatchObject({+ upstream: { kind: "none" },+ sfuPublicationGeneration: null,+ });+ expect(resumedHostAuth.routeAssignment.childPeerIds).toHaveLength(2);++ const resumedFirstRoute = await nextActiveRouteRevision(+ reconnectedRoot,+ resumedHostAuth.routeRevision,+ );+ resumedHost.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "resumed-direct-connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await reconnectedRoot.inbox.next("signal");+ reconnectedRoot.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: resumedFirstRoute.revision,+ phase: "active",+ connectionId: "resumed-direct-connection",+ }),+ );+ const resumedReparent = await nextActiveRouteAfter(+ reconnectedRoot,+ resumedFirstRoute.revision,+ );+ secondViewer.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "resumed-deep-connection",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await reconnectedRoot.inbox.next("signal");+ reconnectedRoot.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: resumedReparent.revision,+ phase: "active",+ connectionId: "resumed-deep-connection",+ }),+ );+ const resumedPrepare = await nextPreparedRoute(resumedHost);+ expect(await resumedHost.inbox.next("sfu-config")).toMatchObject({+ revision: resumedPrepare.revision,+ });+ expect(issued.length).toBeGreaterThan(issuedBeforeFailback);+ });++ it("moves both a failed deep viewer and its host branch within two SFU roots", async () => {+ const issued: Array<Parameters<SfuTokenIssuer["issueToken"]>[0]> = [];+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ issued.push(request);+ return `token-${request.peerId}`;+ },+ },+ });+ const peers = await exhaustDeepViewerPeerRoutes(+ harness.webSocketUrl,+ harness.room,+ "deep-budget",+ );++ const hostPrepare = await nextPreparedRoute(peers.host);+ const branchPrepare = await nextPreparedRoute(peers.secondRoot);+ const failedPrepare = await nextPreparedRoute(peers.failedViewer);+ expect(branchPrepare.revision).toBe(hostPrepare.revision);+ expect(failedPrepare.revision).toBe(hostPrepare.revision);+ expect(hostPrepare.assignment.childPeerIds).toEqual([+ peers.firstRootAuth.peerId,+ ]);+ expect(branchPrepare.assignment.upstream).toEqual({ kind: "sfu" });+ expect(failedPrepare.assignment.upstream).toEqual({ kind: "sfu" });+ expect(+ new Set(issued.map(({ peerId }) => peerId)),+ ).toEqual(+ new Set([+ peers.hostAuth.peerId,+ peers.secondRootAuth.peerId,+ peers.failedAuth.peerId,+ ]),+ );+ });++ it("fails a deep SFU fallback cleanly when its root budget is one", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ return `token-${request.peerId}`;+ },+ },+ maxRoots: 1,+ });+ const peers = await exhaustDeepViewerPeerRoutes(+ harness.webSocketUrl,+ harness.room,+ "deep-limited",+ );++ expect((await peers.failedViewer.inbox.next("error")).code).toBe(+ "PEER_NOT_FOUND",+ );+ await expect(nextPreparedRoute(peers.host)).rejects.toThrow("Timed out");+ expect(peers.host.socket.readyState).toBe(WebSocket.OPEN);+ });++ it("admits a leaf with no peer slot through a selective SFU route", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ return `token-${request.peerId}`;+ },+ },+ });+ const host = await openClient(harness.webSocketUrl);+ await authenticate(host, harness.room, "host", "admission-host");+ const firstLeaf = await openClient(harness.webSocketUrl);+ const firstAuth = peerAssisted(+ await authenticate(+ firstLeaf,+ harness.room,+ "viewer",+ "admission-leaf-a",+ 0,+ ),+ );+ const secondLeaf = await openClient(harness.webSocketUrl);+ const secondAuth = peerAssisted(+ await authenticate(+ secondLeaf,+ harness.room,+ "viewer",+ "admission-leaf-b",+ 0,+ ),+ );+ const pendingLeaf = await openClient(harness.webSocketUrl);+ const pendingAuth = peerAssisted(+ await authenticate(+ pendingLeaf,+ harness.room,+ "viewer",+ "admission-leaf-c",+ 0,+ ),+ );+ expect(pendingAuth.routeAssignment.upstream).toEqual({ kind: "none" });++ const hostPrepare = await nextPreparedRoute(host);+ const budgetPrepare = await nextPreparedRoute(firstLeaf);+ const pendingPrepare = await nextPreparedRoute(pendingLeaf);+ expect(hostPrepare.assignment.childPeerIds).toEqual([secondAuth.peerId]);+ expect(budgetPrepare.assignment.upstream).toEqual({ kind: "sfu" });+ expect(pendingPrepare.assignment.upstream).toEqual({ kind: "sfu" });+ expect(await firstLeaf.inbox.next("sfu-config")).toMatchObject({+ token: `token-${firstAuth.peerId}`,+ });+ expect(await pendingLeaf.inbox.next("sfu-config")).toMatchObject({+ token: `token-${pendingAuth.peerId}`,+ });+ });++ it("uses a free direct slot beside an active SFU publication", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ return `token-${request.peerId}`;+ },+ },+ });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "active-slot-host"),+ );+ const root = await openClient(harness.webSocketUrl);+ const rootAuth = peerAssisted(+ await authenticate(root, harness.room, "viewer", "active-slot-root", 0),+ );+ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: rootAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "active-slot-failed-edge",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await root.inbox.next("signal");+ root.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: rootAuth.routeRevision,+ phase: "active",+ connectionId: "active-slot-failed-edge",+ }),+ );+ const hostPrepare = await nextPreparedRoute(host);+ const rootPrepare = await nextPreparedRoute(root);+ await host.inbox.next("sfu-config");+ await root.inbox.next("sfu-config");+ host.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: hostPrepare.revision,+ phase: "prepare",+ }),+ );+ root.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: rootPrepare.revision,+ phase: "prepare",+ }),+ );+ await nextActiveRouteAfter(host, hostPrepare.revision - 1);++ const directViewer = await openClient(harness.webSocketUrl);+ const directAuth = peerAssisted(+ await authenticate(+ directViewer,+ harness.room,+ "viewer",+ "active-slot-direct",+ 0,+ ),+ );+ expect(directAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: hostAuth.peerId,+ });+ expect(directAuth.routeAssignment.sfuPublicationGeneration).toBeNull();+ });++ it("retires an SFU publication when its root allowlist shrinks", async () => {+ const issued: Array<Parameters<SfuTokenIssuer["issueToken"]>[0]> = [];+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ issued.push(request);+ return `token-${request.peerId}`;+ },+ },+ });+ const peers = await exhaustDeepViewerPeerRoutes(+ harness.webSocketUrl,+ harness.room,+ "shrink-roots",+ );+ const hostPrepare = await nextPreparedRoute(peers.host);+ const branchPrepare = await nextPreparedRoute(peers.secondRoot);+ const failedPrepare = await nextPreparedRoute(peers.failedViewer);+ await peers.host.inbox.next("sfu-config");+ await peers.secondRoot.inbox.next("sfu-config");+ await peers.failedViewer.inbox.next("sfu-config");+ for (const [client, revision] of [+ [peers.host, hostPrepare.revision],+ [peers.secondRoot, branchPrepare.revision],+ [peers.failedViewer, failedPrepare.revision],+ ] as const) {+ client.socket.send(+ JSON.stringify({ type: "route-ready", revision, phase: "prepare" }),+ );+ }+ const hostActive = await nextActiveRouteAfter(+ peers.host,+ hostPrepare.revision - 1,+ );+ await nextActiveRouteAfter(+ peers.secondRoot,+ branchPrepare.revision - 1,+ );+ expect(hostActive.assignment.sfuPublicationGeneration).toBeTruthy();+ expect(issued).toHaveLength(3);++ await closeClient(peers.failedViewer);+ const retiredHost = await nextActiveRouteAfter(+ peers.host,+ hostActive.revision,+ );+ const retiredRoot = await nextActiveRouteAfter(+ peers.secondRoot,+ hostActive.revision,+ );+ expect(retiredHost.assignment.sfuPublicationGeneration).toBeNull();+ expect(retiredRoot.assignment).toMatchObject({+ upstream: { kind: "peer", peerId: peers.hostAuth.peerId },+ sfuPublicationGeneration: null,+ });+ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(issued).toHaveLength(3);+ });++ it("separates host signaling reconnects from new sharing generations", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ return `token-${request.peerId}`;+ },+ },+ });+ const prepared = await prepareFallbackForTwoViewers(+ harness.webSocketUrl,+ harness.room,+ "share-generation",+ "share-gen-a",+ );+ prepared.host.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: prepared.hostPrepare.revision,+ phase: "prepare",+ }),+ );+ prepared.failedViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: prepared.rootPrepare.revision,+ phase: "prepare",+ }),+ );+ const active = await nextActiveRouteRevision(+ prepared.failedViewer,+ prepared.rootPrepare.revision,+ );+ expect(active.assignment.upstream).toEqual({ kind: "sfu" });++ const sameShareHost = await openClient(harness.webSocketUrl);+ const sameShareAuth = peerAssisted(+ await authenticate(+ sameShareHost,+ harness.room,+ "host",+ "share-generation-host-client",+ 1,+ "share-gen-a",+ ).catch((error: unknown) => {+ throw new Error("same-generation authentication failed", {+ cause: error,+ });+ }),+ );+ expect(sameShareAuth.routeRevision).toBe(active.revision);+ expect(sameShareAuth.routeAssignment.sfuPublicationGeneration).toBeTruthy();+ await expect(+ prepared.failedViewer.inbox.next("sharing-stopped", 30),+ ).rejects.toThrow("Timed out");++ const nextShareHost = await openClient(harness.webSocketUrl);+ const nextShareAuth = peerAssisted(+ await authenticate(+ nextShareHost,+ harness.room,+ "host",+ "share-generation-host-client",+ 1,+ "share-gen-b",+ ).catch((error: unknown) => {+ throw new Error("new-generation authentication failed", {+ cause: error,+ });+ }),+ );+ await prepared.failedViewer.inbox.next("sharing-stopped");+ expect(nextShareAuth.routeRevision).toBeLessThanOrEqual(active.revision);+ expect(nextShareAuth.routeAssignment.sfuPublicationGeneration).toBeNull();++ const staleStopClosed = new Promise<number>((resolve) =>+ nextShareHost.socket.once("close", (code) => resolve(code)),+ );+ nextShareHost.socket.send(+ JSON.stringify({+ type: "stop-sharing",+ shareGeneration: "share-gen-a",+ }),+ );+ expect(await staleStopClosed).toBe(4001);+ await expect(+ prepared.failedViewer.inbox.next("sharing-stopped", 30),+ ).rejects.toThrow("Timed out");++ const resumedSameShare = await openClient(harness.webSocketUrl);+ const resumedAuth = peerAssisted(+ await authenticate(+ resumedSameShare,+ harness.room,+ "host",+ "share-generation-host-client",+ 1,+ "share-gen-b",+ ).catch((error: unknown) => {+ throw new Error("resumed-generation authentication failed", {+ cause: error,+ });+ }),+ );+ expect(resumedAuth.routeRevision).toBe(nextShareAuth.routeRevision);+ });++ it("replans a pending fallback after unrelated topology churn", async () => {+ const generations: string[] = [];+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ generations.push(request.publicationGeneration);+ return `token-${request.peerId}`;+ },+ },+ });+ const prepared = await prepareFallbackForTwoViewers(+ harness.webSocketUrl,+ harness.room,+ "topology-churn",+ );+ const extraViewer = await openClient(harness.webSocketUrl);+ await authenticate(+ extraViewer,+ harness.room,+ "viewer",+ "topology-churn-extra",+ 0,+ );++ let rollbackRevision: number | undefined;+ let retriedPrepareRevision: number | undefined;+ while (+ rollbackRevision === undefined ||+ retriedPrepareRevision === undefined+ ) {+ const message = await prepared.host.inbox.next("route-update");+ if (+ message.phase === "active" &&+ message.revision > prepared.hostPrepare.revision+ ) {+ rollbackRevision = message.revision;+ }+ if (message.phase === "prepare") {+ retriedPrepareRevision = message.revision;+ }+ }+ expect(retriedPrepareRevision).toBeGreaterThan(rollbackRevision);+ expect(new Set(generations).size).toBe(2);+ });++ it("keeps a prepared fallback when an unrelated viewer disconnects", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ return `token-${request.peerId}`;+ },+ },+ viewerDisconnectGraceMs: 500,+ });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "unrelated-close-host"),+ );+ const parentA = await openClient(harness.webSocketUrl);+ const parentAAuth = peerAssisted(+ await authenticate(parentA, harness.room, "viewer", "unrelated-parent-a"),+ );+ const parentB = await openClient(harness.webSocketUrl);+ await authenticate(parentB, harness.room, "viewer", "unrelated-parent-b");+ const failedViewer = await openClient(harness.webSocketUrl);+ const failedAuth = peerAssisted(+ await authenticate(+ failedViewer,+ harness.room,+ "viewer",+ "unrelated-failed",+ ),+ );+ const unrelatedViewer = await openClient(harness.webSocketUrl);+ const unrelatedAuth = peerAssisted(+ await authenticate(+ unrelatedViewer,+ harness.room,+ "viewer",+ "unrelated-disconnected",+ 0,+ ),+ );+ expect(failedAuth.routeAssignment.upstream).toEqual({+ kind: "peer",+ peerId: parentAAuth.peerId,+ });++ parentA.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: failedAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "unrelated-close-failed-edge",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await failedViewer.inbox.next("signal");+ failedViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: unrelatedAuth.routeRevision,+ phase: "active",+ connectionId: "unrelated-close-failed-edge",+ }),+ );+ const hostPrepare = await nextPreparedRoute(host).catch((error: unknown) => {+ throw new Error("host did not receive unrelated-close prepare", {+ cause: error,+ });+ });+ const failedPrepare = await nextPreparedRoute(failedViewer).catch(+ (error: unknown) => {+ throw new Error("failed viewer did not receive unrelated-close prepare", {+ cause: error,+ });+ },+ );+ const parentPrepare = await nextPreparedRoute(parentA);+ await host.inbox.next("sfu-config");+ await failedViewer.inbox.next("sfu-config");+ await parentA.inbox.next("sfu-config");++ await closeClient(unrelatedViewer);+ host.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: hostPrepare.revision,+ phase: "prepare",+ }),+ );+ failedViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: failedPrepare.revision,+ phase: "prepare",+ }),+ );+ parentA.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: parentPrepare.revision,+ phase: "prepare",+ }),+ );+ const committed = await nextActiveRouteRevision(+ host,+ hostPrepare.revision,+ ).catch((error: unknown) => {+ throw new Error("unrelated close aborted the prepared route", {+ cause: error,+ });+ });+ expect(committed.assignment).toMatchObject({+ upstream: { kind: "none" },+ sfuPublicationGeneration: expect.any(String),+ });+ expect(committed.assignment.childPeerIds.length).toBeLessThanOrEqual(1);+ expect(hostAuth.peerId).toBeTruthy();+ });++ it("rolls back SFU prepare on timeout and expected-session replacement", async () => {+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ return `token-${request.peerId}`;+ },+ },+ prepareTimeoutMs: 120,+ });+ const timedOut = await prepareFallbackForTwoViewers(+ harness.webSocketUrl,+ harness.room,+ "timeout",+ );+ const timedOutRollback = await nextActiveRouteAfter(+ timedOut.host,+ timedOut.hostPrepare.revision,+ );+ expect(timedOutRollback).toMatchObject({+ revision: timedOut.hostPrepare.revision + 1,+ assignment: {+ upstream: { kind: "none" },+ childPeerIds: [timedOut.rootAuth.peerId],+ sfuPublicationGeneration: null,+ },+ });++ const replacementRoom = harness.roomStore.createRoom();+ const replacing = await prepareFallbackForTwoViewers(+ harness.webSocketUrl,+ replacementRoom,+ "replacement",+ );+ const replacementRoot = await openClient(harness.webSocketUrl);+ const replacementAuth = peerAssisted(+ await authenticate(+ replacementRoot,+ replacementRoom,+ "viewer",+ "replacement-failed-client",+ ),+ );+ expect(replacementAuth).toMatchObject({+ peerId: replacing.failedAuth.peerId,+ routeRevision: replacing.hostPrepare.revision + 1,+ routeAssignment: {+ upstream: { kind: "peer", peerId: replacing.rootAuth.peerId },+ sfuPublicationGeneration: null,+ },+ });+ const replacementRollback = await nextActiveRouteAfter(+ replacing.host,+ replacing.hostPrepare.revision,+ );+ expect(replacementRollback.revision).toBe(+ replacing.hostPrepare.revision + 1,+ );++ replacing.rootViewer.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: replacementAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "replacement-reported-again",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ await replacementRoot.inbox.next("signal");+ replacementRoot.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: replacementAuth.routeRevision,+ phase: "active",+ connectionId: "replacement-reported-again",+ }),+ );+ const replacementRecovered = await nextActiveRouteAfter(+ replacementRoot,+ replacementAuth.routeRevision,+ );+ expect(replacementRecovered.assignment.upstream).toEqual({+ kind: "peer",+ peerId: replacing.hostAuth.peerId,+ });++ replacing.failedViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: replacing.hostPrepare.revision,+ phase: "prepare",+ }),+ );+ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(replacementRoot.socket.readyState).toBe(WebSocket.OPEN);++ const prepareFailureRoom = harness.roomStore.createRoom();+ const prepareFailure = await prepareFallbackForTwoViewers(+ harness.webSocketUrl,+ prepareFailureRoom,+ "prepare-failure",+ );+ prepareFailure.failedViewer.socket.send(+ JSON.stringify({+ type: "route-failed",+ revision: prepareFailure.rootPrepare.revision,+ phase: "prepare",+ connectionId: null,+ }),+ );+ const failedPrepareRollback = await nextActiveRouteAfter(+ prepareFailure.host,+ prepareFailure.hostPrepare.revision,+ );+ expect(failedPrepareRollback.revision).toBe(+ prepareFailure.hostPrepare.revision + 1,+ );+ expect(failedPrepareRollback.assignment).toMatchObject({+ childPeerIds: [prepareFailure.rootAuth.peerId],+ sfuPublicationGeneration: null,+ });+ });++ it("fails back to peer routes when an active SFU token refresh fails", async () => {+ let rejectTokens = false;+ const harness = await startSfuHarness({+ tokenIssuer: {+ async issueToken(request) {+ if (rejectTokens) {+ throw new Error("issuer unavailable");+ }+ return `token-${request.peerId}`;+ },+ },+ });+ const prepared = await prepareFallbackForTwoViewers(+ harness.webSocketUrl,+ harness.room,+ "refresh-failure",+ );+ prepared.host.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: prepared.hostPrepare.revision,+ phase: "prepare",+ }),+ );+ prepared.failedViewer.socket.send(+ JSON.stringify({+ type: "route-ready",+ revision: prepared.rootPrepare.revision,+ phase: "prepare",+ }),+ );+ await nextActiveRouteAfter(+ prepared.host,+ prepared.hostPrepare.revision - 1,+ );+ await nextActiveRouteAfter(+ prepared.failedViewer,+ prepared.rootPrepare.revision - 1,+ );++ rejectTokens = true;+ prepared.failedViewer.socket.send(+ JSON.stringify({+ type: "refresh-sfu",+ revision: prepared.rootPrepare.revision,+ }),+ );+ const rollback = await nextActiveRouteAfter(+ prepared.host,+ prepared.hostPrepare.revision,+ );+ expect(rollback).toMatchObject({+ revision: prepared.hostPrepare.revision + 1,+ assignment: {+ childPeerIds: [prepared.rootAuth.peerId],+ sfuPublicationGeneration: null,+ },+ });+ });++ it("keeps route revisions monotonic when a disconnected host is replaced", async () => {+ const harness = await startHarness({ peerAssistedMedia: true });+ const firstHost = await openClient(harness.webSocketUrl);+ const firstHostAuth = peerAssisted(+ await authenticate(firstHost, harness.room, "host", "takeover-host-a"),+ );+ const viewer = await openClient(harness.webSocketUrl);+ const viewerAuth = peerAssisted(+ await authenticate(viewer, harness.room, "viewer", "takeover-viewer-a"),+ );+ const secondViewer = await openClient(harness.webSocketUrl);+ await authenticate(+ secondViewer,+ harness.room,+ "viewer",+ "takeover-viewer-b",+ );+ const previousRoute = await nextActiveRouteAfter(+ viewer,+ viewerAuth.routeRevision,+ );++ await closeClient(firstHost);+ await viewer.inbox.next("host-status");+ const replacementHost = await openClient(harness.webSocketUrl);+ const replacementAuth = peerAssisted(+ await authenticate(+ replacementHost,+ harness.room,+ "host",+ "takeover-host-b",+ ),+ );+ expect(replacementAuth.peerId).not.toBe(firstHostAuth.peerId);+ expect(replacementAuth.routeRevision).toBeGreaterThan(+ previousRoute.revision,+ );+ const viewerRoute = await nextActiveRouteAfter(+ viewer,+ previousRoute.revision,+ );+ expect(viewerRoute).toMatchObject({+ revision: replacementAuth.routeRevision,+ assignment: {+ upstream: { kind: "peer", peerId: replacementAuth.peerId },+ },+ });+ });++ it("keeps relay assignments through grace and reattaches only the direct child subtree", async () => {+ const harness = await startHarness({+ peerAssistedMedia: true,+ viewerDisconnectGraceMs: 200,+ });+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = peerAssisted(+ await authenticate(host, harness.room, "host", "relay-grace-host"),+ );++ const firstViewer = await openClient(harness.webSocketUrl);+ const firstAuth = peerAssisted(+ await authenticate(+ firstViewer,+ harness.room,+ "viewer",+ "relay-grace-a",+ ),+ );+ await host.inbox.next("media-assignment");++ const secondViewer = await openClient(harness.webSocketUrl);+ const secondAuth = peerAssisted(+ await authenticate(+ secondViewer,+ harness.room,+ "viewer",+ "relay-grace-b",+ ),+ );+ await host.inbox.next("media-assignment");++ const thirdViewer = await openClient(harness.webSocketUrl);+ const thirdAuth = peerAssisted(+ await authenticate(+ thirdViewer,+ harness.room,+ "viewer",+ "relay-grace-c",+ ),+ );+ await firstViewer.inbox.next("media-assignment");++ const fourthViewer = await openClient(harness.webSocketUrl);+ await authenticate(+ fourthViewer,+ harness.room,+ "viewer",+ "relay-grace-d",+ );+ await secondViewer.inbox.next("media-assignment");++ const fifthViewer = await openClient(harness.webSocketUrl);+ const fifthAuth = peerAssisted(+ await authenticate(+ fifthViewer,+ harness.room,+ "viewer",+ "relay-grace-e",+ ),+ );+ const thirdWithChild = await thirdViewer.inbox.next("media-assignment");+ expect(thirdWithChild.mediaAssignment).toEqual({+ parentPeerId: firstAuth.peerId,+ childPeerIds: [fifthAuth.peerId],+ });++ host.inbox.ignore("route-update");+ thirdViewer.inbox.ignore("route-update");+ await closeClient(firstViewer);+ await host.inbox.expectNone(30);+ await thirdViewer.inbox.expectNone(30);++ host.socket.send(+ JSON.stringify({+ type: "signal",+ targetPeerId: firstAuth.peerId,+ payload: {+ kind: "description",+ connectionId: "offer-while-child-offline",+ description: { type: "offer", sdp: "v=0\r\n" },+ },+ }),+ );+ expect((await host.inbox.next("error")).code).toBe("PEER_NOT_FOUND");++ const reconnectedFirstViewer = await openClient(harness.webSocketUrl);+ const reconnectedFirstAuth = peerAssisted(+ await authenticate(+ reconnectedFirstViewer,+ harness.room,+ "viewer",+ "relay-grace-a",+ ),+ );+ expect(reconnectedFirstAuth).toMatchObject({+ peerId: firstAuth.peerId,+ connectionId: null,+ mediaAssignment: {+ parentPeerId: hostAuth.peerId,+ childPeerIds: [thirdAuth.peerId],+ },});expect((await host.inbox.next("media-assignment", 500)).mediaAssignment,@@ -792,6 +2329,7 @@ describe("WebSocket signaling", () => {parentPeerId: hostAuth.peerId,childPeerIds: [fifthAuth.peerId],});+ fifthViewer.inbox.ignore("route-update");await fifthViewer.inbox.expectNone(30);});@@ -1127,6 +2665,50 @@ describe("WebSocket signaling", () => {});});+ it("reasserts an authoritative parent route when a peer-assisted viewer reconnects", async () => {+ const harness = await startHarness({+ peerAssistedMedia: true,+ viewerDisconnectGraceMs: 300,+ });+ const host = await openClient(harness.webSocketUrl);+ peerAssisted(+ await authenticate(host, harness.room, "host", "relay-reauth-host"),+ );+ const originalViewer = await openClient(harness.webSocketUrl);+ const originalAuth = peerAssisted(+ await authenticate(+ originalViewer,+ harness.room,+ "viewer",+ "relay-reauth-viewer",+ ),+ );+ await host.inbox.next("media-assignment");+ await host.inbox.next("route-update");+ await closeClient(originalViewer);++ const reconnectedViewer = await openClient(harness.webSocketUrl);+ const reconnectedAuth = peerAssisted(+ await authenticate(+ reconnectedViewer,+ harness.room,+ "viewer",+ "relay-reauth-viewer",+ ),+ );+ expect(reconnectedAuth.peerId).toBe(originalAuth.peerId);+ expect(reconnectedAuth.connectionId).toBeNull();+ expect(await host.inbox.next("route-update")).toMatchObject({+ revision: reconnectedAuth.routeRevision,+ phase: "active",+ assignment: {+ upstream: { kind: "none" },+ childPeerIds: [originalAuth.peerId],+ sfuPublicationGeneration: null,+ },+ });+ });+it("replays viewers when a host reconnects", async () => {const harness = await startHarness({ viewerDisconnectGraceMs: 500 });const viewer = await openClient(harness.webSocketUrl);diff --git a/tests/sfu-client.test.ts b/tests/sfu-client.test.tsnew file mode 100644index 00000000..c78c34d6--- /dev/null+++ b/tests/sfu-client.test.ts@@ -0,0 +1,460 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import { SfuPublisher } from "../src/client/sfu/publisher.ts";+import { SfuSubscriber } from "../src/client/sfu/subscriber.ts";++type EventHandler = (...args: unknown[]) => void;++const livekit = vi.hoisted(() => {+ class FakeSender {+ parameters: RTCRtpSendParameters = {+ codecs: [],+ encodings: [{}],+ headerExtensions: [],+ rtcp: { cname: "fake", reducedSize: true },+ transactionId: "fake",+ };++ readonly getParameters = vi.fn(() => this.parameters);+ readonly setParameters = vi.fn(+ async (parameters: RTCRtpSendParameters): Promise<void> => {+ this.parameters = parameters;+ },+ );+ }++ class FakeLocalTrack {+ currentTrack: MediaStreamTrack;+ readonly sender = new FakeSender();++ constructor(track: MediaStreamTrack) {+ this.currentTrack = track;+ }++ readonly replaceTrack = vi.fn(+ async (nextTrack: MediaStreamTrack): Promise<void> => {+ this.currentTrack = nextTrack;+ },+ );+ }++ class FakeLocalParticipant {+ readonly publications: Array<{+ track: FakeLocalTrack;+ videoTrack?: FakeLocalTrack;+ rawTrack: MediaStreamTrack;+ options: Record<string, unknown>;+ }> = [];++ readonly publishTrack = vi.fn(+ async (+ rawTrack: MediaStreamTrack,+ options: Record<string, unknown>,+ ) => {+ const localTrack = new FakeLocalTrack(rawTrack);+ const publication = {+ track: localTrack,+ videoTrack: rawTrack.kind === "video" ? localTrack : undefined,+ rawTrack,+ options,+ };+ this.publications.push(publication);+ return publication;+ },+ );++ readonly unpublishTrack = vi.fn(+ async (_track: FakeLocalTrack, _stopOnUnpublish: boolean) => undefined,+ );+ }++ class FakeRemotePublication {+ readonly setSubscribed = vi.fn((_subscribed: boolean) => undefined);++ constructor(+ readonly trackSid: string,+ readonly source: string,+ ) {}+ }++ class FakeRemoteParticipant {+ readonly trackPublications = new Map<string, FakeRemotePublication>();++ constructor(readonly identity: string) {}++ add(publication: FakeRemotePublication): this {+ this.trackPublications.set(publication.trackSid, publication);+ return this;+ }+ }++ class FakeRoom {+ readonly localParticipant = new FakeLocalParticipant();+ readonly remoteParticipants = new Map<string, FakeRemoteParticipant>();+ readonly handlers = new Map<string, EventHandler[]>();+ readonly connect = vi.fn(+ async (+ _url: string,+ _token: string,+ _options: Record<string, unknown>,+ ): Promise<void> => {+ await state.connectGate;+ },+ );+ readonly disconnect = vi.fn(async (_stopTracks?: boolean) => undefined);++ constructor() {+ state.rooms.push(this);+ }++ on(event: string, handler: EventHandler): this {+ const handlers = this.handlers.get(event) ?? [];+ handlers.push(handler);+ this.handlers.set(event, handlers);+ return this;+ }++ emit(event: string, ...args: unknown[]): void {+ for (const handler of this.handlers.get(event) ?? []) {+ handler(...args);+ }+ }+ }++ const state: {+ rooms: FakeRoom[];+ connectGate: Promise<void> | null;+ } = {+ rooms: [],+ connectGate: null,+ };++ return {+ FakeRemoteParticipant,+ FakeRemotePublication,+ FakeRoom,+ state,+ };+});++const RoomEvent = {+ Disconnected: "disconnected",+ ParticipantDisconnected: "participant-disconnected",+ TrackPublished: "track-published",+ TrackSubscribed: "track-subscribed",+ TrackUnpublished: "track-unpublished",+ TrackUnsubscribed: "track-unsubscribed",+} as const;++const Track = {+ Source: {+ Camera: "camera",+ ScreenShare: "screen-share",+ ScreenShareAudio: "screen-share-audio",+ },+} as const;++vi.mock("livekit-client", () => ({+ Room: livekit.FakeRoom,+ RoomEvent,+ Track,+}));++class FakeMediaStream {+ constructor(private readonly tracks: MediaStreamTrack[] = []) {}++ getTracks(): MediaStreamTrack[] {+ return [...this.tracks];+ }++ getVideoTracks(): MediaStreamTrack[] {+ return this.tracks.filter((item) => item.kind === "video");+ }++ getAudioTracks(): MediaStreamTrack[] {+ return this.tracks.filter((item) => item.kind === "audio");+ }+}++const connection = {+ url: "wss://sfu.example.test",+ token: "short-lived-token",+};++const qualityProfile = {+ label: "1080p 60",+ width: 1920,+ height: 1080,+ frameRate: 60,+ maxBitrate: 8_000_000,+} as const;++function track(kind: "video" | "audio", id: string): MediaStreamTrack {+ return { id, kind } as MediaStreamTrack;+}++function stream(...tracks: MediaStreamTrack[]): MediaStream {+ return new FakeMediaStream(tracks) as unknown as MediaStream;+}++function deferred(): {+ promise: Promise<void>;+ resolve: () => void;+} {+ let resolve = (): void => undefined;+ const promise = new Promise<void>((next) => {+ resolve = next;+ });+ return { promise, resolve };+}++beforeEach(() => {+ livekit.state.rooms.length = 0;+ livekit.state.connectGate = null;+ vi.stubGlobal("MediaStream", FakeMediaStream);+});++afterEach(() => {+ vi.unstubAllGlobals();+});++describe("SfuPublisher", () => {+ it("prepares a connection without publishing media", async () => {+ const publisher = new SfuPublisher();++ await expect(publisher.connect(connection)).resolves.toBe(true);++ const room = livekit.state.rooms[0];+ expect(room.connect).toHaveBeenCalledWith(connection.url, connection.token, {+ autoSubscribe: false,+ });+ expect(room.localParticipant.publishTrack).not.toHaveBeenCalled();++ await publisher.disconnect();+ await publisher.disconnect();+ expect(room.disconnect).toHaveBeenCalledOnce();+ expect(room.disconnect).toHaveBeenCalledWith(false);+ });++ it("publishes one screen video and optional audio only while active", async () => {+ const publisher = new SfuPublisher();+ const video = track("video", "video-1");+ const audio = track("audio", "audio-1");+ await publisher.connect(connection);++ await expect(+ publisher.activate(stream(video, audio), qualityProfile),+ ).resolves.toBe(true);++ const room = livekit.state.rooms[0];+ expect(room.localParticipant.publishTrack).toHaveBeenNthCalledWith(1, video, {+ source: Track.Source.ScreenShare,+ simulcast: false,+ screenShareEncoding: {+ maxBitrate: 8_000_000,+ maxFramerate: 60,+ },+ degradationPreference: "balanced",+ });+ expect(room.localParticipant.publishTrack).toHaveBeenNthCalledWith(2, audio, {+ source: Track.Source.ScreenShareAudio,+ dtx: false,+ });++ await expect(publisher.deactivate()).resolves.toBe(true);+ expect(room.localParticipant.unpublishTrack).toHaveBeenCalledTimes(2);+ expect(room.disconnect).not.toHaveBeenCalled();+ });++ it("updates the active sender profile without republishing", async () => {+ const publisher = new SfuPublisher();+ await publisher.connect(connection);+ await publisher.activate(stream(track("video", "video-1")), qualityProfile);+ const room = livekit.state.rooms[0];+ const videoPublication = room.localParticipant.publications[0];++ await expect(+ publisher.updateProfile({+ label: "720p 30",+ width: 1280,+ height: 720,+ frameRate: 30,+ maxBitrate: 3_000_000,+ }),+ ).resolves.toBe(true);++ expect(videoPublication.track.sender.setParameters).toHaveBeenCalledWith(+ expect.objectContaining({+ degradationPreference: "balanced",+ encodings: [+ expect.objectContaining({+ maxBitrate: 3_000_000,+ maxFramerate: 30,+ }),+ ],+ }),+ );+ expect(room.localParticipant.publishTrack).toHaveBeenCalledOnce();+ });++ it("restores the previous video after a partially applied replacement fails", async () => {+ const previousVideo = track("video", "video-1");+ const nextVideo = track("video", "video-2");+ const publisher = new SfuPublisher();+ await publisher.connect(connection);+ await publisher.activate(stream(previousVideo), qualityProfile);+ const localTrack = livekit.state.rooms[0].localParticipant.publications[0].track;+ localTrack.replaceTrack.mockImplementationOnce(async (replacement) => {+ localTrack.currentTrack = replacement;+ throw new Error("sender swap failed after applying");+ });++ await expect(publisher.replaceStream(stream(nextVideo))).resolves.toBe(false);++ expect(localTrack.replaceTrack).toHaveBeenNthCalledWith(1, nextVideo);+ expect(localTrack.replaceTrack).toHaveBeenNthCalledWith(2, previousVideo);+ expect(localTrack.currentTrack).toBe(previousVideo);+ });++ it("disconnects fail-closed when replacement rollback also fails", async () => {+ const disconnected = vi.fn();+ const previousVideo = track("video", "video-1");+ const publisher = new SfuPublisher({ onDisconnected: disconnected });+ await publisher.connect(connection);+ await publisher.activate(stream(previousVideo), qualityProfile);+ const room = livekit.state.rooms[0];+ const localTrack = room.localParticipant.publications[0].track;+ localTrack.replaceTrack+ .mockRejectedValueOnce(new Error("replace failed"))+ .mockRejectedValueOnce(new Error("rollback failed"));++ await expect(+ publisher.replaceStream(stream(track("video", "video-2"))),+ ).rejects.toThrow("rollback failed");+ expect(room.disconnect).toHaveBeenCalledWith(false);+ expect(disconnected).toHaveBeenCalledOnce();+ });++ it("does not resurrect a stale connection after disconnect", async () => {+ const gate = deferred();+ livekit.state.connectGate = gate.promise;+ const publisher = new SfuPublisher();+ const connecting = publisher.connect(connection);+ await vi.waitFor(() => expect(livekit.state.rooms).toHaveLength(1));+ const room = livekit.state.rooms[0];++ await publisher.disconnect();+ gate.resolve();++ await expect(connecting).resolves.toBe(false);+ expect(room.localParticipant.publishTrack).not.toHaveBeenCalled();+ expect(room.disconnect).toHaveBeenCalledOnce();+ });+});++describe("SfuSubscriber", () => {+ it("stays inactive while prepared and selectively subscribes after activation", async () => {+ const gate = deferred();+ livekit.state.connectGate = gate.promise;+ const streams: Array<MediaStream | null> = [];+ const subscriber = new SfuSubscriber({+ onStream: (nextStream) => streams.push(nextStream),+ });+ const connecting = subscriber.connect(connection);+ await vi.waitFor(() => expect(livekit.state.rooms).toHaveLength(1));+ const room = livekit.state.rooms[0];+ const host = new livekit.FakeRemoteParticipant("host");+ const hostVideo = new livekit.FakeRemotePublication(+ "host-video",+ Track.Source.ScreenShare,+ );+ const hostAudio = new livekit.FakeRemotePublication(+ "host-audio",+ Track.Source.ScreenShareAudio,+ );+ const hostCamera = new livekit.FakeRemotePublication(+ "host-camera",+ Track.Source.Camera,+ );+ host.add(hostVideo).add(hostAudio).add(hostCamera);+ room.remoteParticipants.set("host", host);+ const viewer = new livekit.FakeRemoteParticipant("viewer:other");+ const viewerScreen = new livekit.FakeRemotePublication(+ "viewer-screen",+ Track.Source.ScreenShare,+ );+ viewer.add(viewerScreen);+ room.remoteParticipants.set(viewer.identity, viewer);++ gate.resolve();+ await expect(connecting).resolves.toBe(true);+ expect(room.connect).toHaveBeenCalledWith(connection.url, connection.token, {+ autoSubscribe: false,+ });+ expect(hostVideo.setSubscribed).not.toHaveBeenCalled();+ expect(streams).toEqual([]);++ expect(subscriber.activate()).toBe(true);+ expect(hostVideo.setSubscribed).toHaveBeenCalledWith(true);+ expect(hostAudio.setSubscribed).toHaveBeenCalledWith(true);+ expect(hostCamera.setSubscribed).not.toHaveBeenCalled();+ expect(viewerScreen.setSubscribed).not.toHaveBeenCalled();++ const audio = track("audio", "audio-1");+ room.emit(+ RoomEvent.TrackSubscribed,+ { mediaStreamTrack: audio },+ hostAudio,+ host,+ );+ expect(streams).toEqual([]);++ const video = track("video", "video-1");+ room.emit(+ RoomEvent.TrackSubscribed,+ { mediaStreamTrack: video },+ hostVideo,+ host,+ );+ expect(streams.at(-1)?.getTracks()).toEqual([video, audio]);++ expect(subscriber.deactivate()).toBe(true);+ expect(hostVideo.setSubscribed).toHaveBeenLastCalledWith(false);+ expect(hostAudio.setSubscribed).toHaveBeenLastCalledWith(false);+ expect(streams.at(-1)).toBeNull();+ expect(room.disconnect).not.toHaveBeenCalled();+ });++ it("notifies the controller after a terminal room disconnect", async () => {+ const disconnected = vi.fn();+ const subscriber = new SfuSubscriber({+ onStream: vi.fn(),+ onDisconnected: disconnected,+ });+ await subscriber.connect(connection);+ const room = livekit.state.rooms[0];++ room.emit(RoomEvent.Disconnected);+ room.emit(RoomEvent.Disconnected);++ expect(disconnected).toHaveBeenCalledOnce();+ expect(subscriber.deactivate()).toBe(false);+ });++ it("does not activate a stale connection after disconnect", async () => {+ const gate = deferred();+ livekit.state.connectGate = gate.promise;+ const subscriber = new SfuSubscriber({ onStream: vi.fn() });+ const connecting = subscriber.connect(connection);+ await vi.waitFor(() => expect(livekit.state.rooms).toHaveLength(1));+ const room = livekit.state.rooms[0];++ await subscriber.disconnect();+ await subscriber.disconnect();+ gate.resolve();++ await expect(connecting).resolves.toBe(false);+ expect(room.disconnect).toHaveBeenCalledOnce();+ expect(() => subscriber.activate()).toThrow("expected prepared");+ });+});diff --git a/tests/viewer-message-authority.test.ts b/tests/viewer-message-authority.test.tsnew file mode 100644index 00000000..f602363f--- /dev/null+++ b/tests/viewer-message-authority.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from "vitest";++import { ViewerMessageAuthority } from "../src/client/media/viewer-message-authority.ts";+import type { ServerMessage } from "../src/shared/protocol.ts";++function message(type: ServerMessage["type"]): ServerMessage {+ return { type } as ServerMessage;+}++describe("ViewerMessageAuthority", () => {+ it("invalidates an awaited authenticated continuation on newer authority", () => {+ const authority = new ViewerMessageAuthority();+ const authenticated = authority.tokenFor(message("authenticated"));++ expect(authority.tokenFor(message("route-update"))).toBe(authenticated);+ expect(authority.owns(authenticated)).toBe(true);++ authority.tokenFor(message("sharing-stopped"));+ expect(authority.owns(authenticated)).toBe(false);+ });++ it("invalidates pending work on a newer auth, ICE snapshot, or termination", () => {+ const authority = new ViewerMessageAuthority();+ const first = authority.tokenFor(message("authenticated"));+ authority.tokenFor(message("ice-config"));+ expect(authority.owns(first)).toBe(false);++ const second = authority.tokenFor(message("authenticated"));+ authority.invalidate();+ expect(authority.owns(second)).toBe(false);+ });+});diff --git a/tests/viewer-peer-generation.test.ts b/tests/viewer-peer-generation.test.tsindex 2c952cfd..83f4a16d 100644--- a/tests/viewer-peer-generation.test.ts+++ b/tests/viewer-peer-generation.test.ts@@ -104,6 +104,8 @@ class FakePeerConnection extends EventTarget {const intervalCallbacks = new Map<number, () => void>();let nextIntervalId = 1;+const timeoutCallbacks = new Map<number, () => void>();+let nextTimeoutId = 1;function offer(connectionId: string): SignalPayload {return {@@ -154,6 +156,8 @@ beforeEach(() => {FakePeerConnection.plans.length = 0;intervalCallbacks.clear();nextIntervalId = 1;+ timeoutCallbacks.clear();+ nextTimeoutId = 1;vi.stubGlobal("MediaStream", FakeMediaStream);vi.stubGlobal("RTCPeerConnection", FakePeerConnection);vi.stubGlobal("window", {@@ -163,8 +167,12 @@ beforeEach(() => {return id;},clearInterval: (id: number) => intervalCallbacks.delete(id),- setTimeout,- clearTimeout,+ setTimeout: (callback: () => void) => {+ const id = nextTimeoutId++;+ timeoutCallbacks.set(id, callback);+ return id;+ },+ clearTimeout: (id: number) => timeoutCallbacks.delete(id),});});@@ -173,6 +181,90 @@ afterEach(() => {});describe("ViewerPeer connection generations", () => {+ it("reports one exhausted edge after bounded restart and rebuild attempts", async () => {+ const restartRequests: Array<{+ peerId: string;+ connectionId: string;+ rebuild: boolean;+ }> = [];+ const exhausted: Array<{ peerId: string; connectionId: string }> = [];+ const peer = new ViewerPeer(+ { iceServers: [], expiresAt: null, relayAvailable: false },+ {+ sendSignal: () => true,+ sendRestartRequest: (peerId, connectionId, rebuild) => {+ restartRequests.push({ peerId, connectionId, rebuild });+ return true;+ },+ onStream: () => undefined,+ onUpdate: () => undefined,+ onRecoveryExhausted: (peerId, connectionId) => {+ exhausted.push({ peerId, connectionId });+ return true;+ },+ },+ );+ await peer.acceptSignal("relay-parent", offer("failed-connection"));+ const connection = FakePeerConnection.instances[0]!;+ connection.connectionState = "failed";+ connection.dispatchEvent(new Event("connectionstatechange"));++ expect(restartRequests).toEqual([+ {+ peerId: "relay-parent",+ connectionId: "failed-connection",+ rebuild: false,+ },+ ]);+ timeoutCallbacks.get(1)!();+ expect(restartRequests.at(-1)).toEqual({+ peerId: "relay-parent",+ connectionId: "failed-connection",+ rebuild: true,+ });+ timeoutCallbacks.get(2)!();+ expect(exhausted).toEqual([+ { peerId: "relay-parent", connectionId: "failed-connection" },+ ]);++ connection.dispatchEvent(new Event("connectionstatechange"));+ expect(restartRequests).toHaveLength(2);+ expect(exhausted).toHaveLength(1);+ });++ it("retries delivery of an exhausted edge after signaling reconnects", async () => {+ let reportAvailable = false;+ const exhausted: string[] = [];+ const peer = new ViewerPeer(+ { iceServers: [], expiresAt: null, relayAvailable: false },+ {+ sendSignal: () => true,+ sendRestartRequest: () => true,+ onStream: () => undefined,+ onUpdate: () => undefined,+ onRecoveryExhausted: (_peerId, connectionId) => {+ exhausted.push(connectionId);+ return reportAvailable;+ },+ },+ );+ await peer.acceptSignal("relay-parent", offer("failed-connection"));+ const connection = FakePeerConnection.instances[0]!;+ connection.connectionState = "failed";+ connection.dispatchEvent(new Event("connectionstatechange"));++ timeoutCallbacks.get(1)!();+ timeoutCallbacks.get(2)!();+ expect(exhausted).toEqual(["failed-connection"]);++ reportAvailable = true;+ timeoutCallbacks.get(3)!();+ expect(exhausted).toEqual(["failed-connection", "failed-connection"]);++ connection.dispatchEvent(new Event("connectionstatechange"));+ expect(exhausted).toHaveLength(2);+ });+it("requests one bounded rebuild when answer negotiation fails", async () => {FakePeerConnection.plans.push({ answerError: new Error("first answer failed") },@@ -208,6 +300,36 @@ describe("ViewerPeer connection generations", () => {]);});+ it("requests a rebuild when the completed answer cannot be signaled", async () => {+ const restartRequests: Array<{+ peerId: string;+ connectionId: string;+ rebuild: boolean;+ }> = [];+ const peer = new ViewerPeer(+ { iceServers: [], expiresAt: null, relayAvailable: false },+ {+ sendSignal: () => false,+ sendRestartRequest: (peerId, connectionId, rebuild) => {+ restartRequests.push({ peerId, connectionId, rebuild });+ return true;+ },+ onStream: () => undefined,+ onUpdate: () => undefined,+ },+ );++ await peer.acceptSignal("relay-parent", offer("unsent-answer"));++ expect(restartRequests).toEqual([+ {+ peerId: "relay-parent",+ connectionId: "unsent-answer",+ rebuild: true,+ },+ ]);+ });+it("targets answers and recovery requests at the current parent", async () => {const signals: SignalPayload[] = [];const signalPeers: string[] = [];