pipework 0.252.0 → 0.252.1

package/src/test/vitest.ts

@@ -0,0 +1,333 @@
+import { beforeAll, afterAll, beforeEach, afterEach } from 'vitest'
+import type { DB } from '../data/db/index.js'
+import type { Blueprint } from '../core/config/index.js'
+import type { Manifold } from '../core/pipework.js'
+import type { SurfaceContext, TestClient } from '../core/surface/types.js'
+import { createManifold } from '../core/pipework.js'
+import { SETUP_HOOK_TIMEOUT_MS } from './progress.js'
+import { setupTestDatabases, teardownTestDatabases, getTestDatabase } from './setup.js'
+import { settleTraceWritesBounded, TEARDOWN_HOOK_TIMEOUT_MS } from '../trace/runtime/pending-writes.js'
+import { beginTestIsolation, endTestIsolation, createTestContext, createSetupConnection, propagateTestSessionVars, runInContext, type TestContext } from './plugin.js'
+import { describeError } from '../core/logging/error-chain.js'
+
+export { type TestContext, type TestDatabaseConnections } from './plugin.js'
+
+let _testContext: TestContext | null = null
+let _instance: Manifold | null = null
+
+const _setupConnections = new Map<string, { drizzle: DB; close: () => Promise<void> }>()
+
+export function _setTestState(instance: Manifold, testContext?: TestContext | null): void {
+  _instance = instance
+  if (testContext !== undefined) {
+    _testContext = testContext
+  }
+}
+
+export function setupPipeworkTests(configOrInstance: Blueprint | Manifold): Manifold {
+  const instance = isInstance(configOrInstance) ? configOrInstance : createManifold(configOrInstance)
+  _instance = instance
+
+  beforeAll(async () => {
+    await setupTestDatabases(instance)
+  }, SETUP_HOOK_TIMEOUT_MS)
+
+  afterAll(async () => {
+    await teardownAfterAll(instance)
+  }, TEARDOWN_HOOK_TIMEOUT_MS)
+
+  beforeEach(async ({ task }) => {
+    _testContext = await beginTestIsolation(instance, task)
+  })
+
+  afterEach(async () => {
+    if (_testContext) {
+      await endTestIsolation(instance, _testContext)
+      _testContext = null
+    }
+  }, TEARDOWN_HOOK_TIMEOUT_MS)
+
+  return instance
+}
+
+export function useTestDb(name?: string): DB {
+  const resolvedName = name
+
+  function resolve(): DB {
+    if (!_testContext || !_instance) {
+      throw new Error(
+        '[pipework] No test context available.\n\n' +
+        '  useTestDb() only works inside test bodies (it, test) and beforeEach/afterEach.\n' +
+        '  For beforeAll/afterAll fixture setup, use useSetupDb() instead.\n'
+      )
+    }
+
+    const dbName = resolvedName ?? _instance.config.defaultDatabaseName()
+    const db = _testContext.db[dbName]
+    if (!db) {
+      const available = Object.keys(_testContext.db).join(', ')
+      throw new Error(
+        `[pipework] No test database "${dbName}". Available: ${available}`,
+      )
+    }
+    return db
+  }
+
+  return new Proxy({} as DB, {
+    get(_target, prop, receiver) {
+      const db = resolve()
+      const value: unknown = Reflect.get(db, prop, receiver)
+      return typeof value === 'function' ? (value as Function).bind(db) : value
+    },
+    has(_target, prop) {
+      return prop in resolve()
+    },
+  })
+}
+
+export function useSetupDb(name?: string): DB {
+  const resolvedName = name
+
+  function resolve(): DB {
+    if (!_instance) {
+      throw new Error(
+        '[pipework] No test instance available.\n\n' +
+        '  Add to your vitest.config.ts:\n' +
+        '    test: { setupFiles: [\'pipework/test/setup\'] }\n'
+      )
+    }
+
+    const dbName = resolvedName ?? _instance.config.defaultDatabaseName()
+
+    const existing = _setupConnections.get(dbName)
+    if (existing) return existing.drizzle
+
+    const testDb = getTestDatabase(dbName)
+    if (!testDb) {
+      throw new Error(
+        `[pipework] Test database "${dbName}" is not set up yet.\n\n` +
+        '  useSetupDb() requires setupTestDatabases() to have completed.\n' +
+        '  Make sure your beforeAll that seeds data runs after the pipework setup.\n'
+      )
+    }
+
+    const conn = createSetupConnection(testDb)
+    _setupConnections.set(dbName, conn)
+    return conn.drizzle
+  }
+
+  return new Proxy({} as DB, {
+    get(_target, prop, receiver) {
+      const db = resolve()
+      const value: unknown = Reflect.get(db, prop, receiver)
+      return typeof value === 'function' ? (value as Function).bind(db) : value
+    },
+    has(_target, prop) {
+      return prop in resolve()
+    },
+  })
+}
+
+/**
+ * Register a setup connection directly. Internal: the only caller outside this module
+ * is the test that proves a close failure is named rather than swallowed (#395), which
+ * needs a connection whose `close` rejects.
+ */
+export function _registerSetupConnection(database: string, conn: { drizzle: DB; close: () => Promise<void> }): void {
+  _setupConnections.set(database, conn)
+}
+
+/**
+ * Close every connection `useSetupDb()` has opened, and forget them.
+ *
+ * The harness closes these in `setupPipeworkTests`' own `afterAll`. Under
+ * vitest's `sequence.hooks: 'stack'` that hook runs *after* a consumer's
+ * setupFile `afterAll`, so a teardown-time observer — one sampling
+ * `pg_stat_activity` to name leaked backends, say — sees every setup
+ * connection still open and cannot tell them from a real leak. Call this
+ * first, then sample: what remains is a true survivor set.
+ *
+ * Idempotent, and safe to call before the harness's own teardown — that
+ * teardown still closes the pool and drops the databases afterwards. A later
+ * `useSetupDb()` opens a fresh connection.
+ */
+export async function closeSetupConnections(): Promise<void> {
+  const failures: Array<{ database: string; cause: unknown }> = []
+
+  for (const [database, conn] of _setupConnections) {
+    try {
+      await conn.close()
+    } catch (cause: unknown) {
+      failures.push({ database, cause })
+    }
+  }
+  // Cleared either way: a connection that would not close must not be handed to a
+  // later useSetupDb(). What must not happen is clearing it *quietly* — the backend
+  // stays held, and the only later evidence is a foreign pid in pg_stat_activity or
+  // a setup hook that times out, both of which read as a test or box fault (#395).
+  _setupConnections.clear()
+
+  if (failures.length > 0) throw new SetupConnectionCloseError(failures)
+}
+
+/**
+ * A setup connection refused to close.
+ *
+ * Names every database whose connection would not close and the underlying error,
+ * because the backend is still held: the alternative is a leak with no record, found
+ * later as an unexplained pid or a hook that never finishes.
+ */
+export class SetupConnectionCloseError extends Error {
+  readonly failures: ReadonlyArray<{ database: string; cause: unknown }>
+
+  constructor(failures: ReadonlyArray<{ database: string; cause: unknown }>) {
+    const named = failures.map(f => `    ${f.database}: ${messageOf(f.cause)}`).join('\n')
+    super(
+      `[pipework] ${String(failures.length)} setup connection${failures.length === 1 ? '' : 's'} would not close.\n\n` +
+      `${named}\n\n` +
+      '  Each backend above is still held by this test process. It is dropped from\n' +
+      '  pipework\'s registry regardless, so a later useSetupDb() opens a fresh one —\n' +
+      '  but the old backend holds its locks until the process exits.\n',
+    )
+    this.name = 'SetupConnectionCloseError'
+    this.failures = failures
+    if (failures.length === 1) this.cause = failures[0]!.cause
+  }
+}
+
+/**
+ * The harness's own `afterAll`: close setup connections, the pool, the databases.
+ *
+ * A setup connection that will not close must not cost the pool and the databases
+ * their teardown — that would trade one leak for many. Every step runs, and the close
+ * failure is raised at the end so the file fails by name (#395).
+ */
+export async function teardownAfterAll(instance: Manifold): Promise<void> {
+  await settleTraceWritesBounded()
+  let closeFailure: unknown
+  try {
+    await closeSetupConnections()
+  } catch (err: unknown) {
+    closeFailure = err
+  }
+
+  await instance.pool.closeAll()
+  await teardownTestDatabases()
+
+  if (closeFailure !== undefined) throw closeFailure
+}
+
+function messageOf(cause: unknown): string {
+  return describeError(cause).message
+}
+
+export function _isInTestIsolation(): boolean {
+  return _testContext !== null
+}
+
+/**
+ * The manifold the test harness set up: one connection per database with an
+ * open transaction, bound into the context for every database name. Nothing a
+ * handler writes under it is ever committed, so a test on this instance cannot
+ * observe commit boundaries in either direction — transaction-per-request on or
+ * off reads the same. A request, a job, `pipe.transaction()`, a `'manual'`
+ * checkpoint or any other framework transaction is a savepoint of the test's
+ * transaction (isolation-level options are ignored there): the transaction id
+ * stays the same, and tenant and other transaction-local settings, and the role,
+ * are back to their earlier values once it ends. For commit boundaries, build the venue from `discoverInstance()` and
+ * `createServer()` on the package entry instead.
+ */
+export function useTestInstance(): Manifold {
+  if (!_instance) {
+    throw new Error(
+      '[pipework] No test instance available.\n\n' +
+      '  Add to your vitest.config.ts:\n' +
+      '    test: { setupFiles: [\'pipework/test/setup\'] }\n'
+    )
+  }
+  return _instance
+}
+
+export interface UseTestClientOptions {
+  /** App setup (services, sinks) that runs before the client is made. */
+  before?: () => void | Promise<void>
+}
+
+/**
+ * A test client made in this file's `beforeAll` and closed in its `afterAll`
+ * only if it was made, so a failed setup reports only its own error. Replaces
+ * the `let client; beforeAll(...); afterAll(() => client.close())` pattern.
+ *
+ *   const client = useTestClient(api, useTestInstance, {
+ *     before: async () => { await startSinks() },
+ *   })
+ *   it('answers', async () => { expect((await client.inject({ url: '/x' })).statusCode).toBe(200) })
+ *
+ * `inject` throws a `[pipework]` error if the client was not made or is closed.
+ */
+export function useTestClient(
+  surface: { test(context: SurfaceContext): Promise<TestClient> },
+  context: () => SurfaceContext = useTestInstance,
+  options: UseTestClientOptions = {},
+): TestClient {
+  let made: TestClient | undefined
+  let closed = false
+
+  beforeAll(async () => {
+    await options.before?.()
+    made = await surface.test(context())
+  })
+
+  const close = async (): Promise<void> => {
+    if (!made || closed) return
+    closed = true
+    await made.close()
+  }
+
+  afterAll(close)
+
+  return {
+    async inject(opts) {
+      if (closed) {
+        throw new Error('[pipework] The test client is closed: inject() ran after close() or afterAll.')
+      }
+      if (!made) {
+        throw new Error('[pipework] The test client was not made: setup failed or the call ran before beforeAll. See the setup error above.')
+      }
+      return await made.inject(opts)
+    },
+    close,
+  }
+}
+
+export interface WithFlowOptions {
+  auth?: unknown
+  tenant?: string | null
+}
+
+export function withFlow<T>(fn: () => T): Promise<Awaited<T>>
+export function withFlow<T>(options: WithFlowOptions, fn: () => T): Promise<Awaited<T>>
+export async function withFlow<T>(fnOrOptions: (() => T) | WithFlowOptions, maybeFn?: () => T): Promise<Awaited<T>> {
+  if (!_testContext || !_instance) {
+    throw new Error(
+      '[pipework] No test context available.\n\n' +
+      '  Add to your vitest.config.ts:\n' +
+      '    test: { setupFiles: [\'pipework/test/setup\'] }\n'
+    )
+  }
+
+  const options = typeof fnOrOptions === 'function' ? {} : fnOrOptions
+  const fn = typeof fnOrOptions === 'function' ? fnOrOptions : maybeFn!
+
+  const ctx = createTestContext(_instance, _testContext, options.auth, options.tenant)
+
+  if (options.tenant != null) {
+    await propagateTestSessionVars(_instance, _testContext, options.tenant)
+  }
+
+  return await runInContext(ctx, fn) as Awaited<T>
+}
+
+function isInstance(v: Blueprint | Manifold): v is Manifold {
+  return 'pool' in v && 'config' in v
+}

