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. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

chore(route): add opt-in route tracing

AAA9537c59d914e
diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.ts
index 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.ts
index 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.ts
index 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