@bakery-framework/plugin-db-explorer 2.0.0-alpha.11

package/src/identity.ts

@@ -0,0 +1,401 @@
+/**
+ * How a row is named.
+ *
+ * Every write endpoint addresses rows through this module and nothing else,
+ * because the three obvious alternatives are all broken and the explorer
+ * inherited none of them:
+ *
+ *   - **`rowid`** (SQLite) is absent from a `WITHOUT ROWID` table and is not
+ *     stable across a `VACUUM`.
+ *   - **`ctid`** (Postgres) is the *physical* location of a tuple and moves on
+ *     every UPDATE. Reading a page, editing two rows and writing the second by
+ *     the ctid the read returned edits whatever now sits in that slot.
+ *   - **`getSchema()`'s first `pk` column**, which the dashboard uses on MySQL.
+ *     On a composite key that predicate matches every row sharing the first
+ *     column, so one edit rewrites all of them. Silently.
+ *
+ * What replaces them is a declared key: a primary key, or failing that a unique
+ * index over columns that cannot be null. A table with neither cannot have one
+ * of its rows named at all, so it is read-only for everybody — a 409, not a
+ * best guess.
+ *
+ * ## The two traps this module exists to absorb
+ *
+ * `getConstraints()` camel-cases **both** the table key and every column key
+ * (`Case.camel`), while `getSchema()` and `getData()` speak raw database names.
+ * `Case.snake` is not the inverse of `Case.camel` (`SKU_code` → `sKUCode` →
+ * `s_k_u_code`), so raw names cannot be recovered from camel ones. For columns
+ * they are carried through from `getSchema()`; for index columns the adapters
+ * now carry them too (`rawCols` on `getIndexes()` entries), which retired the
+ * camel→raw map this module used to rebuild. That map was first-wins over
+ * collisions — a table holding both `user_id` and `userId` resolved an index
+ * over the second to the first, a predicate over the wrong column — and the
+ * adapter, which had the real names all along, is the only place that cannot
+ * happen.
+ *
+ * And `getConstraints()` includes **views**, which carry a `_view` key. A view
+ * has no rows of its own to address, so it is always `none`.
+ */
+
+import { Case } from '@bakery-framework/core/utils'
+import type { SQLAdapter } from '@bakery-framework/orm/adapters'
+import { connection } from '@bakery-framework/orm/connection'
+import type { ColumnKind, ColumnMeta } from './shared/coerce'
+
+/**
+ * The shapes the adapter reports, derived from its own signatures rather than
+ * imported: `@bakery-framework/orm` does not export `sync/types`, and adding a
+ * subpath to another package's export map to read three optional fields is a
+ * public-API decision this plugin does not get to make on its own.
+ */
+export type TableConstraints = Awaited<
+  ReturnType<SQLAdapter['getConstraints']>
+>[string]
+export type TableDetails = Awaited<ReturnType<SQLAdapter['getSchema']>>[number]
+export type IndexEntry = Awaited<ReturnType<SQLAdapter['getIndexes']>>[string]
+
+/**
+ * One column of `TableConstraints`, structurally.
+ *
+ * Spelled out because `TableConstraints` is an intersection of an index
+ * signature with `_view`/`_oldTable`/`_transform`, so indexing it does not
+ * narrow to the column type on its own.
+ */
+export interface ColumnConstraint {
+  type?: string
+  length?: number
+  _enum?: readonly string[]
+  primary?: boolean
+  autoIncrement?: boolean
+  nullable?: boolean
+  default?: unknown
+}
+
+export type IdentityMode = 'pk' | 'unique' | 'none'
+
+export interface Identity {
+  mode: IdentityMode
+  /** Raw database column names, in a stable order. Empty when `mode` is `none`. */
+  cols: string[]
+  /** Why there is no identity. Present only when `mode` is `none`. */
+  reason?: string
+}
+
+export interface TableIntrospection {
+  /** The raw database table name. */
+  name: string
+  /** `getConstraints()[Case.camel(name)]`, camel-keyed, possibly `_view`. */
+  constraints: TableConstraints
+  /**
+   * This table's `getIndexes()` entries: `cols` camel-cased, `rawCols` the
+   * database's own spelling, aligned by position.
+   */
+  indexes: { name: string; type: string; cols: string[]; rawCols?: string[] }[]
+  /** Raw database column names, in `getSchema()` order. */
+  columns: string[]
+}
+
+/**
+ * Can this identifier survive being written into a statement?
+ *
+ * `qId` — the single SQL identifier writer (convention 8) — snake-cases before
+ * quoting, so `qId('Orders')` emits `"orders"`. For every name the ORM created
+ * that is a no-op, because it snake-cases on the way in too. For a table some
+ * other tool created with a capital in it, it is a statement against a
+ * different object, and on a case-sensitive MySQL install that object may not
+ * exist or may be a different table entirely.
+ *
+ * So a name that does not round-trip is refused rather than quietly rewritten.
+ * The cost is that such a table is read-only in the explorer; the alternative
+ * is writing to a table the user did not name.
+ */
+export function isAddressable(name: string): boolean {
+  return Case.snake(name) === name
+}
+
+/**
+ * A column key of `TableConstraints` that is really a column.
+ *
+ * `_view`, `_oldTable` and `_transform` share the same object. No real column
+ * can collide with them: `Case.camel` strips a leading underscore, so a column
+ * genuinely named `_view` is filed under `view`.
+ */
+function isColumnKey(key: string): boolean {
+  return !key.startsWith('_')
+}
+
+const none = (reason: string): Identity => ({ mode: 'none', cols: [], reason })
+
+/**
+ * The identity of one table, in the order the brief fixes: declared primary
+ * key, else the narrowest all-NOT-NULL unique index, else nothing.
+ */
+export function describeIdentity(table: TableIntrospection): Identity {
+  if (!isAddressable(table.name)) {
+    return none(
+      `the table name ${table.name} is not addressable — ` +
+        'identifiers are snake-cased before they are quoted',
+    )
+  }
+
+  const constraints = table.constraints as Record<string, unknown>
+  if (typeof constraints._view === 'string') {
+    return none('a view has no rows of its own to address')
+  }
+
+  const column = (camel: string): ColumnConstraint | undefined =>
+    isColumnKey(camel) ? (constraints[camel] as ColumnConstraint) : undefined
+
+  // 1. Primary key. Composite is the normal case, not an exception — walked in
+  //    `getSchema()` column order so a composite key has a stable spelling
+  //    rather than whatever order the introspection query returned.
+  const primary = table.columns.filter(
+    name => column(Case.camel(name))?.primary === true,
+  )
+  if (primary.length) {
+    const unaddressable = primary.filter(c => !isAddressable(c))
+    if (unaddressable.length) {
+      return none(
+        `primary key columns are not addressable: ${unaddressable.join(', ')}`,
+      )
+    }
+    return { mode: 'pk', cols: primary }
+  }
+
+  // 2. The narrowest unique index whose every column is declared NOT NULL.
+  //    NULL is the whole reason for that condition: `NULL = NULL` is unknown,
+  //    so a predicate over a nullable unique column matches no row, and an
+  //    UPDATE that reports zero changes is indistinguishable from a conflict.
+  const candidates = table.indexes
+    .filter(index => index.type === 'unique')
+    .map(index => ({
+      name: index.name,
+      // The adapter's own raw spelling, aligned with `cols` by position — the
+      // camel spelling is kept alongside because the *constraints* are keyed by
+      // it. An entry with no `rawCols` (a TS-declared index reaching here
+      // through some future path) yields `undefined` cells and is filtered out
+      // below rather than guessed at.
+      cols: index.cols.map((camel, i) => ({
+        camel,
+        raw: index.rawCols?.[i],
+      })),
+    }))
+    .filter(
+      (index): index is { name: string; cols: { camel: string; raw: string }[] } =>
+        index.cols.length > 0 &&
+        index.cols.every(
+          col =>
+            typeof col.raw === 'string' &&
+            isAddressable(col.raw) &&
+            // `nullable === false` explicitly, never `!nullable`. An adapter
+            // that reported nothing for a column would otherwise read as NOT
+            // NULL, which is the fail-open direction (convention 2).
+            column(col.camel)?.nullable === false,
+        ),
+    )
+    // Narrowest first; ties broken by index name so two equally narrow keys
+    // do not depend on introspection order.
+    .sort(
+      (a, b) => a.cols.length - b.cols.length || a.name.localeCompare(b.name),
+    )
+
+  const chosen = candidates[0]
+  if (chosen) return { mode: 'unique', cols: chosen.cols.map(c => c.raw) }
+
+  return none(
+    'no primary key and no unique index over NOT NULL columns — ' +
+      'there is no way to name one row of this table',
+  )
+}
+
+export interface ColumnFacts {
+  /** The raw database column name — what goes into a statement. */
+  name: string
+  /** The key `getConstraints()` filed it under. */
+  camel: string
+  /** The database's own type string, from `getSchema()`. */
+  sqlType: string
+  meta: ColumnMeta
+}
+
+/** One index, with its columns translated back to raw database names. */
+export interface IndexFacts {
+  name: string
+  type: string
+  /** Raw column names where they resolve, the camel spelling where they do not. */
+  cols: string[]
+}
+
+export interface TableFacts {
+  name: string
+  camel: string
+  isView: boolean
+  /** `null` unless `introspect({ rowCounts: true })` was asked — see below. */
+  rowCount: number | null
+  columns: ColumnFacts[]
+  /** By raw column name. */
+  byName: Map<string, ColumnFacts>
+  identity: Identity
+  /**
+   * Declared indexes.
+   *
+   * Computed here already — `describeIdentity` walks them to find a usable
+   * unique key — and now carried out rather than discarded, because the
+   * Structure view shows them and there is no second endpoint that knows them.
+   */
+  indexes: IndexFacts[]
+  /**
+   * The first text column that is not part of the identity — what a foreign-key
+   * reference shows instead of a bare id. `null` when the table has none.
+   */
+  label: string | null
+}
+
+/** Genuine date/time column types, as the three dialects spell them. */
+const RX_DATE_TYPE = /^(date|datetime|timestamp)/i
+
+/**
+ * What kind of value a column holds.
+ *
+ * `getConstraints()` is the authority, with one exception it cannot express:
+ * `ColumnType` has no date member, so every adapter maps a real `DATE` or
+ * `TIMESTAMP` to `string` (MySQL explicitly, Postgres by falling through). The
+ * raw SQL type is the only place that distinction survives, and it matters —
+ * `''` into a text column is an empty string and into a timestamp is an error.
+ */
+function kindOf(declared: string | undefined, sqlType: string): ColumnKind {
+  const known: ColumnKind[] = [
+    'integer',
+    'number',
+    'bigint',
+    'string',
+    'boolean',
+    'json',
+    'buffer',
+  ]
+  const kind = known.find(k => k === declared) ?? 'string'
+  if (kind === 'string' && RX_DATE_TYPE.test(sqlType.trim())) return 'date'
+  return kind
+}
+
+export function metaOf(
+  constraint: ColumnConstraint | undefined,
+  schemaColumn: TableDetails['columns'][number],
+): ColumnMeta {
+  return {
+    kind: kindOf(constraint?.type, schemaColumn.type ?? ''),
+    // `getConstraints()` when it says anything, `getSchema()`'s NOT NULL flag
+    // otherwise. Both are the database's own answer; the first is the richer
+    // one and the second is never absent.
+    nullable: constraint?.nullable ?? !schemaColumn.notnull,
+    length: constraint?.length,
+    enum: constraint?._enum,
+    // **Not `'default' in constraint`.** That reads as the careful choice —
+    // `DEFAULT NULL` is a real default and is filed as `default: null`, so the
+    // key's presence looks like the honest test. It is not: `parseConstraints`
+    // writes the key on **every** column, defaulted or not, so `in` answered
+    // `true` for all of them.
+    //
+    // That is not cosmetic. `omittableOnInsert` is
+    // `autoIncrement || hasDefault || nullable`, so an always-true `hasDefault`
+    // makes every column omittable — and the insert dialog would happily leave
+    // out a NOT NULL column with no default, to be refused by the database
+    // rather than by the form that knew.
+    //
+    // A column genuinely declared `DEFAULT NULL` reads as having none here. It
+    // loses nothing: such a column is nullable, and `nullable` is the next term
+    // in that same expression.
+    hasDefault: constraint?.default !== null && constraint?.default !== undefined,
+    primary: constraint?.primary ?? schemaColumn.pk,
+    autoIncrement: constraint?.autoIncrement,
+  }
+}
+
+/**
+ * Every table the connection has, with its identity resolved.
+ *
+ * Three round trips, taken per request rather than cached. Convention 6 forbids
+ * an unbounded module cache, and a bounded one would be worse than none here:
+ * the wrong entry is not a slow response, it is a write addressed by a key the
+ * table no longer has. Schema introspection is also exactly what the explorer's
+ * own `/api/_db/schema` call already costs, so a write pays what a page load
+ * pays.
+ */
+export async function introspect(options?: {
+  /**
+   * Take the per-table `COUNT(*)`. The schema listing displays it; nothing
+   * else does, and every write introspects to resolve row identity — so the
+   * default skips a full scan of every table per write.
+   */
+  rowCounts?: boolean
+}): Promise<Map<string, TableFacts>> {
+  const [schema, constraints, indexes] = await Promise.all([
+    connection.getSchema({ rowCounts: options?.rowCounts === true }),
+    connection.getConstraints(),
+    connection.getIndexes(),
+  ])
+
+  const byTable = new Map<string, TableFacts>()
+  for (const table of schema) {
+    const camel = Case.camel(table.name)
+    const tableConstraints = (constraints[camel] ?? {}) as TableConstraints
+    const raw = tableConstraints as Record<string, unknown>
+
+    const tableIndexes = Object.entries(indexes)
+      .filter(([, index]) => index.table === camel)
+      .map(([name, index]) => ({
+        name,
+        type: index.type,
+        cols: index.cols,
+        rawCols: index.rawCols,
+      }))
+
+    const identity = describeIdentity({
+      name: table.name,
+      constraints: tableConstraints,
+      indexes: tableIndexes,
+      columns: table.columns.map(c => c.name),
+    })
+
+    const columns = table.columns.map(column => {
+      const columnCamel = Case.camel(column.name)
+      const constraint = isColumnKey(columnCamel)
+        ? (raw[columnCamel] as ColumnConstraint | undefined)
+        : undefined
+      return {
+        name: column.name,
+        camel: columnCamel,
+        sqlType: column.type ?? '',
+        meta: metaOf(constraint, column),
+      }
+    })
+
+    const identityCols = new Set(identity.cols)
+    const label =
+      columns.find(c => c.meta.kind === 'string' && !identityCols.has(c.name))
+        ?.name ?? null
+
+    // The adapter's raw spelling where it exists, the camel one where it does
+    // not — shown as it came rather than dropped, so a mismatch is visible
+    // instead of silently missing a column.
+    const tableIndexFacts = tableIndexes.map(index => ({
+      name: index.name,
+      type: index.type,
+      cols: index.cols.map((col, i) => index.rawCols?.[i] ?? col),
+    }))
+
+    byTable.set(table.name, {
+      name: table.name,
+      camel,
+      isView: typeof raw._view === 'string',
+      rowCount: table.rowCount,
+      columns,
+      byName: new Map(columns.map(c => [c.name, c])),
+      identity,
+      indexes: tableIndexFacts,
+      label,
+    })
+  }
+
+  return byTable
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import { definePlugin } from '@bakery-framework/core/plugins'
+import type { AccessConfig } from './access'
+
+/**
+ * Part of this plugin's public surface.
+ *
+ * These are the explorer's own rather than core's `AuthorizeFn`, because the
+ * explorer asks a different question. The dashboard and analytics need to know
+ * *whether* a request is admitted; the explorer edits rows, so it needs to know
+ * *what* the request may do. A boolean cannot carry that.
+ */
+export type { Access, AccessFn, ExplorerUser, ExplorerUsers } from './access'
+
+export interface DbExplorerPluginOptions extends AccessConfig {
+  /**
+   * Register the explorer. Defaults to true; set false to keep it out of a
+   * build entirely.
+   */
+  enabled?: boolean
+}
+
+/**
+ * A database browser and editor at `/_db`: table list, rows, paging, sorting,
+ * inline editing, foreign-key navigation and CSV import.
+ *
+ * **No raw SQL and no DDL.** That is structural, not a mode: there is no
+ * endpoint that runs a statement you supply, and none that creates, drops or
+ * alters a table. What CRUD changed is row data. Where the dashboard gated its
+ * write paths behind an environment flag, the explorer still has no path for
+ * the things it refuses.
+ *
+ * Nobody is admitted until an application says who may come in, and access is
+ * a level rather than a yes:
+ *
+ * ```ts
+ * dbExplorerPlugin({
+ *   users: {
+ *     ops:    { credential: process.env.OPS_KEY!,    access: 'write' },
+ *     oncall: { credential: process.env.ONCALL_KEY!, access: 'read'  },
+ *   },
+ *   authorize: req => (req.session.get('role') === 'admin' ? 'write' : false),
+ * })
+ * ```
+ *
+ * Either door admits and the higher level wins — a session admin presenting a
+ * read-only key is still an admin. With neither configured the explorer admits
+ * nobody, which is the same default it had when it was read-only, and the
+ * reason there is no `writes: true` flag to leave set by accident.
+ *
+ * A `read` caller gets the grid with no edit affordances and a 403 on every
+ * write endpoint. A table with no primary key or unique index is read-only for
+ * everyone: there is no way to name one of its rows, so there is no way to
+ * change one safely.
+ */
+export default function dbExplorerPlugin(
+  options: DbExplorerPluginOptions = {},
+) {
+  const enabled = options.enabled ?? true
+
+  return definePlugin({
+    name: 'db-explorer',
+    async setup() {
+      if (!enabled) return
+      const { setupExplorer } = await import('./setup')
+      setupExplorer({ users: options.users, authorize: options.authorize })
+    },
+  })
+}

package/src/policy.ts

@@ -0,0 +1,45 @@
+/**
+ * How much one request may do.
+ *
+ * These are not rate limits and not tuning knobs — they are the size at which a
+ * request stops being an edit and starts being a migration. The explorer has no
+ * raw-SQL endpoint precisely so that nothing it exposes can rewrite a table in
+ * one call; a `rows` array with no ceiling would put that back, one row at a
+ * time.
+ *
+ * **Over a bound is a 413 with nothing executed.** Not a truncation, and not a
+ * partial apply: a caller who sent 5,000 rows and got "1,000 inserted" has no
+ * way to know which 1,000, and the retry duplicates them.
+ *
+ * The numbers are deliberately round rather than derived. The one real
+ * constraint — the ~32,766 bound parameters a statement may carry — is already
+ * handled below this layer, by `DB.Insert`'s batching.
+ */
+
+export const LIMITS = {
+  /** Rows in one `POST /api/_db/rows`. */
+  insertRows: 1000,
+  /** Edits in one `POST /api/_db/rows/bulk`. */
+  bulkEdits: 1000,
+  /** Keys in one `DELETE /api/_db/rows`. */
+  deleteKeys: 1000,
+  /** Rows in one `POST /api/_db/import` — a spreadsheet, not an edit. */
+  csvRows: 50_000,
+  /** Foreign-key targets resolved in one `POST /api/_db/lookup`. */
+  lookupRefs: 200,
+} as const
+
+export type LimitName = keyof typeof LIMITS
+
+/**
+ * The 413 message for a request that is too big, or `null` if it fits.
+ *
+ * Returns the rejection rather than throwing, and returns it for an
+ * indeterminate count as well (a `keys` that is not an array reads as `NaN`) —
+ * convention 2's shape, applied to a bound rather than to an identity.
+ */
+export function overLimit(limit: LimitName, count: number): string | null {
+  const max = LIMITS[limit]
+  if (Number.isFinite(count) && count <= max) return null
+  return `too many: ${limit} is limited to ${max} per request, got ${count}`
+}

package/src/preview.ts

@@ -0,0 +1,53 @@
+/**
+ * Rolling a transaction back on purpose, and getting an answer out of it.
+ *
+ * **This is a workaround for a gap in the ORM, and it should be read as one.**
+ * `SQLAdapter.transaction()` commits when the callback returns and rolls back
+ * when it throws — there is no third outcome, so there is no way to say "undo
+ * this, and here is what it would have done". A dry run needs exactly that: the
+ * statements have to actually execute (otherwise the report is a guess about
+ * constraints the database has not been asked about), and then not stick.
+ *
+ * So the report rides out on the exception. The transaction rolls back because
+ * the callback threw, `Try.return` catches the signal outside and turns it into
+ * an ordinary response, and anything that is **not** this class is rethrown —
+ * which is the part that has to stay right. A `catch` that swallowed a real
+ * error here would report a failed write as a successful preview.
+ *
+ * The honest fix is a `transaction()` that takes a rollback decision from its
+ * callback's return value. When the ORM grows one, this module goes away and
+ * the four endpoints that import it lose an `if`.
+ */
+
+/**
+ * A deliberate rollback carrying its report.
+ *
+ * `status` because two different outcomes need the same mechanism: a dry run
+ * answers 200 with what *would* have happened, and a bulk edit that hit an
+ * optimistic-concurrency conflict answers 409 with what did — and both have to
+ * leave the database untouched, so both have to leave through a throw.
+ */
+export class RollbackSignal<T = unknown> extends Error {
+  constructor(
+    readonly report: T,
+    readonly status: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'RollbackSignal'
+  }
+}
+
+/** A dry run: nothing kept, 200 with the report. */
+export function previewRollback<T>(report: T): never {
+  throw new RollbackSignal(report, 200, 'dry run — rolled back')
+}
+
+/** A conflict: nothing kept, 409 with the report. */
+export function conflictRollback<T>(report: T): never {
+  throw new RollbackSignal(report, 409, 'conflict — rolled back')
+}
+
+export function isRollbackSignal(error: unknown): error is RollbackSignal {
+  return error instanceof RollbackSignal
+}