@facetlayer/prism-framework 0.4.0 → 0.4.1

package/src/web/ExpressAppSetup.ts

@@ -0,0 +1,125 @@
+import cookieParser from 'cookie-parser';
+import express from 'express';
+import type { Server } from 'http';
+import { PrismApp } from '../app/PrismApp.ts';
+import { getMetrics } from '../Metrics.ts';
+import { corsMiddleware, type CorsConfig } from './corsMiddleware.ts';
+import { mountPrismApp, } from './ExpressEndpointSetup.ts';
+import { localhostOnlyMiddleware } from './localhostOnlyMiddleware.ts';
+import { requestContextMiddleware } from './requestContextMiddleware.ts';
+import { mountOpenAPIEndpoints, type OpenAPIConfig } from './openapi/OpenAPI.ts';
+import { createListingEndpoints } from './EndpointListing.ts';
+import { captureError } from '@facetlayer/streams';
+import { logError, logInfo } from '../logging/index.ts';
+import { validateAppOrThrow } from '../app/validateApp.ts';
+import { setupWebMiddleware, type WebConfig } from './ViteIntegration.ts';
+
+export type { WebConfig } from './ViteIntegration.ts';
+
+export interface ServerSetupConfig {
+  port: number;
+  app: PrismApp;
+  openapiConfig?: OpenAPIConfig;
+  corsConfig?: CorsConfig;
+  /** Serve web files alongside the API. When provided, API endpoints are mounted at /api/. */
+  web?: WebConfig;
+}
+
+export function createExpressApp(config: ServerSetupConfig): express.Application {
+  const app = express();
+
+  app.use(corsMiddleware(config.corsConfig ?? {}));
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+  app.use(requestContextMiddleware);
+  app.use(cookieParser());
+
+  // Create the API router - all API endpoints live under /api/
+  const apiRouter = express.Router();
+
+  // Health check endpoint
+  apiRouter.get('/health', localhostOnlyMiddleware, (req, res) => {
+    res.json({ status: 'ok', timestamp: new Date().toISOString() });
+  });
+
+  // Prometheus metrics endpoint (localhost only)
+  apiRouter.get('/metrics', localhostOnlyMiddleware, async (req, res) => {
+    try {
+      const metrics = await getMetrics();
+      res.set('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+      res.end(metrics);
+    } catch (error) {
+      res.status(500).json({ error: 'Failed to retrieve metrics' });
+    }
+  });
+
+  if (config.openapiConfig) {
+    mountOpenAPIEndpoints(config.openapiConfig, apiRouter, config.app);
+  }
+
+  // Mount endpoint listing endpoints
+  const allEndpoints = config.app.listAllEndpoints();
+  const listingEndpoints = createListingEndpoints(allEndpoints);
+  for (const endpoint of listingEndpoints) {
+    const handler = async (req: express.Request, res: express.Response) => {
+      try {
+        const result = await endpoint.handler({});
+        if (result.sendHttpResponse) {
+          result.sendHttpResponse(res);
+        } else {
+          res.json(result);
+        }
+      } catch (error) {
+        logError('Unhandled error in endpoint', {
+          endpointPath: endpoint.path,
+          error: captureError(error),
+        });
+        res.status(500).json({ error: 'Internal server error' });
+      }
+    };
+    if (endpoint.method === 'GET') {
+      apiRouter.get(endpoint.path, handler);
+    }
+  }
+
+  mountPrismApp(apiRouter, config.app);
+
+  // API 404 handler (only for /api/* routes)
+  apiRouter.use((req: express.Request, res: express.Response) => {
+    res.status(404).json({ error: "Not found" });
+  });
+
+  // Mount the API router at /api
+  app.use('/api', apiRouter);
+
+  return app;
+}
+
+export async function startServer(config: ServerSetupConfig): Promise<Server> {
+  // Validate app configuration before starting
+  validateAppOrThrow(config.app);
+
+  const port = config.port;
+
+  const app = createExpressApp(config);
+
+  // Set up web serving if configured (after API routes)
+  if (config.web) {
+    await setupWebMiddleware(app, config.web);
+  }
+
+  const server = app.listen(port, () => {
+    logInfo(`Server now listening on port ${port}`);
+  });
+
+  // Graceful shutdown
+  process.on('SIGTERM', () => {
+    logInfo('SIGTERM received, shutting down gracefully');
+    server.close(() => {
+      logInfo('Server closed');
+      process.exit(0);
+    });
+  });
+
+  return server;
+}

package/src/web/ExpressEndpointSetup.ts

@@ -0,0 +1,178 @@
+import express, { type NextFunction, type Request, type Response } from 'express';
+import { z } from 'zod';
+import { isHttpError, NotFoundError } from '../Errors.ts';
+import { recordHttpRequest, recordHttpResponse } from '../Metrics.ts';
+import { getCurrentRequestContext } from '../RequestContext.ts';
+import { SseResponse } from './SseResponse.ts';
+import { PrismApp, endpointKey } from '../app/PrismApp.ts';
+import { logError } from '../logging/index.ts';
+
+export { createEndpoint } from '../endpoints/createEndpoint.ts';
+
+type EndpointRequireOption = 'authenticated-user';
+
+export interface EndpointDefinition {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  path: string;
+  handler: (input: any) => Promise<any> | any;
+  requestSchema?: z.ZodSchema;
+  responseSchema?: z.ZodSchema;
+  description?: string;
+  requires?: EndpointRequireOption[];
+  /**
+   * Unique identifier for this endpoint in the OpenAPI schema.
+   * If not provided, one will be generated from the method and path.
+   * Must be unique across all endpoints in the app.
+   */
+  operationId?: string;
+}
+
+export function getRequestDataFromReq(req: Request): any {
+  let result = {};
+
+  if (req.body) {
+    result = { ...result, ...req.body };
+  }
+
+  if (req.params) {
+    result = { ...result, ...req.params };
+  }
+
+  if (req.query) {
+    result = { ...result, ...req.query };
+  }
+
+  return result;
+}
+
+function getOneHandler(
+  prismApp: PrismApp,
+  endpoint: { method: string; path: string }
+) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const startTime = Date.now();
+    const method = req.method;
+    const path = req.path;
+
+    try {
+      recordHttpRequest(method, endpoint.path);
+
+      // TODO: Authentication check
+
+      const inputData = getRequestDataFromReq(req);
+
+      const result = await prismApp.callEndpoint({ method: endpoint.method, path: endpoint.path, input: inputData });
+
+      // TODO: Handle SSE response
+
+      res.status(200).json(result);
+      recordHttpResponse(endpoint.method, endpoint.path, 200, Date.now() - startTime);
+      return;
+    } catch (error) {
+
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+
+      let statusCode = 500;
+
+      if (isHttpError(error)) {
+        statusCode = error.statusCode;
+
+        if (error.statusCode >= 500 || error.statusCode == null) {
+          logError(
+            `Server error in endpoint ${method} ${path}`,
+            {
+              path,
+              method,
+              errorMessage: error.message,
+              stack: error.stack,
+            },
+            error as Error
+          );
+        }
+
+        logDebug(`response ${error.statusCode}: ${method} ${path}`);
+        res.status(error.statusCode).json({
+          message: error.message,
+          details: error.details,
+        });
+      } else {
+        console.error('Unhandled error in endpoint', {
+          path,
+          method,
+          errorMessage: error.message,
+          stack: error.stack,
+        });
+        logError(
+          `Unhandled error in endpoint handler ${method} ${path}`,
+          {
+            path,
+            method,
+            errorMessage: error.message,
+            stack: error.stack,
+          },
+          error as Error
+        );
+        logDebug(`response 500: ${method} ${path}`);
+        res.status(500).json({
+          message: 'Internal Server Error',
+        });
+      }
+
+      recordHttpResponse(method, endpoint.path, statusCode, duration);
+    }
+  };
+}
+
+export function mountPrismApp(
+  app: express.Application | express.Router,
+  prismApp: PrismApp,
+): void {
+  const router = app as express.Router;
+
+  // Register each endpoint with Express to support path parameters
+  const endpoints = prismApp.listAllEndpoints();
+
+  for (const endpoint of endpoints) {
+    const handler = getOneHandler(prismApp, endpoint);
+
+    switch (endpoint.method) {
+      case 'GET':
+        router.get(endpoint.path, handler);
+        break;
+      case 'POST':
+        router.post(endpoint.path, handler);
+        break;
+      case 'PUT':
+        router.put(endpoint.path, handler);
+        break;
+      case 'DELETE':
+        router.delete(endpoint.path, handler);
+        break;
+      case 'PATCH':
+        router.patch(endpoint.path, handler);
+        break;
+    }
+  }
+}
+
+export function mountMiddleware(
+  app: express.Application,
+  middleware: { path: string; handler: (req: Request, res: Response, next: NextFunction) => void }
+): void {
+  app.use(middleware.path, middleware.handler);
+}
+
+export function mountMiddlewares(
+  app: express.Application,
+  middlewares: {
+    path: string;
+    handler: (req: Request, res: Response, next: NextFunction) => void;
+  }[]
+): void {
+  middlewares.forEach(middleware => mountMiddleware(app, middleware));
+}
+function logDebug(_message: string) {
+  // Debug logging - silently ignore for now
+}
+

