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

13.9 KB
Raw Blame
import type { SignalPayload } from "../../shared/protocol";
import { candidateSignalOrigin } from "../../shared/nat-candidate";
import { debugError } from "../lib/debug";

export type SignalCandidate = Extract<
  SignalPayload,
  { kind: "candidate" }
>["candidate"];
type ConcreteSignalCandidate = NonNullable<SignalCandidate>;

export function isNativeNatSurveyCandidate(
  candidate: SignalCandidate,
  iceServers: readonly RTCIceServer[] | undefined,
  auxiliaryStunUrls: readonly string[] = [],
): boolean {
  const index = candidate && /^candidate:ns([1-9]\d*)\s/i.exec(candidate.candidate)?.[1];
  if (!index) return false;
  // App identifies the requested destination, never its response order. Extra
  // ordinary STUN servers remain useful candidates but are not survey evidence.
  const urls = iceServersWithNatPrediction(iceServers, true, auxiliaryStunUrls)
    .flatMap(urlsOf).filter(url => /^stun:/i.test(url));
  const url = urls[Number(index) - 1];
  const normalized = url ? normalizedStunUrl(url) : null;
  return normalized !== null && natPredictionSurveyUrls(iceServers, auxiliaryStunUrls).has(normalized);
}

const DEFAULT_STUN_PORT = 3478;
const MIN_PREDICTABLE_PORT = 1;
const MAX_PREDICTABLE_PORT = 65_535;

/** Keep the experiment bounded so normal ICE candidates retain their budget. */
export const NAT_PREDICTION_STEPS = 4;
export const MAX_NAT_PREDICTION_CANDIDATES = NAT_PREDICTION_STEPS * 2;

export async function addRemoteIceCandidate(
  connection: RTCPeerConnection,
  candidate: SignalCandidate,
): Promise<void> {
  try {
    await connection.addIceCandidate(candidate);
  } catch (error) {
    // A stale/rejected candidate is disposable input, not failed SDP or a dead
    // transport. Keep draining this generation; ICE state owns route failure.
    if (
      !(error instanceof DOMException && error.name === "OperationError") &&
      candidateSignalOrigin(candidate?.candidate ?? null) !== "predicted"
    ) {
      throw error;
    }
    debugError("webrtc", "remote-candidate-rejected", error, {
      origin: candidateSignalOrigin(candidate?.candidate ?? null),
    });
  }
}

interface SrflxObservation {
  candidate: SignalCandidate;
  fields: string[];
  address: string;
  port: number;
  groupKey: string;
}

function urlsOf(server: RTCIceServer): readonly string[] {
  return Array.isArray(server.urls) ? server.urls : [server.urls];
}

function cloneIceServer(server: RTCIceServer): RTCIceServer {
  return {
    ...server,
    urls: Array.isArray(server.urls) ? [...server.urls] : server.urls,
  };
}

function normalizedStunUrl(url: string): string | null {
  if (!/^stun:/i.test(url)) {
    return null;
  }
  const authority = url.slice(url.indexOf(":") + 1);
  let parsed: URL;
  try {
    parsed = new URL(`http://${authority}`);
  } catch {
    return null;
  }
  if (
    !parsed.hostname ||
    parsed.username ||
    parsed.password ||
    parsed.pathname !== "/" ||
    parsed.search ||
    parsed.hash
  ) {
    return null;
  }
  const hostname = parsed.hostname.startsWith("[")
    ? parsed.hostname.toLowerCase()
    : parsed.hostname.includes(":")
      ? `[${parsed.hostname.toLowerCase()}]`
      : parsed.hostname.toLowerCase();
  // The HTTP parser normalizes the host but drops an explicit :80. STUN
  // defaults to 3478 only when its authority omits the port (RFC 7064).
  const explicitPort = /:(\d+)$/.exec(authority)?.[1];
  const port = explicitPort === undefined ? DEFAULT_STUN_PORT : Number(explicitPort);
  return `stun:${hostname}:${port}`;
}

/** URLs whose same-socket observations may form the controlled port sequence. */
export function natPredictionSurveyUrls(
  iceServers: readonly RTCIceServer[] | undefined,
  auxiliaryStunUrls: readonly string[] = [],
): ReadonlySet<string> {
  const configuredAuxiliaryUrls = new Set(
    auxiliaryStunUrls.flatMap((url) => {
      const normalized = normalizedStunUrl(url);
      return normalized ? [normalized] : [];
    }),
  );
  if (configuredAuxiliaryUrls.size !== 2) {
    return new Set();
  }
  const ordinary = (iceServers ?? []).flatMap(urlsOf)
    .map(normalizedStunUrl)
    .filter((url): url is string => url !== null && !configuredAuxiliaryUrls.has(url));
  // Keep the published Hosted base choice, independent of discovery order.
  // Explicit App surveys may also use a non-default port.
  const base = ordinary.find(url => url.endsWith(`:${DEFAULT_STUN_PORT}`)) ?? ordinary[0];
  return base ? new Set([base, ...configuredAuxiliaryUrls]) : new Set();
}