package/src/test/watch.ts

@@ -0,0 +1,105 @@
+import { readFile } from 'node:fs/promises'
+import postgres from 'postgres'
+import { getAdminUrl } from './reap.js'
+
+/** Prefix for the one stderr line written when a test is 2/3 of the way to its timeout. */
+export const TEST_WATCH_LOG_PREFIX = 'pipework:test-watch'
+
+const QUERY_MAX_CHARS = 200
+const WATCH_FRACTION = 2 / 3
+const WATCH_QUERY_TIMEOUT_MS = 5_000
+
+export interface TestWatchTarget {
+  /** The test's full name, suites included. */
+  name: string
+  /** The effective timeout of the test in ms; 0 or less disables the watch. */
+  timeoutMs: number
+  /** Per-test databases whose backends are reported, with a URL to reach their server. */
+  databases: readonly { database: string; url: string }[]
+}
+
+interface BackendRow {
+  datname: string
+  pid: number
+  state: string | null
+  wait_event_type: string | null
+  wait_event: string | null
+  state_s: string | null
+  blocked_by: string | null
+  query: string | null
+}
+
+/**
+ * Arms a timer at 2/3 of the test's timeout. On fire it samples pg_stat_activity
+ * over its own short-lived connection (the test's is busy) plus the host's load
+ * and pressure files, and writes one line. Returns the disarm function; a test
+ * that ends first prints nothing. Nothing here may fail or delay the test.
+ */
+export function armTestWatch(
+  target: TestWatchTarget,
+  write: (line: string) => void = line => console.warn(line),
+): () => void {
+  if (!(target.timeoutMs > 0)) return () => {}
+  const timer = setTimeout(() => {
+    void sampleLine(target).then(write, () => {})
+  }, Math.floor(target.timeoutMs * WATCH_FRACTION))
+  timer.unref()
+  return () => clearTimeout(timer)
+}
+
+async function sampleLine(target: TestWatchTarget): Promise<string> {
+  const parts: string[] = [`${TEST_WATCH_LOG_PREFIX} test=${JSON.stringify(target.name)} timeout_ms=${String(target.timeoutMs)}`]
+  const urls = new Map<string, string>()
+  for (const d of target.databases) urls.set(d.database, d.url)
+  const byServer = new Map<string, string[]>()
+  for (const [database, url] of urls) {
+    const admin = getAdminUrl(url)
+    byServer.set(admin, [...(byServer.get(admin) ?? []), database])
+  }
+  for (const [adminUrl, names] of byServer) {
+    try {
+      parts.push(...(await backends(adminUrl, names)))
+    } catch (error) {
+      parts.push(`watch-error=${oneLine(error instanceof Error ? error.message : String(error), 120)}`)
+    }
+  }
+  for (const [label, path] of [['loadavg', '/proc/loadavg'], ['pressure_io', '/proc/pressure/io'], ['pressure_cpu', '/proc/pressure/cpu']] as const) {
+    try {
+      parts.push(`${label}=${JSON.stringify(oneLine((await readFile(path, 'utf8')).trim(), 200))}`)
+    } catch {
+      // absent (non-Linux, or no PSI): skip silently
+    }
+  }
+  return parts.join(' ')
+}
+
+async function backends(adminUrl: string, databases: string[]): Promise<string[]> {
+  const client = postgres(adminUrl, { max: 1, onnotice: () => {}, connect_timeout: 5 })
+  try {
+    const rows = await Promise.race([
+      client<BackendRow[]>`
+        SELECT datname, pid, state, wait_event_type, wait_event,
+               round(extract(epoch FROM (now() - state_change))::numeric, 1)::text AS state_s,
+               pg_blocking_pids(pid)::text AS blocked_by, query
+          FROM pg_stat_activity
+         WHERE datname = ANY(${databases}) AND pid <> pg_backend_pid()
+         ORDER BY datname, pid`,
+      new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error('pg_stat_activity query timed out')), WATCH_QUERY_TIMEOUT_MS).unref()
+      }),
+    ])
+    if (rows.length === 0) return [`backends(${databases.join(',')})=none`]
+    return rows.map(r =>
+      `backend[db=${r.datname} pid=${String(r.pid)} state=${r.state ?? '-'} ` +
+      `wait=${r.wait_event_type ?? '-'}/${r.wait_event ?? '-'} in_state_s=${r.state_s ?? '-'} ` +
+      `blocked_by=${r.blocked_by ?? '{}'} query=${JSON.stringify(oneLine(r.query ?? '', QUERY_MAX_CHARS))}]`,
+    )
+  } finally {
+    void client.end({ timeout: 1 }).catch(() => {})
+  }
+}
+
+function oneLine(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, ' ')
+  return flat.length > max ? `${flat.slice(0, max)}...` : flat
+}

