@specific.dev/spectest 0.93.1 → 0.95.0

package/README.md

@@ -15,6 +15,31 @@ 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
+
+`pubsub()` runs Google's local emulator and creates topics/subscriptions before
+dependent services start:
+
+```ts
+import { pubsub } from "@specific.dev/spectest/components";
+
+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 +138,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/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/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/components/s3.d.ts

@@ -17,9 +17,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/dist/daemon.js

@@ -56,10 +56,11 @@ import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
-import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
+import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, upstreamRequestHeaders, } from "./harness/http-proxy.js";
 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, {
@@ -2098,8 +2118,6 @@ server, service, port, listenerLabel, proto) {
         // 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),
         });
@@ -2127,28 +2145,10 @@ server, service, port, listenerLabel, proto) {
         }
         return new Response(`spectest-daemon: ws upgrade refused on ${listenerLabel}\n`, { status: 426, headers: { "content-type": "text/plain" } });
     }
-    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
@@ -2619,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/http-proxy.d.ts

@@ -12,13 +12,18 @@
  * Forwarding `transfer-encoding` or `content-length` from a re-encoded
  * body is the classic way to produce a response the client cannot frame;
  * forwarding `connection` leaks our keep-alive intent to the upstream.
- * `host` is here because the proxy sets its own — the upstream must see
- * the service it actually is, not the public name the client asked for.
+ * `host` identifies the requested origin and must survive the proxy hop.
  */
 export declare const HOP_BY_HOP_HEADERS: ReadonlySet<string>;
 export declare function isHopByHop(name: string): boolean;
 /** Copy headers, dropping the ones that belong to this connection. */
 export declare function forwardableHeaders(headers: Headers): Headers;
+/** Preserve the requested Host (including its port) while dialing the service's
+ * internal address. HTTP and WebSocket forwarding share this policy. */
+export declare function upstreamRequestHeaders(headers: Headers, opts: {
+    proto: string;
+    clientIp?: string;
+}): Headers;
 /**
  * A CORS preflight is an `OPTIONS` carrying both `Origin` and
  * `Access-Control-Request-Method`. An `OPTIONS` without them is a normal

package/dist/harness/http-proxy.js

@@ -12,8 +12,7 @@
  * Forwarding `transfer-encoding` or `content-length` from a re-encoded
  * body is the classic way to produce a response the client cannot frame;
  * forwarding `connection` leaks our keep-alive intent to the upstream.
- * `host` is here because the proxy sets its own — the upstream must see
- * the service it actually is, not the public name the client asked for.
+ * `host` identifies the requested origin and must survive the proxy hop.
  */
 export const HOP_BY_HOP_HEADERS = new Set([
     "connection",
@@ -24,7 +23,6 @@ export const HOP_BY_HOP_HEADERS = new Set([
     "trailers",
     "transfer-encoding",
     "upgrade",
-    "host",
 ]);
 export function isHopByHop(name) {
     return HOP_BY_HOP_HEADERS.has(name.toLowerCase());
@@ -38,6 +36,22 @@ export function forwardableHeaders(headers) {
     });
     return out;
 }
+/** Preserve the requested Host (including its port) while dialing the service's
+ * internal address. HTTP and WebSocket forwarding share this policy. */
+export function upstreamRequestHeaders(headers, opts) {
+    const out = forwardableHeaders(headers);
+    const priorXff = headers.get("x-forwarded-for");
+    const xff = opts.clientIp
+        ? priorXff ? `${priorXff}, ${opts.clientIp}` : opts.clientIp
+        : priorXff;
+    if (xff)
+        out.set("x-forwarded-for", xff);
+    out.set("x-forwarded-proto", opts.proto);
+    const host = headers.get("host");
+    if (host)
+        out.set("x-forwarded-host", host);
+    return out;
+}
 /**
  * A CORS preflight is an `OPTIONS` carrying both `Origin` and
  * `Access-Control-Request-Method`. An `OPTIONS` without them is a normal

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`). */