@rangka/core 0.1.0 → 0.1.2

package/src/api/route-generator.ts

@@ -1,448 +0,0 @@
-import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import type { SchemaRegistry } from '../schema/registry.js';
-import type { DatabaseClient } from '../db/client.js';
-import type { PermissionRegistry } from '../auth/permission-registry.js';
-import type { HookRegistry } from '../hooks/registry.js';
-import type { ServiceRegistry } from '../services/registry.js';
-import type { EventBus } from '../events/bus.js';
-import type { ResolvedModel } from '../schema/types.js';
-import { KyselyModelOps } from '../db/model-ops.js';
-import type { ModelOps } from '../model-api/types.js';
-import type { ModelAccessOptions } from '../model-api/types.js';
-import {
-  listHandler,
-  getHandler,
-  createHandler,
-  updateHandler,
-  deleteHandler,
-} from './handlers.js';
-import { createAuthHook, createSessionHandler, deleteSessionHandler } from '../auth/session.js';
-import { createModelPermissionGuard } from '../auth/model-permissions.js';
-import { createScopeHook, createScopeWriteGuard } from '../auth/scopes.js';
-import type { ScopeRegistry } from '../auth/scope-registry.js';
-import { createFieldWriteGuard, createFieldStripHook } from '../auth/field-permissions.js';
-import { withHooksCreate, withHooksUpdate, withHooksDelete } from '../hooks/middleware.js';
-import {
-  modelToSchemaComponent,
-  modelToCreateSchema,
-  modelToUpdateSchema,
-} from './openapi-schema.js';
-import { createMetaBootHandler } from './meta-handler.js';
-import type { MetaBootContext } from './meta-handler.js';
-import type { ModuleConfig, PageDefinition, WidgetDefinitionMeta } from '@rangka/shared';
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-export interface RouteGeneratorOptions {
-  permissionRegistry?: PermissionRegistry;
-  hookRegistry?: HookRegistry;
-  serviceRegistry?: ServiceRegistry;
-  eventBus?: EventBus;
-  scopeRegistry?: ScopeRegistry;
-  config?: Record<string, unknown>;
-  pages?: Array<{ module: string; page: PageDefinition }>;
-  modules?: ModuleConfig[];
-  widgets?: WidgetDefinitionMeta[];
-  adapterRegistry?: import('../plugins/adapter-registry.js').AdapterRegistry;
-  adapterCapabilities?: Record<string, import('../plugins/types.js').AdapterCapability[]>;
-}
-
-/** Context passed to lifecycle hook middleware (create/update/delete with hooks). */
-interface HookMiddlewareContext {
-  model: ResolvedModel;
-  registry: SchemaRegistry;
-  db: import('kysely').Kysely<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
-  ops: ModelOps;
-  hookRegistry: HookRegistry;
-  serviceRegistry?: ServiceRegistry;
-  eventBus?: EventBus;
-  config: Record<string, unknown>;
-}
-
-/** Context for registering all routes belonging to a single model. */
-interface ModelRouteContext {
-  registry: SchemaRegistry;
-  db: DatabaseClient;
-  permissionRegistry?: PermissionRegistry;
-  hookRegistry?: HookRegistry;
-  serviceRegistry?: ServiceRegistry;
-  eventBus?: EventBus;
-  scopeRegistry?: ScopeRegistry;
-  config: Record<string, unknown>;
-}
-
-/** Extended context for external model routes. */
-interface ExternalModelRouteContext extends ModelRouteContext {
-  adapterRegistry?: import('../plugins/adapter-registry.js').AdapterRegistry;
-  adapterCapabilities?: Record<string, import('../plugins/types.js').AdapterCapability[]>;
-}
-
-// ─── Main entry point ────────────────────────────────────────────────────────
-
-/**
- * Registers all REST routes for every model in the schema registry,
- * plus session and meta routes.
- */
-export function generateRoutes(
-  server: FastifyInstance,
-  registry: SchemaRegistry,
-  db: DatabaseClient,
-  options?: RouteGeneratorOptions,
-): void {
-  const permissionRegistry = options?.permissionRegistry;
-  const hookRegistry = options?.hookRegistry;
-  const serviceRegistry = options?.serviceRegistry;
-  const eventBus = options?.eventBus;
-  const scopeRegistry = options?.scopeRegistry;
-  const config = options?.config ?? {};
-
-  registerSessionRoutes(server, db, permissionRegistry);
-  registerMetaRoute(server, db, registry, permissionRegistry, options);
-
-  for (const [module, models] of registry.getModelsByModule()) {
-    for (const model of models) {
-      // Session model has dedicated routes above; skip it here.
-      if (model.qualifiedName === 'core.session') continue;
-
-      if (model.source) {
-        registerExternalModelRoutes(server, model, module, {
-          registry,
-          db,
-          permissionRegistry,
-          hookRegistry,
-          serviceRegistry,
-          eventBus,
-          scopeRegistry,
-          config,
-          adapterRegistry: options?.adapterRegistry,
-          adapterCapabilities: options?.adapterCapabilities,
-        });
-      } else {
-        registerModelRoutes(server, model, module, {
-          registry,
-          db,
-          permissionRegistry,
-          hookRegistry,
-          serviceRegistry,
-          eventBus,
-          scopeRegistry,
-          config,
-        });
-      }
-    }
-  }
-}
-
-// ─── Session routes (login/logout) ───────────────────────────────────────────
-
-function registerSessionRoutes(
-  server: FastifyInstance,
-  db: DatabaseClient,
-  permissionRegistry?: PermissionRegistry,
-) {
-  server.post('/api/core/session', createSessionHandler(db));
-
-  if (permissionRegistry) {
-    server.delete('/api/core/session', {
-      onRequest: createAuthHook(db, permissionRegistry),
-      handler: deleteSessionHandler(db),
-    });
-  }
-}
-
-// ─── Meta boot route (provides UI shell config) ─────────────────────────────
-
-function registerMetaRoute(
-  server: FastifyInstance,
-  db: DatabaseClient,
-  registry: SchemaRegistry,
-  permissionRegistry?: PermissionRegistry,
-  options?: RouteGeneratorOptions,
-) {
-  if (!permissionRegistry || !options?.pages || !options?.modules) return;
-
-  const metaCtx: MetaBootContext = {
-    schemaRegistry: registry,
-    pages: options.pages,
-    modules: options.modules,
-    widgets: options.widgets,
-  };
-
-  server.get('/api/meta/boot', {
-    onRequest: createAuthHook(db, permissionRegistry),
-    schema: { tags: ['meta'] },
-    handler: createMetaBootHandler(metaCtx),
-  });
-}
-
-// ─── Per-model CRUD routes ───────────────────────────────────────────────────
-
-/** Registers list, get, create, update, delete routes for a model. */
-function registerModelRoutes(
-  server: FastifyInstance,
-  model: ResolvedModel,
-  module: string,
-  ctx: ModelRouteContext,
-) {
-  const basePath = `/api/${module}/${model.name}`;
-  const authHooks = buildAuthHooks(model, ctx);
-  const schemas = buildRouteSchemas(model, module);
-  const modelAccessOpts: Omit<ModelAccessOptions, 'auth'> = { db: ctx.db, registry: ctx.registry };
-  const handlerCtx = { model, registry: ctx.registry, db: ctx.db.kysely, modelAccessOpts };
-
-  const modelHasHooks = ctx.hookRegistry?.hasHooks(model.qualifiedName) ?? false;
-  const hookMiddlewareCtx: HookMiddlewareContext = {
-    model,
-    registry: ctx.registry,
-    db: ctx.db.kysely,
-    ops: new KyselyModelOps({ db: ctx.db, model, registry: ctx.registry }),
-    hookRegistry: ctx.hookRegistry!,
-    serviceRegistry: ctx.serviceRegistry,
-    eventBus: ctx.eventBus,
-    config: ctx.config,
-  };
-
-  // Read endpoints
-  server.get(basePath, { ...authHooks, schema: schemas.list, handler: listHandler(handlerCtx) });
-  server.get(`${basePath}/:id`, {
-    ...authHooks,
-    schema: schemas.get,
-    handler: getHandler(handlerCtx),
-  });
-
-  // Write endpoints (use hook middleware when lifecycle hooks are registered)
-  server.post(basePath, {
-    ...authHooks,
-    schema: schemas.create,
-    handler: modelHasHooks ? withHooksCreate(hookMiddlewareCtx) : createHandler(handlerCtx),
-  });
-
-  server.put(`${basePath}/:id`, {
-    ...authHooks,
-    schema: schemas.update,
-    handler: modelHasHooks ? withHooksUpdate(hookMiddlewareCtx) : updateHandler(handlerCtx),
-  });
-
-  server.delete(`${basePath}/:id`, {
-    ...authHooks,
-    schema: schemas.delete,
-    handler: modelHasHooks ? withHooksDelete(hookMiddlewareCtx) : deleteHandler(handlerCtx),
-  });
-}
-
-// ─── External model routes (capability-gated, no hooks) ────────────────────
-
-/** Registers routes for an external model, limited by adapter capabilities. */
-function registerExternalModelRoutes(
-  server: FastifyInstance,
-  model: ResolvedModel,
-  module: string,
-  ctx: ExternalModelRouteContext,
-) {
-  const basePath = `/api/${module}/${model.name}`;
-  const authHooks = buildAuthHooks(model, ctx);
-  const schemas = buildRouteSchemas(model, module);
-  const modelAccessOpts: Omit<ModelAccessOptions, 'auth'> = {
-    db: ctx.db,
-    registry: ctx.registry,
-    adapterRegistry: ctx.adapterRegistry,
-    adapterCapabilities: ctx.adapterCapabilities,
-  };
-  const handlerCtx = { model, registry: ctx.registry, db: ctx.db.kysely, modelAccessOpts };
-
-  const capabilities = new Set(ctx.adapterCapabilities?.[model.source!] ?? ['read']);
-
-  // GET single is always available (read is required for all adapters)
-  server.get(`${basePath}/:id`, {
-    ...authHooks,
-    schema: schemas.get,
-    handler: getHandler(handlerCtx),
-  });
-
-  // GET list requires 'list' capability
-  if (capabilities.has('list') || capabilities.has('read')) {
-    server.get(basePath, { ...authHooks, schema: schemas.list, handler: listHandler(handlerCtx) });
-  }
-
-  // POST create requires 'create' capability
-  if (capabilities.has('create')) {
-    server.post(basePath, {
-      ...authHooks,
-      schema: schemas.create,
-      handler: createHandler(handlerCtx),
-    });
-  }
-
-  // PUT update requires 'update' capability
-  if (capabilities.has('update')) {
-    server.put(`${basePath}/:id`, {
-      ...authHooks,
-      schema: schemas.update,
-      handler: updateHandler(handlerCtx),
-    });
-  }
-
-  // DELETE requires 'delete' capability
-  if (capabilities.has('delete')) {
-    server.delete(`${basePath}/:id`, {
-      ...authHooks,
-      schema: schemas.delete,
-      handler: deleteHandler(handlerCtx),
-    });
-  }
-}
-
-// ─── Auth hook assembly ──────────────────────────────────────────────────────
-
-/** Builds the full set of Fastify auth hooks (onRequest, preHandler, onSend) for a model. */
-function buildAuthHooks(model: ResolvedModel, ctx: ModelRouteContext) {
-  if (!ctx.permissionRegistry) return {};
-
-  const { db, permissionRegistry, scopeRegistry } = ctx;
-
-  const preHandler: Array<(req: FastifyRequest, rep: FastifyReply) => Promise<void>> = [
-    createModelPermissionGuard(model, permissionRegistry),
-  ];
-
-  if (scopeRegistry) {
-    const scopeCtx = { model, scopeRegistry, db };
-    preHandler.push(createScopeHook(scopeCtx));
-    preHandler.push(createScopeWriteGuard(scopeCtx));
-  }
-
-  preHandler.push(createFieldWriteGuard(model));
-
-  return {
-    onRequest: createAuthHook(db, permissionRegistry),
-    preHandler,
-    onSend: createFieldStripHook(model),
-  };
-}
-
-// ─── Route schema definitions ────────────────────────────────────────────────
-
-/** Builds Fastify JSON Schema objects for each CRUD operation on a model. */
-function buildRouteSchemas(model: ResolvedModel, module: string) {
-  const tag = module;
-  const createBody = modelToCreateSchema(model);
-  const updateBody = modelToUpdateSchema(model);
-
-  const idParams = {
-    type: 'object' as const,
-    properties: { id: { type: 'string' as const, description: 'Record ID' } },
-    required: ['id'] as const,
-  };
-
-  const listQuerystring = {
-    type: 'object' as const,
-    properties: {
-      page: { type: 'integer' as const, default: 1, description: 'Page number' },
-      limit: {
-        type: 'integer' as const,
-        default: 25,
-        maximum: 100,
-        description: 'Records per page',
-      },
-      sort: {
-        type: 'string' as const,
-        description: 'Sort fields (prefix with - for descending, comma-separated)',
-      },
-      fields: {
-        type: 'string' as const,
-        description: 'Sparse fieldset (comma-separated field names)',
-      },
-      include: {
-        type: 'string' as const,
-        description: 'Eager-load relations (comma-separated, dot notation for nested)',
-      },
-      includeArchived: {
-        type: 'string' as const,
-        description: 'Include soft-deleted (archived) records (true/false)',
-      },
-      search: {
-        type: 'string' as const,
-        description: 'Search keyword applied across searchable fields',
-      },
-    },
-    additionalProperties: true,
-  };
-
-  return {
-    list: { tags: [tag], querystring: listQuerystring },
-    get: { tags: [tag], params: idParams },
-    create: { tags: [tag], body: createBody },
-    update: { tags: [tag], params: idParams, body: updateBody },
-    delete: { tags: [tag], params: idParams },
-  };
-}
-
-// ─── OpenAPI response schemas ────────────────────────────────────────────────
-
-/** Builds OpenAPI response schemas (200, 201, 400, 404, etc.) for a model's endpoints. */
-export function buildOpenApiResponseSchemas(model: ResolvedModel) {
-  const responseSchema = modelToSchemaComponent(model);
-
-  const errorResponse = {
-    type: 'object' as const,
-    properties: {
-      error: {
-        type: 'object' as const,
-        properties: {
-          code: { type: 'string' as const },
-          message: { type: 'string' as const },
-        },
-      },
-    },
-  };
-
-  const paginationMeta = {
-    type: 'object' as const,
-    properties: {
-      total: { type: 'integer' as const },
-      page: { type: 'integer' as const },
-      limit: { type: 'integer' as const },
-      totalPages: { type: 'integer' as const },
-    },
-  };
-
-  return {
-    list: {
-      200: {
-        description: 'Paginated list',
-        type: 'object' as const,
-        properties: {
-          data: { type: 'array' as const, items: responseSchema },
-          meta: paginationMeta,
-        },
-      },
-    },
-    get: {
-      200: {
-        description: 'Single record',
-        type: 'object' as const,
-        properties: { data: responseSchema },
-      },
-      404: errorResponse,
-    },
-    create: {
-      201: {
-        description: 'Created record',
-        type: 'object' as const,
-        properties: { data: responseSchema },
-      },
-      400: errorResponse,
-    },
-    update: {
-      200: {
-        description: 'Updated record',
-        type: 'object' as const,
-        properties: { data: responseSchema },
-      },
-      404: errorResponse,
-    },
-    delete: {
-      204: { description: 'No content', type: 'null' as const },
-      404: errorResponse,
-    },
-  };
-}

