@crombolo/server 0.9.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/server",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "The crombolo HTTP server: routing, configuration, media stores and background jobs.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,16 +28,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/api-management": "0.9.1",
-    "@crombolo/assistant": "0.9.1",
-    "@crombolo/auth": "0.9.1",
-    "@crombolo/backoffice-host": "0.9.1",
-    "@crombolo/contracts": "0.9.1",
-    "@crombolo/core": "0.9.1",
-    "@crombolo/data": "0.9.1",
-    "@crombolo/render": "0.9.1",
-    "@crombolo/schema": "0.9.1",
-    "@crombolo/transfer": "0.9.1",
+    "@crombolo/api-management": "0.11.0",
+    "@crombolo/assistant": "0.11.0",
+    "@crombolo/auth": "0.11.0",
+    "@crombolo/backoffice-host": "0.11.0",
+    "@crombolo/contracts": "0.11.0",
+    "@crombolo/core": "0.11.0",
+    "@crombolo/data": "0.11.0",
+    "@crombolo/render": "0.11.0",
+    "@crombolo/schema": "0.11.0",
+    "@crombolo/transfer": "0.11.0",
     "@logtape/logtape": "^2.3.8"
   }
 }

package/src/adapters/audit.ts

@@ -0,0 +1,186 @@
+/**
+ * The audit log's ports: where the router writes, what an item's Info tab reads,
+ * and the Settings dashboard's endpoint. docs/audit-log.md.
+ */
+import type { AuditHistoryPort, AuditSink } from '@crombolo/api-management'
+import {
+  AUDIT_CATEGORIES,
+  type AuditCategory,
+  type AuditEntry,
+  type AuditEntryInput,
+  AuditLog,
+  type Db,
+} from '@crombolo/data'
+import { logger } from '../logging.ts'
+
+const log = logger('Audit')
+
+/** The oldest moment the log still keeps, or undefined when it keeps everything. */
+export function auditRetainedSince(retentionDays: number, now = new Date()): Date | undefined {
+  return retentionDays > 0 ? new Date(now.getTime() - retentionDays * 86_400_000) : undefined
+}
+
+/**
+ * Writes an entry without ever failing what it records: the change has already
+ * been made by the time it is written, so a failure here is logged, not raised.
+ */
+export async function recordAudit(
+  db: Db,
+  entries: AuditEntryInput | readonly AuditEntryInput[],
+): Promise<void> {
+  try {
+    await new AuditLog(db).record(entries)
+  } catch (error) {
+    log.error('Could not write to the audit log: {error}', { error })
+  }
+}
+
+export function createAuditSink(db: Db): AuditSink {
+  const audit = new AuditLog(db)
+  return {
+    async describe(entityType, key) {
+      try {
+        return await audit.describe(entityType, key)
+      } catch (error) {
+        log.warning('Could not name {entityType} {key} for the audit log: {error}', {
+          entityType,
+          key,
+          error,
+        })
+        return { entityType, entityKey: key, entityName: null }
+      }
+    },
+    record: (entries) =>
+      recordAudit(
+        db,
+        entries.map((entry) => ({ ...entry, source: 'request' as const })),
+      ),
+  }
+}
+
+export function createAuditHistory(db: Db, retentionDays: number): AuditHistoryPort {
+  const audit = new AuditLog(db)
+  let started: Date | undefined
+  return {
+    async forItem(key) {
+      const { items } = await audit.query({ entityKey: key }, { skip: 0, take: 10_000 })
+      return items
+    },
+    async startedAt() {
+      started ??= await audit.startedAt()
+      return started
+    },
+    retainedSince: () => auditRetainedSince(retentionDays),
+  }
+}
+
+function toResponse(entry: AuditEntry) {
+  return {
+    id: entry.id,
+    occurredAt: entry.occurredAt.toISOString(),
+    category: entry.category,
+    action: entry.action,
+    source: entry.source,
+    user: entry.userKey || entry.userName ? { key: entry.userKey, name: entry.userName } : null,
+    item: entry.entityType
+      ? { type: entry.entityType, key: entry.entityKey, name: entry.entityName }
+      : null,
+    ipAddress: entry.ipAddress,
+    forwardedFor: entry.forwardedFor,
+    detail: entry.detail,
+  }
+}
+
+function dateParam(value: string | null): Date | undefined | null {
+  if (!value) return undefined
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? null : parsed
+}
+
+const badRequest = (detail: string) =>
+  Response.json({ title: 'Invalid request', status: 400, detail }, { status: 400 })
+
+/**
+ * The Settings dashboard's reads: `GET /` lists entries, newest first, filtered
+ * by user, item, category, action, date and text; `GET /users` names everyone in
+ * the log. Nothing here writes, so an entry cannot be changed through it.
+ */
+export function createAuditHost(db: Db, retentionDays: number) {
+  const audit = new AuditLog(db)
+  return {
+    async handle(request: Request, pathname: string): Promise<Response | undefined> {
+      if (pathname !== '' && pathname !== '/' && pathname !== '/users') return undefined
+      if (request.method !== 'GET')
+        return new Response('Method Not Allowed', { status: 405, headers: { allow: 'GET' } })
+      if (pathname === '/users') return Response.json({ items: await audit.users() })
+
+      const search = new URL(request.url).searchParams
+      const skip = Number(search.get('skip') ?? 0)
+      const take = Number(search.get('take') ?? 50)
+      if (!Number.isInteger(skip) || skip < 0 || !Number.isInteger(take) || take < 1 || take > 500)
+        return badRequest('skip must be 0 or more, and take between 1 and 500.')
+      const category = search.get('category') ?? undefined
+      if (category && !AUDIT_CATEGORIES.includes(category as AuditCategory))
+        return badRequest(`There is no category "${category}".`)
+      const since = dateParam(search.get('since'))
+      const until = dateParam(search.get('until'))
+      if (since === null || until === null) return badRequest('since and until must be dates.')
+      const result = await audit.query(
+        {
+          userKey: search.get('user') ?? undefined,
+          entityKey: search.get('item') ?? undefined,
+          category: category as AuditCategory | undefined,
+          action: search.get('action') ?? undefined,
+          since,
+          until,
+          text: search.get('text') ?? undefined,
+        },
+        { skip, take },
+      )
+      return Response.json({
+        total: result.total,
+        retentionDays,
+        items: result.items.map(toResponse),
+      })
+    },
+  }
+}
+
+const VERB: Record<string, string> = {
+  POST: 'Create',
+  PUT: 'Save',
+  PATCH: 'Save',
+  DELETE: 'Delete',
+}
+
+/** Crombolo's own endpoints that change something, by their first segment. */
+const PLUGIN_AREAS: Record<string, { category: AuditCategory; entityType: string }> = {
+  'schema-import': { category: 'schema', entityType: 'Schema' },
+  git: { category: 'schema', entityType: 'Schema' },
+  seo: { category: 'settings', entityType: 'SeoSettings' },
+  bundles: { category: 'system', entityType: 'Bundle' },
+  forms: { category: 'content', entityType: 'Form' },
+}
+
+const PLUGIN_ACTIONS: Record<string, string> = {
+  'schema-import': 'Import',
+  'git/commit': 'Commit',
+  'bundles/install': 'Install',
+  'bundles/uninstall': 'Uninstall',
+}
+
+/** The entry for a write to `<plugin>/api/<subpath>`: the area it is in, and what it did there. */
+export function pluginAuditPlan(
+  method: string,
+  subpath: string,
+): Pick<AuditEntryInput, 'category' | 'action' | 'entityType' | 'entityKey' | 'detail'> {
+  const [area = '', ...rest] = subpath.split('/')
+  const known = PLUGIN_AREAS[area]
+  return {
+    category: known?.category ?? 'settings',
+    entityType: known?.entityType ?? area,
+    action: PLUGIN_ACTIONS[subpath] ?? VERB[method] ?? method,
+    entityKey: rest.length > 0 ? rest.join('/') : null,
+    detail: `${method} ${subpath}`,
+  }
+}

