@facetlayer/prism-framework 0.4.0 → 0.4.1

package/docs/stdin-protocol.md

@@ -0,0 +1,176 @@
+# Stdin/Stdout Protocol
+
+Prism Framework apps can run in **stdin protocol mode** instead of starting an HTTP server. This is useful for:
+
+- Embedding a Prism app as a subprocess in a larger application
+- Composing multiple Prism apps to serve parts of a web UI
+- Running in environments where opening a port is not desirable
+- Building process-based microservice architectures
+
+## How It Works
+
+When started with `--stdin`, the app communicates over **newline-delimited JSON (NDJSON)** on stdin and stdout:
+
+- The parent process sends **request messages** as JSON lines to the app's stdin
+- The app sends **response messages** as JSON lines to its stdout
+- All logging is redirected to stderr so it doesn't interfere with the protocol
+
+The same endpoints defined with `createEndpoint` work identically in both modes.
+
+## Usage
+
+### Setting Up Your App
+
+Use `startStdinServer` as an alternative to `startServer`:
+
+```typescript
+import {
+  createEndpoint, App, startServer, startStdinServer,
+  type ServiceDefinition,
+} from '@facetlayer/prism-framework';
+import { z } from 'zod';
+
+const myService: ServiceDefinition = {
+  name: 'items',
+  endpoints: [
+    createEndpoint({
+      method: 'GET',
+      path: '/items',
+      responseSchema: z.array(z.object({ id: z.string(), name: z.string() })),
+      handler: async () => [{ id: '1', name: 'Item 1' }],
+    }),
+  ],
+};
+
+const app = new App({ services: [myService] });
+
+if (process.argv.includes('--stdin')) {
+  startStdinServer({ app });
+} else {
+  await startServer({ app, port: 3000 });
+}
+```
+
+### Launching as a Subprocess
+
+From the parent process, spawn the app and communicate over pipes:
+
+```typescript
+import { spawn } from 'child_process';
+
+const child = spawn('node', ['my-app.js', '--stdin'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+
+// Send a request
+child.stdin.write(JSON.stringify({
+  id: 'req-1',
+  method: 'GET',
+  path: '/items',
+}) + '\n');
+
+// Read responses line by line
+let buffer = '';
+child.stdout.on('data', (data) => {
+  buffer += data.toString();
+  const lines = buffer.split('\n');
+  buffer = lines.pop();
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const response = JSON.parse(line);
+    console.log('Response:', response);
+  }
+});
+```
+
+## Protocol Specification
+
+### Request Message
+
+Each request is a single JSON line written to the app's stdin:
+
+```json
+{
+  "id": "unique-request-id",
+  "method": "GET",
+  "path": "/items/123",
+  "body": { "optional": "data" }
+}
+```
+
+| Field    | Type   | Required | Description                                    |
+|----------|--------|----------|------------------------------------------------|
+| `id`     | string | Yes      | Unique ID to correlate the response             |
+| `method` | string | Yes      | HTTP method: GET, POST, PUT, DELETE, PATCH      |
+| `path`   | string | Yes      | Endpoint path, e.g. `/items` or `/items/123`    |
+| `body`   | object | No       | Request body / input data                       |
+
+### Response Message
+
+Each response is a single JSON line written to stdout:
+
+```json
+{
+  "id": "unique-request-id",
+  "status": 200,
+  "body": { "id": "123", "name": "Item" }
+}
+```
+
+| Field    | Type   | Description                                    |
+|----------|--------|------------------------------------------------|
+| `id`     | string | Matches the request ID                          |
+| `status` | number | HTTP-style status code (200, 400, 404, 500, etc.) |
+| `body`   | any    | Response data or error details                  |
+
+### Ready Signal
+
+When the app starts, it sends a ready message:
+
+```json
+{ "id": "_ready", "status": 200, "body": { "message": "stdin server ready" } }
+```
+
+Wait for this message before sending requests.
+
+### Error Responses
+
+Errors from handlers (using `NotFoundError`, `BadRequestError`, etc.) are returned with the appropriate status code:
+
+```json
+{ "id": "req-1", "status": 404, "body": { "message": "Item not found" } }
+```
+
+Invalid JSON or missing fields return status 400:
+
+```json
+{ "id": "unknown", "status": 400, "body": { "message": "Invalid JSON" } }
+```
+
+### Process Lifecycle
+
+- The app exits when stdin is closed (EOF)
+- The parent should close stdin to signal the app to shut down
+- All logging output goes to stderr, keeping stdout clean for the protocol
+
+## Composing Multiple Subprocess UIs
+
+A key use case is running multiple Prism apps as subprocesses that each render a portion of a larger web UI. The parent process acts as a coordinator:
+
+```
+┌──────────────────────────────────────────┐
+│           Parent Web Server              │
+│                                          │
+│  ┌─────────────┐  ┌─────────────┐       │
+│  │ App A        │  │ App B        │      │
+│  │ (--stdin)    │  │ (--stdin)    │      │
+│  │ /dashboard/* │  │ /settings/* │       │
+│  └──────┬───────┘  └──────┬──────┘      │
+│         │stdin/stdout      │stdin/stdout  │
+│         └─────────┬────────┘             │
+│                   │                      │
+│         Request Router                   │
+└──────────────────────────────────────────┘
+```
+
+The parent process routes incoming HTTP requests to the appropriate subprocess based on path prefix, translates them to stdin protocol messages, and sends the subprocess responses back to the browser.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@facetlayer/prism-framework",
-  "version": "0.4.0",
-  "description": "Base library and CLI tools for the Prism app framework",
+  "version": "0.4.1",
+  "description": "Base library, server framework, and CLI tools for the Prism app framework",
   "type": "module",
