@specific.dev/spectest 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/index.ts

@@ -11,6 +11,11 @@ export {
   type PostgresOptions,
   type PostgresHelpers,
 } from "./postgres.js";
+export {
+  s3,
+  type S3Options,
+  type S3Helpers,
+} from "./s3.js";
 // `SQL` / `SqlClient` now live in the core SDK (`@specific.dev/spectest`),
 // next to `expect` and `fetch` — re-exported here so existing
 // `from ".../components"` imports keep resolving.

package/src/components/s3.ts

@@ -0,0 +1,132 @@
+import type { ServiceDefinition } from "../index.js";
+import { S3Client, type S3ClientLike } from "../s3.js";
+
+export interface S3Options {
+  /** HTTP port the S3 API is served on. Default `9090`. */
+  port?: number;
+  /**
+   * Buckets to create on first boot. The backing server's own `initialBuckets`
+   * env is unreliable across versions, so the component creates them in `setup`
+   * (a plain CreateBucket `PUT`) — captured into the warm snapshot, never
+   * re-run on warm starts/forks.
+   */
+  buckets?: string[];
+  /**
+   * Default bucket the `helpers.client` targets (so `client.file("k")` resolves
+   * without a per-call `{ bucket }`). Defaults to the first entry of `buckets`.
+   */
+  bucket?: string;
+  /**
+   * Hostnames to additionally serve the store at over **HTTPS** (CA-trusted),
+   * via the daemon's TLS-terminating reverse proxy. Optional — defaults to none;
+   * the store is always reachable at `http://<key>:<port>` 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.
+   */
+  hosts?: string[];
+  /** Access key id the helper client signs with. The store ignores SigV4, so
+   *  any non-empty value works; default `"s3"`. */
+  accessKeyId?: string;
+  /** Secret key the helper client signs with (ignored by the store). Default
+   *  `"s3"`. */
+  secretAccessKey?: string;
+  /** Region for the helper client. Default `"us-east-1"`. */
+  region?: string;
+  /** Extra environment variables forwarded to the container. */
+  env?: Record<string, string>;
+}
+
+/** Helpers an `s3(...)` service exposes on `ctx.svc.<name>`. */
+export interface S3Helpers {
+  /** An instrumented {@link S3Client} pointed at this store (path-style) — each
+   *  object op lands on the test event log and its result comes back
+   *  provenance-wrapped, so `expect(...)` on a read links to the op. */
+  client: S3ClientLike;
+}
+
+// Backing image, pinned internally (not user-configurable). adobe/s3mock 5.1.0
+// is the current release; avoid exactly 5.0.0, which crashed at startup on
+// Java 25 (`NoClassDefFoundError: KotlinBuiltIns$2`) — fixed in 5.1.0.
+const S3_IMAGE = "adobe/s3mock:5.1.0";
+
+/**
+ * A ready-to-use, S3-compatible object store (backed by
+ * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
+ *
+ * ```ts
+ * import { s3 } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   storage: s3({ buckets: ["uploads"] }),
+ * },
+ * ```
+ *
+ * Tests get an instrumented S3 client at `ctx.svc.<key>.client`:
+ *
+ * ```ts
+ * await ctx.svc.storage.client.write("hello.txt", "hi there");
+ * const body = await ctx.svc.storage.client.file("hello.txt").text();
+ * expect(body).toBe("hi there");          // nests under the s3 read step
+ * ```
+ *
+ * The store skips SigV4 validation and is path-style only (what S3-compatible
+ * clients use), so it stands in for AWS S3, R2, Spaces, etc. without credential
+ * plumbing. If — and only if — the app under test hardcodes a specific prod S3
+ * endpoint, pass `hosts` to also serve the store there over a CA-trusted cert:
+ *
+ * ```ts
+ * // app hardcodes https://files.example.com — serve it there too:
+ * storage: s3({ hosts: ["files.example.com"] }),
+ * ```
+ */
+export function s3(opts: S3Options = {}) {
+  const port = opts.port ?? 9090;
+  const buckets = opts.buckets ?? [];
+  const defaultBucket = opts.bucket ?? buckets[0];
+  const accessKeyId = opts.accessKeyId ?? "s3";
+  const secretAccessKey = opts.secretAccessKey ?? "s3";
+  const region = opts.region ?? "us-east-1";
+
+  return {
+    image: { type: "registry", reference: S3_IMAGE },
+    ports: [port],
+    ...(opts.env ? { env: opts.env } : {}),
+    ...(opts.hosts
+      ? { tls: opts.hosts.map((hostname) => ({ hostname, port })) }
+      : {}),
+    // GET / returns the ListBuckets XML with 200 once the store is up.
+    readyCheck: { type: "http" as const, port, path: "/", timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }): S3Helpers => ({
+      client: new S3Client({
+        endpoint: `http://${name}:${port}`,
+        region,
+        accessKeyId,
+        secretAccessKey,
+        ...(defaultBucket ? { bucket: defaultBucket } : {}),
+        // Path-style (Bun's default) — the store is path-style only.
+      }),
+    }),
+    ...(buckets.length > 0
+      ? {
+          setup: async ({ name }: { name: string }) => {
+            for (const bucket of buckets) {
+              // CreateBucket is a plain `PUT` on the bucket root; the store
+              // returns 200 (or 409 if it already exists — idempotent enough to
+              // ignore).
+              const res = await fetch(`http://${name}:${port}/${bucket}`, {
+                method: "PUT",
+              });
+              if (!res.ok && res.status !== 409) {
+                throw new Error(
+                  `s3: failed to create bucket ${bucket}: ${res.status}`,
+                );
+              }
+            }
+          },
+        }
+      : {}),
+  } satisfies ServiceDefinition<S3Helpers>;
+}

