@specific.dev/spectest 0.94.0 → 0.96.0

package/README.md

@@ -15,6 +15,34 @@ Install the [Spectest CLI](https://github.com/specific-dev/spectest/releases/lat
 and run `spectest docs /installation` for project setup and authentication.
 `spectest docs` contains the complete offline authoring guide.
 
+## Google Cloud Pub/Sub
+
+Google Cloud components are available from `@specific.dev/spectest/components/gcp`.
+The existing Pub/Sub exports from `/components` remain supported.
+
+`pubsub()` runs Google's local emulator and creates topics/subscriptions before
+dependent services start:
+
+```ts
+import { pubsub } from "@specific.dev/spectest/components/gcp";
+
+const services = {
+  messages: pubsub({
+    projectId: "local-orders",
+    subscriptions: { "orders-worker": { topic: "orders" } },
+  }),
+};
+```
+
+The default endpoint is `https://pubsub.googleapis.com`, with trusted TLS and
+gRPC support. Keep your application's normal endpoint configuration, supply
+local test credentials and project `local-orders`, and use
+`dependsOn: ["messages"]`. Tests can call
+`ctx.svc.messages.publish()`, `pull()` and `acknowledge()`. VM snapshots preserve
+the emulator's live state. See `examples/google-pubsub` and
+`spectest docs /components/pubsub` for test credential setup and options.
+Set `tls: false` to use explicit plaintext emulator mode instead.
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and
@@ -113,3 +141,13 @@ Dockerfile builds in `images` targeting `registry.test/...` are published and
 preloaded from the same cached build, preserving digests without an export/push
 step. Other images keep direct preloading. Registry writes stay isolated across
 test forks; client and containerd CA trust are configured automatically.
+
+### HTTP/2 and gRPC ingress
+
+For a service listening on plaintext HTTP/2 (h2c), declare
+`tls: [{ hostname: "grpc.example.test", port: 50051, http2: true }]`.
+Clients use trusted TLS on port 443. The ingress selects HTTP/2 with ALPN,
+routes each stream by `:authority`, and preserves streaming bodies, metadata,
+trailers, and cancellation. HTTP/1.1 requests still use the existing HTTP proxy.
+Runtime services support the same option. HTTP/2 streams currently bypass
+`ctx.intercept` and HTTP request recording. `pubsub()` enables this by default.

package/dist/components/gcp.d.ts

@@ -0,0 +1,2 @@
+/** Google Cloud components for local Spectest environments. */
+export { pubsub, pubsubClient, type PubSubOptions, type PubSubClient, type PubSubHelpers, type PubSubSubscriptionOptions, type PubSubMessage, type PubSubReceivedMessage, } from "./pubsub.js";

package/dist/components/gcp.js

@@ -0,0 +1,2 @@
+/** Google Cloud components for local Spectest environments. */
+export { pubsub, pubsubClient, } from "./pubsub.js";

package/dist/components/index.d.ts

@@ -1,3 +1,4 @@
+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";
 export { postgres, type PostgresOptions, type PostgresHelpers, } from "./postgres.js";
 export { s3, type S3Options, type S3Helpers, } from "./s3.js";

package/dist/components/index.js

@@ -1,4 +1,5 @@
 // Reusable, pre-built service definitions for common dependencies.
+export { pubsub, pubsubClient } from "./pubsub.js";
 export { temporal, temporalClient } from "./temporal.js";
 //
 // Each component returns a fully-formed `ServiceDefinition` ready to

package/dist/components/pubsub.d.ts

@@ -0,0 +1,77 @@
+import type { ServiceSetupContext, ServicesMap } from "../index.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;
+}
+/** 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 declare function pubsubClient(endpoint: string, projectId?: string, fetcher?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>): {
+    projectId: string;
+    endpoint: string;
+    topicName: (id: string) => string;
+    subscriptionName: (id: string) => string;
+    createTopic(id: string): Promise<{
+        name: string;
+    }>;
+    createSubscription(id: string, options: PubSubSubscriptionOptions): Promise<{
+        name: string;
+        topic: string;
+        ackDeadlineSeconds: number;
+    }>;
+    publish(topic: string, data: string | Uint8Array, attributes?: Record<string, string>): Promise<string>;
+    /** A pull leases messages; call acknowledge() to remove them. Empty is valid.
+     * Uses the emulator's immediate pull mode for bounded test polling.
+     */
+    pull(subscription: string, options?: {
+        maxMessages?: number;
+        timeoutMs?: number;
+    }): Promise<PubSubReceivedMessage[]>;
+    acknowledge(subscription: string, ackIds: string[]): Promise<void>;
+};
+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 declare function pubsub(opts?: PubSubOptions): import("../index.js").ServiceGroup<ServicesMap, PubSubHelpers, "emulator">;

package/dist/components/pubsub.js

