@crombolo/server 0.0.0-stage → 0.9.1

package/src/adapters/public-access.ts

@@ -0,0 +1,116 @@
+/**
+ * Public access: protecting a branch by member group or by named member.
+ *
+ * The stored rules are names, not keys, because that is what a signed-in member
+ * carries and what the render path compares against. Reading an entry back
+ * therefore resolves each name to the member or group the editor should show —
+ * and a name that no longer resolves simply drops out, which is exactly what a
+ * renamed group means for the rule.
+ */
+import type {
+  MemberGroupItem,
+  MemberItem,
+  PublicAccessInput,
+  PublicAccessPort,
+  PublicAccessResponse,
+  PublicAccessStatus,
+} from '@crombolo/api-management'
+import { ObjectTypes } from '@crombolo/core'
+import {
+  type Db,
+  MemberRepository,
+  NodeRepository,
+  type PublicAccessEntry,
+  PublicAccessRepository,
+} from '@crombolo/data'
+
+export function createPublicAccessPort(
+  db: Db,
+  options: { onChange?: () => void | Promise<void> } = {},
+): PublicAccessPort {
+  const access = new PublicAccessRepository(db)
+  const members = new MemberRepository(db)
+  const nodes = new NodeRepository(db)
+
+  const isDocument = async (key: string) => {
+    const node = await nodes.byKey(key)
+    return node?.objectType === ObjectTypes.Document
+  }
+
+  const groupsNamed = async (names: readonly string[]): Promise<MemberGroupItem[]> => {
+    const found: MemberGroupItem[] = []
+    for (const name of names) {
+      const rows = await db.query<{ unique_id: string; text: string | null }>(
+        'SELECT unique_id, text FROM node WHERE node_object_type = ? AND text = ?',
+        [ObjectTypes.MemberGroup, name],
+      )
+      const row = rows[0]
+      if (row) found.push({ id: String(row.unique_id), name: String(row.text ?? ''), flags: [] })
+    }
+    return found
+  }
+
+  const membersNamed = async (usernames: readonly string[]): Promise<MemberItem[]> => {
+    const found: MemberItem[] = []
+    for (const username of usernames) {
+      const member = await members.byUsername(username)
+      if (member)
+        found.push({
+          id: member.key,
+          memberType: {
+            id: member.contentTypeKey,
+            icon: member.contentTypeIcon ?? 'icon-user',
+          },
+          variants: [{ name: member.name, culture: null }],
+          kind: 'Default',
+          flags: [],
+        })
+    }
+    return found
+  }
+
+  const toResponse = async (
+    entry: PublicAccessEntry,
+    requestedKey: string,
+  ): Promise<PublicAccessResponse> => ({
+    loginDocument: { id: entry.loginNodeKey },
+    errorDocument: { id: entry.errorNodeKey },
+    members: await membersNamed(entry.memberUserNames),
+    groups: await groupsNamed(entry.memberGroupNames),
+    isProtectedByAncestor: entry.nodeKey !== requestedKey.toLowerCase(),
+  })
+
+  return {
+    async entry(documentKey, includeAncestors) {
+      if (!(await isDocument(documentKey))) return { status: 'content-not-found' }
+      const found = includeAncestors
+        ? await access.entryFor(documentKey)
+        : await access.byNodeKey(documentKey)
+      if (!found) return { status: 'entry-not-found' }
+      return { status: 'ok', entry: await toResponse(found, documentKey) }
+    },
+
+    async save(documentKey, input: PublicAccessInput): Promise<PublicAccessStatus> {
+      if (!(await isDocument(documentKey))) return 'content-not-found'
+      if (!(await isDocument(input.loginDocumentKey))) return 'login-node-not-found'
+      if (!(await isDocument(input.errorDocumentKey))) return 'error-node-not-found'
+      const saved = await access.save({
+        nodeKey: documentKey,
+        loginNodeKey: input.loginDocumentKey,
+        errorNodeKey: input.errorDocumentKey,
+        memberGroupNames: input.memberGroupNames,
+        memberUserNames: input.memberUserNames,
+      })
+      if (!saved) return 'content-not-found'
+      await options.onChange?.()
+      return 'ok'
+    },
+
+    async remove(documentKey): Promise<PublicAccessStatus> {
+      if (!(await isDocument(documentKey))) return 'content-not-found'
+      if (!(await access.remove(documentKey))) return 'entry-not-found'
+      await options.onChange?.()
+      return 'ok'
+    },
+  }
+}

