pipework 0.251.0 → 0.252.1

package/src/request/fixture/namespace.ts

@@ -0,0 +1,23 @@
+import { resourceToHandlers } from './to-handlers.js'
+import { MethodNotAllowedError } from './errors.js'
+import { encodeCursor, decodeCursor, buildPage } from './paginate.js'
+import { validateBatchRequest } from './batch.js'
+import { buildResource } from './builder.js'
+
+/** REST resource builder namespace — declarative CRUD with cursor pagination and batch operations. */
+export const fixture = {
+  /** Converts a Resource into fitted Handler[] that go through the standard handler pipeline. */
+  toHandlers: resourceToHandlers,
+  /** Builds a Resource from a name, operations map, and builder state — used internally by fitting().fixture(). */
+  build: buildResource,
+  /** Encodes pagination cursor values into an opaque base64 string. */
+  encodeCursor,
+  /** Decodes an opaque pagination cursor back into its values. */
+  decodeCursor,
+  /** Builds a PageResult from rows, limit, and cursor extractor — handles hasMore detection. */
+  buildPage,
+  /** Validates a batch request body (preview/execute mode, targets, actions). */
+  validateBatch: validateBatchRequest,
+  /** Thrown when a resource doesn't support the requested HTTP method. */
+  MethodNotAllowedError,
+}

package/src/request/fixture/paginate.ts

@@ -0,0 +1,44 @@
+import { ValidationError } from '../../core/errors/index.js'
+
+export interface PageResult<T> {
+  readonly items: T[]
+  readonly cursor: string | null
+  readonly hasMore: boolean
+}
+
+export interface CursorPaginationParams {
+  readonly cursor?: string
+  readonly limit: number
+}
+
+export function encodeCursor(values: readonly unknown[]): string {
+  const json = JSON.stringify(values)
+  return Buffer.from(json).toString('base64url')
+}
+
+export function decodeCursor(cursor: string): unknown[] {
+  try {
+    const json = Buffer.from(cursor, 'base64url').toString('utf-8')
+    const parsed: unknown = JSON.parse(json)
+    if (!Array.isArray(parsed)) {
+      throw new ValidationError('Invalid cursor: expected encoded array')
+    }
+    return parsed
+  } catch (err) {
+    if (err instanceof ValidationError) throw err
+    throw new ValidationError('Invalid cursor: malformed or tampered value')
+  }
+}
+
+export function buildPage<T>(
+  rows: readonly T[],
+  limit: number,
+  getCursor: (item: T) => string,
+): PageResult<T> {
+  const hasMore = rows.length > limit
+  const items = hasMore ? rows.slice(0, limit) : [...rows]
+  const cursor = hasMore && items.length > 0
+    ? encodeCursor([getCursor(items[items.length - 1]!)])
+    : null
+  return { items, cursor, hasMore }
+}

package/src/request/fixture/to-handlers.ts