-  "main": "dist/cli.js",
-  "types": "dist/cli.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "prism": "dist/cli.js"
   },
@@ -17,26 +17,59 @@
   },
   "keywords": [
     "framework",
-    "testing",
-    "tools",
-    "typescript"
+    "express",
+    "electron",
+    "typescript",
+    "saas",
+    "tools"
   ],
   "author": "",
   "license": "MIT",
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "README.md"
+  ],
   "packageManager": "pnpm@10.15.1",
   "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.1.0",
     "@facetlayer/doc-files-helper": "0.1.2",
-    "@facetlayer/prism-framework-api": "0.2.0",
     "@facetlayer/qc": "^0.1.0",
+    "@facetlayer/sqlite-wrapper": "^1.2.0",
+    "@facetlayer/streams": "^1.0.0",
+    "cookie-parser": "^1.4.7",
     "dotenv": "^16.4.7",
+    "express": "^4.21.1",
+    "openapi3-ts": "^4.5.0",
+    "prom-client": "^15.1.3",
+    "swagger-ui-express": "^5.0.1",
     "uuid": "^11.1.0",
-    "yargs": "18.0.0"
+    "yargs": "18.0.0",
+    "zod": "^4.1.12"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.0",
+    "zod": "^4.0.5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "zod": {
+      "optional": false
+    }
   },
   "devDependencies": {
     "@facetlayer/build-config-nodejs": "^0.3.0",
+    "@facetlayer/subprocess": "^1.1.1",
+    "@types/cookie-parser": "^1.4.7",
+    "@types/express": "^5.0.0",
     "@types/node": "^22.10.2",
+    "@types/swagger-ui-express": "^4.1.8",
     "@types/uuid": "^10.0.0",
     "@types/yargs": "17.0.34",
+    "esbuild": "^0.25.12",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"
   }

package/src/Errors.ts

