@specific.dev/spectest 0.39.0 → 0.43.0

package/src/harness/http-proxy.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  augmentCorsResponse,
+  corsPreflightResponse,
+  forwardableHeaders,
+  isCorsPreflight,
+  isHopByHop,
+} from "./http-proxy";
+
+describe("hop-by-hop headers", () => {
+  test("connection-scoped headers are recognised, case-insensitively", () => {
+    expect(isHopByHop("Connection")).toBe(true);
+    expect(isHopByHop("TRANSFER-ENCODING")).toBe(true);
+    expect(isHopByHop("upgrade")).toBe(true);
+    expect(isHopByHop("host")).toBe(true);
+  });
+
+  test("ordinary headers are forwardable", () => {
+    expect(isHopByHop("authorization")).toBe(false);
+    expect(isHopByHop("content-type")).toBe(false);
+    expect(isHopByHop("cookie")).toBe(false);
+  });
+
+  /** Forwarding transfer-encoding from a re-encoded body produces a
+   *  response the client cannot frame; forwarding host would hide which
+   *  service the upstream actually is. */
+  test("forwardableHeaders drops them and keeps the rest", () => {
+    const h = new Headers({
+      host: "app.test",
+      connection: "keep-alive",
+      "transfer-encoding": "chunked",
+      authorization: "Bearer x",
+      "content-type": "application/json",
+    });
+    const out = forwardableHeaders(h);
+    expect(out.get("host")).toBeNull();
+    expect(out.get("connection")).toBeNull();
+    expect(out.get("transfer-encoding")).toBeNull();
+    expect(out.get("authorization")).toBe("Bearer x");
+    expect(out.get("content-type")).toBe("application/json");
+  });
+
+  test("repeated headers survive as repeats", () => {
+    const h = new Headers();
+    h.append("set-cookie", "a=1");
+    h.append("set-cookie", "b=2");
+    expect(forwardableHeaders(h).getAll("set-cookie")).toEqual(["a=1", "b=2"]);
+  });
+});
+
+describe("preflight detection", () => {
+  const req = (method: string, headers: Record<string, string>) =>
+    new Request("http://app.test/", { method, headers });
+
+  test("OPTIONS with Origin and Access-Control-Request-Method is a preflight", () => {
+    expect(
+      isCorsPreflight(
+        req("OPTIONS", { origin: "http://a.test", "access-control-request-method": "POST" }),
+      ),
+    ).toBe(true);
+  });
+
+  /** A bare OPTIONS is a real request — an API being asked what it
+   *  supports. Answering it here would hide the app's own response. */
+  test("OPTIONS without the CORS headers is NOT a preflight", () => {
+    expect(isCorsPreflight(req("OPTIONS", {}))).toBe(false);
+    expect(isCorsPreflight(req("OPTIONS", { origin: "http://a.test" }))).toBe(false);
+  });
+
+  test("a non-OPTIONS request is never a preflight", () => {
+    expect(
+      isCorsPreflight(
+        req("POST", { origin: "http://a.test", "access-control-request-method": "POST" }),
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("preflight response", () => {
+  const preflight = (headers: Record<string, string>) =>
+    corsPreflightResponse(new Request("http://app.test/", { method: "OPTIONS", headers }));
+
+  /** `Allow-Origin: *` with `Allow-Credentials: true` is a spec violation
+   *  browsers reject — a wildcard would break exactly the credentialed
+   *  requests this exists to permit. */
+  test("echoes the specific origin, never a wildcard, alongside credentials", () => {
+    const res = preflight({ origin: "http://a.test", "access-control-request-method": "POST" });
+    expect(res.headers.get("access-control-allow-origin")).toBe("http://a.test");
+    expect(res.headers.get("access-control-allow-credentials")).toBe("true");
+    expect(res.headers.get("access-control-allow-origin")).not.toBe("*");
+  });
+
+  test("echoes the requested method and headers", () => {
+    const res = preflight({
+      origin: "http://a.test",
+      "access-control-request-method": "PATCH",
+      "access-control-request-headers": "x-custom, authorization",
+    });
+    expect(res.headers.get("access-control-allow-methods")).toBe("PATCH");
+    expect(res.headers.get("access-control-allow-headers")).toBe("x-custom, authorization");
+  });
+
+  test("falls back to a permissive set when nothing specific was asked", () => {
+    const res = preflight({ origin: "http://a.test", "access-control-request-method": "" });
+    expect(res.headers.get("access-control-allow-methods")).toContain("POST");
+    expect(res.headers.get("access-control-allow-headers")).toBe("*");
+  });
+
+  test("is a 204 with no body", async () => {
+    const res = preflight({ origin: "http://a.test", "access-control-request-method": "GET" });
+    expect(res.status).toBe(204);
+    expect(await res.text()).toBe("");
+  });
+
+  /** Without Vary, a cache can serve one origin's preflight to another. */
+  test("varies on origin and requested headers", () => {
+    const res = preflight({ origin: "http://a.test", "access-control-request-method": "GET" });
+    const vary = res.headers.get("vary") ?? "";
+    expect(vary.toLowerCase()).toContain("origin");
+    expect(vary.toLowerCase()).toContain("access-control-request-headers");
+  });
+});
+
+describe("augmenting a proxied response", () => {
+  const withOrigin = new Request("http://app.test/", { headers: { origin: "http://a.test" } });
+
+  test("adds CORS headers when the response has none", () => {
+    const out = augmentCorsResponse(withOrigin, new Response("hi"));
+    expect(out.headers.get("access-control-allow-origin")).toBe("http://a.test");
+    expect(out.headers.get("access-control-allow-credentials")).toBe("true");
+  });
+
+  /** An app that sets its own policy has an opinion — possibly a
+   *  restrictive one a test is asserting. Overriding it would make the
+   *  environment lie about the app. */
+  test("never overrides the upstream's own policy", () => {
+    const res = new Response("hi", {
+      headers: { "access-control-allow-origin": "https://only-this.test" },
+    });
+    const out = augmentCorsResponse(withOrigin, res);
+    expect(out.headers.get("access-control-allow-origin")).toBe("https://only-this.test");
+  });
+
+  test("a request with no Origin is left alone", () => {
+    const out = augmentCorsResponse(new Request("http://app.test/"), new Response("hi"));
+    expect(out.headers.get("access-control-allow-origin")).toBeNull();
+  });
+
+  test("an immutable-header response is returned unchanged rather than throwing", () => {
+    // A redirect response has guarded headers in some runtimes; the point
+    // is that a header failure must not fail the request.
+    const res = Response.redirect("http://elsewhere.test/", 302);
+    expect(() => augmentCorsResponse(withOrigin, res)).not.toThrow();
+  });
+});

package/src/harness/http-proxy.ts

@@ -0,0 +1,119 @@
+/**
+ * HTTP semantics the ingress proxy has to get right: which headers must
+ * not be forwarded, and how CORS is answered.
+ *
+ * Ported out of `daemon.ts`. Pure request→response logic, so the rules
+ * below are now assertable rather than inferred from a header list.
+ */
+
+/**
+ * Headers that describe **this** connection rather than the message, and
+ * so must never be copied to the next hop (RFC 9110 §7.6.1).
+ *
+ * Forwarding `transfer-encoding` or `content-length` from a re-encoded
+ * body is the classic way to produce a response the client cannot frame;
+ * forwarding `connection` leaks our keep-alive intent to the upstream.
+ * `host` is here because the proxy sets its own — the upstream must see
+ * the service it actually is, not the public name the client asked for.
+ */
+export const HOP_BY_HOP_HEADERS: ReadonlySet<string> = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+]);
+
+export function isHopByHop(name: string): boolean {
+  return HOP_BY_HOP_HEADERS.has(name.toLowerCase());
+}
+
+/** Copy headers, dropping the ones that belong to this connection. */
+export function forwardableHeaders(headers: Headers): Headers {
+  const out = new Headers();
+  headers.forEach((value, key) => {
+    if (!isHopByHop(key)) out.append(key, value);
+  });
+  return out;
+}
+
+/**
+ * A CORS preflight is an `OPTIONS` carrying both `Origin` and
+ * `Access-Control-Request-Method`. An `OPTIONS` without them is a normal
+ * request (an API asking what it supports) and must be proxied, not
+ * answered here.
+ */
+export function isCorsPreflight(req: {
+  method: string;
+  headers: { has(n: string): boolean };
+}): boolean {
+  return (
+    req.method === "OPTIONS" &&
+    req.headers.has("origin") &&
+    req.headers.has("access-control-request-method")
+  );
+}
+
+/**
+ * Answer a preflight permissively — the environment is hermetic, so
+ * there is nothing here to protect from itself, and a test failing on
+ * CORS teaches nothing about the app.
+ *
+ * The one rule that is not a matter of taste: the **specific** origin is
+ * echoed rather than `*`. `Allow-Origin: *` together with
+ * `Allow-Credentials: true` is a spec violation that browsers reject
+ * outright, so a wildcard would break exactly the credentialed requests
+ * this is meant to permit.
+ */
+export function corsPreflightResponse(req: {
+  headers: { get(n: string): string | null };
+}): Response {
+  const origin = req.headers.get("origin") ?? "*";
+  const reqHeaders = req.headers.get("access-control-request-headers");
+  const reqMethod = req.headers.get("access-control-request-method");
+  const headers = new Headers();
+  headers.set("access-control-allow-origin", origin);
+  headers.set("access-control-allow-credentials", "true");
+  headers.set(
+    "access-control-allow-methods",
+    reqMethod && reqMethod.length > 0 ? reqMethod : "GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS",
+  );
+  headers.set("access-control-allow-headers", reqHeaders && reqHeaders.length > 0 ? reqHeaders : "*");
+  headers.set("access-control-max-age", "600");
+  // The answer depends on what was asked — say so, or a cache will serve
+  // one origin's preflight to another.
+  headers.append("vary", "Origin");
+  headers.append("vary", "Access-Control-Request-Headers");
+  return new Response(null, { status: 204, headers });
+}
+
+/**
+ * Add CORS headers to a proxied response, without overriding the
+ * upstream's own.
+ *
+ * An app that already sets `Access-Control-Allow-Origin` has an opinion —
+ * possibly a deliberately restrictive one that a test is checking — and
+ * replacing it would make the environment lie about the app's behaviour.
+ */
+export function augmentCorsResponse(
+  req: { headers: { get(n: string): string | null } },
+  res: Response,
+): Response {
+  const origin = req.headers.get("origin");
+  if (!origin) return res;
+  if (res.headers.has("access-control-allow-origin")) return res;
+  try {
+    res.headers.set("access-control-allow-origin", origin);
+    res.headers.set("access-control-allow-credentials", "true");
+    res.headers.append("vary", "Origin");
+  } catch {
+    // Some responses carry guarded/immutable headers — a 101 upgrade stub,
+    // for instance. Leave those exactly as they are rather than failing the
+    // request over a cosmetic header.
+  }
+  return res;
+}

package/src/harness/ingress-rebind.test.ts

@@ -0,0 +1,125 @@
+/**
+ * The :443 rebind must not be collateral damage for traffic already on the
+ * listener.
+ *
+ * Adding an SNI certificate needs a second `Bun.serve` — `reload()` accepts
+ * a new `tls` option and goes on serving the old certificates. The question
+ * this file pins down is the *order*: bind the replacement first and drain
+ * the old one, rather than stopping the old one and leaving a gap.
+ *
+ * These drive real sockets rather than a model of them, because the bug was
+ * in socket behaviour: a model would have agreed with the broken code.
+ * They use plain HTTP — the TLS part is Bun's SNI table, measured
+ * separately; what is asserted here is that a listener swap costs no
+ * connection, which is the part that was wrong.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const servers: any[] = [];
+afterEach(() => {
+  for (const s of servers.splice(0)) {
+    try {
+      s.stop(true);
+    } catch {
+      /* already stopped */
+    }
+  }
+});
+
+/** A listener shaped like the ingress ones: reusePort, no idle timeout. */
+function bind(port: number, label: string, delayMs = 0) {
+  const server = Bun.serve({
+    port,
+    hostname: "127.0.0.1",
+    reusePort: true,
+    idleTimeout: 0,
+    async fetch() {
+      if (delayMs) await Bun.sleep(delayMs);
+      return new Response(label);
+    },
+  });
+  servers.push(server);
+  return server;
+}
+
+/** Can a fresh connection be served right now? */
+async function reachable(port: number): Promise<boolean> {
+  try {
+    await fetch(`http://127.0.0.1:${port}/`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("swapping a listener", () => {
+  /** SO_REUSEPORT is what makes an overlap possible at all. Without it on
+   *  BOTH sockets the second bind fails outright, so this is a precondition
+   *  of the whole approach rather than a nicety. */
+  test("a replacement can bind while the original is still listening", () => {
+    const port = 19100;
+    bind(port, "old");
+    expect(() => bind(port, "new")).not.toThrow();
+  });
+
+  test("without reusePort the second bind is refused", () => {
+    const port = 19101;
+    const first = Bun.serve({ port, hostname: "127.0.0.1", fetch: () => new Response("a") });
+    servers.push(first);
+    expect(() =>
+      Bun.serve({ port, hostname: "127.0.0.1", fetch: () => new Response("b") }),
+    ).toThrow();
+  });
+
+  /**
+   * The regression. A request already in flight when the swap happens must
+   * still get its response.
+   *
+   * With the old ordering — `old.stop(true)` before serving the replacement
+   * — this request is force-closed mid-flight and the fetch rejects. That is
+   * exactly what the app under test saw: `SocketError: other side closed`,
+   * on an upload that had nothing to do with the service being provisioned.
+   */
+  test("a request in flight survives the swap", async () => {
+    const port = 19102;
+    const old = bind(port, "old", 300);
+    const inFlight = fetch(`http://127.0.0.1:${port}/`);
+    await Bun.sleep(50); // let it be genuinely in flight
+
+    bind(port, "new"); // replacement first…
+    old.stop(false); // …then drain the original
+
+    await expect(inFlight.then((r) => r.text())).resolves.toBe("old");
+  });
+
+  /**
+   * The other half of the same bug: stopping first leaves a window where
+   * nothing is bound, and a connection arriving then gets ECONNREFUSED.
+   * Binding first means the port is continuously served.
+   */
+  test("the port is never refused across the swap", async () => {
+    const port = 19103;
+    const old = bind(port, "old");
+    expect(await reachable(port)).toBe(true);
+
+    const replacement = bind(port, "new");
+    expect(await reachable(port)).toBe(true);
+
+    old.stop(false);
+    expect(await reachable(port)).toBe(true);
+
+    replacement.stop(false);
+  });
+
+  /** After the original has drained, the replacement is the only thing
+   *  serving — otherwise a stale route table would keep answering. */
+  test("the replacement serves once the original is gone", async () => {
+    const port = 19104;
+    const old = bind(port, "old");
+    bind(port, "new");
+    old.stop(true);
+    const body = await fetch(`http://127.0.0.1:${port}/`).then((r) => r.text());
+    expect(body).toBe("new");
+  });
+});

package/src/harness/ingress-table.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, test } from "bun:test";
+
+import { matchRoute } from "./hostmatch";
+import {
+  INGRESS_HTTPS_PORT,
+  INGRESS_HTTP_PORT,
+  bindRoute,
+  certEntries,
+  clearTables,
+  emptyTables,
+  planBind,
+  registryTarget,
+  routesFor,
+  unbindRoute,
+  type Route,
+} from "./ingress-table";
+
+const leaf = (tag: string) => ({ cert: `cert-${tag}`, key: `key-${tag}` });
+const proxy = (service: string, port = 8080): Route => ({ kind: "proxy", service, port });
+
+describe("route tables", () => {
+  /** The one that matters. Every listener closes over the Map it was bound
+   *  with, so a caller that receives a *new* Map on the second call would
+   *  add routes nobody is serving — and nothing would report it, because
+   *  binding a route has no observable result of its own. */
+  test("returns the same table object every time, so listeners stay attached", () => {
+    const t = emptyTables();
+    const first = routesFor(t, INGRESS_HTTPS_PORT);
+    first.set("a.test", proxy("a"));
+    const second = routesFor(t, INGRESS_HTTPS_PORT);
+    expect(second).toBe(first);
+    expect(second.get("a.test")).toEqual(proxy("a"));
+  });
+
+  test("a route added after a listener captured the table is visible to it", () => {
+    const t = emptyTables();
+    // Stand in for a listener: capture the table once, as Bun.serve's
+    // fetch closure does, then look routes up through the capture.
+    const captured = routesFor(t, INGRESS_HTTPS_PORT);
+    bindRoute(t, "later.test", proxy("later"));
+    expect(matchRoute(captured, "later.test")).toEqual(proxy("later"));
+  });
+
+  test("different ports get different tables", () => {
+    const t = emptyTables();
+    expect(routesFor(t, 80)).not.toBe(routesFor(t, 443));
+  });
+
+  test("binding serves both schemes, matching boot tls", () => {
+    const t = emptyTables();
+    bindRoute(t, "app.test", proxy("app", 3000));
+    expect(routesFor(t, INGRESS_HTTP_PORT).get("app.test")).toEqual(proxy("app", 3000));
+    expect(routesFor(t, INGRESS_HTTPS_PORT).get("app.test")).toEqual(proxy("app", 3000));
+  });
+
+  test("unbinding removes both schemes", () => {
+    const t = emptyTables();
+    bindRoute(t, "app.test", proxy("app"));
+    unbindRoute(t, "app.test");
+    expect(routesFor(t, INGRESS_HTTP_PORT).has("app.test")).toBe(false);
+    expect(routesFor(t, INGRESS_HTTPS_PORT).has("app.test")).toBe(false);
+  });
+
+  test("unbinding a hostname that was never bound is a no-op", () => {
+    const t = emptyTables();
+    expect(() => unbindRoute(t, "ghost.test")).not.toThrow();
+  });
+
+  /** Removing the cert would cost a :443 rebind at teardown, for nothing:
+   *  a cert with no route behind it can't serve anything. */
+  test("unbinding leaves the certificate in place", () => {
+    const t = emptyTables();
+    t.certByHost.set("app.test", leaf("app"));
+    bindRoute(t, "app.test", proxy("app"));
+    unbindRoute(t, "app.test");
+    expect(t.certByHost.has("app.test")).toBe(true);
+  });
+});
+
+describe("planBind", () => {
+  test("a brand-new hostname needs a cert and a rebind", () => {
+    const t = emptyTables();
+    expect(planBind(t, "new.test", { httpsListening: true })).toEqual({
+      needsCert: true,
+      needsHttpsRebind: true,
+    });
+  });
+
+  test("the first bind rebinds even when a cert already covers the name", () => {
+    const t = emptyTables();
+    t.certByHost.set("app.test", leaf("app"));
+    // Nothing is listening yet, so :443 has to be served regardless.
+    expect(planBind(t, "app.test", { httpsListening: false })).toEqual({
+      needsCert: false,
+      needsHttpsRebind: true,
+    });
+  });
+
+  test("re-binding an exact hostname already covered costs nothing", () => {
+    const t = emptyTables();
+    t.certByHost.set("app.test", leaf("app"));
+    expect(planBind(t, "app.test", { httpsListening: true })).toEqual({
+      needsCert: false,
+      needsHttpsRebind: false,
+    });
+  });
+
+  /** The case that makes runtime provisioning cheap: a component claims
+   *  `*.db.test` up front, then a fake mints endpoints under it in a loop.
+   *  Rebinding per iteration would restart the listener each time. */
+  test("a hostname under an existing wildcard cert needs neither", () => {
+    const t = emptyTables();
+    t.certByHost.set("*.db.test", leaf("wild"));
+    expect(planBind(t, "tenant-1.db.test", { httpsListening: true })).toEqual({
+      needsCert: false,
+      needsHttpsRebind: false,
+    });
+  });
+
+  /** A wildcard cert covers exactly one label (RFC 6125), so a deeper name
+   *  needs its own leaf. Reporting it covered would hand the client a
+   *  certificate it rejects, and the failure would surface at request time
+   *  far from here. */
+  test("a deeper name under a wildcard cert still needs its own", () => {
+    const t = emptyTables();
+    t.certByHost.set("*.db.test", leaf("wild"));
+    expect(planBind(t, "a.b.db.test", { httpsListening: true }).needsCert).toBe(true);
+  });
+});
+
+describe("certEntries", () => {
+  test("renders the SNI table for Bun.serve", () => {
+    const t = emptyTables();
+    t.certByHost.set("a.test", leaf("a"));
+    t.certByHost.set("*.b.test", leaf("b"));
+    expect(certEntries(t)).toEqual([
+      { serverName: "a.test", cert: "cert-a", key: "key-a" },
+      { serverName: "*.b.test", cert: "cert-b", key: "key-b" },
+    ]);
+  });
+
+  test("an empty table yields no entries rather than throwing", () => {
+    expect(certEntries(emptyTables())).toEqual([]);
+  });
+});
+
+describe("clearTables", () => {
+  test("drops routes and certs, so a new project starts clean", () => {
+    const t = emptyTables();
+    bindRoute(t, "old.test", proxy("old"));
+    t.certByHost.set("old.test", leaf("old"));
+    clearTables(t);
+    expect(t.routesByPort.size).toBe(0);
+    expect(t.certByHost.size).toBe(0);
+  });
+});
+
+describe("registryTarget", () => {
+  test("a wildcard goes to the suffix table, which is its only home", () => {
+    expect(registryTarget("*.example.com")).toEqual({
+      wildcard: true,
+      suffix: ".example.com",
+    });
+  });
+
+  test("an exact name goes to the exact table, so it keeps winning", () => {
+    expect(registryTarget("api.example.com")).toEqual({
+      wildcard: false,
+      host: "api.example.com",
+    });
+  });
+});