pipework 0.251.0 → 0.252.1

package/src/request/context/create.ts

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto'
+import type { Manifold } from '../../core/pipework.js'
+import type { TraceContext } from '../../trace/entry/trace-context.js'
+import type { Flow, RequestMetadata } from './types.js'
+import type { TenantConfig } from '../../auth/tenant/types.js'
+
+export interface CreateRequestContextOptions<TAuth = unknown> {
+  instance: Manifold
+  requestId?: string
+  auth?: TAuth | null
+  tenant?: string | null
+  user?: string | null
+  asOf?: string | null
+  metadata: RequestMetadata
+  trace?: TraceContext | null
+  tenantConfig?: TenantConfig | null
+}
+
+export function createRequestContext<TAuth = unknown>(
+  options: CreateRequestContextOptions<TAuth>,
+): Flow<TAuth> {
+  return {
+    instance: options.instance,
+    requestId: options.requestId ?? randomUUID(),
+    _nonce: randomUUID(),
+    auth: options.auth ?? null,
+    tenant: options.tenant ?? null,
+    user: options.user ?? null,
+    asOf: options.asOf ?? null,
+    metadata: options.metadata,
+    jobType: null,
+    jobAttempt: null,
+    jobMaxAttempts: null,
+    tenantConfig: options.tenantConfig ?? null,
+    transactions: new Map(),
+    trace: options.trace ?? null,
+  }
+}
+
+export interface CreateJobContextOptions<TAuth = unknown> {
+  instance: Manifold
+  jobId?: string
+  jobType?: string
+  /** 1-based attempt number of the job. */
+  attempt?: number
+  /** The job's attempt limit. */
+  maxAttempts?: number
+  auth?: TAuth | null
+  tenant?: string | null
+  user?: string | null
+  asOf?: string | null
+  trace?: TraceContext | null
+  tenantConfig?: TenantConfig | null
+}
+
+export function createJobContext<TAuth = unknown>(
+  options: CreateJobContextOptions<TAuth>,
+): Flow<TAuth> {
+  return {
+    instance: options.instance,
+    requestId: options.jobId ?? randomUUID(),
+    _nonce: randomUUID(),
+    auth: options.auth ?? null,
+    tenant: options.tenant ?? null,
+    user: options.user ?? null,
+    asOf: options.asOf ?? null,
+    metadata: null,
+    jobType: options.jobType ?? null,
+    jobAttempt: options.attempt ?? null,
+    jobMaxAttempts: options.maxAttempts ?? null,
+    tenantConfig: options.tenantConfig ?? null,
+    transactions: new Map(),
+    trace: options.trace ?? null,
+  }
+}
+
+export interface CreateTestContextOptions {
+  auth?: unknown
+  tenant?: string | null | undefined
+  user?: string | null | undefined
+  asOf?: string | null | undefined
+  trace?: TraceContext | null
+  tenantConfig?: TenantConfig | null
+}
+
+export function createTestContext(instance: Manifold, requestId?: string, options?: CreateTestContextOptions): Flow {
+  return {
+    instance,
+    requestId: requestId ?? randomUUID(),
+    _nonce: randomUUID(),
+    auth: options?.auth ?? null,
+    tenant: options?.tenant ?? null,
+    user: options?.user ?? null,
+    asOf: options?.asOf ?? null,
+    metadata: null,
+    jobType: null,
+    jobAttempt: null,
+    jobMaxAttempts: null,
+    tenantConfig: options?.tenantConfig ?? null,
+    transactions: new Map(),
+    trace: options?.trace ?? null,
+  }
+}

package/src/request/context/guard.ts