@@ -0,0 +1,260 @@
+import type { DB } from '../../data/db/index.js'
+import type { Handler, HandlerMeta, HttpMethod } from '../di/types.js'
+import { DEFAULT_DB } from '../di/types.js'
+import type { Resource, PaginationConfig } from './types.js'
+import { unknown as unknownSchema } from '../../data/schema/generated/type-constructor.js'
+import { requireContext } from '../context/store.js'
+import { NotFoundError } from '../../core/errors/index.js'
+import { MethodNotAllowedError } from './errors.js'
+import { validateBatchRequest } from './batch.js'
+import { singularize } from '../internal/text.js'
+
+type AnyHandler = Handler<Record<string, unknown>, unknown>
+
+const passthroughSchema = unknownSchema().refine((value) => value !== undefined, 'A request body is required')
+
+function makeMeta(
+  resource: Resource<unknown>,
+  method: HttpMethod,
+  path: string,
+  overrides?: Partial<HandlerMeta>,
+): HandlerMeta {
+  const { database, authRequirement, permission } = resource.meta
+  return {
+    databases: [database],
+    requiresAuth: authRequirement === 'required',
+    authRequirement,
+    inputSchema: null,
+    outputSchemas: new Map(),
+    querySchema: null,
+    paramsSchema: null,
+    route: { method, path },
+    isJob: false,
+    jobType: null,
+    jobRetry: null,
+    jobTimeout: null,
+    jobTransaction: 'auto',
+    permission,
+    wantsRequest: false,
+    wantsResponse: false,
+    wantsRawBody: false,
+    ...overrides,
+  }
+}
+
+function make405(resource: Resource<unknown>, method: HttpMethod, path: string): AnyHandler {
+  return {
+    meta: makeMeta(resource, method, path, {
+      databases: [],
+      requiresAuth: false,
+      authRequirement: 'none',
+      permission: null,
+    }),
+    execute() {
+      return Promise.reject(new MethodNotAllowedError(method, resource.meta.name))
+    },
+  }
+}
+
+function depKey(database: string): string {
+  return database === DEFAULT_DB ? 'db' : database
+}
+
+function parsePagination(
+  query: Record<string, unknown> | undefined,
+  config: PaginationConfig,
+): { limit: number; offset: number } {
+  const rawLimit = query?.['limit'] !== undefined ? parseInt(String(query['limit']), 10) : config.defaultLimit
+  const limit = Math.min(Math.max(1, Number.isNaN(rawLimit) ? config.defaultLimit : rawLimit), config.maxLimit)
+  const rawOffset = query?.['offset'] !== undefined ? parseInt(String(query['offset']), 10) : 0
+  const offset = Math.max(0, Number.isNaN(rawOffset) ? 0 : rawOffset)
+  return { limit, offset }
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+
+export function resourceToHandlers(resource: Resource<unknown>): AnyHandler[] {
+  const handlers: AnyHandler[] = []
+  const { name, database, pagination } = resource.meta
+  const ops = resource.operations
+  const basePath = `/${name}`
+  const itemPath = `/${name}/:id`
+  const key = depKey(database)
+
+  // GET /resource — list
+  if (ops.listCursor !== undefined && pagination !== null) {
+    handlers.push({
+      meta: makeMeta(resource, 'GET', basePath, { querySchema: passthroughSchema }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const query = deps['query'] as Record<string, unknown> | undefined
+        const rawLimit = query?.['limit'] !== undefined ? parseInt(String(query['limit']), 10) : pagination.defaultLimit
+        const limit = Math.min(Math.max(1, Number.isNaN(rawLimit) ? pagination.defaultLimit : rawLimit), pagination.maxLimit)
+        const cursor = query?.['cursor'] !== undefined ? String(query['cursor']) : undefined
+        const result = await ops.listCursor!(db, auth, tenant, cursor !== undefined ? { cursor, limit } : { limit })
+        return { status: 200, body: result }
+      },
+    })
+  } else if (ops.listPaginated !== undefined && pagination !== null) {
+    handlers.push({
+      meta: makeMeta(resource, 'GET', basePath, { querySchema: passthroughSchema }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const query = deps['query'] as Record<string, unknown> | undefined
+        const { limit, offset } = parsePagination(query, pagination)
+        const result = await ops.listPaginated!(db, auth, tenant, { limit, offset })
+        return {
+          status: 200,
+          body: {
+            data: result.data,
+            pagination: { limit, offset, total: result.total, hasMore: offset + result.data.length < result.total },
+          },
+        }
+      },
+    })
+  } else if (ops.list !== undefined) {
+    handlers.push({
+      meta: makeMeta(resource, 'GET', basePath),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const result = await ops.list!(db, auth, tenant)
+        return { status: 200, body: result }
+      },
+    })
+  } else {
+    handlers.push(make405(resource, 'GET', basePath))
+  }
+
+  // GET /resource/:id
+  if (ops.get !== undefined) {
+    handlers.push({
+      meta: makeMeta(resource, 'GET', itemPath, { paramsSchema: passthroughSchema }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const params = deps['params'] as Record<string, unknown>
+        const id = String(params['id'])
+        const result = await ops.get!(db, auth, tenant, id)
+        if (result === null || result === undefined) {
+          throw new NotFoundError(`${capitalize(singularize(name))} "${id}"`)
+        }
+        return { status: 200, body: result }
+      },
+    })
+  } else {
+    handlers.push(make405(resource, 'GET', itemPath))
+  }
+
+  // POST /resource
+  if (ops.create !== undefined) {
+    handlers.push({
+      meta: makeMeta(resource, 'POST', basePath, {
+        inputSchema: ops.create.input ?? passthroughSchema,
+      }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const input = deps['input']
+        const result = await ops.create!.handler(db, auth, tenant, input)
+        return { status: 201, body: result }
+      },
+    })
+  } else {
+    handlers.push(make405(resource, 'POST', basePath))
+  }
+
+  // PUT /resource/:id
+  if (ops.update !== undefined) {
+    handlers.push({
+      meta: makeMeta(resource, 'PUT', itemPath, {
+        inputSchema: ops.update.input ?? passthroughSchema,
+        paramsSchema: passthroughSchema,
+      }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const params = deps['params'] as Record<string, unknown>
+        const id = String(params['id'])
+        const input = deps['input']
+        const result = await ops.update!.handler(db, auth, tenant, id, input)
+        if (result === null || result === undefined) {
+          throw new NotFoundError(`${capitalize(singularize(name))} "${id}"`)
+        }
+        return { status: 200, body: result }
+      },
+    })
+  } else {
+    handlers.push(make405(resource, 'PUT', itemPath))
+  }
+
+  // DELETE /resource/:id
+  if (ops.delete !== undefined) {
+    handlers.push({
+      meta: makeMeta(resource, 'DELETE', itemPath, { paramsSchema: passthroughSchema }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const params = deps['params'] as Record<string, unknown>
+        const id = String(params['id'])
+        await ops.delete!(db, auth, tenant, id)
+        return { status: 204 }
+      },
+    })
+  } else {
+    handlers.push(make405(resource, 'DELETE', itemPath))
+  }
+
+  if (ops.batch !== undefined) {
+    const validActions = Object.keys(ops.batch)
+
+    handlers.push({
+      meta: makeMeta(resource, 'POST', `${basePath}/batch/preview`, {
+        inputSchema: passthroughSchema,
+      }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const input = deps['input']
+        const { action, targets } = validateBatchRequest(input, validActions)
+        const batchAction = ops.batch![action]!
+        if (batchAction.preview === undefined) {
+          throw new MethodNotAllowedError('POST', `${name}/batch/preview (action: ${action})`)
+        }
+        const result = await batchAction.preview(db, auth, tenant, targets)
+        return { status: 200, body: result }
+      },
+    })
+
+    handlers.push({
+      meta: makeMeta(resource, 'POST', `${basePath}/batch`, {
+        inputSchema: passthroughSchema,
+      }),
+      async execute(deps) {
+        const db = deps[key] as DB
+        const auth = deps['auth'] as unknown
+        const tenant = requireContext().tenant
+        const input = deps['input']
+        const { action, targets } = validateBatchRequest(input, validActions)
+        const batchAction = ops.batch![action]!
+        const result = await batchAction.execute(db, auth, tenant, targets)
+        return { status: 200, body: result }
+      },
+    })
+  }
+
+  return handlers
+}

