pipework 0.252.0 → 0.253.0

package/src/core/logging/error-chain.ts

@@ -0,0 +1,68 @@
+/** One error in a cause chain: its class name, message, and the Postgres error fields it carries. */
+export interface ErrorLink {
+  readonly type: string
+  readonly message: string
+  readonly code?: string
+  readonly detail?: string
+  readonly constraint_name?: string
+  readonly table_name?: string
+  readonly column_name?: string
+}
+
+export interface ErrorDescription {
+  /** The error's message, then `: <message>` for each cause whose text it does not already hold; at most 2000 characters. */
+  readonly message: string
+  /** The causes under the error, outermost first, at most 5 deep; never the error itself. */
+  readonly chain: readonly ErrorLink[]
+}
+
+const MAX_DEPTH = 5
+const MAX_MESSAGE = 2000
+const MAX_LINK_MESSAGE = 500
+const PG_FIELDS = ['code', 'detail', 'constraint_name', 'table_name', 'column_name'] as const
+
+const cap = (text: string, max: number): string => (text.length <= max ? text : `${text.slice(0, max - 1)}…`)
+
+function messageOf(value: unknown): string {
+  if (value instanceof Error) {
+    // Drizzle's message ends `\nparams: <values>`: the values are not part of why it failed.
+    const at = Object.hasOwn(value, 'params') ? value.message.indexOf('\nparams: ') : -1
+    return at === -1 ? value.message : value.message.slice(0, at)
+  }
+  if (typeof value === 'object' && value !== null && typeof (value as { message?: unknown }).message === 'string') return (value as { message: string }).message
+  return String(value)
+}
+
+function link(value: unknown): ErrorLink {
+  const type = typeof value === 'object' && value !== null ? ((value as { constructor?: { name?: string } }).constructor?.name ?? 'Object') : typeof value
+  const fields: Record<string, string> = {}
+  if (typeof value === 'object' && value !== null) {
+    for (const key of PG_FIELDS) {
+      const v = (value as Record<string, unknown>)[key]
+      if (typeof v === 'string' && v !== '') fields[key] = cap(v, MAX_LINK_MESSAGE)
+    }
+  }
+  return { type, message: cap(messageOf(value), MAX_LINK_MESSAGE), ...fields }
+}
+
+/**
+ * The message of a thrown value with its `cause` chain folded in, and the chain itself with each
+ * Postgres error's `code`, `detail`, `constraint_name`, `table_name` and `column_name`. Bounded in
+ * depth and size; a cause that points back up the chain ends it.
+ */
+export function describeError(err: unknown): ErrorDescription {
+  let message = messageOf(err)
+  const chain: ErrorLink[] = []
+  const seen = new Set<unknown>([err])
+  let current: unknown = err
+  while (chain.length < MAX_DEPTH && typeof current === 'object' && current !== null) {
+    const next = (current as { cause?: unknown }).cause
+    if (next === undefined || next === null || seen.has(next)) break
+    seen.add(next)
+    const l = link(next)
+    chain.push(l)
+    if (l.message !== '' && !message.includes(l.message)) message += `: ${l.message}`
+    current = next
+  }
+  return { message: cap(message, MAX_MESSAGE), chain }
+}

package/src/core/logging/index.ts

@@ -0,0 +1,5 @@
+export { createPipeworkLogger, getLogger, getBaseLogger, setLoggingConfig, DEFAULT_REDACT_PATHS } from './logger.js'
+export { log } from './proxy.js'
+export type { LoggerConfig, LogLevel, PipeworkLogger, LogNamespace, LoggingConfig, ContextField } from './types.js'
+export { describeError } from './error-chain.js'
+export type { ErrorLink, ErrorDescription } from './error-chain.js'

package/src/core/logging/logger.ts

@@ -0,0 +1,65 @@
+import pino from 'pino'
+import type { PipeworkLogger, LoggerConfig, LoggingConfig } from './types.js'
+import { getCorrelationFields } from './context.js'
+import { describeError } from './error-chain.js'
+
+export const DEFAULT_REDACT_PATHS: readonly string[] = [
+  'password',
+  'token',
+  'authorization',
+  '*.password',
+  '*.token',
+  '*.authorization',
+]
+
+/** Pino's standard `err` output, with the message carrying its causes' text and `cause` the chain (Postgres fields included). */
+export function serializeErrorForLog(err: unknown): unknown {
+  const out = pino.stdSerializers.err(err as Error) as unknown as Record<string, unknown>
+  if (!(err instanceof Error)) return out
+  const { message, chain } = describeError(err)
+  out['message'] = message
+  if (chain.length > 0) out['cause'] = chain
+  return out
+}
+
+const serializers = { err: serializeErrorForLog as (err: unknown) => unknown }
+
+let baseLogger: PipeworkLogger | null = null
+let loggingConfig: LoggingConfig | null = null
+
+export function createPipeworkLogger(
+  config: LoggerConfig = {},
+  stream?: { write(chunk: string): void },
+): PipeworkLogger {
+  const level = config.level ?? 'info'
+  const redact = config.redact ?? [...DEFAULT_REDACT_PATHS]
+
+  const pinoOpts: pino.LoggerOptions = { level, redact: redact as string[], serializers }
+
+  if (config.pretty === true) {
+    pinoOpts.transport = { target: 'pino-pretty', options: { colorize: true } }
+  }
+
+  baseLogger = (stream === undefined ? pino(pinoOpts) : pino(pinoOpts, stream)) as unknown as PipeworkLogger
+  return baseLogger
+}
+
+export function setLoggingConfig(config: LoggingConfig): void {
+  loggingConfig = config
+}
+
+export function getLoggingConfig(): LoggingConfig | null {
+  return loggingConfig
+}
+
+export function getLogger(): PipeworkLogger {
+  const base = baseLogger ?? (pino({ level: 'info', serializers }) as unknown as PipeworkLogger)
+  const fields = getCorrelationFields()
+
+  if (Object.keys(fields).length === 0) return base
+  return base.child(fields)
+}
+
+export function getBaseLogger(): PipeworkLogger {
+  return baseLogger ?? (pino({ level: 'info', serializers }) as unknown as PipeworkLogger)
+}

