@bakery-framework/plugin-db-explorer 2.0.0-alpha.5 → 2.0.0-alpha.7

package/src/endpoints/common.ts

@@ -0,0 +1,122 @@
+/**
+ * The preamble every write endpoint shares, in the order the checks have to
+ * happen.
+ *
+ *   1. **`currentCanWrite()`** — a `read` caller is refused before the body is
+ *      even parsed, so nothing about the request can influence the answer.
+ *   2. **The body** — JSON, an object, naming a table.
+ *   3. **The table** — 404 if it is not there.
+ *   4. **The identity** — 409 if the table has none. A table with no primary
+ *      key and no all-NOT-NULL unique index is read-only for everyone,
+ *      including a `write` caller, because there is no way to name one of its
+ *      rows. See `identity.ts`.
+ *
+ * Bounds (413) and validation (400) come after, in each endpoint, because they
+ * are about the request's own shape rather than about who is asking.
+ */
+
+import { Case, Try } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import { currentCanWrite } from '../access'
+import { introspect, type TableFacts } from '../identity'
+import type { FieldError } from '../validate'
+
+export type Envelope = JsonResponseData<unknown>
+
+export type WriteStart =
+  | { ok: true; table: TableFacts; body: Record<string, unknown> }
+  | { ok: false; response: Envelope }
+
+/** A 400 carrying every field error, never only the first. */
+export function invalid(errors: FieldError[]): Envelope {
+  return response.json.error(400, 'Invalid request', { errors })
+}
+
+/**
+ * The request body as an object, or `null`.
+ *
+ * `req.json()` rather than core's `processBody`, which answers `{}` for a body
+ * it could not parse — indistinguishable from an empty one, so a truncated
+ * upload would be reported as a missing `table` field.
+ */
+export async function readBody(
+  req: Request,
+): Promise<Record<string, unknown> | null> {
+  const body = await Try.return(
+    async () => (await req.json()) as unknown,
+    null as unknown,
+  )
+  return typeof body === 'object' && body !== null && !Array.isArray(body)
+    ? (body as Record<string, unknown>)
+    : null
+}
+
+/**
+ * Find a table by the name the caller used.
+ *
+ * Raw database name first — that is what `/api/_db/schema` renders and what the
+ * grid sends back. The camel spelling is accepted as well, because a script
+ * written against a typed schema has `orderItems` where the database has
+ * `order_items`, and refusing that would be refusing the ORM's own vocabulary.
+ */
+export function findTable(
+  tables: Map<string, TableFacts>,
+  name: string,
+): TableFacts | undefined {
+  const exact = tables.get(name)
+  if (exact) return exact
+  const camel = Case.camel(name)
+  for (const table of tables.values()) {
+    if (table.camel === camel) return table
+  }
+  return undefined
+}
+
+export async function beginWrite(req: Request): Promise<WriteStart> {
+  // First, and before the body is read. Convention 2: the guard returns the
+  // rejection, and it is the caller's job to return it unchanged.
+  if (!currentCanWrite()) {
+    return {
+      ok: false,
+      response: response.json.error(403, 'This session may read but not write'),
+    }
+  }
+
+  const body = await readBody(req)
+  if (!body) {
+    return {
+      ok: false,
+      response: response.json.error(400, 'Expected a JSON object body'),
+    }
+  }
+
+  const name = body.table
+  if (typeof name !== 'string' || !name) {
+    return {
+      ok: false,
+      response: response.json.error(400, 'table is required'),
+    }
+  }
+
+  const tables = await introspect()
+  const table = findTable(tables, name)
+  if (!table) {
+    return {
+      ok: false,
+      response: response.json.error(404, `No table named ${name}`),
+    }
+  }
+
+  if (table.identity.mode === 'none') {
+    return {
+      ok: false,
+      response: response.json.error(
+        409,
+        `${table.name} is read-only: ${table.identity.reason}`,
+      ),
+    }
+  }
+
+  return { ok: true, table, body }
+}

package/src/endpoints/graph.ts