package/src/request/fixture/types.ts

@@ -0,0 +1,79 @@
+import type { Schema } from '../../data/schema/types.js'
+import type { DB } from '../../data/db/index.js'
+import type { AuthRequirement, PermissionMeta } from '../di/types.js'
+
+export type ResourceId = string
+
+export interface PaginationConfig {
+  readonly defaultLimit: number
+  readonly maxLimit: number
+}
+
+export interface PaginationParams {
+  readonly limit: number
+  readonly offset: number
+}
+
+export interface PaginatedResponse<T = unknown> {
+  readonly data: T[]
+  readonly pagination: {
+    readonly limit: number
+    readonly offset: number
+    readonly total: number
+    readonly hasMore: boolean
+  }
+}
+
+export interface ResourceListOp<TAuth> {
+  (db: DB, auth: TAuth, tenant: string | null): Promise<readonly unknown[]>
+}
+
+export interface ResourceListPaginatedOp<TAuth> {
+  (db: DB, auth: TAuth, tenant: string | null, pagination: PaginationParams): Promise<{ data: readonly unknown[]; total: number }>
+}
+
+export interface ResourceListCursorOp<TAuth> {
+  (db: DB, auth: TAuth, tenant: string | null, pagination: import('./paginate.js').CursorPaginationParams): Promise<import('./paginate.js').PageResult<unknown>>
+}
+
+export interface ResourceGetOp<TAuth> {
+  (db: DB, auth: TAuth, tenant: string | null, id: ResourceId): Promise<unknown | null>
+}
+
+export interface ResourceCreateOp<TAuth> {
+  readonly input?: Schema
+  readonly handler: (db: DB, auth: TAuth, tenant: string | null, input: unknown) => Promise<unknown>
+}
+
+export interface ResourceUpdateOp<TAuth> {
+  readonly input?: Schema
+  readonly handler: (db: DB, auth: TAuth, tenant: string | null, id: ResourceId, input: unknown) => Promise<unknown | null>
+}
+
+export interface ResourceDeleteOp<TAuth> {
+  (db: DB, auth: TAuth, tenant: string | null, id: ResourceId): Promise<void>
+}
+
+export interface ResourceOperations<TAuth> {
+  readonly list?: ResourceListOp<TAuth>
+  readonly listPaginated?: ResourceListPaginatedOp<TAuth>
+  readonly listCursor?: ResourceListCursorOp<TAuth>
+  readonly get?: ResourceGetOp<TAuth>
+  readonly create?: ResourceCreateOp<TAuth>
+  readonly update?: ResourceUpdateOp<TAuth>
+  readonly delete?: ResourceDeleteOp<TAuth>
+  readonly batch?: Record<string, import('./batch.js').BatchAction<TAuth>>
+}
+
+export interface ResourceMeta {
+  readonly name: string
+  readonly database: string
+  readonly authRequirement: AuthRequirement
+  readonly permission: PermissionMeta | null
+  readonly pagination: PaginationConfig | null
+}
+
+export interface Resource<TAuth> {
+  readonly meta: ResourceMeta
+  readonly operations: ResourceOperations<TAuth>
+}

