@networkdiagnostics/sdk 0.1.0-pre.1

package/dist/react/index.d.cts

@@ -0,0 +1,113 @@
+/**
+ * UDP throughput probe session. Returned by the customer's backend from
+ * `POST /v1/probe/udp/sessions` on api.networktests.com.
+ *
+ * The frontend passes this to `nt.runUdpTest(session)`.
+ */
+interface UdpSession {
+    /** Opaque session ticket. Single-use; valid for ~30 minutes. */
+    sessionId: string;
+    /** WebSocket URL the SDK must connect to (region-pinned). */
+    wsUrl: string;
+    /** ICE servers to seed the RTCPeerConnection. Server may override via `welcome` message. */
+    iceServers?: RTCIceServer[];
+    /** Test duration in seconds (defaults to server config). */
+    duration?: number;
+    /** Packet rate (packets per second). */
+    rate?: number;
+    /** Packet size in bytes (max 1400). */
+    packetSize?: number;
+}
+/**
+ * DNS leak probe session. Returned by `POST /v1/probe/dns-leak/sessions`.
+ *
+ * The SDK iterates `fqdns` and triggers DNS resolution of each one. Our
+ * authoritative DNS server records which recursive resolver did the
+ * lookup; the customer's backend later calls
+ * `GET /v1/probe/dns-leak/sessions/:id` to retrieve the resolver list.
+ */
+interface DnsLeakSession {
+    sessionId: string;
+    fqdns: string[];
+}
+interface LatencyStats {
+    /** Mean RTT in milliseconds. */
+    avg: number;
+    min: number;
+    max: number;
+    /** 50th percentile. */
+    p50: number;
+    /** 95th percentile. */
+    p95: number;
+    /** Down-sampled to 200 evenly-spaced points across the full test. */
+    samples?: number[];
+}
+interface UdpResult {
+    sessionId: string;
+    packetsSent: number;
+    packetsReceived: number;
+    packetsLost: number;
+    /** Packet loss percentage (0-100). */
+    lossPercent: number;
+    /** Inter-packet arrival jitter, in ms. */
+    jitter: number;
+    latency: LatencyStats;
+    /** Total test duration in ms (wall clock from WS open to result). */
+    durationMs: number;
+    completedAt: string;
+}
+interface UdpProgress {
+    packetsSent: number;
+    packetsReceived: number;
+    lossPercent: number;
+    elapsedMs: number;
+}
+interface RunUdpOptions {
+    /** Per-packet progress callback. Fires ~10x/sec, debounced. */
+    onProgress?: (progress: UdpProgress) => void;
+    /** AbortSignal — abort cancels the test cleanly (closes WS + DC). */
+    signal?: AbortSignal;
+    /** Hard timeout in ms. Defaults to (session.duration + 10) * 1000. */
+    timeoutMs?: number;
+}
+interface RunDnsLeakOptions {
+    /** Called after each FQDN trigger resolves or errors. */
+    onResolved?: (fqdn: string) => void;
+    /** AbortSignal — cancels any in-flight image/fetch triggers. */
+    signal?: AbortSignal;
+    /** Hard timeout in ms. Default 15000. */
+    timeoutMs?: number;
+}
+
+interface UseUdpTestState {
+    result: UdpResult | null;
+    error: Error | null;
+    isRunning: boolean;
+    progress: UdpProgress | null;
+}
+interface UseUdpTestApi extends UseUdpTestState {
+    /** Start the test. Throws if already running. */
+    run: (session: UdpSession, options?: Omit<RunUdpOptions, "onProgress" | "signal">) => Promise<UdpResult>;
+    /** Abort an in-flight test. No-op if idle. */
+    cancel: () => void;
+    /** Reset state to initial. */
+    reset: () => void;
+}
+declare function useUdpTest(): UseUdpTestApi;
+
+interface UseDnsLeakTestState {
+    isRunning: boolean;
+    error: Error | null;
+    /** FQDNs that have been triggered (server-side resolver list is separate). */
+    resolved: string[];
+    /** True once all FQDNs have been triggered. */
+    complete: boolean;
+}
+interface UseDnsLeakTestApi extends UseDnsLeakTestState {
+    run: (session: DnsLeakSession, options?: Omit<RunDnsLeakOptions, "onResolved" | "signal">) => Promise<void>;
+    cancel: () => void;
+    reset: () => void;
+}
+declare function useDnsLeakTest(): UseDnsLeakTestApi;
+
+export { type UseDnsLeakTestApi, type UseDnsLeakTestState, type UseUdpTestApi, type UseUdpTestState, useDnsLeakTest, useUdpTest };