package/src/trace/capture/bounded-serializer.ts

@@ -0,0 +1,146 @@
+// The bounded serializer is the last safety net on trace input capture: it
+// turns an arbitrary captured value into something JSON-safe, size-bounded, and
+// redacted before it lands in `trace_step.captured_inputs`.
+//
+// "Safe" means it never throws and never blows up the trace row: depth, fan-out
+// and string length are all capped, cycles are broken, and non-JSON primitives
+// (bigint, NaN, Date, functions) are rendered to stable markers or strings.
+// "Redacted" means it runs every key-path through the same redact matcher the
+// logger uses, so a path censored in logs is censored in traces too.
+
+import { compileRedactPaths, type RedactMatcher } from '../../core/logging/redact-match.js'
+import { DEFAULT_REDACT_PATHS } from '../../core/logging/index.js'
+
+export interface TraceSerializeOptions {
+  /** Nested objects/arrays deeper than this are replaced with a marker. */
+  readonly maxDepth?: number
+  /** Object keys / array items kept per level; the excess is summarized. */
+  readonly maxEntries?: number
+  /** Strings longer than this are truncated with a marker. */
+  readonly maxStringLength?: number
+  /** Key-path matcher; matching values are replaced with `[Redacted]`. */
+  readonly redact?: RedactMatcher
+}
+
+interface ResolvedOptions {
+  readonly maxDepth: number
+  readonly maxEntries: number
+  readonly maxStringLength: number
+  readonly redact: RedactMatcher
+}
+
+const DEFAULTS = {
+  maxDepth: 6,
+  maxEntries: 64,
+  maxStringLength: 1024,
+  redact: compileRedactPaths(DEFAULT_REDACT_PATHS),
+} as const
+
+/**
+ * Serialize a captured value into a JSON-safe, bounded, redacted form.
+ *
+ * The result contains only `null`, booleans, finite numbers, strings, plain
+ * objects and arrays — safe to write straight into a `jsonb` column. Anything
+ * that would break those guarantees is replaced with a `[…]` marker rather than
+ * dropped silently, so a reader can tell capture hit a bound.
+ */
+export function serializeForTrace(value: unknown, options: TraceSerializeOptions = {}): unknown {
+  const resolved: ResolvedOptions = {
+    maxDepth: options.maxDepth ?? DEFAULTS.maxDepth,
+    maxEntries: options.maxEntries ?? DEFAULTS.maxEntries,
+    maxStringLength: options.maxStringLength ?? DEFAULTS.maxStringLength,
+    redact: options.redact ?? DEFAULTS.redact,
+  }
+  return walk(value, 0, [], new WeakSet<object>(), resolved)
+}
+
+function walk(
+  value: unknown,
+  depth: number,
+  keyPath: readonly string[],
+  seen: WeakSet<object>,
+  opts: ResolvedOptions,
+): unknown {
+  if (value === null) return null
+
+  switch (typeof value) {
+    case 'string':
+      return boundString(value, opts.maxStringLength)
+    case 'number':
+      return Number.isFinite(value) ? value : String(value)
+    case 'boolean':
+      return value
+    case 'bigint':
+      return value.toString()
+    case 'undefined':
+      return undefined
+    case 'function':
+      return '[Function]'
+    case 'symbol':
+      return value.toString()
+  }
+
+  if (value instanceof Date) return value.toISOString()
+
+  if (depth >= opts.maxDepth) return '[Pruned: max depth]'
+  if (seen.has(value)) return '[Circular]'
+  seen.add(value)
+  const result = Array.isArray(value)
+    ? walkArray(value, depth, keyPath, seen, opts)
+    : walkObject(value as Record<string, unknown>, depth, keyPath, seen, opts)
+  seen.delete(value)
+  return result
+}
+
+function walkArray(
+  value: readonly unknown[],
+  depth: number,
+  keyPath: readonly string[],
+  seen: WeakSet<object>,
+  opts: ResolvedOptions,
+): unknown[] {
+  const out: unknown[] = []
+  for (const item of value.slice(0, opts.maxEntries)) {
+    // Arrays are transparent to the redact key-path: an item carries its
+    // parent's path, not an index segment. This makes redaction match by
+    // object-key nesting and, where it differs from pino, errs toward
+    // redacting more — the safe direction for a capture net.
+    const serialized = walk(item, depth + 1, keyPath, seen, opts)
+    // JSON arrays cannot carry holes; an undefined slot becomes null.
+    out.push(serialized === undefined ? null : serialized)
+  }
+  if (value.length > opts.maxEntries) {
+    out.push(`[Pruned: ${value.length - opts.maxEntries} more items]`)
+  }
+  return out
+}
+
+function walkObject(
+  value: Record<string, unknown>,
+  depth: number,
+  keyPath: readonly string[],
+  seen: WeakSet<object>,
+  opts: ResolvedOptions,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  const entries = Object.entries(value)
+  for (const [key, raw] of entries.slice(0, opts.maxEntries)) {
+    const path = [...keyPath, key]
+    if (opts.redact(path)) {
+      out[key] = '[Redacted]'
+      continue
+    }
+    const serialized = walk(raw, depth + 1, path, seen, opts)
+    // An undefined property is absent in JSON; drop it rather than emit a hole.
+    if (serialized !== undefined) out[key] = serialized
+  }
+  if (entries.length > opts.maxEntries) {
+    out['[Pruned]'] = `${entries.length - opts.maxEntries} more keys`
+  }
+  return out
+}
+
+function boundString(value: string, max: number): string {
+  if (value.length <= max) return value
+  return `${value.slice(0, max)}[Truncated: ${value.length - max} chars]`
+}