package/src/request/flow/act-as.ts

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto'
+import type { Flow } from '../context/types.js'
+import type { DB } from '../../data/db/index.js'
+import { requireContext, runInContext } from '../context/store.js'
+import { bindTransaction } from '../context/guard.js'
+import { sql } from '../../data/db/sql.js'
+import { propagateLocals } from '../context/run-in-transaction.js'
+import { openChildTrace } from '../../trace/entry/child-trace.js'
+import { finalizeTrace } from '../../trace/entry/finalize-trace.js'
+
+/**
+ * Runs `fn` as `as.tenant` and `as.userId` from a Flow that has no tenant: a
+ * sign-up that has just founded a tenant, a public sign-in recording into its
+ * org. Row-level security, audit rows (tenant and actor) and the trace all
+ * carry that tenant and user.
+ *
+ * `fn` runs in a savepoint of the request's own transaction, so it commits or
+ * rolls back with the request. If `fn` throws, its writes are undone, the
+ * request's transaction stays usable and the error is rethrown. When `actAs`
+ * returns the Flow and the transaction are tenantless again. A Flow with no
+ * transaction on the default database gets a new app-role transaction instead.
+ * Refused when the Flow already has a tenant.
+ */
+export async function actAs<T>(
+  as: { readonly tenant: string; readonly userId: string },
+  fn: () => Promise<T>,
+): Promise<T> {
+  const flow = requireContext()
+  if (flow.tenant !== null) {
+    throw new Error(
+      `[pipework] flow.actAs runs only in a Flow with no tenant; this Flow is tenant "${flow.tenant}", ` +
+      `asked for "${as.tenant}".\n\n` +
+      '  actAs is for code that has just chosen a tenant (sign-up, a public sign-in). ' +
+      'Code already running as a tenant keeps that tenant.\n',
+    )
+  }
+  const dbName = flow.instance.config.defaultDatabaseName()
+  const auth = { userId: as.userId, tenantId: as.tenant }
+  const childTrace = openChildTrace(flow, as.tenant, auth)
+  const child: Flow = {
+    ...flow,
+    _nonce: randomUUID(),
+    tenant: as.tenant,
+    user: null,
+    auth,
+    transactions: new Map(),
+    trace: childTrace,
+  }
+
+  const run = async (tx: DB): Promise<T> => {
+    child.transactions.set(dbName, bindTransaction(child, dbName, tx))
+    await propagateLocals(tx, child, child.tenantConfig)
+    return runInContext(child, fn)
+  }
+
+  const parentBound = flow.transactions.get(dbName)
+  if (parentBound === undefined) {
+    const conn = flow.instance.pool.getOrCreate(flow.instance.config.database(dbName), 'app')
+    return finalizeTrace(flow.instance, childTrace, conn.drizzle.transaction(run))
+  }
+
+  const parentTx = parentBound.drizzle
+  const names = [
+    'pipework.request_id', 'pipework.tenant_id', 'pipework.user_id', 'pipework.asof',
+    ...Object.keys(flow.tenantConfig?.sessionVars ?? {}),
+  ]
+  const before = new Map<string, string>()
+  for (const name of names) {
+    const rows = await parentTx.execute(sql`SELECT current_setting(${name}, true) AS value`)
+    before.set(name, (rows[0]?.['value'] as string | null | undefined) ?? '')
+  }
+  const work = parentTx.transaction(run).then(async (value) => {
+    // Releasing the savepoint keeps its SET LOCALs; put the request's own back.
+    for (const [name, value] of before) await parentTx.execute(sql`SELECT set_config(${name}, ${value}, true)`)
+    return value
+  })
+  return finalizeTrace(flow.instance, childTrace, work)
+}

