pipework 0.285.0 → 0.286.0

package/src/data/db/filter.ts

@@ -5,9 +5,9 @@ import {
 } from '../query/index.js'
 import { countAgg, countDistinctAgg, sumAgg, sumDistinctAgg, avgAgg, avgDistinctAgg, maxAgg, minAgg, boolAnd, boolOr, arrayAgg, stringAgg, jsonbAgg, jsonbObjectAgg, jsonbBuildObject } from './aggregates.js'
 import { except, exceptAll, intersect, intersectAll, union, unionAll } from '../query/pg-core/index.js'
-import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
+import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayOf, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
 import { ago, castUuid, castJsonb, castTimestamp, castBoolean, castNumeric, castInteger, castText, nextSequence } from './composed.js'
-import { json as jsonbExtract, pathText as jsonbExtractText, contains as jsonbContains, merge as jsonbMerge, remove as jsonbRemove } from '../jsonb/query.js'
+import { json as jsonbExtract, pathText as jsonbExtractText, contains as jsonbContains, merge as jsonbMerge, concat as jsonbConcat, remove as jsonbRemove } from '../jsonb/query.js'
 import { arrayAny, arrayAll, jsonbElements } from './array-elements.js'
 import { inList, notInList } from './in-list.js'
 
@@ -56,6 +56,7 @@ export const filter = {
   arraySlice,
   arrayToString,
   arrayAppend,
+  arrayOf,
   arrayRemove,
   dateTrunc,
   rowNumber,
@@ -81,6 +82,7 @@ export const filter = {
   jsonbExtractText,
   jsonbContains,
   jsonbMerge,
+  jsonbConcat,
   jsonbRemove,
   arrayAny,
   arrayAll,

package/src/data/jsonb/namespace.ts

@@ -1,4 +1,4 @@
-import { contains, merge, remove, containedBy, hasKey, text, json, path, pathText } from './query.js'
+import { contains, merge, concat, remove, containedBy, hasKey, text, json, path, pathText } from './query.js'
 import { boolean, number, integer } from './composed.js'
 
 /** JSONB query operators — typed helpers for PostgreSQL JSONB containment, key checks, and field extraction. */
@@ -7,6 +7,8 @@ export const jsonb = {
   contains,
   /** Merges an object into a JSONB column in `.set()`: `coalesce(col, '{}') || value`. Top-level keys overwrite; others are kept. */
   merge,
+  /** Appends to a JSONB column in `.set()`: `col || $1::jsonb`, value bound as jsonb. An array appends its elements; a null column stays null. */
+  concat,
   /** Removes top-level keys from a JSONB column in `.set()`: `col - 'key'`. Composes as the column of `jsonb.merge`. */
   remove,
   /** The <@ contained-by operator — tests whether a JSONB column is contained by the given value. */

package/src/data/jsonb/query.ts

@@ -43,6 +43,25 @@ export function pathText(column: Column | SQL, ...keys: string[]): SQL<string> {
   return text(intermediate, finalKey)
 }
 
+/**
+ * Appends to a JSONB column for `.set()`, typically in `onConflictDoUpdate`: `col || $1::jsonb`, with `value`
+ * serialized and bound as jsonb. Appending an array to an array column adds its elements (`[1] || [2]` is `[1, 2]`);
+ * an object merges its top-level keys. The append happens in the statement, so concurrent upserts each
+ * add their element and none is lost. A null column stays null (SQL `||`): seed the column on insert, or
+ * wrap it in `coalesce(col, '[]'::jsonb)`.
+ */
+export function concat(column: Column | SQL, value: unknown): SQL {
+  const json: unknown = JSON.stringify(value)
+  if (typeof json !== 'string') {
+    throw new Error(
+      '[pipework] jsonb.concat() needs a JSON-serializable value, got ' + typeof value + '.\n\n' +
+      '  undefined, functions and symbols have no JSON form.\n' +
+      "  Fix: pass a value JSON can hold: jsonb.concat(col, [{ id: 1 }]).\n",
+    )
+  }
+  return sql`(${column} || ${json}::jsonb)`
+}
+
 /**
  * Merges `value` into a JSONB column for `.set()`: `coalesce(col, '{}'::jsonb) || value::jsonb`. Top-level keys
  * in `value` overwrite; others are kept; a null column becomes `value`. The merge happens in the statement,
@@ -57,7 +76,7 @@ export function merge(column: Column | SQL, value: Record<string, unknown>): SQL
       "  Fix: pass an object: jsonb.merge(col, { key: 'value' }).\n",
     )
   }
-  return sql`coalesce(${column}, '{}'::jsonb) || ${JSON.stringify(value)}::jsonb`
+  return sql`(coalesce(${column}, '{}'::jsonb) || ${JSON.stringify(value)}::jsonb)`
 }
 
 /**
@@ -81,6 +100,6 @@ export function remove(column: Column | SQL, ...keys: string[]): SQL {
       )
     }
   }
-  if (keys.length === 1) return sql`${column} - ${keys[0]!}::text`
-  return sql`${column} - array[${sql.join(keys.map(k => sql`${k}`), sql`, `)}]::text[]`
+  if (keys.length === 1) return sql`(${column} - ${keys[0]!}::text)`
+  return sql`(${column} - array[${sql.join(keys.map(k => sql`${k}`), sql`, `)}]::text[])`
 }

package/src/index.ts

@@ -21,7 +21,7 @@ export type { TimeoutOptions } from './data/db/timeouts.js'
 // sanctioned door to a raw connection; keeps the WRAPPED_PACKAGES postgres ban airtight.
 export { tap } from './data/db/pool.js'
 export type { ManagedConnection, ConnectOptions } from './data/db/pool.js'
-export type { StatementObserver, StatementEvent, StatementSettledObserver, StatementSettledEvent, StatementSettledError } from './core/config/statement-observer.js'
+export type { StatementObserver, StatementEvent, StatementSettledObserver, StatementSettledEvent, StatementSettledError, StatementSettledFeed } from './core/config/statement-observer.js'
 
 export type { DefinedTable, ExternalTable, DomainDefinition, DefinitionMethods, FieldDescriptor, FieldModifiers, FieldMeta, DefineOptions,
   FactoryBuilder, FactoryOptions, TraitDefinition, FieldColumn, ProjectedColumns,

package/src/infra/alerts/index.ts

@@ -10,3 +10,4 @@ export type { AlertsHttpOptions } from './http.js'
 export { clientFaults } from './client-faults.js'
 export type { ClientFaultsOptions, ClientFaultReport } from './client-faults.js'
 export type { RequestFaultsOptions } from './request-faults.js'
+export type { StatementTimingOptions, StatementTimingSource } from './statement-sources.js'

package/src/infra/alerts/namespace.ts

@@ -8,6 +8,7 @@ import { recordFault, recordFaultFor, useFaultTarget, faultsSource } from './fau
 import { recordBeatFor } from './beat.js'
 import { deliveryFailedSource, webhookFailedSource, creditsSource } from './subsystem-sources.js'
 import { emailSource, storageSource, accessLinksSource, lockoutsSource } from './infra-sources.js'
+import { statementTimingSource } from './statement-sources.js'
 import { schedulesSource, stepsSource, pipelinesSource, tracesSource } from './async-sources.js'
 
 /** Alerts namespace — raise and resolve keyed conditions, grouped, delivered to sinks through an outbox, traced. */
@@ -75,6 +76,8 @@ export const alerts = {
     traces: tracesSource,
     /** Raises `fault:<kind>` per kind of swallowed failure recorded by `recordFault` since the last tick (the pipework subsystems record audit-write, quota-record, credits-callback, trace-steps-lost, queue-* and scheduler faults). `kinds` limits it. */
     faults: faultsSource,
+    /** Raises `statement-slow:<label>` while the p90 of a `pipe.labelled` label's last `window` settled statements is over that label's budget; give the returned source to `observability.statementTiming` too. */
+    statementTiming: statementTimingSource,
     /** Raises `loop-stalled:<name>` while a background loop (scheduler, reaper, claim loop, support drain) has not run or succeeded within its allowance; the tick itself is covered by `pipework alerts stale`. */
     loopStalled: loopStalledSource,
   },

package/src/infra/alerts/statement-sources.ts

@@ -0,0 +1,94 @@
+// An alert source over settled statements: per `pipe.labelled` label, the p90 of its last N durations against a budget.
+
+import type { StatementSettledEvent, StatementSettledFeed } from '../../core/config/statement-observer.js'
+import type { AlertSeverity } from './handle.js'
+import type { AlertCondition, AlertSource } from './sources.js'
+
+export interface StatementTimingOptions {
+  /** Budget in ms per label: `{ 'gate-read': 1000 }`. A label not named here is never recorded. At least one. */
+  readonly budgets: Readonly<Record<string, number>>
+  /** N: statements per label the p90 is taken over. The source stays quiet for a label until N have settled. */
+  readonly window: number
+  /** Default `warning`, as the backlog source. */
+  readonly severity?: AlertSeverity
+  readonly owner?: string
+  readonly runbook?: string
+}
+
+/** What `alerts.source.statementTiming` returns: an `AlertSource` that is also passed as `observability.statementTiming`. */
+export type StatementTimingSource = AlertSource & StatementSettledFeed
+
+interface Ring { readonly samples: number[]; next: number }
+
+/** Nearest rank: the smallest sample that at least 90% of the samples are at or under. */
+function p90(samples: readonly number[]): number {
+  const sorted = [...samples].sort((a, b) => a - b)
+  return sorted[Math.ceil(sorted.length * 0.9) - 1]!
+}
+
+/**
+ * Raises `statement-slow:<label>` while the p90 duration of a label's last `window` settled statements is over
+ * that label's budget; resolves when it is back under. Statements are fed in-process by
+ * `observability.statementTiming` (pass the returned source there as well as to `alerts.create({ sources })`;
+ * the app's own `onStatementSettled` still fires). Only the labels in `budgets` are recorded, each in a ring of
+ * `window` numbers, so memory is bounded by `window` times the labels named; unlabelled statements and other
+ * labels are ignored. Failed statements count, with the time they took. The window is this process's: a tick sees
+ * only statements that settled in its own process, and a label that stops being called keeps its last window.
+ * Context carries `label`, `p90Ms`, `window` and `budgetMs`.
+ */
+export function statementTimingSource(options: StatementTimingOptions): StatementTimingSource {
+  const who = 'alerts.source.statementTiming'
+  if (!Number.isInteger(options.window) || options.window < 1) {
+    throw new Error(`[pipework] ${who} window must be a positive integer number of statements, got ${String(options.window)}.`)
+  }
+  const entries = Object.entries(options.budgets)
+  if (entries.length === 0) throw new Error(`[pipework] ${who} needs budgets: at least one label and its budget in ms.`)
+  const budgets = new Map<string, number>()
+  for (const [label, budget] of entries) {
+    if (label === '') throw new Error(`[pipework] ${who} budgets: a label must not be empty.`)
+    if (typeof budget !== 'number' || !Number.isFinite(budget) || budget <= 0) {
+      throw new Error(`[pipework] ${who} budget for "${label}" must be a positive number of milliseconds, got ${String(budget)}.`)
+    }
+    budgets.set(label, budget)
+  }
+  const size = options.window
+  const severity = options.severity ?? 'warning'
+  const rings = new Map<string, Ring>()
+  let attached = false
+  const prefix = 'statement-slow:'
+
+  return {
+    name: 'statement-slow',
+    owns: key => key.startsWith(prefix),
+    observe(event: StatementSettledEvent): void {
+      if (event.label === null || !budgets.has(event.label)) return
+      let ring = rings.get(event.label)
+      if (ring === undefined) { ring = { samples: [], next: 0 }; rings.set(event.label, ring) }
+      if (ring.samples.length < size) ring.samples.push(event.durationMs)
+      else { ring.samples[ring.next] = event.durationMs; ring.next = (ring.next + 1) % size }
+    },
+    attach(): void { attached = true },
+    evaluate(): Promise<AlertCondition[]> {
+      if (!attached) {
+        return Promise.reject(new Error(`[pipework] ${who} was never given to the blueprint: set observability.statementTiming to this source, or it sees no statements.`))
+      }
+      const out: AlertCondition[] = []
+      for (const [label, budget] of budgets) {
+        const ring = rings.get(label)
+        if (ring === undefined || ring.samples.length < size) continue
+        const value = p90(ring.samples)
+        if (value <= budget) continue
+        out.push({
+          key: `${prefix}${label}`,
+          severity,
+          message: `p90 of the last ${String(size)} "${label}" statements is ${String(value)} ms, over its ${String(budget)} ms budget`,
+          subject: { entity: 'statement-label', entityId: label },
+          ...(options.owner !== undefined ? { owner: options.owner } : {}),
+          ...(options.runbook !== undefined ? { runbook: options.runbook } : {}),
+          context: { label, p90Ms: value, window: size, budgetMs: budget },
+        })
+      }
+      return Promise.resolve(out)
+    },
+  }
+}