@owlmeans/planning-postgres 0.1.18-rc.0

package/src/service.ts

@@ -0,0 +1,45 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { WithPlanningService } from '@owlmeans/planning'
+import { DEFAULT_ALIAS, makePlanningService } from '@owlmeans/server-planning'
+import type { PlanningHostService } from '@owlmeans/server-planning'
+import { makePlanningPostgresResources } from './resource.js'
+import { makePostgresPlanningStore, planningPostgresAliases } from './store/index.js'
+import type { PostgresPlanningServiceOptions } from './types.js'
+
+/**
+ * The planning service over a Postgres store — what a target's own `services/planning.ts`
+ * exports as its `makeService()`. The store resolves its four resources on the service's context
+ * at the first call, so the resources are registered separately (`resources/planning/*.ts`).
+ */
+export const makePostgresPlanningService = (
+  opts: PostgresPlanningServiceOptions = {}, alias: string = DEFAULT_ALIAS
+): PlanningHostService => {
+  const { aliases, bus, limits, ...service } = opts
+  let host: PlanningHostService | undefined
+  const store = makePostgresPlanningStore({
+    aliases, bus, limits, ids: opts.ids, now: opts.now,
+    context: () => host?.ctx as BasicContext<any> | undefined,
+  })
+  host = makePlanningService({ ...service, store }, alias)
+
+  return host
+}
+
+/**
+ * Register the four Postgres resources (each unless the context already has it), the planning
+ * service over them, and `context.planning()` — the one-call wiring of a hand-written backend.
+ */
+export const appendPostgresPlanning = <C extends BasicConfig, T extends BasicContext<C>>(
+  ctx: T, opts: PostgresPlanningServiceOptions = {}, alias: string = DEFAULT_ALIAS
+): T & WithPlanningService => {
+  const context = ctx as T & WithPlanningService
+  for (const resource of makePlanningPostgresResources(planningPostgresAliases(opts.aliases))) {
+    if (!context.hasResource(resource.alias)) {
+      context.registerResource(resource)
+    }
+  }
+  context.registerService(makePostgresPlanningService(opts, alias))
+  context.planning = () => context.service<PlanningHostService>(alias)
+
+  return context
+}

package/src/sql.ts

