@specific.dev/spectest 0.89.0 → 0.90.0

package/src/harness/ws-bridge.test.ts

@@ -0,0 +1,224 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+
+import {
+  WS_BRIDGE_HANDLERS,
+  openUpstreamWebSocket,
+  parseSubprotocols,
+  upstreamHandshakeHeaders,
+  type WsBridgeData,
+} from "./ws-bridge";
+
+describe("parseSubprotocols", () => {
+  test("splits, trims, drops empty tokens, keeps order", () => {
+    expect(parseSubprotocols("console, ticket-abc")).toEqual(["console", "ticket-abc"]);
+    expect(parseSubprotocols(" a ,, b ,")).toEqual(["a", "b"]);
+    expect(parseSubprotocols(null)).toEqual([]);
+    expect(parseSubprotocols("")).toEqual([]);
+  });
+});
+
+describe("upstreamHandshakeHeaders", () => {
+  test("forwards cookies and origin, drops the client's handshake fields, stamps provenance", () => {
+    const req = new Headers({
+      host: "api.prod.specific.dev",
+      connection: "Upgrade",
+      upgrade: "websocket",
+      "sec-websocket-key": "abc==",
+      "sec-websocket-version": "13",
+      "sec-websocket-protocol": "console, ticket",
+      "sec-websocket-extensions": "permessage-deflate",
+      cookie: "sid=1",
+      origin: "https://app.test",
+      authorization: "Bearer t",
+    });
+    const out = upstreamHandshakeHeaders(req, {
+      service: "api",
+      port: 4000,
+      proto: "https",
+      clientIp: "10.0.0.7",
+    });
+    expect(out["cookie"]).toBe("sid=1");
+    expect(out["origin"]).toBe("https://app.test");
+    expect(out["authorization"]).toBe("Bearer t");
+    expect(out["host"]).toBe("api:4000");
+    expect(out["x-forwarded-host"]).toBe("api.prod.specific.dev");
+    expect(out["x-forwarded-proto"]).toBe("https");
+    expect(out["x-forwarded-for"]).toBe("10.0.0.7");
+    for (const k of Object.keys(out)) {
+      expect(k.startsWith("sec-websocket-")).toBe(false);
+      expect(["connection", "upgrade"]).not.toContain(k);
+    }
+  });
+
+  test("appends the client to an existing x-forwarded-for", () => {
+    const out = upstreamHandshakeHeaders(new Headers({ "x-forwarded-for": "1.2.3.4" }), {
+      service: "api",
+      port: 1,
+      proto: "http",
+      clientIp: "10.0.0.7",
+    });
+    expect(out["x-forwarded-for"]).toBe("1.2.3.4, 10.0.0.7");
+  });
+});
+
+/**
+ * A loopback copy of the daemon's arrangement: an upstream that admits a
+ * connection only when the SECOND subprotocol is the ticket (the shape of
+ * Specific's console API), a bridge listener in front of it that does what
+ * `proxyToService` does, and a client through the bridge.
+ */
+describe("the bridge on loopback", () => {
+  let upstream: ReturnType<typeof Bun.serve>;
+  let bridge: ReturnType<typeof Bun.serve>;
+  /** What the upstream saw on its last handshake. */
+  let seen: { protocols: string[]; cookie: string | null; xfh: string | null } | null = null;
+
+  beforeAll(() => {
+    upstream = Bun.serve({
+      port: 0,
+      fetch(req, server) {
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        seen = {
+          protocols,
+          cookie: req.headers.get("cookie"),
+          xfh: req.headers.get("x-forwarded-host"),
+        };
+        if (protocols[1] !== "ticket-ok") return new Response("Unauthorized", { status: 401 });
+        const ok = server.upgrade(req, {
+          headers: { "sec-websocket-protocol": protocols[0] },
+          data: { admitted: protocols[1] },
+        });
+        return ok ? undefined : new Response("refused", { status: 426 });
+      },
+      websocket: {
+        open(ws) {
+          ws.send("ready");
+        },
+        message(ws, m) {
+          if (typeof m === "string") {
+            if (m === "close-me") ws.close(4402, "app said so");
+            else ws.send(`echo:${m}`);
+          } else {
+            ws.send(new Uint8Array(m).reverse());
+          }
+        },
+      },
+    });
+
+    bridge = Bun.serve({
+      port: 0,
+      async fetch(req, server) {
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        const headers = upstreamHandshakeHeaders(req.headers, {
+          service: "api",
+          port: upstream.port!,
+          proto: "https",
+        });
+        const url = new URL(req.url);
+        const opened = await openUpstreamWebSocket(
+          `ws://127.0.0.1:${upstream.port}${url.pathname}${url.search}`,
+          { protocols, headers },
+        );
+        if (!opened.ok) return new Response(opened.reason, { status: 502 });
+        const data: WsBridgeData = { upstreamUrl: "", upstream: opened.socket };
+        const ok = server.upgrade(req, {
+          headers: opened.socket.protocol
+            ? { "sec-websocket-protocol": opened.socket.protocol }
+            : undefined,
+          data,
+        });
+        if (!ok) {
+          opened.socket.close();
+          return new Response("refused", { status: 426 });
+        }
+        return undefined;
+      },
+      websocket: WS_BRIDGE_HANDLERS,
+    });
+  });
+
+  afterAll(() => {
+    upstream.stop(true);
+    bridge.stop(true);
+  });
+
+  function connect(protocols: string[]): Promise<{
+    ws: WebSocket;
+    events: Array<{ kind: "open" | "message" | "close" | "error"; value?: unknown }>;
+    done: Promise<void>;
+  }> {
+    const Ctor = WebSocket as unknown as new (
+      url: string,
+      opts: { protocols?: string[]; headers?: Record<string, string> },
+    ) => WebSocket;
+    const ws = new Ctor(`ws://127.0.0.1:${bridge.port}/console?x=1`, {
+      protocols,
+      headers: { cookie: "sid=abc", host: "api.prod.specific.dev" },
+    });
+    ws.binaryType = "arraybuffer";
+    const events: Array<{ kind: "open" | "message" | "close" | "error"; value?: unknown }> = [];
+    const done = new Promise<void>((resolve) => {
+      ws.addEventListener("close", (ev) => {
+        events.push({ kind: "close", value: { code: ev.code, reason: ev.reason } });
+        resolve();
+      });
+    });
+    ws.addEventListener("error", (ev) => events.push({ kind: "error", value: (ev as { message?: string }).message }));
+    ws.addEventListener("message", (ev) => events.push({ kind: "message", value: ev.data }));
+    return new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => {
+        events.push({ kind: "open" });
+        resolve({ ws, events, done });
+      });
+      done.then(() => reject(new Error(`closed before open: ${JSON.stringify(events)}`)));
+    });
+  }
+
+  test("the full protocol list and the headers reach the upstream; the selected protocol comes back", async () => {
+    const { ws, events, done } = await connect(["console", "ticket-ok"]);
+    expect(ws.protocol).toBe("console");
+    expect(seen).toEqual({
+      protocols: ["console", "ticket-ok"],
+      cookie: "sid=abc",
+      xfh: "api.prod.specific.dev",
+    });
+    await Bun.sleep(20);
+    ws.send("hi");
+    ws.send(new Uint8Array([1, 2, 3]));
+    await Bun.sleep(50);
+    ws.close(1000, "bye");
+    await done;
+    const messages = events.filter((e) => e.kind === "message").map((e) => e.value);
+    expect(messages[0]).toBe("ready");
+    expect(messages[1]).toBe("echo:hi");
+    expect(Array.from(new Uint8Array(messages[2] as ArrayBuffer))).toEqual([3, 2, 1]);
+  });
+
+  test("an upstream close code after the handshake is relayed to the client", async () => {
+    const { ws, events, done } = await connect(["console", "ticket-ok"]);
+    await Bun.sleep(20);
+    ws.send("close-me");
+    await done;
+    const close = events.find((e) => e.kind === "close")?.value as { code: number; reason: string };
+    expect(close.code).toBe(4402);
+    expect(close.reason).toBe("app said so");
+  });
+
+  test("an upstream that refuses the handshake never gives the client a 101", async () => {
+    // A plain fetch with the upgrade headers shows the status the bridge
+    // answers with; a WebSocket client only reports a failed handshake.
+    const res = await fetch(`http://127.0.0.1:${bridge.port}/console`, {
+      headers: {
+        connection: "Upgrade",
+        upgrade: "websocket",
+        "sec-websocket-version": "13",
+        "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==",
+        "sec-websocket-protocol": "console, ticket-bad",
+      },
+    });
+    expect(res.status).toBe(502);
+    expect(await res.text()).toContain("upstream handshake failed");
+    expect(seen?.protocols).toEqual(["console", "ticket-bad"]);
+    await expect(connect(["console", "ticket-bad"])).rejects.toThrow(/closed before open/);
+  });
+});