package/src/adapters/redirects.ts

@@ -0,0 +1,73 @@
+/**
+ * The redirect rows as the backoffice reads them.
+ *
+ * `destinationUrl` is resolved for display: a rule pointing at a document shows
+ * where that document lives now, so the dashboard never shows a stale target. A
+ * rule the site configured is reported as such and refuses to be deleted — the
+ * config file owns it, and the next boot would put it back.
+ */
+
+import type { RedirectListing, RedirectPort } from '@crombolo/api-management'
+import type { Page } from '@crombolo/core'
+import { type Db, RedirectRepository, type RedirectRow } from '@crombolo/data'
+import type { PublishedCache } from '@crombolo/render'
+
+export function createRedirectPort(
+  db: Db,
+  cache: PublishedCache | undefined,
+  options: { isTracking: boolean; onChange?: () => void },
+): RedirectPort {
+  const redirects = new RedirectRepository(db)
+
+  /** The pattern as a visitor would type it, hostname included when one scopes it. */
+  const originalUrl = async (row: RedirectRow): Promise<string> => {
+    const suffix =
+      row.matchKind === 'prefix' ? `${row.pattern === '/' ? '' : row.pattern}/*` : row.pattern
+    if (row.rootKey === null) return suffix
+    const snapshot = await cache?.snapshot()
+    const domain = snapshot?.domains.find(
+      (d) => !d.isWildcard && snapshot.domainRoots.get(d.nodeId) === row.rootKey,
+    )
+    return domain ? `//${domain.domainName}${suffix === '/' ? '/' : suffix}` : suffix
+  }
+
+  const destinationUrl = async (row: RedirectRow): Promise<string> => {
+    if (row.targetKind !== 'document') return row.target
+    const content = await cache?.byKey(row.target, row.culture)
+    return content && content.url !== '#' ? content.url : ''
+  }
+
+  const listing = async (row: RedirectRow): Promise<RedirectListing> => ({
+    key: row.key,
+    originalUrl: await originalUrl(row),
+    destinationUrl: await destinationUrl(row),
+    culture: row.culture,
+    documentKey: row.targetKind === 'document' ? row.target : null,
+    created: row.createDate,
+    isConfigured: row.source === 'config',
+  })
+
+  const page = async (result: {
+    total: number
+    items: RedirectRow[]
+  }): Promise<Page<RedirectListing>> => ({
+    total: result.total,
+    items: await Promise.all(result.items.map(listing)),
+  })
+
+  return {
+    list: async (filter, paging) => page(await redirects.list({ filter, ...paging })),
+    byDocument: async (key, paging) => page(await redirects.byDocument(key, paging)),
+    async remove(key) {
+      const found = await redirects.byKey(key)
+      if (!found) return 'notFound'
+      if (found.source === 'config') return 'configured'
+      await redirects.delete(key)
+      // The rules live in the published cache's snapshot, so it has to be dropped
+      // for the redirect to stop answering.
+      options.onChange?.()
+      return 'deleted'
+    },
+    isTracking: () => options.isTracking,
+  }
+}

package/src/adapters/references.ts

