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

refactor(route): enforce exact candidate lifecycle

AAAd6dcca5e8f2d
diff --git a/src/server/room-route-controller.ts b/src/server/room-route-controller.ts
new file mode 100644
index 00000000..25f422f5
--- /dev/null
+++ b/src/server/room-route-controller.ts
@@ -0,0 +1,1166 @@
+import { MAX_MEDIA_ROUTE_REVISION } from "../shared/protocol.js";
+import { assertEndpointMediaCopyCapacity } from "../shared/media-copy-accounting.js";
+
+export type CandidateTuple =
+ | { kind: "peer"; parentPeerId: string; transport: "direct" | "selected-turn" }
+ | { kind: "sfu"; publication: "reuse" | "create" | "replace"; ingress: "existing" | "direct" | "selected-turn" };
+
+export type CandidateReservation<Resource> =
+ | { kind: "direct"; overlap?: Resource }
+ | { kind: "selected-turn"; edge: Resource; overlap?: Resource }
+ | { kind: "sfu-reuse"; edge: Resource; overlap?: Resource }
+ | { kind: "sfu-create"; edge: Resource; publication: Resource; overlap?: Resource };
+
+export type EndpointRetirement =
+ | {
+ kind: "edge";
+ childPeerId: string;
+ childSessionId: string;
+ parentPeerId: string;
+ parentSessionId: string;
+ transport: "direct" | "selected-turn";
+ connectionId: string;
+ }
+ | {
+ kind: "publication";
+ hostSessionId: string;
+ generation: string;
+ connectionId: string;
+ };
+
+export type EndpointTransition =
+ | { kind: "none"; producerPeerId?: string }
+ | { kind: "overlap"; producerPeerId: string }
+ | { kind: "bounded-gap"; producerPeerId: string; retire: EndpointRetirement };
+
+export interface CandidatePlan {
+ tuple: CandidateTuple;
+ endpointTransition: EndpointTransition;
+}
+
+export type CommittedEdge<Resource> =
+ | { kind: "peer"; childSessionId: string; parentPeerId: string; parentSessionId: string; transport: "direct"; connectionId: string; usable: boolean; physicalActive: boolean }
+ | { kind: "peer"; childSessionId: string; parentPeerId: string; parentSessionId: string; transport: "selected-turn"; connectionId: string; usable: boolean; physicalActive: boolean; resource: Resource }
+ | { kind: "sfu"; childSessionId: string; publicationGeneration: string; transport: "sfu"; connectionId: string; usable: boolean; physicalActive: boolean; resource: Resource };
+
+export type CommittedEdgeSeed<Resource> =
+ | Omit<Extract<CommittedEdge<Resource>, { transport: "direct" }>, "childSessionId" | "parentSessionId">
+ | Omit<Extract<CommittedEdge<Resource>, { transport: "selected-turn" }>, "childSessionId" | "parentSessionId">
+ | Omit<Extract<CommittedEdge<Resource>, { transport: "sfu" }>, "childSessionId">;
+
+export interface ParticipantInput {
+ peerId: string;
+ role: "host" | "viewer";
+ sessionId: string;
+ effectiveDownstreamCapacity: number;
+}
+
+export interface EdgeGuard {
+ childPeerId: string;
+ childSessionId: string;
+ routeRevision: number;
+ connectionId: string;
+ parentSessionId?: string;
+}
+
+export interface CandidateGuard {
+ childPeerId: string;
+ childSessionId: string;
+ revision: number;
+ connectionId: string;
+}
+
+export interface CandidateCursorGuard {
+ childPeerId: string;
+ childSessionId: string;
+ baseRevision: number;
+ factVersion: number;
+ cursor: number;
+ plan: CandidatePlan;
+}
+
+export interface ControllerOptions {
+ hostPeerId: string;
+ endpointMediaCopyCapacity: number;
+ operationTimeoutMs: number;
+ selectedTurnEnabled?: boolean;
+ hostSfuSelectedTurnEnabled?: boolean;
+ sfuEnabled?: boolean;
+}
+
+interface Participant {
+ peerId: string;
+ role: "host" | "viewer";
+ sessionId: string | null;
+ departureConfirmed: boolean;
+ joinOrder: number;
+ effectiveDownstreamCapacity: number;
+ blockedAtFactVersion?: number;
+}
+
+interface Attempt<Resource> {
+ tuple: CandidateTuple;
+ revision: number;
+ connectionId: string;
+ childSessionId: string;
+ parentSessionId?: string;
+ publicationGeneration?: string;
+ publicationConnectionId?: string;
+ reservation: CandidateReservation<Resource>;
+}
+
+interface ChildOperation<Resource> {
+ childPeerId: string;
+ childSessionId: string;
+ baseRevision: number;
+ candidates: CandidatePlan[];
+ cursor: number;
+ deadlineAtMs: number;
+ builtAtFactVersion: number;
+ current?: Attempt<Resource>;
+}
+
+export interface OperationSnapshot {
+ childPeerId: string;
+ childSessionId: string;
+ baseRevision: number;
+ factVersion: number;
+ candidates: readonly CandidatePlan[];
+ cursor: number;
+ deadlineAtMs: number;
+ current?: { tuple: CandidateTuple; revision: number; connectionId: string };
+}
+
+export interface RouteSnapshot<Resource> {
+ revision: number;
+ paused: boolean;
+ factVersion: number;
+ upstreamByViewer: ReadonlyMap<string, CommittedEdge<Resource>>;
+ hostPublication: HostPublication<Resource> | null;
+ operation?: OperationSnapshot;
+}
+
+export interface ReconcileResult<Resource> {
+ operation?: OperationSnapshot;
+ removedPeerIds: readonly string[];
+ released: readonly Resource[];
+}
+
+export interface SettleResult<Resource> {
+ accepted: boolean;
+ exhausted?: boolean;
+ activeRevision: number;
+ released: readonly Resource[];
+}
+
+export interface BeginResult<Resource> {
+ accepted: boolean;
+ operation?: OperationSnapshot;
+ exhausted?: boolean;
+ released: readonly Resource[];
+}
+
+interface HostPublication<Resource> {
+ generation: string;
+ hostSessionId: string;
+ connectionId: string;
+ ingress: "direct" | "selected-turn";
+ usable: boolean;
+ physicalActive: boolean;
+ resource: Resource;
+}
+
+export class RoomRouteController<Resource = unknown> {
+ private readonly participants = new Map<string, Participant>();
+ private readonly upstreamByViewer = new Map<string, CommittedEdge<Resource>>();
+ private hostPublication: HostPublication<Resource> | null = null;
+ private operation?: ChildOperation<Resource>;
+ private revision = 0;
+ private factVersion = 0;
+ private nextJoinOrder = 0;
+ private paused = false;
+
+ constructor(private readonly options: ControllerOptions) {
+ assertEndpointMediaCopyCapacity(options.endpointMediaCopyCapacity);
+ if (!Number.isSafeInteger(options.operationTimeoutMs) || options.operationTimeoutMs <= 0) {
+ throw new Error("Route operation timeout must be a positive integer");
+ }
+ }
+
+ snapshot(): RouteSnapshot<Resource> {
+ return {
+ revision: this.revision,
+ paused: this.paused,
+ factVersion: this.factVersion,
+ upstreamByViewer: new Map([...this.upstreamByViewer].map(([id, edge]) => [id, { ...edge }])),
+ hostPublication: this.hostPublication ? { ...this.hostPublication } : null,
+ operation: this.operationSnapshot(),
+ };
+ }
+
+ upsertParticipant(input: ParticipantInput): readonly Resource[] {
+ if ((input.peerId === this.options.hostPeerId) !== (input.role === "host")) {
+ throw new Error("Route Host identity is inconsistent");
+ }
+ const capacity = this.effectiveCapacity(input.effectiveDownstreamCapacity);
+ const current = this.participants.get(input.peerId);
+ if (current && current.role !== input.role) throw new Error("Route role cannot change");
+ if (current) {
+ let changed = false;
+ const released: Resource[] = [];
+ const previousSessionId = current.sessionId;
+ if (previousSessionId !== input.sessionId) {
+ current.sessionId = input.sessionId;
+ released.push(...this.rebindCommittedSession(input.peerId, input.sessionId));
+ changed = true;
+ }
+ if (current.departureConfirmed) {
+ current.departureConfirmed = false;
+ changed = true;
+ }
+ if (current.effectiveDownstreamCapacity !== capacity) {
+ current.effectiveDownstreamCapacity = capacity;
+ changed = true;
+ }
+ if (changed && current.blockedAtFactVersion !== undefined) {
+ current.blockedAtFactVersion = undefined;
+ }
+ if (changed) this.touchFacts();
+ return released;
+ } else {
+ this.participants.set(input.peerId, {
+ ...input,
+ effectiveDownstreamCapacity: capacity,
+ departureConfirmed: false,
+ joinOrder: this.nextJoinOrder++,
+ });
+ }
+ this.touchFacts();
+ return [];
+ }
+
+ disconnectSession(peerId: string, sessionId: string): boolean {
+ const participant = this.participants.get(peerId);
+ if (!participant || participant.sessionId !== sessionId) return false;
+ participant.sessionId = null;
+ this.touchFacts();
+ return true;
+ }
+
+ confirmDeparture(peerId: string): boolean {
+ const participant = this.participants.get(peerId);
+ if (!participant || participant.role === "host") return false;
+ if (participant.departureConfirmed && participant.sessionId === null &&
+ participant.effectiveDownstreamCapacity === 0) return true;
+ participant.sessionId = null;
+ participant.departureConfirmed = true;
+ participant.effectiveDownstreamCapacity = 0;
+ this.touchFacts();
+ return true;
+ }
+
+ setEffectiveCapacity(peerId: string, sessionId: string, value: number): boolean {
+ const participant = this.participants.get(peerId);
+ if (!participant || participant.sessionId !== sessionId) return false;
+ const capacity = this.effectiveCapacity(value);
+ const changed = participant.effectiveDownstreamCapacity !== capacity;
+ if (!changed) return true;
+ participant.effectiveDownstreamCapacity = capacity;
+ participant.blockedAtFactVersion = undefined;
+ this.touchFacts();
+ return true;
+ }
+
+ touchExternalFacts(): void {
+ this.touchFacts();
+ }
+
+ hydrateEdge(
+ childPeerId: string,
+ edge: CommittedEdgeSeed<Resource>,
+ ): void {
+ if (this.operation) throw new Error("Cannot hydrate while an operation is active");
+ this.assertViewer(childPeerId);
+ const childSessionId = this.participants.get(childPeerId)!.sessionId;
+ if (!childSessionId) throw new Error("Route child has no current session");
+ this.upstreamByViewer.set(childPeerId, edge.kind === "peer" ? {
+ ...edge,
+ childSessionId,
+ parentSessionId:
+ this.participants.get(edge.parentPeerId)?.sessionId ?? "",
+ } : { ...edge, childSessionId });
+ this.assertGraph();
+ }
+
+ hydrateHostPublication(
+ generation: string,
+ resource: Resource,
+ connectionId = `publication:${generation}`,
+ ingress: "direct" | "selected-turn" = "direct",
+ ): void {
+ if (this.operation) throw new Error("Cannot hydrate while an operation is active");
+ const hostSessionId = this.participants.get(this.options.hostPeerId)?.sessionId;
+ if (!hostSessionId) throw new Error("Route Host has no current session");
+ this.hostPublication = {
+ generation,
+ hostSessionId,
+ connectionId,
+ ingress,
+ usable: true,
+ physicalActive: true,
+ resource,
+ };
+ this.assertGraph();
+ }
+
+ invalidateEdge(guard: EdgeGuard): boolean {
+ const child = this.participants.get(guard.childPeerId);
+ const edge = this.upstreamByViewer.get(guard.childPeerId);
+ if (!child || child.sessionId !== guard.childSessionId || this.revision !== guard.routeRevision ||
+ !edge || edge.connectionId !== guard.connectionId ||
+ edge.childSessionId !== guard.childSessionId ||
+ (edge.kind === "peer" && edge.parentSessionId !== guard.parentSessionId)) {
+ return false;
+ }
+ if (edge.usable) {
+ edge.usable = false;
+ child.blockedAtFactVersion = undefined;
+ this.touchFacts();
+ }
+ return true;
+ }
+
+ invalidateHostPublication(guard: {
+ hostSessionId: string;
+ routeRevision: number;
+ generation: string;
+ connectionId: string;
+ }): boolean {
+ const publication = this.hostPublication;
+ if (!publication || this.revision !== guard.routeRevision ||
+ publication.hostSessionId !== guard.hostSessionId ||
+ publication.generation !== guard.generation ||
+ publication.connectionId !== guard.connectionId) return false;
+ if (publication.usable) {
+ publication.usable = false;
+ this.touchFacts();
+ }
+ return true;
+ }
+
+ retireCommittedTransport(guard: EdgeGuard): readonly Resource[] {
+ const child = this.participants.get(guard.childPeerId);
+ const edge = this.upstreamByViewer.get(guard.childPeerId);
+ if (this.operation?.current || !child || child.sessionId !== guard.childSessionId || this.revision !== guard.routeRevision ||
+ !edge || edge.connectionId !== guard.connectionId || !edge.physicalActive ||
+ edge.childSessionId !== guard.childSessionId ||
+ (edge.kind === "peer" && edge.parentSessionId !== guard.parentSessionId)) {
+ return [];
+ }
+ edge.physicalActive = false;
+ edge.usable = false;
+ child.blockedAtFactVersion = undefined;
+ this.revision = this.nextRevision();
+ if (this.operation) this.operation.baseRevision = this.revision;
+ this.touchFacts();
+ return edge.transport === "direct" ? [] : [edge.resource];
+ }
+
+ retireHostPublication(guard: {
+ hostSessionId: string;
+ routeRevision: number;
+ generation: string;
+ connectionId: string;
+ }): readonly Resource[] {
+ const publication = this.hostPublication;
+ if (this.operation?.current || !publication || !publication.physicalActive ||
+ this.revision !== guard.routeRevision ||
+ publication.hostSessionId !== guard.hostSessionId ||
+ publication.generation !== guard.generation ||
+ publication.connectionId !== guard.connectionId) return [];
+ publication.physicalActive = false;
+ publication.usable = false;
+ this.revision = this.nextRevision();
+ if (this.operation) this.operation.baseRevision = this.revision;
+ this.touchFacts();
+ return [publication.resource];
+ }
+
+ setPaused(paused: boolean): readonly Resource[] {
+ if (this.paused === paused) return [];
+ this.paused = paused;
+ this.touchFacts();
+ return paused ? this.abortOperation() : [];
+ }
+
+ reconcile(nowMs: number): ReconcileResult<Resource> {
+ const released: Resource[] = [];
+ const validation = this.validateOrAdvance(nowMs);
+ released.push(...validation.released);
+ if (this.paused || this.operation) {
+ return { operation: this.operationSnapshot(), removedPeerIds: [], released };
+ }
+ const removedPeerIds = this.pruneDepartedLeaves(released);
+
+ for (let remaining = this.participants.size; remaining > 0; remaining -= 1) {
+ const bootstrap = this.bootstrapForBlockedDemand();
+ const childPeerId = bootstrap ?? this.selectNextChild();
+ if (!childPeerId) return { removedPeerIds, released };
+ const child = this.participants.get(childPeerId)!;
+ const candidates = this.buildCandidates(childPeerId, bootstrap !== undefined);
+ if (candidates.length === 0) {
+ child.blockedAtFactVersion = this.factVersion;
+ continue;
+ }
+ this.operation = {
+ childPeerId,
+ childSessionId: child.sessionId!,
+ baseRevision: this.revision,
+ candidates,
+ cursor: 0,
+ deadlineAtMs: nowMs + this.options.operationTimeoutMs,
+ builtAtFactVersion: this.factVersion,
+ };
+ return { operation: this.operationSnapshot(), removedPeerIds, released };
+ }
+ return { removedPeerIds, released };
+ }
+
+ beginCurrentCandidate(input: {
+ guard: CandidateCursorGuard;
+ nowMs: number;
+ connectionId: string;
+ reservation: CandidateReservation<Resource>;
+ publicationGeneration?: string;
+ publicationConnectionId?: string;
+ }): BeginResult<Resource> {
+ const validation = this.validateOrAdvance(input.nowMs);
+ const operation = this.operation;
+ if (!operation || operation.current || operation.baseRevision !== this.revision ||
+ !this.cursorGuardMatches(input.guard, operation)) {
+ return {
+ accepted: false,
+ released: [...validation.released, ...reservationResources(input.reservation)],
+ exhausted: validation.exhausted,
+ };
+ }
+ const plan = operation.candidates[operation.cursor];
+ if (!plan || !this.candidateValid(operation.childPeerId, plan)) {
+ return {
+ accepted: false,
+ released: [...validation.released, ...reservationResources(input.reservation)],
+ exhausted: validation.exhausted,
+ };
+ }
+ if (plan.endpointTransition.kind === "bounded-gap") {
+ return {
+ accepted: false,
+ operation: this.operationSnapshot(),
+ released: [...validation.released, ...reservationResources(input.reservation)],
+ };
+ }
+ const tuple = plan.tuple;
+ this.assertReservation(tuple, input.reservation, plan.endpointTransition.kind === "overlap");
+ const publicationGeneration = tuple.kind === "sfu"
+ ? tuple.publication === "reuse" ? this.hostPublication?.generation : input.publicationGeneration
+ : undefined;
+ if (tuple.kind === "sfu" && !publicationGeneration) throw new Error("SFU candidate needs a publication generation");
+ if (tuple.kind === "sfu" && tuple.publication !== "reuse" && !input.publicationConnectionId) {
+ throw new Error("SFU publication candidate needs an ingress connection identity");
+ }
+ operation.current = {
+ tuple,
+ revision: this.nextRevision(),
+ connectionId: input.connectionId,
+ childSessionId: operation.childSessionId,
+ parentSessionId: tuple.kind === "peer" ? this.participants.get(tuple.parentPeerId)?.sessionId ?? undefined : undefined,
+ publicationGeneration,
+ publicationConnectionId: input.publicationConnectionId,
+ reservation: input.reservation,
+ };
+ return { accepted: true, operation: this.operationSnapshot(), released: validation.released };
+ }
+
+ skipCurrentCandidate(guard: CandidateCursorGuard, nowMs: number): BeginResult<Resource> {
+ const validation = this.validateOrAdvance(nowMs);
+ const operation = this.operation;
+ if (!operation || operation.current || !this.cursorGuardMatches(guard, operation)) {
+ return { accepted: false, released: validation.released, exhausted: validation.exhausted };
+ }
+ operation.cursor += 1;
+ const advanced = this.validateOrAdvance(nowMs);
+ return {
+ operation: this.operationSnapshot(),
+ accepted: true,
+ released: [...validation.released, ...advanced.released],
+ exhausted: advanced.exhausted,
+ };
+ }
+
+ retireCurrentCandidateProducer(
+ guard: CandidateCursorGuard,
+ nowMs: number,
+ ): BeginResult<Resource> {
+ const validation = this.validateOrAdvance(nowMs);
+ const operation = this.operation;
+ if (!operation || operation.current || !this.cursorGuardMatches(guard, operation)) {
+ return { accepted: false, released: validation.released, exhausted: validation.exhausted };
+ }
+ const plan = operation.candidates[operation.cursor];
+ if (!plan || plan.endpointTransition.kind !== "bounded-gap") {
+ return { accepted: false, operation: this.operationSnapshot(), released: validation.released };
+ }
+ const released = [...validation.released];
+ const retirement = plan.endpointTransition.retire;
+ if (retirement.kind === "edge") {
+ const edge = this.upstreamByViewer.get(retirement.childPeerId);
+ if (!edge || edge.kind !== "peer" || !edge.physicalActive ||
+ edge.childSessionId !== retirement.childSessionId ||
+ edge.parentPeerId !== retirement.parentPeerId ||
+ edge.parentSessionId !== retirement.parentSessionId ||
+ edge.transport !== retirement.transport ||
+ edge.connectionId !== retirement.connectionId) {
+ return { accepted: false, operation: this.operationSnapshot(), released };
+ }
+ if (edge.transport === "selected-turn") released.push(edge.resource);
+ this.upstreamByViewer.delete(retirement.childPeerId);
+ } else {
+ const publication = this.hostPublication;
+ if (!publication || !publication.physicalActive ||
+ publication.hostSessionId !== retirement.hostSessionId ||
+ publication.generation !== retirement.generation ||
+ publication.connectionId !== retirement.connectionId) {
+ return { accepted: false, operation: this.operationSnapshot(), released };
+ }
+ released.push(...this.removePublicationGeneration(retirement.generation));
+ }
+ this.advanceActiveRevision(operation);
+ const nextTuple = retirement.kind === "publication" && plan.tuple.kind === "sfu" &&
+ plan.tuple.publication === "replace"
+ ? { ...plan.tuple, publication: "create" as const }
+ : plan.tuple;
+ const nextPlan = this.planCandidate(operation.childPeerId, nextTuple);
+ if (!nextPlan) {
+ operation.cursor += 1;
+ const advanced = this.validateOrAdvance(nowMs);
+ return {
+ accepted: true,
+ operation: this.operationSnapshot(),
+ exhausted: advanced.exhausted,
+ released: [...released, ...advanced.released],
+ };
+ }
+ operation.candidates[operation.cursor] = nextPlan;
+ return { accepted: true, operation: this.operationSnapshot(), released };
+ }
+
+ candidateReady(guard: CandidateGuard, nowMs: number): SettleResult<Resource> {
+ const validation = this.validateOrAdvance(nowMs);
+ const operation = this.operation;
+ const attempt = operation?.current;
+ if (!operation || !attempt || !this.guardMatches(guard, operation, attempt)) {
+ return { accepted: false, exhausted: validation.exhausted, activeRevision: this.revision, released: validation.released };
+ }
+ const released = [...validation.released, ...this.commitAttempt(operation, attempt)];
+ return { accepted: true, activeRevision: this.revision, released };
+ }
+
+ candidateFailed(guard: CandidateGuard, nowMs: number): SettleResult<Resource> {
+ const validation = this.validateOrAdvance(nowMs, guard);
+ if (validation.consumedGuard) {
+ return { accepted: true, exhausted: validation.exhausted, activeRevision: this.revision, released: validation.released };
+ }
+ return { accepted: false, exhausted: validation.exhausted, activeRevision: this.revision, released: validation.released };
+ }
+
+ operationExpired(nowMs: number): SettleResult<Resource> {
+ const validation = this.validateOrAdvance(nowMs);
+ return { accepted: validation.expired, exhausted: validation.exhausted, activeRevision: this.revision, released: validation.released };
+ }
+
+ private validateOrAdvance(nowMs: number, failedGuard?: CandidateGuard): {
+ released: Resource[]; exhausted?: boolean; expired: boolean; consumedGuard: boolean;
+ } {
+ const released: Resource[] = [];
+ const result = { released, exhausted: undefined as boolean | undefined, expired: false, consumedGuard: false };
+ let operation = this.operation;
+ if (!operation) return result;
+ if (nowMs >= operation.deadlineAtMs) {
+ if (operation.current) released.push(...reservationResources(operation.current.reservation));
+ if (operation.current) this.advanceActiveRevision(operation);
+ const factsChanged = operation.builtAtFactVersion !== this.factVersion;
+ this.blockAndClear(operation, !factsChanged);
+ return { ...result, exhausted: !factsChanged, expired: true };
+ }
+ if (this.participants.get(operation.childPeerId)?.sessionId !== operation.childSessionId) {
+ if (operation.current) released.push(...reservationResources(operation.current.reservation));
+ if (operation.current) this.advanceActiveRevision(operation);
+ this.operation = undefined;
+ return result;
+ }
+
+ while ((operation = this.operation)) {
+ const attempt = operation.current;
+ if (attempt) {
+ const guardFailed = failedGuard && this.guardMatches(failedGuard, operation, attempt);
+ const plan = operation.candidates[operation.cursor];
+ if (!guardFailed && plan && this.candidateValid(operation.childPeerId, plan, attempt)) return result;
+ released.push(...reservationResources(attempt.reservation));
+ this.advanceActiveRevision(operation);
+ operation.current = undefined;
+ operation.cursor += 1;
+ result.consumedGuard = Boolean(guardFailed);
+ }
+ while (operation.cursor < operation.candidates.length &&
+ !this.candidateValid(operation.childPeerId, operation.candidates[operation.cursor]!)) {
+ operation.cursor += 1;
+ }
+ if (operation.cursor < operation.candidates.length) return result;
+ const factsChanged = operation.builtAtFactVersion !== this.factVersion;
+ this.blockAndClear(operation, !factsChanged);
+ result.exhausted = !factsChanged;
+ }
+ return result;
+ }
+
+ private commitAttempt(operation: ChildOperation<Resource>, attempt: Attempt<Resource>): Resource[] {
+ const released: Resource[] = [];
+ const old = this.upstreamByViewer.get(operation.childPeerId);
+ if ("overlap" in attempt.reservation && attempt.reservation.overlap !== undefined) released.push(attempt.reservation.overlap);
+
+ if (attempt.tuple.kind === "sfu" && attempt.tuple.publication === "replace") {
+ released.push(...this.removePublicationGeneration(this.hostPublication!.generation));
+ } else if (old && old.transport !== "direct" && old.physicalActive) {
+ released.push(old.resource);
+ }
+
+ if (attempt.tuple.kind === "peer") {
+ const parentSessionId = this.participants.get(attempt.tuple.parentPeerId)?.sessionId;
+ if (!parentSessionId) throw new Error("Candidate parent session is unavailable");
+ this.upstreamByViewer.set(operation.childPeerId, attempt.tuple.transport === "direct" ? {
+ kind: "peer", childSessionId: operation.childSessionId,
+ parentPeerId: attempt.tuple.parentPeerId, parentSessionId, transport: "direct",
+ connectionId: attempt.connectionId, usable: true, physicalActive: true,
+ } : {
+ kind: "peer", childSessionId: operation.childSessionId,
+ parentPeerId: attempt.tuple.parentPeerId, parentSessionId, transport: "selected-turn",
+ connectionId: attempt.connectionId, usable: true, physicalActive: true,
+ resource: (attempt.reservation as Extract<CandidateReservation<Resource>, { kind: "selected-turn" }>).edge,
+ });
+ } else {
+ const generation = attempt.publicationGeneration!;
+ if (attempt.tuple.publication !== "reuse") {
+ const reservation = attempt.reservation as Extract<CandidateReservation<Resource>, { kind: "sfu-create" }>;
+ const hostSessionId = this.participants.get(this.options.hostPeerId)?.sessionId;
+ if (!hostSessionId || !attempt.publicationConnectionId) {
+ throw new Error("SFU publication identity is unavailable");
+ }
+ this.hostPublication = {
+ generation,
+ hostSessionId,
+ connectionId: attempt.publicationConnectionId,
+ ingress: attempt.tuple.ingress === "selected-turn" ? "selected-turn" : "direct",
+ usable: true,
+ physicalActive: true,
+ resource: reservation.publication,
+ };
+ }
+ const edge = (attempt.reservation as Extract<CandidateReservation<Resource>, { kind: "sfu-reuse" | "sfu-create" }>).edge;
+ this.upstreamByViewer.set(operation.childPeerId, {
+ kind: "sfu", childSessionId: operation.childSessionId,
+ publicationGeneration: generation, transport: "sfu",
+ connectionId: attempt.connectionId, usable: true, physicalActive: true, resource: edge,
+ });
+ }
+ this.revision = attempt.revision;
+ this.operation = undefined;
+ this.touchFacts();
+ const participant = this.participants.get(operation.childPeerId);
+ if (participant) participant.blockedAtFactVersion = undefined;
+ if (old?.kind === "sfu" && !this.hasSfuSubscribers() && this.hostPublication) {
+ if (this.hostPublication.physicalActive) released.push(this.hostPublication.resource);
+ this.hostPublication = null;
+ }
+ this.assertGraph();
+ return released;
+ }
+
+ private buildCandidates(childPeerId: string, sfuOnly: boolean): CandidatePlan[] {
+ const failed = this.upstreamByViewer.get(childPeerId);
+ const failedKey = failed?.usable === false ? edgeTupleKey(failed) : undefined;
+ const descendants = this.descendantsOf(childPeerId);
+ const parents = [...this.participants.values()]
+ .filter((parent) => parent.sessionId && !parent.departureConfirmed && parent.peerId !== childPeerId &&
+ !descendants.has(parent.peerId) && this.sourceUsable(parent.peerId) && this.targetFits(parent.peerId, childPeerId))
+ .sort((left, right) => this.depth(left.peerId) - this.depth(right.peerId) ||
+ this.remaining(right.peerId, childPeerId) - this.remaining(left.peerId, childPeerId) ||
+ compareParticipant(left, right));
+ const candidates: CandidateTuple[] = [];
+ if (!sfuOnly) {
+ for (const parent of parents) candidates.push({ kind: "peer", parentPeerId: parent.peerId, transport: "direct" });
+ if (this.options.selectedTurnEnabled) {
+ for (const parent of parents) if (parent.role !== "host") {
+ candidates.push({ kind: "peer", parentPeerId: parent.peerId, transport: "selected-turn" });
+ }
+ }
+ }
+ if (this.options.sfuEnabled) {
+ if (this.hostPublication?.usable && this.hostPublication.physicalActive) {
+ candidates.push({ kind: "sfu", publication: "reuse", ingress: "existing" });
+ } else if (this.hostPublication || this.publicationFits(childPeerId, false)) {
+ const publication = this.hostPublication ? "replace" : "create";
+ candidates.push({ kind: "sfu", publication, ingress: "direct" });
+ if (this.options.hostSfuSelectedTurnEnabled) {
+ candidates.push({ kind: "sfu", publication, ingress: "selected-turn" });
+ }
+ }
+ }
+ return candidates.filter((candidate, index, all) => tupleKey(candidate) !== failedKey &&
+ all.findIndex((other) => tupleKey(other) === tupleKey(candidate)) === index)
+ .map((candidate) => this.planCandidate(childPeerId, candidate))
+ .filter((candidate): candidate is CandidatePlan => candidate !== null &&
+ this.candidateValid(childPeerId, candidate));
+ }
+
+ private selectNextChild(): string | undefined {
+ const viewers = this.availableViewers();
+ const departedParent = viewers.find(({ peerId }) => {
+ const edge = this.upstreamByViewer.get(peerId);
+ return edge?.kind === "peer" && this.participants.get(edge.parentPeerId)?.departureConfirmed;
+ });
+ if (departedParent) return departedParent.peerId;
+ const overflow = this.overflowChildren();
+ if (overflow.length > 0) return overflow[0];
+ const unusable = viewers.find(({ peerId }) => this.upstreamByViewer.get(peerId)?.usable === false);
+ const staleSfu = viewers.find(({ peerId }) => {
+ const edge = this.upstreamByViewer.get(peerId);
+ return edge?.kind === "sfu" && (!this.hostPublication?.usable ||
+ this.hostPublication.generation !== edge.publicationGeneration);
+ });
+ return unusable?.peerId ?? staleSfu?.peerId ?? viewers.find(({ peerId }) => !this.upstreamByViewer.has(peerId))?.peerId;
+ }
+
+ private bootstrapForBlockedDemand(): string | undefined {
+ if (!this.options.sfuEnabled || this.hostPublication || this.hostHasPublicationSlot()) return undefined;
+ const demand = this.availableViewers(true).find((viewer) => viewer.blockedAtFactVersion === this.factVersion);
+ if (!demand) return undefined;
+ return this.childrenOf(this.options.hostPeerId)
+ .filter((id) => {
+ const participant = this.participants.get(id);
+ const edge = this.upstreamByViewer.get(id);
+ return participant?.sessionId && participant.blockedAtFactVersion !== this.factVersion &&
+ edge?.kind === "peer" && edge.transport === "direct" && edge.usable;
+ })
+ .sort((left, right) => compareParticipant(this.participants.get(right)!, this.participants.get(left)!))[0];
+ }
+
+ private availableViewers(includeBlocked = false): Participant[] {
+ return [...this.participants.values()].filter((participant) => participant.role === "viewer" &&
+ participant.sessionId && !participant.departureConfirmed &&
+ (includeBlocked || participant.blockedAtFactVersion !== this.factVersion))
+ .sort(compareParticipant);
+ }
+
+ private overflowChildren(): string[] {
+ const result: string[] = [];
+ for (const parent of this.participants.values()) {
+ const capacity = Math.max(0, parent.effectiveDownstreamCapacity - (parent.role === "host" && this.hostPublication ? 1 : 0));
+ const children = this.childrenOf(parent.peerId).filter((id) => {
+ const child = this.participants.get(id);
+ return child?.sessionId && !child.departureConfirmed && child.blockedAtFactVersion !== this.factVersion;
+ }).sort((left, right) => compareParticipant(this.participants.get(left)!, this.participants.get(right)!));
+ result.push(...children.slice(capacity).reverse());
+ }
+ return result;
+ }
+
+ private candidateValid(childPeerId: string, plan: CandidatePlan, attempt?: Attempt<Resource>): boolean {
+ const tuple = plan.tuple;
+ const child = this.participants.get(childPeerId);
+ if (!child?.sessionId || child.departureConfirmed || (attempt && attempt.childSessionId !== child.sessionId)) return false;
+ if (tuple.kind === "peer") {
+ const parent = this.participants.get(tuple.parentPeerId);
+ if (!parent?.sessionId || parent.departureConfirmed || (attempt && parent.sessionId !== attempt.parentSessionId) ||
+ this.descendantsOf(childPeerId).has(parent.peerId) || !this.sourceUsable(parent.peerId) ||
+ !this.targetFits(parent.peerId, childPeerId)) return false;
+ } else {
+ if (!this.options.sfuEnabled) return false;
+ if (tuple.publication === "reuse") {
+ if (!this.hostPublication?.usable || !this.hostPublication.physicalActive ||
+ (attempt && attempt.publicationGeneration !== this.hostPublication.generation)) return false;
+ } else if (tuple.publication === "replace") {
+ if (!this.hostPublication || this.hostPublication.usable || !this.publicationFits(childPeerId, true)) return false;
+ } else if (this.hostPublication || !this.publicationFits(childPeerId, false)) {
+ return false;
+ }
+ }
+ const currentPlan = this.planCandidate(childPeerId, tuple);
+ return Boolean(currentPlan && endpointTransitionEquals(currentPlan.endpointTransition, plan.endpointTransition));
+ }
+
+ private planCandidate(childPeerId: string, tuple: CandidateTuple): CandidatePlan | null {
+ if (tuple.kind === "sfu" && tuple.publication === "reuse") {
+ return { tuple, endpointTransition: { kind: "none" } };
+ }
+ const producerPeerId = tuple.kind === "peer" ? tuple.parentPeerId : this.options.hostPeerId;
+ const producer = this.participants.get(producerPeerId);
+ if (!producer?.sessionId || producer.departureConfirmed) return null;
+ const copies = this.physicalCopies(producerPeerId);
+ if (copies + 1 <= producer.effectiveDownstreamCapacity) {
+ return { tuple, endpointTransition: { kind: "none", producerPeerId } };
+ }
+ if (copies + 1 <= Math.min(this.options.endpointMediaCopyCapacity + 1, 3)) {
+ return { tuple, endpointTransition: { kind: "overlap", producerPeerId } };
+ }
+ const retire = this.retirementFor(childPeerId, producerPeerId, tuple);
+ if (!retire || copies > producer.effectiveDownstreamCapacity) return null;
+ return { tuple, endpointTransition: { kind: "bounded-gap", producerPeerId, retire } };
+ }
+
+ private retirementFor(
+ childPeerId: string,
+ producerPeerId: string,
+ tuple: CandidateTuple,
+ ): EndpointRetirement | null {
+ const old = this.upstreamByViewer.get(childPeerId);
+ if (old?.kind === "peer" && old.parentPeerId === producerPeerId && old.physicalActive) {
+ return {
+ kind: "edge",
+ childPeerId,
+ childSessionId: old.childSessionId,
+ parentPeerId: old.parentPeerId,
+ parentSessionId: old.parentSessionId,
+ transport: old.transport,
+ connectionId: old.connectionId,
+ };
+ }
+ if (producerPeerId !== this.options.hostPeerId || !this.hostPublication?.physicalActive) return null;
+ const replacesPublication = tuple.kind === "sfu" && tuple.publication === "replace";
+ const releasesLastPublication = tuple.kind === "peer" && old?.kind === "sfu" &&
+ this.sfuSubscriberCount() === 1;
+ if (!replacesPublication && !releasesLastPublication) return null;
+ return {
+ kind: "publication",
+ hostSessionId: this.hostPublication.hostSessionId,
+ generation: this.hostPublication.generation,
+ connectionId: this.hostPublication.connectionId,
+ };
+ }
+
+ private physicalCopies(peerId: string): number {
+ let copies = [...this.upstreamByViewer.values()].filter((edge) =>
+ edge.kind === "peer" && edge.parentPeerId === peerId && edge.physicalActive).length;
+ if (peerId === this.options.hostPeerId && this.hostPublication?.physicalActive) copies += 1;
+ return copies;
+ }
+
+ private assertReservation(tuple: CandidateTuple, reservation: CandidateReservation<Resource>, overlap: boolean): void {
+ const expected = tuple.kind === "peer" ? tuple.transport === "direct" ? "direct" : "selected-turn" :
+ tuple.publication === "reuse" ? "sfu-reuse" : "sfu-create";
+ if (reservation.kind !== expected) throw new Error("Candidate reservation kind does not match tuple");
+ if (overlap && !("overlap" in reservation && reservation.overlap !== undefined)) {
+ throw new Error("Candidate requires an endpoint overlap reservation");
+ }
+ }
+
+ private pruneDepartedLeaves(released: Resource[]): string[] {
+ const removed: string[] = [];
+ let changed = true;
+ while (changed) {
+ changed = false;
+ for (const participant of this.participants.values()) {
+ if (participant.role !== "viewer" || !participant.departureConfirmed || this.childrenOf(participant.peerId).length > 0) continue;
+ const edge = this.upstreamByViewer.get(participant.peerId);
+ if (edge && edge.transport !== "direct" && edge.physicalActive) released.push(edge.resource);
+ this.upstreamByViewer.delete(participant.peerId);
+ this.participants.delete(participant.peerId);
+ removed.push(participant.peerId);
+ changed = true;
+ }
+ }
+ if (removed.length > 0) {
+ if (!this.hasSfuSubscribers() && this.hostPublication) {
+ if (this.hostPublication.physicalActive) released.push(this.hostPublication.resource);
+ this.hostPublication = null;
+ }
+ this.revision = this.nextRevision();
+ this.touchFacts();
+ }
+ return removed;
+ }
+
+ private abortOperation(): Resource[] {
+ if (!this.operation) return [];
+ const released = this.operation.current ? reservationResources(this.operation.current.reservation) : [];
+ if (this.operation.current) this.advanceActiveRevision(this.operation);
+ this.operation = undefined;
+ return released;
+ }
+
+ private advanceActiveRevision(operation: ChildOperation<Resource>): void {
+ this.revision = this.nextRevision();
+ operation.baseRevision = this.revision;
+ }
+
+ private blockAndClear(operation: ChildOperation<Resource>, block = true): void {
+ const child = this.participants.get(operation.childPeerId);
+ if (block && child) child.blockedAtFactVersion = this.factVersion;
+ this.operation = undefined;
+ }
+
+ private operationSnapshot(): OperationSnapshot | undefined {
+ const operation = this.operation;
+ if (!operation) return undefined;
+ return { childPeerId: operation.childPeerId, childSessionId: operation.childSessionId,
+ baseRevision: operation.baseRevision, factVersion: operation.builtAtFactVersion,
+ candidates: operation.candidates.map(cloneCandidatePlan),
+ cursor: operation.cursor, deadlineAtMs: operation.deadlineAtMs,
+ current: operation.current ? { tuple: { ...operation.current.tuple }, revision: operation.current.revision,
+ connectionId: operation.current.connectionId } : undefined };
+ }
+
+ private guardMatches(guard: CandidateGuard, operation: ChildOperation<Resource>, attempt: Attempt<Resource>): boolean {
+ return guard.childPeerId === operation.childPeerId && guard.childSessionId === operation.childSessionId &&
+ guard.revision === attempt.revision && guard.connectionId === attempt.connectionId;
+ }
+
+ private cursorGuardMatches(guard: CandidateCursorGuard, operation: ChildOperation<Resource>): boolean {
+ const plan = operation.candidates[operation.cursor];
+ return Boolean(plan && guard.childPeerId === operation.childPeerId &&
+ guard.childSessionId === operation.childSessionId && guard.baseRevision === operation.baseRevision &&
+ guard.factVersion === operation.builtAtFactVersion && guard.cursor === operation.cursor &&
+ candidatePlanEquals(guard.plan, plan));
+ }
+
+ private childrenOf(parentPeerId: string): string[] {
+ return [...this.upstreamByViewer].filter(([, edge]) => edge.kind === "peer" && edge.parentPeerId === parentPeerId).map(([id]) => id);
+ }
+
+ private descendantsOf(peerId: string): Set<string> {
+ const descendants = new Set<string>();
+ const queue = [peerId];
+ while (queue.length) for (const child of this.childrenOf(queue.pop()!)) if (!descendants.has(child)) {
+ descendants.add(child); queue.push(child);
+ }
+ return descendants;
+ }
+
+ private sourceUsable(peerId: string): boolean {
+ if (peerId === this.options.hostPeerId) return true;
+ const seen = new Set<string>();
+ while (!seen.has(peerId)) {
+ seen.add(peerId);
+ const edge = this.upstreamByViewer.get(peerId);
+ if (!edge?.usable || !edge.physicalActive) return false;
+ if (edge.kind === "sfu") return Boolean(this.hostPublication?.usable &&
+ this.hostPublication.physicalActive && this.hostPublication.generation === edge.publicationGeneration);
+ if (edge.parentPeerId === this.options.hostPeerId) return true;
+ peerId = edge.parentPeerId;
+ }
+ return false;
+ }
+
+ private targetFits(parentPeerId: string, childPeerId: string): boolean {
+ const parent = this.participants.get(parentPeerId)!;
+ const edge = this.upstreamByViewer.get(childPeerId);
+ const already = edge?.kind === "peer" && edge.parentPeerId === parentPeerId;
+ const releasesLastPublication = parent.role === "host" && edge?.kind === "sfu" &&
+ this.sfuSubscriberCount() === 1;
+ return this.usedSlots(parentPeerId) - (releasesLastPublication ? 1 : 0) +
+ (already ? 0 : 1) <= parent.effectiveDownstreamCapacity;
+ }
+
+ private publicationFits(childPeerId: string, replacing: boolean): boolean {
+ const host = this.participants.get(this.options.hostPeerId);
+ const edge = this.upstreamByViewer.get(childPeerId);
+ const releasesHost = edge?.kind === "peer" && edge.parentPeerId === this.options.hostPeerId;
+ const nextSlots = this.usedSlots(this.options.hostPeerId) - (releasesHost ? 1 : 0) +
+ (replacing ? 0 : 1);
+ return Boolean(host?.sessionId && !host.departureConfirmed && nextSlots <= host.effectiveDownstreamCapacity);
+ }
+
+ private hostHasPublicationSlot(): boolean {
+ const host = this.participants.get(this.options.hostPeerId);
+ return Boolean(host && this.usedSlots(this.options.hostPeerId) + 1 <= host.effectiveDownstreamCapacity);
+ }
+
+ private usedSlots(peerId: string): number {
+ const participant = this.participants.get(peerId);
+ return this.childrenOf(peerId).length + (participant?.role === "host" && this.hostPublication ? 1 : 0);
+ }
+
+ private remaining(parentPeerId: string, childPeerId: string): number {
+ const parent = this.participants.get(parentPeerId)!;
+ const edge = this.upstreamByViewer.get(childPeerId);
+ const already = edge?.kind === "peer" && edge.parentPeerId === parentPeerId;
+ return parent.effectiveDownstreamCapacity - this.usedSlots(parentPeerId) - (already ? 0 : 1);
+ }
+
+ private depth(peerId: string): number {
+ if (peerId === this.options.hostPeerId) return 1;
+ let depth = 1;
+ const seen = new Set<string>();
+ while (!seen.has(peerId)) {
+ seen.add(peerId);
+ const edge = this.upstreamByViewer.get(peerId);
+ if (!edge || edge.kind === "sfu") return depth + 1;
+ depth += 1;
+ if (edge.parentPeerId === this.options.hostPeerId) return depth;
+ peerId = edge.parentPeerId;
+ }
+ return Number.MAX_SAFE_INTEGER;
+ }
+
+ private hasSfuSubscribers(): boolean {
+ return [...this.upstreamByViewer.values()].some((edge) => edge.kind === "sfu");
+ }
+
+ private sfuSubscriberCount(): number {
+ return [...this.upstreamByViewer.values()].filter((edge) => edge.kind === "sfu").length;
+ }
+
+ private rebindCommittedSession(peerId: string, sessionId: string): Resource[] {
+ const released: Resource[] = [];
+ const ownEdge = this.upstreamByViewer.get(peerId);
+ if (ownEdge?.kind === "peer" && ownEdge.transport === "selected-turn") {
+ if (ownEdge.physicalActive) released.push(ownEdge.resource);
+ ownEdge.physicalActive = false;
+ ownEdge.usable = false;
+ } else if (ownEdge) {
+ ownEdge.childSessionId = sessionId;
+ }
+ for (const edge of this.upstreamByViewer.values()) {
+ if (edge.kind !== "peer" || edge.parentPeerId !== peerId) continue;
+ if (edge.transport === "selected-turn") {
+ if (edge.physicalActive) released.push(edge.resource);
+ edge.physicalActive = false;
+ edge.usable = false;
+ } else {
+ edge.parentSessionId = sessionId;
+ }
+ }
+ if (peerId === this.options.hostPeerId && this.hostPublication) {
+ if (this.hostPublication.ingress === "selected-turn") {
+ if (this.hostPublication.physicalActive) released.push(this.hostPublication.resource);
+ this.hostPublication.physicalActive = false;
+ this.hostPublication.usable = false;
+ } else {
+ this.hostPublication.hostSessionId = sessionId;
+ }
+ }
+ return released;
+ }
+
+ private removePublicationGeneration(generation: string): Resource[] {
+ const released: Resource[] = [];
+ for (const [viewerPeerId, edge] of this.upstreamByViewer) {
+ if (edge.kind !== "sfu" || edge.publicationGeneration !== generation) continue;
+ if (edge.physicalActive) released.push(edge.resource);
+ this.upstreamByViewer.delete(viewerPeerId);
+ }
+ if (this.hostPublication?.generation === generation) {
+ if (this.hostPublication.physicalActive) released.push(this.hostPublication.resource);
+ this.hostPublication = null;
+ }
+ return released;
+ }
+
+ private assertGraph(): void {
+ const host = this.participants.get(this.options.hostPeerId);
+ if (!host || host.role !== "host") throw new Error("Route Host is missing");
+ for (const [child, edge] of this.upstreamByViewer) {
+ this.assertViewer(child);
+ if (edge.kind === "peer" && !this.participants.has(edge.parentPeerId)) throw new Error("Route parent is missing");
+ if (edge.kind === "sfu" && this.hostPublication?.generation !== edge.publicationGeneration) throw new Error("SFU publication is stale");
+ const seen = new Set<string>();
+ let current = child;
+ while (current !== this.options.hostPeerId) {
+ if (seen.has(current)) throw new Error("Peer route contains a cycle");
+ seen.add(current);
+ const currentEdge = this.upstreamByViewer.get(current);
+ if (!currentEdge) throw new Error("Route is not source-reachable");
+ if (currentEdge.kind === "sfu") break;
+ current = currentEdge.parentPeerId;
+ }
+ }
+ for (const participant of this.participants.values()) if (this.usedSlots(participant.peerId) > this.options.endpointMediaCopyCapacity) {
+ throw new Error("Committed route exceeds endpoint capacity");
+ }
+ }
+
+ private assertViewer(peerId: string): void {
+ if (this.participants.get(peerId)?.role !== "viewer") throw new Error("Route child must be a Viewer");
+ }
+
+ 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);
+ }
+
+ private touchFacts(): void { this.factVersion += 1; }
+
+ private nextRevision(): number {
+ if (this.revision >= MAX_MEDIA_ROUTE_REVISION) throw new Error("Media route revision space exhausted");
+ return this.revision + 1;
+ }
+}
+
+function compareParticipant(left: Participant, right: Participant): number {
+ return left.joinOrder - right.joinOrder || left.peerId.localeCompare(right.peerId);
+}
+
+function tupleKey(tuple: CandidateTuple): string {
+ return tuple.kind === "peer" ? `peer:${tuple.parentPeerId}:${tuple.transport}` : `sfu:${tuple.publication}:${tuple.ingress}`;
+}
+
+function edgeTupleKey<Resource>(edge: CommittedEdge<Resource>): string {
+ return edge.kind === "peer" ? `peer:${edge.parentPeerId}:${edge.transport}` : "sfu:reuse:existing";
+}
+
+function cloneCandidatePlan(plan: CandidatePlan): CandidatePlan {
+ return {
+ tuple: { ...plan.tuple },
+ endpointTransition: plan.endpointTransition.kind === "bounded-gap"
+ ? { ...plan.endpointTransition, retire: { ...plan.endpointTransition.retire } }
+ : { ...plan.endpointTransition },
+ };
+}
+
+function candidatePlanEquals(left: CandidatePlan, right: CandidatePlan): boolean {
+ return tupleKey(left.tuple) === tupleKey(right.tuple) &&
+ endpointTransitionEquals(left.endpointTransition, right.endpointTransition);
+}
+
+function endpointTransitionEquals(left: EndpointTransition, right: EndpointTransition): boolean {
+ if (left.kind !== right.kind) return false;
+ if (left.kind === "none" && right.kind === "none") {
+ return left.producerPeerId === right.producerPeerId;
+ }
+ if (left.kind === "overlap" && right.kind === "overlap") {
+ return left.producerPeerId === right.producerPeerId;
+ }
+ if (left.kind !== "bounded-gap" || right.kind !== "bounded-gap" ||
+ left.producerPeerId !== right.producerPeerId || left.retire.kind !== right.retire.kind) return false;
+ if (left.retire.kind === "publication" && right.retire.kind === "publication") {
+ return left.retire.hostSessionId === right.retire.hostSessionId &&
+ left.retire.generation === right.retire.generation &&
+ left.retire.connectionId === right.retire.connectionId;
+ }
+ if (left.retire.kind === "edge" && right.retire.kind === "edge") {
+ return left.retire.childPeerId === right.retire.childPeerId &&
+ left.retire.childSessionId === right.retire.childSessionId &&
+ left.retire.parentPeerId === right.retire.parentPeerId &&
+ left.retire.parentSessionId === right.retire.parentSessionId &&
+ left.retire.transport === right.retire.transport &&
+ left.retire.connectionId === right.retire.connectionId;
+ }
+ return false;
+}
+
+function reservationResources<Resource>(reservation: CandidateReservation<Resource>): Resource[] {
+ const resources: Resource[] = [];
+ if ("edge" in reservation) resources.push(reservation.edge);
+ if ("publication" in reservation) resources.push(reservation.publication);
+ if ("overlap" in reservation && reservation.overlap !== undefined) resources.push(reservation.overlap);
+ return resources;
+}
diff --git a/tests/room-route-controller.test.ts b/tests/room-route-controller.test.ts
new file mode 100644
index 00000000..074846fb
--- /dev/null
+++ b/tests/room-route-controller.test.ts
@@ -0,0 +1,905 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ RoomRouteController,
+ type CandidateGuard,
+ type CandidateCursorGuard,
+ type CandidateReservation,
+ type CommittedEdgeSeed,
+ type OperationSnapshot,
+} from "../src/server/room-route-controller.ts";
+
+const HOST = "host_12345678";
+const A = "viewer_a_12345678";
+const B = "viewer_b_12345678";
+const C = "viewer_c_12345678";
+const D = "viewer_d_12345678";
+const E = "viewer_e_12345678";
+const F = "viewer_f_12345678";
+
+function controller(
+ capacity: 1 | 2 | 3 = 2,
+ options: { selectedTurnEnabled?: boolean; sfuEnabled?: boolean } = {},
+) {
+ const routes = new RoomRouteController<string>({
+ hostPeerId: HOST,
+ endpointMediaCopyCapacity: capacity,
+ operationTimeoutMs: 10_000,
+ ...options,
+ });
+ routes.upsertParticipant({
+ peerId: HOST,
+ role: "host",
+ sessionId: "host_session",
+ effectiveDownstreamCapacity: capacity,
+ });
+ return routes;
+}
+
+function addViewer(
+ routes: RoomRouteController<string>,
+ peerId: string,
+ capacity: 0 | 1 | 2 | 3,
+) {
+ routes.upsertParticipant({
+ peerId,
+ role: "viewer",
+ sessionId: `${peerId}_session`,
+ effectiveDownstreamCapacity: capacity,
+ });
+}
+
+function cursorGuard(operation: OperationSnapshot): CandidateCursorGuard {
+ return {
+ childPeerId: operation.childPeerId,
+ childSessionId: operation.childSessionId,
+ baseRevision: operation.baseRevision,
+ factVersion: operation.factVersion,
+ cursor: operation.cursor,
+ plan: operation.candidates[operation.cursor]!,
+ };
+}
+
+function beginCandidate(
+ routes: RoomRouteController<string>,
+ input: {
+ nowMs: number;
+ connectionId: string;
+ reservation: CandidateReservation<string>;
+ publicationGeneration?: string;
+ publicationConnectionId?: string;
+ },
+) {
+ const operation = routes.snapshot().operation!;
+ return routes.beginCurrentCandidate({
+ guard: cursorGuard(operation),
+ ...input,
+ });
+}
+
+function skipCandidate(routes: RoomRouteController<string>, nowMs: number) {
+ const operation = routes.snapshot().operation!;
+ return routes.skipCurrentCandidate(cursorGuard(operation), nowMs);
+}
+
+function commitCurrent(
+ routes: RoomRouteController<string>,
+ nowMs: number,
+ connectionId: string,
+) {
+ const begin = beginCandidate(routes, {
+ nowMs,
+ connectionId,
+ reservation: { kind: "direct" },
+ });
+ const prepared = begin.operation!;
+ const current = prepared.current!;
+ const guard: CandidateGuard = {
+ childPeerId: prepared.childPeerId,
+ childSessionId: prepared.childSessionId,
+ revision: current.revision,
+ connectionId,
+ };
+ expect(routes.candidateReady(guard, nowMs + 1).accepted).toBe(true);
+ return guard;
+}
+
+function peerEdge(
+ parentPeerId: string,
+ connectionId: string,
+ usable = true,
+): CommittedEdgeSeed<string> {
+ return {
+ kind: "peer",
+ parentPeerId,
+ transport: "direct",
+ connectionId,
+ usable,
+ physicalActive: true,
+ };
+}
+
+describe("RoomRouteController", () => {
+ it.each([1, 2, 3] as const)(
+ "builds a deterministic acyclic route without a depth cap at C=%i",
+ (capacity) => {
+ const routes = controller(capacity);
+ for (const peerId of [A, B, C, D]) {
+ addViewer(routes, peerId, capacity);
+ const result = routes.reconcile(0);
+ expect(result.operation?.childPeerId).toBe(peerId);
+ commitCurrent(routes, 1, `${peerId}_connection`);
+ }
+
+ const snapshot = routes.snapshot();
+ expect(snapshot.upstreamByViewer).toHaveLength(4);
+ for (const [childPeerId, edge] of snapshot.upstreamByViewer) {
+ expect(edge.kind).toBe("peer");
+ expect(edge.kind === "peer" && edge.parentPeerId).not.toBe(childPeerId);
+ }
+ if (capacity === 1) {
+ expect(snapshot.upstreamByViewer.get(D)).toMatchObject({
+ kind: "peer",
+ parentPeerId: C,
+ });
+ }
+ },
+ );
+
+ it("keeps the old edge until exact candidate first-frame ready", () => {
+ const routes = controller(2);
+ addViewer(routes, A, 2);
+ addViewer(routes, B, 2);
+ routes.reconcile(0);
+ commitCurrent(routes, 1, "old_connection");
+ routes.reconcile(2);
+ commitCurrent(routes, 3, "b_connection");
+ const revision = routes.snapshot().revision;
+ expect(
+ routes.invalidateEdge({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ parentSessionId: "host_session",
+ routeRevision: revision,
+ connectionId: "old_connection",
+ }),
+ ).toBe(true);
+
+ routes.reconcile(100);
+ const prepared = beginCandidate(routes, {
+ nowMs: 101,
+ connectionId: "new_connection",
+ reservation: { kind: "direct" },
+ }).operation!;
+ expect(routes.snapshot().upstreamByViewer.get(A)?.connectionId).toBe(
+ "old_connection",
+ );
+ expect(
+ routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: prepared.current!.revision - 1,
+ connectionId: "new_connection",
+ }, 102).accepted,
+ ).toBe(false);
+ expect(
+ routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: prepared.current!.revision,
+ connectionId: "new_connection",
+ }, 102),
+ ).toMatchObject({ accepted: true });
+ expect(routes.snapshot().upstreamByViewer.get(A)).toMatchObject({
+ connectionId: "new_connection",
+ parentPeerId: B,
+ usable: true,
+ });
+ });
+
+ it("advances one candidate cursor without resetting the operation deadline", () => {
+ const routes = controller(2, {
+ selectedTurnEnabled: true,
+ sfuEnabled: true,
+ });
+ addViewer(routes, A, 2);
+ const operation = routes.reconcile(1_000).operation!;
+ const deadline = operation.deadlineAtMs;
+ const first = beginCandidate(routes, {
+ nowMs: 1_001,
+ connectionId: "candidate_1",
+ reservation: { kind: "direct" },
+ }).operation!;
+ const failed = routes.candidateFailed({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: first.current!.revision,
+ connectionId: "candidate_1",
+ }, 1_001);
+ expect(failed.accepted).toBe(true);
+ expect(failed.exhausted).toBeUndefined();
+ expect(failed.released).toEqual([]);
+ expect(routes.snapshot().operation).toMatchObject({
+ cursor: 1,
+ deadlineAtMs: deadline,
+ });
+
+ const second = beginCandidate(routes, {
+ nowMs: 1_002,
+ connectionId: "candidate_2",
+ publicationGeneration: "publication_2",
+ publicationConnectionId: "publication_connection_2",
+ reservation: {
+ kind: "sfu-create",
+ edge: "candidate_2_edge",
+ publication: "candidate_2_publication",
+ },
+ }).operation!;
+ const lateReady = routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: second.current!.revision,
+ connectionId: "candidate_2",
+ }, deadline);
+ expect(lateReady).toMatchObject({ accepted: false, exhausted: true });
+ expect(lateReady.released).toEqual([
+ "candidate_2_edge",
+ "candidate_2_publication",
+ ]);
+ expect(routes.snapshot().operation).toBeUndefined();
+ expect(
+ routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: second.current!.revision,
+ connectionId: "candidate_2",
+ }, deadline + 1).accepted,
+ ).toBe(false);
+ expect(routes.reconcile(deadline + 1).operation).toBeUndefined();
+ routes.touchExternalFacts();
+ expect(routes.reconcile(deadline + 2).operation?.childPeerId).toBe(A);
+
+ const overlap = controller(2, { selectedTurnEnabled: true });
+ addViewer(overlap, A, 1);
+ addViewer(overlap, B, 0);
+ overlap.hydrateEdge(A, peerEdge(HOST, "a_parent"));
+ overlap.hydrateEdge(B, peerEdge(A, "b_direct"));
+ expect(overlap.invalidateEdge({
+ childPeerId: B,
+ childSessionId: `${B}_session`,
+ parentSessionId: `${A}_session`,
+ routeRevision: 0,
+ connectionId: "b_direct",
+ })).toBe(true);
+ overlap.reconcile(0);
+ const hostAttempt = beginCandidate(overlap, {
+ nowMs: 1,
+ connectionId: "b_host",
+ reservation: { kind: "direct" },
+ }).operation!;
+ overlap.candidateFailed({
+ childPeerId: B,
+ childSessionId: `${B}_session`,
+ revision: hostAttempt.current!.revision,
+ connectionId: "b_host",
+ }, 2);
+ expect(() => beginCandidate(overlap, {
+ nowMs: 3,
+ connectionId: "b_turn",
+ reservation: { kind: "selected-turn", edge: "turn_edge" },
+ })).toThrow("endpoint overlap reservation");
+ beginCandidate(overlap, {
+ nowMs: 3,
+ connectionId: "b_turn",
+ reservation: {
+ kind: "selected-turn",
+ edge: "turn_edge",
+ overlap: "overlap_slot",
+ },
+ });
+ overlap.setEffectiveCapacity(A, `${A}_session`, 0);
+ expect(overlap.reconcile(4).released).toEqual([
+ "turn_edge",
+ "overlap_slot",
+ ]);
+ });
+
+ it("retains another exact failed edge while one child operation is busy", () => {
+ const routes = controller(3);
+ addViewer(routes, A, 1);
+ addViewer(routes, B, 1);
+ addViewer(routes, C, 1);
+ routes.hydrateEdge(A, peerEdge(HOST, "a_old"));
+ routes.hydrateEdge(B, peerEdge(HOST, "b_old"));
+ routes.hydrateEdge(C, peerEdge(HOST, "c_old"));
+ const revision = routes.snapshot().revision;
+ expect(
+ routes.invalidateEdge({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ parentSessionId: "host_session",
+ routeRevision: revision,
+ connectionId: "a_old",
+ }),
+ ).toBe(true);
+ routes.reconcile(0);
+ const current = beginCandidate(routes, {
+ nowMs: 1,
+ connectionId: "a_new",
+ reservation: { kind: "direct" },
+ }).operation!;
+ expect(
+ routes.invalidateEdge({
+ childPeerId: B,
+ childSessionId: `${B}_session`,
+ parentSessionId: "host_session",
+ routeRevision: revision,
+ connectionId: "b_old",
+ }),
+ ).toBe(true);
+ expect(
+ routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: current.current!.revision,
+ connectionId: "a_new",
+ }, 2).accepted,
+ ).toBe(false);
+ const replacement = beginCandidate(routes, {
+ nowMs: 2,
+ connectionId: "a_new_2",
+ reservation: { kind: "direct" },
+ }).operation!;
+ expect(
+ routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: replacement.current!.revision,
+ connectionId: "a_new_2",
+ }, 3).accepted,
+ ).toBe(true);
+ expect(routes.reconcile(3).operation?.childPeerId).toBe(B);
+ });
+
+ it("keeps grace media, then reparents a confirmed relay departure", () => {
+ const routes = controller(2);
+ addViewer(routes, A, 2);
+ addViewer(routes, B, 1);
+ addViewer(routes, C, 0);
+ routes.hydrateEdge(A, peerEdge(HOST, "a_connection"));
+ routes.hydrateEdge(B, peerEdge(A, "b_connection"));
+ routes.hydrateEdge(C, peerEdge(B, "c_connection"));
+
+ expect(routes.disconnectSession(A, `${A}_session`)).toBe(true);
+ expect(routes.reconcile(0).operation).toBeUndefined();
+ expect(routes.confirmDeparture(A)).toBe(true);
+ expect(routes.reconcile(1).operation?.childPeerId).toBe(B);
+ commitCurrent(routes, 2, "b_reparented");
+ const beforePrune = routes.snapshot().revision;
+ const after = routes.reconcile(3);
+ expect(after.removedPeerIds).toContain(A);
+ expect(routes.snapshot().revision).toBeGreaterThan(beforePrune);
+ expect(routes.snapshot().upstreamByViewer.get(C)).toMatchObject({
+ parentPeerId: B,
+ connectionId: "c_connection",
+ });
+ });
+
+ it("moves newest overflow children and supports effective capacity zero", () => {
+ const routes = controller(3);
+ addViewer(routes, A, 3);
+ routes.hydrateEdge(A, peerEdge(HOST, "a_connection"));
+ for (const peerId of [B, C, D]) {
+ addViewer(routes, peerId, 0);
+ routes.hydrateEdge(peerId, peerEdge(A, `${peerId}_connection`));
+ }
+ expect(routes.setEffectiveCapacity(A, `${A}_session`, 1)).toBe(true);
+ expect(routes.reconcile(0).operation?.childPeerId).toBe(D);
+ expect(routes.setPaused(true)).toEqual([]);
+ expect(routes.setEffectiveCapacity(A, `${A}_session`, 0)).toBe(true);
+ expect(routes.setPaused(false)).toEqual([]);
+ expect(routes.reconcile(1).operation?.childPeerId).toBe(D);
+
+ const blocked = controller(1);
+ addViewer(blocked, A, 0);
+ addViewer(blocked, B, 0);
+ blocked.hydrateEdge(A, peerEdge(HOST, "blocked_a"));
+ blocked.hydrateEdge(B, peerEdge(A, "blocked_b"));
+ expect(blocked.reconcile(0).operation).toBeUndefined();
+ expect(blocked.reconcile(1).operation).toBeUndefined();
+ });
+
+ it("uses an SFU-fed endpoint as an ordinary parent and aborts pause resources", () => {
+ const routes = controller(1, { sfuEnabled: true });
+ addViewer(routes, A, 1);
+ addViewer(routes, B, 0);
+ routes.hydrateHostPublication("publication_1", "publication_resource");
+ routes.hydrateEdge(A, {
+ kind: "sfu",
+ publicationGeneration: "publication_1",
+ transport: "sfu",
+ connectionId: "a_sfu",
+ usable: true,
+ physicalActive: true,
+ resource: "a_subscription",
+ });
+ const operation = routes.reconcile(0).operation!;
+ expect(operation.candidates[0]?.tuple).toEqual({
+ kind: "peer",
+ parentPeerId: A,
+ transport: "direct",
+ });
+ beginCandidate(routes, {
+ nowMs: 1,
+ connectionId: "b_candidate",
+ reservation: { kind: "direct" },
+ });
+ expect(routes.setPaused(true)).toEqual([]);
+ expect(routes.snapshot().operation).toBeUndefined();
+ expect(routes.snapshot().upstreamByViewer.get(A)?.connectionId).toBe("a_sfu");
+ routes.setPaused(false);
+ expect(routes.invalidateHostPublication({
+ hostSessionId: "host_session",
+ routeRevision: routes.snapshot().revision,
+ generation: "publication_1",
+ connectionId: "publication:publication_1",
+ })).toBe(true);
+ const repair = routes.reconcile(2).operation!;
+ expect(repair.childPeerId).toBe(A);
+ expect(repair.candidates[0]?.tuple).toEqual({
+ kind: "peer",
+ parentPeerId: HOST,
+ transport: "direct",
+ });
+ skipCandidate(routes, 3);
+ expect(routes.snapshot().operation?.candidates[1]?.tuple).toEqual({
+ kind: "sfu",
+ publication: "replace",
+ ingress: "direct",
+ });
+ expect(() => beginCandidate(routes, {
+ nowMs: 3,
+ connectionId: "a_sfu_2",
+ publicationGeneration: "publication_2",
+ publicationConnectionId: "publication_connection_2",
+ reservation: {
+ kind: "sfu-create",
+ edge: "a_subscription_2",
+ publication: "publication_resource_2",
+ },
+ })).toThrow("endpoint overlap reservation");
+ const publicationRepair = beginCandidate(routes, {
+ nowMs: 3,
+ connectionId: "a_sfu_2",
+ publicationGeneration: "publication_2",
+ publicationConnectionId: "publication_connection_2",
+ reservation: {
+ kind: "sfu-create",
+ edge: "a_subscription_2",
+ publication: "publication_resource_2",
+ overlap: "publication_overlap",
+ },
+ }).operation!;
+ const repaired = routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: publicationRepair.current!.revision,
+ connectionId: "a_sfu_2",
+ }, 4);
+ expect(repaired.accepted).toBe(true);
+ expect(repaired.released).toEqual([
+ "publication_overlap",
+ "a_subscription",
+ "publication_resource",
+ ]);
+ expect(routes.snapshot().hostPublication).toMatchObject({
+ generation: "publication_2",
+ usable: true,
+ physicalActive: true,
+ });
+
+ const bootstrap = controller(1, { sfuEnabled: true });
+ addViewer(bootstrap, A, 0);
+ addViewer(bootstrap, B, 0);
+ bootstrap.hydrateEdge(A, peerEdge(HOST, "bootstrap_a"));
+ const bootstrapOperation = bootstrap.reconcile(0).operation!;
+ expect(bootstrapOperation.childPeerId).toBe(A);
+ expect(bootstrapOperation.candidates[0]?.tuple).toEqual({
+ kind: "sfu",
+ publication: "create",
+ ingress: "direct",
+ });
+ expect(() => beginCandidate(bootstrap, {
+ nowMs: 2,
+ connectionId: "bootstrap_sfu",
+ publicationGeneration: "bootstrap_publication",
+ publicationConnectionId: "bootstrap_ingress_connection",
+ reservation: {
+ kind: "sfu-create",
+ edge: "bootstrap_subscription",
+ publication: "bootstrap_ingress",
+ },
+ })).toThrow("endpoint overlap reservation");
+ const preparedBootstrap = beginCandidate(bootstrap, {
+ nowMs: 2,
+ connectionId: "bootstrap_sfu",
+ publicationGeneration: "bootstrap_publication",
+ publicationConnectionId: "bootstrap_ingress_connection",
+ reservation: {
+ kind: "sfu-create",
+ edge: "bootstrap_subscription",
+ publication: "bootstrap_ingress",
+ overlap: "bootstrap_overlap",
+ },
+ }).operation!;
+ expect(bootstrap.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: preparedBootstrap.current!.revision,
+ connectionId: "bootstrap_sfu",
+ }, 3).accepted).toBe(true);
+ expect(bootstrap.reconcile(4).operation?.childPeerId).toBe(B);
+ });
+
+ it("binds reserve and skip results to the exact candidate cursor", () => {
+ const reserve = controller(2);
+ addViewer(reserve, A, 2);
+ reserve.hydrateEdge(A, peerEdge(HOST, "a_active"));
+ addViewer(reserve, B, 0);
+ const first = reserve.reconcile(0).operation!;
+ expect(first.candidates[0]?.tuple).toMatchObject({
+ kind: "peer",
+ parentPeerId: HOST,
+ });
+ reserve.setEffectiveCapacity(HOST, "host_session", 0);
+ const staleReserve = reserve.beginCurrentCandidate({
+ guard: cursorGuard(first),
+ nowMs: 1,
+ connectionId: "reserved_for_old_cursor",
+ reservation: { kind: "direct", overlap: "stale_reservation" },
+ });
+ expect(staleReserve).toMatchObject({ accepted: false });
+ expect(staleReserve.released).toEqual(["stale_reservation"]);
+ expect(reserve.snapshot().operation).toMatchObject({ cursor: 1 });
+ expect(reserve.snapshot().operation?.current).toBeUndefined();
+
+ const skip = controller(2);
+ addViewer(skip, A, 2);
+ skip.hydrateEdge(A, peerEdge(HOST, "a_active"));
+ addViewer(skip, B, 0);
+ const staleCursor = skip.reconcile(0).operation!;
+ skip.setEffectiveCapacity(HOST, "host_session", 0);
+ expect(skip.skipCurrentCandidate(cursorGuard(staleCursor), 1).accepted).toBe(false);
+ expect(skip.snapshot().operation).toMatchObject({ cursor: 1 });
+ expect(skip.snapshot().operation?.candidates[1]?.tuple).toMatchObject({
+ kind: "peer",
+ parentPeerId: A,
+ });
+ });
+
+ it("replaces one publication and makes every old subscriber waiting", () => {
+ const routes = controller(1, { sfuEnabled: true });
+ addViewer(routes, A, 0);
+ addViewer(routes, B, 0);
+ routes.hydrateHostPublication("publication_1", "publication_resource_1");
+ for (const [peerId, resource] of [[A, "subscription_a"], [B, "subscription_b"]] as const) {
+ routes.hydrateEdge(peerId, {
+ kind: "sfu",
+ publicationGeneration: "publication_1",
+ transport: "sfu",
+ connectionId: `${peerId}_sfu_1`,
+ usable: true,
+ physicalActive: true,
+ resource,
+ });
+ }
+ expect(routes.invalidateHostPublication({
+ hostSessionId: "host_session",
+ routeRevision: 0,
+ generation: "publication_1",
+ connectionId: "publication:publication_1",
+ })).toBe(true);
+ const operation = routes.reconcile(0).operation!;
+ expect(operation.candidates[0]).toMatchObject({
+ tuple: { kind: "sfu", publication: "replace", ingress: "direct" },
+ endpointTransition: { kind: "overlap", producerPeerId: HOST },
+ });
+ const prepared = beginCandidate(routes, {
+ nowMs: 1,
+ connectionId: "a_sfu_2",
+ publicationGeneration: "publication_2",
+ publicationConnectionId: "publication_connection_2",
+ reservation: {
+ kind: "sfu-create",
+ edge: "subscription_a_2",
+ publication: "publication_resource_2",
+ overlap: "publication_overlap",
+ },
+ }).operation!;
+ const settled = routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: prepared.current!.revision,
+ connectionId: "a_sfu_2",
+ }, 2);
+ expect(settled.accepted).toBe(true);
+ expect(settled.released).toEqual([
+ "publication_overlap",
+ "subscription_a",
+ "subscription_b",
+ "publication_resource_1",
+ ]);
+ expect(routes.snapshot().upstreamByViewer.get(A)).toMatchObject({
+ publicationGeneration: "publication_2",
+ });
+ expect(routes.snapshot().upstreamByViewer.has(B)).toBe(false);
+ expect(routes.reconcile(3).operation?.childPeerId).toBe(B);
+ });
+
+ it("releases session-bound transports while rebinding direct media", () => {
+ const peerRoutes = controller(2);
+ addViewer(peerRoutes, A, 1);
+ addViewer(peerRoutes, B, 0);
+ peerRoutes.hydrateEdge(A, {
+ kind: "peer",
+ parentPeerId: HOST,
+ transport: "selected-turn",
+ connectionId: "a_selected",
+ usable: true,
+ physicalActive: true,
+ resource: "a_turn_allocation",
+ });
+ peerRoutes.hydrateEdge(B, peerEdge(HOST, "b_direct"));
+ expect(peerRoutes.upsertParticipant({
+ peerId: A,
+ role: "viewer",
+ sessionId: "a_replacement",
+ effectiveDownstreamCapacity: 1,
+ })).toEqual(["a_turn_allocation"]);
+ expect(peerRoutes.snapshot().upstreamByViewer.get(A)).toMatchObject({
+ childSessionId: `${A}_session`,
+ usable: false,
+ physicalActive: false,
+ });
+ expect(peerRoutes.upsertParticipant({
+ peerId: B,
+ role: "viewer",
+ sessionId: "b_replacement",
+ effectiveDownstreamCapacity: 0,
+ })).toEqual([]);
+ expect(peerRoutes.snapshot().upstreamByViewer.get(B)).toMatchObject({
+ childSessionId: "b_replacement",
+ usable: true,
+ physicalActive: true,
+ });
+
+ const sfuRoutes = controller(1, { sfuEnabled: true });
+ addViewer(sfuRoutes, A, 0);
+ sfuRoutes.hydrateHostPublication(
+ "selected_publication",
+ "selected_ingress_resource",
+ "selected_ingress_connection",
+ "selected-turn",
+ );
+ sfuRoutes.hydrateEdge(A, {
+ kind: "sfu",
+ publicationGeneration: "selected_publication",
+ transport: "sfu",
+ connectionId: "subscription_connection",
+ usable: true,
+ physicalActive: true,
+ resource: "subscription_resource",
+ });
+ expect(sfuRoutes.upsertParticipant({
+ peerId: HOST,
+ role: "host",
+ sessionId: "host_replacement",
+ effectiveDownstreamCapacity: 1,
+ })).toEqual(["selected_ingress_resource"]);
+ expect(sfuRoutes.snapshot().hostPublication).toMatchObject({
+ hostSessionId: "host_session",
+ ingress: "selected-turn",
+ usable: false,
+ physicalActive: false,
+ });
+ expect(sfuRoutes.upsertParticipant({
+ peerId: A,
+ role: "viewer",
+ sessionId: "a_replacement",
+ effectiveDownstreamCapacity: 0,
+ })).toEqual([]);
+ expect(sfuRoutes.snapshot().upstreamByViewer.get(A)).toMatchObject({
+ childSessionId: "a_replacement",
+ physicalActive: true,
+ });
+ });
+
+ it("does not reopen an exhausted bootstrap without a new fact", () => {
+ const routes = controller(1, { sfuEnabled: true });
+ addViewer(routes, A, 0);
+ routes.hydrateEdge(A, peerEdge(HOST, "failed_direct"));
+ expect(routes.invalidateEdge({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ parentSessionId: "host_session",
+ routeRevision: 0,
+ connectionId: "failed_direct",
+ })).toBe(true);
+ const operation = routes.reconcile(0).operation!;
+ const prepared = beginCandidate(routes, {
+ nowMs: 1,
+ connectionId: "failed_sfu",
+ publicationGeneration: "failed_publication",
+ publicationConnectionId: "failed_publication_connection",
+ reservation: {
+ kind: "sfu-create",
+ edge: "failed_subscription_resource",
+ publication: "failed_publication_resource",
+ overlap: "failed_overlap",
+ },
+ }).operation!;
+ expect(routes.candidateFailed({
+ childPeerId: operation.childPeerId,
+ childSessionId: operation.childSessionId,
+ revision: prepared.current!.revision,
+ connectionId: "failed_sfu",
+ }, 2)).toMatchObject({ accepted: true, exhausted: true });
+ const factVersion = routes.snapshot().factVersion;
+ expect(routes.reconcile(3).operation).toBeUndefined();
+ expect(routes.setEffectiveCapacity(A, `${A}_session`, 0)).toBe(true);
+ expect(routes.snapshot().factVersion).toBe(factVersion);
+ expect(routes.reconcile(4).operation).toBeUndefined();
+ expect(routes.invalidateEdge({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ parentSessionId: "host_session",
+ routeRevision: routes.snapshot().revision,
+ connectionId: "failed_direct",
+ })).toBe(true);
+ expect(routes.snapshot().factVersion).toBe(factVersion);
+ expect(routes.reconcile(5).operation).toBeUndefined();
+ });
+
+ it.each([1, 2] as const)(
+ "requires one overlap slot for an SFU-to-Host transition at C=%i",
+ (capacity) => {
+ const routes = controller(capacity, { sfuEnabled: true });
+ addViewer(routes, A, 0);
+ if (capacity === 2) {
+ addViewer(routes, E, 0);
+ routes.hydrateEdge(E, peerEdge(HOST, "e_direct"));
+ }
+ routes.hydrateHostPublication("publication_1", "publication_resource_1");
+ routes.hydrateEdge(A, {
+ kind: "sfu",
+ publicationGeneration: "publication_1",
+ transport: "sfu",
+ connectionId: "a_sfu",
+ usable: true,
+ physicalActive: true,
+ resource: "a_subscription",
+ });
+ routes.invalidateEdge({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ routeRevision: 0,
+ connectionId: "a_sfu",
+ });
+ const operation = routes.reconcile(0).operation!;
+ expect(operation.candidates[0]).toMatchObject({
+ tuple: { kind: "peer", parentPeerId: HOST, transport: "direct" },
+ endpointTransition: { kind: "overlap", producerPeerId: HOST },
+ });
+ expect(() => beginCandidate(routes, {
+ nowMs: 1,
+ connectionId: "a_host_direct",
+ reservation: { kind: "direct" },
+ })).toThrow("endpoint overlap reservation");
+ },
+ );
+
+ it("uses one bounded gap instead of a fourth Host copy at C=3", () => {
+ const routes = controller(3, { sfuEnabled: true });
+ addViewer(routes, A, 0);
+ for (const peerId of [E, F]) {
+ addViewer(routes, peerId, 0);
+ routes.hydrateEdge(peerId, peerEdge(HOST, `${peerId}_direct`));
+ }
+ routes.hydrateHostPublication("publication_1", "publication_resource_1");
+ routes.hydrateEdge(A, {
+ kind: "sfu",
+ publicationGeneration: "publication_1",
+ transport: "sfu",
+ connectionId: "a_sfu",
+ usable: true,
+ physicalActive: true,
+ resource: "a_subscription",
+ });
+ routes.invalidateEdge({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ routeRevision: 0,
+ connectionId: "a_sfu",
+ });
+ const operation = routes.reconcile(10).operation!;
+ const deadline = operation.deadlineAtMs;
+ expect(operation.candidates[0]).toMatchObject({
+ tuple: { kind: "peer", parentPeerId: HOST, transport: "direct" },
+ endpointTransition: {
+ kind: "bounded-gap",
+ producerPeerId: HOST,
+ retire: { kind: "publication", generation: "publication_1" },
+ },
+ });
+ const gap = routes.retireCurrentCandidateProducer(cursorGuard(operation), 11);
+ expect(gap).toMatchObject({ accepted: true });
+ expect(gap.released).toEqual(["a_subscription", "publication_resource_1"]);
+ expect(gap.operation).toMatchObject({
+ deadlineAtMs: deadline,
+ candidates: [{ endpointTransition: { kind: "none", producerPeerId: HOST } }],
+ });
+ const prepared = beginCandidate(routes, {
+ nowMs: 12,
+ connectionId: "a_host_direct",
+ reservation: { kind: "direct" },
+ }).operation!;
+ expect(routes.candidateReady({
+ childPeerId: A,
+ childSessionId: `${A}_session`,
+ revision: prepared.current!.revision,
+ connectionId: "a_host_direct",
+ }, 13).accepted).toBe(true);
+ expect(routes.snapshot().hostPublication).toBeNull();
+ });
+
+ it("retires one exact peer edge for a C=3 bounded gap", () => {
+ const routes = controller(3, { selectedTurnEnabled: true });
+ addViewer(routes, A, 3);
+ routes.hydrateEdge(A, peerEdge(HOST, "a_direct"));
+ for (const peerId of [B, C, D]) {
+ addViewer(routes, peerId, 0);
+ routes.hydrateEdge(peerId, peerEdge(A, `${peerId}_from_a`));
+ }
+ routes.invalidateEdge({
+ childPeerId: B,
+ childSessionId: `${B}_session`,
+ parentSessionId: `${A}_session`,
+ routeRevision: 0,
+ connectionId: `${B}_from_a`,
+ });
+ const first = routes.reconcile(0).operation!;
+ expect(first.candidates[0]?.tuple).toMatchObject({
+ kind: "peer",
+ parentPeerId: HOST,
+ transport: "direct",
+ });
+ expect(skipCandidate(routes, 1).accepted).toBe(true);
+ const bounded = routes.snapshot().operation!;
+ expect(bounded.candidates[bounded.cursor]).toMatchObject({
+ tuple: { kind: "peer", parentPeerId: A, transport: "selected-turn" },
+ endpointTransition: {
+ kind: "bounded-gap",
+ producerPeerId: A,
+ retire: { kind: "edge", childPeerId: B, connectionId: `${B}_from_a` },
+ },
+ });
+ const gap = routes.retireCurrentCandidateProducer(cursorGuard(bounded), 2);
+ expect(gap).toMatchObject({ accepted: true, released: [] });
+ const prepared = beginCandidate(routes, {
+ nowMs: 3,
+ connectionId: "b_selected_turn",
+ reservation: { kind: "selected-turn", edge: "b_turn_resource" },
+ }).operation!;
+ expect(routes.candidateReady({
+ childPeerId: B,
+ childSessionId: `${B}_session`,
+ revision: prepared.current!.revision,
+ connectionId: "b_selected_turn",
+ }, 4).accepted).toBe(true);
+ expect(routes.snapshot().upstreamByViewer.get(B)).toMatchObject({
+ parentPeerId: A,
+ transport: "selected-turn",
+ resource: "b_turn_resource",
+ });
+ });
+});