/**
 * Add two optional survey destinations without changing the server-provided
 * ordinary STUN list. The caller opts into this per connection.
 */
export function iceServersWithNatPrediction(
  iceServers: readonly RTCIceServer[] | undefined,
  enabled: boolean,
  auxiliaryStunUrls: readonly string[] = [],
): RTCIceServer[] {
  const base = (iceServers ?? []).map(cloneIceServer);
  if (!enabled) {
    return base;
  }

  const additions = new Set<string>();
  const existing = new Set(
    (iceServers ?? [])
      .flatMap((server) => urlsOf(server))
      .map((url) => normalizedStunUrl(url) ?? url),
  );
  for (const url of auxiliaryStunUrls) {
    const normalized = normalizedStunUrl(url);
    if (normalized && !existing.has(normalized)) {
      additions.add(url);
      existing.add(normalized);
    }
  }

  return [
    ...base,
    ...Array.from(additions, (url) => ({ urls: url })),
  ];
}

function parseSrflxCandidate(
  candidate: SignalCandidate,
): SrflxObservation | null {
  if (!candidate || !candidate.candidate.trim()) {
    return null;
  }
  const fields = candidate.candidate.trim().split(/\s+/);
  const typeIndex = fields.findIndex(
    (field) => field.toLowerCase() === "typ",
  );
  if (
    fields.length < 8 ||
    !fields[0]?.toLowerCase().startsWith("candidate:") ||
    fields[2]?.toLowerCase() !== "udp" ||
    typeIndex < 0 ||
    fields[typeIndex + 1]?.toLowerCase() !== "srflx"
  ) {
    return null;
  }
  const address = fields[4];
  const port = Number(fields[5]);
  if (
    !address ||
    !Number.isInteger(port) ||
    port < MIN_PREDICTABLE_PORT ||
    port > MAX_PREDICTABLE_PORT
  ) {
    return null;
  }
  const related = (name: string): string => {
    const index = fields.findIndex(field => field.toLowerCase() === name);
    return index < 0 ? "" : fields[index + 1] ?? "";
  };
  // One public IP can cover multiple local sockets. Do not spend this
  // generation's prediction budget on a sequence mixed across their bases.
  // Redacted/missing related fields retain the bounded Browser hypothesis.
  const groupKey = [
    candidate.sdpMid ?? "",
    candidate.sdpMLineIndex ?? "",
    fields[1],
    related("raddr"),
    related("rport"),
    address,
  ].join("/");
  return { candidate, fields, address, port, groupKey };
}

function distinctObservations(
  observations: readonly SrflxObservation[],
): SrflxObservation[] {
  const seen = new Set<string>();
  return observations.filter((observation) => {
    const key = `${observation.groupKey}/${observation.port}`;
    if (seen.has(key)) {
      return false;
    }
    seen.add(key);
    return true;
  });
}

function stableStep(observations: readonly SrflxObservation[]): number | null {
  if (observations.length < 3) {
    return null;
  }
  const sorted = [...observations].sort((left, right) => left.port - right.port);
  const step = sorted[1]!.port - sorted[0]!.port;
  if (
    step <= 0 ||
    sorted.some(
      (observation, index) =>
        index > 0 && observation.port - sorted[index - 1]!.port !== step,
    )
  ) {
    return null;
  }
  return step;
}

function predictedAround(
  low: SrflxObservation,
  high: SrflxObservation,
  step: number,
): SignalCandidate[] {
  const predicted: SignalCandidate[] = [];
  for (const [anchor, direction] of [
    [high, 1],
    [low, -1],
  ] as const) {
    for (let index = 1; index <= NAT_PREDICTION_STEPS; index += 1) {
      const port = anchor.port + direction * step * index;
      if (port < MIN_PREDICTABLE_PORT || port > MAX_PREDICTABLE_PORT) {
        continue;
      }
      const fields = [...anchor.fields];
      fields[0] = `candidate:s${direction > 0 ? "p" : "m"}${index}`;
      fields[5] = String(port);
      predicted.push({
        ...anchor.candidate,
        candidate: fields.join(" "),
      });
    }
  }
  return predicted;
}

/**
 * Return a bounded, connection-local prediction only for a clear arithmetic
 * srflx shape. No participant classification or candidate rejection happens
 * here; callers append the result to the ordinary ICE candidate set.
 */
export function predictSrflxCandidates(
  candidates: readonly SignalCandidate[],
): SignalCandidate[] {
  const groups = new Map<string, SrflxObservation[]>();
  for (const candidate of candidates) {
    const observation = parseSrflxCandidate(candidate);
    if (!observation) {
      continue;
    }
    const group = groups.get(observation.groupKey) ?? [];
    group.push(observation);
    groups.set(observation.groupKey, group);
  }

  for (const group of groups.values()) {
    const distinct = distinctObservations(group);
    const step = stableStep(distinct);
    if (step === null) {
      continue;
    }
    const ordered = [...distinct].sort((left, right) => left.port - right.port);
    return predictedAround(ordered[0]!, ordered.at(-1)!, step).slice(
      0,
      MAX_NAT_PREDICTION_CANDIDATES,
    );
  }
  return [];
}

