@specific.dev/spectest 0.97.0 → 0.99.0

package/dist/components/pubsub.js

@@ -1,175 +0,0 @@
-import { readFileSync } from "node:fs";
-import { serviceGroup, certificate } from "../index.js";
-import { rawFetch } from "../harness/raw-fetch.js";
-import { readRaw } from "../inspect.js";
-const PUSH_ADAPTER = readFileSync(new URL("./pubsub-push.py", import.meta.url), "utf8");
-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 && options.pushConfig && options.pushEndpoint !== options.pushConfig.pushEndpoint)
-        throw new Error("pubsub(): pushEndpoint and pushConfig.pushEndpoint disagree");
-    const push = options.pushConfig ?? (options.pushEndpoint ? { pushEndpoint: options.pushEndpoint } : undefined);
-    if (push) {
-        if (!push.pushEndpoint || !/^https?:$/.test(new URL(push.pushEndpoint).protocol))
-            throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
-        if (push.oidcToken && (!/^[^@\s]+@[^@\s]+$/.test(push.oidcToken.serviceAccountEmail) || (push.oidcToken.audience !== undefined && !push.oidcToken.audience)))
-            throw new Error("pubsub(): oidcToken requires a serviceAccountEmail and nonempty audience");
-    }
-    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.pushConfig ? { pushConfig: options.pushConfig } : options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
-                ...(options.deadLetterPolicy ? { deadLetterPolicy: options.deadLetterPolicy } : {}),
-                ...(options.retryPolicy ? { retryPolicy: options.retryPolicy } : {}),
-            });
-        },
-        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 });
-        },
-    };
-}
-// The official emulator ignores OIDC. Keep its push/retry/dead-letter engine,
-// but route authenticated deliveries through a local adapter in its container.
-function authenticatedPush(options, pushPort) {
-    subscriptionOptions(options);
-    const push = options.pushConfig;
-    if (!push?.oidcToken)
-        return options;
-    const config = Buffer.from(JSON.stringify({ endpoint: push.pushEndpoint, ...push.oidcToken })).toString("base64url");
-    return {
-        ...options, pushEndpoint: undefined,
-        pushConfig: { ...push, pushEndpoint: `http://127.0.0.1:${pushPort}/push/${config}` },
-    };
-}
-function withPushAuth(client, pushPort) {
-    return { ...client, createSubscription: (id, options) => client.createSubscription(id, authenticatedPush(options, pushPort)) };
-}
-/** 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 pushPort = port === 8086 ? 8087 : 8086;
-    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: ["sh", "-ec", `
-java_home=$(dirname "$(dirname "$(readlink -f "$(command -v java)")")")
-cp "$java_home/lib/security/cacerts" /tmp/spectest-pubsub-cacerts
-keytool -importcert -noprompt -alias spectest-environment -keystore /tmp/spectest-pubsub-cacerts -storepass changeit -file "$NODE_EXTRA_CA_CERTS"
-export JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=/tmp/spectest-pubsub-cacerts -Djavax.net.ssl.trustStorePassword=changeit \${JAVA_TOOL_OPTIONS:-}"
-python3 /opt/spectest-pubsub-push.py ${pushPort} &
-exec gcloud beta emulators pubsub start --project=${projectId} --host-port=0.0.0.0:${port} --quiet
-`],
-                files: [{ path: "/opt/spectest-pubsub-push.py", content: PUSH_ADAPTER }],
-                ports: [port],
-                ...(hostname ? { tls: [{ hostname, port, http2: true }] } : {}),
-                readyCheck: { type: "http", port, path: `/v1/projects/${projectId}/topics`, timeoutSecs: 60 },
-                setup: async ({ name }) => {
-                    const client = withPushAuth(pubsubClient(`http://${name}:${port}`, projectId), pushPort);
-                    for (const topic of topics)
-                        await client.createTopic(topic);
-                    for (const [id, options] of subscriptions)
-                        await client.createSubscription(id, options);
-                },
-            };
-            return { emulator };
-        },
-        helpers: (ctx) => ({
-            ...withPushAuth(pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId, async (input, init) => readRaw(await ctx.fetch(String(input), init))), pushPort),
-            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/src/components/gcp.ts

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

package/src/components/pubsub-push.py

@@ -1,83 +0,0 @@
-"""Authenticated push adapter; the emulator still owns scheduling and retries.
-
-Runs only on loopback in the emulator container. Tokens come from the local
-Google IAM fake, so recipients verify them with the same Google JWKS as usual.
-Never follows redirects or acknowledges a failed token request/delivery.
-"""
-import base64
-import json
-import os
-import ssl
-import sys
-import urllib.error
-import urllib.parse
-import urllib.request
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-
-
-class NoRedirect(urllib.request.HTTPRedirectHandler):
-    def redirect_request(self, req, fp, code, msg, headers, newurl):
-        return None
-
-
-def opener():
-    context = ssl.create_default_context(cafile=os.environ.get("SSL_CERT_FILE"))
-    return urllib.request.build_opener(NoRedirect(), urllib.request.HTTPSHandler(context=context))
-
-
-class Handler(BaseHTTPRequestHandler):
-    def do_POST(self):
-        phase = "configuration"
-        try:
-            if not self.path.startswith('/push/'):
-                self.send_error(404)
-                return
-            encoded = self.path[len('/push/'):]
-            config = json.loads(base64.urlsafe_b64decode(encoded + '=' * (-len(encoded) % 4)))
-            endpoint = config['endpoint']
-            if urllib.parse.urlsplit(endpoint).scheme not in ('http', 'https'):
-                raise ValueError('Invalid push endpoint')
-            size = int(self.headers.get('Content-Length', '0'))
-            if not 0 <= size <= 16 * 1024 * 1024:
-                self.send_error(413)
-                return
-            body = self.rfile.read(size)
-            account = urllib.parse.quote(config['serviceAccountEmail'], safe='')
-            token_url = 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/' + account + ':generateIdToken'
-            token_body = json.dumps({'audience': config.get('audience') or endpoint, 'includeEmail': True}).encode()
-            http = opener()
-            phase = "token issuance"
-            with http.open(urllib.request.Request(token_url, data=token_body, headers={'Content-Type': 'application/json'}), timeout=10) as response:
-                token = json.load(response)['token']
-            if not isinstance(token, str) or not token or '\r' in token or '\n' in token:
-                raise ValueError('Invalid ID token from Google IAM fake')
-            request = urllib.request.Request(endpoint, data=body, headers={
-                'Content-Type': self.headers.get('Content-Type', 'application/json'),
-                'Authorization': 'Bearer ' + token,
-            })
-            phase = "delivery"
-            with http.open(request, timeout=30) as response:
-                status = response.status
-            self.send_response(status)
-            self.end_headers()
-        except urllib.error.HTTPError as error:
-            # An unsuccessful token request or destination response must retry.
-            print(f"pubsub push {phase} returned HTTP {error.code}", flush=True)
-            self.send_response(error.code if error.code >= 300 else 502)
-            self.end_headers()
-            error.close()
-        except Exception as error:
-            # Do not log tokens, request bodies, or the encoded config URL.
-            print('pubsub push adapter failed: ' + type(error).__name__, flush=True)
-            self.send_response(502)
-            self.end_headers()
-
-    def log_message(self, format, *args):
-        pass
-
-
-if __name__ == '__main__':
-    server = ThreadingHTTPServer(('127.0.0.1', int(sys.argv[1])), Handler)
-    server.daemon_threads = True
-    print('pubsub authenticated push adapter ready', flush=True)
-    server.serve_forever()

package/src/components/pubsub.test.ts

@@ -1,103 +0,0 @@
-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?.join("\n")).toContain("--host-port=0.0.0.0:9095");
-    expect(service.args?.join("\n")).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();
-  });
-});
-
-
-test("subscription push authentication and delivery policies are passed through", async () => {
-  let body: any;
-  const client = pubsubClient("http://emulator:8085", "spectest", async (_, init) => {
-    body = JSON.parse(init!.body as string); return Response.json({});
-  });
-  const pushConfig = { pushEndpoint: "https://worker.run.app/push", oidcToken: { serviceAccountEmail: "push@spectest.iam.gserviceaccount.com", audience: "https://worker.run.app" }, attributes: { "x-goog-version": "v1" } };
-  const deadLetterPolicy = { deadLetterTopic: "projects/spectest/topics/dead-letters", maxDeliveryAttempts: 5 };
-  const retryPolicy = { minimumBackoff: "1s", maximumBackoff: "60s" };
-  await client.createSubscription("worker", { topic: "orders", pushConfig, deadLetterPolicy, retryPolicy });
-  expect(body).toEqual({ topic: "projects/spectest/topics/orders", ackDeadlineSeconds: 10, pushConfig, deadLetterPolicy, retryPolicy });
-  expect(() => client.createSubscription("worker", { topic: "orders", pushEndpoint: "https://other.run.app", pushConfig })).toThrow("disagree");
-  expect(() => client.createSubscription("worker", { topic: "orders", pushConfig: { ...pushConfig, oidcToken: { serviceAccountEmail: "invalid" } } })).toThrow("oidcToken");
-});

package/src/components/pubsub.ts

@@ -1,241 +0,0 @@
-import { readFileSync } from "node:fs";
-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";
-
-const PUSH_ADAPTER = readFileSync(new URL("./pubsub-push.py", import.meta.url), "utf8");
-
-export interface PubSubOidcToken {
-  serviceAccountEmail: string;
-  /** Defaults to the original push endpoint URL. */
-  audience?: string;
-}
-export interface PubSubPushConfig {
-  pushEndpoint: string;
-  oidcToken?: PubSubOidcToken;
-  attributes?: Record<string, string>;
-}
-export interface PubSubDeadLetterPolicy {
-  /** Fully qualified projects/{project}/topics/{topic} name. Create this topic separately. */
-  deadLetterTopic: string;
-  maxDeliveryAttempts?: number;
-}
-export interface PubSubRetryPolicy {
-  /** Google duration strings, for example "1s" and "60s". */
-  minimumBackoff?: string;
-  maximumBackoff?: string;
-}
-export interface PubSubSubscriptionOptions {
-  /** Topic ID in this component's project. */
-  topic: string;
-  ackDeadlineSeconds?: number;
-  /** Shorthand for pushConfig.pushEndpoint. HTTP and HTTPS are supported. */
-  pushEndpoint?: string;
-  pushConfig?: PubSubPushConfig;
-  deadLetterPolicy?: PubSubDeadLetterPolicy;
-  retryPolicy?: PubSubRetryPolicy;
-}
-
-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 && options.pushConfig && options.pushEndpoint !== options.pushConfig.pushEndpoint) throw new Error("pubsub(): pushEndpoint and pushConfig.pushEndpoint disagree");
-  const push = options.pushConfig ?? (options.pushEndpoint ? { pushEndpoint: options.pushEndpoint } : undefined);
-  if (push) {
-    if (!push.pushEndpoint || !/^https?:$/.test(new URL(push.pushEndpoint).protocol)) throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
-    if (push.oidcToken && (!/^[^@\s]+@[^@\s]+$/.test(push.oidcToken.serviceAccountEmail) || (push.oidcToken.audience !== undefined && !push.oidcToken.audience))) throw new Error("pubsub(): oidcToken requires a serviceAccountEmail and nonempty audience");
-  }
-  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.pushConfig ? { pushConfig: options.pushConfig } : options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
-        ...(options.deadLetterPolicy ? { deadLetterPolicy: options.deadLetterPolicy } : {}),
-        ...(options.retryPolicy ? { retryPolicy: options.retryPolicy } : {}),
-      });
-    },
-    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;
-}
-
-// The official emulator ignores OIDC. Keep its push/retry/dead-letter engine,
-// but route authenticated deliveries through a local adapter in its container.
-function authenticatedPush(options: PubSubSubscriptionOptions, pushPort: number): PubSubSubscriptionOptions {
-  subscriptionOptions(options);
-  const push = options.pushConfig;
-  if (!push?.oidcToken) return options;
-  const config = Buffer.from(JSON.stringify({ endpoint: push.pushEndpoint, ...push.oidcToken })).toString("base64url");
-  return {
-    ...options, pushEndpoint: undefined,
-    pushConfig: { ...push, pushEndpoint: `http://127.0.0.1:${pushPort}/push/${config}` },
-  };
-}
-
-function withPushAuth(client: PubSubClient, pushPort: number): PubSubClient {
-  return { ...client, createSubscription: (id, options) => client.createSubscription(id, authenticatedPush(options, pushPort)) };
-}
-
-/** 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 pushPort = port === 8086 ? 8087 : 8086;
-  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: ["sh", "-ec", `
-java_home=$(dirname "$(dirname "$(readlink -f "$(command -v java)")")")
-cp "$java_home/lib/security/cacerts" /tmp/spectest-pubsub-cacerts
-keytool -importcert -noprompt -alias spectest-environment -keystore /tmp/spectest-pubsub-cacerts -storepass changeit -file "$NODE_EXTRA_CA_CERTS"
-export JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=/tmp/spectest-pubsub-cacerts -Djavax.net.ssl.trustStorePassword=changeit \${JAVA_TOOL_OPTIONS:-}"
-python3 /opt/spectest-pubsub-push.py ${pushPort} &
-exec gcloud beta emulators pubsub start --project=${projectId} --host-port=0.0.0.0:${port} --quiet
-`],
-        files: [{ path: "/opt/spectest-pubsub-push.py", content: PUSH_ADAPTER }],
-        ports: [port],
-        ...(hostname ? { tls: [{ hostname, port, http2: true }] } : {}),
-        readyCheck: { type: "http", port, path: `/v1/projects/${projectId}/topics`, timeoutSecs: 60 },
-        setup: async ({ name }) => {
-          const client = withPushAuth(pubsubClient(`http://${name}:${port}`, projectId), pushPort);
-          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 => ({
-      ...withPushAuth(pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId,
-        async (input, init) => readRaw(await ctx.fetch(String(input), init)) as unknown as Response), pushPort),
-      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);
-    },
-  });
-}