@specific.dev/spectest 0.96.0 → 0.98.0

package/README.md

@@ -15,33 +15,10 @@ 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.
+Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
+`pubsub`/`pubsubClient` exports and `/components/gcp` entry point are removed.
+Use a local service definition or `serviceGroup()` wrapper; the repository’s
+`examples/google-pubsub` demonstrates this using public SDK APIs.
 
 ## HTTP assertions
 
@@ -150,4 +127,4 @@ 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.
+`ctx.intercept` and HTTP request recording.

package/dist/components/aws.js

@@ -94,13 +94,23 @@ const AWS_REGIONS = [
 const AWS_CN_REGIONS = ["cn-north-1", "cn-northwest-1"];
 /** Every hostname pattern the emulator answers to: the two partitions' global
  *  endpoints (`sts.amazonaws.com`, `iam.amazonaws.com`) plus one per region
- *  for the regional ones (`states.us-east-1.amazonaws.com`). */
+ *  for the regional ones (`states.us-east-1.amazonaws.com`). ECR adds
+ *  labels for its API and account registries, each needing its own SAN. */
 const AWS_HOST_PATTERNS = [
     "*.amazonaws.com",
-    ...AWS_REGIONS.map((r) => `*.${r}.amazonaws.com`),
+    ...AWS_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com")),
     "*.amazonaws.com.cn",
-    ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
+    ...AWS_CN_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com.cn")),
 ];
+function regionalHostPatterns(region, suffix) {
+    return [
+        `*.${region}.${suffix}`,
+        `*.ecr.${region}.${suffix}`,
+        `*.dkr.ecr.${region}.${suffix}`,
+        `*.ecr-fips.${region}.${suffix}`,
+        `*.dkr.ecr-fips.${region}.${suffix}`,
+    ];
+}
 /** The VM's own docker socket, bind-mounted so the emulator can start the
  *  official AWS runtime containers. This is the VM's dockerd, inside the
  *  hermetic environment — the same daemon that runs the services. */

package/dist/components/emulate/entry.mjs

@@ -30,7 +30,7 @@
 // the whole OAuth exchange is readable on the case page with no helper API.
 
 import { createServer } from "@emulators/core";
-import { SignJWT, decodeJwt, exportJWK } from "jose";
+import { SignJWT, decodeJwt, exportJWK, exportPKCS8 } from "jose";
 
 const CONFIG = JSON.parse(process.env.SPECTEST_AUTH_CONFIG ?? "{}");
 const PORT = Number(CONFIG.port ?? 4000);
@@ -60,6 +60,37 @@ const JWKS = {
   keys: [{ ...(await exportJWK(KEY_PAIR.publicKey)), kid: KID, use: "sig", alg: "RS256" }],
 };
 
+// Google's Node/Python clients fetch PEM certificates from /oauth2/v1/certs,
+// while browser clients use the JWK endpoint. Both must identify the same key.
+let GOOGLE_CERT;
+if ((CONFIG.providers ?? []).some(provider => provider.name === "google")) {
+  const child = Bun.spawn(["openssl", "req", "-new", "-x509", "-key", "/dev/stdin", "-days", "3650", "-subj", "/CN=spectest-google-token-signing"], {
+    stdin: new Blob([await exportPKCS8(KEY_PAIR.privateKey)]), stdout: "pipe", stderr: "pipe",
+  });
+  const [cert, error, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code !== 0) throw new Error(`google(): signing certificate setup failed: ${error}`);
+  GOOGLE_CERT = cert;
+}
+
+async function googleIdToken(req, path) {
+  const match = /^\/v1\/projects\/-\/serviceAccounts\/([^/]+):generateIdToken$/.exec(path);
+  if (!match || req.method !== "POST") return json({ error: "Unsupported IAM operation" }, 404);
+  let options, email;
+  try {
+    options = await req.json();
+    email = decodeURIComponent(match[1]);
+  } catch { return json({ error: "Invalid token request" }, 400); }
+  if (!options || !/^[^@\s]+@[^@\s]+$/.test(email) || typeof options.audience !== "string" || !options.audience) return json({ error: "serviceAccountEmail and audience are required" }, 400);
+  // Stable service-account subject; isolated test identities require no cloud credentials.
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(email)));
+  const subject = BigInt('0x' + Buffer.from(digest.slice(0, 8)).toString('hex')).toString();
+  const token = await new SignJWT(options.includeEmail ? { email, email_verified: true } : {})
+    .setProtectedHeader({ alg: "RS256", kid: KID, typ: "JWT" })
+    .setIssuer("https://accounts.google.com").setSubject(subject).setAudience(options.audience)
+    .setIssuedAt().setExpirationTime("1h").sign(KEY_PAIR.privateKey);
+  return json({ token }, 200);
+}
+
 // ──────────────────────────────────────────────────────────────────────────
 // Providers
 // ──────────────────────────────────────────────────────────────────────────