@@ -0,0 +1,139 @@
+import { serviceGroup, certificate } from "../index.js";
+import { rawFetch } from "../harness/raw-fetch.js";
+import { readRaw } from "../inspect.js";
+function resourceId(id) {
+    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) {
+    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) {
+    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, projectId = "spectest", fetcher = rawFetch) {
+    projectName(projectId);
+    const base = endpoint.replace(/\/$/, "");
+    const resource = (kind, id) => `projects/${projectId}/${kind}/${resourceId(id)}`;
+    const path = (kind, id) => `/v1/projects/${projectId}/${kind}/${encodeURIComponent(resourceId(id))}`;
+    async function request(url, method, body, timeoutMs = 10000) {
+        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) : {});
+    }
+    return {
+        projectId, endpoint: base,
+        topicName: (id) => resource("topics", id),
+        subscriptionName: (id) => resource("subscriptions", id),
+        createTopic(id) {
+            return request(path("topics", id), "PUT", {});
+        },
+        createSubscription(id, options) {
+            const ackDeadlineSeconds = subscriptionOptions(options);
+            return request(path("subscriptions", id), "PUT", {
+                topic: resource("topics", options.topic), ackDeadlineSeconds,
+                ...(options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
+            });
+        },
+        async publish(topic, data, attributes) {
+            const result = await request(`${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, options = {}) {
+            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(`${path("subscriptions", subscription)}:pull`, "POST", { maxMessages, returnImmediately: true }, options.timeoutMs);
+            return result.receivedMessages ?? [];
+        },
+        async acknowledge(subscription, ackIds) {
+            await request(`${path("subscriptions", subscription)}:acknowledge`, "POST", { ackIds });
+        },
+    };
+}
+/** 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 = {}) {
+    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: () => {
+            const emulator = {
+                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) => ({
+            ...pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId, async (input, init) => readRaw(await ctx.fetch(String(input), init))),
+            emulatorHost: `${ctx.name}:${port}`,
+        }),
+        setup: async (ctx) => {
+            // 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/dist/daemon.js

@@ -60,6 +60,7 @@ import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsP
 import { WS_BRIDGE_HANDLERS, openUpstreamWebSocket, parseSubprotocols, upstreamHandshakeHeaders, } from "./harness/ws-bridge.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectCertName, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
+import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
 import { isOnStickyDisk } from "./harness/sticky-paths.js";
@@ -1513,6 +1514,7 @@ const INGRESS_HTTPS_SERVERS = new Map();
  * the listener is bound once and lives as long as the project does.
  */
 let HTTPS_TERMINATOR;
+let HTTPS_HTTP2_PROXY;
 /**
  * The in-flight first bind of :443, if one is running.
  *
@@ -1577,6 +1579,8 @@ function stopIngressServers() {
     // 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);
 }
@@ -1703,7 +1707,7 @@ async function startIngress() {
     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
@@ -1720,7 +1724,7 @@ async function startIngress() {
         }
         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 } : {}) });
             }
         }
     }
@@ -1803,10 +1807,24 @@ async function startHttpsIngress(Bun) {
     });
     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;
@@ -1818,6 +1836,8 @@ async function startHttpsIngress(Bun) {
     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);
@@ -1856,16 +1876,16 @@ function certCovers(hostname) {
  * 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, service, port) {
+async function bindRuntimeTls(hostname, service, port, http2) {
     // 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(`runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`);
     }
     const Bun = requireBun();
-    const route = { kind: "proxy", service, port };
+    const 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.
     const plan = planBind(INGRESS, host, {
@@ -2599,7 +2619,7 @@ async function startRuntimeService(spec) {
         // `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/dist/harness/http2-proxy.d.ts

@@ -0,0 +1,10 @@
+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;
+}
+/** A stream proxy rather than fetch: gRPC depends on duplex bodies and trailers. */
+export declare function startHttp2Proxy(options: Http2ProxyOptions): Promise<{
+    port: number;
+    close(): void;
+}>;

package/dist/harness/http2-proxy.js

@@ -0,0 +1,108 @@
+import http2 from "node:http2";
+import { isHopByHop } from "./http-proxy";
+import { hostWithoutPort } from "./hostmatch";
+function headersForHop(headers, pseudo) {
+    const result = {};
+    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) {
+    const server = http2.createServer();
+    const sessions = new Set();
+    const track = (session) => {
+        sessions.add(session);
+        session.on("error", () => { });
+        session.once("close", () => sessions.delete(session));
+    };
+    server.on("session", track);
+    server.on("stream", (downstream, 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, headers) {
+        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 = {};
+        let responseTrailers = {};
+        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;
+        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((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(); });
+    });
+    return {
+        port: server.address().port,
+        close() { for (const session of sessions)
+            session.destroy(); server.close(); },
+    };
+}

package/dist/harness/ingress-table.d.ts

@@ -55,6 +55,7 @@ export type Route<F = unknown> = {
     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 +71,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>;
 }
 /** Fixed HTTPS port shared by every TLS route (fakes + service `tls`). */

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/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