package/dist/react/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * UDP throughput probe session. Returned by the customer's backend from
+ * `POST /v1/probe/udp/sessions` on api.networktests.com.
+ *
+ * The frontend passes this to `nt.runUdpTest(session)`.
+ */
+interface UdpSession {
+    /** Opaque session ticket. Single-use; valid for ~30 minutes. */
+    sessionId: string;
+    /** WebSocket URL the SDK must connect to (region-pinned). */
+    wsUrl: string;
+    /** ICE servers to seed the RTCPeerConnection. Server may override via `welcome` message. */
+    iceServers?: RTCIceServer[];
+    /** Test duration in seconds (defaults to server config). */
+    duration?: number;
+    /** Packet rate (packets per second). */
+    rate?: number;
+    /** Packet size in bytes (max 1400). */
+    packetSize?: number;
+}
+/**
+ * DNS leak probe session. Returned by `POST /v1/probe/dns-leak/sessions`.
+ *
+ * The SDK iterates `fqdns` and triggers DNS resolution of each one. Our
+ * authoritative DNS server records which recursive resolver did the
+ * lookup; the customer's backend later calls
+ * `GET /v1/probe/dns-leak/sessions/:id` to retrieve the resolver list.
+ */
+interface DnsLeakSession {
+    sessionId: string;
+    fqdns: string[];
+}
+interface LatencyStats {
+    /** Mean RTT in milliseconds. */
+    avg: number;
+    min: number;
+    max: number;
+    /** 50th percentile. */
+    p50: number;
+    /** 95th percentile. */
+    p95: number;
+    /** Down-sampled to 200 evenly-spaced points across the full test. */
+    samples?: number[];
+}
+interface UdpResult {
+    sessionId: string;
+    packetsSent: number;
+    packetsReceived: number;
+    packetsLost: number;
+    /** Packet loss percentage (0-100). */
+    lossPercent: number;
+    /** Inter-packet arrival jitter, in ms. */
+    jitter: number;
+    latency: LatencyStats;
+    /** Total test duration in ms (wall clock from WS open to result). */
+    durationMs: number;
+    completedAt: string;
+}
+interface UdpProgress {
+    packetsSent: number;
+    packetsReceived: number;
+    lossPercent: number;
+    elapsedMs: number;
+}
+interface RunUdpOptions {
+    /** Per-packet progress callback. Fires ~10x/sec, debounced. */
+    onProgress?: (progress: UdpProgress) => void;
+    /** AbortSignal — abort cancels the test cleanly (closes WS + DC). */
+    signal?: AbortSignal;
+    /** Hard timeout in ms. Defaults to (session.duration + 10) * 1000. */
+    timeoutMs?: number;
+}
+interface RunDnsLeakOptions {
+    /** Called after each FQDN trigger resolves or errors. */
+    onResolved?: (fqdn: string) => void;
+    /** AbortSignal — cancels any in-flight image/fetch triggers. */
+    signal?: AbortSignal;
+    /** Hard timeout in ms. Default 15000. */
+    timeoutMs?: number;
+}
+
+interface UseUdpTestState {
+    result: UdpResult | null;
+    error: Error | null;
+    isRunning: boolean;
+    progress: UdpProgress | null;
+}
+interface UseUdpTestApi extends UseUdpTestState {
+    /** Start the test. Throws if already running. */
+    run: (session: UdpSession, options?: Omit<RunUdpOptions, "onProgress" | "signal">) => Promise<UdpResult>;
+    /** Abort an in-flight test. No-op if idle. */
+    cancel: () => void;
+    /** Reset state to initial. */
+    reset: () => void;
+}
+declare function useUdpTest(): UseUdpTestApi;
+
+interface UseDnsLeakTestState {
+    isRunning: boolean;
+    error: Error | null;
+    /** FQDNs that have been triggered (server-side resolver list is separate). */
+    resolved: string[];
+    /** True once all FQDNs have been triggered. */
+    complete: boolean;
+}
+interface UseDnsLeakTestApi extends UseDnsLeakTestState {
+    run: (session: DnsLeakSession, options?: Omit<RunDnsLeakOptions, "onResolved" | "signal">) => Promise<void>;
+    cancel: () => void;
+    reset: () => void;
+}
+declare function useDnsLeakTest(): UseDnsLeakTestApi;
+
+export { type UseDnsLeakTestApi, type UseDnsLeakTestState, type UseUdpTestApi, type UseUdpTestState, useDnsLeakTest, useUdpTest };