@@ -0,0 +1,135 @@
+import { quoteIdent, rowToRecord } from '@owlmeans/postgres-resource'
+import type { ColumnSpec, TableSpec } from '@owlmeans/postgres-resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { Pool, PoolClient, QueryResultRow } from 'pg'
+
+/** Where a statement runs — the pool, or one open transaction. */
+export interface SqlRunner {
+  query: <R extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<R[]>
+}
+
+/** The compiled specs of the four tables, read once the resources have initialized. */
+export interface PlanningTables {
+  card: TableSpec
+  transition: TableSpec
+  link: TableSpec
+  schema: TableSpec
+}
+
+/** A runner and the tables it addresses — what every statement builder takes. */
+export interface SqlContext {
+  runner: SqlRunner
+  tables: PlanningTables
+}
+
+export const poolRunner = (pool: Pool): SqlRunner => ({
+  query: async <R extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) =>
+    (await pool.query<R>(text, params as never[])).rows,
+})
+
+export const clientRunner = (client: PoolClient, onError?: (error: unknown) => void): SqlRunner => ({
+  query: async <R extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
+    try {
+      return (await client.query<R>(text, params as never[])).rows
+    } catch (error) {
+      onError?.(error)
+      throw error
+    }
+  },
+})
+
+/** A property's physical column, quoted. */
+export const col = (spec: TableSpec, property: string): string => quoteIdent(spec.byProperty[property].column)
+
+/** A value as the driver takes it for a column: JSON text for jsonb, `null` for absent. */
+export const driverValue = (column: ColumnSpec, value: unknown): unknown => {
+  if (value === undefined || value === null) {
+    return null
+  }
+  // node-postgres would write a JS array as a Postgres array literal, which a jsonb column refuses.
+  return column.jsonb ? JSON.stringify(value) : value
+}
+
+/**
+ * A row back as a record: physical columns to properties with the package's coercions, `null`
+ * dropped (the planning records leave an absent value out), private columns removed.
+ */
+export const recordOf = <T extends ResourceRecord>(
+  row: Record<string, unknown>, spec: TableSpec, hidden: readonly string[] = []
+): T => {
+  const record = rowToRecord<T>(row, spec) as Record<string, unknown>
+  for (const [key, value] of Object.entries(record)) {
+    if (value === null || hidden.includes(key)) {
+      delete record[key]
+    }
+  }
+  return record as T
+}
+
+/** A resource read answered with drizzle's property-keyed rows: `null` and private keys dropped. */
+export const cleanRecord = <T extends object>(record: T, hidden: readonly string[] = []): T =>
+  Object.fromEntries(Object.entries(record).filter(([key, value]) => value !== null && value !== undefined && !hidden.includes(key))) as T
+
+export interface InsertStatement {
+  text: string
+  params: unknown[]
+}
+
+/**
+ * `INSERT INTO <table> (<every column but the skipped>) VALUES (…)` for a record, with an optional
+ * tail (`ON CONFLICT …`, `RETURNING …`).
+ */
+export const insertOf = (
+  spec: TableSpec, record: Record<string, unknown>, opts: { skip?: readonly string[], tail?: string, as?: string } = {}
+): InsertStatement => {
+  const columns = spec.columns.filter(column => !(opts.skip ?? []).includes(column.property))
+  const params = columns.map(column => driverValue(column, record[column.property]))
+
+  return {
+    text: `INSERT INTO ${spec.qualified}${opts.as != null ? ` AS ${opts.as}` : ''}`
+      + ` (${columns.map(column => quoteIdent(column.column)).join(', ')})`
+      + ` VALUES (${columns.map((_, index) => `$${index + 1}`).join(', ')})${opts.tail != null ? ` ${opts.tail}` : ''}`,
+    params,
+  }
+}
+
+/**
+ * A WHERE over fixed fields: a string is equality, a list is `= ANY`, `undefined` is skipped.
+ * Parameters start after `offset`.
+ */
+export const whereOf = (
+  spec: TableSpec, fields: Record<string, string | readonly string[] | undefined>, offset: number = 0
+): { text: string, params: unknown[] } => {
+  const clauses: string[] = []
+  const params: unknown[] = []
+  for (const [property, value] of Object.entries(fields)) {
+    if (value === undefined) {
+      continue
+    }
+    params.push(Array.isArray(value) ? [...value] : value)
+    clauses.push(Array.isArray(value)
+      ? `${col(spec, property)} = ANY($${offset + params.length})`
+      : `${col(spec, property)} = $${offset + params.length}`)
+  }
+
+  return { text: clauses.length > 0 ? clauses.join(' AND ') : 'TRUE', params }
+}
+
+/** The driver error's Postgres code and the constraint (index) it names, through a `cause` chain. */
+export const pgFault = (error: unknown): { code?: string, constraint?: string } => {
+  let current: unknown = error
+  for (let depth = 0; depth < 5 && current != null && typeof current === 'object'; depth++) {
+    const candidate = current as { code?: unknown, constraint?: unknown, cause?: unknown }
+    if (typeof candidate.code === 'string' && /^[0-9A-Z]{5}$/.test(candidate.code)) {
+      return {
+        code: candidate.code,
+        ...(typeof candidate.constraint === 'string' ? { constraint: candidate.constraint } : {}),
+      }
+    }
+    current = candidate.cause
+  }
+  return {}
+}
+
+export const UNIQUE_VIOLATION = '23505'
+export const LOCK_NOT_AVAILABLE = '55P03'

package/src/store/bus.ts

