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

18.9 KB
Raw Blame
import { describe, expect, it, vi } from "vitest";
import { punchIceConfig } from "../src/client/native/native-punch";

import {
  addRemoteIceCandidate,
  iceServersWithNatPrediction,
  isNativeNatSurveyCandidate,
  MAX_NAT_PREDICTION_CANDIDATES,
  NatPredictionCandidateBatch,
  NatPredictionCandidateEmitter,
  natPredictionSurveyUrls,
  predictSrflxCandidates,
  type SignalCandidate,
} from "../src/client/webrtc/nat-prediction.ts";

function candidate(port: number, address = "203.0.113.7"): SignalCandidate {
  return {
    candidate:
      `candidate:base 1 udp 2122260223 ${address} ${port} ` +
      "typ srflx raddr 192.0.2.7 rport 50000 generation 0 ufrag test",
    sdpMid: "0",
    sdpMLineIndex: 0,
    usernameFragment: "test",
  };
}

function hostCandidate(): SignalCandidate {
  return {
    candidate:
      "candidate:host 1 udp 2122260223 192.0.2.7 50000 typ host generation 0 ufrag test",
    sdpMid: "0",
    sdpMLineIndex: 0,
    usernameFragment: "test",
  };
}

function portOf(value: SignalCandidate): number {
  return Number(value?.candidate.trim().split(/\s+/)[5]);
}

function rtcCandidate(port: number): RTCIceCandidate {
  return {
    ...candidate(port),
  } as unknown as RTCIceCandidate;
}

