Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
chore(route): add opt-in route tracing
AAA9537c59d914e
diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex 424197c9..0a6fcc38 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -1,4 +1,5 @@import { randomBytes } from "node:crypto";+import { debuglog } from "node:util";import type {ClientMessage,@@ -34,6 +35,7 @@ type ErrorCode = Extract<ServerMessage, { type: "error" }>["code"];const DEFAULT_ROUTE_OPERATION_TIMEOUT_MS = 20_000;const DEFAULT_SFU_DRAIN_RETRY_MS = 1_000;const DEFAULT_HOST_OFFLINE_CHECK_MS = 5_000;+const routeDebug = debuglog("screener-route");interface RouteResourceBase {released: boolean;@@ -405,11 +407,33 @@ export class HybridMediaRouter {return input.connectionId === edge.connectionId;}+ debugPeerSignal(input: {+ roomId: string;+ sourcePeerId: string;+ targetPeerId: string;+ signalKind: "candidate" | "description";+ descriptionType?: "offer" | "answer";+ authorization: boolean | "probe" | undefined;+ }): void {+ this.debug(input.roomId, "peer-signal", {+ source: this.debugPeer(input.roomId, input.sourcePeerId),+ target: this.debugPeer(input.roomId, input.targetPeerId),+ signalKind: input.signalKind,+ descriptionType: input.descriptionType ?? null,+ authorization:+ input.authorization === undefined ? "assignment" : input.authorization,+ });+ }+setViewerRelayCapacity(participant: AuthenticatedRouteParticipant,downstreamEdges: number,): void {const room = this.room(participant.roomId);+ this.debug(participant.roomId, "relay-capacity-received", {+ participant: this.debugPeer(participant.roomId, participant.peerId),+ downstreamEdges,+ });room.advertisedCapacityByViewer.set(participant.peerId, downstreamEdges);if (room.controller?.setEffectiveCapacity(@@ -428,6 +452,10 @@ export class HybridMediaRouter {message: Extract<ClientMessage, { type: "route-ready" }>,): void {if (participant.role !== "viewer" || message.phase !== "prepare") return;+ this.debug(participant.roomId, "route-ready-received", {+ participant: this.debugPeer(participant.roomId, participant.peerId),+ revision: message.revision,+ });const room = this.rooms.get(participant.roomId);const controller = room?.controller;const operation = controller?.snapshot().operation;@@ -454,6 +482,12 @@ export class HybridMediaRouter {this.now(),(reservation) => this.commitReservation(reservation),);+ this.debug(participant.roomId, "route-ready-settled", {+ participant: this.debugPeer(participant.roomId, participant.peerId),+ revision: message.revision,+ accepted: settled.accepted,+ exhausted: settled.exhausted === true,+ });this.releaseResources(settled.released);if (settled.accepted) {this.resourceWaiters.delete(participant.roomId);@@ -480,6 +514,10 @@ export class HybridMediaRouter {message: Extract<ClientMessage, { type: "route-media-unavailable" }>,): void {if (participant.role !== "viewer") return;+ this.debug(participant.roomId, "sfu-media-unavailable", {+ participant: this.debugPeer(participant.roomId, participant.peerId),+ revision: message.revision,+ });const room = this.rooms.get(participant.roomId);const controller = room?.controller;const snapshot = controller?.snapshot();@@ -508,6 +546,13 @@ export class HybridMediaRouter {participant: AuthenticatedRouteParticipant,message: Extract<ClientMessage, { type: "route-failed" }>,): void {+ this.debug(participant.roomId, "route-failed-received", {+ participant: this.debugPeer(participant.roomId, participant.peerId),+ role: participant.role,+ phase: message.phase,+ revision: message.revision,+ hasConnectionId: Boolean(message.connectionId),+ });const room = this.rooms.get(participant.roomId);const controller = room?.controller;const snapshot = controller?.snapshot();@@ -668,6 +713,7 @@ export class HybridMediaRouter {): void {room.controller = new RoomRouteController<RouteResource>({hostPeerId: host.peerId,+ debugRoomId: roomId,endpointMediaCopyCapacity: this.options.endpointMediaCopyCapacity,operationTimeoutMs:this.options.sfuFallback?.prepareTimeoutMs ?? DEFAULT_ROUTE_OPERATION_TIMEOUT_MS,@@ -758,6 +804,12 @@ export class HybridMediaRouter {(plan.endpointTransition.kind === "bounded-gap" ? 2 : 1),);if (preparation.kind === "denied") {+ this.debug(roomId, "candidate-preparation-denied", {+ child: this.debugPeer(roomId, operation.childPeerId),+ route: this.debugTuple(roomId, plan.tuple),+ rejectionBucket: preparation.rejectionBucket,+ cursor: operation.cursor,+ });if (preparation.rejectionBucket !== "sfu-admission") {this.resourceWaiters.delete(roomId);}@@ -797,6 +849,11 @@ export class HybridMediaRouter {continue;}this.resourceWaiters.delete(roomId);+ this.debug(roomId, "candidate-prepared", {+ child: this.debugPeer(roomId, operation.childPeerId),+ route: this.debugTuple(roomId, plan.tuple),+ cursor: operation.cursor,+ });let currentOperation = controller.snapshot().operation;if (plan.endpointTransition.kind === "bounded-gap") {const beforeGap = controller.snapshot().revision;@@ -831,6 +888,12 @@ export class HybridMediaRouter {publicationConnectionId: preparation.prepared.publicationConnectionId,hostSessionId: preparation.prepared.hostSessionId,});+ this.debug(roomId, "candidate-begin-settled", {+ child: this.debugPeer(roomId, operation.childPeerId),+ route: this.debugTuple(roomId, plan.tuple),+ accepted: begun.accepted,+ exhausted: begun.exhausted === true,+ });this.releaseResources(begun.released);if (!begun.accepted || !begun.operation?.current) {if (begun.exhausted) {@@ -849,6 +912,11 @@ export class HybridMediaRouter {begun.operation,preparation.prepared,);+ this.debug(roomId, "candidate-prepare-sent", {+ child: this.debugPeer(roomId, operation.childPeerId),+ route: this.debugTuple(roomId, plan.tuple),+ revision: begun.operation.current.revision,+ });this.scheduleDeadline(roomId, room, begun.operation);return;}@@ -1201,6 +1269,20 @@ export class HybridMediaRouter {private broadcastActive(roomId: string, room: RoomRuntime): void {const snapshot = room.controller?.snapshot();if (!snapshot) return;+ this.debug(roomId, "active-topology", {+ revision: snapshot.revision,+ paused: snapshot.paused,+ hostPublication: snapshot.hostPublication?.physicalActive === true,+ routes: [...snapshot.upstreamByViewer].map(([childPeerId, edge]) => ({+ child: this.debugPeer(roomId, childPeerId),+ parent:+ edge.kind === "peer"+ ? this.debugPeer(roomId, edge.parentPeerId)+ : "sfu",+ usable: edge.usable,+ physicalActive: edge.physicalActive,+ })),+ });const assignments = this.assignments(roomId, snapshot);const participants = [this.options.roomStore.getConnectedHost(roomId),@@ -1363,11 +1445,25 @@ export class HybridMediaRouter {operation: OperationSnapshot,): void {this.clearDeadline(room);+ this.debug(roomId, "deadline-scheduled", {+ child: this.debugPeer(roomId, operation.childPeerId),+ wakeInMs: Math.max(0, operation.wakeAtMs - this.now()),+ cursor: operation.cursor,+ candidateCount: operation.candidates.length,+ current: operation.current+ ? this.debugTuple(roomId, operation.current.tuple)+ : null,+ });const timer = setTimeout(() => {if (room.deadlineTimer !== timer || !room.controller) return;room.deadlineTimer = undefined;const before = room.controller.snapshot().revision;const expired = room.controller.operationExpired(this.now());+ this.debug(roomId, "deadline-fired", {+ child: this.debugPeer(roomId, operation.childPeerId),+ accepted: expired.accepted,+ exhausted: expired.exhausted === true,+ });this.releaseResources(expired.released);if (room.controller.snapshot().revision !== before) this.broadcastActive(roomId, room);if (expired.exhausted) {@@ -1562,6 +1658,28 @@ export class HybridMediaRouter {}}+ private debugPeer(roomId: string, peerId: string): string {+ if (peerId === this.rooms.get(roomId)?.hostPeerId) return "host";+ const viewerIndex = this.options.roomStore+ .getViewerPeerIds(roomId)+ .indexOf(peerId);+ return viewerIndex >= 0 ? `viewer-${viewerIndex + 1}` : "viewer-unknown";+ }++ private debugTuple(roomId: string, tuple: CandidateTuple): string {+ return tuple.kind === "peer"+ ? `p2p:${this.debugPeer(roomId, tuple.parentPeerId)}`+ : `sfu:${tuple.publication}`;+ }++ private debug(+ roomId: string,+ event: string,+ details: Record<string, unknown>,+ ): void {+ routeDebug("%s", JSON.stringify({ event, roomId, ...details }));+ }+private sendRoomError(roomId: string, code: ErrorCode, message: string): void {const host = this.options.roomStore.getConnectedHost(roomId);if (host) this.options.sendToSession(host.sessionId, { type: "error", code, message });diff --git a/src/server/room-route-controller.ts b/src/server/room-route-controller.tsindex 07a76307..b54d26c5 100644--- a/src/server/room-route-controller.ts+++ b/src/server/room-route-controller.ts@@ -1,3 +1,5 @@+import { debuglog } from "node:util";+import {MAX_MEDIA_ROUTE_REVISION,type RouteDemandReason,@@ -84,11 +86,14 @@ export interface CandidateCursorGuard {export interface ControllerOptions {hostPeerId: string;+ debugRoomId?: string;endpointMediaCopyCapacity: number;operationTimeoutMs: number;sfuEnabled?: boolean;}+const routeDebug = debuglog("screener-route");+interface Participant {peerId: string;role: "host" | "viewer";@@ -204,6 +209,11 @@ export class RoomRouteController<Resource = unknown> {if (!Number.isSafeInteger(options.operationTimeoutMs) || options.operationTimeoutMs <= 0) {throw new Error("Route operation timeout must be a positive integer");}+ this.debug("controller-created", {+ endpointCapacity: options.endpointMediaCopyCapacity,+ operationTimeoutMs: options.operationTimeoutMs,+ sfuEnabled: options.sfuEnabled === true,+ });}snapshot(): RouteSnapshot<Resource> {@@ -327,7 +337,14 @@ export class RoomRouteController<Resource = unknown> {if (changed && current.blockedAtFactVersion !== undefined) {current.blockedAtFactVersion = undefined;}- if (changed) this.touchFacts();+ if (changed) {+ this.touchFacts();+ this.debug("participant-updated", {+ participant: this.debugPeer(input.peerId),+ capacity,+ sessionChanged: previousSessionId !== input.sessionId,+ });+ }if (input.role === "viewer" &&nowMs !== undefined &&@@ -343,6 +360,11 @@ export class RoomRouteController<Resource = unknown> {departureConfirmed: false,joinOrder: this.nextJoinOrder++,});+ this.debug("participant-joined", {+ participant: this.debugPeer(input.peerId),+ role: input.role,+ capacity,+ });}if (input.role === "viewer" && nowMs !== undefined) {this.recordDemand(input.peerId, nowMs, "join");@@ -356,6 +378,9 @@ export class RoomRouteController<Resource = unknown> {if (!participant || participant.sessionId !== sessionId) return false;participant.sessionId = null;this.touchFacts();+ this.debug("participant-disconnected", {+ participant: this.debugPeer(peerId),+ });return true;}@@ -374,6 +399,9 @@ export class RoomRouteController<Resource = unknown> {}}this.touchFacts();+ this.debug("participant-departed", {+ participant: this.debugPeer(peerId),+ });return true;}@@ -396,6 +424,10 @@ export class RoomRouteController<Resource = unknown> {}}this.touchFacts();+ this.debug("capacity-updated", {+ participant: this.debugPeer(peerId),+ capacity,+ });return true;}@@ -590,6 +622,10 @@ export class RoomRouteController<Resource = unknown> {this.ensureDemand(childPeerId, nowMs, reason);const candidates = this.buildCandidates(childPeerId, bootstrap !== undefined);if (candidates.length === 0) {+ this.debug("operation-unavailable", {+ child: this.debugPeer(childPeerId),+ reason,+ });if (this.retireInvalidOperationEdge(childPeerId, released)) {this.revision = this.allocateRevision();this.touchFacts();@@ -617,6 +653,14 @@ export class RoomRouteController<Resource = unknown> {deadlineAtMs: nowMs + this.options.operationTimeoutMs,builtAtFactVersion: this.factVersion,};+ this.debug("operation-started", {+ child: this.debugPeer(childPeerId),+ reason,+ candidates: candidates.map((candidate) => ({+ route: this.debugTuple(candidate.tuple),+ transition: candidate.endpointTransition.kind,+ })),+ });return {operation: this.operationSnapshot(),removedPeerIds,@@ -701,6 +745,12 @@ export class RoomRouteController<Resource = unknown> {publicationConnectionId: input.publicationConnectionId,reservation: input.reservation,};+ this.debug("candidate-started", {+ child: this.debugPeer(operation.childPeerId),+ candidate: this.debugTuple(tuple),+ revision: operation.current.revision,+ cursor: operation.cursor,+ });this.startCandidateTiming(operation.childPeerId, input.nowMs);return { accepted: true, operation: this.operationSnapshot(), released: validation.released };}@@ -732,6 +782,12 @@ export class RoomRouteController<Resource = unknown> {return { accepted: false, released: validation.released, exhausted: validation.exhausted };}this.noteRejection(operation.childPeerId, bucket);+ this.debug("candidate-rejected", {+ child: this.debugPeer(operation.childPeerId),+ candidate: this.debugTuple(operation.candidates[operation.cursor]!.tuple),+ bucket,+ cursor: operation.cursor,+ });operation.cursor += 1;this.clearCandidateTiming(operation.childPeerId);const advanced = this.validateOrAdvance(nowMs);@@ -818,6 +874,11 @@ export class RoomRouteController<Resource = unknown> {return { accepted: false, exhausted: validation.exhausted, activeRevision: this.revision, released: validation.released };}if (!commitReservation(attempt.reservation)) {+ this.debug("candidate-commit-rejected", {+ child: this.debugPeer(operation.childPeerId),+ candidate: this.debugTuple(attempt.tuple),+ revision: attempt.revision,+ });this.noteRejection(operation.childPeerId, "candidate-failed");const failed = this.validateOrAdvance(nowMs, guard);return {@@ -834,6 +895,11 @@ export class RoomRouteController<Resource = unknown> {"none",true,);+ this.debug("candidate-ready", {+ child: this.debugPeer(operation.childPeerId),+ candidate: this.debugTuple(attempt.tuple),+ revision: attempt.revision,+ });const displacedSfuChildren =attempt.tuple.kind === "sfu" && attempt.tuple.publication === "replace"? [...this.upstreamByViewer]@@ -856,6 +922,11 @@ export class RoomRouteController<Resource = unknown> {operation?.current &&this.guardMatches(guard, operation, operation.current)) {+ this.debug("candidate-failed", {+ child: this.debugPeer(operation.childPeerId),+ candidate: this.debugTuple(operation.current.tuple),+ revision: operation.current.revision,+ });this.noteRejection(operation.childPeerId, "candidate-failed");}const validation = this.validateOrAdvance(nowMs, guard);@@ -866,6 +937,16 @@ export class RoomRouteController<Resource = unknown> {}operationExpired(nowMs: number): SettleResult<Resource> {+ if (this.operation) {+ this.debug("operation-deadline", {+ child: this.debugPeer(this.operation.childPeerId),+ candidate: this.operation.current+ ? this.debugTuple(this.operation.current.tuple)+ : null,+ cursor: this.operation.cursor,+ candidateCount: this.operation.candidates.length,+ });+ }const validation = this.validateOrAdvance(nowMs);return { accepted: validation.expired, exhausted: validation.exhausted, activeRevision: this.revision, released: validation.released };}@@ -1055,6 +1136,11 @@ export class RoomRouteController<Resource = unknown> {this.hostPublication = null;}this.assertGraph();+ this.debug("route-committed", {+ child: this.debugPeer(operation.childPeerId),+ route: this.debugTuple(attempt.tuple),+ revision: attempt.revision,+ });const afterResources = new Set(this.committedResources());const released = [...beforeResources].filter((resource) => !afterResources.has(resource));if ("overlap" in attempt.reservation && attempt.reservation.overlap !== undefined) {@@ -1410,6 +1496,10 @@ export class RoomRouteController<Resource = unknown> {) {return false;}+ const skippedFrom = operation.cursor;+ const activeCandidate = operation.current+ ? this.debugTuple(operation.current.tuple)+ : null;if (operation.current) {this.noteRejection(operation.childPeerId, "first-frame-timeout");released.push(...reservationResources(operation.current.reservation));@@ -1424,6 +1514,15 @@ export class RoomRouteController<Resource = unknown> {) {operation.cursor += 1;}+ this.debug("candidate-stage-expired", {+ child: this.debugPeer(operation.childPeerId),+ stage,+ activeCandidate,+ skippedFrom,+ skippedTo: operation.cursor,+ deadlineAtMs: stageDeadlineAtMs,+ observedAtMs: nowMs,+ });return true;}@@ -1799,6 +1898,34 @@ export class RoomRouteController<Resource = unknown> {if (this.participants.get(peerId)?.role !== "viewer") throw new Error("Route child must be a Viewer");}+ private debugPeer(peerId: string): string {+ const participant = this.participants.get(peerId);+ if (peerId === this.options.hostPeerId || participant?.role === "host") {+ return "host";+ }+ return participant ? `viewer-${participant.joinOrder}` : "viewer-unknown";+ }++ private debugTuple(tuple: CandidateTuple): string {+ return tuple.kind === "peer"+ ? `p2p:${this.debugPeer(tuple.parentPeerId)}`+ : `sfu:${tuple.publication}`;+ }++ private debug(event: string, details: Record<string, unknown>): void {+ if (!this.options.debugRoomId) return;+ routeDebug(+ "%s",+ JSON.stringify({+ event,+ roomId: this.options.debugRoomId,+ revision: this.revision,+ factVersion: this.factVersion,+ ...details,+ }),+ );+ }+private effectiveCapacity(value: number): number {if (!Number.isSafeInteger(value) || value < 0) throw new Error("Effective capacity is invalid");return Math.min(value, this.options.endpointMediaCopyCapacity);diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex b04cb655..ff4ff38a 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -1333,6 +1333,14 @@ export class SignalingServer {signalKind: message.payload.kind,...(description ? { descriptionType: description.type } : {}),});+ this.hybridMediaRouter!.debugPeerSignal({+ roomId: source.roomId,+ sourcePeerId: source.peerId,+ targetPeerId: target.peerId,+ signalKind: message.payload.kind,+ ...(description ? { descriptionType: description.type } : {}),+ authorization: candidateAuthorized,+ });const assignedEdgeAuthorized = description? description.type === "offer"? parentToChild