package/src/adapters/bundles.ts

@@ -1,6 +1,6 @@
 /**
- * Bundles: the definitions, and the zip a download builds from one.
- * `docs/17-bundles.md`.
+ * Bundles: the definitions, and the npm package a download builds from one.
+ * `docs/bundles.md`.
  *
  * Nothing new is serialized here. Schema travels as the canonical TOML
  * `@crombolo/schema` already writes, content and media as the bundle
@@ -48,14 +48,27 @@ import {
   type BundleKind,
   type BundleNode,
   type BundleSection,
+  bundleIdFor,
   type ContentSet,
   exportBundle,
+  isPackageName,
+  packageNameFor,
   writeBundle,
+  writeBundlePackage,
 } from '@crombolo/transfer'
+import { VERSION } from '../config.ts'
 import { dictionaryToUdt, writeDictionaryUdt } from '../dictionary-transfer.ts'
 import { readBlobs } from '../media-files.ts'
 import type { MediaStore } from '../media-store.ts'
-import { writeZip, type ZipEntry } from '../zip.ts'
+import { writeNpmTarball } from '../tar.ts'
+
+/** The npm package a definition is built as: what was set on it, or what its name gives. */
+export function bundlePackageOf(row: Bundle): { name: string; version: string } {
+  return {
+    name: row.packageName ?? packageNameFor(row.name),
+    version: row.packageVersion ?? '1.0.0',
+  }
+}
 
 /** The content kinds a bundle's picks can name. */
 const CONTENT_OBJECT_TYPES = [ObjectTypes.Document, ObjectTypes.Media, ObjectTypes.Element]