@@ -0,0 +1,217 @@
+import type { CommitEvent, Unsubscribe } from '@owlmeans/planning'
+import { advisoryKey, quoteIdent } from '@owlmeans/postgres-resource'
+import { Client } from 'pg'
+import type { ClientConfig, Notification, Pool } from 'pg'
+import { BUS_BACKOFF, NOTIFY_PAYLOAD_MAX } from '../consts.js'
+import type { SqlRunner } from '../sql.js'
+
+/** A settled commit, without its record — the card is re-read where one is needed. */
+export interface CommitFrame {
+  p: string
+  t: 'c'
+  e: Omit<CommitEvent, 'record'>
+}
+
+/** A write of an organization's data-defined schemas. */
+export interface SchemaFrame {
+  p: string
+  t: 's'
+  e: string
+}
+
+export type BusFrame = CommitFrame | SchemaFrame
+
+export interface PlanningBus {
+  enabled: boolean
+  /** NOTIFY a frame inside a transaction — delivered only if it commits. A no-op when disabled. */
+  notify: (runner: SqlRunner, frame: Omit<CommitFrame, 'p'> | Omit<SchemaFrame, 'p'>) => Promise<void>
+  onCommit: (listener: (event: CommitEvent) => void | Promise<void>) => Unsubscribe
+  onSchema: (listener: (entityId: string) => void) => Unsubscribe
+  /** Open the LISTEN connection if it is not open (lazily, on the first subscription or wait). */
+  ensure: () => void
+  connected: () => boolean
+  close: () => Promise<void>
+}
+
+export interface PlanningBusOptions {
+  enabled: boolean
+  processId: string
+  /** The qualified transition table — what the channel name is derived from. */
+  table: () => Promise<string>
+  /** The pool whose configuration the dedicated connection copies. */
+  pool: () => Promise<Pool>
+}
+
+/**
+ * The channel of one transition table: `planning_` and a short hash of its qualified name, so two
+ * schemas in one database never hear each other.
+ */
+export const planningChannel = (qualified: string): string => {
+  const [first, second] = advisoryKey(`planning-channel:${qualified}`)
+  return `planning_${(first >>> 0).toString(16).padStart(8, '0')}${(second >>> 0).toString(16).padStart(8, '0')}`
+}
+
+const payloadOf = (frame: BusFrame): string | null => {
+  const text = JSON.stringify(frame)
+  if (new TextEncoder().encode(text).length < NOTIFY_PAYLOAD_MAX) {
+    return text
+  }
+  if (frame.t === 'c' && frame.e.error != null) {
+    // The reason is in the row; a listener reads it with the status.
+    const { error: _error, ...event } = frame.e
+    return payloadOf({ ...frame, e: event })
+  }
+  return null
+}
+
+/**
+ * The cross-process commit bus over LISTEN/NOTIFY.
+ *
+ * NOTIFY runs inside the transaction that settled the commit, so a frame is heard only if that
+ * commit landed. LISTEN holds ONE dedicated connection — a `pg.Client` built from the pool's own
+ * configuration, never a pooled one, so it takes no pool slot — opened on the first subscription
+ * or wait. A dropped connection reconnects with backoff (1 s doubling to 30 s); meanwhile the commit
+ * hub's poll ladder still answers every waiter. A process ignores its own frames (`p`): it delivered
+ * them itself, after its commit.
+ */
+export const makePlanningBus = (opts: PlanningBusOptions): PlanningBus => {
+  const commitListeners = new Set<(event: CommitEvent) => void | Promise<void>>()
+  const schemaListeners = new Set<(entityId: string) => void>()
+  let client: Client | undefined
+  let connecting: Promise<void> | undefined
+  let retry: ReturnType<typeof setTimeout> | undefined
+  let backoff = BUS_BACKOFF[0]
+  let closed = false
+  let live = false
+  let channel: string | undefined
+
+  const channelOf = async (): Promise<string> => channel ??= planningChannel(await opts.table())
+
+  const dispatch = (message: Notification): void => {
+    if (message.channel !== channel || message.payload == null) {
+      return
+    }
+    let frame: BusFrame
+    try {
+      frame = JSON.parse(message.payload) as BusFrame
+    } catch {
+      return
+    }
+    if (frame.p === opts.processId) {
+      return
+    }
+    if (frame.t === 'c') {
+      for (const listener of [...commitListeners]) {
+        void Promise.resolve().then(() => listener(frame.e as CommitEvent))
+          .catch(error => console.error('planning-postgres: commit listener failed:', error))
+      }
+      return
+    }
+    if (frame.t === 's') {
+      for (const listener of [...schemaListeners]) {
+        try {
+          listener(frame.e)
+        } catch (error) {
+          console.error('planning-postgres: schema listener failed:', error)
+        }
+      }
+    }
+  }
+
+  const lost = (target: Client, error?: unknown): void => {
+    if (client !== target) {
+      return
+    }
+    client = undefined
+    live = false
+    void target.end().catch(() => undefined)
+    if (closed) {
+      return
+    }
+    if (error != null) {
+      console.warn('planning-postgres: commit bus connection lost, reconnecting:', error instanceof Error ? error.message : error)
+    }
+    retry = setTimeout(() => { retry = undefined; bus.ensure() }, backoff)
+    backoff = Math.min(backoff * 2, BUS_BACKOFF[1])
+  }
+
+  const connect = async (): Promise<void> => {
+    let pool: Pool
+    let listen: string
+    try {
+      pool = await opts.pool()
+      listen = await channelOf()
+    } catch {
+      // The store cannot reach its tables yet (its calls say why); ask again later.
+      if (!closed) {
+        retry = setTimeout(() => { retry = undefined; bus.ensure() }, backoff)
+        backoff = Math.min(backoff * 2, BUS_BACKOFF[1])
+      }
+      return
+    }
+    // The pool's own client class and configuration (the password stays a non-enumerable property
+    // of that object, so the object itself is handed over, never a copy).
+    const Factory = (pool as unknown as { Client?: typeof Client }).Client ?? Client
+    const target = new Factory(pool.options as ClientConfig)
+    target.on('error', error => lost(target, error))
+    target.on('end', () => lost(target))
+    target.on('notification', dispatch)
+    client = target
+    try {
+      await target.connect()
+      await target.query(`LISTEN ${quoteIdent(listen)}`)
+      live = true
+      backoff = BUS_BACKOFF[0]
+    } catch (error) {
+      lost(target, error)
+    }
+  }
+
+  const bus: PlanningBus = {
+    enabled: opts.enabled,
+
+    notify: async (runner, frame) => {
+      if (!opts.enabled) {
+        return
+      }
+      const payload = payloadOf({ ...frame, p: opts.processId } as BusFrame)
+      if (payload != null) {
+        await runner.query('SELECT pg_notify($1, $2)', [await channelOf(), payload])
+      }
+    },
+
+    onCommit: listener => {
+      commitListeners.add(listener)
+      return () => { commitListeners.delete(listener) }
+    },
+
+    onSchema: listener => {
+      schemaListeners.add(listener)
+      return () => { schemaListeners.delete(listener) }
+    },
+
+    ensure: () => {
+      if (!opts.enabled || closed || client != null || connecting != null || retry != null) {
+        return
+      }
+      connecting = connect().finally(() => { connecting = undefined })
+    },
+
+    connected: () => live,
+
+    close: async () => {
+      closed = true
+      if (retry != null) {
+        clearTimeout(retry)
+        retry = undefined
+      }
+      await connecting?.catch(() => undefined)
+      const target = client
+      client = undefined
+      live = false
+      await target?.end().catch(() => undefined)
+    },
+  }
+
+  return bus
+}

