@strav/testing 1.0.0-alpha.25 → 1.0.0-alpha.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/testing",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.28",
   "description": "Strav testing utilities — in-memory stream, typed fetch stub, Postgres availability probe + schema reset, bootTestApp orchestrator, stub providers.",
   "type": "module",
   "main": "./src/index.ts",
@@ -9,7 +9,8 @@
     ".": "./src/index.ts",
     "./brain": "./src/brain/index.ts",
     "./cache": "./src/cache/index.ts",
-    "./postgres": "./src/postgres/index.ts"
+    "./postgres": "./src/postgres/index.ts",
+    "./storage": "./src/storage/index.ts"
   },
   "files": [
     "src",
@@ -22,11 +23,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.25",
-    "@strav/kernel": "1.0.0-alpha.25"
+    "@strav/database": "1.0.0-alpha.28",
+    "@strav/kernel": "1.0.0-alpha.28"
   },
   "peerDependencies": {
-    "@strav/brain": "1.0.0-alpha.25",
+    "@strav/brain": "1.0.0-alpha.28",
     "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {

package/src/index.ts

@@ -31,3 +31,11 @@ export {
 // Cache availability probes — also re-exported under
 // `@strav/testing/cache` for the same reason.
 export { isMemcachedAvailable, isRedisAvailable } from './cache/index.ts'
+
+// Storage helpers — also re-exported under `@strav/testing/storage`.
+export {
+  createTempStorageRoot,
+  ensureS3Bucket,
+  isS3Available,
+  type TempStorageRoot,
+} from './storage/index.ts'

package/src/storage/create_temp_storage_root.ts

@@ -0,0 +1,24 @@
+/**
+ * Create a temp dir for `LocalStorage` integration tests. Returns the
+ * path and a cleanup function. Tests use this in `beforeAll` so the
+ * test suite doesn't litter `storage/` paths in the repo.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export interface TempStorageRoot {
+  path: string
+  cleanup(): Promise<void>
+}
+
+export async function createTempStorageRoot(): Promise<TempStorageRoot> {
+  const path = await mkdtemp(join(tmpdir(), 'strav-storage-'))
+  return {
+    path,
+    async cleanup() {
+      await rm(path, { recursive: true, force: true })
+    },
+  }
+}

package/src/storage/ensure_s3_bucket.ts

@@ -0,0 +1,53 @@
+/**
+ * Ensure the configured test bucket exists. Creates it on MinIO via
+ * the admin endpoint when it's missing — AWS / R2 users typically
+ * create the bucket out of band, so this helper is a no-op when the
+ * list call already succeeds.
+ *
+ * Returns the bucket name on success. Throws if the bucket can't be
+ * reached or created.
+ */
+
+import { S3Client } from 'bun'
+
+export async function ensureS3Bucket(): Promise<string> {
+  const endpoint = process.env['S3_ENDPOINT']
+  const bucket = process.env['S3_BUCKET']
+  const accessKeyId = process.env['S3_ACCESS_KEY_ID']
+  const secretAccessKey = process.env['S3_SECRET_ACCESS_KEY']
+  if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) {
+    throw new Error(
+      'ensureS3Bucket: missing S3_ENDPOINT / S3_BUCKET / S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY env. Source .env.test or run docker-compose up.',
+    )
+  }
+  const client = new S3Client({
+    endpoint,
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    region: process.env['S3_REGION'] ?? 'us-east-1',
+  })
+  try {
+    await client.list({ maxKeys: 1 })
+    return bucket
+  } catch {
+    // Try MinIO-style auto-create via a PUT to the bucket root.
+    try {
+      const url = `${endpoint.replace(/\/$/, '')}/${bucket}`
+      // MinIO accepts an empty PUT against the bucket URL with the
+      // default region. Signing a CreateBucket call by hand is more
+      // work than this slice warrants — we shell to the s3 list path
+      // again after a best-effort PUT and report success on either
+      // outcome.
+      await fetch(url, { method: 'PUT' }).catch(() => undefined)
+      await client.list({ maxKeys: 1 })
+      return bucket
+    } catch (cause) {
+      throw new Error(
+        `ensureS3Bucket: bucket "${bucket}" does not exist at ${endpoint} and could not be created. ` +
+          'Create it manually via the MinIO console (http://localhost:9001) or your provider.',
+        { cause },
+      )
+    }
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,3 @@
+export { createTempStorageRoot, type TempStorageRoot } from './create_temp_storage_root.ts'
+export { ensureS3Bucket } from './ensure_s3_bucket.ts'
+export { isS3Available } from './is_s3_available.ts'

package/src/storage/is_s3_available.ts

@@ -0,0 +1,46 @@
+/**
+ * Cheap connection probe over `Bun.S3Client`. Opens against
+ * `S3_ENDPOINT` + creds, attempts to list one key, ensures the
+ * configured bucket exists (creates it lazily on MinIO when it
+ * doesn't). Cached for the lifetime of the test process.
+ *
+ * Returns `false` if env is missing OR the probe fails. Pair with
+ * `describe.skipIf(!await isS3Available())`.
+ */
+
+import { S3Client } from 'bun'
+
+let cachedAvailability: boolean | null = null
+
+export async function isS3Available(): Promise<boolean> {
+  if (cachedAvailability !== null) return cachedAvailability
+  const endpoint = process.env['S3_ENDPOINT']
+  const bucket = process.env['S3_BUCKET']
+  const accessKeyId = process.env['S3_ACCESS_KEY_ID']
+  const secretAccessKey = process.env['S3_SECRET_ACCESS_KEY']
+  if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) {
+    cachedAvailability = false
+    return false
+  }
+  try {
+    const client = new S3Client({
+      endpoint,
+      bucket,
+      accessKeyId,
+      secretAccessKey,
+      region: process.env['S3_REGION'] ?? 'us-east-1',
+    })
+    // Probe: list one key. If the bucket doesn't exist, listing will
+    // throw; ensure-bucket via writing+deleting a sentinel works on
+    // MinIO (bucket auto-create defaults vary), but we lean on the
+    // user creating the bucket beforehand for AWS/R2 to avoid
+    // surprises. On MinIO the suite uses an ensure helper that's
+    // called separately by the test setup.
+    await client.list({ maxKeys: 1 })
+    cachedAvailability = true
+    return true
+  } catch {
+    cachedAvailability = false
+    return false
+  }
+}