package/src/index.ts

@@ -42,7 +42,7 @@ export { field } from "./inspect.js";
 // assertions stay tracked. See `sql.ts` / `redis.ts` / `s3.ts`.
 export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
-export { S3Client, type S3ClientLike, type S3File, type S3Options } from "./s3.js";
+export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 
 export type {
   Browser,

package/src/s3.ts

@@ -79,9 +79,9 @@ export interface S3ClientLike {
   [m: string]: (...args: any[]) => any;
 }
 
-/** Options accepted by the {@link S3Client} constructor — Bun's own plus a
- *  recording `label`. Passed through to `Bun.S3Client` verbatim. */
-export interface S3Options {
+/** Options accepted by the {@link S3Client} constructor — Bun's `S3Options`,
+ *  passed through to `Bun.S3Client` verbatim. */
+export interface S3ClientOptions {
   accessKeyId?: string;
   secretAccessKey?: string;
   sessionToken?: string;
@@ -92,12 +92,12 @@ export interface S3Options {
 }
 
 interface BunGlobal {
-  S3Client: new (options?: S3Options) => RawS3Client;
+  S3Client: new (options?: S3ClientOptions) => RawS3Client;
 }
 
 interface S3Constructor {
-  new (options?: S3Options): S3ClientLike;
-  (options?: S3Options): S3ClientLike;
+  new (options?: S3ClientOptions): S3ClientLike;
+  (options?: S3ClientOptions): S3ClientLike;
 }
 
 const MAX_PREVIEW = 512;
@@ -106,7 +106,7 @@ const MAX_PREVIEW = 512;
  * Open an instrumented S3 client. Usable with or without `new`. Requires the
  * Bun runtime — it runs inside the spectest daemon.
  */
-export const S3Client = function S3Client(options?: S3Options): S3ClientLike {
+export const S3Client = function S3Client(options?: S3ClientOptions): S3ClientLike {
   const bun = (globalThis as unknown as { Bun?: BunGlobal }).Bun;
   if (!bun?.S3Client) {
     throw new Error(