@@ -0,0 +1,148 @@
+/**
+ * What the grid needs to render a foreign key as something other than a number.
+ *
+ * `/api/_db/graph` is the map, fetched once: every declared foreign key, every
+ * table's identity, and the column worth showing instead of an id.
+ * `/api/_db/lookup` resolves actual references — **batched, one query per
+ * table**, because the shape this replaces is a `fetch` per visible cell, and a
+ * fifty-row page with three foreign keys is a hundred and fifty round trips.
+ */
+
+import { Try } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import { connection } from '@bakery-framework/orm/connection'
+import { qId } from '@bakery-framework/orm/schema-util'
+import { type Identity, introspect, type TableFacts } from '../identity'
+import { overLimit } from '../policy'
+import { findTable, readBody } from './common'
+
+export async function handleGraph(): Promise<JsonResponseData<unknown>> {
+  return await Try.return(
+    async () => {
+      const [tables, foreignKeys] = await Promise.all([
+        introspect(),
+        // Composites are already grouped by the adapter, keyed by the tuple
+        // rather than by constraint name — SQLite reports no name at all.
+        connection.getForeignKeys(),
+      ])
+
+      const identity: Record<string, Identity> = {}
+      const labels: Record<string, string | null> = {}
+      for (const table of tables.values()) {
+        identity[table.name] = table.identity
+        labels[table.name] = table.label
+      }
+
+      return response.json.success('success', {
+        foreignKeys,
+        identity,
+        labels,
+      })
+    },
+    () => response.json.error(500, 'Failed to read the schema graph'),
+  )
+}
+
+export interface LookupRef {
+  table: string
+  key: Record<string, unknown>
+}
+
+export interface LookupResult {
+  table: string
+  key: Record<string, unknown>
+  row: Record<string, unknown> | null
+}
+
+/** A stable string for a set of identity values, for matching rows to refs. */
+function fingerprint(cols: readonly string[], row: Record<string, unknown>) {
+  // `String(...)` rather than the values themselves: the driver may hand back a
+  // `1n` for the `1` that was sent, or a string for a BIGINT, and a lookup that
+  // failed to match on that would render every foreign key as "missing".
+  return cols.map(col => String(row[col] ?? '\0')).join('\x01')
+}
+
+export async function handleLookup(
+  req: Request,
+): Promise<JsonResponseData<unknown>> {
+  const body = await readBody(req)
+  if (!body) return response.json.error(400, 'Expected a JSON object body')
+
+  const refs = body.refs
+  if (!Array.isArray(refs)) {
+    return response.json.error(400, 'refs must be an array')
+  }
+  const over = overLimit('lookupRefs', refs.length)
+  if (over) return response.json.error(413, over)
+  if (!refs.length) return response.json.success('success', { rows: [] })
+
+  return await Try.return(
+    async () => {
+      const tables = await introspect()
+
+      // Grouped first, queried second. One query per *table*, never one per
+      // ref.
+      const byTable = new Map<string, { table: TableFacts; refs: number[] }>()
+      const parsed: (LookupRef | null)[] = refs.map((ref: any, index) => {
+        if (typeof ref?.table !== 'string' || typeof ref?.key !== 'object') {
+          return null
+        }
+        const table = findTable(tables, ref.table)
+        if (!table || table.identity.mode === 'none') return null
+        const group = byTable.get(table.name) ?? { table, refs: [] }
+        group.refs.push(index)
+        byTable.set(table.name, group)
+        return { table: table.name, key: ref.key as Record<string, unknown> }
+      })
+
+      const results: LookupResult[] = refs.map((ref: any, index) => ({
+        table: String(ref?.table ?? ''),
+        key: (parsed[index]?.key ?? {}) as Record<string, unknown>,
+        row: null,
+      }))
+
+      for (const { table, refs: indexes } of byTable.values()) {
+        const cols = table.identity.cols
+        const params: unknown[] = []
+        const groups: string[] = []
+        const wanted = new Map<string, number[]>()
+
+        for (const index of indexes) {
+          const key = parsed[index]!.key
+          // A ref whose key does not name exactly the identity is skipped
+          // rather than widened — a partial key is a predicate over more than
+          // one row, which is the bug `validateKey` refuses for a write and
+          // there is no reason to accept it for a read.
+          if (cols.some(col => !(col in key))) continue
+          groups.push(
+            `(${cols
+              .map(col => {
+                params.push(key[col])
+                return `${qId(col)} = ?`
+              })
+              .join(' AND ')})`,
+          )
+          const print = fingerprint(cols, key)
+          wanted.set(print, [...(wanted.get(print) ?? []), index])
+        }
+        if (!groups.length) continue
+
+        const rows = (await connection
+          .query(
+            `SELECT * FROM ${qId(table.name)} WHERE ${groups.join(' OR ')}`,
+          )
+          .all(...params)) as Record<string, unknown>[]
+
+        for (const row of rows) {
+          for (const index of wanted.get(fingerprint(cols, row)) ?? []) {
+            results[index]!.row = row
+          }
+        }
+      }
+
+      return response.json.success('success', { rows: results })
+    },
+    (error: any) => response.json.error(400, error?.message ?? 'Lookup failed'),
+  )
+}