package/src/web/SseResponse.ts

@@ -0,0 +1,78 @@
+import type { Response } from 'express';
+
+/*
+SseResponse
+
+Helper object used when sending an SSE response.
+*/
+
+export class SseResponse {
+  public response: Response;
+  private isResponseOpen: boolean = true;
+  private _onClose: () => void;
+
+  constructor(response: Response) {
+    this.response = response;
+    this.setupSseHeaders();
+    this.setupCloseHandlers();
+  }
+
+  private setupSseHeaders(): void {
+    this.response.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+  }
+
+  private setupCloseHandlers(): void {
+    this.response.on('close', () => {
+      this._triggerOnClose();
+    });
+
+    this.response.on('finish', () => {
+      this._triggerOnClose();
+    });
+  }
+
+  send(data: object): void {
+    if (!this.isResponseOpen) {
+      return;
+    }
+
+    const jsonData = JSON.stringify(data);
+    this.response.write(`event: item\ndata: ${jsonData}\n\n`);
+  }
+
+  isOpen(): boolean {
+    return this.isResponseOpen;
+  }
+
+  // close() - Can be called by the handler to close the response.
+  close(): void {
+    if (this.isResponseOpen) {
+      // Send done event before closing
+      this.response.write(`event: done\n\n`);
+      this.response.end();
+
+      this._triggerOnClose();
+    }
+  }
+
+  // Internal: Called when the response is closed.
+  _triggerOnClose(): void {
+    this.isResponseOpen = false;
+    if (this._onClose) {
+      this._onClose();
+      this._onClose = null;
+    }
+  }
+
+  // Adds a callback to be called when the response is closed.
+  onClose(callback: () => void): void {
+    if (this._onClose) {
+      throw new Error('usage error: alrady have onClose callback');
+    }
+    this._onClose = callback;
+  }
+}