describe("NAT prediction ICE adapter", () => {
  it("uses only explicit Native survey candidates as prediction evidence", () => {
    const iceConfig = {
      iceServers: [{ urls: ["stun:share.example.test:3478", "stun:other.example.test:3478"] }],
      natPredictionStunUrls: ["stun:share.example.test:3479", "stun:share.example.test:3480"],
    };
    const survey = candidate(40_000);
    if (survey) {
      survey.candidate = survey.candidate.replace(
        "candidate:base",
        "candidate:ns1",
      );
    }

    const eligible = (value: SignalCandidate) => isNativeNatSurveyCandidate(value, iceConfig.iceServers, iceConfig.natPredictionStunUrls);
    expect(eligible(survey)).toBe(true);
    for (const [index, expected] of [[2, false], [3, true], [4, true], [5, false], [0, false]] as const) {
      expect(eligible({ candidate: `candidate:ns${index} 1 udp 1 203.0.113.7 40000 typ srflx` })).toBe(expected);
    }
    expect(eligible(candidate(40_000))).toBe(false);
    expect(eligible(hostCandidate())).toBe(false);
  });

  it.each([
    { surveyPorts: [40_000, 40_003, 40_006], predictions: MAX_NAT_PREDICTION_CANDIDATES },
    { surveyPorts: [40_000, 40_000, 40_000], predictions: 0 },
  ])("retains survey identity before mapping deduplication: $surveyPorts", ({ surveyPorts, predictions }) => {
    const iceServers = [{ urls: ["stun:share.example.test:3478", "stun:other.example.test:3478"] }];
    const auxiliary = ["stun:share.example.test:3479", "stun:share.example.test:3480"];
    const send = vi.fn<(candidate: SignalCandidate) => void>();
    const batch = new NatPredictionCandidateBatch(send);
    // A faster ordinary destination shares the first survey mapping. All
    // destinations reach ICE, but only the actual survey can prove a pattern.
    const observations = [[2, 40_000], [1, surveyPorts[0]], [3, surveyPorts[1]], [4, surveyPorts[2]]];
    for (const [index, port] of observations) {
      const observation = candidate(port!)!;
      observation.candidate = observation.candidate.replace("candidate:base", `candidate:ns${index}`);
      batch.add(observation, isNativeNatSurveyCandidate(observation, iceServers, auxiliary));
    }
    batch.complete();
    const emitted = send.mock.calls.map(([value]) => value);
    expect(emitted.filter(value => /^candidate:ns/.test(value?.candidate ?? ""))).toHaveLength(4);
    expect(emitted.filter(value => /^candidate:s[pm]/.test(value?.candidate ?? ""))).toHaveLength(predictions);
    expect(emitted.at(-1)).toBeNull();
  });

  it("keeps unexpected ordinary-candidate failures visible", async () => {
    const error = new Error("candidate rejected");
    const connection = {
      addIceCandidate: vi.fn(async () => {
        throw error;
      }),
    } as unknown as RTCPeerConnection;
    const predicted = candidate(40_000);
    if (predicted) {
      predicted.candidate = predicted.candidate.replace(
        "candidate:base",
        "candidate:sp1",
      );
    }

    await expect(
      addRemoteIceCandidate(connection, predicted),
    ).resolves.toBeUndefined();
    await expect(
      addRemoteIceCandidate(connection, candidate(40_000)),
    ).rejects.toBe(error);
    await expect(addRemoteIceCandidate(connection, null)).rejects.toBe(error);
  });

  it("isolates candidate rejection without hiding a missing remote description", async () => {
    const connection = { addIceCandidate: vi.fn() } as unknown as RTCPeerConnection;
    vi.mocked(connection.addIceCandidate).mockRejectedValueOnce(new DOMException("Rejected", "OperationError"));
    await expect(addRemoteIceCandidate(connection, candidate(40_000))).resolves.toBeUndefined();
    const error = new DOMException("Remote description is missing", "InvalidStateError");
    vi.mocked(connection.addIceCandidate).mockRejectedValueOnce(error);
    await expect(addRemoteIceCandidate(connection, candidate(40_000))).rejects.toBe(error);
  });

  it("leaves the configured servers unchanged when disabled", () => {
    const servers = [
      { urls: ["stun:share.example.test:3478"] },
      { urls: "stun:other.example.test:5349" },
    ];

    expect(
      iceServersWithNatPrediction(
        servers,
        false,
        [
          "stun:share.example.test:3479",
          "stun:share.example.test:3480",
        ],
      ),
    ).toEqual(servers);
  });

  it("adds only the configured survey destinations", () => {
    const servers = [{ urls: "stun:share.example.test:3478" }];
    const auxiliary = [
      "stun:survey-a.example.test:3478",
      "stun:survey-b.example.test:3478",
    ];

    expect(
      iceServersWithNatPrediction(servers, true, auxiliary),
    ).toEqual([
      ...servers,
      { urls: "stun:survey-a.example.test:3478" },
      { urls: "stun:survey-b.example.test:3478" },
    ]);
    expect(
      natPredictionSurveyUrls(servers, auxiliary),
    ).toEqual(
      new Set([
        "stun:share.example.test:3478",
        "stun:survey-a.example.test:3478",
        "stun:survey-b.example.test:3478",
      ]),
    );
    expect(
      natPredictionSurveyUrls([
        { urls: "stun:share.example.test:5349" },
      ], auxiliary),
    ).toEqual(new Set([
      "stun:share.example.test:5349",
      ...auxiliary,
    ]));
  });

  it("does not invent auxiliary listeners that the server did not enable", () => {
    const servers = [
      { urls: ["stun:share.example.test:3478", "stun:share.example.test:3478"] },
      { urls: "stun:other.example.test:3478" },
    ];

    expect(iceServersWithNatPrediction(servers, true)).toEqual(servers);
    expect(natPredictionSurveyUrls(servers)).toEqual(new Set());
  });

  it("retains ordinary fallback discovery independently of prediction", () => {
    const urls = ["stun:primary.test:3478", "stun:fallback-a.test:3478", "stun:fallback-b.test:3478"];
    const servers = [{ urls }];
    const auxiliary = urls.slice(1);
    for (const enabled of [false, true]) {
      expect(iceServersWithNatPrediction(servers, enabled, auxiliary)).toEqual(servers);
    }
    expect(natPredictionSurveyUrls(servers, auxiliary)).toEqual(new Set(urls));
  });

  it("keeps auxiliary discovery entries from replacing the ordinary base", () => {
    const auxiliary = ["stun:site.test:3479", "stun:site.test:3480"];
    const urls = [...auxiliary, "stun:site.test:3478"];
    expect(natPredictionSurveyUrls([{ urls }], auxiliary)).toEqual(new Set([
      "stun:site.test:3478", ...auxiliary,
    ]));
    expect(natPredictionSurveyUrls([{ urls: auxiliary }], auxiliary)).toEqual(new Set());
  });

  it.each([
    ["stun:site.test:3479", "stun:site.test:3480"],
    ["stun:survey-a.test:3478", "stun:survey-b.test:3478"],
  ])("preserves the published base choice with non-default discovery first: %s", (...auxiliary) => {
    const servers = [{ urls: ["stun:discovery.test:19302", "stun:site.test:3478"] }];
    expect(natPredictionSurveyUrls(servers, auxiliary)).toEqual(new Set([
      "stun:site.test:3478", ...auxiliary,
    ]));
  });

  it("uses a non-default base when the remaining discovery URLs are the survey pair", () => {
    const urls = ["stun:primary.test:19302", "stun:survey-a.test:3478", "stun:survey-b.test:3478"];
    const servers = [{ urls }];
    const auxiliary = urls.slice(1, 3);
    expect(natPredictionSurveyUrls(servers, auxiliary)).toEqual(new Set(urls.slice(0, 3)));
    expect(punchIceConfig({ iceServers: servers, natPredictionStunUrls: auxiliary })).toEqual({
      iceServers: [{ urls: urls.slice(0, 3) }],
    });

    const send = vi.fn<(candidate: SignalCandidate) => void>();
    const batch = new NatPredictionCandidateBatch(send);
    for (const [index, port] of [[1, 40_000], [2, 40_003], [3, 40_006]]) {
      const observation = candidate(port!)!;
      observation.candidate = observation.candidate.replace("candidate:base", `candidate:ns${index}`);
      const eligible = isNativeNatSurveyCandidate(observation, servers, auxiliary);
      expect(eligible).toBe(true);
      batch.add(observation, eligible);
    }
    batch.complete();
    const emitted = send.mock.calls.map(([value]) => value);
    expect(emitted.filter(value => /^candidate:ns/.test(value?.candidate ?? ""))).toHaveLength(3);
    expect(emitted.filter(value => /^candidate:s[pm]/.test(value?.candidate ?? ""))).toHaveLength(MAX_NAT_PREDICTION_CANDIDATES);
    expect(emitted.at(-1)).toBeNull();
  });

  it.each([
    ["stun:Share.TEST", "stun:share.test:3478"],
    ["STUN:Share.TEST:03478", "stun:share.test:3478"],
    ["stun:[2001:DB8::1]:3478", "stun:[2001:db8::1]:3478"],
    ["stun:share.test:80", "stun:share.test:80"],
    ["stun:share.test:00080", "stun:share.test:80"],
    ["stun:share.test:443", "stun:share.test:443"],
  ] as const)("preserves the STUN port in survey membership for %s", (url, base) => {
    const auxiliary = ["stun:survey.test:80", "stun:survey.test:443"];
    expect(natPredictionSurveyUrls([{ urls: url }], auxiliary)).toEqual(
      new Set([base, ...auxiliary]),
    );
  });

  it("keeps a port-80 auxiliary distinct from the ordinary base endpoint", () => {
    const servers = [{ urls: "stun:share.test:3478" }];
    expect(iceServersWithNatPrediction(servers, true, [
      "stun:share.test:00080",
      "stun:share.test:3480",
    ])).toEqual([
      ...servers,
      { urls: "stun:share.test:00080" },
      { urls: "stun:share.test:3480" },
    ]);
  });

  it("does not duplicate already configured auxiliary listeners", () => {
    const servers = [
      { urls: "stun:share.example.test:3478" },
      { urls: "stun:share.example.test:3479" },
    ];

    expect(iceServersWithNatPrediction(servers, true, [
      "stun:share.example.test:3479",
      "stun:share.example.test:3480",
    ])).toEqual([
      ...servers,
      { urls: "stun:share.example.test:3480" },
    ]);
  });

  it("predicts a bounded two-sided window for a stable arithmetic shape", () => {
    const predictions = predictSrflxCandidates([
      candidate(40_000),
      candidate(40_003),
      candidate(40_006),
    ]);

    expect(predictions).toHaveLength(MAX_NAT_PREDICTION_CANDIDATES);
    expect(predictions.map(portOf)).toEqual([
      40_009,
      40_012,
      40_015,
      40_018,
      39_997,
      39_994,
      39_991,
      39_988,
    ]);
    expect(predictions.every((value) => value?.sdpMid === "0")).toBe(true);
  });

  it("anchors on the port sequence extreme when responses arrive reversed", () => {
    const predictions = predictSrflxCandidates([
      candidate(40_006),
      candidate(40_003),
      candidate(40_000),
    ]);

    expect(predictions.map(portOf)).toEqual([
      40_009,
      40_012,
      40_015,
      40_018,
      39_997,
      39_994,
      39_991,
      39_988,
    ]);
  });

  it.each([
    ["component", "base 1 udp", "base 2 udp"],
    ["address", "raddr 192.0.2.7", "raddr 192.0.2.8"],
    ["port", "rport 50000", "rport 50001"],
  ] as const)("keeps the prediction budget when a different base %s interrupts the survey", (_, from, to) => {
    const sent: SignalCandidate[] = [];
    const batch = new NatPredictionCandidateBatch(value => sent.push(value));
    const first = candidate(40_000)!;
    const second = candidate(40_003)!;
    const third = candidate(40_006)!;
    const unrelated = { ...third, candidate: third.candidate.replace(from, to) };
    batch.add(first);
    batch.add(second);
    batch.add(unrelated);
    expect(sent).toEqual([first, second, unrelated]);

    // A later observation from the original base can still use this
    // generation's budget; the unrelated one must not consume it first.
    batch.add(third);
    expect(sent.filter(value => /^candidate:s[pm]/.test(value?.candidate ?? "")))
      .toHaveLength(MAX_NAT_PREDICTION_CANDIDATES);
    expect(sent.filter(value => !/^candidate:s[pm]/.test(value?.candidate ?? "")))
      .toEqual([first, second, unrelated, third]);
  });

  it("retains bounded prediction when the Browser conceals related addresses", () => {
    const concealed = [40_000, 40_003, 40_006].map(port => {
      const value = candidate(port)!;
      return { ...value, candidate: value.candidate.replace("raddr 192.0.2.7 rport 50000", "raddr 0.0.0.0 rport 0") };
    });
    expect(predictSrflxCandidates(concealed)).toHaveLength(MAX_NAT_PREDICTION_CANDIDATES);
  });

  it("does not predict an unstable or incomplete mapping shape", () => {
    expect(predictSrflxCandidates([candidate(40_000), candidate(40_001)])).toEqual(
      [],
    );
    expect(
      predictSrflxCandidates([
        candidate(40_000),
        candidate(40_003),
        candidate(40_011),
      ]),
    ).toEqual([]);
  });

  it("appends predictions without delaying or replacing ordinary candidates", () => {
    const sent: Array<SignalCandidate | null> = [];
    const batch = new NatPredictionCandidateBatch((value) => sent.push(value));
    const first = candidate(40_000);
    const second = candidate(40_003);
    const third = candidate(40_006);

    batch.add(hostCandidate());
    batch.add(first);
    batch.add(second);
    expect(sent).toEqual([hostCandidate(), first, second]);
    batch.add(third);
    batch.complete();
    batch.complete();

    expect(sent[0]).toEqual(hostCandidate());
    const firstPrediction = sent.findIndex(
      (value) => value?.candidate.includes("candidate:s") ?? false,
    );
    expect(firstPrediction).toBeGreaterThan(sent.indexOf(second));
    expect(firstPrediction).toBeLessThan(sent.indexOf(third));
    expect(sent.filter((value) => value === first)).toHaveLength(1);
    expect(sent.filter((value) => value === second)).toHaveLength(1);
    expect(sent.filter((value) => value === third)).toHaveLength(1);
    expect(sent.at(-1)).toBeNull();
  });

  it("flushes ordinary candidates without inventing a prediction", () => {
    const sent: Array<SignalCandidate | null> = [];
    const batch = new NatPredictionCandidateBatch((value) => sent.push(value));
    const first = candidate(40_000);
    const second = candidate(40_007);

    batch.add(first);
    batch.add(second);
    batch.complete();

    expect(sent).toEqual([first, second, null]);
  });

  it("does not wait for auxiliary gathering before sending stock srflx", () => {
    const sent: Array<SignalCandidate | null> = [];
    const batch = new NatPredictionCandidateBatch((value) => sent.push(value));
    const first = candidate(40_000);

    batch.add(first);

    expect(sent).toEqual([first]);
  });

  it("forwards an ineligible srflx candidate without using it as sequence evidence", () => {
    const sent: Array<SignalCandidate | null> = [];
    const batch = new NatPredictionCandidateBatch((value) => sent.push(value));
    const external = candidate(50_000);

    batch.add(external, false);
    batch.add(candidate(40_000));
    batch.add(candidate(40_003));
    batch.add(candidate(40_006));

    expect(sent[0]).toEqual(external);
    expect(
      sent.some((value) => value?.candidate.startsWith("candidate:sp")),
    ).toBe(true);
  });

  it("does not predict when the Browser omits candidate source URLs", () => {
    const sent: Array<SignalCandidate | null> = [];
    const emitter = new NatPredictionCandidateEmitter(
      true,
      (value) => sent.push(value),
      new Set([
        "stun:share.example.test:3478",
        "stun:survey-a.example.test:3478",
        "stun:survey-b.example.test:3478",
      ]),
    );

    emitter.add(rtcCandidate(40_000));
    emitter.add(rtcCandidate(40_003));
    emitter.add(rtcCandidate(40_006));
    emitter.gatheringComplete();

    expect(
      sent.some((value) => value?.candidate.startsWith("candidate:sp")),
    ).toBe(false);
    expect(sent.filter((value) => value?.candidate)).toHaveLength(3);
  });

  it("retires an unfinished generation without ending the restarted ICE session", () => {
    const sent: SignalCandidate[] = [];
    const survey = [
      "stun:share.example.test:19302",
      "stun:survey-a.example.test:3478",
      "stun:survey-b.example.test:3478",
    ];
    const emitter = new NatPredictionCandidateEmitter(
      true,
      (value) => sent.push(value),
      natPredictionSurveyUrls([{ urls: survey }], survey.slice(1)),
    );
    const emit = (port: number, usernameFragment: string, url: string) => {
      emitter.add({
        ...candidate(port),
        usernameFragment,
        url,
      } as unknown as RTCIceCandidate);
    };

    emit(40_000, "previous", survey[0]!);
    emit(40_003, "previous", survey[1]!);
    emit(40_006, "restarted", survey[0]!);
    expect(sent).toHaveLength(3);
    expect(sent.every((value) => value !== null)).toBe(true);

    emit(40_009, "restarted", survey[1]!);
    emit(40_012, "restarted", survey[2]!);
    const predictions = sent.filter((value) =>
      value?.candidate.startsWith("candidate:sp") ||
      value?.candidate.startsWith("candidate:sm"),
    );
    expect(predictions).toHaveLength(MAX_NAT_PREDICTION_CANDIDATES);
    expect(predictions.every((value) => value?.usernameFragment === "restarted")).toBe(true);

    emitter.gatheringComplete();
    emitter.add(null);
    expect(sent.filter((value) => value?.candidate === "")).toHaveLength(1);
    expect(sent.at(-1)).toMatchObject({ candidate: "", usernameFragment: "restarted" });
    expect(sent).not.toContain(null);
  });

  it("keeps a delayed scoped end from completing another generation", () => {
    const sent: SignalCandidate[] = [];
    const emitter = new NatPredictionCandidateEmitter(true, value => sent.push(value));
    const emit = (port: number) => emitter.addSignal({ ...candidate(port)!, usernameFragment: "current" }, true);
    emit(40_000);
    emitter.addSignal({ candidate: "", usernameFragment: "previous" }, false);
    emit(40_003);
    emit(40_006);
    emitter.gatheringComplete();
    emitter.add(null);
    expect(sent.filter(value => value?.candidate.startsWith("candidate:sp") ||
      value?.candidate.startsWith("candidate:sm"))).toHaveLength(MAX_NAT_PREDICTION_CANDIDATES);
    expect(sent.filter(value => value?.candidate === "").map(value => value?.usernameFragment)).toEqual(["previous", "current"]);
  });
});