@crombolo/data 0.11.0 → 0.13.1

package/src/setup.ts

@@ -0,0 +1,57 @@
+/**
+ * Whether a site still waits for its owner to set it up from the browser. Kept
+ * in the database, not in memory, so a restart can never reopen it.
+ */
+import type { Db } from './database.ts'
+import { Locks } from './locks.ts'
+import { insertSuperUser, type SeedAdmin, type SeedOptions } from './schema/seed.ts'
+
+export const SETUP_STATE_KEY = 'crombolo:setup'
+
+/** `none` is every database set up before this existed, or seeded with an administrator. */
+export type SetupState = 'pending' | 'complete' | 'none'
+
+export async function readSetupState(db: Db): Promise<SetupState> {
+  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
+    SETUP_STATE_KEY,
+  ])
+  const value = rows[0]?.value
+  return value === 'pending' || value === 'complete' ? value : 'none'
+}
+
+async function writeSetupState(db: Db, state: 'pending' | 'complete'): Promise<void> {
+  const now = db.dialect.now()
+  const updated = await db.query<{ key: string }>(
+    `UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ? RETURNING key`,
+    [state, SETUP_STATE_KEY],
+  )
+  if (updated.length === 0)
+    await db.exec(`INSERT INTO key_value (key, value, update_date) VALUES (?, ?, ${now})`, [
+      SETUP_STATE_KEY,
+      state,
+    ])
+}
+
+/** Opens setup on a database that has just been created with no administrator. */
+export function markSetupPending(db: Db): Promise<void> {
+  return writeSetupState(db, 'pending')
+}
+
+/**
+ * Creates the administrator and closes setup for good, or answers `closed` when
+ * it was already done. Under a lock, so two attempts at once cannot both win.
+ */
+export function completeSetup(
+  db: Db,
+  admin: SeedAdmin,
+  options: Pick<SeedOptions, 'hashPassword' | 'passwordConfig'>,
+): Promise<'created' | 'closed'> {
+  return db.locks.withLock(Locks.KeyValues, () =>
+    db.transaction(async (tx) => {
+      if ((await readSetupState(tx)) !== 'pending') return 'closed'
+      await insertSuperUser(tx, { ...options, admin })
+      await writeSetupState(tx, 'complete')
+      return 'created'
+    }),
+  )
+}

package/src/tree-invariants.ts