package/src/web/ViteIntegration.ts

@@ -0,0 +1,72 @@
+/*
+ * ViteIntegration
+ *
+ * Provides web serving capabilities for Prism apps. In development mode,
+ * uses Vite's dev server middleware (if available) for HMR and fast builds.
+ * Falls back to serving static files when Vite is not installed or in production.
+ */
+
+import express from 'express';
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { logInfo } from '../logging/index.ts';
+
+export interface WebConfig {
+  /** Directory containing web files (index.html, etc.). In production, serves from dir/dist if it exists. */
+  dir: string;
+}
+
+/**
+ * Sets up web file serving on the Express app. This should be called AFTER
+ * API routes are mounted so that /api/* takes priority.
+ *
+ * In development (NODE_ENV !== 'production'):
+ *   - Tries to use Vite dev server in middleware mode
+ *   - Falls back to express.static if Vite is not installed
+ *
+ * In production:
+ *   - Serves static files from dir/dist (or dir if dist doesn't exist)
+ *   - SPA fallback: unmatched GET requests serve index.html
+ */
+export async function setupWebMiddleware(
+  expressApp: express.Application,
+  webConfig: WebConfig,
+): Promise<void> {
+  const isDev = process.env.NODE_ENV !== 'production';
+  const webDir = resolve(webConfig.dir);
+
+  if (isDev) {
+    try {
+      // Dynamic import - vite is an optional peer dependency
+      const vite: any = await (Function('return import("vite")')());
+      const viteServer = await vite.createServer({
+        root: webDir,
+        server: { middlewareMode: true },
+        appType: 'spa',
+      });
+      expressApp.use(viteServer.middlewares);
+      logInfo(`Vite dev server middleware attached for ${webDir}`);
+      return;
+    } catch {
+      // Vite not available, fall back to static serving
+    }
+  }
+
+  // Static file serving (production, or dev without Vite)
+  const distDir = join(webDir, 'dist');
+  const serveDir = (!isDev && existsSync(distDir)) ? distDir : webDir;
+
+  expressApp.use(express.static(serveDir));
+
+  // SPA fallback: serve index.html for unmatched GET requests
+  const indexPath = join(serveDir, 'index.html');
+  expressApp.get('*', (req, res) => {
+    if (existsSync(indexPath)) {
+      res.sendFile(indexPath);
+    } else {
+      res.status(404).send('Not found');
+    }
+  });
+
+  logInfo(`Serving static files from ${serveDir}`);
+}

