@specific.dev/spectest 0.93.1 → 0.95.0

package/dist/harness/tls-terminator.d.ts

@@ -6,6 +6,9 @@ export interface TlsTerminatorOptions {
     hostname: string;
     /** Loopback port of the plaintext ingress server to pipe into. */
     upstreamPort: number;
+    /** Loopback HTTP/2 router, selected only for an opted-in SNI hostname. */
+    http2Port?: number;
+    supportsHttp2?(serverName: string): boolean;
     /**
      * The leaf to serve for an SNI server name, read live on every
      * handshake — this is what lets a certificate be added with no restart.

package/dist/harness/tls-terminator.js

@@ -34,7 +34,8 @@
  *
  * The terminator does TLS and *nothing else*: it accepts on :443, picks a
  * leaf by SNI, and pipes the decrypted stream to a plaintext `Bun.serve`
- * bound on loopback. Everything downstream — routing, fakes,
+ * bound on loopback. Opted-in HTTP/2 routes select a separate stream router
+ * by ALPN; HTTP/1.1 and WebSockets retain the existing listener. Everything downstream — routing, fakes,
  * interceptors, reverse-proxying, and `server.upgrade()` WebSocket
  * bridging — is the same `Bun.serve` code that already serves :80, run
  * unchanged. Terminating HTTP here instead (`node:https`, `(req, res)`)
@@ -113,6 +114,8 @@ export function startTlsTerminator(opts) {
     const fallback = opts.certFor(undefined);
     const server = tls.createServer({
         ...(fallback ? { cert: fallback.cert, key: fallback.key } : {}),
+        ...(opts.http2Port ? { ALPNCallback: ({ servername, protocols }) => protocols.includes("h2") && opts.supportsHttp2?.(servername) ? "h2"
+                : protocols.includes("http/1.1") ? "http/1.1" : undefined } : {}),
         SNICallback: (serverName, cb) => {
             const leaf = opts.certFor(serverName) ?? fallback;
             // No certificate at all is a handshake we cannot complete. Answer
@@ -133,7 +136,8 @@ export function startTlsTerminator(opts) {
         // its bytes are buffered rather than dropped — which is the normal
         // case, since a client sends its first request the instant the
         // handshake completes.
-        const upstream = net.connect(opts.upstreamPort, "127.0.0.1");
+        const upstreamPort = client.alpnProtocol === "h2" ? opts.http2Port : opts.upstreamPort;
+        const upstream = net.connect(upstreamPort, "127.0.0.1");
         upstream.setTimeout(0);
         upstream.setNoDelay(true);
         client.setNoDelay(true);
@@ -161,7 +165,7 @@ export function startTlsTerminator(opts) {
             teardown();
         });
         upstream.on("error", (err) => {
-            warn(`ingress upstream :${opts.upstreamPort} failed`, err);
+            warn(`ingress upstream :${upstreamPort} failed`, err);
             teardown();
         });
         client.on("close", teardown);
@@ -178,7 +182,7 @@ export function startTlsTerminator(opts) {
         server.listen(opts.port, opts.hostname, () => {
             server.removeListener("error", reject);
             resolve({
-                port: opts.port,
+                port: server.address().port,
                 clientIpFor: (upstreamPort) => upstreamPort === undefined ? undefined : clientIpByUpstreamPort.get(upstreamPort),
                 connectionCount: () => live.size,
                 close: () => {

package/dist/harness/ws-bridge.d.ts

@@ -33,11 +33,9 @@ export declare function parseSubprotocols(header: string | null | undefined): st
  * 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.
+ * headers and the original Host.
  */
 export declare function upstreamHandshakeHeaders(req: Headers, opts: {
-    service: string;
-    port: number;
     proto: string;
     clientIp?: string;
 }): Record<string, string>;

package/dist/harness/ws-bridge.js

@@ -19,7 +19,7 @@
  * the handshake and the frame relay so the two can be tested on loopback
  * without a VM.
  */
-import { forwardableHeaders } from "./http-proxy.js";
+import { upstreamRequestHeaders } 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
@@ -46,28 +46,15 @@ export function parseSubprotocols(header) {
  * 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.
+ * headers and the original Host.
  */
 export function upstreamHandshakeHeaders(req, opts) {
     const out = {};
-    forwardableHeaders(req).forEach((value, key) => {
+    upstreamRequestHeaders(req, opts).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;
 }
 /**

package/dist/index.d.ts

@@ -741,6 +741,9 @@ export interface ServiceTls {
     /** HTTP port the service listens on inside its container. The
      * daemon forwards proxied requests here over `spectest-net`. */
     port: number;
+    /** Accept HTTP/2 over TLS and forward it as plaintext HTTP/2 (h2c).
+     * Required for gRPC. HTTP/1.1 continues to use the existing HTTP proxy. */
+    http2?: boolean;
 }
 /** @internal Normalized wire representation; legacy definitions remain accepted. */
 export type NormalizedServiceImage = {

package/dist/index.js

@@ -361,6 +361,8 @@ function validateEnvironmentConfig(config) {
             if (!entry || typeof entry.hostname !== "string" || typeof entry.port !== "number") {
                 throw new Error(`service "${name}" tls entry must be { hostname: string, port: number }; got ${JSON.stringify(entry)}`);
             }
+            if (entry.http2 !== undefined && typeof entry.http2 !== "boolean")
+                throw new Error(`service "${name}" tls http2 must be a boolean`);
             const h = entry.hostname.toLowerCase();
             if (!HOSTNAME_RE.test(hostPatternBody(h))) {
                 throw new Error(`service "${name}" tls hostname ${JSON.stringify(entry.hostname)} is not a multi-label DNS name or wildcard (e.g. "app.test", "*.us-east-1.amazonaws.com")`);

package/dist/ingress.d.ts

@@ -23,6 +23,7 @@ export interface ProxyDecl {
     upstream: {
         service: string;
         port: number;
+        http2?: boolean;
     };
 }
 export type IngressDecl = CertificateDecl | DnsDecl | ProxyDecl;
@@ -69,6 +70,7 @@ export declare function dnsName(hostname: string, target: DnsTarget): DnsDecl;
 export declare function proxy(hostname: string, upstream: {
     service: string;
     port: number;
+    http2?: boolean;
 }): ProxyDecl;
 /**
  * Attach low-level ingress decls to a service definition a component
@@ -97,6 +99,7 @@ export interface LoweredIngress {
         hostname: string;
         service: string;
         port: number;
+        http2?: boolean;
     }[];
     /** Hostnames that resolve to the daemon ingress gateway (DNS registry
      *  + `--add-host` on every container). Covers fakes, TLS proxies, and

package/dist/ingress.js

@@ -99,6 +99,8 @@ export function proxy(hostname, upstream) {
     if (!upstream || typeof upstream.service !== "string" || typeof upstream.port !== "number") {
         throw new Error(`proxy(${JSON.stringify(hostname)}): upstream must be { service: string, port: number }`);
     }
+    if (upstream.http2 !== undefined && typeof upstream.http2 !== "boolean")
+        throw new Error("proxy(): http2 must be a boolean");
     return { kind: "proxy", hostname: hostname.toLowerCase(), upstream };
 }
 /** Symbol key under which `provides(...)` stashes a component's ingress
@@ -163,7 +165,7 @@ export function lowerIngress(project) {
                 break;
             case "proxy": {
                 const service = resolveSelf(decl.upstream.service, selfKey);
-                proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port });
+                proxies.push({ hostname: decl.hostname, service, port: decl.upstream.port, ...(decl.upstream.http2 ? { http2: true } : {}) });
                 // A proxied hostname must route to the daemon. A wildcard one can
                 // only be answered by the resolver (there is no `--add-host` for a
                 // pattern), so it goes in the wildcard table pointed at the ingress.
@@ -202,7 +204,7 @@ export function lowerIngress(project) {
         // `tls: [{ hostname, port }]` → cert + TLS-terminated reverse proxy.
         for (const entry of svc.tls ?? []) {
             applyDecl(certificate([entry.hostname]), name);
-            applyDecl(proxy(entry.hostname, { service: name, port: entry.port }), name);
+            applyDecl(proxy(entry.hostname, { service: name, port: entry.port, ...(entry.http2 ? { http2: true } : {}) }), name);
         }
         // `hostnames: [h]` → plain peer alias (no daemon hop).
         for (const h of svc.hostnames ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.93.1",
+  "version": "0.95.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/emulate/entry.mjs

@@ -179,9 +179,8 @@ Bun.serve({
     // own IP and never sends a provider name.
     if (url.pathname === "/healthz") return new Response("ok\n");
 
-    // The daemon reverse-proxies us and rewrites `Host` to the service-net
-    // name, so the provider the client asked for only survives in
-    // `X-Forwarded-Host`. Read that first; `Host` covers a direct call.
+    // Ingress preserves Host and also stamps X-Forwarded-Host with the
+    // requested authority. Host covers direct calls to the emulator.
     const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "")
       .toLowerCase()
       .replace(/:\d+$/, "");

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/components/s3.ts

@@ -20,9 +20,9 @@ export interface S3Options {
    * via the daemon's TLS-terminating reverse proxy. Optional — defaults to none;
    * the store is always reachable at `http://<key>:9090` regardless. Set this
    * only when the app under test hardcodes a specific prod S3 endpoint it can't
-   * be told to override (`https://<bucket>.s3.amazonaws.com`, a provider's
-   * storage host): the daemon mints a cert for each host and proxies to the
-   * store's plain HTTP. The store ignores SigV4, so the Host rewrite is harmless.
+   * be told to override (a provider's storage host; requests must still use
+   * path-style addressing): the daemon mints a cert for each host and proxies to the
+   * store's plain HTTP while preserving the requested Host.
    */
   hosts?: string[];
   /** Access key id the helper client signs with. The store ignores SigV4, so

package/src/daemon.ts

@@ -130,6 +130,7 @@ import {
   augmentCorsResponse,
   corsPreflightResponse,
   isCorsPreflight,
+  upstreamRequestHeaders,
 } from "./harness/http-proxy.js";
 import {
   WS_BRIDGE_HANDLERS,
@@ -158,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";
@@ -1939,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.
  *
@@ -2002,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);
 }
@@ -2141,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
@@ -2157,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 } : {}) });
       }
     }
   }
@@ -2245,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());
@@ -2258,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);
@@ -2299,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(
@@ -2310,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.
@@ -2579,8 +2599,6 @@ async function proxyToService(
     // and the forwardable headers. Same provenance stamps as the HTTP path.
     const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
     const headers = upstreamHandshakeHeaders(req.headers, {
-      service,
-      port,
       proto,
       clientIp: ingressClientIp(server, req, proto),
     });
@@ -2614,25 +2632,10 @@ async function proxyToService(
     );
   }
 
-  const fwdHeaders = new Headers();
-  for (const [k, v] of req.headers) {
-    if (HOP_BY_HOP_HEADERS.has(k.toLowerCase())) continue;
-    fwdHeaders.append(k, v);
-  }
-  // Standard reverse-proxy provenance headers: the upstream sees the
-  // public scheme/host it was reached through and the client's address,
-  // even though we rewrite Host below to the service-net name.
-  const clientIp = ingressClientIp(server, req, proto);
-  const priorXff = req.headers.get("x-forwarded-for");
-  const xff = clientIp ? (priorXff ? `${priorXff}, ${clientIp}` : clientIp) : priorXff;
-  if (xff) fwdHeaders.set("x-forwarded-for", xff);
-  fwdHeaders.set("x-forwarded-proto", proto);
-  const publicHost = req.headers.get("host");
-  if (publicHost) fwdHeaders.set("x-forwarded-host", publicHost);
-  // Override Host so the upstream sees its own service-net name, not
-  // the public hostname. Lets origin servers that vhost by Host header
-  // continue to find the right virtual host.
-  fwdHeaders.set("host", `${service}:${port}`);
+  const fwdHeaders = upstreamRequestHeaders(req.headers, {
+    proto,
+    clientIp: ingressClientIp(server, req, proto),
+  });
   // Fresh connection per upstream request — never reuse a pooled
   // keep-alive conn. Upstreams with short idle timeouts (uvicorn defaults
   // to 5s) close pooled connections under Bun's fetch, and the next
@@ -3149,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({