@@ -0,0 +1,167 @@
+/**
+ * What must hold of the content trees after any mix of concurrent writes: the
+ * check is a pure function over rows, and `loadTreeSnapshot` reads those rows.
+ */
+import { ObjectTypes, SystemNodes } from '@crombolo/core'
+import type { Db } from './database.ts'
+import { fromDbBool } from './dialect.ts'
+
+export interface TreeNode {
+  id: number
+  parentId: number
+  level: number
+  path: string
+  sortOrder: number
+  trashed: boolean
+  objectType: string
+}
+
+export interface TreeDocument {
+  nodeId: number
+  published: boolean
+}
+
+export interface TreeVersion {
+  id: number
+  nodeId: number
+  current: boolean
+  published: boolean
+}
+
+export interface TreeSnapshot {
+  nodes: readonly TreeNode[]
+  /** Rows of `document`, which media and members share with documents. */
+  documents: readonly TreeDocument[]
+  versions: readonly TreeVersion[]
+  /** Node ids with a `content` row. */
+  contentNodeIds: readonly number[]
+}
+
+export type TreeRule =
+  | 'orphan'
+  | 'path'
+  | 'level'
+  | 'trashed'
+  | 'sort-order'
+  | 'current-version'
+  | 'published-version'
+  | 'published-trashed'
+  | 'content-row'
+
+export interface TreeViolation {
+  nodeId: number
+  rule: TreeRule
+  detail: string
+}
+
+export const TREE_OBJECT_TYPES: readonly string[] = [ObjectTypes.Document, ObjectTypes.Media]
+
+const RECYCLE_BINS: ReadonlySet<number> = new Set([
+  SystemNodes.ContentRecycleBin,
+  SystemNodes.MediaRecycleBin,
+  SystemNodes.ElementRecycleBin,
+])
+
+/** Every broken rule in the trees of `objectTypes`; empty when they are consistent. */
+export function checkTreeInvariants(
+  snapshot: TreeSnapshot,
+  objectTypes: readonly string[] = TREE_OBJECT_TYPES,
+): TreeViolation[] {
+  const checked = new Set(objectTypes)
+  const byId = new Map(snapshot.nodes.map((node) => [node.id, node]))
+  const documents = new Map(snapshot.documents.map((doc) => [doc.nodeId, doc]))
+  const content = new Set(snapshot.contentNodeIds)
+  const versions = new Map<number, TreeVersion[]>()
+  for (const version of snapshot.versions) {
+    const list = versions.get(version.nodeId)
+    if (list) list.push(version)
+    else versions.set(version.nodeId, [version])
+  }
+  const violations: TreeViolation[] = []
+  const fail = (nodeId: number, rule: TreeRule, detail: string) =>
+    violations.push({ nodeId, rule, detail })
+  const siblings = new Map<string, number>()
+
+  for (const node of snapshot.nodes) {
+    if (!checked.has(node.objectType)) continue
+    const parent = byId.get(node.parentId)
+    if (!parent) {
+      fail(node.id, 'orphan', `parent ${node.parentId} does not exist`)
+      continue
+    }
+    const inBin = RECYCLE_BINS.has(parent.id)
+    const expected = `${parent.path},${node.id}`
+    if (node.path !== expected) fail(node.id, 'path', `path ${node.path}, expected ${expected}`)
+    if (node.level !== parent.level + 1)
+      fail(node.id, 'level', `level ${node.level}, expected ${parent.level + 1}`)
+    if ((inBin || parent.trashed) && !node.trashed)
+      fail(node.id, 'trashed', 'under the recycle bin but not trashed')
+    if (node.trashed && !inBin && !parent.trashed)
+      fail(node.id, 'trashed', 'trashed but its parent is not')
+
+    const slot = `${node.parentId}|${node.objectType}|${node.sortOrder}`
+    const holder = siblings.get(slot)
+    if (holder !== undefined)
+      fail(node.id, 'sort-order', `shares sort order ${node.sortOrder} with ${holder}`)
+    else siblings.set(slot, node.id)
+
+    const doc = documents.get(node.id)
+    if (!doc || !content.has(node.id)) {
+      fail(node.id, 'content-row', doc ? 'no content row' : 'no document row')
+      continue
+    }
+    const own = versions.get(node.id) ?? []
+    const current = own.filter((v) => v.current).length
+    if (own.length > 0 && current !== 1)
+      fail(node.id, 'current-version', `${current} current versions`)
+    if (doc.published) {
+      const published = own.filter((v) => v.published).length
+      if (published !== 1) fail(node.id, 'published-version', `${published} published versions`)
+      if (node.trashed) fail(node.id, 'published-trashed', 'published while trashed')
+    }
+  }
+  return violations
+}
+
+/** The rows `checkTreeInvariants` reads, for the trees of `objectTypes`. */
+export async function loadTreeSnapshot(
+  db: Db,
+  objectTypes: readonly string[] = TREE_OBJECT_TYPES,
+): Promise<TreeSnapshot> {
+  const marks = objectTypes.map(() => '?').join(', ')
+  const scoped = `SELECT id FROM node WHERE node_object_type IN (${marks})`
+  const [nodes, documents, versions, content] = await Promise.all([
+    db.query('SELECT id, parent_id, level, path, sort_order, trashed, node_object_type FROM node'),
+    db.query(`SELECT node_id, published FROM document WHERE node_id IN (${scoped})`, [
+      ...objectTypes,
+    ]),
+    db.query(
+      `SELECT cv.id, cv.node_id, cv.current, dv.published FROM content_version cv
+       LEFT JOIN document_version dv ON dv.id = cv.id WHERE cv.node_id IN (${scoped})`,
+      [...objectTypes],
+    ),
+    db.query(`SELECT node_id FROM content WHERE node_id IN (${scoped})`, [...objectTypes]),
+  ])
+  return {
+    nodes: nodes.map((row) => ({
+      id: Number(row.id),
+      parentId: Number(row.parent_id),
+      level: Number(row.level),
+      path: String(row.path),
+      sortOrder: Number(row.sort_order),
+      trashed: fromDbBool(row.trashed),
+      objectType: String(row.node_object_type).toLowerCase(),
+    })),
+    documents: documents.map((row) => ({
+      nodeId: Number(row.node_id),
+      published: fromDbBool(row.published),
+    })),
+    versions: versions.map((row) => ({
+      id: Number(row.id),
+      nodeId: Number(row.node_id),
+      current: fromDbBool(row.current),
+      published: fromDbBool(row.published),
+    })),
+    contentNodeIds: content.map((row) => Number(row.node_id)),
+  }
+}

