Skip to content

armgit / Piik

Public Imported from GitHub
0

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.json
index 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.json
index 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.txt
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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 &&
currentAssignment.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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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[] = [];