sovrium 0.0.2

package/src/presentation/api/routes/tables/record-handlers.ts

@@ -0,0 +1,484 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import {
+  hasCreatePermission,
+  hasDeletePermission,
+  hasReadPermission,
+} from '@/application/use-cases/tables/permissions/permissions'
+import {
+  createListRecordsProgram,
+  createListTrashProgram,
+  createGetRecordProgram,
+  createRecordProgram,
+  restoreRecordProgram,
+  deleteRecordProgram,
+  permanentlyDeleteRecordProgram,
+} from '@/application/use-cases/tables/programs'
+import { createRecordRequestSchema, updateRecordRequestSchema } from '@/domain/models/api/request'
+import {
+  listRecordsResponseSchema,
+  getRecordResponseSchema,
+  createRecordResponseSchema,
+} from '@/domain/models/api/tables'
+import { runEffect, validateRequest } from '@/presentation/api/utils'
+import { getTableContext } from '@/presentation/api/utils/context-helpers'
+import {
+  validateRecordCreation,
+  createValidationLayer,
+  formatValidationError,
+} from '@/presentation/api/validation'
+import { provideTableLive, runTableProgram } from './effect-runner'
+import { handleRouteError, handleRestoreRecordError } from './error-handlers'
+import { validateFilterParam, validateAggregateParam } from './field-permission-validation'
+import { parseFilter } from './list-records-filter'
+import { parseListRecordsParams } from './param-parsers'
+import {
+  checkTableUpdatePermissionWithRole,
+  filterAllowedFieldsWithRole,
+  handleNoAllowedFields,
+  executeUpdate,
+} from './record-update-handler'
+import { validateSortPermission } from './sort-validation'
+import { validateTimezoneParam } from './timezone-validation'
+import type { App } from '@/domain/models/app'
+import type { Context } from 'hono'
+
+/** Session type derived from table context to respect layer boundaries */
+type SessionContext = ReturnType<typeof getTableContext>['session']
+
+/**
+ * Check read permission for a table based on user role
+ * Returns error response if permission denied, undefined otherwise
+ */
+function checkReadPermission(
+  table: Parameters<typeof hasReadPermission>[0],
+  userRole: string,
+  c: Context,
+  allTables?: App['tables']
+) {
+  if (!hasReadPermission(table, userRole, allTables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to perform this action',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+  return undefined
+}
+
+export async function handleListRecords(c: Context, app: App) {
+  const { session, tableName, userRole } = getTableContext(c)
+  const table = app.tables?.find((t) => t.name === tableName)
+
+  // Check table-level read permission
+  const permissionError = checkReadPermission(table, userRole, c, app.tables)
+  if (permissionError) return permissionError
+
+  const filter = parseFilter(c, app, tableName, userRole)
+  if (filter.error) {
+    return (
+      filter.response ??
+      c.json(
+        { success: false, message: 'Invalid filterByFormula syntax', code: 'VALIDATION_ERROR' },
+        400
+      )
+    )
+  }
+
+  const { includeDeleted, format, timezone, sort, fields, limit, offset, aggregate } =
+    parseListRecordsParams(c)
+
+  const timezoneError = validateTimezoneParam(timezone, c)
+  if (timezoneError) return timezoneError
+
+  const sortError = validateSortPermission({ sort, app, tableName, userRole, c })
+  if (sortError) return sortError
+
+  const filterError = validateFilterParam(filter.value, table, userRole, c)
+  if (filterError) return filterError
+
+  const aggregateError = validateAggregateParam(aggregate, table, userRole, c)
+  if (aggregateError) return aggregateError
+
+  return runEffect(
+    c,
+    provideTableLive(
+      createListRecordsProgram({
+        session,
+        tableName,
+        app,
+        userRole,
+        filter: filter.value,
+        includeDeleted,
+        format,
+        timezone,
+        sort,
+        fields,
+        limit,
+        offset,
+        aggregate,
+      })
+    ),
+    listRecordsResponseSchema
+  )
+}
+
+export async function handleListTrash(c: Context, app: App) {
+  // Session, tableName, and userRole are guaranteed by middleware chain
+  const { session, tableName, userRole } = getTableContext(c)
+  const table = app.tables?.find((t) => t.name === tableName)
+
+  // Check table-level read permission
+  const permissionError = checkReadPermission(table, userRole, c, app.tables)
+  if (permissionError) return permissionError
+
+  // Parse filter parameter
+  const filter = parseFilter(c, app, tableName, userRole)
+  if (filter.error) {
+    return (
+      filter.response ??
+      c.json(
+        { success: false, message: 'Invalid filterByFormula syntax', code: 'VALIDATION_ERROR' },
+        400
+      )
+    )
+  }
+
+  // Parse query parameters (sort, limit, offset)
+  const { sort, limit, offset } = parseListRecordsParams(c)
+
+  // Validate sort permission
+  const sortError = validateSortPermission({ sort, app, tableName, userRole, c })
+  if (sortError) return sortError
+
+  // Validate filter permission
+  const filterError = validateFilterParam(filter.value, table, userRole, c)
+  if (filterError) return filterError
+
+  return runEffect(
+    c,
+    provideTableLive(
+      createListTrashProgram({
+        session,
+        tableName,
+        app,
+        userRole,
+        filter: filter.value,
+        sort,
+        limit,
+        offset,
+      })
+    ),
+    listRecordsResponseSchema
+  )
+}
+
+/**
+ * Check create permission for table and user role
+ * Returns error response if permission denied, undefined otherwise
+ */
+function checkCreatePermission(
+  table: Parameters<typeof hasCreatePermission>[0],
+  userRole: string,
+  c: Context,
+  allTables?: App['tables']
+) {
+  if (!hasCreatePermission(table, userRole, allTables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to create records in this table',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+  return undefined
+}
+
+export async function handleCreateRecord(c: Context, app: App) {
+  // Session, tableName, and userRole are guaranteed by middleware chain
+  const { session, tableName, userRole } = getTableContext(c)
+
+  const result = await validateRequest(c, createRecordRequestSchema)
+  if (!result.success) return result.response
+
+  const table = app.tables?.find((t) => t.name === tableName)
+
+  // Check table-level create permission
+  const permissionError = checkCreatePermission(table, userRole, c, app.tables)
+  if (permissionError) return permissionError
+
+  // Validate fields using Effect-based validation
+  const validationLayer = createValidationLayer(app, tableName, userRole)
+  const program = validateRecordCreation(result.data.fields).pipe(Effect.provide(validationLayer))
+
+  const validationResult = await Effect.runPromise(program.pipe(Effect.either))
+
+  if (validationResult._tag === 'Left') {
+    return formatValidationError(validationResult.left, c)
+  }
+
+  return await runEffect(
+    c,
+    provideTableLive(
+      createRecordProgram({ session, tableName, fields: validationResult.right, app, userRole })
+    ),
+    createRecordResponseSchema,
+    201
+  )
+}
+
+export async function handleGetRecord(c: Context, app: App) {
+  // Session, tableName, and userRole are guaranteed by middleware chain
+  const { session, tableName, userRole } = getTableContext(c)
+  const recordId = c.req.param('recordId')
+  const includeDeleted = c.req.query('includeDeleted') === 'true'
+
+  const table = app.tables?.find((t) => t.name === tableName)
+  if (!hasReadPermission(table, userRole, app.tables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to perform this action',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  try {
+    return await runEffect(
+      c,
+      provideTableLive(
+        createGetRecordProgram({ session, tableName, app, userRole, recordId, includeDeleted })
+      ),
+      getRecordResponseSchema
+    )
+  } catch (error) {
+    return handleRouteError(c, error)
+  }
+}
+
+/**
+ * Validate readonly fields for update request
+ */
+function validateUpdateReadonlyFields(fields: Record<string, unknown>, c: Context) {
+  const READONLY_FIELDS = new Set(['id', 'created_at', 'updated_at'])
+  const attemptedReadonlyFields = Object.keys(fields).filter((field) => READONLY_FIELDS.has(field))
+
+  if (attemptedReadonlyFields.length > 0) {
+    const firstReadonlyField = attemptedReadonlyFields[0]!
+    return c.json(
+      {
+        success: false,
+        message: `Cannot write to readonly field '${firstReadonlyField}'`,
+        code: 'VALIDATION_ERROR',
+      },
+      400
+    )
+  }
+
+  return undefined
+}
+
+/**
+ * Validate forbidden fields for update request
+ */
+function validateUpdateForbiddenFields(
+  forbiddenFields: readonly string[],
+  c: Context
+): Response | undefined {
+  const SYSTEM_PROTECTED_FIELDS = new Set(['user_id'])
+  const attemptedForbiddenFields = forbiddenFields.filter(
+    (field) => !SYSTEM_PROTECTED_FIELDS.has(field)
+  )
+
+  if (attemptedForbiddenFields.length > 0) {
+    const firstForbiddenField = attemptedForbiddenFields[0]!
+    return c.json(
+      {
+        success: false,
+        message: `Cannot write to field '${firstForbiddenField}': insufficient permissions`,
+        code: 'FORBIDDEN',
+        field: firstForbiddenField,
+      },
+      403
+    )
+  }
+
+  return undefined
+}
+
+export async function handleUpdateRecord(c: Context, app: App) {
+  // Session, tableName, and userRole are guaranteed by middleware chain
+  const { session, tableName, userRole } = getTableContext(c)
+
+  const result = await validateRequest(c, updateRecordRequestSchema)
+  if (!result.success) return result.response
+
+  // Check for readonly fields BEFORE permission checks
+  const readonlyValidation = validateUpdateReadonlyFields(result.data.fields, c)
+  if (readonlyValidation) return readonlyValidation
+
+  const permissionCheck = checkTableUpdatePermissionWithRole(app, tableName, userRole, c)
+  if (!permissionCheck.allowed) {
+    return permissionCheck.response
+  }
+
+  // Extract fields from nested format
+  const { allowedData, forbiddenFields } = filterAllowedFieldsWithRole(
+    app,
+    tableName,
+    userRole,
+    result.data.fields
+  )
+
+  // Validate forbidden fields
+  const forbiddenValidation = validateUpdateForbiddenFields(forbiddenFields, c)
+  if (forbiddenValidation) return forbiddenValidation
+
+  if (Object.keys(allowedData).length === 0) {
+    return handleNoAllowedFields({
+      session,
+      tableName,
+      recordId: c.req.param('recordId'),
+      forbiddenFields,
+      c,
+    })
+  }
+
+  return executeUpdate({
+    session,
+    tableName,
+    recordId: c.req.param('recordId'),
+    allowedData,
+    app,
+    userRole,
+    c,
+  })
+}
+
+/**
+ * Execute permanent delete and return response
+ */
+async function executePermanentDelete(
+  session: SessionContext,
+  tableName: string,
+  recordId: string,
+  c: Context
+) {
+  const result = await runTableProgram(permanentlyDeleteRecordProgram(session, tableName, recordId))
+
+  if (result._tag === 'Left' || !result.right) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // eslint-disable-next-line unicorn/no-null -- Hono's c.body() requires null for 204 No Content
+  return c.body(null, 204)
+}
+
+/**
+ * Execute soft delete and return response
+ */
+async function executeSoftDelete({
+  session,
+  tableName,
+  recordId,
+  app,
+  c,
+}: {
+  readonly session: SessionContext
+  readonly tableName: string
+  readonly recordId: string
+  readonly app: App
+  readonly c: Context
+}) {
+  const result = await runTableProgram(deleteRecordProgram(session, tableName, recordId, app))
+
+  if (result._tag === 'Left' || !result.right) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  // eslint-disable-next-line unicorn/no-null -- Hono's c.body() requires null for 204 No Content
+  return c.body(null, 204)
+}
+
+export async function handleDeleteRecord(c: Context, app: App) {
+  // Session, tableName, and userRole are guaranteed by middleware chain
+  const { session, tableName, userRole } = getTableContext(c)
+
+  const table = app.tables?.find((t) => t.name === tableName)
+  if (!hasDeletePermission(table, userRole, app.tables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to delete records in this table',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  const recordId = c.req.param('recordId')
+  const permanent = c.req.query('permanent') === 'true'
+
+  // Permanent delete requires admin role
+  if (permanent) {
+    if (userRole !== 'admin') {
+      return c.json(
+        {
+          success: false,
+          message: 'Only admins can permanently delete records',
+          code: 'FORBIDDEN',
+        },
+        403
+      )
+    }
+
+    return executePermanentDelete(session, tableName, recordId, c)
+  }
+
+  // Regular soft delete
+  return executeSoftDelete({ session, tableName, recordId, app, c })
+}
+
+export async function handleRestoreRecord(c: Context, app: App) {
+  // Session, tableName, and userRole are guaranteed by middleware chain
+  const { session, tableName, userRole } = getTableContext(c)
+
+  const table = app.tables?.find((t) => t.name === tableName)
+  if (!hasDeletePermission(table, userRole, app.tables)) {
+    return c.json(
+      {
+        success: false,
+        message: 'You do not have permission to restore records in this table',
+        code: 'FORBIDDEN',
+      },
+      403
+    )
+  }
+
+  const recordId = c.req.param('recordId')
+
+  const result = await runTableProgram(restoreRecordProgram(session, tableName, recordId))
+
+  if (result._tag === 'Left') {
+    return handleRestoreRecordError(c, result.left)
+  }
+
+  if (!result.right.success) {
+    return c.json({ success: false, message: 'Resource not found', code: 'NOT_FOUND' }, 404)
+  }
+
+  return c.json(result.right, 200)
+}

package/src/presentation/api/routes/tables/record-routes.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { handleGetRecordHistory } from './activity-handlers'
+import {
+  handleCreateComment,
+  handleDeleteComment,
+  handleGetComment,
+  handleListComments,
+  handleUpdateComment,
+} from './comment-handlers'
+import {
+  handleListRecords,
+  handleListTrash,
+  handleCreateRecord,
+  handleGetRecord,
+  handleUpdateRecord,
+  handleDeleteRecord,
+  handleRestoreRecord,
+} from './record-handlers'
+import type { App } from '@/domain/models/app'
+import type { Hono } from 'hono'
+
+/* eslint-disable drizzle/enforce-delete-with-where -- These are Hono route methods, not Drizzle queries */
+
+export function chainRecordRoutesMethods<T extends Hono>(honoApp: T, app: App) {
+  return honoApp
+    .get('/api/tables/:tableId/records', (c) => handleListRecords(c, app))
+    .get('/api/tables/:tableId/trash', (c) => handleListTrash(c, app))
+    .post('/api/tables/:tableId/records', (c) => handleCreateRecord(c, app))
+    .get('/api/tables/:tableId/records/:recordId', (c) => handleGetRecord(c, app))
+    .patch('/api/tables/:tableId/records/:recordId', (c) => handleUpdateRecord(c, app))
+    .delete('/api/tables/:tableId/records/:recordId', (c) => handleDeleteRecord(c, app))
+    .post('/api/tables/:tableId/records/:recordId/restore', (c) => handleRestoreRecord(c, app))
+    .get('/api/tables/:tableId/records/:recordId/history', (c) => handleGetRecordHistory(c, app))
+    .get('/api/tables/:tableId/records/:recordId/comments', (c) => handleListComments(c, app))
+    .post('/api/tables/:tableId/records/:recordId/comments', (c) => handleCreateComment(c, app))
+    .get('/api/tables/:tableId/records/:recordId/comments/:commentId', (c) =>
+      handleGetComment(c, app)
+    )
+    .patch('/api/tables/:tableId/records/:recordId/comments/:commentId', (c) =>
+      handleUpdateComment(c, app)
+    )
+    .delete('/api/tables/:tableId/records/:recordId/comments/:commentId', (c) =>
+      handleDeleteComment(c, app)
+    )
+}
+
+/* eslint-enable drizzle/enforce-delete-with-where */