package/src/harness/ws-bridge.ts

@@ -0,0 +1,210 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+
+import { forwardableHeaders } from "./http-proxy.js";
+
+/** Headers that belong to the client's own WebSocket handshake. Bun's
+ *  WebSocket client mints its own key and version, and the protocol list
+ *  goes through the constructor option, so these never travel as plain
+ *  headers. */
+const HANDSHAKE_HEADERS: ReadonlySet<string> = new Set([
+  "sec-websocket-key",
+  "sec-websocket-version",
+  "sec-websocket-protocol",
+  "sec-websocket-extensions",
+  "sec-websocket-accept",
+]);
+
+/** Per-bridge context stored on `ws.data` of the client socket. */
+export interface WsBridgeData {
+  upstreamUrl: string;
+  /** Open by the time the client socket exists: the handshake awaited it. */
+  upstream: WebSocket;
+}
+
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export function parseSubprotocols(header: string | null | undefined): string[] {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export function upstreamHandshakeHeaders(
+  req: Headers,
+  opts: {
+    service: string;
+    port: number;
+    proto: string;
+    clientIp?: string;
+  },
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  forwardableHeaders(req).forEach((value, key) => {
+    if (HANDSHAKE_HEADERS.has(key)) return;
+    out[key] = value;
+  });
+  const priorXff = req.get("x-forwarded-for");
+  const xff = opts.clientIp
+    ? priorXff
+      ? `${priorXff}, ${opts.clientIp}`
+      : opts.clientIp
+    : priorXff;
+  if (xff) out["x-forwarded-for"] = xff;
+  out["x-forwarded-proto"] = opts.proto;
+  const publicHost = req.get("host");
+  if (publicHost) out["x-forwarded-host"] = publicHost;
+  out["host"] = `${opts.service}:${opts.port}`;
+  return out;
+}
+
+/** Bun's WebSocket constructor takes an options object with `headers`;
+ *  the bundled types only declare the WHATWG `protocols` form. */
+type BunWebSocketCtor = new (
+  url: string,
+  opts: { protocols?: string[]; headers?: Record<string, string> },
+) => WebSocket;
+
+export type UpstreamOpen =
+  | { ok: true; socket: WebSocket }
+  | { ok: false; reason: string };
+
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export function openUpstreamWebSocket(
+  url: string,
+  opts: { protocols: string[]; headers: Record<string, string>; timeoutMs?: number },
+): Promise<UpstreamOpen> {
+  const Ctor = WebSocket as unknown as BunWebSocketCtor;
+  let socket: WebSocket;
+  try {
+    socket = new Ctor(url, { protocols: opts.protocols, headers: opts.headers });
+  } catch (err) {
+    return Promise.resolve({ ok: false, reason: String(err) });
+  }
+  // ArrayBuffer so binary frames can be sent to the client verbatim.
+  socket.binaryType = "arraybuffer";
+  return new Promise<UpstreamOpen>((resolve) => {
+    let settled = false;
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const timer = setTimeout(() => finish({ ok: false, reason: "upstream handshake timed out" }), timeoutMs);
+    const onOpen = (): void => finish({ ok: true, socket });
+    const onError = (ev: Event): void => {
+      const msg = (ev as { message?: string }).message;
+      finish({ ok: false, reason: msg ? `upstream handshake failed: ${msg}` : "upstream handshake failed" });
+    };
+    const onClose = (ev: CloseEvent): void =>
+      finish({ ok: false, reason: `upstream closed during handshake (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})` });
+    const finish = (result: UpstreamOpen): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeEventListener("open", onOpen);
+      socket.removeEventListener("error", onError);
+      socket.removeEventListener("close", onClose);
+      if (!result.ok) {
+        try {
+          socket.close();
+        } catch {
+          /* already closed */
+        }
+      }
+      resolve(result);
+    };
+    socket.addEventListener("open", onOpen);
+    socket.addEventListener("error", onError);
+    socket.addEventListener("close", onClose);
+  });
+}
+
+/** The minimum of Bun's ServerWebSocket that the relay uses. */
+interface ClientSocket {
+  data: WsBridgeData;
+  send(data: string | ArrayBuffer | Uint8Array): unknown;
+  close(code?: number, reason?: string): unknown;
+}
+
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export const WS_BRIDGE_HANDLERS = {
+  open(ws: ClientSocket): void {
+    const { upstream } = ws.data;
+    upstream.addEventListener("message", (ev: MessageEvent) => {
+      try {
+        ws.send(ev.data);
+      } catch {
+        /* client gone */
+      }
+    });
+    upstream.addEventListener("close", (ev: CloseEvent) => {
+      try {
+        ws.close(ev.code, ev.reason);
+      } catch {
+        /* already closed */
+      }
+    });
+    upstream.addEventListener("error", () => {
+      try {
+        ws.close(1011, "upstream error");
+      } catch {
+        /* already closed */
+      }
+    });
+    // The upstream can have closed between the handshake and this
+    // callback; the close listener above was not attached yet then.
+    if (upstream.readyState !== WebSocket.OPEN) {
+      try {
+        ws.close(1011, "upstream closed");
+      } catch {
+        /* already closed */
+      }
+    }
+  },
+  message(ws: ClientSocket, message: string | Buffer): void {
+    const { upstream } = ws.data;
+    const payload = typeof message === "string" ? message : new Uint8Array(message);
+    if (upstream.readyState === WebSocket.OPEN) upstream.send(payload);
+  },
+  close(ws: ClientSocket, code: number, reason: string): void {
+    try {
+      ws.data.upstream.close(code, reason);
+    } catch {
+      /* ignore */
+    }
+  },
+};

