@specific.dev/spectest 0.94.0 → 0.95.0

package/src/components/index.ts

@@ -1,4 +1,6 @@
 // Reusable, pre-built service definitions for common dependencies.
+export { pubsub, pubsubClient, type PubSubOptions, type PubSubClient, type PubSubHelpers,
+  type PubSubSubscriptionOptions, type PubSubMessage, type PubSubReceivedMessage } from "./pubsub.js";
 export { temporal, temporalClient, type TemporalOptions, type TemporalClient,
   type TemporalNamespace, type TemporalWorkerOptions, type TemporalPoller,
   type TemporalSearchAttributeType, type TemporalTaskType } from "./temporal.js";

package/src/components/pubsub.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment } from "../index.js";
+import { pubsub, pubsubClient } from "./pubsub.js";
+
+describe("Pub/Sub", () => {
+  test("custom port and project configure both the emulator and API readiness", () => {
+    const env = defineEnvironment({ name: "test", services: { messaging: pubsub({ projectId: "local-project", port: 9095 }) } });
+    const service = env.config.services.messaging;
+    expect(service.args).toContain("--host-port=0.0.0.0:9095");
+    expect(service.args).toContain("--project=local-project");
+    expect(service.tls).toEqual([{ hostname: "pubsub.googleapis.com", port: 9095, http2: true }]);
+    expect(Object.keys(env.config.services)).toEqual(["messaging"]);
+    const direct = defineEnvironment({ name: "test", services: { messaging: pubsub({ tls: false }) } });
+    expect(Object.keys(direct.config.services)).toEqual(["messaging"]);
+    expect(direct.config.services.messaging.certificates).toBeUndefined();
+    const custom = defineEnvironment({ name: "test", services: { messaging: pubsub({ tls: { hostname: "other.pubsub.test" } }) } });
+    expect(custom.config.services.messaging.tls).toEqual([{ hostname: "other.pubsub.test", port: 8085, http2: true }]);
+  });
+
+  test("rejects invalid configuration before launching a container", () => {
+    for (const port of [0, 65536, 1.5, NaN]) expect(() => pubsub({ port })).toThrow("port");
+    expect(() => pubsub({ projectId: "../bad" })).toThrow("projectId");
+    expect(() => pubsub({ port: 443 })).toThrow("TLS port");
+    expect(() => pubsub({ tls: { hostname: "invalid/path" } })).toThrow("hostname");
+    expect(() => pubsub({ tls: { hostname: "" } })).toThrow("hostname");
+    expect(() => pubsub({ tls: { hostname: "*.pubsub.test" } })).toThrow("exact hostname");
+    for (const topic of ["ab", "goog-topic", "projects/another/topics/topic", "../topic"]) expect(() => pubsub({ topics: [topic] })).toThrow("ID");
+    expect(() => pubsub({ subscriptions: { worker: { topic: "orders", ackDeadlineSeconds: 601 } } })).toThrow("ackDeadlineSeconds");
+    expect(() => pubsub({ subscriptions: { worker: { topic: "orders", pushEndpoint: "ftp://app" } } })).toThrow("HTTP");
+  });
+
+  test("publish encodes UTF-8 and arbitrary bytes exactly once and preserves attributes", async () => {
+    const bodies: any[] = [];
+    const client = pubsubClient("http://messaging:8085", "spectest", async (_, init) => {
+      bodies.push(JSON.parse(init!.body as string));
+      return Response.json({ messageIds: ["123"] });
+    });
+    expect(await client.publish("orders", "café ☕", { source: "test" })).toBe("123");
+    expect(Buffer.from(bodies[0].messages[0].data, "base64").toString()).toBe("café ☕");
+    expect(bodies[0].messages[0].attributes).toEqual({ source: "test" });
+    await client.publish("orders", new Uint8Array([0, 128, 255]));
+    expect([...Buffer.from(bodies[1].messages[0].data, "base64")]).toEqual([0, 128, 255]);
+  });
+
+  test("pull returns ack IDs and leaves acknowledgement explicit", async () => {
+    const calls: { url: string; body: any }[] = [];
+    const client = pubsubClient("http://messaging:8085/", "spectest", async (url, init) => {
+      calls.push({ url: String(url), body: JSON.parse(init!.body as string) });
+      return Response.json(calls.length === 1 ? { receivedMessages: [{ ackId: "ack-1", message: { data: "aGk=", messageId: "1" } }] } : {});
+    });
+    const messages = await client.pull("worker", { maxMessages: 1 });
+    expect(messages[0].ackId).toBe("ack-1");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].body).toEqual({ maxMessages: 1, returnImmediately: true });
+    await client.acknowledge("worker", [messages[0].ackId]);
+    expect(calls[1]).toEqual({ url: "http://messaging:8085/v1/projects/spectest/subscriptions/worker:acknowledge", body: { ackIds: ["ack-1"] } });
+    expect(await client.pull("worker")).toEqual([]);
+    await expect(client.pull("worker", { maxMessages: 0 })).rejects.toThrow("maxMessages");
+  });
+
+  test("API errors include operation and status and never retry a publish", async () => {
+    let calls = 0;
+    const client = pubsubClient("http://messaging:8085", "spectest", async () => {
+      calls++;
+      return Response.json({ error: { message: "Topic not found" } }, { status: 404 });
+    });
+    await expect(client.publish("missing", "data")).rejects.toThrow("HTTP 404");
+    expect(calls).toBe(1);
+  });
+
+  test("resource IDs are escaped in URLs but remain canonical in subscription bodies", async () => {
+    let requestUrl = "", body: any;
+    const client = pubsubClient("http://messaging:8085", "spectest", async (url, init) => {
+      requestUrl = String(url); body = JSON.parse(init!.body as string);
+      return Response.json({});
+    });
+    await client.createSubscription("worker%one", { topic: "topic+one", pushEndpoint: "http://app:3000/push" });
+    expect(requestUrl).toEndWith("/subscriptions/worker%25one");
+    expect(body).toEqual({ topic: "projects/spectest/topics/topic+one", ackDeadlineSeconds: 10, pushConfig: { pushEndpoint: "http://app:3000/push" } });
+  });
+
+  test("every request has a bounded timeout", async () => {
+    const client = pubsubClient("http://messaging:8085", "spectest", async (_, init) => {
+      return new Promise<Response>((_, reject) => init!.signal!.addEventListener("abort", () => reject(init!.signal!.reason), { once: true }));
+    });
+    await expect(client.pull("worker", { timeoutMs: 10 })).rejects.toThrow();
+  });
+});

