Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
import { afterEach, expect, it, vi } from "vitest";
import type { SignalPayload } from "../src/shared/protocol";
import type { NativeClient } from "../src/client/native/client";
import { NativeMediaBridge } from "../src/client/native/media-bridge";
import { VIEWER_AUTOMATIC_RECOVERY_TIMEOUT_MS, ViewerPeer } from "../src/client/webrtc/viewer-peer";
import { EMPTY_METRICS, type PeerSnapshot } from "../src/client/types";
import type { NativeClientEvent } from "../src/client/native/wire";
import {
NativeCapableViewerPeer,
offerHasNativeVideoCodec,
} from "../src/client/native/native-viewer-peer";
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
vi.unstubAllGlobals();
});
it.each(["commit", "expired", "rpc-expired"].flatMap(outcome =>
[undefined, 20].map(maxRelayChildren => ({ outcome, maxRelayChildren })),
))("scopes optional connection preparation to its route: $outcome, backend capacity $maxRelayChildren", async ({ outcome, maxRelayChildren }) => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
const client = {
health: { nativeMedia: { maxRelayChildren } },
preparePunch: vi.fn(async () => ({ address: "198.51.100.1", port: 40000, step: 1 })),
runPunch: vi.fn(async () => true), closePunch: vi.fn(async () => undefined),
receiveOffer: vi.fn(async () => ({ answer: { type: "answer", sdp: "answer" }, audio: false, codec: "vp8" })),
onEvent: () => () => {}, onClose: () => () => {},
closeReceiver: vi.fn(async () => {}), closeEdge: vi.fn(async () => {}),
} as unknown as NativeClient;
const unavailable = vi.fn(), exhausted = vi.fn(() => true), sent = vi.fn(() => true);
const peer = new NativeCapableViewerPeer({
iceServers: [{ urls: ["stun:site.example:3478"] }],
natPredictionStunUrls: ["stun:site.example:3479", "stun:site.example:3480"],
}, { sendSignal: sent, sendRestartRequest: () => true, onStream: () => {}, onUpdate: () => {}, onRecoveryExhausted: exhausted },
{ natPredictionEnabled: true, recoveryOwner: "route" }, async () => client, unavailable, "session", 20);
// The page accepts a failure only while this peer owns that connection.
exhausted.mockImplementation(() => peer.hasConnectionId("current"));
const prepare: SignalPayload = { kind: "punch", connectionId: "current", punch: { phase: "prepare", secret: "42".repeat(32) } };
try {
await peer.acceptSignal("parent", prepare);
await vi.advanceTimersByTimeAsync(0);
expect(client.preparePunch).toHaveBeenCalledWith("session", "current", expect.anything(), expect.any(String), maxRelayChildren ?? 3);
await peer.acceptSignal("parent", { kind: "punch", connectionId: "current", punch: {
phase: "start", prediction: { address: "198.51.100.2", port: 50000, step: 1 },
} });
await vi.advanceTimersByTimeAsync(0);
if (outcome === "expired") await vi.advanceTimersByTimeAsync(3_500);
if (outcome === "rpc-expired") vi.mocked(client.receiveOffer).mockRejectedValueOnce(new Error("prepared socket expired"));
await peer.acceptSignal("parent", {
kind: "description", connectionId: "current", punched: true,
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
expect(unavailable).not.toHaveBeenCalled();
if (outcome === "commit") {
expect(exhausted).not.toHaveBeenCalled();
expect(client.receiveOffer).toHaveBeenCalledWith("session", "current", expect.anything(), expect.anything(), maxRelayChildren ?? 3, true);
await peer.acceptSignal("parent", prepare);
expect(client.preparePunch).toHaveBeenCalledOnce();
} else {
expect(exhausted).toHaveBeenCalledExactlyOnceWith("parent", "current");
expect(exhausted.mock.results[0].value).toBe(true);
if (outcome === "expired") expect(client.receiveOffer).not.toHaveBeenCalled();
}
} finally { peer.dispose(); }
});
it("uses the offer's STUN destinations for prediction while the next ICE config changes", async () => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
let onEvent!: (event: NativeClientEvent) => void;
const client = {
receiveOffer: vi.fn(async () => ({ answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8" })),
onEvent: (handler: typeof onEvent) => { onEvent = handler; return () => {}; },
onClose: () => () => {},
closeReceiver: vi.fn(async () => {}), closeEdge: vi.fn(async () => {}),
} as unknown as NativeClient;
const original = {
iceServers: [{ urls: ["stun:site.example:3478", "stun:other.example:3478"] }],
natPredictionStunUrls: ["stun:site.example:3479", "stun:site.example:3480"],
};
const sent: SignalPayload[] = [];
const peer = new NativeCapableViewerPeer(original, {
sendSignal: (_parent, payload) => { sent.push(payload); return true; },
sendRestartRequest: () => true, onStream: () => {}, onUpdate: () => {},
}, { natPredictionEnabled: true }, async () => client, () => {}, "session", 2);
const emit = (index: number, port: number) => onEvent({
version: 10, type: "edge-candidate", shareId: "session", connectionId: "current",
candidate: { candidate: `candidate:ns${index} 1 udp 1 203.0.113.7 ${port} typ srflx` },
});
const candidates = () => sent.flatMap(payload => payload.kind === "candidate" ? [payload.candidate] : []);
try {
await peer.acceptSignal("parent", {
kind: "description", connectionId: "current",
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
peer.updateIceConfig({
...original, iceServers: [{ urls: ["stun:other.example:3478", "stun:site.example:3478"] }],
});
emit(3, 40006);
emit(2, 40003); // Ordinary extra destination must not complete a predicted sequence.
emit(1, 40000);
expect(candidates()).toHaveLength(3);
emit(4, 40012);
expect(candidates()).toHaveLength(12); // Four ordinary candidates plus the bounded eight predictions.
} finally {
peer.dispose();
}
});
it.each([false, true])("keeps restarted Native candidates after a delayed previous gathering end (prediction=%s)", async (prediction) => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
let event!: (event: NativeClientEvent) => void;
const result = { answer: { type: "answer" as const, sdp: "answer" }, audio: false, codec: "vp8" as const, reused: true };
const receiveOffer = vi.fn(async () => result);
const client = {
health: { nativeMedia: { receiverReuse: true } }, receiveOffer,
onEvent: (listener: typeof event) => { event = listener; return () => {}; },
onClose: () => () => {}, closeReceiver: vi.fn(async () => {}), closeEdge: vi.fn(async () => {}),
} as unknown as NativeClient;
const sent: SignalPayload[] = [];
const peer = new NativeCapableViewerPeer({
iceServers: [{ urls: "stun:site.example:3478" }],
natPredictionStunUrls: ["stun:site.example:3479", "stun:site.example:3480"],
}, {
sendSignal: (_parent, payload) => { sent.push(payload); return true; },
sendRestartRequest: () => true, onStream: () => {}, onUpdate: () => {},
}, { natPredictionEnabled: prediction }, async () => client, () => {}, "session", 2);
const offer = (fragment: string): SignalPayload => ({
kind: "description", connectionId: "current", description: { type: "offer",
sdp: `v=0\r\na=ice-ufrag:${fragment}\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n` },
});
const emit = (candidate: Extract<NativeClientEvent, { type: "edge-candidate" }>["candidate"]) =>
event({ version: 10, type: "edge-candidate", shareId: "session", connectionId: "current", candidate });
try {
await peer.acceptSignal("parent", offer("first"));
emit({ candidate: "candidate:ns1 1 udp 1 203.0.113.7 40000 typ srflx", usernameFragment: "previous" });
let finish!: () => void;
receiveOffer.mockImplementationOnce(() => new Promise(resolve => { finish = () => resolve(result); }));
const restarting = peer.acceptSignal("parent", offer("restarted"));
await vi.waitFor(() => expect(receiveOffer).toHaveBeenCalledTimes(2));
// The room WS delivered the new offer before an old event already written
// by the independent App WS. The same physical receiver survives restart.
emit(null);
for (let index = 1; index <= 3; index++) {
emit({ candidate: `candidate:ns${index} 1 udp 1 203.0.113.7 ${50000 + index * 3} typ srflx`, usernameFragment: "next" });
}
finish();
await restarting;
const candidates = sent.flatMap(payload => payload.kind === "candidate" ? [payload.candidate] : []);
expect(candidates.filter(candidate => candidate?.candidate && candidate.usernameFragment === "next")).toHaveLength(prediction ? 11 : 3);
expect(candidates.find(candidate => candidate?.candidate === "")).toMatchObject({ usernameFragment: "previous" });
expect(candidates).not.toContain(null);
} finally { peer.dispose(); }
});
it("retires queued candidates when disposed during their delivery", async () => {
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
let finishCandidate!: () => void;
const accept = vi.spyOn(ViewerPeer.prototype, "acceptSignal").mockImplementation(
async (_parent, payload) => {
if (payload.kind === "candidate") {
await new Promise<void>(resolve => { finishCandidate = resolve; });
}
},
);
const peer = new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal: () => true, sendRestartRequest: () => true,
onStream: () => undefined, onUpdate: () => undefined,
},
{}, async () => null, () => undefined, "session", 2,
);
try {
for (const port of [5000, 5001]) {
await peer.acceptSignal("parent", {
kind: "candidate", connectionId: "current",
candidate: { candidate: `candidate:1 1 UDP 2122260223 192.0.2.1 ${port} typ host` },
});
}
const accepting = peer.acceptSignal("parent", {
kind: "description", connectionId: "current",
description: { type: "offer", sdp: "v=0\r\n" },
});
await vi.waitFor(() => expect(accept).toHaveBeenCalledTimes(2));
peer.dispose();
finishCandidate();
await expect(accepting).resolves.toBeUndefined();
expect(accept).toHaveBeenCalledTimes(2);
} finally {
peer.dispose();
}
});
it.each(["viewer", "route"] as const)("retires a connected Native receiver on control loss (%s)", async (recoveryOwner) => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
vi.spyOn(NativeMediaBridge.prototype, "collectMetrics").mockResolvedValue({ ...EMPTY_METRICS });
vi.spyOn(NativeMediaBridge.prototype, "decodedVideoFrames").mockResolvedValue(null);
let onEvent!: (event: NativeClientEvent) => void;
let onClose!: () => void;
const client = {
receiveOffer: async () => ({
answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8",
}),
onEvent: (handler: typeof onEvent) => { onEvent = handler; return () => undefined; },
onClose: (handler: typeof onClose) => { onClose = handler; return () => undefined; },
closeReceiver: vi.fn(async () => undefined),
closeEdge: vi.fn(async () => undefined),
} as unknown as NativeClient;
const unavailable = vi.fn();
const restart = vi.fn(() => true);
const exhausted = vi.fn(() => true);
const updates: PeerSnapshot[] = [];
const peer = new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal: () => true, sendRestartRequest: restart,
onStream: () => undefined, onUpdate: (value) => updates.push(value),
onRecoveryExhausted: exhausted,
},
{ recoveryOwner }, async () => client, unavailable, "session", 2,
);
try {
await peer.acceptSignal("parent", {
kind: "description", connectionId: "current",
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
const connected = {
version: 10, shareId: "session", connectionId: "current", type: "edge-state", state: "connected",
} as const;
onEvent(connected);
expect(peer.isConnected()).toBe(true);
expect(peer.nativeSource).not.toBeNull();
onClose();
expect(peer.isConnected()).toBe(false);
expect(peer.nativeSource).toBeNull();
expect(updates.at(-1)?.connectionState).toBe("failed");
// A queued event cannot revive the receiver that owns the dead bridge.
onEvent(connected);
onClose();
expect(peer.isConnected()).toBe(false);
expect(unavailable).toHaveBeenCalledOnce();
if (recoveryOwner === "viewer") {
expect(restart).toHaveBeenCalledExactlyOnceWith("parent", "current", true);
expect(exhausted).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(VIEWER_AUTOMATIC_RECOVERY_TIMEOUT_MS);
} else {
expect(restart).not.toHaveBeenCalled();
}
expect(exhausted).toHaveBeenCalledExactlyOnceWith("parent", "current");
} finally {
peer.dispose();
}
});
it.each([false, true])("ignores a late Native offer after control loss (disposed=%s)", async (disposeOnFailure) => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
const bridgeStart = vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
let resolveOffer!: (value: Awaited<ReturnType<NativeClient["receiveOffer"]>>) => void;
const receiveOffer = vi.fn(() => new Promise<Awaited<ReturnType<NativeClient["receiveOffer"]>>>((resolve) => {
resolveOffer = resolve;
}));
let onClose!: () => void;
const closeReceiver = vi.fn(async () => undefined);
const client = {
receiveOffer,
onEvent: () => () => undefined,
onClose: (handler: typeof onClose) => { onClose = handler; return () => undefined; },
closeReceiver, closeEdge: vi.fn(async () => undefined),
} as unknown as NativeClient;
const sendSignal = vi.fn(() => true);
const onStream = vi.fn();
const restart = vi.fn(() => true);
const unavailable = vi.fn();
const updates: PeerSnapshot[] = [];
let peer!: NativeCapableViewerPeer;
peer = new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal, sendRestartRequest: restart, onStream,
onUpdate: (value) => {
updates.push(value);
if (disposeOnFailure && value.connectionState === "failed") peer.dispose();
},
},
{}, async () => client, unavailable, "session", 2,
);
try {
const accepting = peer.acceptSignal("parent", {
kind: "description", connectionId: "current",
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
await vi.waitFor(() => expect(receiveOffer).toHaveBeenCalledOnce());
onClose();
resolveOffer({ answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8", reused: false });
await accepting;
expect(updates.at(-1)?.connectionState).toBe("failed");
expect(peer.isConnected()).toBe(false);
expect(peer.nativeSource).toBeNull();
expect(closeReceiver).toHaveBeenCalledWith("session", "current");
expect(sendSignal).not.toHaveBeenCalled();
expect(onStream).not.toHaveBeenCalled();
expect(bridgeStart).not.toHaveBeenCalled();
expect(unavailable).toHaveBeenCalledOnce();
expect(restart).toHaveBeenCalledTimes(disposeOnFailure ? 0 : 1);
} finally {
peer.dispose();
}
});
it.each(["reused", "replaced", "answer-lost", "control-lost"])("keeps Native receiver lifetimes coherent through renegotiation (%s)", async (outcome) => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
const bridges: NativeMediaBridge[] = [];
const bridgeStart = vi.spyOn(NativeMediaBridge.prototype, "start").mockImplementation(async function (this: NativeMediaBridge) {
bridges.push(this);
return {} as MediaStream;
});
let closeControl!: () => void;
let event!: (event: NativeClientEvent) => void;
const receiveOffer = vi.fn(async () => ({
answer: { type: "answer" as const, sdp: "answer-sdp" }, audio: false, codec: "vp8" as const, reused: false,
}));
const closeReceiver = vi.fn(async () => undefined);
const closeEdge = vi.fn(async () => undefined);
const client = {
health: { nativeMedia: { receiverReuse: true } }, receiveOffer, closeReceiver, closeEdge,
onEvent: (listener: typeof event) => { event = listener; return () => {}; },
onClose: (listener: typeof closeControl) => { closeControl = listener; return () => {}; },
} as unknown as NativeClient;
const sendSignal = vi.fn(() => true);
const onStream = vi.fn();
const unavailable = vi.fn();
const peer = new NativeCapableViewerPeer({ iceServers: [] }, {
sendSignal, sendRestartRequest: () => true, onStream, onUpdate: () => {},
}, {}, async () => client, unavailable, "session", 2);
const offer = (ice: string): SignalPayload => ({
kind: "description", connectionId: "current", description: { type: "offer",
sdp: `v=0\r\na=ice-ufrag:${ice}\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n` },
});
try {
await peer.acceptSignal("parent", offer("first"));
event({ version: 10, type: "edge-state", shareId: "session", connectionId: "current", state: "connected" });
const source = peer.nativeSource;
receiveOffer.mockImplementationOnce(async () => {
if (outcome === "replaced") {
// Replacement closes the old local edge before its answer reaches JS.
(bridges[0] as unknown as { onFailed(): void }).onFailed();
}
if (outcome === "control-lost") closeControl();
return { answer: { type: "answer", sdp: "new-answer-sdp" }, audio: false, codec: "vp8", reused: outcome !== "replaced" };
});
if (outcome === "answer-lost") sendSignal.mockReturnValue(false);
await peer.acceptSignal("parent", offer("restarted"));
expect(receiveOffer).toHaveBeenCalledTimes(2);
if (outcome === "control-lost") {
expect(peer.nativeSource).toBeNull();
expect(unavailable).toHaveBeenCalledOnce();
} else {
expect(closeReceiver).not.toHaveBeenCalled();
expect(unavailable).not.toHaveBeenCalled();
expect(bridgeStart).toHaveBeenCalledTimes(outcome === "replaced" ? 2 : 1);
expect(onStream).toHaveBeenCalledTimes(outcome === "replaced" ? 2 : 1);
expect(peer.nativeSource?.generation).toBe(source!.generation + (outcome === "replaced" ? 1 : 0));
if (outcome !== "replaced") {
expect(closeEdge).not.toHaveBeenCalled();
expect(peer.isConnected()).toBe(true);
}
}
} finally { peer.dispose(); }
});
it("admits one active sending H264 or VP8 video section, not unrelated SDP codec text", () => {
const video = (codec: string, direction = "sendonly", port = 9, payload = 96) => [
`m=video ${port} UDP/TLS/RTP/SAVPF ${payload}`,
`a=${direction}`,
`a=rtpmap:96 ${codec}/90000`,
"a=fmtp:96 profile-level-id=42e01f;packetization-mode=1",
"",
].join("\r\n");
expect(offerHasNativeVideoCodec(video("H264"))).toBe(true);
expect(offerHasNativeVideoCodec(video("VP8"))).toBe(true);
expect(offerHasNativeVideoCodec(video("VP8", "sendrecv"))).toBe(true);
expect(offerHasNativeVideoCodec("a=group:BUNDLE 0\r\n" +
video("VP8", "sendonly", 0) + "a=bundle-only\r\na=mid:0\r\n")).toBe(true);
expect(offerHasNativeVideoCodec("m=video 9 UDP/TLS/RTP/SAVPF 96 97\r\n" +
"a=sendonly\r\na=rtpmap:96 H264/90000\r\na=rtpmap:97 VP8/90000\r\n")).toBe(true);
for (const offer of [
video("VP8", "recvonly"), video("VP8", "inactive"),
video("VP8", "sendonly", 0), video("VP8", "sendonly", 9, 97),
video("VP8", "sendonly", 0) + "a=bundle-only\r\na=mid:0\r\n",
video("VP9"), video("H264") + video("VP8"),
"m=audio 9 UDP/TLS/RTP/SAVPF 96\r\na=rtpmap:96 VP8/90000\r\n",
]) expect(offerHasNativeVideoCodec(offer)).toBe(false);
});
it.each([
["42e01f", "1", true], ["42c01f", "1", true],
["4de01f", "1", true], ["58c01f", "1", true],
["42e00b", "1", true], ["42e033", "1", true], ["42e034", "1", true],
["42e03c", "1", false],
["4d001f", "1", false], ["64001f", "1", false], ["42001f", "1", false],
["42e11f", "1", false], ["42e035", "1", false], ["42e03c", "1", false],
["42e01f=invalid", "1", false],
["", "1", false], ["42e01f", "0", false], ["42e01f", "", false],
])("matches Native H264 forwarding admission: profile=%s, packetization=%s", (profile, mode, supported) => {
const offer = "m=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\n" +
"a=rtpmap:96 H264/90000\r\n" +
`a=fmtp:96 profile-level-id=${profile};packetization-mode=${mode}\r\n`;
expect(offerHasNativeVideoCodec(offer)).toBe(supported);
});
it("sends an unsupported Native format straight to the Browser without failing the App", async () => {
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
const browserSignal = vi.spyOn(ViewerPeer.prototype, "acceptSignal").mockResolvedValue();
const acquire = vi.fn(async () => null);
const unavailable = vi.fn();
const restart = vi.fn(() => true);
const peer = new NativeCapableViewerPeer({ iceServers: [] }, {
sendSignal: () => true, sendRestartRequest: restart,
onStream: () => undefined, onUpdate: () => undefined,
}, {}, acquire, unavailable, "session", 2);
const offer: SignalPayload = { kind: "description", connectionId: "current", description: {
type: "offer", sdp: "m=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\n" +
"a=rtpmap:96 H264/90000\r\na=fmtp:96 profile-level-id=64001f;packetization-mode=1\r\n",
}};
try {
await peer.acceptSignal("parent", offer);
expect(browserSignal).toHaveBeenCalledExactlyOnceWith("parent", offer);
expect(acquire).not.toHaveBeenCalled();
expect(unavailable).not.toHaveBeenCalled();
expect(restart).not.toHaveBeenCalled();
} finally { peer.dispose(); }
});
it("does not create a browser backend after deferred native discovery is disposed", async () => {
let resolveClient: (value: null) => void = () => undefined;
const nativeClient = new Promise<null>((resolve) => {
resolveClient = resolve;
});
const peer = new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal: () => true,
sendRestartRequest: () => true,
onStream: () => undefined,
onUpdate: () => undefined,
},
{},
() => nativeClient,
() => undefined,
"session",
2,
);
const accepted = peer.acceptSignal("parent", {
kind: "description",
connectionId: "connection",
description: {
type: "offer",
sdp: [
"v=0",
"m=video 9 UDP/TLS/RTP/SAVPF 96",
"a=sendonly",
"a=rtpmap:96 H264/90000",
"",
].join("\r\n"),
},
});
peer.dispose();
resolveClient(null);
await accepted;
expect(peer.getConnectionIdentity()).toBeNull();
});
it.each(["route", "viewer"] as const)("recovers an answer signaling failure without disabling native (%s)", async (recoveryOwner) => {
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
const receiveOffer = vi.fn(async () => ({
answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8",
}));
const closeReceiver = vi.fn(async () => undefined);
const client = {
receiveOffer,
onEvent: () => () => undefined,
onClose: () => () => undefined,
closeReceiver,
closeEdge: vi.fn(async () => undefined),
} as unknown as NativeClient;
let available = true;
const acquire = vi.fn(async () => available ? client : null);
const unavailable = vi.fn(() => { available = false; });
const restart = vi.fn(() => true);
const exhausted = vi.fn(() => true);
let signalOnline = false;
const peer = new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal: () => signalOnline,
sendRestartRequest: restart,
onStream: () => undefined,
onUpdate: () => undefined,
onRecoveryExhausted: exhausted,
},
{ recoveryOwner },
acquire,
unavailable,
"session",
2,
);
const offer = (connectionId: string): SignalPayload => ({
kind: "description", connectionId,
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
try {
// A transient room-signaling outage at the answer must not disable
// Native reception for the session: close only this receiver and run
// the ordinary recovery path.
await peer.acceptSignal("parent", offer("first"));
expect(unavailable).not.toHaveBeenCalled();
expect(peer.nativeSource).toBeNull();
expect(closeReceiver).toHaveBeenCalledWith("session", "first");
if (recoveryOwner === "viewer") {
expect(restart).toHaveBeenCalledWith("parent", "first", true);
expect(exhausted).not.toHaveBeenCalled();
} else {
expect(exhausted).toHaveBeenCalledWith("parent", "first");
expect(restart).not.toHaveBeenCalled();
}
// With signaling back online, the next offer re-acquires the native path.
signalOnline = true;
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue(
new (class {})() as never,
);
await peer.acceptSignal("parent", offer("second"));
expect(acquire).toHaveBeenCalledTimes(2);
expect(receiveOffer).toHaveBeenCalledTimes(2);
expect(unavailable).not.toHaveBeenCalled();
} finally {
peer.dispose();
}
});
it("still disables native on a genuine failure after a signaling failure", async () => {
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
let eventHandler: ((event: unknown) => void) | null = null;
const receiveOffer = vi.fn(async () => ({
answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8",
}));
const client = {
receiveOffer,
onEvent: (handler: (event: unknown) => void) => {
eventHandler = handler;
return () => undefined;
},
onClose: () => () => undefined,
closeReceiver: vi.fn(async () => undefined),
closeEdge: vi.fn(async () => undefined),
} as unknown as NativeClient;
const unavailable = vi.fn();
const peer = new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal: () => false,
sendRestartRequest: () => true,
onStream: () => undefined,
onUpdate: () => undefined,
onRecoveryExhausted: () => true,
},
{},
async () => client,
unavailable,
"session",
2,
);
try {
await peer.acceptSignal("parent", {
kind: "description",
connectionId: "first",
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
expect(unavailable).not.toHaveBeenCalled();
// A genuine native failure on the same connection must still disable
// Native for the session: the signaling path must not have latched the
// failure state.
eventHandler!({ shareId: "session", type: "share-ended", failed: true });
expect(unavailable).toHaveBeenCalledOnce();
} finally {
peer.dispose();
}
});
it.each([
["route", "initialize"], ["route", "start"],
["viewer", "initialize"], ["viewer", "start"],
] as const)("keeps %s bridge %s failure unavailable across replacement peers", async (recoveryOwner, failureStage) => {
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class {
constructor() { if (failureStage === "initialize") throw new DOMException("Peer unavailable", "NotSupportedError"); }
close() {}
});
const browserSignal = vi.spyOn(ViewerPeer.prototype, "acceptSignal").mockResolvedValue();
const bridgeStart = vi.spyOn(NativeMediaBridge.prototype, "start").mockRejectedValue(new Error("bridge failed"));
const receiveOffer = vi.fn(async () => ({
answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8",
}));
const client = {
receiveOffer,
onEvent: () => () => undefined,
onClose: () => () => undefined,
closeReceiver: vi.fn(async () => undefined),
closeEdge: vi.fn(async () => undefined),
} as unknown as NativeClient;
let available = true;
const acquire = vi.fn(async () => available ? client : null);
const unavailable = vi.fn(() => { available = false; });
const recover = vi.fn(() => {
expect(available).toBe(false);
return true;
});
const create = () => new NativeCapableViewerPeer(
{ iceServers: [] },
{
sendSignal: () => true,
sendRestartRequest: recover,
onStream: () => undefined,
onUpdate: () => undefined,
onRecoveryExhausted: recover,
},
{ recoveryOwner },
acquire,
unavailable,
"session",
2,
);
const offer = (connectionId: string): SignalPayload => ({
kind: "description", connectionId,
description: { type: "offer", sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" },
});
const first = create();
const queued = create();
try {
await first.acceptSignal("parent", offer("first"));
await vi.waitFor(() => expect(unavailable).toHaveBeenCalledOnce());
expect(recover).toHaveBeenCalledOnce();
first.dispose();
await queued.acceptSignal("parent", offer("queued"));
expect(browserSignal).toHaveBeenCalledOnce();
const replacement = create();
try {
await replacement.acceptSignal("parent", offer("replacement"));
expect(browserSignal).toHaveBeenCalledTimes(2);
expect(receiveOffer).toHaveBeenCalledOnce();
expect(bridgeStart).toHaveBeenCalledTimes(failureStage === "initialize" ? 0 : 1);
expect(acquire).toHaveBeenCalledTimes(3);
} finally {
replacement.dispose();
}
} finally {
first.dispose();
queued.dispose();
}
});
it("defers local bridge decoded proof while its prepared Native network edge is disconnected", async () => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
vi.spyOn(NativeMediaBridge.prototype, "collectMetrics").mockResolvedValue({ ...EMPTY_METRICS });
let finishStats!: (frames: number) => void;
const stats = new Promise<number>(resolve => { finishStats = resolve; });
vi.spyOn(NativeMediaBridge.prototype, "decodedVideoFrames").mockReturnValue(stats);
let event!: (event: NativeClientEvent) => void;
const client = {
receiveOffer: vi.fn(async () => ({ answer: { type: "answer", sdp: "answer" }, audio: false, codec: "vp8" })),
onEvent: (listener: typeof event) => { event = listener; return () => {}; }, onClose: () => () => {},
closeReceiver: vi.fn(async () => {}), closeEdge: vi.fn(async () => {}),
} as unknown as NativeClient;
const decoded = vi.fn(() => true), restart = vi.fn(() => true), unavailable = vi.fn();
const peer = new NativeCapableViewerPeer({ iceServers: [] }, {
sendSignal: () => true, sendRestartRequest: restart, onStream: () => {}, onUpdate: () => {}, onFirstDecodedFrame: decoded,
}, { recoveryOwner: "route" }, async () => client, unavailable, "session", 2);
const state = (value: "connected" | "disconnected") => event({
version: 10, shareId: "session", connectionId: "prepared", type: "edge-state", state: value,
});
try {
await peer.acceptSignal("host", { kind: "description", connectionId: "prepared", description: { type: "offer",
sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" } });
state("connected"); state("disconnected");
finishStats(1);
await vi.advanceTimersByTimeAsync(100);
expect(decoded).not.toHaveBeenCalled();
state("connected");
await vi.advanceTimersByTimeAsync(100);
expect(decoded).toHaveBeenCalledExactlyOnceWith("prepared");
expect(client.receiveOffer).toHaveBeenCalledOnce();
expect(restart).not.toHaveBeenCalled();
expect(unavailable).not.toHaveBeenCalled();
} finally { peer.dispose(); }
});
it.each(["first", "replacement", "failed-offer"])("keeps committed route recovery and its budget across backend replacement (%s)", async (scenario) => {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
vi.stubGlobal("RTCPeerConnection", class { close() {} });
vi.spyOn(NativeMediaBridge.prototype, "start").mockResolvedValue({} as MediaStream);
vi.spyOn(NativeMediaBridge.prototype, "collectMetrics").mockResolvedValue({ ...EMPTY_METRICS });
vi.spyOn(NativeMediaBridge.prototype, "decodedVideoFrames").mockResolvedValue(null);
let onEvent!: (event: NativeClientEvent) => void;
const receiveOffer = vi.fn(async () => ({ answer: { type: "answer", sdp: "v=0\r\n" }, audio: false, codec: "vp8" }));
const client = {
receiveOffer,
onEvent: (fn: typeof onEvent) => { onEvent = fn; return () => undefined; },
onClose: () => () => undefined,
closeReceiver: vi.fn(async () => undefined), closeEdge: vi.fn(async () => undefined),
} as unknown as NativeClient;
const restart = vi.fn(() => true);
const exhausted = vi.fn(() => true);
const options = { recoveryOwner: "route" as const };
const peer = new NativeCapableViewerPeer({ iceServers: [] }, {
sendSignal: () => true, sendRestartRequest: restart,
onStream: () => undefined, onUpdate: () => undefined, onRecoveryExhausted: exhausted,
}, options, async () => client, () => undefined, "session", 2);
const offer = (connectionId: string) => ({ kind: "description" as const, connectionId,
description: { type: "offer" as const, sdp: "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\na=rtpmap:96 VP8/90000\r\n" }});
const state = (connectionId: string, value: "connected" | "failed") => onEvent({
version: 10, shareId: "session", connectionId, type: "edge-state", state: value,
});
try {
await peer.acceptSignal("parent", offer("first"));
state("first", "connected");
peer.activatePreparedRoute();
expect(options.recoveryOwner).toBe("route"); // Caller options are not mutable route state.
const connectionId = scenario === "replacement" ? "replacement" : "first";
if (scenario === "replacement") {
await peer.acceptSignal("parent", offer(connectionId));
state(connectionId, "connected");
}
state(connectionId, "failed");
expect(restart).toHaveBeenCalledExactlyOnceWith("parent", connectionId, false);
expect(exhausted).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(VIEWER_AUTOMATIC_RECOVERY_TIMEOUT_MS);
expect(restart).toHaveBeenNthCalledWith(2, "parent", connectionId, true);
// A new physical ID is the requested rebuild, not a recovered parent.
const retiredEvent = onEvent;
if (scenario === "failed-offer") receiveOffer.mockRejectedValueOnce(new Error("receiver unavailable"));
await peer.acceptSignal("parent", offer("rebuilt"));
retiredEvent({ version: 10, shareId: "session", connectionId, type: "edge-state", state: "connected" });
state("rebuilt", "failed");
expect(restart).toHaveBeenCalledTimes(2);
expect(exhausted).toHaveBeenCalledExactlyOnceWith("parent", "rebuilt");
// Explicit retry owns a new bounded request and must report its outcome.
expect(peer.requestRecovery(true)).toBe(true);
await vi.advanceTimersByTimeAsync(VIEWER_AUTOMATIC_RECOVERY_TIMEOUT_MS);
expect(exhausted).toHaveBeenCalledTimes(2);
// Only actual recovery or a different parent gives a fresh budget.
await peer.acceptSignal("parent", offer("healthy"));
state("healthy", "connected");
state("healthy", "failed");
expect(restart).toHaveBeenNthCalledWith(4, "parent", "healthy", false);
await peer.acceptSignal("other-parent", offer("other-connection"));
state("other-connection", "failed");
expect(restart).toHaveBeenNthCalledWith(5, "other-parent", "other-connection", false);
} finally { peer.dispose(); }
});