package/src/index.ts

@@ -1,3 +1,5 @@
+import type { Android, AndroidApp } from "./android.js";
+export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
 // the returned `env.test(...)`, and default-exports `env.project([...])`.
@@ -1967,6 +1969,8 @@ export interface TestContext<
    * like named desktop browsers.
    */
   mobile(app: MobileApp, name?: string): Promise<Mobile>;
+  /** Native Android via Appium. Recording is automatic for test cases; the app and session survive forks. */
+  android(app: AndroidApp): Promise<Android>;
   /** Drive a real Electron renderer window through locators and user input.
    * Acquires the app started by electron(); keeps its live state across forks.
    * Each test gets a self-contained graphical replay. Selecting another window

package/src/recorder.ts

@@ -632,7 +632,7 @@ export interface EventReservation {
 class Recorder {
   private events: TestEvent[] = [];
   private seq = 0;
-  private readonly start = Date.now();
+  constructor(private readonly start = Date.now()) {}
 
   /** Claim a seq + start offset now; pass the result to `push` at finish. */
   reserve(): EventReservation {
@@ -753,8 +753,8 @@ function active(): boolean {
   return current !== null && paused === 0 && scopeAllowsRecording();
 }
 
-export function startRecording(): void {
-  current = new Recorder();
+export function startRecording(startedAt = Date.now()): void {
+  current = new Recorder(startedAt);
   paused = 0;
 }