package/src/components/pubsub.ts

@@ -0,0 +1,182 @@
+import type { ServiceDefinition, ServiceHelpersContext, ServiceSetupContext, ServicesMap } from "../index.js";
+import { serviceGroup, certificate } from "../index.js";
+import { rawFetch } from "../harness/raw-fetch.js";
+import { readRaw } from "../inspect.js";
+
+export interface PubSubSubscriptionOptions {
+  /** Topic ID in this component's project. */
+  topic: string;
+  ackDeadlineSeconds?: number;
+  /** HTTP is supported by the emulator, including other service names. */
+  pushEndpoint?: string;
+}
+
+export interface PubSubOptions {
+  /** Local project ID; no Google Cloud account is needed. Default "spectest". */
+  projectId?: string;
+  /** Official Cloud CLI image with the Pub/Sub emulator installed. */
+  image?: string;
+  /** Emulator HTTP and gRPC port. Default 8085. */
+  port?: number;
+  /** TLS on pubsub.googleapis.com by default. Set false for direct emulator
+   * access, or choose a different hostname for a second isolated instance. */
+  tls?: false | { hostname: string };
+  topics?: string[];
+  /** Subscription ID → options. Referenced topics are created automatically. */
+  subscriptions?: Record<string, PubSubSubscriptionOptions>;
+  /** Runs after the declared topics and subscriptions have been created. */
+  setup?: (ctx: ServiceSetupContext<PubSubHelpers>) => void | Promise<void>;
+}
+
+export interface PubSubMessage {
+  /** Base64 encoded data, as returned by the Pub/Sub REST API. */
+  data?: string;
+  attributes?: Record<string, string>;
+  messageId: string;
+  publishTime: string;
+  orderingKey?: string;
+}
+
+export interface PubSubReceivedMessage {
+  ackId: string;
+  message: PubSubMessage;
+  deliveryAttempt?: number;
+}
+
+function resourceId(id: string): string {
+  if (!/^[A-Za-z][A-Za-z0-9._~+%-]{2,254}$/.test(id) || id.startsWith("goog")) {
+    throw new Error(`pubsub(): invalid topic or subscription ID ${JSON.stringify(id)}; use a 3–255 character ID starting with a letter, not "goog"`);
+  }
+  return id;
+}
+
+function projectName(id: string): string {
+  if (!/^[a-z][a-z0-9-]{4,28}[a-z0-9]$/.test(id)) throw new Error("pubsub(): projectId must be a 6–30 character Google Cloud project ID");
+  return id;
+}
+
+function subscriptionOptions(options: PubSubSubscriptionOptions) {
+  resourceId(options.topic);
+  const seconds = options.ackDeadlineSeconds ?? 10;
+  if (!Number.isInteger(seconds) || seconds < 10 || seconds > 600) throw new Error("pubsub(): ackDeadlineSeconds must be an integer between 10 and 600");
+  if (options.pushEndpoint && !/^https?:$/.test(new URL(options.pushEndpoint).protocol)) throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
+  return seconds;
+}
+
+/** Stateless emulator REST client. No credentials or gRPC channel to preserve across forks.
+ * Resource arguments are short IDs in projectId; publish accepts UTF-8 text or bytes.
+ */
+export function pubsubClient(
+  endpoint: string,
+  projectId = "spectest",
+  fetcher: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response> = rawFetch,
+) {
+  projectName(projectId);
+  const base = endpoint.replace(/\/$/, "");
+  const resource = (kind: "topics" | "subscriptions", id: string) => `projects/${projectId}/${kind}/${resourceId(id)}`;
+  const path = (kind: "topics" | "subscriptions", id: string) => `/v1/projects/${projectId}/${kind}/${encodeURIComponent(resourceId(id))}`;
+  async function request<T>(url: string, method: string, body?: unknown, timeoutMs = 10000): Promise<T> {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("pubsub(): timeoutMs must be positive");
+    const response = await fetcher(`${base}${url}`, {
+      method, headers: { "content-type": "application/json" },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(Math.ceil(timeoutMs)),
+    });
+    const text = await response.text();
+    if (!response.ok) throw new Error(`Pub/Sub ${method} ${url}: HTTP ${response.status}: ${text.slice(0, 1000)}`);
+    return (text ? JSON.parse(text) : {}) as T;
+  }
+  return {
+    projectId, endpoint: base,
+    topicName: (id: string) => resource("topics", id),
+    subscriptionName: (id: string) => resource("subscriptions", id),
+    createTopic(id: string) {
+      return request<{ name: string }>(path("topics", id), "PUT", {});
+    },
+    createSubscription(id: string, options: PubSubSubscriptionOptions) {
+      const ackDeadlineSeconds = subscriptionOptions(options);
+      return request<{ name: string; topic: string; ackDeadlineSeconds: number }>(path("subscriptions", id), "PUT", {
+        topic: resource("topics", options.topic), ackDeadlineSeconds,
+        ...(options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
+      });
+    },
+    async publish(topic: string, data: string | Uint8Array, attributes?: Record<string, string>): Promise<string> {
+      const result = await request<{ messageIds: string[] }>(`${path("topics", topic)}:publish`, "POST", {
+        messages: [{ data: Buffer.from(data).toString("base64"), ...(attributes ? { attributes } : {}) }],
+      });
+      return result.messageIds[0];
+    },
+    /** A pull leases messages; call acknowledge() to remove them. Empty is valid.
+     * Uses the emulator's immediate pull mode for bounded test polling.
+     */
+    async pull(subscription: string, options: { maxMessages?: number; timeoutMs?: number } = {}): Promise<PubSubReceivedMessage[]> {
+      const maxMessages = options.maxMessages ?? 10;
+      if (!Number.isInteger(maxMessages) || maxMessages < 1) throw new Error("pubsub(): maxMessages must be a positive integer");
+      const result = await request<{ receivedMessages?: PubSubReceivedMessage[] }>(`${path("subscriptions", subscription)}:pull`, "POST",
+        { maxMessages, returnImmediately: true }, options.timeoutMs);
+      return result.receivedMessages ?? [];
+    },
+    async acknowledge(subscription: string, ackIds: string[]): Promise<void> {
+      await request(`${path("subscriptions", subscription)}:acknowledge`, "POST", { ackIds });
+    },
+  };
+}
+
+export type PubSubClient = ReturnType<typeof pubsubClient>;
+export interface PubSubHelpers extends PubSubClient {
+  /** Direct plaintext address for clients explicitly using emulator mode. */
+  emulatorHost: string;
+}
+
+/** Google Cloud's real local Pub/Sub emulator, ready for Google client libraries.
+ * Mount directly in services: { pubsub: pubsub({ topics: ["orders"] }) }.
+ * Applications use their default pubsub.googleapis.com:443 endpoint with
+ * verified TLS and local test credentials. No emulator endpoint override.
+ * State survives VM snapshots/forks, but not an emulator process restart.
+ */
+export function pubsub(opts: PubSubOptions = {}) {
+  const projectId = projectName(opts.projectId ?? "spectest");
+  const port = opts.port ?? 8085;
+  const hostname = opts.tls === false ? undefined : opts.tls?.hostname ?? "pubsub.googleapis.com";
+  if (hostname !== undefined) {
+    certificate([hostname]);
+    if (hostname.startsWith("*.")) throw new Error("pubsub(): TLS hostname must be an exact hostname");
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("pubsub(): port must be an integer between 1 and 65535");
+  const subscriptions = Object.entries(opts.subscriptions ?? {});
+  for (const [id, options] of subscriptions) { resourceId(id); subscriptionOptions(options); }
+  const topics = [...new Set([...(opts.topics ?? []), ...subscriptions.map(([, options]) => options.topic)])].map(resourceId);
+  if (hostname && port === 443) throw new Error("pubsub(): the plaintext emulator port must differ from TLS port 443");
+  return serviceGroup({
+    primary: "emulator",
+    services: (): ServicesMap => {
+      const emulator: ServiceDefinition = {
+        image: { type: "registry", reference: opts.image ?? "gcr.io/google.com/cloudsdktool/google-cloud-cli:573.0.0-emulators" },
+        args: ["gcloud", "beta", "emulators", "pubsub", "start", `--project=${projectId}`, `--host-port=0.0.0.0:${port}`, "--quiet"],
+        ports: [port],
+        ...(hostname ? { tls: [{ hostname, port, http2: true }] } : {}),
+        readyCheck: { type: "http", port, path: `/v1/projects/${projectId}/topics`, timeoutSecs: 60 },
+        setup: async ({ name }) => {
+          const client = pubsubClient(`http://${name}:${port}`, projectId);
+          for (const topic of topics) await client.createTopic(topic);
+          for (const [id, options] of subscriptions) await client.createSubscription(id, options);
+        },
+      };
+      return { emulator };
+    },
+    helpers: (ctx: ServiceHelpersContext): PubSubHelpers => ({
+      ...pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId,
+        async (input, init) => readRaw(await ctx.fetch(String(input), init)) as unknown as Response),
+      emulatorHost: `${ctx.name}:${port}`,
+    }),
+    setup: async (ctx: ServiceSetupContext<PubSubHelpers>) => {
+      // Prove the TLS endpoint and certificate are ready before dependents.
+      if (hostname) {
+        const response = await rawFetch(`https://${hostname}/v1/projects/${projectId}/topics`, { signal: AbortSignal.timeout(10000) });
+        if (!response.ok) throw new Error(`pubsub(): TLS readiness failed: HTTP ${response.status}`);
+        await response.text();
+      }
+      await opts.setup?.(ctx);
+    },
+  });
+}

package/src/daemon.ts

@@ -159,6 +159,7 @@ import {
   unbindRoute,
   type Route as IngressRoute,
 } from "./harness/ingress-table.js";
+import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator, type TlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
 import { isOnStickyDisk } from "./harness/sticky-paths.js";
@@ -1940,6 +1941,7 @@ const INGRESS_HTTPS_SERVERS = new Map<number, any>();
  * the listener is bound once and lives as long as the project does.
  */
 let HTTPS_TERMINATOR: TlsTerminator | undefined;
+let HTTPS_HTTP2_PROXY: Awaited<ReturnType<typeof startHttp2Proxy>> | undefined;
 /**
  * The in-flight first bind of :443, if one is running.
  *
@@ -2003,6 +2005,8 @@ function stopIngressServers(): void {
   // has nothing left to reach.
   HTTPS_TERMINATOR?.close();
   HTTPS_TERMINATOR = undefined;
+  HTTPS_HTTP2_PROXY?.close();
+  HTTPS_HTTP2_PROXY = undefined;
   HTTPS_INGRESS_STARTING = undefined;
   clearTables(INGRESS);
 }
@@ -2142,7 +2146,7 @@ async function startIngress(): Promise<void> {
   if (LOWERED.proxies.length > 0) {
     const routes = ensurePort(INGRESS_HTTP_PORT);
     for (const p of LOWERED.proxies) {
-      routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+      routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port, ...(p.http2 ? { http2: true } : {}) });
     }
   }
   // The :443 route table mirrors every handler whose hostname a cert
@@ -2158,7 +2162,7 @@ async function startIngress(): Promise<void> {
     }
     for (const p of LOWERED.proxies) {
       if (certCovers(p.hostname)) {
-        httpsRoutes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+        httpsRoutes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port, ...(p.http2 ? { http2: true } : {}) });
       }
     }
   }
@@ -2246,10 +2250,23 @@ async function startHttpsIngress(Bun: any): Promise<void> {
   });
   INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, plain);
   try {
+    HTTPS_HTTP2_PROXY = await startHttp2Proxy({
+      upstreamFor: async (host) => {
+        const route = matchIngressRoute(routes, host);
+        if (route?.kind !== "proxy" || !route.http2) return undefined;
+        return `http://${await proxyUpstreamHost(route.service)}:${route.port}`;
+      },
+      clientIpFor: (port) => HTTPS_TERMINATOR?.clientIpFor(port),
+    });
     HTTPS_TERMINATOR = await startTlsTerminator({
       port: INGRESS_HTTPS_PORT,
       hostname: "0.0.0.0",
       upstreamPort: plain.port,
+      http2Port: HTTPS_HTTP2_PROXY.port,
+      supportsHttp2: (name) => {
+        const route = matchIngressRoute(routes, (name ?? "").toLowerCase());
+        return route?.kind === "proxy" && route.http2 === true;
+      },
       certFor: (serverName) => {
         if (serverName === undefined) return INGRESS.certByHost.values().next().value;
         const name = selectCertName(INGRESS.certByHost.keys(), serverName.toLowerCase());
@@ -2259,6 +2276,8 @@ async function startHttpsIngress(Bun: any): Promise<void> {
   } catch (err) {
     // Leave nothing half-built: a registered plaintext server with no
     // terminator would make `planBind` believe :443 is up.
+    HTTPS_HTTP2_PROXY?.close();
+    HTTPS_HTTP2_PROXY = undefined;
     INGRESS_HTTPS_SERVERS.delete(INGRESS_HTTPS_PORT);
     try {
       plain.stop(true);
@@ -2300,10 +2319,10 @@ function certCovers(hostname: string): boolean {
  * per-test snapshot exactly like fake state — a `dependsOn` child inherits
  * it, siblings forked from an earlier snapshot never see it.
  */
-async function bindRuntimeTls(hostname: string, service: string, port: number): Promise<void> {
+async function bindRuntimeTls(hostname: string, service: string, port: number, http2?: boolean): Promise<void> {
   // Reuse the boot primitives for validation + lowercasing; throws on a
   // malformed hostname / upstream just like a boot `tls` would at load.
-  const decl = makeProxyDecl(hostname, { service, port });
+  const decl = makeProxyDecl(hostname, { service, port, http2 });
   const host = decl.hostname;
   if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
     throw new Error(
@@ -2311,7 +2330,7 @@ async function bindRuntimeTls(hostname: string, service: string, port: number):
     );
   }
   const Bun = requireBun();
-  const route: Route = { kind: "proxy", service, port };
+  const route: Route = { kind: "proxy", service, port, http2 };
 
   // Decide the cost before mutating anything: an already-covered hostname
   // (an exact duplicate, or one under a boot wildcard) needs only a route.
@@ -3133,7 +3152,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
     // `tls` is the runtime twin of a boot service's: stand up a
     // TLS-terminating reverse proxy at https://<hostname>/ → this container.
     for (const entry of svc.tls ?? []) {
-      await bindRuntimeTls(entry.hostname, svc.name, entry.port);
+      await bindRuntimeTls(entry.hostname, svc.name, entry.port, entry.http2);
     }
     RUNTIME_SERVICES.set(svc.name, svc);
     recordEnv({

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

@@ -0,0 +1,91 @@
+import { afterEach, expect, test } from "bun:test";
+import http2 from "node:http2";
+import { once } from "node:events";
+import { startHttp2Proxy } from "./http2-proxy";
+
+const cleanup: (() => void)[] = [];
+afterEach(() => { for (const close of cleanup.splice(0).reverse()) close(); });
+async function backend(handler: (stream: http2.ServerHttp2Stream, headers: http2.IncomingHttpHeaders) => void) {
+  const server = http2.createServer();
+  const sessions = new Set<http2.ServerHttp2Session>();
+  server.on("session", session => { sessions.add(session); session.on("error", () => {}); });
+  server.on("stream", (stream, headers) => { stream.on("error", () => {}); handler(stream, headers); });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  cleanup.push(() => { for (const session of sessions) session.destroy(); server.close(); });
+  return `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+}
+async function frontend(routes: Map<string, string>) {
+  const proxy = await startHttp2Proxy({ upstreamFor: async host => routes.get(host), clientIpFor: () => "10.0.0.2" });
+  cleanup.push(() => proxy.close());
+  const session = http2.connect(`http://127.0.0.1:${proxy.port}`);
+  session.on("error", () => {});
+  cleanup.push(() => session.destroy());
+  return session;
+}
+async function request(session: http2.ClientHttp2Session, authority: string) {
+  const stream = session.request({ ":authority": authority, ":path": "/rpc" });
+  let text = "";
+  stream.setEncoding("utf8"); stream.on("data", chunk => { text += chunk; });
+  const [headers] = await once(stream, "response");
+  await once(stream, "end");
+  return { text, headers };
+}
+
+test("routes each HTTP/2 authority, including routes added to an existing connection", async () => {
+  const a = await backend(s => { s.respond(); s.end("a"); });
+  const b = await backend(s => { s.respond(); s.end("b"); });
+  const routes = new Map([["a.test", a]]);
+  const client = await frontend(routes);
+  expect((await request(client, "a.test")).text).toBe("a");
+  routes.set("b.test", b);
+  expect((await request(client, "b.test:443")).text).toBe("b");
+  expect((await request(client, "missing.test")).headers[":status"]).toBe(421);
+});
+
+test("streams both directions before request end and forwards request/response trailers", async () => {
+  let upstreamHeaders: http2.IncomingHttpHeaders | undefined;
+  let requestTrailers: http2.IncomingHttpHeaders | undefined;
+  const url = await backend((s, h) => {
+    upstreamHeaders = h;
+    s.respond({ ":status": 200, "content-type": "application/grpc", "metadata-bin": "AQID" }, { waitForTrailers: true });
+    s.on("trailers", t => { requestTrailers = t; });
+    s.on("data", data => s.write(data));
+    s.on("end", () => s.end());
+    s.on("wantTrailers", () => s.sendTrailers({ "grpc-status": "7", "grpc-message": "Permission%20denied" }));
+  });
+  const client = await frontend(new Map([["grpc.test", url]]));
+  const stream = client.request({ ":authority": "grpc.test", ":path": "/package.Service/Call", ":method": "POST", "content-type": "application/grpc", te: "trailers" }, { waitForTrailers: true });
+  stream.on("wantTrailers", () => stream.sendTrailers({ "request-trailer": "preserved" }));
+  const response = once(stream, "response");
+  const first = once(stream, "data");
+  stream.write(Buffer.from([0, 0, 0, 0, 3, 0, 128, 255]));
+  expect((await first)[0]).toEqual(Buffer.from([0, 0, 0, 0, 3, 0, 128, 255]));
+  const trailers = once(stream, "trailers");
+  stream.end();
+  expect((await trailers)[0]["grpc-status"]).toBe("7");
+  expect((await response)[0]["metadata-bin"]).toBe("AQID");
+  expect(requestTrailers?.["request-trailer"]).toBe("preserved");
+  expect(upstreamHeaders?.[":authority"]).toBe("grpc.test");
+  expect(upstreamHeaders?.["x-forwarded-proto"]).toBe("https");
+  expect(upstreamHeaders?.["x-forwarded-for"]).toBe("10.0.0.2");
+});
+
+test("client cancellation reaches upstream without breaking another multiplexed RPC", async () => {
+  let cancelled!: Promise<unknown[]>;
+  const url = await backend((s, h) => {
+    if (h[":path"] === "/cancel") { cancelled = once(s, "aborted"); s.respond(); s.write("ready"); }
+    else { s.respond(); s.end("healthy"); }
+  });
+  const client = await frontend(new Map([["grpc.test", url]]));
+  const stream = client.request({ ":authority": "grpc.test", ":path": "/cancel" });
+  await once(stream, "data");
+  stream.close(http2.constants.NGHTTP2_CANCEL);
+  await cancelled;
+  expect((await request(client, "grpc.test")).text).toBe("healthy");
+});
+
+test("an unavailable upstream produces a bounded error response", async () => {
+  const client = await frontend(new Map([["grpc.test", "http://127.0.0.1:1"]]));
+  expect((await request(client, "grpc.test")).headers[":status"]).toBe(502);
+});

package/src/harness/http2-proxy.ts

@@ -0,0 +1,96 @@
+import http2, { type IncomingHttpHeaders, type OutgoingHttpHeaders, type ServerHttp2Stream } from "node:http2";
+import { isHopByHop } from "./http-proxy";
+import { hostWithoutPort } from "./hostmatch";
+
+export interface Http2ProxyOptions {
+  /** Resolve each stream independently; one connection can carry multiple authorities. */
+  upstreamFor(hostname: string): Promise<string | undefined>;
+  clientIpFor?(port: number | undefined): string | undefined;
+}
+
+function headersForHop(headers: IncomingHttpHeaders, pseudo: boolean): OutgoingHttpHeaders {
+  const result: OutgoingHttpHeaders = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if ((!pseudo && name.startsWith(":")) || (isHopByHop(name) && !(name === "te" && value === "trailers"))) continue;
+    result[name] = value;
+  }
+  return result;
+}
+
+/** A stream proxy rather than fetch: gRPC depends on duplex bodies and trailers. */
+export async function startHttp2Proxy(options: Http2ProxyOptions) {
+  const server = http2.createServer();
+  const sessions = new Set<http2.Http2Session>();
+  const track = (session: http2.Http2Session) => {
+    sessions.add(session);
+    session.on("error", () => {});
+    session.once("close", () => sessions.delete(session));
+  };
+  server.on("session", track);
+  server.on("stream", (downstream: ServerHttp2Stream, headers) => {
+    downstream.on("error", () => {});
+    void forward(downstream, headers).catch(() => {
+      if (downstream.destroyed || downstream.closed) return;
+      if (downstream.headersSent) downstream.close(http2.constants.NGHTTP2_INTERNAL_ERROR);
+      else { downstream.respond({ ":status": 502 }); downstream.end("HTTP/2 upstream unavailable"); }
+    });
+  });
+
+  async function forward(downstream: ServerHttp2Stream, headers: IncomingHttpHeaders) {
+    const authority = String(headers[":authority"] ?? "");
+    const upstreamUrl = await options.upstreamFor(hostWithoutPort(authority.toLowerCase()));
+    if (downstream.destroyed || downstream.closed) return;
+    if (!upstreamUrl) {
+      // A coalesced connection must not silently route an authority to its SNI backend.
+      downstream.respond({ ":status": 421 });
+      downstream.end("No HTTP/2 route for this authority");
+      return;
+    }
+    const session = http2.connect(upstreamUrl);
+    track(session);
+    let requestTrailers: OutgoingHttpHeaders = {};
+    let responseTrailers: OutgoingHttpHeaders = {};
+    const requestHeaders = headersForHop(headers, true);
+    requestHeaders[":scheme"] = "http";
+    requestHeaders["x-forwarded-proto"] = "https";
+    requestHeaders["x-forwarded-host"] = authority;
+    const clientIp = options.clientIpFor?.(downstream.session?.socket.remotePort);
+    if (clientIp) requestHeaders["x-forwarded-for"] = [headers["x-forwarded-for"], clientIp].filter(Boolean).join(", ");
+    let upstream: http2.ClientHttp2Stream;
+    try { upstream = session.request(requestHeaders, { endStream: false, waitForTrailers: true }); }
+    catch (error) { session.destroy(); throw error; }
+    const fail = () => {
+      if (!downstream.closed && !downstream.destroyed) {
+        if (downstream.headersSent) downstream.close(http2.constants.NGHTTP2_INTERNAL_ERROR);
+        else { downstream.respond({ ":status": 502 }); downstream.end("HTTP/2 upstream unavailable"); }
+      }
+      session.destroy();
+    };
+    session.on("error", fail);
+    upstream.on("error", fail);
+    downstream.on("trailers", trailers => { requestTrailers = headersForHop(trailers, false); });
+    upstream.on("wantTrailers", () => { if (!upstream.destroyed && !upstream.closed) upstream.sendTrailers(requestTrailers); });
+    upstream.on("trailers", trailers => { responseTrailers = headersForHop(trailers, false); });
+    downstream.on("wantTrailers", () => {
+      if (!downstream.destroyed && !downstream.closed) downstream.sendTrailers(responseTrailers);
+    });
+    upstream.on("response", response => {
+      if (downstream.destroyed || downstream.closed) return;
+      downstream.respond(headersForHop(response, true), { waitForTrailers: true });
+      upstream.pipe(downstream);
+    });
+    downstream.on("aborted", () => upstream.close(downstream.rstCode || http2.constants.NGHTTP2_CANCEL));
+    upstream.on("aborted", () => { if (!downstream.closed) downstream.close(upstream.rstCode || http2.constants.NGHTTP2_CANCEL); });
+    downstream.once("close", () => session.destroy());
+    downstream.pipe(upstream);
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(); });
+  });
+  return {
+    port: (server.address() as { port: number }).port,
+    close() { for (const session of sessions) session.destroy(); server.close(); },
+  };
+}

