@strav/testing 1.0.0-alpha.24 → 1.0.0-alpha.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/testing",
-  "version": "1.0.0-alpha.24",
+  "version": "1.0.0-alpha.27",
   "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",
@@ -8,7 +8,9 @@
   "exports": {
     ".": "./src/index.ts",
     "./brain": "./src/brain/index.ts",
-    "./postgres": "./src/postgres/index.ts"
+    "./cache": "./src/cache/index.ts",
+    "./postgres": "./src/postgres/index.ts",
+    "./storage": "./src/storage/index.ts"
   },
   "files": [
     "src",
@@ -21,11 +23,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.24",
-    "@strav/kernel": "1.0.0-alpha.24"
+    "@strav/database": "1.0.0-alpha.27",
+    "@strav/kernel": "1.0.0-alpha.27"
   },
   "peerDependencies": {
-    "@strav/brain": "1.0.0-alpha.24",
+    "@strav/brain": "1.0.0-alpha.27",
     "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {

package/src/cache/index.ts

@@ -0,0 +1,2 @@
+export { isMemcachedAvailable } from './is_memcached_available.ts'
+export { isRedisAvailable } from './is_redis_available.ts'

package/src/cache/is_memcached_available.ts

@@ -0,0 +1,75 @@
+/**
+ * Cheap connection probe over Bun's TCP socket — opens a connection,
+ * sends `version\r\n`, expects a `VERSION ...\r\n` reply. Cached for
+ * the lifetime of the test process.
+ *
+ * Returns `false` if `MEMCACHED_HOST` / `MEMCACHED_PORT` are missing
+ * OR the probe fails. Pair with
+ * `describe.skipIf(!await isMemcachedAvailable())`.
+ */
+
+let cachedAvailability: boolean | null = null
+
+export async function isMemcachedAvailable(): Promise<boolean> {
+  if (cachedAvailability !== null) return cachedAvailability
+  const host = process.env['MEMCACHED_HOST']
+  const portStr = process.env['MEMCACHED_PORT']
+  if (host === undefined || host === '' || portStr === undefined || portStr === '') {
+    cachedAvailability = false
+    return false
+  }
+  const port = Number(portStr)
+  if (!Number.isFinite(port) || port <= 0) {
+    cachedAvailability = false
+    return false
+  }
+  try {
+    cachedAvailability = await probe(host, port)
+  } catch {
+    cachedAvailability = false
+  }
+  return cachedAvailability
+}
+
+function probe(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (ok: boolean): void => {
+      if (settled) return
+      settled = true
+      resolve(ok)
+    }
+    const timeout = setTimeout(() => finish(false), 2_000)
+    void Bun.connect({
+      hostname: host,
+      port,
+      socket: {
+        open(socket) {
+          socket.write('version\r\n')
+        },
+        data(socket, chunk) {
+          const bytes = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+          const text = new TextDecoder().decode(bytes)
+          const ok = text.startsWith('VERSION')
+          // Settle before closing — `socket.end()` synchronously fires
+          // the `close` callback, which would beat `finish(ok)` to the
+          // settle line and report a false negative.
+          clearTimeout(timeout)
+          finish(ok)
+          socket.end()
+        },
+        error(_socket, _error) {
+          clearTimeout(timeout)
+          finish(false)
+        },
+        close() {
+          clearTimeout(timeout)
+          if (!settled) finish(false)
+        },
+      },
+    }).catch(() => {
+      clearTimeout(timeout)
+      finish(false)
+    })
+  })
+}

package/src/cache/is_redis_available.ts

@@ -0,0 +1,39 @@
+/**
+ * Cheap connection probe — opens `Bun.RedisClient` against
+ * `REDIS_URL`, sends `PING`, reports. Cached for the lifetime of the
+ * test process.
+ *
+ * Returns `false` if `REDIS_URL` is missing OR the connection / PING
+ * fails. Pair with `describe.skipIf(!await isRedisAvailable())`.
+ */
+
+import { RedisClient } from 'bun'
+
+let cachedAvailability: boolean | null = null
+
+export async function isRedisAvailable(): Promise<boolean> {
+  if (cachedAvailability !== null) return cachedAvailability
+  const url = process.env['REDIS_URL']
+  if (url === undefined || url === '') {
+    cachedAvailability = false
+    return false
+  }
+  let client: RedisClient | undefined
+  try {
+    client = new RedisClient(url)
+    // `send('PING', [])` is supported on every Bun.RedisClient build —
+    // safer than `ping()` which isn't on the typed surface.
+    const reply = await client.send('PING', [])
+    cachedAvailability = reply === 'PONG' || reply === 'OK' || typeof reply === 'string'
+    return cachedAvailability
+  } catch {
+    cachedAvailability = false
+    return false
+  } finally {
+    try {
+      client?.close()
+    } catch {
+      // Already closed / never connected — nothing to clean.
+    }
+  }
+}

package/src/index.ts

@@ -27,3 +27,15 @@ export {
   resetSchema,
   testDatabaseUrl,
 } from './postgres/index.ts'
+
+// 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
+  }
+}