package/src/store/cards.ts

@@ -0,0 +1,153 @@
+import { IntrinsicStatus, PlanningError, WorkcardKind } from '@owlmeans/planning'
+import type { ProjectionStore, SummaryView, Workcard } from '@owlmeans/planning'
+import { quoteIdent } from '@owlmeans/postgres-resource'
+import type { Criteria } from '@owlmeans/resource'
+import { wantsSpecifications } from '@owlmeans/server-planning/store'
+import { PlanningPostgresError } from '../errors.js'
+import { cleanRecord, col, driverValue, insertOf, recordOf } from '../sql.js'
+import type { SqlContext } from '../sql.js'
+import type { PlanningCardRecord, PlanningCardResource } from '../types.js'
+
+/** Columns no caller ever sees. */
+export const CARD_PRIVATE = ['headAt'] as const
+
+const and = (where: Criteria<Workcard> | undefined, ...extra: Criteria<Workcard>[]): Criteria<Workcard> => {
+  const base = (where ?? {}) as Criteria<Workcard> & { $and?: Criteria<Workcard>[] }
+  return { ...base, $and: [...(base.$and ?? []), ...extra] } as Criteria<Workcard>
+}
+
+const NOT_SPECIFICATION = { kind: { $ne: WorkcardKind.Specification } } as Criteria<Workcard>
+
+/** A card list names specifications only when it asks for them — the rule every store keeps. */
+export const routedCriteria = (where?: Criteria<Workcard>): Criteria<Workcard> =>
+  wantsSpecifications(where) ? (where ?? {}) as Criteria<Workcard> : and(where, NOT_SPECIFICATION)
+
+/** A card row with its private bookkeeping (what the fold reads), or `null`. */
+export const readCardRow = async (sql: SqlContext, id: string, entityId?: string): Promise<PlanningCardRecord | null> => {
+  const spec = sql.tables.card
+  const rows = await sql.runner.query(
+    `SELECT * FROM ${spec.qualified} WHERE ${col(spec, 'id')} = $1${entityId != null ? ` AND ${col(spec, 'entityId')} = $2` : ''}`,
+    entityId != null ? [id, entityId] : [id]
+  )
+  return rows[0] == null ? null : recordOf<PlanningCardRecord>(rows[0], spec)
+}
+
+export const readCard = async (sql: SqlContext, id: string, entityId: string): Promise<Workcard | null> => {
+  const row = await readCardRow(sql, id, entityId)
+  return row == null ? null : cleanRecord(row, CARD_PRIVATE)
+}
+
+/**
+ * Write a folded card whole. `head` is never lowered — an allocation made while the fold ran stays
+ * — and `headAt` is never touched.
+ *
+ * A create (`seq` 1) is an upsert. Anything later is an UPDATE of a row that must still exist: a
+ * card purged with its project while one of its own transitions was folding is not resurrected.
+ *
+ * @throws {PlanningPostgresError} `fold:card-vanished:<id>`
+ */
+export const writeCard = async (sql: SqlContext, card: Workcard): Promise<void> => {
+  const spec = sql.tables.card
+  if (card.id == null) {
+    throw new PlanningPostgresError('malformed:put-without-id')
+  }
+  const record = { ...card, head: Math.max(card.head ?? card.seq, card.seq) } as Record<string, unknown>
+  const head = col(spec, 'head')
+  const seq = col(spec, 'seq')
+  const assigned = spec.columns
+    .filter(column => !['id', 'headAt', 'head'].includes(column.property))
+    .map(column => column.column)
+
+  if (card.seq <= 1) {
+    const insert = insertOf(spec, record, {
+      skip: CARD_PRIVATE,
+      as: 'existing',
+      tail: `ON CONFLICT (${col(spec, 'id')}) DO UPDATE SET `
+        + [...assigned.map(name => `${quoteIdent(name)} = EXCLUDED.${quoteIdent(name)}`),
+          `${head} = GREATEST(COALESCE(existing.${head}, existing.${seq}), EXCLUDED.${head})`].join(', '),
+    })
+    await sql.runner.query(insert.text, insert.params)
+    return
+  }
+
+  const columns = spec.columns.filter(column => assigned.includes(column.column))
+  const params = [card.id, ...columns.map(column => driverValue(column, record[column.property])), record.head]
+  const updated = await sql.runner.query(
+    `UPDATE ${spec.qualified} SET ${columns.map((column, index) => `${quoteIdent(column.column)} = $${index + 2}`).join(', ')},`
+    + ` ${head} = GREATEST(COALESCE(${head}, ${seq}), $${columns.length + 2}) WHERE ${col(spec, 'id')} = $1 RETURNING ${col(spec, 'id')}`,
+    params
+  )
+  if (updated.length === 0) {
+    throw new PlanningPostgresError(`fold:card-vanished:${card.id}`)
+  }
+}
+
+export const dropCard = async (sql: SqlContext, id: string, entityId: string): Promise<void> => {
+  const spec = sql.tables.card
+  await sql.runner.query(
+    `DELETE FROM ${spec.qualified} WHERE ${col(spec, 'id')} = $1 AND ${col(spec, 'entityId')} = $2`, [id, entityId]
+  )
+}
+
+const emptyCounts = () => ({
+  total: 0, [IntrinsicStatus.Planned]: 0, [IntrinsicStatus.InProgress]: 0, [IntrinsicStatus.Closed]: 0,
+})
+
+export interface CardPortDeps {
+  sql: () => Promise<SqlContext>
+  resource: () => PlanningCardResource
+  project: (card: string) => Promise<void>
+  purge: (project: string, entityId: string) => Promise<number>
+}
+
+/**
+ * The projection port. Point reads and writes are this package's own statements; lists, counts and
+ * summaries go through the resource, so a criteria means here what it means everywhere
+ * (`criteriaToSql`).
+ */
+export const makeCardPort = (deps: CardPortDeps): ProjectionStore => ({
+  get: async (id, entityId) => await readCard(await deps.sql(), id, entityId),
+
+  list: async (where, opts) => {
+    await deps.sql()
+    const listed = await deps.resource().list(routedCriteria(where) as Criteria<PlanningCardRecord>, opts as never)
+    return { ...listed, items: listed.items.map(item => cleanRecord(item, CARD_PRIVATE) as Workcard) }
+  },
+
+  count: async where => {
+    await deps.sql()
+    return await deps.resource().count(routedCriteria(where) as Criteria<PlanningCardRecord>)
+  },
+
+  summary: async (parents, where) => {
+    if (parents.length === 0) {
+      return {}
+    }
+    await deps.sql()
+    const rows = await deps.resource().countBy(
+      and(where, NOT_SPECIFICATION, { parent: parents } as Criteria<Workcard>) as Criteria<PlanningCardRecord>,
+      ['parent', 'intrinsic']
+    )
+    return rows.reduce<SummaryView>((view, row) => {
+      const parent = row.parent as string
+      const counts = view[parent] ?? emptyCounts()
+      counts.total += row.count
+      counts[row.intrinsic as IntrinsicStatus] = (counts[row.intrinsic as IntrinsicStatus] ?? 0) + row.count
+      view[parent] = counts
+      return view
+    }, {})
+  },
+
+  put: async card => { await writeCard(await deps.sql(), card) },
+
+  drop: async (id, entityId) => { await dropCard(await deps.sql(), id, entityId) },
+
+  project: async card => { await deps.project(card) },
+
+  purge: async (project, entityId) => {
+    if (project == null || project === '') {
+      throw new PlanningError('purge:empty')
+    }
+    return await deps.purge(project, entityId)
+  },
+})