@@ -0,0 +1,67 @@
+/**
+ * References, shaped for the wire. The client discriminates the list by
+ * `$type`, so a referencing node becomes a document, a media item, or the
+ * default shape when it is neither.
+ */
+import type { ReferencePort } from '@crombolo/api-management'
+import { ObjectTypes } from '@crombolo/core'
+import { type Db, ReferenceRepository, type ReferencingNode } from '@crombolo/data'
+
+function toReference(node: ReferencingNode): unknown {
+  const type = {
+    id: node.contentTypeKey ?? node.key,
+    icon: node.contentTypeIcon,
+    alias: node.contentTypeAlias,
+    name: node.contentTypeAlias,
+  }
+  if (node.objectType === ObjectTypes.Document)
+    return {
+      $type: 'DocumentReferenceResponseModel',
+      id: node.key,
+      name: node.name,
+      published: node.published,
+      documentType: type,
+      // Invariant until a reference needs to name the culture it came from.
+      variants: [
+        {
+          id: node.key,
+          name: node.name ?? '',
+          culture: null,
+          state: node.published ? 'Published' : 'Draft',
+          flags: [],
+        },
+      ],
+    }
+  if (node.objectType === ObjectTypes.Media)
+    return {
+      $type: 'MediaReferenceResponseModel',
+      id: node.key,
+      name: node.name,
+      mediaType: type,
+    }
+  return {
+    $type: 'DefaultReferenceResponseModel',
+    id: node.key,
+    name: node.name,
+    type: node.contentTypeAlias,
+    icon: node.contentTypeIcon,
+  }
+}
+
+export function createReferencePort(db: Db): ReferencePort {
+  const references = new ReferenceRepository(db)
+  return {
+    async referencedBy(key, paging) {
+      const result = await references.referencedBy(key, paging.skip, paging.take)
+      return { total: result.total, items: result.items.map(toReference) }
+    },
+    async referencedDescendants(key, paging) {
+      const result = await references.referencedDescendants(key, paging.skip, paging.take)
+      return { total: result.total, items: result.items.map((id) => ({ id })) }
+    },
+    async areReferenced(keys, paging) {
+      const result = await references.areReferenced(keys, paging.skip, paging.take)
+      return { total: result.total, items: result.items.map((id) => ({ id })) }
+    },
+  }
+}

package/src/adapters/schema-files.ts