package/src/url-options.ts

@@ -0,0 +1,61 @@
+/**
+ * How this site's URLs are built, as Umbraco's `HideTopLevelNodeFromPath`
+ * sets it. Synced from `schema/schema.toml` and changed in Settings; read by
+ * the published cache. docs/rendering.md, "URLs".
+ */
+import type { Db } from './database.ts'
+
+export const URL_OPTIONS_KEY = 'crombolo:urls'
+
+export interface UrlOptions {
+  /** Leave the top-level page's segment out of every path below it. Umbraco's default. */
+  hideTopLevel: boolean
+}
+
+export const DEFAULT_URL_OPTIONS: UrlOptions = { hideTopLevel: true }
+
+/** Whether two settings build the same URLs. Pure. */
+export const sameUrlOptions = (a: UrlOptions, b: UrlOptions): boolean =>
+  a.hideTopLevel === b.hideTopLevel
+
+/** A stored value read leniently: anything unreadable is the default. Pure. */
+export function parseUrlOptions(value: string | undefined): UrlOptions {
+  if (!value) return { ...DEFAULT_URL_OPTIONS }
+  try {
+    const parsed = JSON.parse(value) as Partial<UrlOptions>
+    return {
+      hideTopLevel:
+        typeof parsed.hideTopLevel === 'boolean'
+          ? parsed.hideTopLevel
+          : DEFAULT_URL_OPTIONS.hideTopLevel,
+    }
+  } catch {
+    return { ...DEFAULT_URL_OPTIONS }
+  }
+}
+
+export async function readUrlOptions(db: Db): Promise<UrlOptions> {
+  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
+    URL_OPTIONS_KEY,
+  ])
+  return parseUrlOptions(rows[0]?.value)
+}
+
+/** Stores the setting; answers what it was before. */
+export async function writeUrlOptions(db: Db, options: UrlOptions): Promise<UrlOptions> {
+  return db.transaction(async (tx) => {
+    const before = await readUrlOptions(tx)
+    const value = JSON.stringify({ hideTopLevel: options.hideTopLevel })
+    const now = tx.dialect.now()
+    const updated = await tx.query<{ key: string }>(
+      `UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ? RETURNING key`,
+      [value, URL_OPTIONS_KEY],
+    )
+    if (updated.length === 0)
+      await tx.exec(`INSERT INTO key_value (key, value, update_date) VALUES (?, ?, ${now})`, [
+        URL_OPTIONS_KEY,
+        value,
+      ])
+    return before
+  })
+}

package/src/workflow-store.ts

