@specific.dev/spectest 0.38.0 → 0.41.0

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>;
+}