package/src/harness/ingress-table.ts

@@ -53,7 +53,7 @@ import { certCovers, isWildcard, wildcardSuffix } from "./hostmatch";
  */
 export type Route<F = unknown> =
   | { kind: "fake"; fake: F }
-  | { kind: "proxy"; service: string; port: number };
+  | { kind: "proxy"; service: string; port: number; http2?: boolean };
 
 /** A PEM leaf + key, as handed to `Bun.serve`'s TLS config. */
 export interface Leaf {
@@ -70,7 +70,7 @@ export interface Leaf {
 export interface IngressTables<F = unknown> {
   /** Listen port → (hostname → route). Values are mutated in place. */
   routesByPort: Map<number, Map<string, Route<F>>>;
-  /** SNI server name → leaf. Adding to this is what forces a rebind. */
+  /** SNI server name → leaf. Read live by the TLS terminator without rebinding. */
   certByHost: Map<string, Leaf>;
 }
 

package/src/harness/tls-terminator.test.ts

@@ -18,6 +18,9 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test
 import { spawnSync } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import net from "node:net";
+import http2 from "node:http2";
+import { once } from "node:events";
+import { startHttp2Proxy } from "./http2-proxy";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import tls from "node:tls";
@@ -238,3 +241,29 @@ describe("the pipe", () => {
     expect(term.connectionCount()).toBe(0);
   });
 });