package/src/endpoints/import.ts

@@ -0,0 +1,89 @@
+/**
+ * CSV import — the rows, not the file.
+ *
+ * The parse happens in the browser, in `shared/csv.ts`, and stays there. This
+ * endpoint takes rows that are already records, so the mapping the user
+ * confirmed in the dialog is what arrives, rather than a file the server
+ * re-guesses the columns of. No CSV text reaches the server at all.
+ *
+ * Two things separate it from `POST /api/_db/rows`, and both are about scale:
+ * the bound is a spreadsheet's worth of rows rather than an edit's, and a bad
+ * row does not have to end the whole import — `onBadRow: 'skip'` reports it and
+ * carries on, which is what a 50,000-row file with three malformed lines needs.
+ */
+
+import { Try } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import { DB } from '@bakery-framework/orm/orm'
+import { overLimit } from '../policy'
+import { isRollbackSignal, previewRollback } from '../preview'
+import { type FieldError, validateInsertRow } from '../validate'
+import { beginWrite, invalid } from './common'
+
+export type OnBadRow = 'stop' | 'skip'
+
+export async function handleImport(
+  req: Request,
+): Promise<JsonResponseData<unknown>> {
+  const start = await beginWrite(req)
+  if (!start.ok) return start.response
+  const { table, body } = start
+
+  const rows = body.rows
+  if (!Array.isArray(rows) || !rows.length) {
+    return response.json.error(400, 'rows must be a non-empty array')
+  }
+  const over = overLimit('csvRows', rows.length)
+  if (over) return response.json.error(413, over)
+
+  const onBadRow: OnBadRow = body.onBadRow === 'skip' ? 'skip' : 'stop'
+  if (body.onBadRow !== 'skip' && body.onBadRow !== 'stop') {
+    // Named explicitly rather than defaulted silently: the two answers differ
+    // in whether a partially-good file gets partially imported, which is the
+    // one decision the caller must have made on purpose.
+    return response.json.error(400, "onBadRow must be 'stop' or 'skip'")
+  }
+
+  const errors: FieldError[] = []
+  const records: Record<string, unknown>[] = []
+  rows.forEach((row, index) => {
+    const validated = validateInsertRow(row, table, index)
+    if (validated.errors.length) {
+      errors.push(...validated.errors)
+      return
+    }
+    records.push(validated.values)
+  })
+
+  // `stop` refuses the whole file before a statement runs — the same "413 with
+  // nothing executed" promise, for a 400.
+  if (onBadRow === 'stop' && errors.length) return invalid(errors)
+
+  const skipped = rows.length - records.length
+  if (!records.length) {
+    return response.json.success('imported', { inserted: 0, skipped, errors })
+  }
+
+  const dryRun = body.dryRun === true
+
+  return await Try.return(
+    async () =>
+      await DB.transaction(async () => {
+        const result = await DB.Insert.into(table.name).values(records).run()
+        const report = {
+          inserted: Number(result.changes ?? 0),
+          skipped,
+          errors,
+        }
+        if (dryRun) previewRollback(report)
+        return response.json.success('imported', report)
+      }),
+    (error: any) => {
+      if (isRollbackSignal(error)) {
+        return response.json.success(error.message, error.report, error.status)
+      }
+      return response.json.error(400, error?.message ?? 'Import failed')
+    },
+  )
+}

package/src/endpoints/read.ts