@@ -0,0 +1,120 @@
+/*
+Errors
+
+Helper classes for various HTTP error codes.
+*/
+
+export class HttpError extends Error {
+  public statusCode: number;
+  public details?: any;
+
+  constructor(statusCode: number, message: string, details?: any) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = 'HttpError';
+  }
+}
+
+export class BadRequestError extends HttpError {
+  constructor(message: string = 'Bad Request', details?: any) {
+    super(400, message, details);
+    this.name = 'BadRequestError';
+  }
+}
+
+export class SchemaValidationError extends HttpError {
+  constructor(message: string = 'Schema Validation Error', details?: any) {
+    super(422, message, details);
+    this.name = 'SchemaValidationError';
+  }
+}
+
+export class ResponseSchemaValidationError extends HttpError {
+  constructor(message: string = 'Response Schema Validation Error', details?: any) {
+    super(500, message, details);
+    this.name = 'ResponseSchemaValidationError';
+  }
+}
+
+export class UnauthorizedError extends HttpError {
+  constructor(message: string = 'Unauthorized', details?: any) {
+    super(401, message, details);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+export class ForbiddenError extends HttpError {
+  constructor(message: string = 'Forbidden', details?: any) {
+    super(403, message, details);
+    this.name = 'ForbiddenError';
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message: string = 'Not Found', details?: any) {
+    super(404, message, details);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ConflictError extends HttpError {
+  constructor(message: string = 'Conflict', details?: any) {
+    super(409, message, details);
+    this.name = 'ConflictError';
+  }
+}
+
+export class ValidationError extends HttpError {
+  constructor(message: string = 'Validation Error', details?: any) {
+    super(422, message, details);
+    this.name = 'ValidationError';
+  }
+}
+
+export class NotImplementedError extends HttpError {
+  constructor(message: string = 'Not Implemented', details?: any) {
+    super(501, message, details);
+    this.name = 'NotImplementedError';
+  }
+}
+
+export class ServiceUnavailableError extends HttpError {
+  constructor(message: string = 'Service Unavailable', details?: any) {
+    super(503, message, details);
+    this.name = 'ServiceUnavailableError';
+  }
+}
+
+export function createErrorFromStatus(
+  statusCode: number,
+  message?: string,
+  details?: any
+): HttpError {
+  switch (statusCode) {
+    case 400:
+      return new BadRequestError(message, details);
+    case 401:
+      return new UnauthorizedError(message, details);
+    case 403:
+      return new ForbiddenError(message, details);
+    case 404:
+      return new NotFoundError(message, details);
+    case 409:
+      return new ConflictError(message, details);
+    case 422:
+      return new ValidationError(message, details);
+    case 500:
+      return new HttpError(500, message || 'Internal Server Error', details);
+    case 501:
+      return new NotImplementedError(message, details);
+    case 503:
+      return new ServiceUnavailableError(message, details);
+    default:
+      return new HttpError(statusCode, message || 'Unknown Error', details);
+  }
+}
+
+export function isHttpError(error: any): error is HttpError {
+  return error instanceof HttpError;
+}

package/src/Metrics.ts

@@ -0,0 +1,53 @@
+import PromClient from 'prom-client';
+
+let _hasSetupMetrics = false;
+let httpRequests: PromClient.Counter;
+let httpResponses: PromClient.Counter;
+
+export function setupMetrics(): void {
+  _hasSetupMetrics = true;
+
+  PromClient.collectDefaultMetrics({
+    // prefix: ...
+    // labels: ...
+  });
+
+  httpRequests = new PromClient.Counter({
+    name: 'http_request_counter',
+    help: 'HTTP requests',
+    labelNames: ['method', 'endpoint'],
+  });
+  httpResponses = new PromClient.Counter({
+    name: 'http_response_counter',
+    help: 'HTTP responses',
+    labelNames: ['method', 'endpoint', 'status_code', 'duration'],
+  });
+}
+
+// Function to record an HTTP request
+export function recordHttpRequest(method: string, endpoint: string): void {
+  if (!_hasSetupMetrics) {
+    setupMetrics();
+  }
+  httpRequests.inc({ method, endpoint });
+}
+
+export function recordHttpResponse(
+  method: string,
+  endpoint: string,
+  statusCode: number,
+  duration: number
+): void {
+  if (!_hasSetupMetrics) {
+    setupMetrics();
+  }
+  httpResponses.inc({ method, endpoint, status_code: statusCode.toString(), duration });
+}
+
+// Function to get metrics in Prometheus format
+export function getMetrics(): Promise<string> {
+  if (!_hasSetupMetrics) {
+    setupMetrics();
+  }
+  return PromClient.register.metrics();
+}

package/src/RequestContext.ts

@@ -0,0 +1,36 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { Request, Response } from 'express';
+import type { Authorization } from './authorization/Authorization.ts';
+
+/*
+ * RequestContext
+ *
+ * Helper object stored on every incoming request using AsyncLocalStorage.
+ *
+ * Includes
+ *  - The request and response objects
+ *  - Authorization data
+ */
+
+export interface RequestContext {
+  requestId: string;
+  startTime: number;
+  req?: Request;
+  res?: Response;
+  auth: Authorization;
+}
+
+export const requestContextStorage = new AsyncLocalStorage<RequestContext>();
+
+
+export function withRequestContext<T>(context: RequestContext, fn: () => T): T {
+  return requestContextStorage.run(context, fn);
+}
+
+export function getCurrentRequestContext(): RequestContext | undefined {
+  return requestContextStorage.getStore();
+}
+
+export const RequestContext = {
+  getCurrentRequestContext,
+};

package/src/ServiceDefinition.ts

@@ -0,0 +1,35 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { EndpointDefinition } from './web/ExpressEndpointSetup.ts';
+
+export interface MiddlewareDefinition {
+  path: string;
+  handler: (req: Request, res: Response, next: NextFunction) => void;
+}
+
+/*
+ * ServiceDefinition
+ *
+ * A service is a self-contained module that can contain:
+ *  - API endpoints
+ *  - Middleware
+ *  - Database schemas
+ *  - Background jobs
+ */
+
+export interface ServiceDefinition {
+  name: string;
+
+  // API endpoints
+  endpoints?: EndpointDefinition[];
+
+  // Middleware
+  middleware?: MiddlewareDefinition[];
+
+  // Database schemas
+  databases?: Record<string, {
+    statements: string[];
+  }>;
+
+  // Callback used to launch background jobs
+  startJobs?: () => Promise<void>;
+}