package/src/request/flow/namespace.ts

@@ -0,0 +1,17 @@
+import { runInContext, requireContext, getContext } from '../context/store.js'
+import { createTestContext } from '../context/create.js'
+import { actAs } from './act-as.js'
+
+/** AsyncLocalStorage context namespace — manages request/job/test contexts that carry auth, tenant, transactions. */
+export const flow = {
+  /** Executes a function within a Flow context (AsyncLocalStorage). All pipe() calls inside will use this context. */
+  run: runInContext,
+  /** Returns the current Flow or throws — use in code that must run inside a managed context. */
+  require: requireContext,
+  /** Returns the current Flow or undefined — use for optional context detection. */
+  get: getContext,
+  /** Creates a Flow for test isolation with optional auth and tenant overrides. */
+  createTest: createTestContext,
+  /** Runs `fn` as a tenant and user chosen inside a tenantless Flow (sign-up, a public sign-in): RLS, audit and trace under that tenant, on the request's transaction. */
+  actAs,
+}

package/src/request/http/error-step.ts

@@ -0,0 +1,42 @@
+import { randomUUID } from 'node:crypto'
+import type { Flow } from '../context/index.js'
+import { ValidationError } from '../../core/errors/index.js'
+import { serializeForTrace } from '../../trace/capture/bounded-serializer.js'
+import { projectStepError } from '../../trace/runtime/step-error.js'
+
+export interface ErrorStepInfo {
+  readonly method: string
+  /** The route pattern (`/things/:id`), never the URL. */
+  readonly route: string
+  readonly status: number
+  readonly code: string
+  readonly error: unknown
+}
+
+/**
+ * Records one `http.error` step on the request's trace for an error response:
+ * method, route pattern, status, code and, for a ValidationError, each issue's
+ * source, path and message. Input values are never recorded. A no-op when the
+ * request has no trace (the error came before it opened, or tracing is off).
+ */
+export function recordErrorStep(ctx: Flow | undefined, info: ErrorStepInfo): void {
+  const trace = ctx?.trace
+  if (trace === undefined || trace === null) return
+  const meta: Record<string, unknown> = { method: info.method, route: info.route, status: info.status, code: info.code }
+  if (info.error instanceof ValidationError) {
+    meta['issues'] = info.error.issues.map(i => ({ source: i.source, path: [...i.path], message: i.message }))
+  }
+  const now = new Date()
+  const { name, message } = projectStepError(info.error)
+  trace.buffer.stageExternal({
+    id: randomUUID(),
+    parentStepId: trace.buffer.openStepId,
+    flowStepRef: 'http.error',
+    status: 'error',
+    startedAt: now,
+    completedAt: now,
+    durationMicros: 0n,
+    capturedInputs: null,
+    error: { name, message: serializeForTrace(message) as string, stack: null, detail: serializeForTrace(meta) },
+  })
+}