@@ -0,0 +1,114 @@
+/**
+ * The approval workflows as last synced from `schema/workflows/` (story 028),
+ * each with its version, so a running node reads them without the files and a
+ * sync can tell which changed. docs/workflows.md.
+ */
+import { type SchemaWorkflow, startStages } from '@crombolo/core'
+import type { Db } from './database.ts'
+import { ApprovalRepository } from './repositories/approvals.ts'
+
+export const WORKFLOWS_KEY = 'crombolo:workflows'
+
+export interface StoredWorkflow {
+  workflow: SchemaWorkflow
+  version: string
+}
+
+/** Stored workflows read leniently: anything unreadable is none. Pure. */
+export function parseStoredWorkflows(value: string | undefined): StoredWorkflow[] {
+  if (!value) return []
+  try {
+    const parsed = JSON.parse(value) as unknown
+    return Array.isArray(parsed)
+      ? parsed.filter(
+          (w): w is StoredWorkflow =>
+            !!w && typeof w === 'object' && 'workflow' in w && 'version' in w,
+        )
+      : []
+  } catch {
+    return []
+  }
+}
+
+export async function readWorkflows(db: Db): Promise<StoredWorkflow[]> {
+  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
+    WORKFLOWS_KEY,
+  ])
+  return parseStoredWorkflows(rows[0]?.value)
+}
+
+/** Stores the workflows; answers what was there before. */
+export async function writeWorkflows(
+  db: Db,
+  workflows: readonly StoredWorkflow[],
+): Promise<StoredWorkflow[]> {
+  return db.transaction(async (tx) => {
+    const before = await readWorkflows(tx)
+    const value = JSON.stringify(workflows)
+    const now = tx.dialect.now()
+    const updated = await tx.query<{ key: string }>(
+      `UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ? RETURNING key`,
+      [value, WORKFLOWS_KEY],
+    )
+    if (updated.length === 0)
+      await tx.exec(`INSERT INTO key_value (key, value, update_date) VALUES (?, ?, ${now})`, [
+        WORKFLOWS_KEY,
+        value,
+      ])
+    return before
+  })
+}
+
+export interface WorkflowSyncReport {
+  /** Aliases whose meaning changed, or that are new or gone. */
+  changed: string[]
+  /** What `on-change` did to requests in flight, by request key. */
+  requests: Array<{ key: string; workflow: string; outcome: 'kept' | 'restarted' | 'withdrawn' }>
+}
+
+/**
+ * Stores the workflows and applies each changed one's `on-change` to the
+ * requests in flight under it: `keep` leaves them on the version they started
+ * with, `restart` starts them again from the first stage of the new one, and
+ * `withdraw` ends them. A workflow that is gone cannot be restarted under, so
+ * its requests are kept or withdrawn as it said.
+ */
+export async function syncWorkflows(
+  db: Db,
+  workflows: readonly StoredWorkflow[],
+): Promise<WorkflowSyncReport> {
+  const report: WorkflowSyncReport = { changed: [], requests: [] }
+  const before = await writeWorkflows(db, workflows)
+  const identity = (w: SchemaWorkflow) => w.key ?? w.alias
+  const previous = new Map(before.map((s) => [identity(s.workflow), s]))
+  const current = new Map(workflows.map((s) => [identity(s.workflow), s]))
+  const requests = new ApprovalRepository(db)
+  for (const id of new Set([...previous.keys(), ...current.keys()])) {
+    const was = previous.get(id)
+    const now = current.get(id)
+    if (was && now && was.version === now.version) continue
+    report.changed.push((now ?? was)?.workflow.alias ?? id)
+    const rule = (now ?? was)?.workflow.onChange ?? 'keep'
+    for (const request of await requests.waitingUnder(id)) {
+      if (request.workflowVersion === now?.version) continue
+      if (rule === 'keep') {
+        report.requests.push({ key: request.key, workflow: id, outcome: 'kept' })
+        continue
+      }
+      if (rule === 'restart' && now) {
+        await requests.rebase(request.id, now.workflow, now.version)
+        for (const stage of startStages(now.workflow)) await requests.addStep(request.id, stage)
+        await requests.record(request.id, { kind: 'restarted', comment: 'the workflow changed' })
+        report.requests.push({ key: request.key, workflow: id, outcome: 'restarted' })
+        continue
+      }
+      await requests.setState(request.id, 'withdrawn')
+      await requests.record(request.id, {
+        kind: 'withdrawn',
+        comment: now ? 'the workflow changed' : 'the workflow was removed',
+      })
+      report.requests.push({ key: request.key, workflow: id, outcome: 'withdrawn' })
+    }
+  }
+  return report
+}