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: add bounded peer-assisted relay topology

AAAadc57063e8c9
diff --git a/.env.example b/.env.example
index b3baaa5c..5bd64de7 100644
--- a/.env.example
+++ b/.env.example
@@ -16,6 +16,8 @@ ROOM_DATABASE_PATH=
ROOM_TTL_SECONDS=14400
MAX_ROOMS=1000
MAX_VIEWERS_PER_ROOM=8
+# Experimental standard-WebRTC relay chains. Keep false outside measured tests.
+PEER_ASSISTED_MEDIA=false
# ICE servers. Separate multiple URLs with commas.
STUN_URLS=
diff --git a/src/client/lib/opaque-id.ts b/src/client/lib/opaque-id.ts
new file mode 100644
index 00000000..18f08925
--- /dev/null
+++ b/src/client/lib/opaque-id.ts
@@ -0,0 +1,6 @@
+export function createOpaqueId(): string {
+ const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+ return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+ "",
+ );
+}
diff --git a/src/client/lib/session.ts b/src/client/lib/session.ts
index 1b8e9c53..7d17de77 100644
--- a/src/client/lib/session.ts
+++ b/src/client/lib/session.ts
@@ -3,6 +3,7 @@ import {
roomCodeSchema,
type CreateRoomResponse,
} from "../../shared/protocol";
+import { createOpaqueId } from "./opaque-id";
const CLIENT_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
const HOST_ROOM_STORAGE_KEY = "screener:host-room:v1";
@@ -98,11 +99,7 @@ export function getStableClientId(role: "host" | "viewer", roomId: string): stri
return existing;
}
- // randomUUID is unavailable to LAN viewers on HTTP; getRandomValues is not.
- const randomBytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
- const clientId = Array.from(randomBytes, (byte) =>
- byte.toString(16).padStart(2, "0"),
- ).join("");
+ const clientId = createOpaqueId();
writeSessionValue(storageKey, clientId);
return clientId;
}
diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsx
index 81555c85..12c5cebd 100644
--- a/src/client/pages/HostPage.tsx
+++ b/src/client/pages/HostPage.tsx
@@ -40,6 +40,10 @@ import type {
SignalConnectionState,
} from "../types";
import { HostPeer } from "../webrtc/host-peer";
+import {
+ limitMediaAssignment,
+ MAX_HOST_MEDIA_CHILDREN,
+} from "../webrtc/media-assignment";
type HostPhase = "idle" | "starting" | "live" | "ended" | "error";
@@ -122,6 +126,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
const signalRef = useRef<SignalingClient | null>(null);
const iceConfigRef = useRef<IceConfig | null>(null);
const peersRef = useRef(new Map<string, HostPeer>());
+ const peerAssistedRef = useRef(false);
const generationRef = useRef(0);
const activeGenerationRef = useRef<number | null>(null);
const sourceSwitchRef = useRef<object | null>(null);
@@ -180,6 +185,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
streamRef.current = null;
retiringStreamRef.current = null;
iceConfigRef.current = null;
+ peerAssistedRef.current = false;
setStream(null);
setDetails(null);
setRelayAvailable(false);
@@ -368,12 +374,47 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
await startPeer(peerId, generation);
}
+ function reconcilePeerAssistedChildren(
+ childPeerIds: string[],
+ generation: number,
+ ): void {
+ const assignment = limitMediaAssignment(
+ { parentPeerId: null, childPeerIds },
+ MAX_HOST_MEDIA_CHILDREN,
+ );
+ const assignedChildren = new Set(assignment.childPeerIds);
+ for (const peerId of peersRef.current.keys()) {
+ if (!assignedChildren.has(peerId)) {
+ removePeer(peerId);
+ }
+ }
+ for (const peerId of assignedChildren) {
+ void startPeer(peerId, generation).catch((error: unknown) => {
+ if (isCurrentGeneration(generation)) {
+ setNotice(readableError(error));
+ }
+ });
+ }
+ }
+
function handleSignalMessage(message: ServerMessage, generation: number): void {
if (!isCurrentGeneration(generation)) {
return;
}
if (message.type === "authenticated" && message.role === "host") {
setMaxViewers(message.maxViewers);
+ if (
+ "mediaMode" in message &&
+ message.mediaMode === "peer-assisted"
+ ) {
+ peerAssistedRef.current = true;
+ reconcilePeerAssistedChildren(
+ message.mediaAssignment.childPeerIds,
+ generation,
+ );
+ return;
+ }
+ peerAssistedRef.current = false;
const currentViewerIds = new Set(message.viewerPeerIds);
for (const peerId of peersRef.current.keys()) {
if (!currentViewerIds.has(peerId)) {
@@ -382,7 +423,19 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
}
return;
}
+ if (message.type === "media-assignment") {
+ if (peerAssistedRef.current) {
+ reconcilePeerAssistedChildren(
+ message.mediaAssignment.childPeerIds,
+ generation,
+ );
+ }
+ return;
+ }
if (message.type === "peer-joined") {
+ if (peerAssistedRef.current) {
+ return;
+ }
void startPeer(message.peerId, generation).catch((error: unknown) => {
if (isCurrentGeneration(generation)) {
setNotice(readableError(error));
@@ -391,6 +444,9 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {
return;
}
if (message.type === "peer-left") {
+ if (peerAssistedRef.current) {
+ return;
+ }
removePeer(message.peerId);
return;
}
diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsx
index a7ee5cb2..ee632928 100644
--- a/src/client/pages/ViewerPage.tsx
+++ b/src/client/pages/ViewerPage.tsx
@@ -7,7 +7,11 @@ import {
VolumeX,
} from "lucide-react";
import { useEffect, useMemo, useRef, useState } from "react";
-import type { IceConfig, ServerMessage } from "../../shared/protocol";
+import type {
+ IceConfig,
+ MediaAssignment,
+ ServerMessage,
+} from "../../shared/protocol";
import { AppHeader } from "../components/AppHeader";
import {
PathBadge,
@@ -18,11 +22,19 @@ import {
import { StatsGrid } from "../components/StatsGrid";
import { getStableClientId } from "../lib/session";
import { SignalingClient } from "../lib/signaling";
+import { QUALITY_PROFILES } from "../media/quality";
import type {
PeerSnapshot,
SignalConnectionState,
} from "../types";
+import {
+ limitMediaAssignment,
+ MAX_VIEWER_MEDIA_CHILDREN,
+ viewerRestartMessage,
+ viewerSignalMessage,
+} from "../webrtc/media-assignment";
import { ViewerPeer } from "../webrtc/viewer-peer";
+import { ViewerRelay } from "../webrtc/viewer-relay";
interface ViewerPageProps {
roomId: string;
@@ -41,6 +53,7 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
const [relayAvailable, setRelayAvailable] = useState(false);
const [remoteStream, setRemoteStream] = useState<MediaStream | null>(null);
const [peerSnapshot, setPeerSnapshot] = useState<PeerSnapshot | null>(null);
+ const [relaySnapshot, setRelaySnapshot] = useState<PeerSnapshot | null>(null);
const [playbackBlocked, setPlaybackBlocked] = useState(false);
const [muted, setMuted] = useState(false);
@@ -51,6 +64,12 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
let active = true;
let currentIceConfig: IceConfig | null = null;
let currentHostOnline = false;
+ let peerAssisted = false;
+ let currentAssignment: MediaAssignment = {
+ parentPeerId: null,
+ childPeerIds: [],
+ };
+ let viewerRelay: ViewerRelay | null = null;
const signal = new SignalingClient(
{
@@ -90,7 +109,40 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
},
);
- function clearPeerState(): void {
+ function ensureViewerRelay(): ViewerRelay | null {
+ if (viewerRelay) {
+ return viewerRelay;
+ }
+ if (!peerAssisted || !currentIceConfig) {
+ return null;
+ }
+ viewerRelay = new ViewerRelay(
+ currentIceConfig,
+ QUALITY_PROFILES["1080p60"],
+ {
+ sendSignal: (targetPeerId, payload) =>
+ active &&
+ peerAssisted &&
+ currentAssignment.childPeerIds[0] === targetPeerId
+ ? signal.send({
+ type: "signal",
+ targetPeerId,
+ payload,
+ })
+ : false,
+ onUpdate: (snapshot) => {
+ if (active) {
+ setRelaySnapshot(snapshot);
+ }
+ },
+ },
+ forceRelay,
+ );
+ viewerRelay.setChild(currentAssignment.childPeerIds[0] ?? null);
+ return viewerRelay;
+ }
+
+ function clearUpstreamState(): void {
peerRef.current?.dispose();
peerRef.current = null;
setRemoteStream(null);
@@ -98,6 +150,30 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
setPlaybackBlocked(false);
}
+ function clearPeerState(): void {
+ clearUpstreamState();
+ viewerRelay?.stop();
+ }
+
+ function applyMediaAssignment(assignment: MediaAssignment): void {
+ const nextAssignment = limitMediaAssignment(
+ assignment,
+ MAX_VIEWER_MEDIA_CHILDREN,
+ );
+ const previousParentId = currentAssignment.parentPeerId;
+ currentAssignment = nextAssignment;
+
+ if (previousParentId !== nextAssignment.parentPeerId) {
+ clearUpstreamState();
+ setStatusText(
+ nextAssignment.parentPeerId
+ ? "正在切换媒体来源"
+ : "等待可用的媒体来源",
+ );
+ }
+ ensureViewerRelay()?.setChild(nextAssignment.childPeerIds[0] ?? null);
+ }
+
function ensurePeer(): ViewerPeer | null {
if (peerRef.current) {
return peerRef.current;
@@ -108,13 +184,26 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
const peer = new ViewerPeer(
currentIceConfig,
{
- sendSignal: (payload) => signal.send({ type: "signal", payload }),
- sendRestartRequest: (connectionId, rebuild) =>
- signal.send({ type: "restart-request", connectionId, rebuild }),
+ sendSignal: (targetPeerId, payload) =>
+ signal.send(
+ viewerSignalMessage(peerAssisted, targetPeerId, payload),
+ ),
+ sendRestartRequest: (targetPeerId, connectionId, rebuild) =>
+ signal.send(
+ viewerRestartMessage(
+ peerAssisted,
+ targetPeerId,
+ connectionId,
+ rebuild,
+ ),
+ ),
onStream: (nextStream) => {
if (active) {
setRemoteStream(nextStream);
setStatusText("正在播放");
+ // Audio and video can arrive as separate track events on the
+ // same MediaStream, so refresh both downstream senders each time.
+ ensureViewerRelay()?.setStream(nextStream);
}
},
onUpdate: (snapshot) => {
@@ -147,10 +236,22 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
async function handleMessage(message: ServerMessage): Promise<void> {
if (message.type === "authenticated") {
+ const nextPeerAssisted =
+ "mediaMode" in message && message.mediaMode === "peer-assisted";
+ if (!nextPeerAssisted && peerAssisted) {
+ clearPeerState();
+ viewerRelay?.dispose();
+ viewerRelay = null;
+ currentAssignment = { parentPeerId: null, childPeerIds: [] };
+ }
+ peerAssisted = nextPeerAssisted;
currentIceConfig = message.iceConfig;
currentHostOnline = message.hostOnline;
setRelayAvailable(message.iceConfig.relayAvailable);
setHostOnline(message.hostOnline);
+ if (nextPeerAssisted) {
+ applyMediaAssignment(message.mediaAssignment);
+ }
if (
!message.hostOnline &&
message.connectionId === null &&
@@ -163,21 +264,54 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
);
const peer = peerRef.current;
peer?.updateIceConfig(message.iceConfig);
+ viewerRelay?.updateIceConfig(message.iceConfig);
if (
message.connectionId &&
!peer?.hasConnectionId(message.connectionId)
) {
- signal.send({
- type: "restart-request",
- connectionId: message.connectionId,
- rebuild: true,
- });
+ const parentPeerId = currentAssignment.parentPeerId;
+ if (!peerAssisted) {
+ signal.send({
+ type: "restart-request",
+ connectionId: message.connectionId,
+ rebuild: true,
+ });
+ } else if (parentPeerId) {
+ signal.send({
+ type: "restart-request",
+ targetPeerId: parentPeerId,
+ connectionId: message.connectionId,
+ rebuild: true,
+ });
+ }
} else if (peer?.hasConnection() && !peer.isConnected()) {
peer.requestRecovery();
}
return;
}
+ if (message.type === "media-assignment") {
+ if (peerAssisted) {
+ applyMediaAssignment(message.mediaAssignment);
+ }
+ return;
+ }
if (message.type === "signal") {
+ if (
+ peerAssisted &&
+ currentAssignment.childPeerIds[0] === message.fromPeerId
+ ) {
+ await viewerRelay?.acceptSignal(
+ message.fromPeerId,
+ message.payload,
+ );
+ return;
+ }
+ if (
+ peerAssisted &&
+ currentAssignment.parentPeerId !== message.fromPeerId
+ ) {
+ return;
+ }
const peer = ensurePeer();
if (!peer) {
setStatusText("尚未收到可用的 ICE 配置");
@@ -186,10 +320,21 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
await peer.acceptSignal(message.fromPeerId, message.payload);
return;
}
+ if (message.type === "restart-request") {
+ if (peerAssisted) {
+ await viewerRelay?.recover(
+ message.fromPeerId,
+ message.connectionId,
+ message.rebuild,
+ );
+ }
+ return;
+ }
if (message.type === "ice-config") {
currentIceConfig = message.iceConfig;
setRelayAvailable(message.iceConfig.relayAvailable);
peerRef.current?.updateIceConfig(message.iceConfig);
+ viewerRelay?.updateIceConfig(message.iceConfig);
return;
}
if (message.type === "host-status") {
@@ -241,6 +386,8 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
signal.stop();
peerRef.current?.dispose();
peerRef.current = null;
+ viewerRelay?.dispose();
+ viewerRelay = null;
};
}, [forceRelay, onAuthorizationRequired, roomId]);
@@ -401,6 +548,12 @@ export function ViewerPage({ roomId, onAuthorizationRequired }: ViewerPageProps)
<StatsGrid metrics={peerSnapshot.metrics} direction="receive" />
</section>
)}
+ {relaySnapshot && (
+ <section className="viewer-stats" aria-labelledby="relay-stats-heading">
+ <h2 id="relay-stats-heading">转发数据</h2>
+ <StatsGrid metrics={relaySnapshot.metrics} direction="send" />
+ </section>
+ )}
</main>
</div>
);
diff --git a/src/client/webrtc/host-peer.ts b/src/client/webrtc/host-peer.ts
index e8d7ece9..e3b340d8 100644
--- a/src/client/webrtc/host-peer.ts
+++ b/src/client/webrtc/host-peer.ts
@@ -1,4 +1,5 @@
import type { IceConfig, SignalPayload } from "../../shared/protocol";
+import { createOpaqueId } from "../lib/opaque-id";
import type { QualityProfile } from "../media/quality";
import { configureVideoSender } from "../media/quality";
import {
@@ -22,7 +23,7 @@ interface HostPeerEvents {
}
export class HostPeer {
- readonly connectionId = crypto.randomUUID();
+ readonly connectionId = createOpaqueId();
private readonly connection: RTCPeerConnection;
private readonly pendingCandidates: SignalCandidate[] = [];
diff --git a/src/client/webrtc/media-assignment.ts b/src/client/webrtc/media-assignment.ts
new file mode 100644
index 00000000..c416cdc8
--- /dev/null
+++ b/src/client/webrtc/media-assignment.ts
@@ -0,0 +1,44 @@
+import type {
+ ClientMessage,
+ MediaAssignment,
+ SignalPayload,
+} from "../../shared/protocol";
+
+export const MAX_HOST_MEDIA_CHILDREN = 2;
+export const MAX_VIEWER_MEDIA_CHILDREN = 1;
+
+export function limitMediaAssignment(
+ assignment: MediaAssignment,
+ maxChildren: number,
+): MediaAssignment {
+ return {
+ parentPeerId: assignment.parentPeerId,
+ childPeerIds: [...new Set(assignment.childPeerIds)].slice(0, maxChildren),
+ };
+}
+
+export function viewerSignalMessage(
+ peerAssisted: boolean,
+ targetPeerId: string,
+ payload: SignalPayload,
+): Extract<ClientMessage, { type: "signal" }> {
+ return peerAssisted
+ ? { type: "signal", targetPeerId, payload }
+ : { type: "signal", payload };
+}
+
+export function viewerRestartMessage(
+ peerAssisted: boolean,
+ targetPeerId: string,
+ connectionId: string,
+ rebuild: boolean,
+): Extract<ClientMessage, { type: "restart-request" }> {
+ return peerAssisted
+ ? {
+ type: "restart-request",
+ targetPeerId,
+ connectionId,
+ rebuild,
+ }
+ : { type: "restart-request", connectionId, rebuild };
+}
diff --git a/src/client/webrtc/viewer-peer.ts b/src/client/webrtc/viewer-peer.ts
index beea3127..d3ab443a 100644
--- a/src/client/webrtc/viewer-peer.ts
+++ b/src/client/webrtc/viewer-peer.ts
@@ -16,8 +16,12 @@ type SignalCandidate = Extract<
>["candidate"];
interface ViewerPeerEvents {
- sendSignal: (payload: SignalPayload) => boolean;
- sendRestartRequest: (connectionId: string, rebuild: boolean) => boolean;
+ sendSignal: (peerId: string, payload: SignalPayload) => boolean;
+ sendRestartRequest: (
+ peerId: string,
+ connectionId: string,
+ rebuild: boolean,
+ ) => boolean;
onStream: (stream: MediaStream) => void;
onUpdate: (snapshot: PeerSnapshot) => void;
}
@@ -25,7 +29,7 @@ interface ViewerPeerEvents {
export class ViewerPeer {
private connection: RTCPeerConnection | null = null;
private connectionId: string | null = null;
- private hostPeerId: string | null = null;
+ private parentPeerId: string | null = null;
private remoteStream = new MediaStream();
private pendingByConnection = new Map<
string,
@@ -35,6 +39,7 @@ export class ViewerPeer {
private statsTimer: number | null = null;
private disconnectTimer: number | null = null;
private restartRequested = false;
+ private offerRecoveryAttempts = 0;
private disposed = false;
private currentIceConfig: IceConfig;
private snapshot: PeerSnapshot | null = null;
@@ -48,13 +53,12 @@ export class ViewerPeer {
}
async acceptSignal(
- hostPeerId: string,
+ parentPeerId: string,
payload: SignalPayload,
): Promise<void> {
if (this.disposed) {
return;
}
- this.hostPeerId = hostPeerId;
let operationConnection: RTCPeerConnection | null = null;
let operationConnectionId: string | null = null;
@@ -63,8 +67,12 @@ export class ViewerPeer {
if (payload.description.type !== "offer") {
return;
}
- if (!this.connection || this.connectionId !== payload.connectionId) {
- this.replaceConnection(hostPeerId, payload.connectionId);
+ if (
+ !this.connection ||
+ this.connectionId !== payload.connectionId ||
+ this.parentPeerId !== parentPeerId
+ ) {
+ this.replaceConnection(parentPeerId, payload.connectionId);
}
const connection = this.connection;
if (!connection) {
@@ -92,7 +100,7 @@ export class ViewerPeer {
if (!connection.localDescription) {
throw new Error("Local description was not created");
}
- this.events.sendSignal({
+ this.events.sendSignal(parentPeerId, {
kind: "description",
connectionId,
description: {
@@ -101,8 +109,10 @@ export class ViewerPeer {
},
});
this.restartRequested = false;
+ this.offerRecoveryAttempts = 0;
} else if (
this.connection &&
+ this.parentPeerId === parentPeerId &&
this.connectionId === payload.connectionId &&
this.connection.remoteDescription
) {
@@ -126,6 +136,18 @@ export class ViewerPeer {
return;
}
this.setError(error, "处理分享端信令失败");
+ if (
+ payload.kind === "description" &&
+ this.offerRecoveryAttempts < 1 &&
+ this.events.sendRestartRequest(
+ parentPeerId,
+ operationConnectionId,
+ true,
+ )
+ ) {
+ this.offerRecoveryAttempts += 1;
+ this.restartRequested = true;
+ }
}
}
@@ -145,10 +167,14 @@ export class ViewerPeer {
}
requestRecovery(): boolean {
- if (!this.connectionId) {
+ if (!this.connectionId || !this.parentPeerId) {
return false;
}
- const sent = this.events.sendRestartRequest(this.connectionId, false);
+ const sent = this.events.sendRestartRequest(
+ this.parentPeerId,
+ this.connectionId,
+ false,
+ );
if (sent) {
this.restartRequested = true;
}
@@ -176,9 +202,14 @@ export class ViewerPeer {
this.pendingByConnection.clear();
}
- private replaceConnection(hostPeerId: string, connectionId: string): void {
+ private replaceConnection(parentPeerId: string, connectionId: string): void {
+ const parentChanged =
+ this.parentPeerId !== null && this.parentPeerId !== parentPeerId;
this.disposeConnection();
- this.hostPeerId = hostPeerId;
+ if (parentChanged) {
+ this.offerRecoveryAttempts = 0;
+ }
+ this.parentPeerId = parentPeerId;
this.connectionId = connectionId;
this.remoteStream = new MediaStream();
this.statsAccumulator = createStatsAccumulator();
@@ -190,7 +221,7 @@ export class ViewerPeer {
});
this.connection = connection;
this.snapshot = {
- peerId: hostPeerId,
+ peerId: parentPeerId,
connectionId,
connectionState: connection.connectionState,
iceConnectionState: connection.iceConnectionState,
@@ -199,10 +230,10 @@ export class ViewerPeer {
};
connection.addEventListener("icecandidate", (event) => {
- if (!this.hostPeerId || this.connection !== connection) {
+ if (!this.parentPeerId || this.connection !== connection) {
return;
}
- this.events.sendSignal({
+ this.events.sendSignal(parentPeerId, {
kind: "candidate",
connectionId,
candidate: event.candidate
@@ -385,6 +416,7 @@ export class ViewerPeer {
this.connection?.close();
this.connection = null;
this.connectionId = null;
+ this.parentPeerId = null;
this.snapshot = null;
}
}
diff --git a/src/client/webrtc/viewer-relay.ts b/src/client/webrtc/viewer-relay.ts
new file mode 100644
index 00000000..8da12232
--- /dev/null
+++ b/src/client/webrtc/viewer-relay.ts
@@ -0,0 +1,228 @@
+import type { IceConfig, SignalPayload } from "../../shared/protocol";
+import type { QualityProfile } from "../media/quality";
+import type { PeerSnapshot } from "../types";
+import { HostPeer } from "./host-peer";
+
+interface ViewerRelayEvents {
+ sendSignal: (peerId: string, payload: SignalPayload) => boolean;
+ onUpdate?: (snapshot: PeerSnapshot | null) => void;
+}
+
+export class ViewerRelay {
+ private childPeerId: string | null = null;
+ private stream: MediaStream | null = null;
+ private peer: HostPeer | null = null;
+ private snapshot: PeerSnapshot | null = null;
+ private syncQueue = Promise.resolve();
+ private disposed = false;
+
+ constructor(
+ private iceConfig: IceConfig,
+ private readonly profile: QualityProfile,
+ private readonly events: ViewerRelayEvents,
+ private readonly forceRelay = false,
+ ) {}
+
+ getSnapshot(): PeerSnapshot | null {
+ return this.snapshot
+ ? { ...this.snapshot, metrics: { ...this.snapshot.metrics } }
+ : null;
+ }
+
+ setChild(childPeerId: string | null): void {
+ if (this.disposed) {
+ return;
+ }
+ if (this.childPeerId === childPeerId) {
+ if (
+ childPeerId &&
+ this.stream &&
+ (!this.peer || !this.peer.isConnected())
+ ) {
+ this.disposePeer();
+ this.startPeer(childPeerId, this.stream);
+ }
+ return;
+ }
+ this.disposePeer();
+ this.childPeerId = childPeerId;
+ if (childPeerId && this.stream) {
+ this.startPeer(childPeerId, this.stream);
+ }
+ }
+
+ setStream(stream: MediaStream): void {
+ if (this.disposed) {
+ return;
+ }
+ this.stream = stream;
+ this.syncQueue = this.syncQueue
+ .then(() => this.syncStream(stream))
+ .catch(() => undefined);
+ }
+
+ async acceptSignal(
+ fromPeerId: string,
+ payload: SignalPayload,
+ ): Promise<void> {
+ if (fromPeerId !== this.childPeerId) {
+ return;
+ }
+ await this.peer?.acceptSignal(payload);
+ }
+
+ async recover(
+ fromPeerId: string,
+ connectionId: string,
+ rebuild: boolean,
+ ): Promise<void> {
+ const stream = this.stream;
+ const peer = this.peer;
+ if (this.disposed || !stream || fromPeerId !== this.childPeerId) {
+ return;
+ }
+ if (rebuild) {
+ if (peer && peer.connectionId !== connectionId) {
+ return;
+ }
+ this.disposePeer();
+ this.startPeer(fromPeerId, stream);
+ return;
+ }
+ if (!peer || peer.connectionId !== connectionId) {
+ return;
+ }
+ if (await peer.restartIce()) {
+ return;
+ }
+ if (this.peer === peer) {
+ this.disposePeer();
+ this.startPeer(fromPeerId, stream);
+ }
+ }
+
+ updateIceConfig(iceConfig: IceConfig): void {
+ this.iceConfig = iceConfig;
+ this.peer?.updateIceConfig(iceConfig);
+ }
+
+ stop(): void {
+ this.stream = null;
+ this.disposePeer();
+ }
+
+ dispose(): void {
+ if (this.disposed) {
+ return;
+ }
+ this.disposed = true;
+ this.stream = null;
+ this.childPeerId = null;
+ this.disposePeer();
+ }
+
+ private async syncStream(stream: MediaStream): Promise<void> {
+ const childPeerId = this.childPeerId;
+ if (this.disposed || this.stream !== stream || !childPeerId) {
+ return;
+ }
+ const peer = this.peer;
+ if (!peer) {
+ this.startPeer(childPeerId, stream);
+ return;
+ }
+
+ let replaced = false;
+ try {
+ replaced = await peer.replaceStream(stream, this.profile);
+ } catch {
+ // Rebuilding below is safer than leaving a stopped upstream track.
+ }
+ if (
+ replaced ||
+ this.disposed ||
+ this.peer !== peer ||
+ this.stream !== stream ||
+ this.childPeerId !== childPeerId
+ ) {
+ return;
+ }
+ this.disposePeer();
+ this.startPeer(childPeerId, stream);
+ }
+
+ private startPeer(
+ childPeerId: string,
+ stream: MediaStream,
+ attempt = 0,
+ ): void {
+ if (
+ this.disposed ||
+ this.peer ||
+ this.stream !== stream ||
+ this.childPeerId !== childPeerId
+ ) {
+ return;
+ }
+
+ let peer: HostPeer;
+ peer = new HostPeer(
+ childPeerId,
+ this.iceConfig,
+ stream,
+ this.profile,
+ {
+ sendSignal: (targetPeerId, payload) =>
+ !this.disposed &&
+ this.peer === peer &&
+ this.childPeerId === targetPeerId
+ ? this.events.sendSignal(targetPeerId, payload)
+ : false,
+ onUpdate: (snapshot) => {
+ if (
+ !this.disposed &&
+ this.peer === peer &&
+ this.childPeerId === childPeerId &&
+ snapshot.peerId === childPeerId &&
+ snapshot.connectionId === peer.connectionId
+ ) {
+ this.snapshot = {
+ ...snapshot,
+ metrics: { ...snapshot.metrics },
+ };
+ this.events.onUpdate?.(this.getSnapshot());
+ }
+ },
+ },
+ this.forceRelay,
+ );
+ this.peer = peer;
+ void peer
+ .start()
+ .catch(() => false)
+ .then((started) => {
+ if (started || this.peer !== peer) {
+ return;
+ }
+ this.disposePeer();
+ if (
+ attempt < 1 &&
+ !this.disposed &&
+ this.stream === stream &&
+ this.childPeerId === childPeerId
+ ) {
+ window.setTimeout(() => {
+ this.startPeer(childPeerId, stream, attempt + 1);
+ }, 500);
+ }
+ });
+ }
+
+ private disposePeer(): void {
+ const peer = this.peer;
+ this.peer = null;
+ this.snapshot = null;
+ this.events.onUpdate?.(null);
+ peer?.dispose();
+ }
+}
diff --git a/src/server/app.ts b/src/server/app.ts
index 761c5a82..fc589c88 100644
--- a/src/server/app.ts
+++ b/src/server/app.ts
@@ -93,6 +93,7 @@ export async function createScreenerServer(
const signaling = new SignalingServer({
server: httpServer,
roomStore,
+ peerAssistedMedia: config.peerAssistedMedia,
ice: iceOptions,
allowedOrigins: config.allowedOrigins,
authorizeUpgrade: (request) =>
diff --git a/src/server/config.ts b/src/server/config.ts
index 28e69e8a..48ba5034 100644
--- a/src/server/config.ts
+++ b/src/server/config.ts
@@ -5,6 +5,7 @@ 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 MAX_PEER_ASSISTED_VIEWERS = 8;
const DEFAULT_MAX_VIEWERS_PER_ROOM = 8;
const VISIBLE_ASCII_PATTERN = /^[\x21-\x7e]+$/;
@@ -19,12 +20,30 @@ export interface ServerConfig {
roomTtlMs: number;
maxRooms: number;
maxViewersPerRoom: number;
+ peerAssistedMedia: boolean;
stunUrls: readonly string[];
turnUrls: readonly string[];
turnSharedSecret?: string;
turnCredentialTtlSeconds: number;
}
+function parseBoolean(
+ value: string | undefined,
+ fallback: boolean,
+ name: string,
+): boolean {
+ if (value === undefined || value === "") {
+ return fallback;
+ }
+ if (value === "true") {
+ return true;
+ }
+ if (value === "false") {
+ return false;
+ }
+ throw new Error(`${name} must be true or false`);
+}
+
interface IceEndpoint {
scheme: "stun" | "stuns" | "turn" | "turns";
port?: number;
@@ -256,6 +275,18 @@ export function loadConfig(
"TURN_URLS",
new Set(["turn:", "turns:"]),
);
+ const maxViewersPerRoom = parseBoundedInteger(
+ environment.MAX_VIEWERS_PER_ROOM,
+ DEFAULT_MAX_VIEWERS_PER_ROOM,
+ "MAX_VIEWERS_PER_ROOM",
+ 1,
+ MAX_VIEWERS_PER_ROOM_LIMIT,
+ );
+ const peerAssistedMedia = parseBoolean(
+ environment.PEER_ASSISTED_MEDIA,
+ false,
+ "PEER_ASSISTED_MEDIA",
+ );
if ((turnUrls.length > 0) !== Boolean(turnSharedSecret)) {
throw new Error(
@@ -293,6 +324,11 @@ export function loadConfig(
if (nodeEnv === "production") {
requireProductionTurnCoverage(turnUrls);
}
+ if (peerAssistedMedia && maxViewersPerRoom > MAX_PEER_ASSISTED_VIEWERS) {
+ throw new Error(
+ "PEER_ASSISTED_MEDIA currently supports at most 8 viewers per room",
+ );
+ }
return {
nodeEnv,
@@ -309,13 +345,8 @@ export function loadConfig(
parsePositiveInteger(environment.ROOM_TTL_SECONDS, 14_400, "ROOM_TTL_SECONDS") *
1_000,
maxRooms: parsePositiveInteger(environment.MAX_ROOMS, 1_000, "MAX_ROOMS"),
- maxViewersPerRoom: parseBoundedInteger(
- environment.MAX_VIEWERS_PER_ROOM,
- DEFAULT_MAX_VIEWERS_PER_ROOM,
- "MAX_VIEWERS_PER_ROOM",
- 1,
- MAX_VIEWERS_PER_ROOM_LIMIT,
- ),
+ maxViewersPerRoom,
+ peerAssistedMedia,
stunUrls,
turnUrls,
turnSharedSecret,
diff --git a/src/server/peer-relay-topology.ts b/src/server/peer-relay-topology.ts
new file mode 100644
index 00000000..ccaf9b84
--- /dev/null
+++ b/src/server/peer-relay-topology.ts
@@ -0,0 +1,280 @@
+import type { MediaAssignment } from "../shared/protocol.js";
+
+export interface MediaAssignmentChange {
+ peerId: string;
+ previousParentPeerId?: string | null;
+ mediaAssignment: MediaAssignment;
+}
+
+interface RelayViewer {
+ order: number;
+ parentPeerId: string | null;
+ childPeerIds: string[];
+}
+
+interface RelayRoom {
+ hostPeerId?: string;
+ hostChildPeerIds: string[];
+ viewers: Map<string, RelayViewer>;
+ nextOrder: number;
+}
+
+export class PeerRelayTopology {
+ private readonly rooms = new Map<string, RelayRoom>();
+
+ setHost(
+ roomId: string,
+ hostPeerId: string,
+ connectedPeerIds: ReadonlySet<string>,
+ ): MediaAssignmentChange[] {
+ const room = this.room(roomId);
+ const before = snapshot(room);
+ const previousHostPeerId = room.hostPeerId;
+ room.hostPeerId = hostPeerId;
+
+ if (previousHostPeerId !== hostPeerId) {
+ for (const childPeerId of room.hostChildPeerIds) {
+ const child = room.viewers.get(childPeerId);
+ if (child) {
+ child.parentPeerId = hostPeerId;
+ }
+ }
+ }
+
+ for (const [peerId, viewer] of orderedViewers(room)) {
+ if (viewer.parentPeerId === null) {
+ this.assignViewer(room, peerId, connectedPeerIds);
+ }
+ }
+ return changedAssignments(before, snapshot(room));
+ }
+
+ addViewer(
+ roomId: string,
+ peerId: string,
+ connectedPeerIds: ReadonlySet<string>,
+ ): MediaAssignmentChange[] {
+ const room = this.room(roomId);
+ const before = snapshot(room);
+ if (!room.viewers.has(peerId)) {
+ room.viewers.set(peerId, {
+ order: room.nextOrder,
+ parentPeerId: null,
+ childPeerIds: [],
+ });
+ room.nextOrder += 1;
+ }
+ for (const [candidatePeerId, viewer] of orderedViewers(room)) {
+ if (viewer.parentPeerId === null) {
+ this.assignViewer(room, candidatePeerId, connectedPeerIds);
+ }
+ }
+ return changedAssignments(before, snapshot(room));
+ }
+
+ removeViewer(
+ roomId: string,
+ peerId: string,
+ connectedPeerIds: ReadonlySet<string>,
+ ): MediaAssignmentChange[] {
+ const room = this.rooms.get(roomId);
+ const removed = room?.viewers.get(peerId);
+ if (!room || !removed) {
+ return [];
+ }
+
+ const before = snapshot(room);
+ this.detach(room, peerId, removed.parentPeerId);
+ const subtreeRootPeerId = removed.childPeerIds[0];
+ if (subtreeRootPeerId) {
+ const subtreeRoot = room.viewers.get(subtreeRootPeerId);
+ if (subtreeRoot) {
+ subtreeRoot.parentPeerId = null;
+ }
+ }
+ room.viewers.delete(peerId);
+
+ if (subtreeRootPeerId) {
+ this.assignViewer(room, subtreeRootPeerId, connectedPeerIds);
+ }
+ for (const [candidatePeerId, viewer] of orderedViewers(room)) {
+ if (viewer.parentPeerId === null) {
+ this.assignViewer(room, candidatePeerId, connectedPeerIds);
+ }
+ }
+ return changedAssignments(before, snapshot(room));
+ }
+
+ getAssignment(
+ roomId: string,
+ peerId: string,
+ ): MediaAssignment | undefined {
+ const room = this.rooms.get(roomId);
+ if (!room) {
+ return undefined;
+ }
+ if (room.hostPeerId === peerId) {
+ return {
+ parentPeerId: null,
+ childPeerIds: [...room.hostChildPeerIds],
+ };
+ }
+ const viewer = room.viewers.get(peerId);
+ return viewer
+ ? {
+ parentPeerId: viewer.parentPeerId,
+ childPeerIds: [...viewer.childPeerIds],
+ }
+ : undefined;
+ }
+
+ isParentOf(roomId: string, parentPeerId: string, childPeerId: string): boolean {
+ return (
+ this.rooms.get(roomId)?.viewers.get(childPeerId)?.parentPeerId ===
+ parentPeerId
+ );
+ }
+
+ deleteRoom(roomId: string): void {
+ this.rooms.delete(roomId);
+ }
+
+ private room(roomId: string): RelayRoom {
+ let room = this.rooms.get(roomId);
+ if (!room) {
+ room = {
+ hostChildPeerIds: [],
+ viewers: new Map(),
+ nextOrder: 0,
+ };
+ this.rooms.set(roomId, room);
+ }
+ return room;
+ }
+
+ private assignViewer(
+ room: RelayRoom,
+ peerId: string,
+ connectedPeerIds: ReadonlySet<string>,
+ ): void {
+ const viewer = room.viewers.get(peerId);
+ if (
+ !viewer ||
+ viewer.parentPeerId !== null ||
+ !connectedPeerIds.has(peerId)
+ ) {
+ return;
+ }
+ const parentPeerId = findShallowestAvailableParent(room, connectedPeerIds);
+ if (!parentPeerId) {
+ return;
+ }
+ 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,
+ );
+ }
+
+ private detach(
+ room: RelayRoom,
+ peerId: string,
+ parentPeerId: string | null,
+ ): void {
+ if (!parentPeerId) {
+ return;
+ }
+ const children = childPeerIds(room, parentPeerId);
+ const childIndex = children.indexOf(peerId);
+ if (childIndex !== -1) {
+ children.splice(childIndex, 1);
+ }
+ }
+}
+
+function findShallowestAvailableParent(
+ room: RelayRoom,
+ connectedPeerIds: ReadonlySet<string>,
+): string | undefined {
+ const hostPeerId = room.hostPeerId;
+ if (!hostPeerId || !connectedPeerIds.has(hostPeerId)) {
+ return undefined;
+ }
+
+ const queue = [hostPeerId];
+ while (queue.length > 0) {
+ const peerId = queue.shift()!;
+ if (!connectedPeerIds.has(peerId)) {
+ continue;
+ }
+ const children = childPeerIds(room, peerId);
+ const capacity = peerId === hostPeerId ? 2 : 1;
+ if (children.length < capacity) {
+ return peerId;
+ }
+ queue.push(...children);
+ }
+ return undefined;
+}
+
+function childPeerIds(room: RelayRoom, peerId: string): string[] {
+ if (room.hostPeerId === peerId) {
+ return room.hostChildPeerIds;
+ }
+ const viewer = room.viewers.get(peerId);
+ if (!viewer) {
+ throw new Error("Peer relay topology references an unknown parent");
+ }
+ return viewer.childPeerIds;
+}
+
+function orderedViewers(room: RelayRoom): Array<[string, RelayViewer]> {
+ return [...room.viewers.entries()].sort(
+ ([, left], [, right]) => left.order - right.order,
+ );
+}
+
+function snapshot(room: RelayRoom): Map<string, MediaAssignment> {
+ const assignments = new Map<string, MediaAssignment>();
+ if (room.hostPeerId) {
+ assignments.set(room.hostPeerId, {
+ parentPeerId: null,
+ childPeerIds: [...room.hostChildPeerIds],
+ });
+ }
+ for (const [peerId, viewer] of room.viewers) {
+ assignments.set(peerId, {
+ parentPeerId: viewer.parentPeerId,
+ childPeerIds: [...viewer.childPeerIds],
+ });
+ }
+ return assignments;
+}
+
+function changedAssignments(
+ before: ReadonlyMap<string, MediaAssignment>,
+ after: ReadonlyMap<string, MediaAssignment>,
+): MediaAssignmentChange[] {
+ const changes: MediaAssignmentChange[] = [];
+ for (const [peerId, mediaAssignment] of after) {
+ const previous = before.get(peerId);
+ if (
+ !previous ||
+ previous.parentPeerId !== mediaAssignment.parentPeerId ||
+ previous.childPeerIds.length !== mediaAssignment.childPeerIds.length ||
+ previous.childPeerIds.some(
+ (childPeerId, index) =>
+ childPeerId !== mediaAssignment.childPeerIds[index],
+ )
+ ) {
+ changes.push({
+ peerId,
+ previousParentPeerId: previous?.parentPeerId,
+ mediaAssignment,
+ });
+ }
+ }
+ return changes;
+}
diff --git a/src/server/signaling.ts b/src/server/signaling.ts
index b07ea99a..9ef3ecb3 100644
--- a/src/server/signaling.ts
+++ b/src/server/signaling.ts
@@ -12,6 +12,10 @@ import {
type ServerMessage,
} from "../shared/protocol.js";
import { RoomStore, RoomStoreError } from "./room-store.js";
+import {
+ PeerRelayTopology,
+ type MediaAssignmentChange,
+} from "./peer-relay-topology.js";
import { createIceConfig, type IceConfigOptions } from "./turn.js";
type ErrorCode = Extract<ServerMessage, { type: "error" }>["code"];
@@ -37,6 +41,7 @@ interface SocketState {
export interface SignalingOptions {
server: HttpServer;
roomStore: RoomStore;
+ peerAssistedMedia: boolean;
ice: IceConfigOptions;
allowedOrigins: ReadonlySet<string>;
authorizeUpgrade: (request: IncomingMessage) => boolean;
@@ -60,6 +65,7 @@ export class SignalingServer {
private readonly socketsBySessionId = new Map<string, WebSocket>();
private readonly viewerGraceTimers = new Map<string, NodeJS.Timeout>();
private readonly connectionIdsByViewer = new Map<string, string>();
+ private readonly peerRelayTopology = new PeerRelayTopology();
private readonly now: () => number;
private readonly authenticationTimeoutMs: number;
private readonly viewerDisconnectGraceMs: number;
@@ -283,6 +289,32 @@ export class SignalingServer {
: Date.parse(participant.expiresAt),
};
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) {
+ 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");
+ return;
+ }
const connectionId =
participant.role === "viewer"
? (this.connectionIdsByViewer.get(
@@ -294,8 +326,8 @@ export class SignalingServer {
? this.options.roomStore.getConnectedViewers(participant.roomId)
: [];
- this.send(socket, {
- type: "authenticated",
+ const authenticatedMessage = {
+ type: "authenticated" as const,
role: participant.role,
peerId: participant.peerId,
roomExpiresAt: participant.expiresAt,
@@ -310,7 +342,16 @@ export class SignalingServer {
? null
: Date.parse(participant.expiresAt),
),
- });
+ };
+ if (mediaAssignment) {
+ this.send(socket, {
+ ...authenticatedMessage,
+ mediaMode: "peer-assisted",
+ mediaAssignment,
+ });
+ } else {
+ this.send(socket, authenticatedMessage);
+ }
if (participant.replacedSessionId) {
const replaced = this.socketsBySessionId.get(participant.replacedSessionId);
@@ -319,14 +360,40 @@ export class SignalingServer {
}
}
+ if (this.options.peerAssistedMedia) {
+ this.sendMediaAssignmentChanges(
+ participant.roomId,
+ assignmentChanges,
+ participant.peerId,
+ );
+ if (
+ participant.role === "viewer" &&
+ mediaAssignment?.parentPeerId &&
+ !assignmentChanges.some(
+ ({ peerId }) => peerId === mediaAssignment.parentPeerId,
+ )
+ ) {
+ this.sendCurrentParentAssignment(
+ participant.roomId,
+ participant.peerId,
+ );
+ }
+ }
+
if (participant.role === "host") {
for (const viewer of connectedViewers) {
this.sendToSession(viewer.sessionId, { type: "host-status", online: true });
- this.send(socket, { type: "peer-joined", peerId: viewer.peerId });
+ if (!this.options.peerAssistedMedia) {
+ this.send(socket, { type: "peer-joined", peerId: viewer.peerId });
+ }
}
return;
}
+ if (this.options.peerAssistedMedia) {
+ return;
+ }
+
const host = this.options.roomStore.getConnectedHost(participant.roomId);
if (!host) {
return;
@@ -354,6 +421,14 @@ export class SignalingServer {
this.sendError(socket, "FORBIDDEN", "Only viewers may request an ICE restart");
return;
}
+ if (this.options.peerAssistedMedia) {
+ this.routePeerAssistedRestart(socket, authenticated, message);
+ return;
+ }
+ if (message.targetPeerId) {
+ this.sendError(socket, "FORBIDDEN", "P2P restart requests target the host implicitly");
+ return;
+ }
this.routeToHost(socket, authenticated, {
type: "restart-request",
fromPeerId: authenticated.peerId,
@@ -408,6 +483,11 @@ export class SignalingServer {
source: AuthenticatedSession,
message: Extract<ClientMessage, { type: "signal" }>,
): void {
+ if (this.options.peerAssistedMedia) {
+ this.routePeerAssistedSignal(sourceSocket, source, message);
+ return;
+ }
+
const description =
message.payload.kind === "description" ? message.payload.description : undefined;
@@ -449,6 +529,101 @@ export class SignalingServer {
});
}
+ private routePeerAssistedSignal(
+ sourceSocket: WebSocket,
+ source: AuthenticatedSession,
+ message: Extract<ClientMessage, { type: "signal" }>,
+ ): void {
+ const targetPeerId = message.targetPeerId;
+ if (!targetPeerId) {
+ this.sendError(
+ sourceSocket,
+ "FORBIDDEN",
+ "Peer-assisted signals must target an assigned peer",
+ );
+ return;
+ }
+ const target = this.connectedPeer(source.roomId, targetPeerId);
+ if (!target) {
+ this.sendError(sourceSocket, "PEER_NOT_FOUND", "Target peer is not connected");
+ return;
+ }
+
+ const parentToChild = this.peerRelayTopology.isParentOf(
+ source.roomId,
+ source.peerId,
+ targetPeerId,
+ );
+ const childToParent = this.peerRelayTopology.isParentOf(
+ source.roomId,
+ targetPeerId,
+ source.peerId,
+ );
+ const description =
+ message.payload.kind === "description"
+ ? message.payload.description
+ : undefined;
+ const authorized = description
+ ? description.type === "offer"
+ ? parentToChild
+ : childToParent
+ : parentToChild || childToParent;
+ if (!authorized) {
+ this.sendError(
+ sourceSocket,
+ "FORBIDDEN",
+ "Signal target is not authorized by the media assignment",
+ );
+ return;
+ }
+
+ if (description?.type === "offer") {
+ this.connectionIdsByViewer.set(
+ viewerConnectionKey(source.roomId, targetPeerId),
+ message.payload.connectionId,
+ );
+ }
+ this.sendToSession(target.sessionId, {
+ type: "signal",
+ fromPeerId: source.peerId,
+ payload: message.payload,
+ });
+ }
+
+ private routePeerAssistedRestart(
+ sourceSocket: WebSocket,
+ source: AuthenticatedSession,
+ message: Extract<ClientMessage, { type: "restart-request" }>,
+ ): void {
+ const targetPeerId = message.targetPeerId;
+ if (
+ !targetPeerId ||
+ !this.peerRelayTopology.isParentOf(
+ source.roomId,
+ targetPeerId,
+ source.peerId,
+ )
+ ) {
+ this.sendError(
+ sourceSocket,
+ "FORBIDDEN",
+ "Restart target is not the assigned media parent",
+ );
+ return;
+ }
+ const parent = this.connectedPeer(source.roomId, targetPeerId);
+ if (!parent) {
+ this.sendError(sourceSocket, "PEER_NOT_FOUND", "Media parent is not connected");
+ return;
+ }
+ this.sendToSession(parent.sessionId, {
+ type: "restart-request",
+ fromPeerId: source.peerId,
+ connectionId: message.connectionId,
+ rebuild: message.rebuild,
+ });
+ }
+
private routeToHost(
sourceSocket: WebSocket,
source: AuthenticatedSession,
@@ -509,6 +684,22 @@ export class SignalingServer {
this.connectionIdsByViewer.delete(
viewerConnectionKey(disconnected.roomId, disconnected.peerId),
);
+ if (this.options.peerAssistedMedia) {
+ const assignmentChanges = this.peerRelayTopology.removeViewer(
+ disconnected.roomId,
+ disconnected.peerId,
+ this.connectedPeerIds(disconnected.roomId),
+ );
+ this.clearChangedConnectionIds(
+ disconnected.roomId,
+ assignmentChanges,
+ );
+ this.sendMediaAssignmentChanges(
+ disconnected.roomId,
+ assignmentChanges,
+ );
+ return;
+ }
const host = this.options.roomStore.getConnectedHost(disconnected.roomId);
if (host) {
this.sendToSession(host.sessionId, {
@@ -537,6 +728,7 @@ export class SignalingServer {
}
this.clearRoomGraceTimers(roomId);
this.clearRoomConnectionIds(roomId);
+ this.peerRelayTopology.deleteRoom(roomId);
for (const sessionId of abandoned.sessionIds) {
const socket = this.socketsBySessionId.get(sessionId);
if (!socket) {
@@ -551,6 +743,7 @@ 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);
for (const sessionId of expired.sessionIds) {
const socket = this.socketsBySessionId.get(sessionId);
if (!socket) {
@@ -621,6 +814,87 @@ 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) {
+ return host;
+ }
+ 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 a989670a..6ef862d3 100644
--- a/src/shared/protocol.ts
+++ b/src/shared/protocol.ts
@@ -79,6 +79,14 @@ export const signalPayloadSchema = z.discriminatedUnion("kind", [
]);
export type SignalPayload = z.infer<typeof signalPayloadSchema>;
+export const mediaAssignmentSchema = z
+ .object({
+ parentPeerId: opaqueIdSchema.nullable(),
+ childPeerIds: z.array(opaqueIdSchema).max(2),
+ })
+ .strict();
+export type MediaAssignment = z.infer<typeof mediaAssignmentSchema>;
+
const authenticateMessageSchema = z.discriminatedUnion("role", [
z
.object({
@@ -111,6 +119,7 @@ export const clientMessageSchema = z.union([
z
.object({
type: z.literal("restart-request"),
+ targetPeerId: opaqueIdSchema.optional(),
connectionId: opaqueIdSchema,
rebuild: z.boolean(),
})
@@ -135,20 +144,31 @@ const errorCodeSchema = z.enum([
"SERVER_ERROR",
]);
-export const serverMessageSchema = z.discriminatedUnion("type", [
+const authenticatedMessageShape = {
+ type: z.literal("authenticated"),
+ role: roleSchema,
+ peerId: opaqueIdSchema,
+ roomExpiresAt: z.string().datetime().nullable(),
+ maxViewers: z.number().int().min(1).max(MAX_VIEWERS_PER_ROOM_LIMIT),
+ hostOnline: z.boolean(),
+ connectionId: opaqueIdSchema.nullable(),
+ viewerPeerIds: z.array(opaqueIdSchema).max(MAX_VIEWERS_PER_ROOM_LIMIT),
+ iceConfig: iceConfigSchema,
+};
+
+const authenticatedMessageSchema = z.union([
+ z.object(authenticatedMessageShape).strict(),
z
.object({
- type: z.literal("authenticated"),
- role: roleSchema,
- peerId: opaqueIdSchema,
- roomExpiresAt: z.string().datetime().nullable(),
- maxViewers: z.number().int().min(1).max(MAX_VIEWERS_PER_ROOM_LIMIT),
- hostOnline: z.boolean(),
- connectionId: opaqueIdSchema.nullable(),
- viewerPeerIds: z.array(opaqueIdSchema).max(MAX_VIEWERS_PER_ROOM_LIMIT),
- iceConfig: iceConfigSchema,
+ ...authenticatedMessageShape,
+ mediaMode: z.literal("peer-assisted"),
+ mediaAssignment: mediaAssignmentSchema,
})
.strict(),
+]);
+
+export const serverMessageSchema = z.union([
+ authenticatedMessageSchema,
z
.object({
type: z.literal("peer-joined"),
@@ -176,6 +196,12 @@ export const serverMessageSchema = z.discriminatedUnion("type", [
rebuild: z.boolean(),
})
.strict(),
+ z
+ .object({
+ type: z.literal("media-assignment"),
+ mediaAssignment: mediaAssignmentSchema,
+ })
+ .strict(),
z
.object({
type: z.literal("ice-config"),
diff --git a/tests/host-peer-tracks.test.ts b/tests/host-peer-tracks.test.ts
index b0432a02..50e640e0 100644
--- a/tests/host-peer-tracks.test.ts
+++ b/tests/host-peer-tracks.test.ts
@@ -2,6 +2,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { QUALITY_PROFILES } from "../src/client/media/quality.ts";
import { HostPeer } from "../src/client/webrtc/host-peer.ts";
+import { ViewerRelay } from "../src/client/webrtc/viewer-relay.ts";
+
+const statsCallbacks: Array<() => void> = [];
class FakeSender {
failNextReplace = false;
@@ -23,6 +26,7 @@ class FakeSender {
class FakePeerConnection {
static latest: FakePeerConnection | null = null;
+ static offersFailing = 0;
readonly senders: FakeSender[] = [];
readonly transceiverInputs: Array<{
@@ -34,6 +38,7 @@ class FakePeerConnection {
signalingState: RTCSignalingState = "stable";
localDescription: RTCSessionDescription | null = null;
remoteDescription: RTCSessionDescription | null = null;
+ readonly statsReports: Array<RTCStatsReport | Promise<RTCStatsReport>> = [];
constructor() {
FakePeerConnection.latest = this;
@@ -54,6 +59,10 @@ class FakePeerConnection {
addEventListener(): void {}
async createOffer(): Promise<RTCSessionDescriptionInit> {
+ if (FakePeerConnection.offersFailing > 0) {
+ FakePeerConnection.offersFailing -= 1;
+ throw new Error("createOffer failed");
+ }
return { type: "offer", sdp: "test-offer" };
}
@@ -63,11 +72,104 @@ class FakePeerConnection {
this.localDescription = description as RTCSessionDescription;
}
+ async getStats(): Promise<RTCStatsReport> {
+ return await (this.statsReports.shift() ?? emptyStatsReport());
+ }
+
close(): void {
this.connectionState = "closed";
}
}
+function emptyStatsReport(): RTCStatsReport {
+ return new Map() as unknown as RTCStatsReport;
+}
+
+function sendStatsReport({
+ bytesSent,
+ framesEncoded,
+ timestamp,
+ qualityLimitationReason,
+}: {
+ bytesSent: number;
+ framesEncoded: number;
+ timestamp: number;
+ qualityLimitationReason: string;
+}): RTCStatsReport {
+ return new Map<string, Record<string, unknown>>([
+ [
+ "transport",
+ {
+ id: "transport",
+ type: "transport",
+ timestamp,
+ selectedCandidatePairId: "pair",
+ },
+ ],
+ [
+ "pair",
+ {
+ id: "pair",
+ type: "candidate-pair",
+ timestamp,
+ state: "succeeded",
+ nominated: true,
+ localCandidateId: "local",
+ remoteCandidateId: "remote",
+ currentRoundTripTime: 0.02,
+ availableOutgoingBitrate: 6_000_000,
+ },
+ ],
+ [
+ "local",
+ {
+ id: "local",
+ type: "local-candidate",
+ timestamp,
+ candidateType: "host",
+ protocol: "udp",
+ },
+ ],
+ [
+ "remote",
+ {
+ id: "remote",
+ type: "remote-candidate",
+ timestamp,
+ candidateType: "host",
+ protocol: "udp",
+ },
+ ],
+ [
+ "outbound-video",
+ {
+ id: "outbound-video",
+ type: "outbound-rtp",
+ timestamp,
+ kind: "video",
+ bytesSent,
+ framesEncoded,
+ framesPerSecond: 30,
+ frameWidth: 1280,
+ frameHeight: 720,
+ totalEncodeTime: framesEncoded * 0.005,
+ qualityLimitationReason,
+ encoderImplementation: "test-encoder",
+ codecId: "codec",
+ },
+ ],
+ [
+ "codec",
+ {
+ id: "codec",
+ type: "codec",
+ timestamp,
+ mimeType: "video/VP8",
+ },
+ ],
+ ]) as unknown as RTCStatsReport;
+}
+
function createTrack(kind: "video" | "audio", id: string): MediaStreamTrack {
return { id, kind } as MediaStreamTrack;
}
@@ -99,10 +201,19 @@ function createPeer(stream: MediaStream): HostPeer {
beforeEach(() => {
FakePeerConnection.latest = null;
+ FakePeerConnection.offersFailing = 0;
+ statsCallbacks.length = 0;
vi.stubGlobal("RTCPeerConnection", FakePeerConnection);
vi.stubGlobal("window", {
- setInterval: vi.fn(() => 1),
+ setInterval: vi.fn((callback: () => void) => {
+ statsCallbacks.push(callback);
+ return statsCallbacks.length;
+ }),
clearInterval: vi.fn(),
+ setTimeout: (callback: () => void, delay: number) =>
+ globalThis.setTimeout(callback, delay),
+ clearTimeout: (timer: ReturnType<typeof setTimeout>) =>
+ globalThis.clearTimeout(timer),
});
});
@@ -135,6 +246,7 @@ describe("HostPeer source replacement", () => {
expect(connection.senders[0]?.track).toBe(nextVideo);
expect(connection.senders[1]?.track).toBe(nextAudio);
+ expect(connection.transceiverInputs).toHaveLength(2);
expect(connection.senders[0]?.setParameters).toHaveBeenCalledTimes(2);
});
@@ -205,3 +317,261 @@ describe("HostPeer source replacement", () => {
expect(audioSender.track).toBe(oldAudio);
});
});
+
+describe("ViewerRelay downstream ownership", () => {
+ it("exposes a defensive snapshot of current downstream send metrics", async () => {
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["720p30"],
+ { sendSignal: () => true },
+ );
+ relay.setChild("metrics-child");
+ relay.setStream(
+ createStream(createTrack("video", "metrics-video"), null),
+ );
+
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.peerId).toBe("metrics-child"),
+ );
+ const connection = FakePeerConnection.latest!;
+ connection.statsReports.push(
+ sendStatsReport({
+ bytesSent: 1_000_000,
+ framesEncoded: 30,
+ timestamp: 1_000,
+ qualityLimitationReason: "cpu",
+ }),
+ sendStatsReport({
+ bytesSent: 1_500_000,
+ framesEncoded: 60,
+ timestamp: 2_000,
+ qualityLimitationReason: "bandwidth",
+ }),
+ );
+
+ statsCallbacks[0]!();
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.metrics.averageEncodeMs).toBe(5),
+ );
+ statsCallbacks[0]!();
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.metrics.bitrateKbps).toBe(4_000),
+ );
+
+ const snapshot = relay.getSnapshot()!;
+ expect(snapshot.metrics).toMatchObject({
+ averageEncodeMs: 5,
+ bitrateKbps: 4_000,
+ encoderImplementation: "test-encoder",
+ qualityLimitationReason: "bandwidth",
+ });
+ snapshot.metrics.qualityLimitationReason = "mutated";
+ expect(relay.getSnapshot()?.metrics.qualityLimitationReason).toBe(
+ "bandwidth",
+ );
+ });
+
+ it("clears snapshots across child replacement, stop, and dispose", async () => {
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["720p30"],
+ { sendSignal: () => true },
+ );
+ const stream = createStream(createTrack("video", "relay-video"), null);
+ relay.setChild("first-child");
+ relay.setStream(stream);
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.peerId).toBe("first-child"),
+ );
+
+ relay.setChild("second-child");
+ expect(relay.getSnapshot()).toBeNull();
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.peerId).toBe("second-child"),
+ );
+
+ relay.stop();
+ expect(relay.getSnapshot()).toBeNull();
+ relay.setStream(stream);
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.peerId).toBe("second-child"),
+ );
+
+ relay.dispose();
+ expect(relay.getSnapshot()).toBeNull();
+ relay.setStream(stream);
+ expect(relay.getSnapshot()).toBeNull();
+ });
+
+ it("does not publish a stale stats result after replacing its child", async () => {
+ let resolveOldStats!: (report: RTCStatsReport) => void;
+ const pendingOldStats = new Promise<RTCStatsReport>((resolve) => {
+ resolveOldStats = resolve;
+ });
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["720p30"],
+ { sendSignal: () => true },
+ );
+ relay.setChild("old-child");
+ relay.setStream(
+ createStream(createTrack("video", "relay-video"), null),
+ );
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.peerId).toBe("old-child"),
+ );
+ FakePeerConnection.latest!.statsReports.push(pendingOldStats);
+ statsCallbacks[0]!();
+
+ relay.setChild("current-child");
+ await vi.waitFor(() =>
+ expect(relay.getSnapshot()?.peerId).toBe("current-child"),
+ );
+ resolveOldStats(
+ sendStatsReport({
+ bytesSent: 999_999,
+ framesEncoded: 30,
+ timestamp: 1_000,
+ qualityLimitationReason: "old-peer",
+ }),
+ );
+ await Promise.resolve();
+ await Promise.resolve();
+
+ expect(relay.getSnapshot()).toMatchObject({
+ peerId: "current-child",
+ metrics: { qualityLimitationReason: null },
+ });
+ });
+
+ it("creates a downstream peer without secure-context randomUUID", async () => {
+ vi.stubGlobal("crypto", {
+ getRandomValues: (bytes: Uint8Array) => {
+ bytes.fill(7);
+ return bytes;
+ },
+ });
+ const targets: string[] = [];
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["720p30"],
+ {
+ sendSignal: (peerId) => {
+ targets.push(peerId);
+ return true;
+ },
+ },
+ );
+
+ relay.setChild("lan-child-peer");
+ relay.setStream(
+ createStream(createTrack("video", "lan-video"), null),
+ );
+
+ await vi.waitFor(() => expect(targets).toEqual(["lan-child-peer"]));
+ expect(FakePeerConnection.latest?.connectionState).toBe("new");
+ });
+
+ it("retries a missing peer when the same assignment is reconciled", async () => {
+ vi.useFakeTimers();
+ try {
+ FakePeerConnection.offersFailing = 2;
+ const targets: string[] = [];
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["720p30"],
+ {
+ sendSignal: (peerId) => {
+ targets.push(peerId);
+ return true;
+ },
+ },
+ );
+ const stream = createStream(createTrack("video", "relay-video"), null);
+ relay.setChild("same-child-peer");
+ relay.setStream(stream);
+
+ await vi.runAllTimersAsync();
+ const failedPeer = FakePeerConnection.latest;
+ expect(targets).toEqual([]);
+
+ relay.setChild("same-child-peer");
+ await vi.runAllTimersAsync();
+
+ expect(FakePeerConnection.latest).not.toBe(failedPeer);
+ expect(targets).toEqual(["same-child-peer"]);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("rebuilds a stalled peer but preserves a connected peer on reconciliation", async () => {
+ const targets: string[] = [];
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["720p30"],
+ {
+ sendSignal: (peerId) => {
+ targets.push(peerId);
+ return true;
+ },
+ },
+ );
+ relay.setChild("reconciled-child");
+ relay.setStream(
+ createStream(createTrack("video", "reconciled-video"), null),
+ );
+ await vi.waitFor(() => expect(targets).toEqual(["reconciled-child"]));
+ const stalledConnection = FakePeerConnection.latest!;
+
+ relay.setChild("reconciled-child");
+ await vi.waitFor(() =>
+ expect(FakePeerConnection.latest).not.toBe(stalledConnection),
+ );
+ const connectedConnection = FakePeerConnection.latest!;
+ await vi.waitFor(() => expect(targets).toHaveLength(2));
+ connectedConnection.connectionState = "connected";
+
+ relay.setChild("reconciled-child");
+ expect(FakePeerConnection.latest).toBe(connectedConnection);
+ expect(targets).toHaveLength(2);
+ });
+
+ it("keeps one downstream connection across upstream stream replacement", async () => {
+ const targets: string[] = [];
+ const relay = new ViewerRelay(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ QUALITY_PROFILES["1080p60"],
+ {
+ sendSignal: (peerId) => {
+ targets.push(peerId);
+ return true;
+ },
+ },
+ );
+ const firstStream = createStream(
+ createTrack("video", "first-video"),
+ createTrack("audio", "first-audio"),
+ );
+
+ relay.setChild("child-peer-one");
+ relay.setStream(firstStream);
+ await vi.waitFor(() => expect(FakePeerConnection.latest).not.toBeNull());
+ const connection = FakePeerConnection.latest!;
+ await vi.waitFor(() => expect(targets).toEqual(["child-peer-one"]));
+
+ const nextVideo = createTrack("video", "next-video");
+ const nextAudio = createTrack("audio", "next-audio");
+ relay.setStream(createStream(nextVideo, nextAudio));
+ await vi.waitFor(() => expect(connection.senders[0]?.track).toBe(nextVideo));
+
+ expect(FakePeerConnection.latest).toBe(connection);
+ expect(connection.senders[1]?.track).toBe(nextAudio);
+ expect(connection.transceiverInputs).toHaveLength(2);
+
+ relay.setChild("child-peer-two");
+ await vi.waitFor(() => expect(FakePeerConnection.latest).not.toBe(connection));
+ expect(connection.connectionState).toBe("closed");
+ await vi.waitFor(() => expect(targets.at(-1)).toBe("child-peer-two"));
+ });
+});
diff --git a/tests/media-assignment.test.ts b/tests/media-assignment.test.ts
new file mode 100644
index 00000000..acba0a39
--- /dev/null
+++ b/tests/media-assignment.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+
+import type { SignalPayload } from "../src/shared/protocol.ts";
+import {
+ limitMediaAssignment,
+ MAX_HOST_MEDIA_CHILDREN,
+ MAX_VIEWER_MEDIA_CHILDREN,
+ viewerRestartMessage,
+ viewerSignalMessage,
+} from "../src/client/webrtc/media-assignment.ts";
+
+const offer: SignalPayload = {
+ kind: "description",
+ connectionId: "connection_12345678",
+ description: { type: "offer", sdp: "test-offer" },
+};
+
+describe("peer-assisted client assignment", () => {
+ it("keeps host and viewer child counts within their client limits", () => {
+ const assignment = {
+ parentPeerId: "parent_12345678",
+ childPeerIds: [
+ "child_12345678",
+ "child_abcdefgh",
+ "child_12345678",
+ ],
+ };
+
+ expect(
+ limitMediaAssignment(assignment, MAX_HOST_MEDIA_CHILDREN),
+ ).toEqual({
+ parentPeerId: "parent_12345678",
+ childPeerIds: ["child_12345678", "child_abcdefgh"],
+ });
+ expect(
+ limitMediaAssignment(assignment, MAX_VIEWER_MEDIA_CHILDREN),
+ ).toEqual({
+ parentPeerId: "parent_12345678",
+ childPeerIds: ["child_12345678"],
+ });
+ });
+
+ it("leaves legacy viewer signaling untargeted", () => {
+ expect(viewerSignalMessage(false, "host_12345678", offer)).toEqual({
+ type: "signal",
+ payload: offer,
+ });
+ expect(
+ viewerRestartMessage(
+ false,
+ "host_12345678",
+ "connection_12345678",
+ true,
+ ),
+ ).toEqual({
+ type: "restart-request",
+ connectionId: "connection_12345678",
+ rebuild: true,
+ });
+ });
+
+ it("targets peer-assisted signaling at the assigned parent", () => {
+ expect(viewerSignalMessage(true, "parent_12345678", offer)).toEqual({
+ type: "signal",
+ targetPeerId: "parent_12345678",
+ payload: offer,
+ });
+ expect(
+ viewerRestartMessage(
+ true,
+ "parent_12345678",
+ "connection_12345678",
+ false,
+ ),
+ ).toEqual({
+ type: "restart-request",
+ targetPeerId: "parent_12345678",
+ connectionId: "connection_12345678",
+ rebuild: false,
+ });
+ });
+});
diff --git a/tests/peer-relay-topology.test.ts b/tests/peer-relay-topology.test.ts
new file mode 100644
index 00000000..5d5c7a9a
--- /dev/null
+++ b/tests/peer-relay-topology.test.ts
@@ -0,0 +1,313 @@
+import { describe, expect, it } from "vitest";
+
+import { PeerRelayTopology } from "../src/server/peer-relay-topology.ts";
+
+function connected(...peerIds: string[]): Set<string> {
+ return new Set(peerIds);
+}
+
+function expectValidTree(
+ topology: PeerRelayTopology,
+ roomId: string,
+ hostPeerId: string,
+ viewerPeerIds: readonly string[],
+): number {
+ const hostAssignment = topology.getAssignment(roomId, hostPeerId)!;
+ expect(hostAssignment.parentPeerId).toBeNull();
+ expect(hostAssignment.childPeerIds.length).toBeLessThanOrEqual(2);
+
+ const allChildren = new Set(hostAssignment.childPeerIds);
+ let maximumDepth = 0;
+ for (const peerId of viewerPeerIds) {
+ const assignment = topology.getAssignment(roomId, peerId)!;
+ expect(assignment.childPeerIds.length).toBeLessThanOrEqual(1);
+ for (const childPeerId of assignment.childPeerIds) {
+ expect(allChildren.has(childPeerId)).toBe(false);
+ allChildren.add(childPeerId);
+ }
+
+ let parentPeerId = assignment.parentPeerId;
+ const ancestors = new Set([peerId]);
+ let depth = 0;
+ while (parentPeerId) {
+ expect(ancestors.has(parentPeerId)).toBe(false);
+ ancestors.add(parentPeerId);
+ depth += 1;
+ parentPeerId = topology.getAssignment(roomId, parentPeerId)?.parentPeerId ?? null;
+ }
+ maximumDepth = Math.max(maximumDepth, depth);
+ }
+ expect(allChildren).toEqual(new Set(viewerPeerIds));
+ return maximumDepth;
+}
+
+describe("PeerRelayTopology", () => {
+ it("fills the shallowest stable slots with bounded fanout", () => {
+ const topology = new PeerRelayTopology();
+ const roomId = "room";
+ const host = "host";
+ topology.setHost(roomId, host, connected(host));
+
+ const viewers = ["viewer-a", "viewer-b", "viewer-c", "viewer-d", "viewer-e"];
+ for (const viewer of viewers) {
+ topology.addViewer(roomId, viewer, connected(host, ...viewers));
+ }
+
+ expect(topology.getAssignment(roomId, host)).toEqual({
+ parentPeerId: null,
+ childPeerIds: ["viewer-a", "viewer-b"],
+ });
+ expect(topology.getAssignment(roomId, "viewer-a")).toEqual({
+ parentPeerId: host,
+ childPeerIds: ["viewer-c"],
+ });
+ expect(topology.getAssignment(roomId, "viewer-b")).toEqual({
+ parentPeerId: host,
+ childPeerIds: ["viewer-d"],
+ });
+ expect(topology.getAssignment(roomId, "viewer-c")).toEqual({
+ parentPeerId: "viewer-a",
+ childPeerIds: ["viewer-e"],
+ });
+ });
+
+ it("forms two bounded acyclic chains for eight viewers", () => {
+ const topology = new PeerRelayTopology();
+ const roomId = "room";
+ const hostPeerId = "host";
+ const viewerPeerIds = Array.from(
+ { length: 8 },
+ (_, index) => `viewer-${index + 1}`,
+ );
+ topology.setHost(roomId, hostPeerId, connected(hostPeerId));
+ for (const peerId of viewerPeerIds) {
+ topology.addViewer(
+ roomId,
+ peerId,
+ connected(hostPeerId, ...viewerPeerIds),
+ );
+ }
+
+ expect(expectValidTree(topology, roomId, hostPeerId, viewerPeerIds)).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(
+ roomId,
+ "viewer-b",
+ connected("host", "viewer-a", "viewer-b"),
+ );
+ topology.addViewer(
+ roomId,
+ "viewer-c",
+ connected("host", "viewer-a", "viewer-b", "viewer-c"),
+ );
+
+ topology.addViewer(
+ roomId,
+ "viewer-d",
+ connected("host", "viewer-b", "viewer-c", "viewer-d"),
+ );
+
+ expect(topology.getAssignment(roomId, "viewer-c")?.parentPeerId).toBe(
+ "viewer-a",
+ );
+ expect(topology.getAssignment(roomId, "viewer-d")?.parentPeerId).toBe(
+ "viewer-b",
+ );
+ });
+
+ it("reattaches only the removed viewer's direct child subtree entry", () => {
+ const topology = new PeerRelayTopology();
+ const roomId = "room";
+ topology.setHost(roomId, "host", connected("host"));
+ topology.addViewer(roomId, "viewer-a", connected("host", "viewer-a"));
+ topology.addViewer(
+ roomId,
+ "viewer-b",
+ connected("host", "viewer-a", "viewer-b"),
+ );
+ topology.addViewer(
+ roomId,
+ "viewer-c",
+ connected("host", "viewer-a", "viewer-b", "viewer-c"),
+ );
+ topology.addViewer(
+ roomId,
+ "viewer-d",
+ connected("host", "viewer-a", "viewer-b", "viewer-c", "viewer-d"),
+ );
+ topology.addViewer(
+ roomId,
+ "viewer-e",
+ connected(
+ "host",
+ "viewer-a",
+ "viewer-b",
+ "viewer-c",
+ "viewer-d",
+ "viewer-e",
+ ),
+ );
+
+ const changes = topology.removeViewer(
+ roomId,
+ "viewer-a",
+ connected("host", "viewer-b", "viewer-c", "viewer-d", "viewer-e"),
+ );
+
+ expect(topology.getAssignment(roomId, "host")?.childPeerIds).toEqual([
+ "viewer-b",
+ "viewer-c",
+ ]);
+ expect(topology.getAssignment(roomId, "viewer-c")?.parentPeerId).toBe(
+ "host",
+ );
+ expect(topology.getAssignment(roomId, "viewer-e")?.parentPeerId).toBe(
+ "viewer-c",
+ );
+ expect(changes.map((change) => change.peerId).sort()).toEqual([
+ "host",
+ "viewer-c",
+ ]);
+ });
+
+ it("waits to reattach an offline subtree root until it reconnects", () => {
+ const topology = new PeerRelayTopology();
+ const roomId = "room";
+ topology.setHost(roomId, "host", connected("host"));
+ topology.addViewer(roomId, "viewer-a", connected("host", "viewer-a"));
+ topology.addViewer(
+ roomId,
+ "viewer-b",
+ connected("host", "viewer-a", "viewer-b"),
+ );
+ topology.addViewer(
+ roomId,
+ "viewer-c",
+ connected("host", "viewer-a", "viewer-b", "viewer-c"),
+ );
+
+ topology.removeViewer(
+ roomId,
+ "viewer-a",
+ connected("host", "viewer-b"),
+ );
+
+ expect(topology.getAssignment(roomId, "viewer-c")?.parentPeerId).toBeNull();
+ expect(topology.getAssignment(roomId, "host")?.childPeerIds).toEqual([
+ "viewer-b",
+ ]);
+
+ const reconnectChanges = topology.addViewer(
+ roomId,
+ "viewer-c",
+ connected("host", "viewer-b", "viewer-c"),
+ );
+
+ expect(topology.getAssignment(roomId, "viewer-c")?.parentPeerId).toBe(
+ "host",
+ );
+ expect(reconnectChanges.map((change) => change.peerId).sort()).toEqual([
+ "host",
+ "viewer-c",
+ ]);
+ });
+
+ it("assigns connected pending viewers when removals make slots reachable", () => {
+ const topology = new PeerRelayTopology();
+ const roomId = "room";
+ topology.setHost(roomId, "host", connected("host"));
+ for (const peerId of ["a", "b", "c", "d"]) {
+ topology.addViewer(
+ roomId,
+ peerId,
+ connected("host", "a", "b", "c", "d"),
+ );
+ }
+
+ topology.addViewer(roomId, "e", connected("host", "c", "d", "e"));
+ expect(topology.getAssignment(roomId, "e")?.parentPeerId).toBeNull();
+
+ topology.removeViewer(roomId, "a", connected("host", "c", "d", "e"));
+ topology.removeViewer(roomId, "b", connected("host", "c", "d", "e"));
+
+ expect(topology.getAssignment(roomId, "e")?.parentPeerId).toBe("c");
+ expect(topology.getAssignment(roomId, "c")?.childPeerIds).toEqual(["e"]);
+ });
+
+ it("keeps pending viewers unassigned until a host arrives", () => {
+ const topology = new PeerRelayTopology();
+ topology.addViewer("room", "viewer-a", connected("viewer-a"));
+ expect(topology.getAssignment("room", "viewer-a")?.parentPeerId).toBeNull();
+
+ topology.setHost(
+ "room",
+ "host",
+ connected("host", "viewer-a"),
+ );
+ expect(topology.getAssignment("room", "viewer-a")?.parentPeerId).toBe(
+ "host",
+ );
+ });
+
+ 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(
+ "room",
+ "viewer-a",
+ connected("host-a", "viewer-a"),
+ );
+ topology.addViewer(
+ "room",
+ "viewer-b",
+ connected("host-a", "viewer-a", "viewer-b"),
+ );
+ topology.addViewer(
+ "room",
+ "viewer-c",
+ connected("host-a", "viewer-a", "viewer-b", "viewer-c"),
+ );
+
+ topology.setHost(
+ "room",
+ "host-b",
+ connected("host-b", "viewer-a", "viewer-b", "viewer-c"),
+ );
+
+ expect(topology.getAssignment("room", "viewer-a")?.parentPeerId).toBe(
+ "host-b",
+ );
+ expect(topology.getAssignment("room", "viewer-b")?.parentPeerId).toBe(
+ "host-b",
+ );
+ expect(topology.getAssignment("room", "viewer-c")?.parentPeerId).toBe(
+ "viewer-a",
+ );
+ });
+
+ it("drops all assignments when a room is deleted", () => {
+ const topology = new PeerRelayTopology();
+ topology.setHost("room", "host-a", connected("host-a"));
+ topology.addViewer(
+ "room",
+ "viewer-a",
+ connected("host-a", "viewer-a"),
+ );
+
+ topology.deleteRoom("room");
+ expect(topology.getAssignment("room", "host-a")).toBeUndefined();
+ expect(topology.getAssignment("room", "viewer-a")).toBeUndefined();
+
+ topology.setHost("room", "host-b", connected("host-b"));
+ expect(topology.getAssignment("room", "host-b")).toEqual({
+ parentPeerId: null,
+ childPeerIds: [],
+ });
+ });
+});
diff --git a/tests/protocol.test.ts b/tests/protocol.test.ts
index 22324d59..f91c1e8e 100644
--- a/tests/protocol.test.ts
+++ b/tests/protocol.test.ts
@@ -107,6 +107,12 @@ describe("client signaling protocol", () => {
};
expect(clientMessageSchema.safeParse(restartRequest).success).toBe(true);
+ expect(
+ clientMessageSchema.safeParse({
+ ...restartRequest,
+ targetPeerId: "parent_12345678",
+ }).success,
+ ).toBe(true);
expect(
clientMessageSchema.safeParse({
type: restartRequest.type,
@@ -173,6 +179,44 @@ describe("server signaling protocol", () => {
).toBe(true);
});
+ it("requires a complete bounded peer-assisted assignment", () => {
+ const peerAssisted = {
+ ...authenticatedMessage(8),
+ mediaMode: "peer-assisted",
+ mediaAssignment: {
+ parentPeerId: null,
+ childPeerIds: ["viewer_12345678", "viewer_87654321"],
+ },
+ };
+
+ expect(serverMessageSchema.safeParse(peerAssisted).success).toBe(true);
+ expect(
+ serverMessageSchema.safeParse({
+ type: "media-assignment",
+ mediaAssignment: peerAssisted.mediaAssignment,
+ }).success,
+ ).toBe(true);
+ expect(
+ serverMessageSchema.safeParse({
+ ...authenticatedMessage(8),
+ mediaMode: "peer-assisted",
+ }).success,
+ ).toBe(false);
+ expect(
+ serverMessageSchema.safeParse({
+ ...peerAssisted,
+ mediaAssignment: {
+ parentPeerId: null,
+ childPeerIds: [
+ "viewer_12345678",
+ "viewer_87654321",
+ "viewer_overflow",
+ ],
+ },
+ }).success,
+ ).toBe(false);
+ });
+
it.each([0, 1.5, MAX_VIEWERS_PER_ROOM_LIMIT + 1])(
"rejects viewer limit %s outside the protocol boundary",
(maxViewers) => {
diff --git a/tests/server-config.test.ts b/tests/server-config.test.ts
index 44cb397e..81205eee 100644
--- a/tests/server-config.test.ts
+++ b/tests/server-config.test.ts
@@ -14,6 +14,27 @@ describe("server configuration", () => {
expect(config.allowedOrigins).toEqual(new Set(["http://localhost:9123"]));
expect(config.turnUrls).toEqual([]);
expect(config.maxViewersPerRoom).toBe(8);
+ expect(config.peerAssistedMedia).toBe(false);
+ });
+
+ it("requires an explicit boolean to enable peer-assisted media", () => {
+ expect(loadConfig({ PEER_ASSISTED_MEDIA: "true" }).peerAssistedMedia).toBe(
+ true,
+ );
+ expect(loadConfig({ PEER_ASSISTED_MEDIA: "false" }).peerAssistedMedia).toBe(
+ false,
+ );
+ expect(() => loadConfig({ PEER_ASSISTED_MEDIA: "1" })).toThrow(
+ "PEER_ASSISTED_MEDIA must be true or false",
+ );
+ expect(() =>
+ loadConfig({
+ PEER_ASSISTED_MEDIA: "true",
+ MAX_VIEWERS_PER_ROOM: "9",
+ }),
+ ).toThrow(
+ "PEER_ASSISTED_MEDIA currently supports at most 8 viewers per room",
+ );
});
it("allows an explicit loopback listen host", () => {
diff --git a/tests/server-http.test.ts b/tests/server-http.test.ts
index 8496c631..80636a30 100644
--- a/tests/server-http.test.ts
+++ b/tests/server-http.test.ts
@@ -42,6 +42,7 @@ function testConfig(overrides: Partial<ServerConfig> = {}): ServerConfig {
roomTtlMs: 14_400_000,
maxRooms: 10,
maxViewersPerRoom: 8,
+ peerAssistedMedia: false,
stunUrls: [],
turnUrls: [],
turnCredentialTtlSeconds: 3_600,
diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.ts
index ee889292..6f98c04a 100644
--- a/tests/server-signal.test.ts
+++ b/tests/server-signal.test.ts
@@ -109,6 +109,7 @@ function testConfig(): ServerConfig {
roomTtlMs: 14_400_000,
maxRooms: 10,
maxViewersPerRoom: 8,
+ peerAssistedMedia: false,
stunUrls: [],
turnUrls: [],
turnCredentialTtlSeconds: 3_600,
@@ -124,10 +125,12 @@ async function startHarness(
maxUnauthenticatedSignalConnections?: number;
accessPassword?: string;
persistent?: boolean;
+ peerAssistedMedia?: boolean;
} = {},
): Promise<SignalHarness> {
const config = testConfig();
config.accessPassword = overrides.accessPassword;
+ config.peerAssistedMedia = overrides.peerAssistedMedia ?? false;
const maxViewersPerRoom = overrides.maxViewersPerRoom ?? 8;
config.maxViewersPerRoom = maxViewersPerRoom;
const roomStore = new RoomStore({
@@ -248,6 +251,15 @@ async function authenticate(
return client.inbox.next("authenticated");
}
+function peerAssisted(
+ message: Extract<ServerMessage, { type: "authenticated" }>,
+) {
+ if (!("mediaMode" in message)) {
+ throw new Error("Expected a peer-assisted authenticated message");
+ }
+ return message;
+}
+
async function closeClient(client: TestClient): Promise<void> {
if (client.socket.readyState === WebSocket.CLOSED) {
return;
@@ -290,6 +302,7 @@ describe("WebSocket signaling", () => {
"viewer-client-early",
);
expect(viewerAuth.hostOnline).toBe(false);
+ expect("mediaMode" in viewerAuth).toBe(false);
const host = await openClient(harness.webSocketUrl);
await authenticate(host, harness.room, "host", "host-client-stable");
@@ -389,6 +402,471 @@ describe("WebSocket signaling", () => {
await foreignViewer.inbox.expectNone(30);
});
+ it("assigns a bounded peer relay tree and authorizes only direct media edges", async () => {
+ const harness = await startHarness({ peerAssistedMedia: true });
+ const secondRoom = harness.roomStore.createRoom();
+ const host = await openClient(harness.webSocketUrl);
+ const hostAuth = peerAssisted(
+ await authenticate(host, harness.room, "host", "relay-host"),
+ );
+ expect(hostAuth.mediaAssignment).toEqual({
+ parentPeerId: null,
+ childPeerIds: [],
+ });
+
+ const firstViewer = await openClient(harness.webSocketUrl);
+ const firstAuth = peerAssisted(
+ await authenticate(
+ firstViewer,
+ harness.room,
+ "viewer",
+ "relay-viewer-a",
+ ),
+ );
+ expect(firstAuth.mediaAssignment.parentPeerId).toBe(hostAuth.peerId);
+ expect((await host.inbox.next("media-assignment")).mediaAssignment).toEqual({
+ parentPeerId: null,
+ childPeerIds: [firstAuth.peerId],
+ });
+
+ const secondViewer = await openClient(harness.webSocketUrl);
+ const secondAuth = peerAssisted(
+ await authenticate(
+ secondViewer,
+ harness.room,
+ "viewer",
+ "relay-viewer-b",
+ ),
+ );
+ expect(secondAuth.mediaAssignment.parentPeerId).toBe(hostAuth.peerId);
+ expect((await host.inbox.next("media-assignment")).mediaAssignment).toEqual({
+ parentPeerId: null,
+ childPeerIds: [firstAuth.peerId, secondAuth.peerId],
+ });
+
+ const thirdViewer = await openClient(harness.webSocketUrl);
+ const thirdAuth = peerAssisted(
+ await authenticate(
+ thirdViewer,
+ harness.room,
+ "viewer",
+ "relay-viewer-c",
+ ),
+ );
+ expect(thirdAuth.mediaAssignment.parentPeerId).toBe(firstAuth.peerId);
+ expect(
+ (await firstViewer.inbox.next("media-assignment")).mediaAssignment,
+ ).toEqual({
+ parentPeerId: hostAuth.peerId,
+ childPeerIds: [thirdAuth.peerId],
+ });
+
+ firstViewer.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: thirdAuth.peerId,
+ payload: {
+ kind: "description",
+ connectionId: "relay-connection",
+ description: { type: "offer", sdp: "v=0\r\n" },
+ },
+ }),
+ );
+ expect(await thirdViewer.inbox.next("signal")).toMatchObject({
+ fromPeerId: firstAuth.peerId,
+ payload: { description: { type: "offer" } },
+ });
+
+ thirdViewer.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: firstAuth.peerId,
+ payload: {
+ kind: "description",
+ connectionId: "relay-connection",
+ description: { type: "answer", sdp: "v=0\r\n" },
+ },
+ }),
+ );
+ expect(await firstViewer.inbox.next("signal")).toMatchObject({
+ fromPeerId: thirdAuth.peerId,
+ payload: { description: { type: "answer" } },
+ });
+
+ thirdViewer.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: firstAuth.peerId,
+ payload: {
+ kind: "candidate",
+ connectionId: "relay-connection",
+ candidate: null,
+ },
+ }),
+ );
+ expect(await firstViewer.inbox.next("signal")).toMatchObject({
+ fromPeerId: thirdAuth.peerId,
+ payload: { kind: "candidate" },
+ });
+
+ thirdViewer.socket.send(
+ JSON.stringify({
+ type: "restart-request",
+ targetPeerId: firstAuth.peerId,
+ connectionId: "relay-connection",
+ rebuild: true,
+ }),
+ );
+ expect(await firstViewer.inbox.next("restart-request")).toMatchObject({
+ fromPeerId: thirdAuth.peerId,
+ connectionId: "relay-connection",
+ rebuild: true,
+ });
+
+ thirdViewer.socket.send(
+ JSON.stringify({
+ type: "restart-request",
+ targetPeerId: hostAuth.peerId,
+ connectionId: "relay-connection",
+ rebuild: false,
+ }),
+ );
+ expect((await thirdViewer.inbox.next("error")).code).toBe("FORBIDDEN");
+
+ host.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: thirdAuth.peerId,
+ payload: {
+ kind: "candidate",
+ connectionId: "forbidden-non-edge",
+ candidate: null,
+ },
+ }),
+ );
+ expect((await host.inbox.next("error")).code).toBe("FORBIDDEN");
+
+ thirdViewer.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: firstAuth.peerId,
+ payload: {
+ kind: "description",
+ connectionId: "forbidden-direction",
+ description: { type: "offer", sdp: "v=0\r\n" },
+ },
+ }),
+ );
+ expect((await thirdViewer.inbox.next("error")).code).toBe("FORBIDDEN");
+
+ const foreignViewer = await openClient(harness.webSocketUrl);
+ const foreignAuth = peerAssisted(
+ await authenticate(
+ foreignViewer,
+ secondRoom,
+ "viewer",
+ "relay-foreign-viewer",
+ ),
+ );
+ firstViewer.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: foreignAuth.peerId,
+ payload: {
+ kind: "candidate",
+ connectionId: "cross-room",
+ candidate: null,
+ },
+ }),
+ );
+ expect((await firstViewer.inbox.next("error")).code).toBe("PEER_NOT_FOUND");
+ 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,
+ });
+ 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],
+ });
+
+ 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,
+ ).toEqual({
+ parentPeerId: null,
+ childPeerIds: [firstAuth.peerId, secondAuth.peerId],
+ });
+ await closeClient(reconnectedFirstViewer);
+
+ expect(
+ (await host.inbox.next("media-assignment", 500)).mediaAssignment,
+ ).toEqual({
+ parentPeerId: null,
+ childPeerIds: [secondAuth.peerId, thirdAuth.peerId],
+ });
+ expect(
+ (await thirdViewer.inbox.next("media-assignment", 500)).mediaAssignment,
+ ).toEqual({
+ parentPeerId: hostAuth.peerId,
+ childPeerIds: [fifthAuth.peerId],
+ });
+ await fifthViewer.inbox.expectNone(30);
+ });
+
+ it("reattaches a subtree root that reconnects after its parent expires", 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-offline-host"),
+ );
+ const firstViewer = await openClient(harness.webSocketUrl);
+ const firstAuth = peerAssisted(
+ await authenticate(
+ firstViewer,
+ harness.room,
+ "viewer",
+ "relay-offline-a",
+ ),
+ );
+ await host.inbox.next("media-assignment");
+ const secondViewer = await openClient(harness.webSocketUrl);
+ const secondAuth = peerAssisted(
+ await authenticate(
+ secondViewer,
+ harness.room,
+ "viewer",
+ "relay-offline-b",
+ ),
+ );
+ await host.inbox.next("media-assignment");
+ const subtreeRoot = await openClient(harness.webSocketUrl);
+ const subtreeRootAuth = peerAssisted(
+ await authenticate(
+ subtreeRoot,
+ harness.room,
+ "viewer",
+ "relay-offline-c",
+ ),
+ );
+ expect(subtreeRootAuth.mediaAssignment.parentPeerId).toBe(firstAuth.peerId);
+ await firstViewer.inbox.next("media-assignment");
+
+ await closeClient(firstViewer);
+ await new Promise((resolve) => setTimeout(resolve, 80));
+ await closeClient(subtreeRoot);
+
+ expect(
+ (await host.inbox.next("media-assignment", 500)).mediaAssignment,
+ ).toEqual({
+ parentPeerId: null,
+ childPeerIds: [secondAuth.peerId],
+ });
+
+ const reconnectedSubtreeRoot = await openClient(harness.webSocketUrl);
+ const reconnectedAuth = peerAssisted(
+ await authenticate(
+ reconnectedSubtreeRoot,
+ harness.room,
+ "viewer",
+ "relay-offline-c",
+ ),
+ );
+ expect(reconnectedAuth).toMatchObject({
+ peerId: subtreeRootAuth.peerId,
+ connectionId: null,
+ mediaAssignment: {
+ parentPeerId: hostAuth.peerId,
+ childPeerIds: [],
+ },
+ });
+ expect(
+ (await host.inbox.next("media-assignment", 500)).mediaAssignment,
+ ).toEqual({
+ parentPeerId: null,
+ childPeerIds: [secondAuth.peerId, subtreeRootAuth.peerId],
+ });
+ });
+
+ it("retains peer relay assignments but clears connection generations when sharing stops", async () => {
+ const harness = await startHarness({
+ peerAssistedMedia: true,
+ viewerDisconnectGraceMs: 500,
+ });
+ const host = await openClient(harness.webSocketUrl);
+ const hostAuth = peerAssisted(
+ await authenticate(host, harness.room, "host", "relay-stop-host"),
+ );
+ const viewer = await openClient(harness.webSocketUrl);
+ const viewerAuth = peerAssisted(
+ await authenticate(
+ viewer,
+ harness.room,
+ "viewer",
+ "relay-stop-viewer",
+ ),
+ );
+ await host.inbox.next("media-assignment");
+
+ host.socket.send(
+ JSON.stringify({
+ type: "signal",
+ targetPeerId: viewerAuth.peerId,
+ payload: {
+ kind: "description",
+ connectionId: "connection-before-relay-stop",
+ description: { type: "offer", sdp: "v=0\r\n" },
+ },
+ }),
+ );
+ await viewer.inbox.next("signal");
+
+ const stoppedHostClosed = new Promise<number>((resolve) =>
+ host.socket.once("close", (code) => resolve(code)),
+ );
+ host.socket.send(JSON.stringify({ type: "stop-sharing" }));
+ await viewer.inbox.next("sharing-stopped");
+ expect(await viewer.inbox.next("host-status")).toMatchObject({
+ online: false,
+ });
+ expect(await stoppedHostClosed).toBe(1000);
+
+ await closeClient(viewer);
+ const reconnectedViewer = await openClient(harness.webSocketUrl);
+ const reconnectedViewerAuth = peerAssisted(
+ await authenticate(
+ reconnectedViewer,
+ harness.room,
+ "viewer",
+ "relay-stop-viewer",
+ ),
+ );
+ expect(reconnectedViewerAuth).toMatchObject({
+ peerId: viewerAuth.peerId,
+ connectionId: null,
+ mediaAssignment: {
+ parentPeerId: hostAuth.peerId,
+ childPeerIds: [],
+ },
+ });
+
+ const resumedHost = await openClient(harness.webSocketUrl);
+ const resumedHostAuth = peerAssisted(
+ await authenticate(
+ resumedHost,
+ harness.room,
+ "host",
+ "relay-stop-host",
+ ),
+ );
+ expect(resumedHostAuth).toMatchObject({
+ peerId: hostAuth.peerId,
+ mediaAssignment: {
+ parentPeerId: null,
+ childPeerIds: [viewerAuth.peerId],
+ },
+ });
+ expect(await reconnectedViewer.inbox.next("host-status")).toMatchObject({
+ online: true,
+ });
+ });
+
it("keeps a viewer peer stable when it reconnects inside the grace period", async () => {
const harness = await startHarness({ viewerDisconnectGraceMs: 80 });
const host = await openClient(harness.webSocketUrl);
diff --git a/tests/viewer-peer-generation.test.ts b/tests/viewer-peer-generation.test.ts
index 8ba45b8b..8e3b8b96 100644
--- a/tests/viewer-peer-generation.test.ts
+++ b/tests/viewer-peer-generation.test.ts
@@ -18,6 +18,7 @@ function createDeferred<T>(): Deferred<T> {
}
interface ConnectionPlan {
+ answerError?: Error;
candidateGates?: Promise<void>[];
localDescriptionGate?: Promise<void>;
}
@@ -46,6 +47,7 @@ class FakePeerConnection extends EventTarget {
private readonly candidateGates: Promise<void>[];
private readonly localDescriptionGate: Promise<void> | null;
+ private readonly answerError: Error | null;
readonly addIceCandidate = vi.fn(async (_candidate: RTCIceCandidateInit | null) => {
const gate = this.candidateGates.shift();
@@ -73,6 +75,7 @@ class FakePeerConnection extends EventTarget {
const plan = FakePeerConnection.plans.shift() ?? {};
this.candidateGates = [...(plan.candidateGates ?? [])];
this.localDescriptionGate = plan.localDescriptionGate ?? null;
+ this.answerError = plan.answerError ?? null;
FakePeerConnection.instances.push(this);
}
@@ -83,6 +86,9 @@ class FakePeerConnection extends EventTarget {
}
async createAnswer(): Promise<RTCSessionDescriptionInit> {
+ if (this.answerError) {
+ throw this.answerError;
+ }
return {
type: "answer",
sdp: `answer-${FakePeerConnection.instances.indexOf(this)}`,
@@ -122,11 +128,13 @@ function candidate(connectionId: string, value: string): SignalPayload {
function createPeer(
signals: SignalPayload[],
snapshots: PeerSnapshot[],
+ signalPeers: string[] = [],
): ViewerPeer {
return new ViewerPeer(
{ iceServers: [], expiresAt: null, relayAvailable: false },
{
- sendSignal: (payload) => {
+ sendSignal: (peerId, payload) => {
+ signalPeers.push(peerId);
signals.push(payload);
return true;
},
@@ -165,6 +173,80 @@ afterEach(() => {
});
describe("ViewerPeer connection generations", () => {
+ it("requests one bounded rebuild when answer negotiation fails", async () => {
+ FakePeerConnection.plans.push(
+ { answerError: new Error("first answer failed") },
+ { answerError: new Error("second answer failed") },
+ );
+ const restartRequests: Array<{
+ peerId: string;
+ connectionId: string;
+ rebuild: boolean;
+ }> = [];
+ 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,
+ },
+ );
+
+ await peer.acceptSignal("relay-parent", offer("connection-first"));
+ await peer.acceptSignal("relay-parent", offer("connection-second"));
+
+ expect(restartRequests).toEqual([
+ {
+ peerId: "relay-parent",
+ connectionId: "connection-first",
+ rebuild: true,
+ },
+ ]);
+ });
+
+ it("targets answers and recovery requests at the current parent", async () => {
+ const signals: SignalPayload[] = [];
+ const signalPeers: string[] = [];
+ const restartRequests: Array<{
+ peerId: string;
+ connectionId: string;
+ rebuild: boolean;
+ }> = [];
+ const peer = new ViewerPeer(
+ { iceServers: [], expiresAt: null, relayAvailable: false },
+ {
+ sendSignal: (peerId, payload) => {
+ signalPeers.push(peerId);
+ signals.push(payload);
+ return true;
+ },
+ sendRestartRequest: (peerId, connectionId, rebuild) => {
+ restartRequests.push({ peerId, connectionId, rebuild });
+ return true;
+ },
+ onStream: () => undefined,
+ onUpdate: () => undefined,
+ },
+ );
+
+ await peer.acceptSignal("parent-old", offer("connection-old"));
+ await peer.acceptSignal("parent-new", offer("connection-new"));
+ expect(signalPeers).toEqual(["parent-old", "parent-new"]);
+
+ expect(peer.requestRecovery()).toBe(true);
+ expect(restartRequests).toEqual([
+ {
+ peerId: "parent-new",
+ connectionId: "connection-new",
+ rebuild: false,
+ },
+ ]);
+ });
+
it("does not send an old answer or candidate after replacing the connection", async () => {
const oldLocalDescription = createDeferred<void>();
FakePeerConnection.plans.push({