@@ -205,7 +236,11 @@ Bun.serve({
     }
 
     let res;
-    if (provider.oidc && provider.jwksPath?.test(path)) {
+    if (provider.name === "google" && host === "iamcredentials.googleapis.com") {
+      res = await googleIdToken(req, path);
+    } else if (provider.name === "google" && path === "/oauth2/v1/certs") {
+      res = json({ [KID]: GOOGLE_CERT }, 200);
+    } else if (provider.oidc && provider.jwksPath?.test(path)) {
       // Our key, never the emulator's — we re-sign every id_token.
       res = json(JWKS, 200);
     } else {

package/dist/components/emulate/service.js

@@ -80,6 +80,7 @@ const ENTRY_SCRIPT = (() => {
 const DOCKERFILE = `
 FROM ${IMAGE_BASE}
 WORKDIR /srv
+RUN apk add --no-cache openssl
 RUN echo '{"name":"spectest-provider","private":true}' > package.json \\
  && bun add \\
       @emulators/core@${EMULATE_VERSION} \\

package/dist/components/google.js

@@ -1,7 +1,8 @@
 // `google()` — Google, emulated inside the environment, answering at its
 // real endpoints.
 //
-// Today that is Sign in with Google: OpenID Connect discovery, the account
+// Supports service-account ID tokens (IAM generateIdToken) and Sign in
+// with Google: OpenID Connect discovery, the account
 // picker, PKCE, the token exchange, refresh, and userinfo. The component is
 // named for the provider rather than for the feature, because the backing
 // emulator also carries Gmail, Calendar and Drive — claiming
@@ -16,6 +17,7 @@ function spec(users, opts) {
         baseUrl: "https://accounts.google.com",
         hosts: [
             "accounts.google.com",
+            "iamcredentials.googleapis.com",
             "oauth2.googleapis.com",
             "www.googleapis.com",
             "openidconnect.googleapis.com",

package/dist/components/index.d.ts

@@ -1,4 +1,3 @@
-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,5 +1,4 @@
 // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.96.0",
+  "version": "0.98.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,11 +16,6 @@
       "bun": "./src/components/index.ts",
       "default": "./dist/components/index.js"
     },
-    "./components/gcp": {
-      "types": "./dist/components/gcp.d.ts",
-      "bun": "./src/components/gcp.ts",
-      "default": "./dist/components/gcp.js"
-    },
     "./coverage": {
       "types": "./dist/coverage.d.ts",
       "bun": "./src/coverage.ts",

package/src/components/aws.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "bun:test";
+import { X509Certificate } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defineEnvironment } from "../index.js";
+import { lowerIngress } from "../ingress.js";
+import { generateHostCert } from "../harness/certificate.js";
+import { aws } from "./aws.js";
+
+test("AWS certificate verifies nested ECR endpoints in every partition", async () => {
+  const env = defineEnvironment({ name: "test", services: { cloud: aws() } });
+  const ingress = lowerIngress(env.project([]));
+  expect(ingress.certificates).toHaveLength(1);
+  const names = ingress.certificates[0].hostnames;
+  const dir = await mkdtemp(join(tmpdir(), "spectest-aws-tls-"));
+  const ca = join(dir, "ca.crt");
+  const key = join(dir, "ca.key");
+  try {
+    const root = Bun.spawnSync(["openssl", "req", "-x509", "-newkey", "rsa:2048",
+      "-nodes", "-days", "1", "-subj", "/CN=test-ca", "-keyout", key, "-out", ca]);
+    expect(root.exitCode, root.stderr.toString()).toBe(0);
+    const { cert } = await generateHostCert("aws", names, ca, key);
+    const leaf = new X509Certificate(cert);
+    for (const host of [
+      "api.ecr.eu-central-1.amazonaws.com",
+      "123456789012.dkr.ecr.eu-central-1.amazonaws.com",
+      "api.ecr.us-gov-west-1.amazonaws.com",
+      "api.ecr-fips.us-gov-west-1.amazonaws.com",
+      "123456789012.dkr.ecr-fips.us-gov-west-1.amazonaws.com",
+      "api.ecr.cn-north-1.amazonaws.com.cn",
+      "123456789012.dkr.ecr.cn-northwest-1.amazonaws.com.cn",
+      "states.us-east-1.amazonaws.com",
+      "sts.amazonaws.com",
+    ]) {
+      const pattern = leaf.checkHost(host);
+      expect(pattern, host).toBeDefined();
+      expect(ingress.proxies).toContainEqual({ hostname: pattern, service: "cloud", port: 4566 });
+    }
+    expect(leaf.checkHost("api.ecr.eu-central-1.amazonaws.com.attacker.test")).toBeUndefined();
+    const file = join(dir, "leaf.crt");
+    await writeFile(file, cert);
+    const verified = Bun.spawnSync(["openssl", "verify", "-CAfile", ca,
+      "-verify_hostname", "api.ecr.eu-central-1.amazonaws.com", file]);
+    expect(verified.exitCode, verified.stderr.toString()).toBe(0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}, 10_000);

package/src/components/aws.ts

@@ -101,14 +101,25 @@ const AWS_CN_REGIONS = ["cn-north-1", "cn-northwest-1"];
 
 /** Every hostname pattern the emulator answers to: the two partitions' global
  *  endpoints (`sts.amazonaws.com`, `iam.amazonaws.com`) plus one per region
- *  for the regional ones (`states.us-east-1.amazonaws.com`). */
+ *  for the regional ones (`states.us-east-1.amazonaws.com`). ECR adds
+ *  labels for its API and account registries, each needing its own SAN. */
 const AWS_HOST_PATTERNS = [
   "*.amazonaws.com",
-  ...AWS_REGIONS.map((r) => `*.${r}.amazonaws.com`),
+  ...AWS_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com")),
   "*.amazonaws.com.cn",
-  ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
+  ...AWS_CN_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com.cn")),
 ];
 
+function regionalHostPatterns(region: string, suffix: string): string[] {
+  return [
+    `*.${region}.${suffix}`,
+    `*.ecr.${region}.${suffix}`,
+    `*.dkr.ecr.${region}.${suffix}`,
+    `*.ecr-fips.${region}.${suffix}`,
+    `*.dkr.ecr-fips.${region}.${suffix}`,
+  ];
+}
+
 /** The VM's own docker socket, bind-mounted so the emulator can start the
  *  official AWS runtime containers. This is the VM's dockerd, inside the
  *  hermetic environment — the same daemon that runs the services. */

package/src/components/emulate/entry.mjs

@@ -30,7 +30,7 @@
 // the whole OAuth exchange is readable on the case page with no helper API.
 
 import { createServer } from "@emulators/core";
-import { SignJWT, decodeJwt, exportJWK } from "jose";
+import { SignJWT, decodeJwt, exportJWK, exportPKCS8 } from "jose";
 
 const CONFIG = JSON.parse(process.env.SPECTEST_AUTH_CONFIG ?? "{}");
 const PORT = Number(CONFIG.port ?? 4000);
@@ -60,6 +60,37 @@ const JWKS = {
   keys: [{ ...(await exportJWK(KEY_PAIR.publicKey)), kid: KID, use: "sig", alg: "RS256" }],
 };
 
+// Google's Node/Python clients fetch PEM certificates from /oauth2/v1/certs,
+// while browser clients use the JWK endpoint. Both must identify the same key.
+let GOOGLE_CERT;
+if ((CONFIG.providers ?? []).some(provider => provider.name === "google")) {
+  const child = Bun.spawn(["openssl", "req", "-new", "-x509", "-key", "/dev/stdin", "-days", "3650", "-subj", "/CN=spectest-google-token-signing"], {
+    stdin: new Blob([await exportPKCS8(KEY_PAIR.privateKey)]), stdout: "pipe", stderr: "pipe",
+  });
+  const [cert, error, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code !== 0) throw new Error(`google(): signing certificate setup failed: ${error}`);
+  GOOGLE_CERT = cert;
+}
+
+async function googleIdToken(req, path) {
+  const match = /^\/v1\/projects\/-\/serviceAccounts\/([^/]+):generateIdToken$/.exec(path);
+  if (!match || req.method !== "POST") return json({ error: "Unsupported IAM operation" }, 404);
+  let options, email;
+  try {
+    options = await req.json();
+    email = decodeURIComponent(match[1]);
+  } catch { return json({ error: "Invalid token request" }, 400); }
+  if (!options || !/^[^@\s]+@[^@\s]+$/.test(email) || typeof options.audience !== "string" || !options.audience) return json({ error: "serviceAccountEmail and audience are required" }, 400);
+  // Stable service-account subject; isolated test identities require no cloud credentials.
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(email)));
+  const subject = BigInt('0x' + Buffer.from(digest.slice(0, 8)).toString('hex')).toString();
+  const token = await new SignJWT(options.includeEmail ? { email, email_verified: true } : {})
+    .setProtectedHeader({ alg: "RS256", kid: KID, typ: "JWT" })
+    .setIssuer("https://accounts.google.com").setSubject(subject).setAudience(options.audience)
+    .setIssuedAt().setExpirationTime("1h").sign(KEY_PAIR.privateKey);
+  return json({ token }, 200);
+}
+
 // ──────────────────────────────────────────────────────────────────────────
 // Providers
 // ──────────────────────────────────────────────────────────────────────────
@@ -205,7 +236,11 @@ Bun.serve({
     }
 
     let res;
-    if (provider.oidc && provider.jwksPath?.test(path)) {
+    if (provider.name === "google" && host === "iamcredentials.googleapis.com") {
+      res = await googleIdToken(req, path);
+    } else if (provider.name === "google" && path === "/oauth2/v1/certs") {
+      res = json({ [KID]: GOOGLE_CERT }, 200);
+    } else if (provider.oidc && provider.jwksPath?.test(path)) {
       // Our key, never the emulator's — we re-sign every id_token.
       res = json(JWKS, 200);
     } else {

package/src/components/emulate/service.ts

@@ -155,6 +155,7 @@ const ENTRY_SCRIPT: string = (() => {
 const DOCKERFILE = `
 FROM ${IMAGE_BASE}
 WORKDIR /srv
+RUN apk add --no-cache openssl
 RUN echo '{"name":"spectest-provider","private":true}' > package.json \\
  && bun add \\
       @emulators/core@${EMULATE_VERSION} \\

package/src/components/google.ts

@@ -1,7 +1,8 @@
 // `google()` — Google, emulated inside the environment, answering at its
 // real endpoints.
 //
-// Today that is Sign in with Google: OpenID Connect discovery, the account
+// Supports service-account ID tokens (IAM generateIdToken) and Sign in
+// with Google: OpenID Connect discovery, the account
 // picker, PKCE, the token exchange, refresh, and userinfo. The component is
 // named for the provider rather than for the feature, because the backing
 // emulator also carries Gmail, Calendar and Drive — claiming
@@ -27,6 +28,7 @@ function spec(users: ProviderUser[], opts: GoogleOptions): ProviderSpec {
     baseUrl: "https://accounts.google.com",
     hosts: [
       "accounts.google.com",
+      "iamcredentials.googleapis.com",
       "oauth2.googleapis.com",
       "www.googleapis.com",
       "openidconnect.googleapis.com",

package/src/components/index.ts

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

package/dist/components/gcp.d.ts

@@ -1,2 +0,0 @@
-/** 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

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

package/dist/components/pubsub.d.ts

@@ -1,77 +0,0 @@
-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

@@ -1,139 +0,0 @@
-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/src/components/gcp.ts

@@ -1,11 +0,0 @@
-/** 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/src/components/pubsub.test.ts

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

package/src/components/pubsub.ts

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