@@ -0,0 +1,204 @@
+/**
+ * The backoffice writes schema files. A document-type save lands in the
+ * database as before and, when the directory is writable, in
+ * `schema/content-types/<alias>.toml` — the file the next boot will sync.
+ * docs/09-schema-as-code.md, "The backoffice writes files".
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { PortFailure } from '@crombolo/api-management'
+import type { ContentTypeAggregate, DataTypeModel } from '@crombolo/core'
+import { currentSchemaState, type Db, updateSchemaStateHash } from '@crombolo/data'
+import {
+  type ChangeClass,
+  exportSchemaSet,
+  fileNameFor,
+  hashSchemaSet,
+  loadSchemaDirectory,
+  nextSchemaVersion,
+  type SchemaTypeKind,
+  TYPE_KIND_FILES,
+  validateSchemaSet,
+  writeContentType,
+  writeDataType,
+  writeLanguages,
+  writeSchemaFiles,
+  writeSchemaVersion,
+} from '@crombolo/schema'
+import { logger } from '../logging.ts'
+
+export interface SchemaFiles {
+  schemaDir: string
+  writable: boolean
+  componentAliases(): ReadonlySet<string>
+  /**
+   * Called after any write, so a shared schema store outlives this container.
+   * Absent when the schema is a directory on disk, which needs no publishing.
+   */
+  onChanged?(): Promise<void>
+}
+
+export interface SchemaFileWriter {
+  /** A read-only directory refuses the save before the database changes. */
+  refuse(aggregate: { alias: string }): PortFailure | undefined
+  /**
+   * Moves the site's schema version on by what the change costs the content,
+   * before the database is written and while the two can still be compared.
+   * `breaking` is a major: getting there converted data.
+   */
+  bumpVersion(classification: ChangeClass): Promise<void>
+  /** Writes the saved type canonically; an alias change removes the old file. */
+  write(aggregate: ContentTypeAggregate, previousAlias?: string): Promise<void>
+  remove(alias: string): Promise<void>
+  writeDataType(model: DataTypeModel): Promise<void>
+  removeDataType(alias: string): Promise<void>
+  writeLanguages(): Promise<void>
+  /** After a move or a folder change: every file, from the database, canonically. */
+  rewriteAll(): Promise<void>
+}
+
+/**
+ * A writer for one kind of content type: content types (the default) write
+ * `schema/content-types/`, media types `schema/media-types/`. Data types,
+ * languages and the rewrite are the same whichever kind asks.
+ */
+export function createSchemaFileWriter(
+  db: Db,
+  files: SchemaFiles,
+  kind: SchemaTypeKind = 'document',
+): SchemaFileWriter {
+  const dir = join(files.schemaDir, TYPE_KIND_FILES[kind].dir)
+  const fileFor = (alias: string) => join(dir, fileNameFor(alias))
+  const plural = { document: 'Content types', media: 'Media types', member: 'Member types' }[kind]
+  const managed = () => existsSync(files.schemaDir)
+
+  /**
+   * The database already matches the files; record their hash so the next sync is
+   * a no-op, then hand the files to wherever they durably live.
+   */
+  const settle = async () => {
+    const state = await currentSchemaState(db)
+    await updateSchemaStateHash(
+      db,
+      state.id,
+      hashSchemaSet(loadSchemaDirectory(files.schemaDir).set),
+    )
+    await files.onChanged?.()
+  }
+
+  return {
+    refuse(aggregate) {
+      if (!managed() || files.writable) return undefined
+      const shown = relative(process.cwd(), fileFor(aggregate.alias))
+      return {
+        ok: false,
+        status: 409,
+        reason: `${plural} are defined in schema/ and this environment is read-only; change ${shown} in source control.`,
+      }
+    },
+
+    async bumpVersion(classification) {
+      if (!managed() || !files.writable || classification === 'none') return
+      const loaded = loadSchemaDirectory(files.schemaDir)
+      const next = nextSchemaVersion(loaded.set.version, classification)
+      if (next === loaded.set.version) return
+      writeFileSync(join(files.schemaDir, 'schema.toml'), writeSchemaVersion(next))
+      logger('schema').info('Schema version {from} → {to} ({classification})', {
+        from: loaded.set.version,
+        to: next,
+        classification,
+      })
+    },
+
+    async write(aggregate, previousAlias) {
+      if (!managed() || !files.writable) return
+      const set = await exportSchemaSet(db, loadSchemaDirectory(files.schemaDir).set.version)
+      const list =
+        kind === 'document'
+          ? set.contentTypes
+          : kind === 'media'
+            ? (set.mediaTypes ?? [])
+            : (set.memberTypes ?? [])
+      const type = list.find((t) => t.key === aggregate.key)
+      if (!type) return
+      const problems = validateSchemaSet(set, { componentAliases: files.componentAliases() })
+      if (problems.length > 0) {
+        const detail = problems.map((p) => `${p.file}: ${p.message}`).join('; ')
+        logger('schema').error('Not writing {file}: {detail}', {
+          file: fileNameFor(aggregate.alias),
+          detail,
+        })
+        return
+      }
+      mkdirSync(dir, { recursive: true })
+      if (previousAlias && previousAlias !== aggregate.alias)
+        rmSync(fileFor(previousAlias), { force: true })
+      writeFileSync(fileFor(aggregate.alias), writeContentType(type, kind))
+      await settle()
+    },
+
+    async remove(alias) {
+      if (!managed() || !files.writable) return
+      rmSync(fileFor(alias), { force: true })
+      await settle()
+    },
+
+    async writeDataType(model) {
+      if (!managed() || !files.writable || !model.alias) return
+      const set = await exportSchemaSet(db, loadSchemaDirectory(files.schemaDir).set.version)
+      const dataType = set.dataTypes.find((d) => d.key === model.key)
+      // An unchanged built-in has no file; a changed one does.
+      if (!dataType) {
+        rmSync(join(files.schemaDir, 'data-types', fileNameFor(model.alias)), { force: true })
+        await settle()
+        return
+      }
+      // The same guard `write` applies to a content type: a set that does not
+      // validate never reaches the disk, because the file is what every other
+      // node reads and what a deploy boots from.
+      const problems = validateSchemaSet(set, { componentAliases: files.componentAliases() })
+      if (problems.length > 0) {
+        const detail = problems.map((p) => `${p.file}: ${p.message}`).join('; ')
+        logger('schema').error('Not writing {file}: {detail}', {
+          file: fileNameFor(model.alias),
+          detail,
+        })
+        return
+      }
+      mkdirSync(join(files.schemaDir, 'data-types'), { recursive: true })
+      writeFileSync(
+        join(files.schemaDir, 'data-types', fileNameFor(model.alias)),
+        writeDataType(dataType),
+      )
+      await settle()
+    },
+
+    async removeDataType(alias) {
+      if (!managed() || !files.writable) return
+      rmSync(join(files.schemaDir, 'data-types', fileNameFor(alias)), { force: true })
+      await settle()
+    },
+
+    async writeLanguages() {
+      if (!managed() || !files.writable) return
+      const set = await exportSchemaSet(db, loadSchemaDirectory(files.schemaDir).set.version)
+      writeFileSync(join(files.schemaDir, 'languages.toml'), writeLanguages(set.languages))
+      await settle()
+    },
+
+    async rewriteAll() {
+      if (!managed() || !files.writable) return
+      const loaded = loadSchemaDirectory(files.schemaDir)
+      const set = await exportSchemaSet(db, loaded.set.version)
+      const problems = validateSchemaSet(set, { componentAliases: files.componentAliases() })
+      if (problems.length > 0) {
+        const detail = problems.map((p) => `${p.file}: ${p.message}`).join('; ')
+        logger('schema').error('Not rewriting the schema files: {detail}', { detail })
+        return
+      }
+      writeSchemaFiles(files.schemaDir, set)
+      await settle()
+    },
+  }
+}