package/src/web/__tests__/OpenAPI.invalidZodSchemas.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { validateServicesForOpenapi } from '../openapi/validateServicesForOpenapi.ts';
+import { generateOpenAPISchema } from '../openapi/OpenAPI.ts';
+import { ServiceDefinition } from '../../ServiceDefinition.ts';
+import { createEndpoint } from '../../endpoints/createEndpoint.ts';
+import { EndpointDefinition } from '../ExpressEndpointSetup.ts';
+
+describe('validateServicesForOpenapi', () => {
+  it('should return empty array for valid schemas', () => {
+    const services: ServiceDefinition[] = [
+      {
+        name: 'test-service',
+        endpoints: [
+          createEndpoint({
+            method: 'GET',
+            path: '/test',
+            requestSchema: z.object({ id: z.string() }),
+            responseSchema: z.object({ result: z.string() }),
+            handler: async () => ({ result: 'ok' }),
+          }),
+        ],
+      },
+    ];
+
+    const result = validateServicesForOpenapi(services);
+
+    expect(result.problemEndpoints).toEqual([]);
+  });
+
+  it('should detect z.lazy() schemas as problematic when not using createEndpoint', () => {
+    // Test the raw validation function with endpoints that haven't been sanitized
+    interface TreeNode {
+      name: string;
+      children?: TreeNode[];
+    }
+
+    const TreeNodeSchema: z.ZodType<TreeNode> = z.lazy(() =>
+      z.object({
+        name: z.string(),
+        children: z.array(TreeNodeSchema).optional(),
+      })
+    );
+
+    // Create endpoint directly without createEndpoint to test raw validation
+    const rawEndpoint: EndpointDefinition = {
+      method: 'GET',
+      path: '/codebase/scan',
+      requestSchema: z.object({ directory: z.string() }),
+      responseSchema: z.object({ tree: TreeNodeSchema }),
+      handler: async () => ({ tree: { name: 'root' } }),
+    };
+
+    const services: ServiceDefinition[] = [
+      {
+        name: 'codebase',
+        endpoints: [rawEndpoint],
+      },
+    ];
+
+    const result = validateServicesForOpenapi(services);
+
+    expect(result.problemEndpoints).toHaveLength(1);
+    expect(result.problemEndpoints[0].path).toBe('/codebase/scan');
+    expect(result.problemEndpoints[0].method).toBe('GET');
+    expect(result.problemEndpoints[0].error.errorMessage).toContain('Unknown zod object type');
+  });
+
+  it('should return empty when createEndpoint sanitizes invalid schemas', () => {
+    // When using createEndpoint, invalid schemas are removed so validation passes
+    interface TreeNode {
+      name: string;
+      children?: TreeNode[];
+    }
+
+    const TreeNodeSchema: z.ZodType<TreeNode> = z.lazy(() =>
+      z.object({
+        name: z.string(),
+        children: z.array(TreeNodeSchema).optional(),
+      })
+    );
+
+    const services: ServiceDefinition[] = [
+      {
+        name: 'codebase',
+        endpoints: [
+          createEndpoint({
+            method: 'GET',
+            path: '/codebase/scan',
+            requestSchema: z.object({ directory: z.string() }),
+            responseSchema: z.object({ tree: TreeNodeSchema }),
+            handler: async () => ({ tree: { name: 'root' } }),
+          }),
+        ],
+      },
+    ];
+
+    // createEndpoint removes the invalid schemas, so validation passes
+    const result = validateServicesForOpenapi(services);
+    expect(result.problemEndpoints).toEqual([]);
+  });
+
+  it('should handle services with no endpoints', () => {
+    const services: ServiceDefinition[] = [
+      {
+        name: 'empty-service',
+        endpoints: [],
+      },
+    ];
+
+    const result = validateServicesForOpenapi(services);
+
+    expect(result.problemEndpoints).toEqual([]);
+  });
+
+  it('should handle undefined endpoints array', () => {
+    const services: ServiceDefinition[] = [
+      {
+        name: 'no-endpoints-service',
+      } as ServiceDefinition,
+    ];
+
+    const result = validateServicesForOpenapi(services);
+
+    expect(result.problemEndpoints).toEqual([]);
+  });
+});
+
+describe('generateOpenAPISchema', () => {
+  it('should succeed when createEndpoint sanitizes invalid schemas', () => {
+    // createEndpoint removes invalid schemas, so OpenAPI generation succeeds
+    interface TreeNode {
+      name: string;
+      children?: TreeNode[];
+    }
+
+    const TreeNodeSchema: z.ZodType<TreeNode> = z.lazy(() =>
+      z.object({
+        name: z.string(),
+        children: z.array(TreeNodeSchema).optional(),
+      })
+    );
+
+    const services: ServiceDefinition[] = [
+      {
+        name: 'test',
+        endpoints: [
+          createEndpoint({
+            method: 'GET',
+            path: '/tree',
+            responseSchema: z.object({ tree: TreeNodeSchema }),
+            handler: async () => ({ tree: { name: 'root' } }),
+          }),
+        ],
+      },
+    ];
+
+    // Should not throw because createEndpoint removed the invalid schema
+    const schema = generateOpenAPISchema(services, {
+      version: '1.0.0',
+      title: 'Test',
+      description: 'Test',
+    });
+
+    expect(schema.openapi).toBe('3.1.0');
+    expect(schema.paths!['/tree']).toBeDefined();
+  });
+
+  it('should throw for raw endpoints with invalid schemas', () => {
+    // Test that raw endpoints (not sanitized by createEndpoint) still throw
+    interface TreeNode {
+      name: string;
+      children?: TreeNode[];
+    }
+
+    const TreeNodeSchema: z.ZodType<TreeNode> = z.lazy(() =>
+      z.object({
+        name: z.string(),
+        children: z.array(TreeNodeSchema).optional(),
+      })
+    );
+
+    const rawEndpoint: EndpointDefinition = {
+      method: 'GET',
+      path: '/tree',
+      responseSchema: z.object({ tree: TreeNodeSchema }),
+      handler: async () => ({ tree: { name: 'root' } }),
+    };
+
+    const services: ServiceDefinition[] = [
+      {
+        name: 'test',
+        endpoints: [rawEndpoint],
+      },
+    ];
+
+    expect(() =>
+      generateOpenAPISchema(services, {
+        version: '1.0.0',
+        title: 'Test',
+        description: 'Test',
+      })
+    ).toThrow('Unknown zod object type');
+  });
+
+  it('should succeed with valid non-recursive schemas', () => {
+    const services: ServiceDefinition[] = [
+      {
+        name: 'test',
+        endpoints: [
+          createEndpoint({
+            method: 'GET',
+            path: '/users',
+            requestSchema: z.object({ id: z.string() }),
+            responseSchema: z.object({
+              user: z.object({
+                id: z.string(),
+                name: z.string(),
+                email: z.string(),
+              }),
+            }),
+            handler: async () => ({
+              user: { id: '1', name: 'Test', email: 'test@example.com' },
+            }),
+          }),
+          createEndpoint({
+            method: 'POST',
+            path: '/users',
+            requestSchema: z.object({
+              name: z.string(),
+              email: z.string(),
+            }),
+            responseSchema: z.object({ id: z.string() }),
+            handler: async () => ({ id: '1' }),
+          }),
+        ],
+      },
+    ];
+
+    const schema = generateOpenAPISchema(services, {
+      version: '1.0.0',
+      title: 'Test API',
+      description: 'Test API Description',
+    });
+
+    expect(schema.openapi).toBe('3.1.0');
+    expect(schema.info.title).toBe('Test API');
+    expect(schema.paths!['/users']).toBeDefined();
+  });
+});