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

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/import.ts

@@ -0,0 +1,89 @@
+/**
+ * CSV import — the rows, not the file.
+ *
+ * The parse happens in `shared/csv.ts`, which the browser runs to show a
+ * preview and the server runs on whatever it is sent. 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.
+ *
+ * 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),
+  )
+}