+
+
+test("ALPN selects HTTP/2 only for opted-in routes and keeps HTTP/1.1 working", async () => {
+  const backend = http2.createServer();
+  const sessions = new Set<http2.Http2Session>();
+  backend.on("session", s => { sessions.add(s); s.on("error", () => {}); });
+  backend.on("stream", (s: http2.ServerHttp2Stream) => { s.respond({ ":status": 200 }); s.end("grpc backend"); });
+  backend.listen(0, "127.0.0.1");
+  await once(backend, "listening");
+  const h2 = await startHttp2Proxy({ upstreamFor: async () => `http://127.0.0.1:${(backend.address() as net.AddressInfo).port}` });
+  const optedIn = new Set(["app.test"]);
+  const terminator = await startTlsTerminator({ port: 0, hostname: "127.0.0.1", upstreamPort: plain.port,
+    http2Port: h2.port, supportsHttp2: name => optedIn.has(name), certFor: name => leaves.get(name ?? "app.test") });
+  const client = http2.connect(`https://127.0.0.1:${terminator.port}`, { servername: "app.test", ca: caPem });
+  try {
+    const stream = client.request({ ":authority": "app.test", ":path": "/" });
+    stream.setEncoding("utf8"); let body = ""; stream.on("data", chunk => { body += chunk; });
+    await once(stream, "end");
+    expect(client.alpnProtocol).toBe("h2"); expect(body).toBe("grpc backend");
+    const socket = tls.connect({ host: "127.0.0.1", port: terminator.port, servername: "late.test", ca: caPem, ALPNProtocols: ["h2", "http/1.1"] });
+    try { await once(socket, "secureConnect"); expect(socket.alpnProtocol).toBe("http/1.1"); } finally { socket.destroy(); }
+    optedIn.add("late.test");
+    const late = tls.connect({ host: "127.0.0.1", port: terminator.port, servername: "late.test", ca: caPem, ALPNProtocols: ["h2", "http/1.1"] });
+    try { await once(late, "secureConnect"); expect(late.alpnProtocol).toBe("h2"); } finally { late.destroy(); }
+  } finally { client.destroy(); terminator.close(); h2.close(); for (const s of sessions) s.destroy(); backend.close(); }
+});