package/src/adapters/schema-proposals.ts

@@ -0,0 +1,180 @@
+/**
+ * Schema proposals as the TOML files they become.
+ *
+ * A type is a file in `schema/`, and that file is what gets committed, so a
+ * proposal holds the file rather than a request body full of keys. Applying one
+ * writes it and imports it — the same path a commit or another node's publish
+ * takes — instead of writing the database and deriving the file from it
+ * afterwards, which is the wrong way round and is why an editor's change could
+ * never be classified.
+ *
+ * Validation happens twice on purpose: when the proposal is made, so a reviewer
+ * is never shown something that cannot be applied, and again at approval, because
+ * the rest of the schema may have moved in between.
+ */
+
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { SchemaProposalPort } from '@crombolo/assistant'
+import type { Db } from '@crombolo/data'
+import {
+  fileNameFor,
+  loadSchemaDirectory,
+  nextSchemaVersion,
+  parseContentType,
+  parseDataType,
+  type SchemaProblem,
+  TYPE_KIND_FILES,
+  validateSchemaSet,
+  writeContentType,
+  writeDataType,
+  writeSchemaVersion,
+} from '@crombolo/schema'
+import type { CromboloConfig } from '../config.ts'
+import { logger } from '../logging.ts'
+import { componentAliasesIn, importSchema } from '../schema.ts'
+
+const log = logger('schema')
+
+const isDataType = (kind: string) => kind.startsWith('data-type')
+
+/** Where a kind's files live, relative to the schema directory. */
+const directoryFor = (kind: string) =>
+  isDataType(kind) ? 'data-types' : TYPE_KIND_FILES.document.dir
+
+export interface SchemaProposalOptions {
+  db: Db
+  config: CromboloConfig
+  /** The node's identity and state, refreshed in place by an import. */
+  boot: { nodeId: string; nodeState: { version: string; revision: string } }
+}
+
+export function createSchemaProposals(options: SchemaProposalOptions): SchemaProposalPort {
+  const { config } = options
+  const pathFor = (kind: string, alias: string) =>
+    join(config.schemaDir, directoryFor(kind), fileNameFor(alias))
+
+  /**
+   * The proposal's file substituted into the schema as it stands, so a property
+   * pointing at a data type that does not exist, or a composition that would
+   * cycle, is a problem now rather than a surprise at approval.
+   */
+  const validate = async (kind: string, alias: string, toml: string): Promise<SchemaProblem[]> => {
+    const file = `schema/${directoryFor(kind)}/${fileNameFor(alias)}`
+    if (isDataType(kind)) {
+      const parsed = parseDataType(file, toml)
+      const dataType = parsed.value
+      if (parsed.problems.length > 0 || !dataType) {
+        return parsed.problems.length > 0
+          ? parsed.problems
+          : [{ file, path: '', message: 'the file defines no data type' }]
+      }
+      const set = loadSchemaDirectory(config.schemaDir).set
+      const dataTypes = [
+        ...set.dataTypes.filter((existing) => existing.alias !== dataType.alias),
+        dataType,
+      ]
+      return validateSchemaSet({ ...set, dataTypes })
+    }
+
+    const parsed = parseContentType(file, toml)
+    const contentType = parsed.value
+    if (parsed.problems.length > 0 || !contentType) {
+      return parsed.problems.length > 0
+        ? parsed.problems
+        : [{ file, path: '', message: 'the file defines no content type' }]
+    }
+    const set = loadSchemaDirectory(config.schemaDir).set
+    const contentTypes = [
+      ...set.contentTypes.filter((existing) => existing.alias !== contentType.alias),
+      contentType,
+    ]
+    return validateSchemaSet(
+      { ...set, contentTypes },
+      { componentAliases: componentAliasesIn(config.componentsDir) },
+    )
+  }
+
+  return {
+    fileFor: (kind, alias) => `schema/${directoryFor(kind)}/${fileNameFor(alias)}`,
+
+    async read(kind, alias) {
+      const path = pathFor(kind, alias)
+      if (!existsSync(path)) return undefined
+      return await readFile(path, 'utf8')
+    },
+
+    validate,
+
+    async apply(kind, alias, toml) {
+      if (!config.schemaWritable) {
+        return {
+          ok: false,
+          error:
+            'Types are defined in schema/ and this environment is read-only; change the file in source control, or configure a schema store.',
+        }
+      }
+      const problems = await validate(kind, alias, toml)
+      if (problems.length > 0) {
+        return { ok: false, error: problems.map((problem) => problem.message).join('; ') }
+      }
+
+      const path = pathFor(kind, alias)
+      const versionFile = join(config.schemaDir, 'schema.toml')
+      const previous = existsSync(path) ? await readFile(path, 'utf8') : undefined
+      const previousVersion = existsSync(versionFile)
+        ? await readFile(versionFile, 'utf8')
+        : undefined
+      await mkdir(dirname(path), { recursive: true })
+      await writeFile(path, canonical(kind, alias, toml), 'utf8')
+
+      const restore = async () => {
+        if (previous === undefined) await rm(path, { force: true })
+        else await writeFile(path, previous, 'utf8')
+        if (previousVersion !== undefined) await writeFile(versionFile, previousVersion, 'utf8')
+      }
+
+      // Classified while the files and the database still differ: afterwards there
+      // is nothing left to compare. The version moves in the same breath, or the
+      // import lands at a version the other nodes already have and they never
+      // learn they are behind.
+      const ahead = await importSchema(options.db, config, options.boot, { dryRun: true })
+      const version = loadSchemaDirectory(config.schemaDir).set.version
+      const next = nextSchemaVersion(version, ahead.classification)
+      if (next !== version) await writeFile(versionFile, writeSchemaVersion(next), 'utf8')
+
+      const result = await importSchema(options.db, config, options.boot)
+      if (result.report && result.report.action !== 'applied') {
+        // Put the files back: a refused import leaves the site with a file it will
+        // not accept, which is worse than the change not having happened.
+        await restore()
+        return {
+          ok: false,
+          error: result.report.reason ?? `the import was ${result.report.action}`,
+        }
+      }
+      log.info('{alias} applied from a proposal: {classification}, schema at {version}', {
+        alias,
+        classification: ahead.classification,
+        version: options.boot.nodeState.version,
+      })
+      return { ok: true, version: options.boot.nodeState.version }
+    },
+  }
+
+  /**
+   * Written back through the canonical writer, so what lands on disk is what the
+   * backoffice itself would write — one layout, one key order — rather than
+   * whatever the model's formatting happened to be.
+   */
+  function canonical(kind: string, alias: string, toml: string): string {
+    const file = `schema/${directoryFor(kind)}/${fileNameFor(alias)}`
+    if (isDataType(kind)) {
+      const parsed = parseDataType(file, toml)
+      return parsed.value ? writeDataType(parsed.value) : toml
+    }
+    const parsed = parseContentType(file, toml)
+    return parsed.value ? writeContentType(parsed.value) : toml
+  }
+}