/**
 * Emits every ordinary candidate at normal trickle timing. Once one ICE
 * generation proves a predictable srflx shape, the bounded predictions are
 * appended without delaying or replacing stock ICE.
 */
export class NatPredictionCandidateBatch {
  private readonly observedSrflx: SignalCandidate[] = [];
  private predictionsSent = false;
  private completed = false;

  constructor(private readonly send: (candidate: SignalCandidate | null) => void) {}

  add(candidate: SignalCandidate, predictionEligible = true): void {
    if (this.completed) {
      return;
    }
    if (!parseSrflxCandidate(candidate)) {
      this.send(candidate);
      return;
    }
    if (predictionEligible) {
      this.observedSrflx.push(candidate);
      this.trySendPredictions();
    }
    this.send(candidate);
  }

  complete(end: SignalCandidate = null): void {
    if (this.completed) {
      return;
    }
    this.trySendPredictions();
    this.send(end);
    this.completed = true;
  }

  discard(): void {
    this.completed = true;
    this.observedSrflx.length = 0;
  }

  private trySendPredictions(): void {
    if (this.predictionsSent) {
      return;
    }
    const predictions = predictSrflxCandidates(this.observedSrflx);
    if (predictions.length === 0) {
      return;
    }
    for (const candidate of predictions) {
      this.send(candidate);
    }
    this.predictionsSent = true;
  }
}

function signalCandidate(candidate: RTCIceCandidate): ConcreteSignalCandidate {
  return {
    candidate: candidate.candidate,
    sdpMid: candidate.sdpMid,
    sdpMLineIndex: candidate.sdpMLineIndex,
    usernameFragment: candidate.usernameFragment,
  };
}

/** Own local ICE generations across Browser and Native trickle delivery. */
export class NatPredictionCandidateEmitter {
  private batch: NatPredictionCandidateBatch | null = null;
  private generation: ConcreteSignalCandidate | null = null;
  private endSent = false;
  private surveyUrls = new Set<string>();

  constructor(
    private readonly enabled: boolean,
    private readonly send: (candidate: SignalCandidate | null) => void,
    surveyUrls: ReadonlySet<string> = new Set(),
  ) {
    this.setSurveyUrls(surveyUrls);
  }

  setSurveyUrls(urls: ReadonlySet<string>): void {
    this.surveyUrls = new Set(
      [...urls].flatMap((url) => {
        const normalized = normalizedStunUrl(url);
        return normalized ? [normalized] : [];
      }),
    );
  }

  add(candidate: RTCIceCandidate | null): void {
    const serverUrl = (
      candidate as (RTCIceCandidate & { readonly url?: string | null }) | null
    )?.url;
    const candidateUrl = serverUrl ? normalizedStunUrl(serverUrl) : null;
    this.addSignal(candidate ? signalCandidate(candidate) : null,
      candidateUrl !== null && this.surveyUrls.has(candidateUrl));
  }

  /** Native trickle shares the same ICE-generation owner as Browser trickle. */
  addSignal(next: SignalCandidate, predictionEligible: boolean): void {
    if (!next || next.candidate === "") {
      // A scoped end can arrive after a newer generation started. Forward it
      // without completing that generation's prediction observations.
      if (next?.usernameFragment && this.generation?.usernameFragment &&
        next.usernameFragment !== this.generation.usernameFragment) {
        this.send(next);
      } else this.completeBatch(next);
      return;
    }

    if (
      this.batch &&
      this.generation?.usernameFragment &&
      next.usernameFragment &&
      next.usernameFragment !== this.generation.usernameFragment
    ) {
      // An ICE restart retires old observations; an unscoped end marker here
      // would end the new remote generation before its candidates arrive.
      this.discard();
    }
    if (!this.batch) {
      this.generation = next;
      this.endSent = false;
      this.batch = new NatPredictionCandidateBatch(this.send);
    }
    this.batch.add(next, this.enabled && predictionEligible);
  }

  gatheringComplete(): void {
    this.completeBatch();
  }

  discard(): void {
    this.batch?.discard();
    this.batch = null;
    this.generation = null;
    this.endSent = false;
  }

  private completeBatch(end: SignalCandidate = null): void {
    if (!this.batch) {
      if (!this.endSent && end?.usernameFragment) {
        this.send(end);
        this.generation = end;
        this.endSent = true;
      }
      return;
    }
    // An unscoped null applies to the latest remote ICE generation. Keep a
    // delayed end attached to the candidates that actually finished gathering.
    const marker = end?.usernameFragment ? end : this.generation?.usernameFragment
      ? { ...this.generation, candidate: "" } : null;
    this.batch.complete(marker);
    this.batch = null;
    this.endSent = true;
  }
}