package/dist/react/index.mjs

@@ -0,0 +1,478 @@
+import { useState, useRef, useCallback } from 'react';
+
+// src/react/useUdpTest.ts
+
+// src/errors.ts
+var NetworkTestsError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "NetworkTestsError";
+    this.code = code;
+  }
+};
+var AbortError = class extends NetworkTestsError {
+  constructor(message = "Operation aborted") {
+    super("ABORTED", message);
+    this.name = "AbortError";
+  }
+};
+var TimeoutError = class extends NetworkTestsError {
+  constructor(message = "Operation timed out") {
+    super("TIMEOUT", message);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/udp/webrtc.ts
+function createPeerConnection(iceServers) {
+  return new RTCPeerConnection({ iceServers });
+}
+function setupDataChannel(pc) {
+  const channel = pc.createDataChannel("test", { ordered: false });
+  const ready = new Promise((resolve, reject) => {
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new NetworkTestsError("DC_ERROR", "DataChannel error before open"));
+    };
+    const onClose = () => {
+      cleanup();
+      reject(new NetworkTestsError("DC_CLOSED", "DataChannel closed before open"));
+    };
+    function cleanup() {
+      channel.removeEventListener("open", onOpen);
+      channel.removeEventListener("error", onError);
+      channel.removeEventListener("close", onClose);
+    }
+    channel.addEventListener("open", onOpen);
+    channel.addEventListener("error", onError);
+    channel.addEventListener("close", onClose);
+  });
+  return { channel, ready };
+}
+async function createOffer(pc) {
+  const offer = await pc.createOffer();
+  await pc.setLocalDescription(offer);
+  return offer;
+}
+async function applyAnswer(pc, sdp) {
+  await pc.setRemoteDescription({ type: "answer", sdp });
+}
+
+// src/udp/packetLoop.ts
+function startPacketLoop(opts) {
+  const { channel, onProgress } = opts;
+  const progressMs = opts.progressIntervalMs ?? 100;
+  const startTs = Date.now();
+  let received = 0;
+  let highestSeq = -1;
+  let stopped = false;
+  const onMsg = (ev) => {
+    if (stopped) return;
+    try {
+      const msg = JSON.parse(ev.data);
+      if (msg && msg.type === "packet" && typeof msg.seq === "number") {
+        received++;
+        if (msg.seq > highestSeq) highestSeq = msg.seq;
+        try {
+          channel.send(JSON.stringify({ type: "ack", seq: msg.seq }));
+        } catch {
+        }
+      }
+    } catch {
+    }
+  };
+  channel.addEventListener("message", onMsg);
+  let progressTimer = null;
+  if (onProgress) {
+    progressTimer = setInterval(() => {
+      if (stopped) return;
+      const sent = highestSeq + 1;
+      const loss = sent > 0 ? (sent - received) / sent * 100 : 0;
+      onProgress({
+        packetsSent: sent,
+        packetsReceived: received,
+        lossPercent: Math.round(loss * 100) / 100,
+        elapsedMs: Date.now() - startTs
+      });
+    }, progressMs);
+  }
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      channel.removeEventListener("message", onMsg);
+      if (progressTimer) clearInterval(progressTimer);
+    }
+  };
+}
+
+// src/udp/signaling.ts
+function isServerMsg(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+
+// src/udp/index.ts
+var DEFAULT_ICE_SERVERS = [
+  { urls: "stun:stun.l.google.com:19302" }
+];
+async function runUdpTest(session, options = {}) {
+  const startedAt = Date.now();
+  const { signal, onProgress } = options;
+  const timeoutMs = options.timeoutMs ?? ((session.duration ?? 30) + 10) * 1e3;
+  if (signal?.aborted) throw new AbortError();
+  const ws = new WebSocket(session.wsUrl);
+  ws.binaryType = "arraybuffer";
+  let pc = null;
+  let dataChannel = null;
+  let packetLoop = null;
+  let timeoutHandle = null;
+  let abortHandler = null;
+  const cleanup = () => {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
+    packetLoop?.stop();
+    try {
+      dataChannel?.close();
+    } catch {
+    }
+    try {
+      pc?.close();
+    } catch {
+    }
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const fail = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const succeed = (result) => {
+      cleanup();
+      resolve(result);
+    };
+    timeoutHandle = setTimeout(
+      () => fail(new TimeoutError(`UDP test exceeded ${timeoutMs}ms`)),
+      timeoutMs
+    );
+    if (signal) {
+      abortHandler = () => fail(new AbortError());
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }
+    const send = (msg) => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+    };
+    ws.addEventListener(
+      "error",
+      () => fail(new NetworkTestsError("WS_ERROR", "WebSocket error"))
+    );
+    ws.addEventListener("close", (ev) => {
+      if (ws.readyState === WebSocket.CLOSED) {
+        const reason = ev.reason || `WebSocket closed (code ${ev.code})`;
+        fail(new NetworkTestsError("WS_CLOSED", reason));
+      }
+    });
+    ws.addEventListener("open", async () => {
+    });
+    ws.addEventListener("message", async (ev) => {
+      let msg;
+      try {
+        msg = JSON.parse(String(ev.data));
+      } catch {
+        return;
+      }
+      if (!isServerMsg(msg)) return;
+      const m = msg;
+      try {
+        switch (m.type) {
+          case "welcome": {
+            const iceServers = [
+              ...session.iceServers ?? DEFAULT_ICE_SERVERS
+            ];
+            if (m.turn) {
+              iceServers.push({
+                urls: m.turn.urls,
+                username: m.turn.username,
+                credential: m.turn.credential
+              });
+            }
+            pc = createPeerConnection(iceServers);
+            pc.addEventListener("icecandidate", (e) => {
+              if (e.candidate) {
+                send({ type: "ice-candidate", candidate: e.candidate.toJSON() });
+              }
+            });
+            const dcSetup = setupDataChannel(pc);
+            dataChannel = dcSetup.channel;
+            const offer = await createOffer(pc);
+            send({ type: "offer", sdp: offer.sdp ?? "" });
+            dcSetup.ready.then(() => send({ type: "datachannel-ready" })).catch((err) => fail(toError(err)));
+            break;
+          }
+          case "answer": {
+            if (!pc) throw new NetworkTestsError("BAD_STATE", "answer before welcome");
+            await applyAnswer(pc, m.sdp.sdp);
+            break;
+          }
+          case "ice-candidate": {
+            if (!pc) return;
+            try {
+              await pc.addIceCandidate(m.candidate);
+            } catch {
+            }
+            break;
+          }
+          case "datachannel-open": {
+            if (!dataChannel) throw new NetworkTestsError("BAD_STATE", "no DC");
+            packetLoop = startPacketLoop({ channel: dataChannel, onProgress });
+            send({
+              type: "start-packet-test",
+              duration: session.duration,
+              rate: session.rate,
+              packetSize: session.packetSize
+            });
+            break;
+          }
+          case "test-started":
+            break;
+          case "test-complete": {
+            const r = m.results;
+            succeed({
+              sessionId: session.sessionId,
+              packetsSent: r.packetsSent,
+              packetsReceived: r.packetsReceived,
+              packetsLost: r.packetsLost,
+              lossPercent: r.lossPercent,
+              jitter: r.jitter,
+              latency: {
+                avg: r.latency.avg,
+                min: r.latency.min,
+                max: r.latency.max,
+                p50: r.latency.p50,
+                p95: r.latency.p95,
+                samples: r.latency.samples
+              },
+              durationMs: Date.now() - startedAt,
+              completedAt: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            break;
+          }
+          case "test-stopped":
+            fail(new NetworkTestsError("TEST_STOPPED", "Server stopped the test"));
+            break;
+          case "error":
+            fail(new NetworkTestsError("SERVER_ERROR", m.message));
+            break;
+        }
+      } catch (err) {
+        fail(toError(err));
+      }
+    });
+  });
+}
+function toError(value) {
+  if (value instanceof Error) return value;
+  return new NetworkTestsError("UNKNOWN", String(value));
+}
+
+// src/react/useUdpTest.ts
+var INITIAL = {
+  result: null,
+  error: null,
+  isRunning: false,
+  progress: null
+};
+function useUdpTest() {
+  const [state, setState] = useState(INITIAL);
+  const abortRef = useRef(null);
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setState(INITIAL);
+  }, []);
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+  const run = useCallback(async (session, options) => {
+    abortRef.current?.abort();
+    const ctrl = new AbortController();
+    abortRef.current = ctrl;
+    setState({ ...INITIAL, isRunning: true });
+    try {
+      const result = await runUdpTest(session, {
+        ...options,
+        signal: ctrl.signal,
+        onProgress: (progress) => {
+          setState((s) => s.isRunning ? { ...s, progress } : s);
+        }
+      });
+      setState({ result, error: null, isRunning: false, progress: null });
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState({ result: null, error, isRunning: false, progress: null });
+      throw error;
+    } finally {
+      if (abortRef.current === ctrl) abortRef.current = null;
+    }
+  }, []);
+  return { ...state, run, cancel, reset };
+}
+
+// src/dnsleak/trigger.ts
+var ABORT_AFTER_MS = 5e3;
+function triggerDnsResolution(fqdn, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  if (typeof Image !== "undefined") {
+    return triggerViaImage(fqdn, signal);
+  }
+  return triggerViaFetch(fqdn, signal);
+}
+function triggerViaImage(fqdn, signal) {
+  return new Promise((resolve) => {
+    const img = new Image();
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      img.src = "";
+      resolve();
+    };
+    const onAbort = () => finish();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(finish, ABORT_AFTER_MS);
+    img.onload = () => {
+      clearTimeout(timer);
+      finish();
+    };
+    img.onerror = () => {
+      clearTimeout(timer);
+      finish();
+    };
+    img.src = `https://${fqdn}/_/leak.gif?t=${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  });
+}
+function triggerViaFetch(fqdn, signal) {
+  const controller = new AbortController();
+  const abortSignal = signal ? mergeSignals(signal, controller.signal) : controller.signal;
+  const timer = setTimeout(() => controller.abort(), ABORT_AFTER_MS);
+  return fetch(`https://${fqdn}/_/leak?t=${Date.now()}`, {
+    method: "GET",
+    mode: "no-cors",
+    cache: "no-store",
+    signal: abortSignal
+  }).catch(() => void 0).finally(() => clearTimeout(timer)).then(() => void 0);
+}
+function mergeSignals(a, b) {
+  const c = new AbortController();
+  const onAbort = () => c.abort();
+  if (a.aborted || b.aborted) c.abort();
+  else {
+    a.addEventListener("abort", onAbort, { once: true });
+    b.addEventListener("abort", onAbort, { once: true });
+  }
+  return c.signal;
+}
+
+// src/dnsleak/index.ts
+async function runDnsLeakTest(session, options = {}) {
+  if (options.signal?.aborted) throw new AbortError();
+  const timeoutMs = options.timeoutMs ?? 15e3;
+  let timeoutHandle = null;
+  const timeoutController = new AbortController();
+  const combinedSignal = mergeSignals2(options.signal, timeoutController.signal);
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      timeoutController.abort();
+      reject(new TimeoutError(`DNS-leak test exceeded ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  const abortPromise = new Promise((_, reject) => {
+    options.signal?.addEventListener(
+      "abort",
+      () => reject(new AbortError()),
+      { once: true }
+    );
+  });
+  const triggers = session.fqdns.map(
+    (fqdn) => triggerDnsResolution(fqdn, combinedSignal).then(() => {
+      options.onResolved?.(fqdn);
+    })
+  );
+  try {
+    await Promise.race([
+      Promise.all(triggers),
+      timeoutPromise,
+      abortPromise
+    ]);
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+}
+function mergeSignals2(a, b) {
+  if (!a) return b;
+  const c = new AbortController();
+  if (a.aborted || b.aborted) c.abort();
+  else {
+    a.addEventListener("abort", () => c.abort(), { once: true });
+    b.addEventListener("abort", () => c.abort(), { once: true });
+  }
+  return c.signal;
+}
+
+// src/react/useDnsLeakTest.ts
+var INITIAL2 = {
+  isRunning: false,
+  error: null,
+  resolved: [],
+  complete: false
+};
+function useDnsLeakTest() {
+  const [state, setState] = useState(INITIAL2);
+  const abortRef = useRef(null);
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setState(INITIAL2);
+  }, []);
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+  const run = useCallback(async (session, options) => {
+    abortRef.current?.abort();
+    const ctrl = new AbortController();
+    abortRef.current = ctrl;
+    setState({ ...INITIAL2, isRunning: true });
+    try {
+      await runDnsLeakTest(session, {
+        ...options,
+        signal: ctrl.signal,
+        onResolved: (fqdn) => {
+          setState(
+            (s) => s.isRunning ? { ...s, resolved: [...s.resolved, fqdn] } : s
+          );
+        }
+      });
+      setState((s) => ({ ...s, isRunning: false, complete: true }));
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState((s) => ({ ...s, isRunning: false, error }));
+      throw error;
+    } finally {
+      if (abortRef.current === ctrl) abortRef.current = null;
+    }
+  }, []);
+  return { ...state, run, cancel, reset };
+}
+
+export { useDnsLeakTest, useUdpTest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map