package/src/api/server.ts

@@ -1,147 +0,0 @@
-import Fastify from 'fastify';
-import type { FastifyInstance, FastifyError } from 'fastify';
-import fastifySwagger from '@fastify/swagger';
-import fastifySwaggerUi from '@fastify/swagger-ui';
-import qs from 'qs';
-import type { ServerConfig } from './types.js';
-import { AppError } from '../errors.js';
-
-/**
- * Create and configure the Fastify server instance with JSON parsing,
- * error handling, and optional OpenAPI docs.
- */
-export async function createServer(options?: ServerConfig): Promise<FastifyInstance> {
-  const server = Fastify({
-    logger: options?.logger ?? { level: 'error' },
-    genReqId: () => crypto.randomUUID(),
-    requestIdHeader: options?.requestIdHeader ?? 'x-request-id',
-    routerOptions: {
-      querystringParser: (str) => qs.parse(str),
-    },
-  });
-
-  const docsEnabled = options?.docs !== false;
-  if (docsEnabled) {
-    await registerOpenApiDocs(server, options);
-  }
-
-  registerJsonParser(server);
-  registerErrorHandler(server);
-
-  return server;
-}
-
-/** Register @fastify/swagger and swagger-ui for API documentation. */
-async function registerOpenApiDocs(server: FastifyInstance, options?: ServerConfig): Promise<void> {
-  await server.register(fastifySwagger, {
-    openapi: {
-      openapi: '3.1.0',
-      info: {
-        title: 'Rangka API',
-        version: '1.0.0',
-      },
-      tags: options?.tags ?? [],
-    },
-  });
-
-  await server.register(fastifySwaggerUi, {
-    routePrefix: '/api/docs',
-  });
-}
-
-/** Override the default JSON content-type parser with explicit error handling. */
-function registerJsonParser(server: FastifyInstance): void {
-  server.addContentTypeParser('application/json', { parseAs: 'string' }, (req, body, done) => {
-    try {
-      const str = (body as string).trim();
-      if (!str) {
-        done(null, undefined);
-        return;
-      }
-      const parsed = JSON.parse(str);
-      done(null, parsed);
-    } catch (err: unknown) {
-      done(err as Error, undefined);
-    }
-  });
-}
-
-/** Normalize all errors into a consistent { error: { code, message, details? } } shape. */
-function registerErrorHandler(server: FastifyInstance): void {
-  server.setErrorHandler((error: FastifyError | AppError, request, reply) => {
-    if (error instanceof AppError) {
-      if (error.statusCode >= 500) {
-        request.log.error(
-          { err: error, url: request.url },
-          'AppError %s: %s',
-          error.code,
-          error.message,
-        );
-      }
-      const response: Record<string, unknown> = {
-        error: {
-          code: error.code,
-          message: error.message,
-          ...(error.details !== undefined && { details: error.details }),
-        },
-      };
-      return reply.status(error.statusCode).send(response);
-    }
-
-    // Handle Postgres/database errors with meaningful messages
-
-    const pgCode = (error as unknown as Record<string, unknown>).code;
-    if (typeof pgCode === 'string' && pgCode.match(/^[0-9A-Z]{5}$/)) {
-      const detail = mapPgError(pgCode, error.message);
-      request.log.error({ err: error, url: request.url, pgCode }, 'Database error: %s', detail);
-      return reply.status(500).send({
-        error: { code: 'INTERNAL_ERROR', message: 'An internal error occurred' },
-      });
-    }
-
-    const statusCode = error.statusCode ?? 500;
-    if (statusCode >= 500) {
-      request.log.error({ err: error, url: request.url }, 'Unhandled error: %s', error.message);
-    }
-    const response = {
-      error: {
-        code: error.code ?? 'INTERNAL_ERROR',
-        message: statusCode >= 500 ? 'An internal error occurred' : error.message,
-        ...(error.validation && { details: error.validation }),
-      },
-    };
-    reply.status(statusCode).send(response);
-  });
-}
-
-function mapPgError(code: string, raw: string): string {
-  switch (code) {
-    case '42P01':
-      return `Table does not exist: ${extractRelation(raw)}`;
-    case '42703':
-      return `Column does not exist: ${extractDetail(raw)}`;
-    case '23505':
-      return `Duplicate value violates unique constraint`;
-    case '23503':
-      return `Referenced record does not exist (foreign key violation)`;
-    case '23502':
-      return `Missing required field (not-null violation)`;
-    case '42P02':
-      return `Invalid query parameter`;
-    case '08001':
-    case '08006':
-      return `Database connection failed`;
-    default:
-      return `Database error (${code})`;
-  }
-}
-
-function extractRelation(msg: string): string {
-  const match = msg.match(/relation "([^"]+)"/);
-  return match ? match[1] : 'unknown';
-}
-
-function extractDetail(msg: string): string {
-  const match = msg.match(/column "([^"]+)"/);
-  return match ? match[1] : 'unknown';
-}

package/src/api/types.ts

@@ -1,16 +0,0 @@
-export interface ServerConfig {
-  port?: number;
-  host?: string;
-  logger?: boolean | { level: string };
-  requestIdHeader?: string;
-  docs?: boolean;
-  tags?: Array<{ name: string; description?: string }>;
-}
-
-export interface ApiDefinition {
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-  path: string;
-  roles?: string[];
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  handler: (request: any, reply: any) => Promise<unknown>;
-}