@@ -0,0 +1,49 @@
+import type { Flow, BoundTransaction } from './types.js'
+import type { DB } from '../../data/db/index.js'
+import { InvariantViolation } from '../../invariants/assert.js'
+
+export function verifyTransactionBinding(
+  ctx: Flow,
+  bound: BoundTransaction,
+  dbName: string,
+): void {
+  if (bound.nonce !== ctx._nonce) {
+    throw new InvariantViolation('context-nonce-mismatch', {
+      message:
+        `The transaction for database "${dbName}" was created in a different AsyncLocalStorage ` +
+        'context than the one currently active. This usually means Node.js swapped async contexts ' +
+        'between concurrent requests — a known ALS bug that can cause cross-tenant data leaks.',
+      transactionNonce: bound.nonce,
+      contextNonce: ctx._nonce,
+      database: dbName,
+      contextTenant: ctx.tenant,
+      requestId: ctx.requestId,
+    })
+  }
+
+  if (bound.tenant !== ctx.tenant) {
+    throw new InvariantViolation('tenant-context-mismatch', {
+      message:
+        `The transaction for database "${dbName}" was created for tenant "${bound.tenant}" ` +
+        `but the current context has tenant "${ctx.tenant}". This indicates an AsyncLocalStorage ` +
+        'context swap that would cause writes to go to the wrong tenant.\n\n' +
+        '  In tests, use withFlow({ tenant }, fn) to run tenant-scoped code:\n\n' +
+        "    import { withFlow, asTenant } from 'pipework/test'\n\n" +
+        "    withFlow({ auth: asTenant('tenant-1'), tenant: 'tenant-1' }, async () => {\n" +
+        '      // pipe() and useTestDb() work correctly here\n' +
+        '    })',
+      transactionTenant: bound.tenant,
+      contextTenant: ctx.tenant,
+      database: dbName,
+      requestId: ctx.requestId,
+    })
+  }
+}
+
+export function bindTransaction(
+  ctx: Flow,
+  dbName: string,
+  drizzle: DB,
+): BoundTransaction {
+  return { drizzle, nonce: ctx._nonce, tenant: ctx.tenant }
+}

package/src/request/context/index.ts

@@ -0,0 +1,4 @@
+export type { Flow, RequestMetadata, BoundTransaction } from './types.js'
+export { flowStorage, getContext, requireContext, runInContext } from './store.js'
+export { createRequestContext, createJobContext, createTestContext, type CreateRequestContextOptions, type CreateJobContextOptions } from './create.js'
+export { verifyTransactionBinding, bindTransaction } from './guard.js'

package/src/request/context/run-in-transaction.ts

