Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
import type { z } from "zod";
import type { RemoteControlMode } from "../remote-control/protocol";
import { debugError, debugEvent } from "../lib/debug";
import { clientRuntimePort } from "../lib/session";
import { NATIVE_CLIENT_PORT_START, NATIVE_CLIENT_PORT_END } from "./discovery-ports";
import type {
IceConfig,
QualitySettings,
SignalPayload,
SfuSignalMessage,
PunchPrediction,
} from "../../shared/protocol";
import { createOpaqueId } from "../lib/opaque-id";
import {
nativeCaptureTargetKey,
type NativeCapturePath,
} from "./capture-selection";
import {
captureOptionsResponseSchema,
edgeOfferResponseSchema,
nativeAckResponseSchema,
remoteStopShortcutResponseSchema,
nativeEventSchema,
nativeDiscoveryIdentitySchema,
nativeConnectSchema,
nativeHealthSchema,
NATIVE_CLIENT_PROTOCOL,
NATIVE_CLIENT_SUBPROTOCOL,
pongResponseSchema,
publicationResponseSchema,
receiveAnswerResponseSchema,
readyResponseSchema,
requestFailedResponseSchema,
shareStartedResponseSchema,
shareSourceReplacedResponseSchema,
shareUpdatedResponseSchema,
sourceListResponseSchema,
microphoneListResponseSchema,
sourcePreviewResponseSchema,
punchPreparedResponseSchema,
punchCompleteResponseSchema,
type NativeAdapter,
type NativeClientEvent,
type NativeHealth,
type NativeCaptureTarget,
type NativeIceCandidate,
type NativeVideoCodec,
type RemoteStopShortcut,
} from "./wire";
const REQUEST_TIMEOUT_MS = 8_000;
interface NativeDiscoveryOptions {
waitForPermission?: boolean;
signal?: AbortSignal;
}
export function isLoopbackPage(): boolean {
return ["localhost", "127.0.0.1", "[::1]"].includes(window.location.hostname);
}
async function localPermission(): Promise<PermissionStatus | null> {
// App Local already runs on loopback. Its permission can say "prompt" even
// though loopback-to-loopback requests do not need consent.
if (isLoopbackPage()) return null;
for (const name of ["loopback-network", "local-network-access"]) {
try {
return await navigator.permissions.query({ name: name as PermissionName });
} catch {
// Older Chromium uses the combined name; other browsers may expose neither.
}
}
return null;
}
interface PendingRequest<T = unknown> {
operation: string;
schema: z.ZodType<T>;
resolve: (value: T) => void;
reject: (error: Error) => void;
timer: number | null;
}
export interface NativeShareInput {
shareId: string;
source: NativeCaptureTarget;
audio: boolean;
excludeAudio?: NativeCaptureTarget;
showCaptureBorder?: boolean;
adapterIndex: number;
encoderIndex: number;
edgeCapacity: number;
profile: QualitySettings;
codec: NativeVideoCodec | "auto";
}
export class NativeCompatibilityError extends Error {
constructor(readonly actualProtocol: number) {
super(`Piik App control protocol ${actualProtocol} is incompatible with ${NATIVE_CLIENT_PROTOCOL}`);
this.name = "NativeCompatibilityError";
}
}
/** The control boundary knows the failed operation, not the driver's cause. */
export class NativeRequestError extends Error {
constructor(
readonly reason: "unavailable" | "timeout" | "send-failed" | "rejected" | "invalid-response" | "disconnected",
readonly operation: string,
options?: ErrorOptions,
) {
super({
unavailable: "Piik App is unavailable",
timeout: "Piik App request timed out",
"send-failed": "Piik App request failed",
rejected: "Piik App request failed",
"invalid-response": "Piik App response is invalid",
disconnected: "Piik App disconnected",
}[reason], options);
this.name = "NativeRequestError";
}
}
export async function discoverNativeHealth(
options: NativeDiscoveryOptions = {},
): Promise<NativeHealth | null> {
const health = await discoverNative("health", body => nativeHealthSchema.parse(body), options);
if (health) debugEvent("native", "discovered", { capabilities: health.nativeMedia });
return health;
}
/** A local approval address is not permission to use native media. */
export async function discoverNativeConnect(signal?: AbortSignal): Promise<string | null> {
return discoverNative("connect-discovery", body => {
const { connectURL } = nativeConnectSchema.parse(body);
const url = new URL(connectURL);
if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port ||
url.username || url.password || url.pathname !== "/client" || url.search || url.hash) {
throw new Error("Invalid local App approval address");
}
url.searchParams.set("site", window.location.origin);
return url.toString();
}, { signal });
}
async function discoverNative<T>(
path: "health" | "connect-discovery", read: (body: unknown) => T,
{ waitForPermission = true, signal }: NativeDiscoveryOptions,
): Promise<T | null> {
if (signal?.aborted) return null;
const permission = await localPermission();
if (!waitForPermission && permission && permission.state !== "granted") {
debugEvent("native", "unavailable", { stage: "permission", permission: permission.state });
return null;
}
if (signal?.aborted) return null;
const controller = new AbortController();
const abort = () => controller.abort(signal?.reason);
signal?.addEventListener("abort", abort, { once: true });
// Permission waiting is user-owned; the parallel scan has one network deadline.
let timer: number | undefined;
const startDeadline = () => { timer ??= window.setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS); };
const permissionChanged = () => { if (permission?.state !== "prompt") startDeadline(); };
const awaitingPermission = permission?.state === "prompt";
try {
if (awaitingPermission) permission.addEventListener("change", permissionChanged);
permissionChanged();
// An explicit launch stays with its App even when another approved App is faster.
const selectedPort = clientRuntimePort();
const ports = selectedPort === null ? Array.from({
length: NATIVE_CLIENT_PORT_END - NATIVE_CLIENT_PORT_START + 1,
}, (_, index) => NATIVE_CLIENT_PORT_START + index) : [selectedPort];
return await Promise.any(ports.map(async port => {
const response = await fetch(`http://127.0.0.1:${port}/${path}`, {
cache: "no-store",
signal: controller.signal,
...(isLoopbackPage() ? {} : { targetAddressSpace: "loopback" }),
} as RequestInit);
startDeadline();
if (!response.ok) throw new Error("Piik App discovery was not accepted");
const body: unknown = await response.json();
const identity = nativeDiscoveryIdentitySchema.safeParse(body);
if (!identity.success || identity.data.port !== port) {
throw new Error("Not a Piik App discovery response");
}
if (identity.data.protocol !== NATIVE_CLIENT_PROTOCOL) {
throw new NativeCompatibilityError(identity.data.protocol);
}
return read(body);
}));
} catch (error) {
const incompatible = error instanceof AggregateError
? error.errors.find((failure) => failure instanceof NativeCompatibilityError)
: undefined;
if (incompatible) {
debugEvent("native", "incompatible", {
expectedProtocol: NATIVE_CLIENT_PROTOCOL,
actualProtocol: incompatible.actualProtocol,
});
throw incompatible;
}
// A failed fetch cannot distinguish an absent App from blocked local access.
debugEvent("native", "unavailable", { stage: "discovery", timedOut: controller.signal.aborted });
return null;
} finally {
if (awaitingPermission) permission.removeEventListener("change", permissionChanged);
signal?.removeEventListener("abort", abort);
window.clearTimeout(timer);
controller.abort();
}
}
export async function notifyNativePresentation(
language: "zh" | "en" | "vis",
signal: AbortSignal,
): Promise<void> {
if (signal.aborted) return;
const health = await discoverNativeHealth({ signal, waitForPermission: false });
if (!health || signal.aborted) return;
await fetch(`http://127.0.0.1:${health.port}/presentation`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ language }),
signal,
...(isLoopbackPage() ? {} : { targetAddressSpace: "loopback" }),
} as RequestInit);
}
export class NativeClient {
private readonly pending = new Map<string, PendingRequest>();
private readonly listeners = new Set<(event: NativeClientEvent) => void>();
private readonly closeListeners = new Set<() => void>();
private closed = false;
private audioVolumeUpdates = new Map<"set-microphone" | "set-share-volume", { shareId: string; volume: number; done: Promise<void> }>();
private constructor(
readonly health: NativeHealth,
private readonly socket: WebSocket,
) {
socket.addEventListener("message", (event) =>
this.handleMessage(event.data),
);
socket.addEventListener("close", () => this.handleClose());
socket.addEventListener("error", () => this.handleClose());
}
static async connect(options?: NativeDiscoveryOptions): Promise<NativeClient | null> {
const signal = options?.signal;
const health = await discoverNativeHealth(options);
if (!health || signal?.aborted) return null;
const socket = new WebSocket(`ws://127.0.0.1:${health.port}/control`, [
`${NATIVE_CLIENT_SUBPROTOCOL}.${health.instanceToken}`,
]);
const client = new NativeClient(health, socket);
// Acquisition owns discovery, the WebSocket handshake and hello together.
// Once returned, the caller owns the live client independently of this signal.
const abort = () => client.close();
signal?.addEventListener("abort", abort, { once: true });
try {
const opened = await new Promise<boolean>((resolveOpen) => {
const finish = (value: boolean) => {
window.clearTimeout(timer);
socket.removeEventListener("open", onOpen);
socket.removeEventListener("error", fail);
socket.removeEventListener("close", fail);
signal?.removeEventListener("abort", fail);
resolveOpen(value);
};
const onOpen = () => finish(socket.protocol === `${NATIVE_CLIENT_SUBPROTOCOL}.${health.instanceToken}`);
const fail = () => finish(false);
const timer = window.setTimeout(fail, REQUEST_TIMEOUT_MS);
socket.addEventListener("open", onOpen);
socket.addEventListener("error", fail);
socket.addEventListener("close", fail);
signal?.addEventListener("abort", fail, { once: true });
});
if (!opened || client.closed || signal?.aborted) {
if (!signal?.aborted) debugEvent("native", "unavailable", { stage: "control" });
client.close();
return null;
}
await client.request("hello", {}, readyResponseSchema);
if (client.closed || signal?.aborted) { client.close(); return null; }
debugEvent("native", "connected");
return client;
} catch {
client.close();
return null;
} finally {
signal?.removeEventListener("abort", abort);
}
}
onEvent(listener: (event: NativeClientEvent) => void): () => void {
this.listeners.add(listener);
return () => this.listeners.delete(listener);
}
onClose(listener: () => void): () => void {
if (this.closed) {
listener();
return () => undefined;
}
this.closeListeners.add(listener);
return () => this.closeListeners.delete(listener);
}
async ping(): Promise<void> {
await this.request("ping", {}, pongResponseSchema);
}
async captureOptions(): Promise<NativeAdapter[]> {
const response = await this.request(
"capture-options",
{},
captureOptionsResponseSchema,
);
return response.adapters;
}
async sources(): Promise<NativeCaptureTarget[]> {
const response = await this.request(
"list-sources",
{},
sourceListResponseSchema,
);
return response.sources;
}
async sourcePreview(target: NativeCaptureTarget): Promise<string | null> {
const response = await this.request(
"source-preview",
{ source: target },
sourcePreviewResponseSchema,
);
if (response.sourceKey !== nativeCaptureTargetKey(target)) {
throw new Error("Native capture preview identity changed");
}
return response.data
? `data:${response.mime};base64,${response.data}`
: null;
}
async startShare(
input: NativeShareInput,
onRequested?: () => void,
): Promise<{ audio: boolean; codec: NativeVideoCodec; sourceAudio?: boolean }> {
// Older Apps reject unknown command fields.
const { showCaptureBorder = false, excludeAudio, ...shareInput } = input;
this.validateAudioExclusion(excludeAudio);
const response = await this.request(
"start-share",
{
...shareInput,
...(excludeAudio ? { excludeAudio } : {}),
// Keep a stable output for source-audio toggles during sharing.
...(this.health.nativeMedia.microphone || this.health.nativeMedia.shareVolume ? { microphoneMixing: true } : {}),
...(this.health.nativeMedia.remoteInput ? { remoteInput: true } : {}),
...(this.health.nativeMedia.captureBorderControl ? { showCaptureBorder } : {}),
...(this.health.nativeMedia.sourceCancellation ? { reportSourceCancellation: true } : {}),
...(this.health.nativeMedia.captureFailureDetails ? { reportCaptureFailure: true } : {}),
},
shareStartedResponseSchema,
input.source.kind === "picker" ? null : REQUEST_TIMEOUT_MS,
onRequested,
);
if (response.shareId !== input.shareId) {
throw new Error("Native share identity changed");
}
return { audio: response.audio, codec: response.codec, sourceAudio: response.sourceAudio };
}
async updateShare(shareId: string, profile: QualitySettings): Promise<void> {
const response = await this.request(
"update-share",
{ shareId, profile },
shareUpdatedResponseSchema,
null,
);
if (response.shareId !== shareId) {
throw new Error("Native share identity changed");
}
}
private validateAudioExclusion(target: NativeCaptureTarget | undefined): void {
if (target && !this.health.nativeMedia.processAudioExclusion) {
throw new Error("Piik App does not support audio exclusion");
}
}
async replaceShareSource(
shareId: string,
source: NativeCaptureTarget,
audio: boolean,
path: NativeCapturePath,
showCaptureBorder = false,
excludeAudio?: NativeCaptureTarget,
): Promise<void> {
this.validateAudioExclusion(excludeAudio);
const response = await this.request(
"replace-share-source",
{
shareId,
source,
audio,
...(excludeAudio ? { excludeAudio } : {}),
adapterIndex: path.adapterIndex,
encoderIndex: path.encoderIndex,
...(this.health.nativeMedia.captureBorderControl ? { showCaptureBorder } : {}),
...(this.health.nativeMedia.sourceCancellation ? { reportSourceCancellation: true } : {}),
},
shareSourceReplacedResponseSchema,
source.kind === "picker" ? null : REQUEST_TIMEOUT_MS,
);
if (response.shareId !== shareId) {
throw new Error("Native share identity changed");
}
}
async prepareEdge(
shareId: string,
connectionId: string,
iceConfig: IceConfig,
sourceConnectionId?: string,
punched = false,
): Promise<RTCSessionDescriptionInit> {
const response = await this.request(
"prepare-edge",
{
shareId,
connectionId,
...(punched ? { punched: true } : {}),
...(sourceConnectionId ? { sourceConnectionId } : {}),
iceServers: iceConfig.iceServers.map((server) => ({
urls: Array.isArray(server.urls) ? server.urls : [server.urls],
})),
},
edgeOfferResponseSchema,
);
if (
response.shareId !== shareId ||
response.connectionId !== connectionId
) {
throw new Error("Native edge identity changed");
}
return { type: "offer", sdp: response.sdp };
}
async preparePunch(shareId: string, connectionId: string, iceConfig: IceConfig,
secret: string, edgeCapacity?: number, sourceConnectionId?: string): Promise<PunchPrediction | null> {
const response = await this.request("prepare-punch", {
shareId, connectionId, secret,
...(edgeCapacity !== undefined ? { edgeCapacity } : {}),
...(sourceConnectionId ? { sourceConnectionId } : {}),
iceServers: iceConfig.iceServers.map(server => ({ urls: Array.isArray(server.urls) ? server.urls : [server.urls] })),
}, punchPreparedResponseSchema);
return response.prediction;
}
async runPunch(shareId: string, connectionId: string, prediction: PunchPrediction): Promise<boolean> {
return (await this.request("run-punch", { shareId, connectionId, prediction }, punchCompleteResponseSchema)).connected;
}
async closePunch(shareId: string, connectionId: string): Promise<void> {
await this.request("close-punch", { shareId, connectionId }, nativeAckResponseSchema);
}
async preparePublication(
shareId: string,
publicationGeneration: string,
connectionId: string,
iceConfig: IceConfig,
) {
const response = await this.request(
"prepare-publication",
{
shareId,
publicationGeneration,
connectionId,
iceServers: iceConfig.iceServers.map((server) => ({
urls: Array.isArray(server.urls) ? server.urls : [server.urls],
})),
},
publicationResponseSchema,
);
if (
response.type !== "publication-offer" ||
!response.sdp ||
response.shareId !== shareId ||
response.publicationGeneration !== publicationGeneration ||
response.connectionId !== connectionId
) {
throw new Error("Native publication identity changed");
}
return {
description: { type: "offer" as const, sdp: response.sdp },
media: response.media,
};
}
async publicationMedia(
shareId: string,
publicationGeneration: string,
connectionId: string,
) {
const response = await this.request(
"publication-media",
{
shareId,
publicationGeneration,
connectionId,
},
publicationResponseSchema,
);
if (
response.type !== "publication-media" ||
response.shareId !== shareId ||
response.publicationGeneration !== publicationGeneration ||
response.connectionId !== connectionId
) {
throw new Error("Native publication identity changed");
}
return response.media;
}
async acceptPublicationSignal(
shareId: string,
message: SfuSignalMessage,
): Promise<void> {
const identity = {
shareId,
publicationGeneration: message.publicationGeneration,
connectionId: message.connectionId,
};
if (
message.kind === "description" &&
message.description?.type === "answer"
) {
await this.request(
"publication-answer",
{ ...identity, sdp: message.description.sdp },
nativeAckResponseSchema,
);
} else if (message.kind === "candidate") {
await this.request(
"publication-candidate",
{ ...identity, candidate: message.candidate ?? null },
nativeAckResponseSchema,
);
} else if (message.kind === "layers") {
await this.request(
"publication-layers",
{ ...identity, activeCount: message.activeCount },
nativeAckResponseSchema,
);
}
}
async closePublication(
shareId: string,
publicationGeneration: string,
connectionId: string,
): Promise<void> {
await this.request(
"close-publication",
{ shareId, publicationGeneration, connectionId },
nativeAckResponseSchema,
);
}
async prepareLocalEdge(
shareId: string,
connectionId: string,
sourceConnectionId?: string,
restart = false,
): Promise<RTCSessionDescriptionInit & { offerId: string }> {
const response = await this.request(
"prepare-local-edge",
{
shareId,
connectionId,
restart,
...(sourceConnectionId ? { sourceConnectionId } : {}),
},
edgeOfferResponseSchema,
);
if (
response.shareId !== shareId ||
response.connectionId !== connectionId
) {
throw new Error("Native local edge identity changed");
}
return { type: "offer", sdp: response.sdp, offerId: response.id };
}
async receiveOffer(
shareId: string,
connectionId: string,
offer: RTCSessionDescriptionInit,
iceConfig: IceConfig,
edgeCapacity: number,
punched = false,
): Promise<{
answer: { type: "answer"; sdp: string };
audio: boolean;
codec: NativeVideoCodec;
reused: boolean;
}> {
if (offer.type !== "offer" || !offer.sdp) {
throw new Error("Native receiver requires an SDP offer");
}
const response = await this.request(
"receive-offer",
{
shareId,
connectionId,
...(this.health.nativeMedia.receiverReuse ? { reuseReceiver: true } : {}),
edgeCapacity,
...(punched ? { punched: true } : {}),
iceServers: iceConfig.iceServers.map((server) => ({
urls: Array.isArray(server.urls) ? server.urls : [server.urls],
})),
sdp: offer.sdp,
},
receiveAnswerResponseSchema,
);
if (
response.shareId !== shareId ||
response.connectionId !== connectionId
) {
throw new Error("Native receiver identity changed");
}
return {
answer: { type: "answer", sdp: response.sdp },
audio: response.audio,
codec: response.codec,
reused: response.reused === true,
};
}
async addReceiveCandidate(
shareId: string,
connectionId: string,
candidate: NativeIceCandidate | null,
): Promise<void> {
await this.request(
"receive-candidate",
{ shareId, connectionId, candidate },
nativeAckResponseSchema,
);
}
async closeReceiver(shareId: string, connectionId: string): Promise<void> {
await this.request(
"close-receiver",
{ shareId, connectionId },
nativeAckResponseSchema,
);
}
async stopReceive(shareId: string): Promise<void> {
await this.request("stop-receive", { shareId }, nativeAckResponseSchema);
}
async acceptSignal(
shareId: string,
connectionId: string,
payload: SignalPayload,
offerId?: string,
): Promise<void> {
if (payload.connectionId !== connectionId || payload.kind === "punch") return;
if (payload.kind === "description") {
if (payload.description.type !== "answer") return;
await this.request(
"edge-answer",
{ shareId, connectionId, sdp: payload.description.sdp, ...(offerId ? { offerId } : {}) },
nativeAckResponseSchema,
);
return;
}
await this.request(
"edge-candidate",
{ shareId, connectionId, candidate: payload.candidate },
nativeAckResponseSchema,
);
}
async closeEdge(shareId: string, connectionId: string): Promise<void> {
await this.request(
"close-edge",
{ shareId, connectionId },
nativeAckResponseSchema,
);
}
async microphones(): Promise<{ id: string; label: string }[]> {
if (!this.health.nativeMedia.microphone) throw new Error("Piik App microphone is unavailable");
return (await this.request("list-microphones", {}, microphoneListResponseSchema)).devices;
}
async setMicrophone(shareId: string, enabled: boolean, volume: number, deviceId = ""): Promise<void> {
if (!this.health.nativeMedia.microphone) throw new Error("Piik App microphone is unavailable");
await this.request("set-microphone", { shareId, enabled, volume, deviceId }, nativeAckResponseSchema, null);
}
// Dragging keeps at most one request in flight and one latest value. It cannot
// queue dozens of slider events ahead of Stop or reopen a lost microphone.
setMicrophoneVolume(shareId: string, volume: number): Promise<void> {
if (!this.health.nativeMedia.microphone) return Promise.reject(new Error("Piik App microphone is unavailable"));
return this.setAudioVolume("set-microphone", shareId, volume);
}
setShareVolume(shareId: string, volume: number): Promise<void> {
if (!this.health.nativeMedia.shareVolume) return Promise.reject(new Error("Piik App share volume is unavailable"));
return this.setAudioVolume("set-share-volume", shareId, volume);
}
private setAudioVolume(type: "set-microphone" | "set-share-volume", shareId: string, volume: number): Promise<void> {
const active = this.audioVolumeUpdates.get(type);
if (active?.shareId === shareId) { active.volume = volume; return active.done; }
const update = { shareId, volume, done: Promise.resolve() };
this.audioVolumeUpdates.set(type, update);
update.done = (async () => {
do {
const sent = update.volume;
await this.request(type, { shareId, volume: sent }, nativeAckResponseSchema);
if (sent === update.volume) break;
} while (this.audioVolumeUpdates.get(type) === update && !this.closed);
})().finally(() => { if (this.audioVolumeUpdates.get(type) === update) this.audioVolumeUpdates.delete(type); });
return update.done;
}
async setRemoteControl(shareId: string, requestId: string, allow: boolean): Promise<void> {
await this.request("set-remote-control", { shareId, requestId, allow }, nativeAckResponseSchema);
}
async setRemoteControlPolicy(shareId: string, mode: RemoteControlMode, password?: string): Promise<void> {
await this.request("set-remote-control-policy", { shareId, mode, ...(password !== undefined ? { password } : {}),
...(this.health.nativeMedia.remoteCoPlay ? { coPlay: true } : {}) }, nativeAckResponseSchema, null);
}
async remoteStopShortcut(shareId: string, key?: number): Promise<RemoteStopShortcut> {
if (!this.health.nativeMedia.remoteStopShortcut) throw new Error("Piik App shortcut settings are unavailable");
return this.request(key === undefined ? "get-remote-stop-shortcut" : "set-remote-stop-shortcut",
{ shareId, ...(key === undefined ? {} : { key }) }, remoteStopShortcutResponseSchema);
}
async setRemoteInputPeers(shareId: string, peers: { peerId: string; endpointId: string; secret: string }[]): Promise<void> {
await this.request("set-remote-input-peers", { shareId, peers }, nativeAckResponseSchema);
}
async setRemoteControlSimultaneous(shareId: string, enabled: boolean): Promise<void> {
await this.request("set-remote-control-simultaneous", { shareId, enabled }, nativeAckResponseSchema);
}
async stopShare(shareId: string): Promise<void> {
for (const [type, update] of this.audioVolumeUpdates) if (update.shareId === shareId) this.audioVolumeUpdates.delete(type);
await this.request("stop-share", { shareId }, nativeAckResponseSchema);
}
async setPaused(shareId: string, paused: boolean): Promise<void> {
await this.request(
"pause-share",
{ shareId, paused },
nativeAckResponseSchema,
);
}
close(): void {
if (this.closed) return;
this.closed = true;
this.audioVolumeUpdates.clear();
this.rejectPending();
this.listeners.clear();
this.closeListeners.clear();
if (this.socket.readyState < WebSocket.CLOSING) {
this.socket.close(1000, "page closed");
}
}
private request<T>(
type: string,
fields: object,
schema: z.ZodType<T>,
timeoutMs: number | null = REQUEST_TIMEOUT_MS,
onRequested?: () => void,
): Promise<T> {
if (this.closed || this.socket.readyState !== WebSocket.OPEN) {
return Promise.reject(new NativeRequestError("unavailable", type));
}
const id = createOpaqueId();
const began = performance.now();
const details = { type, requestId: id };
return new Promise<T>((resolveRequest, rejectRequest) => {
const timer =
timeoutMs === null
? null
: window.setTimeout(() => {
this.pending.delete(id);
debugEvent("native", "request-timeout", { ...details, durationMs: performance.now() - began });
rejectRequest(new NativeRequestError("timeout", type));
}, timeoutMs);
this.pending.set(id, {
operation: type,
schema,
resolve: (value) => {
debugEvent("native", "response", { ...details, durationMs: performance.now() - began, applied: value });
resolveRequest(value as T);
},
reject: (error) => {
debugError("native", "request-failed", error, { ...details, durationMs: performance.now() - began });
rejectRequest(error);
},
timer,
});
try {
debugEvent("native", "request", { ...details, requested: fields, timeoutMs });
this.socket.send(
JSON.stringify({
version: NATIVE_CLIENT_PROTOCOL,
id,
type,
...fields,
}),
);
} catch (error) {
if (timer !== null) window.clearTimeout(timer);
this.pending.delete(id);
debugError("native", "request-failed", error, { ...details, durationMs: performance.now() - began });
rejectRequest(new NativeRequestError("send-failed", type, { cause: error }));
return;
}
onRequested?.();
});
}
private handleMessage(raw: unknown): void {
let value: unknown;
try {
value = JSON.parse(String(raw));
} catch {
debugEvent("native", "protocol-failed", { stage: "json-invalid" });
this.failConnection();
return;
}
const id = requestId(value);
if (id) {
const pending = this.pending.get(id);
if (!pending) return;
this.pending.delete(id);
if (pending.timer !== null) window.clearTimeout(pending.timer);
const failure = requestFailedResponseSchema.safeParse(value);
if (failure.success) {
if (failure.data.code === "source-canceled") {
pending.reject(new DOMException("Source selection canceled", "NotAllowedError"));
return;
}
pending.reject(new NativeRequestError("rejected", pending.operation, { cause: { code: failure.data.code } }));
return;
}
const parsed = pending.schema.safeParse(value);
if (parsed.success) {
pending.resolve(parsed.data);
} else {
pending.reject(new NativeRequestError("invalid-response", pending.operation, { cause: parsed.error }));
}
return;
}
const event = nativeEventSchema.safeParse(value);
if (!event.success) {
// A rejected observation has no control authority. Drop it without
// retiring healthy media; its identity/state must still pass to be used.
if (value && typeof value === "object" && "type" in value &&
(value.type === "edge-quality" || value.type === "publication-quality")) {
debugError("native", "quality-sample-invalid", event.error);
return;
}
debugError("native", "protocol-failed", event.error, { stage: "event-invalid" });
this.failConnection();
return;
}
debugEvent("native", "event", event.data);
for (const listener of this.listeners) {
listener(event.data);
}
}
private handleClose(): void {
if (this.closed) return;
debugEvent("native", "closed");
this.closed = true;
this.rejectPending();
this.listeners.clear();
const listeners = [...this.closeListeners];
this.closeListeners.clear();
for (const listener of listeners) listener();
}
private failConnection(): void {
if (this.socket.readyState < WebSocket.CLOSING) {
this.socket.close(1008, "invalid Client message");
}
this.handleClose();
}
private rejectPending(): void {
for (const request of this.pending.values()) {
if (request.timer !== null) window.clearTimeout(request.timer);
request.reject(new NativeRequestError("disconnected", request.operation));
}
this.pending.clear();
}
}
function requestId(value: unknown): string | null {
if (!value || typeof value !== "object" || !("id" in value)) return null;
const id = (value as { id?: unknown }).id;
return typeof id === "string" ? id : null;
}