@@ -0,0 +1,173 @@
+/**
+ * The two read endpoints.
+ *
+ * `/api/_db/schema` now answers with more than the schema: the caller's own
+ * access level, and per table whether it is writable and why not. The client
+ * needs its posture *before* it renders — a grid that draws edit affordances
+ * and then discovers on save that the table has no primary key has already
+ * wasted the user's work.
+ */
+
+import { Try } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import { connection } from '@bakery-framework/orm/connection'
+import { currentAccess, currentCanWrite } from '../access'
+import { type Identity, introspect } from '../identity'
+import { parseFilters } from '../shared/filters'
+
+export interface SchemaColumn {
+  name: string
+  /** The database's own type string, unchanged — what the grid shows. */
+  type: string
+  notnull: boolean
+  pk: boolean
+  /** What the editor coerces against. See `shared/coerce.ts`. */
+  kind: string
+  nullable: boolean
+  length?: number
+  enum?: readonly string[]
+  hasDefault: boolean
+  autoIncrement?: boolean
+}
+
+/** A declared index, as the Structure view lists it. */
+export interface SchemaIndex {
+  name: string
+  type: string
+  cols: string[]
+}
+
+export interface SchemaTable {
+  name: string
+  rowCount: number
+  columns: SchemaColumn[]
+  identity: Identity
+  /**
+   * Declared indexes.
+   *
+   * `introspect()` has always computed these — it walks them to find a usable
+   * unique key when there is no primary key — and used to throw them away here.
+   * The Structure view is the first thing that shows them, and there is no
+   * other endpoint that knows them.
+   */
+  indexes: SchemaIndex[]
+  /** Whether this table is a view. A view has no rows of its own to address. */
+  isView: boolean
+  writable: boolean
+  /** Why not, when `writable` is false. */
+  reason?: string
+}
+
+export interface SchemaReport {
+  access: 'read' | 'write' | false
+  tables: SchemaTable[]
+}
+
+export async function handleSchema(): Promise<JsonResponseData<unknown>> {
+  return await Try.return(
+    async () => {
+      const tables = await introspect()
+      const access = currentAccess()
+      const canWrite = currentCanWrite()
+
+      const report: SchemaReport = {
+        access,
+        tables: [...tables.values()].map(table => {
+          // Two independent reasons a table is not writable, and the caller's
+          // level is reported first because it is the one that applies to
+          // every table at once.
+          const reason = !canWrite
+            ? 'this session may read but not write'
+            : table.identity.reason
+          return {
+            name: table.name,
+            rowCount: table.rowCount,
+            columns: table.columns.map(column => ({
+              name: column.name,
+              type: column.sqlType,
+              notnull: !column.meta.nullable,
+              pk: Boolean(column.meta.primary),
+              kind: column.meta.kind,
+              nullable: column.meta.nullable,
+              length: column.meta.length,
+              enum: column.meta.enum,
+              hasDefault: column.meta.hasDefault,
+              autoIncrement: column.meta.autoIncrement,
+            })),
+            identity: table.identity,
+            indexes: table.indexes,
+            isView: table.isView,
+            writable: canWrite && table.identity.mode !== 'none',
+            reason,
+          }
+        }),
+      }
+
+      return response.json.success('success', report)
+    },
+    () => response.json.error(500, 'Failed to retrieve schema details'),
+  )
+}
+
+/** Table names the way the ORM writes them: identifier characters only. */
+const RX_TABLE_NAME = /^[a-zA-Z0-9_]+$/
+
+/**
+ * Read the `filters` parameter, or say why it cannot be read.
+ *
+ * Split out because it is the one part of this endpoint with a decision in it,
+ * and because both failure modes have to be a 400 rather than a silently empty
+ * filter set: `JSON.parse` throwing on a mangled parameter, and `parseFilters`
+ * rejecting an operator the ORM would otherwise drop. A dropped filter *widens*
+ * the result, and the explorer's Delete acts on a selection made from this
+ * view — see the header of `shared/filters.ts`.
+ */
+function readFilters(
+  url: URL,
+):
+  | { ok: true; filters: Record<string, unknown> }
+  | { ok: false; error: string } {
+  const raw = url.searchParams.get('filters')
+  if (!raw) return { ok: true, filters: {} }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // A hand-edited or truncated query string. Named as such rather than
+    // treated as "no filters", which would answer a question nobody asked.
+    return { ok: false, error: 'filters is not valid JSON' }
+  }
+
+  const checked = parseFilters(parsed)
+  return checked.ok
+    ? { ok: true, filters: checked.filters }
+    : { ok: false, error: checked.error }
+}
+
+export async function handleTableData(
+  url: URL,
+): Promise<JsonResponseData<unknown>> {
+  const tableName = url.searchParams.get('tableName')
+  if (!tableName || !RX_TABLE_NAME.test(tableName)) {
+    return response.json.error(400, 'Invalid table name')
+  }
+
+  const filters = readFilters(url)
+  if (!filters.ok) return response.json.error(400, filters.error)
+
+  return await Try.return(
+    async () => {
+      const data = await connection.getData(tableName, {
+        page: Number.parseInt(url.searchParams.get('page') || '1', 10),
+        pageSize: Number.parseInt(url.searchParams.get('pageSize') || '50', 10),
+        sortBy: url.searchParams.get('sortBy'),
+        sortOrder: url.searchParams.get('sortOrder') || 'ASC',
+        filters: filters.filters,
+      })
+      return response.json.success('success', data)
+    },
+    (error: any) => response.json.error(400, error.message),
+  )
+}