@@ -0,0 +1,200 @@
+import type { Flow } from './types.js'
+import type { DB, ManagedConnection } from '../../data/db/index.js'
+import type { TenantConfig, TenantContext } from '../../auth/tenant/types.js'
+import { sql } from '../../data/db/sql.js'
+import { propagateTenantLocals } from '../../auth/tenant/index.js'
+import { bindTransaction } from './guard.js'
+import { runInContext } from './store.js'
+
+/**
+ * Runs `run` inside a database transaction (or one independent transaction per
+ * database, when several are involved), with the request/job context's locals
+ * propagated via `SET LOCAL` so Postgres-side RLS policies and `current_setting`
+ * lookups see the active tenant.
+ *
+ * The transactions are bound to a child context so `pipe()` and DI resolution
+ * pick them up; `run` is invoked inside that child context. This is the single
+ * shared path for both the HTTP surface and `jobs.execute` — keep it that way
+ * so the two entry points cannot drift in their isolation behaviour.
+ *
+ * With a `signal`, aborting cancels each transaction's in-flight query on the
+ * server (`pg_cancel_backend`), so the query fails, the transaction rolls back
+ * and the connection returns to the pool instead of being held to completion.
+ */
+export async function executeInTransaction<T>(
+  ctx: Flow,
+  databases: readonly string[],
+  tenant: TenantConfig | null,
+  timeoutMs: number,
+  run: () => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  const instance = ctx.instance
+
+  if (databases.length === 1) {
+    const dbName = databases[0]!
+    const dbConfig = instance.config.database(dbName)
+    const conn = instance.pool.getOrCreate(dbConfig, 'app')
+
+    return conn.drizzle.transaction(async (tx) => {
+      const childCtx: Flow = {
+        ...ctx,
+        transactions: new Map(ctx.transactions),
+      }
+      childCtx.transactions.set(dbName, bindTransaction(ctx, dbName, tx))
+
+      await propagateLocals(tx, ctx, tenant)
+
+      const disarm = await armCancellation(conn, tx, signal)
+      try {
+        return await runInContext(childCtx, run)
+      } finally {
+        disarm()
+      }
+    })
+  }
+
+  // Multiple databases: nested transactions (each independent)
+  const childCtx: Flow = {
+    ...ctx,
+    transactions: new Map(ctx.transactions),
+  }
+
+  const txPromises: Promise<void>[] = []
+  const readyPromises: Promise<void>[] = []
+  const disarms: (() => void)[] = []
+  const readyDatabases = new Set<string>()
+  let releaseAll!: () => void
+  let abortAll!: (err: Error) => void
+
+  const donePromise = new Promise<void>((resolve, reject) => {
+    releaseAll = resolve
+    abortAll = reject
+  })
+  donePromise.catch(() => {})
+
+  for (const dbName of databases) {
+    const dbConfig = instance.config.database(dbName)
+    const conn = instance.pool.getOrCreate(dbConfig, 'app')
+
+    let signalReady!: () => void
+    readyPromises.push(new Promise<void>(r => { signalReady = r }))
+
+    txPromises.push(
+      conn.drizzle.transaction(async (tx) => {
+        childCtx.transactions.set(dbName, bindTransaction(ctx, dbName, tx))
+        await propagateLocals(tx, ctx, tenant)
+        disarms.push(await armCancellation(conn, tx, signal))
+        readyDatabases.add(dbName)
+        signalReady()
+        await donePromise
+      }),
+    )
+  }
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    const timer = setTimeout(() => {
+      const pending = databases.filter(db => !readyDatabases.has(db))
+      reject(new Error(
+        `[pipework] Multi-database transaction setup timed out after ${timeoutMs}ms.\n\n` +
+        `  Database(s) that failed to become ready: ${pending.join(', ')}\n` +
+        `  Database(s) that are ready: ${[...readyDatabases].join(', ') || '(none)'}\n\n` +
+        '  This usually means one of the databases is unreachable or under heavy load.\n' +
+        '  You can increase the timeout via createServer({ transactionTimeoutMs }).\n'
+      ))
+    }, timeoutMs)
+    timer.unref()
+  })
+
+  const disarmAll = (): void => { for (const disarm of disarms) disarm() }
+
+  try {
+    await Promise.race([Promise.all(readyPromises), timeoutPromise])
+  } catch (err) {
+    abortAll(err instanceof Error ? err : new Error(String(err)))
+    await Promise.allSettled(txPromises)
+    disarmAll()
+    throw err
+  }
+
+  try {
+    const result = await runInContext(childCtx, run)
+    releaseAll()
+    await Promise.all(txPromises)
+    return result
+  } catch (err) {
+    abortAll(err instanceof Error ? err : new Error(String(err)))
+    await Promise.allSettled(txPromises)
+    throw err
+  } finally {
+    disarmAll()
+  }
+}
+
+/**
+ * Arms server-side cancellation for one transaction: on abort, a separate
+ * pooled connection issues `pg_cancel_backend` against the backend this
+ * transaction holds, so an in-flight query fails with `query_canceled` and the
+ * transaction unwinds. Returns a disarm function — always call it, or the
+ * listener outlives the transaction and cancels a backend the pool has since
+ * handed to someone else.
+ */
+async function armCancellation(
+  conn: ManagedConnection,
+  tx: DB,
+  signal: AbortSignal | undefined,
+): Promise<() => void> {
+  if (signal === undefined) return () => {}
+
+  const [row] = await tx.execute(sql`SELECT pg_backend_pid() AS pid`)
+  const pid = Number((row as { pid?: unknown } | undefined)?.pid)
+  if (!Number.isInteger(pid)) return () => {}
+
+  const cancel = (): void => {
+    // Best effort: the backend may already have finished, and a failed cancel
+    // must not replace the abort the caller is about to see.
+    void conn.drizzle.execute(sql`SELECT pg_cancel_backend(${pid})`).catch(() => {})
+  }
+
+  if (signal.aborted) {
+    cancel()
+    return () => {}
+  }
+
+  signal.addEventListener('abort', cancel, { once: true })
+  return () => { signal.removeEventListener('abort', cancel) }
+}
+
+/**
+ * Propagates context locals onto a transaction via `SET LOCAL`: the request id,
+ * the tenant id (`pipework.tenant_id`, read by generated RLS policies), and any
+ * custom tenant session variables.
+ */
+export async function propagateLocals(
+  tx: DB,
+  ctx: Flow,
+  tenant: TenantConfig | null,
+): Promise<void> {
+  if (ctx.requestId !== '') {
+    await tx.execute(sql`SELECT set_config('pipework.request_id', ${ctx.requestId}, true)`)
+  }
+  if (ctx.tenant !== null) {
+    await tx.execute(sql`SELECT set_config('pipework.tenant_id', ${ctx.tenant}, true)`)
+  }
+  if (ctx.user !== null) {
+    await tx.execute(sql`SELECT set_config('pipework.user_id', ${ctx.user}, true)`)
+  }
+  if (ctx.asOf !== null) {
+    await tx.execute(sql`SELECT set_config('pipework.asof', ${ctx.asOf}, true)`)
+  }
+  if (tenant !== null && tenant.sessionVars !== undefined && ctx.tenant !== null) {
+    const tenantCtx: TenantContext = {
+      tenant: ctx.tenant,
+      requestId: ctx.requestId,
+      userId: ctx.auth !== null && typeof ctx.auth === 'object' && 'userId' in ctx.auth
+        ? (ctx.auth as { userId: string }).userId
+        : null,
+    }
+    await propagateTenantLocals(tx, tenant, tenantCtx)
+  }
+}