@@ -376,17 +389,19 @@ export function createPackagePort(db: Db, options: PackagePortOptions): PackageP
     },
 
     /**
-     * The definition as one bundle, zipped.
+     * The definition as one bundle, packed as the npm package it is.
      *
      * Everything goes through `writeBundle` so there is a single manifest over
-     * the whole artifact: it declares the sections, carries the hash that covers
-     * them, and names the package — a zip of loose directories would have no
-     * record of what it was or whether it arrived whole.
+     * the whole payload: it declares the sections, carries the hash that covers
+     * them, and names the bundle. The package around it is what gives it a
+     * name, a version and the core it was written for, so the download is
+     * something `bun add ./file.tgz` and `bun publish` take as it is.
      */
     async build(id): Promise<BuiltPackage | undefined> {
       const row = await bundles.byId(id)
       if (!row) return undefined
       const from = definition(row)
+      const pkg = bundlePackageOf(row)
 
       // The schema version the site is actually at, so the files a package
       // carries say where they came from rather than claiming version 0.
@@ -422,11 +437,71 @@ export function createPackagePort(db: Db, options: PackagePortOptions): PackageP
 
       const labelled: ContentSet = { ...set, manifest: { ...set.manifest, label: from.name } }
       const encoder = new TextEncoder()
-      const entries: ZipEntry[] = writeBundle(labelled, content.blobs, sections).map((file) => ({
+      const files = writeBundlePackage(writeBundle(labelled, content.blobs, sections), {
+        name: pkg.name,
+        version: pkg.version,
+        id: bundleIdFor(pkg.name.replace(/^@[^/]+\//, '')),
+        label: from.name,
+        peerRange: `^${VERSION}`,
+      })
+      const entries = files.map((file) => ({
         path: file.path,
         bytes: file.bytes ?? encoder.encode(file.text ?? ''),
       }))
-      return { fileName: packageFileName(from.name), bytes: writeZip(entries) }
+      return {
+        fileName: packageFileName(pkg.name, pkg.version),
+        contentType: 'application/gzip',
+        bytes: writeNpmTarball(entries),
+      }
     },
   }
 }
+
+/** A created bundle's npm package as the Created view edits it. */
+export interface CreatedBundlePackage {
+  name: string
+  version: string
+  /** Whether each was set, rather than derived from the definition's name. */
+  set: { name: boolean; version: boolean }
+}
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/** The npm package a definition builds as, or undefined when it is gone. */
+export async function readCreatedBundlePackage(
+  db: Db,
+  id: string,
+): Promise<CreatedBundlePackage | undefined> {
+  const row = await new BundleRepository(db).byId(id)
+  if (!row) return undefined
+  return {
+    ...bundlePackageOf(row),
+    set: { name: row.packageName !== null, version: row.packageVersion !== null },
+  }
+}
+
+/**
+ * Sets the npm package a definition builds as. An empty value goes back to its
+ * default; anything else must be what npm itself would accept.
+ */
+export async function writeCreatedBundlePackage(
+  db: Db,
+  id: string,
+  input: { name?: unknown; version?: unknown },
+): Promise<{ ok: true; package: CreatedBundlePackage } | { ok: false; message: string }> {
+  const bundles = new BundleRepository(db)
+  if (!(await bundles.byId(id))) return { ok: false, message: 'That bundle no longer exists.' }
+  const text = (value: unknown) => (typeof value === 'string' ? value.trim() : '')
+  const name = text(input.name)
+  const version = text(input.version)
+  if (name && !isPackageName(name))
+    return {
+      ok: false,
+      message:
+        'A package name is lowercase letters, digits, dots, hyphens and underscores, optionally with an @scope/ in front.',
+    }
+  if (version && !SEMVER.test(version))
+    return { ok: false, message: 'A version is three numbers, like 1.0.0.' }
+  await bundles.setPackage(id, { name: name || null, version: version || null })
+  return { ok: true, package: (await readCreatedBundlePackage(db, id)) as CreatedBundlePackage }
+}

package/src/adapters/schema-files.ts

@@ -2,7 +2,7 @@
  * 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".
+ * docs/schema-as-code.md, "The backoffice writes files".
  */
 
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'

package/src/adapters/search-index.ts

@@ -0,0 +1,31 @@
+/** The Examine dashboard's port over the search index. docs/search.md. */
+import type { SearchIndexInfo, SearchIndexPort } from '@crombolo/api-management'
+import { type Db, SEARCH_INDEXES, SearchIndex, type SearchIndexDefinition } from '@crombolo/data'
+
+export function createSearchIndexPort(db: Db, onQueued?: () => void): SearchIndexPort {
+  const search = new SearchIndex(db)
+  const info = async (index: SearchIndexDefinition): Promise<SearchIndexInfo> => ({
+    name: index.name,
+    searcherName: index.searcherName,
+    ...(await search.stats(index)),
+  })
+  return {
+    indexes: () => Promise.all(SEARCH_INDEXES.map(info)),
+    async index(name) {
+      const index = SearchIndex.definition(name)
+      return index ? info(index) : undefined
+    },
+    async rebuild(name) {
+      const index = SearchIndex.definition(name)
+      if (!index) return false
+      await search.rebuild(index)
+      onQueued?.()
+      return true
+    },
+    searchers: () => SEARCH_INDEXES.map((index) => index.searcherName),
+    async query(searcherName, term, paging) {
+      const index = SearchIndex.bySearcher(searcherName)
+      return index ? search.query(index, term, paging) : undefined
+    },
+  }
+}

package/src/backup.ts

@@ -1,5 +1,5 @@
 /**
- * Rollback is a backup (docs/10-packaging-and-upgrades.md): SQLite is copied
+ * Rollback is a backup (docs/packaging-and-upgrades.md): SQLite is copied
  * beside the database; Postgres runs the operator's `CROMBOLO_PG_DUMP` command
  * or refuses unless the caller vouches with `--backup-taken`.
  */