package/src/core/logging/namespace.ts

@@ -0,0 +1,16 @@
+import { log as logProxy } from './proxy.js'
+import { createPipeworkLogger, getLogger, getBaseLogger, setLoggingConfig, DEFAULT_REDACT_PATHS } from './logger.js'
+
+/** Structured logger (Pino) — auto-binds requestId, tenantId, userId, sessionId from ALS context on every log call. */
+export const log = Object.assign(logProxy, {
+  /** Creates a new PipeworkLogger instance with custom config (level, redaction, transport). */
+  create: createPipeworkLogger,
+  /** Returns the context-aware logger proxy (same as the log export itself). */
+  get: getLogger,
+  /** Returns the raw Pino logger without ALS context binding. */
+  getBase: getBaseLogger,
+  /** Sets global logging config (level, redaction paths, custom context fields). */
+  configure: setLoggingConfig,
+  /** Default redaction paths — password, secret, token, authorization, cookie, etc. */
+  REDACT_PATHS: DEFAULT_REDACT_PATHS,
+})

package/src/core/logging/proxy.ts

@@ -0,0 +1,22 @@
+import type { PipeworkLogger, LogNamespace } from './types.js'
+import { createPipeworkLogger, getLogger, getBaseLogger, setLoggingConfig, DEFAULT_REDACT_PATHS } from './logger.js'
+
+const target = {
+  create: createPipeworkLogger,
+  get: getLogger,
+  getBase: getBaseLogger,
+  configure: setLoggingConfig,
+  REDACT_PATHS: DEFAULT_REDACT_PATHS,
+} as unknown as LogNamespace
+
+export const log: LogNamespace = new Proxy(target, {
+  get(target, prop: string | symbol) {
+    if (Object.hasOwn(target, prop)) return (target as unknown as Record<string | symbol, unknown>)[prop]
+    const logger = getLogger()
+    const value = logger[prop as keyof PipeworkLogger]
+    if (typeof value === 'function') {
+      return (value as Function).bind(logger)
+    }
+    return value
+  },
+})

package/src/core/logging/redact-match.ts

@@ -0,0 +1,24 @@
+// Pino-compatible redact-path matching, factored out so the trace capture
+// serializer can honor the same configured paths the logger redacts.
+//
+// A path is dot-separated segments; a segment is a literal key or `*` (matches
+// any one key). Paths are anchored at the root and match the whole key-path —
+// the same semantics pino's `redact` option uses: `password` redacts a
+// top-level `password`, `*.password` redacts it exactly one level down.
+
+export type RedactMatcher = (keyPath: readonly string[]) => boolean
+
+/** Compile redact paths into a matcher over a value's key-path from the root. */
+export function compileRedactPaths(paths: readonly string[]): RedactMatcher {
+  const compiled = paths.map(path => path.split('.'))
+  return keyPath => compiled.some(pattern => segmentsMatch(pattern, keyPath))
+}
+
+function segmentsMatch(pattern: readonly string[], keyPath: readonly string[]): boolean {
+  if (pattern.length !== keyPath.length) return false
+  for (let i = 0; i < pattern.length; i++) {
+    const segment = pattern[i]!
+    if (segment !== '*' && segment !== keyPath[i]) return false
+  }
+  return true
+}

package/src/core/logging/types.ts

@@ -0,0 +1,47 @@
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
+
+export type ContextField = 'requestId' | 'tenantId' | 'userId' | 'sessionId' | 'traceId'
+
+export interface PipeworkLogger {
+  info(msg: string): void
+  info(obj: Record<string, unknown>, msg?: string): void
+  warn(msg: string): void
+  warn(obj: Record<string, unknown>, msg?: string): void
+  error(msg: string): void
+  error(obj: Record<string, unknown>, msg?: string): void
+  debug(msg: string): void
+  debug(obj: Record<string, unknown>, msg?: string): void
+  fatal(msg: string): void
+  fatal(obj: Record<string, unknown>, msg?: string): void
+  trace(msg: string): void
+  trace(obj: Record<string, unknown>, msg?: string): void
+  child(bindings: Record<string, unknown>): PipeworkLogger
+  silent: boolean
+}
+
+export interface LogNamespace extends PipeworkLogger {
+  create(config?: LoggerConfig): PipeworkLogger
+  get(): PipeworkLogger
+  getBase(): PipeworkLogger
+  configure(config: LoggingConfig): void
+  readonly REDACT_PATHS: readonly string[]
+}
+
+export interface LoggerConfig {
+  readonly level?: LogLevel
+  readonly pretty?: boolean
+  readonly slowQueryMs?: number
+  readonly redact?: readonly string[] | {
+    readonly paths: readonly string[]
+    readonly censor?: string
+    readonly remove?: boolean
+  }
+}
+
+export interface LoggingConfig {
+  readonly traceHeader?: string
+  readonly requestIdHeader?: string
+  readonly sessionHeader?: string
+  readonly authFields?: readonly string[]
+  readonly contextFields?: readonly ContextField[]
+}