package/src/request/context/store.ts

@@ -0,0 +1,28 @@
+import { runtime } from '../../core/runtime/broker.js'
+import type { Flow } from './types.js'
+
+// Pinned to the cross-realm runtime broker, not a fresh module singleton: when a
+// shared leaf library resolves its own physical copy of pipework, both copies must
+// share ONE AsyncLocalStorage or a context entered by one is invisible to pipe() in
+// the other. See src/core/runtime/broker.ts.
+export const flowStorage = runtime().flowStorage
+
+export function getContext<TAuth = unknown>(): Flow<TAuth> | undefined {
+  return flowStorage.getStore() as Flow<TAuth> | undefined
+}
+
+export function requireContext<TAuth = unknown>(): Flow<TAuth> {
+  const ctx = flowStorage.getStore() as Flow<TAuth> | undefined
+  if (!ctx) {
+    throw new Error(
+      '[pipework] No active context. db() must be called within a request handler, job, or test.\n\n' +
+      '  Hint: If you need a connection outside of a managed context (migrations, seeds),\n' +
+      '  use instance.pool.getOrCreate(config.database("name")).drizzle instead.\n'
+    )
+  }
+  return ctx
+}
+
+export function runInContext<T>(ctx: Flow, fn: () => T): T {
+  return flowStorage.run(ctx, fn)
+}

package/src/request/context/types.ts

@@ -0,0 +1,50 @@
+import type { DB } from '../../data/db/index.js'
+import type { Manifold } from '../../core/pipework.js'
+import type { TenantConfig } from '../../auth/tenant/types.js'
+import type { TraceContext } from '../../trace/entry/trace-context.js'
+
+/** A transaction bound to a specific context nonce and tenant — defense-in-depth against ALS context swaps. */
+export interface BoundTransaction {
+  readonly drizzle: DB
+  readonly nonce: string
+  readonly tenant: string | null
+}
+
+/** The AsyncLocalStorage context — carries requestId, auth, tenant, active transactions, and a nonce for integrity checks. */
+export interface Flow<TAuth = unknown> {
+  readonly instance: Manifold
+  readonly requestId: string
+  readonly _nonce: string
+  readonly auth: TAuth | null
+  readonly tenant: string | null
+  /** The acting principal's user id — propagated as `pipework.user_id` for user-level RLS. */
+  readonly user: string | null
+  /** The as-of instant access is evaluated against — propagated as `pipework.asof` for temporal RLS. Null = current. */
+  readonly asOf: string | null
+  readonly metadata: RequestMetadata | null
+  readonly jobType: string | null
+  /** The 1-based attempt of the job this Flow runs, counting attempts a lost worker used; null outside a worker-run job. */
+  readonly jobAttempt: number | null
+  /** The attempt limit of the job this Flow runs; null outside a worker-run job. */
+  readonly jobMaxAttempts: number | null
+  /**
+   * The tenant configuration in force at this entry, or `null` where none is
+   * configured. Carried on the context so ANY transaction opened inside it can
+   * propagate the same session variables the entry's own transaction does —
+   * without it, a transaction opened by `pipe.transaction` propagated nothing
+   * and every RLS policy read zero rows.
+   */
+  readonly tenantConfig: TenantConfig | null
+  readonly transactions: Map<string, BoundTransaction>
+  /** The trace opened at this entry, or `null` when the entry ran untraced. */
+  readonly trace: TraceContext | null
+}
+
+/** HTTP request metadata stored in a Flow — method, path, trace ID, session ID. */
+export interface RequestMetadata {
+  readonly method: string
+  readonly path: string
+  readonly startedAt: number
+  readonly traceId: string
+  readonly sessionId: string | null
+}