@facetlayer/prism-framework 0.4.0 → 0.4.1

package/src/__tests__/validateApp.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from 'vitest';
+import { PrismApp } from '../app/PrismApp.ts';
+import { validateApp, validateAppOrThrow } from '../app/validateApp.ts';
+
+describe('validateApp', () => {
+  describe('duplicate operationId detection', () => {
+    it('should pass when all operationIds are unique', () => {
+      const app = new PrismApp({
+        services: [
+          {
+            name: 'test-service',
+            endpoints: [
+              {
+                method: 'GET',
+                path: '/users',
+                operationId: 'getUsers',
+                handler: async () => [],
+              },
+              {
+                method: 'POST',
+                path: '/users',
+                operationId: 'createUser',
+                handler: async () => ({}),
+              },
+              {
+                method: 'GET',
+                path: '/users/:id',
+                operationId: 'getUserById',
+                handler: async () => ({}),
+              },
+            ],
+          },
+        ],
+      });
+
+      const result = validateApp(app);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should fail when endpoints have duplicate explicit operationIds', () => {
+      const app = new PrismApp({
+        services: [
+          {
+            name: 'test-service',
+            endpoints: [
+              {
+                method: 'GET',
+                path: '/users',
+                operationId: 'getUsers',
+                handler: async () => [],
+              },
+              {
+                method: 'GET',
+                path: '/customers',
+                operationId: 'getUsers', // Duplicate!
+                handler: async () => [],
+              },
+            ],
+          },
+        ],
+      });
+
+      const result = validateApp(app);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].message).toContain('Duplicate operationIds');
+      expect(result.errors[0].message).toContain('getUsers');
+    });
+
+    it('should detect duplicates across multiple services', () => {
+      const app = new PrismApp({
+        services: [
+          {
+            name: 'service-a',
+            endpoints: [
+              {
+                method: 'GET',
+                path: '/items',
+                operationId: 'listItems',
+                handler: async () => [],
+              },
+            ],
+          },
+          {
+            name: 'service-b',
+            endpoints: [
+              {
+                method: 'GET',
+                path: '/products',
+                operationId: 'listItems', // Duplicate from service-a
+                handler: async () => [],
+              },
+            ],
+          },
+        ],
+      });
+
+      const result = validateApp(app);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].message).toContain('listItems');
+    });
+
+    it('should pass when auto-generated operationIds are unique', () => {
+      const app = new PrismApp({
+        services: [
+          {
+            name: 'test-service',
+            endpoints: [
+              {
+                method: 'GET',
+                path: '/users',
+                handler: async () => [], // Will auto-generate "getUsers"
+              },
+              {
+                method: 'POST',
+                path: '/users',
+                handler: async () => ({}), // Will auto-generate "postUsers"
+              },
+            ],
+          },
+        ],
+      });
+
+      const result = validateApp(app);
+
+      expect(result.valid).toBe(true);
+    });
+
+    it('should pass for empty app', () => {
+      const app = new PrismApp();
+
+      const result = validateApp(app);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should pass for app with services but no endpoints', () => {
+      const app = new PrismApp({
+        services: [
+          {
+            name: 'empty-service',
+            endpoints: [],
+          },
+        ],
+      });
+
+      const result = validateApp(app);
+
+      expect(result.valid).toBe(true);
+    });
+  });
+});
+
+describe('validateAppOrThrow', () => {
+  it('should not throw for valid app', () => {
+    const app = new PrismApp({
+      services: [
+        {
+          name: 'test-service',
+          endpoints: [
+            {
+              method: 'GET',
+              path: '/users',
+              operationId: 'getUsers',
+              handler: async () => [],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(() => validateAppOrThrow(app)).not.toThrow();
+  });
+
+  it('should throw for app with duplicate operationIds', () => {
+    const app = new PrismApp({
+      services: [
+        {
+          name: 'test-service',
+          endpoints: [
+            {
+              method: 'GET',
+              path: '/users',
+              operationId: 'duplicateId',
+              handler: async () => [],
+            },
+            {
+              method: 'GET',
+              path: '/items',
+              operationId: 'duplicateId',
+              handler: async () => [],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(() => validateAppOrThrow(app)).toThrow('PrismApp validation failed');
+    expect(() => validateAppOrThrow(app)).toThrow('Duplicate operationIds');
+  });
+});

package/src/app/PrismApp.ts

@@ -0,0 +1,117 @@
+import type { EndpointDefinition } from '../web/ExpressEndpointSetup.ts';
+import type { ServiceDefinition } from '../ServiceDefinition.ts';
+import { callEndpoint, type CallEndpointOptions } from './callEndpoint.ts';
+
+export interface PrismAppConfig {
+  name?: string;
+  description?: string;
+  services?: ServiceDefinition[];
+}
+
+export function endpointKey(method: string, path: string): string {
+  return `${method} ${path}`;
+}
+
+export class PrismApp {
+  endpointMap: Map<string, EndpointDefinition>;
+  services: ServiceDefinition[];
+  name: string;
+  description: string;
+
+  constructor(config: PrismAppConfig = {}) {
+    this.name = config.name ?? 'Prism App';
+    this.description = config.description ?? '';
+    this.services = [];
+    this.endpointMap = new Map();
+
+    // Register initial services if provided
+    if (config.services) {
+      for (const service of config.services) {
+        this.addService(service);
+      }
+    }
+  }
+
+  /**
+   * Add a service to the app. Endpoints from the service will be registered
+   * and available for routing.
+   */
+  addService(service: ServiceDefinition): void {
+    this.services.push(service);
+
+    if (service.endpoints) {
+      for (const endpoint of service.endpoints) {
+        const key = endpointKey(endpoint.method, endpoint.path);
+        this.endpointMap.set(key, endpoint);
+      }
+    }
+  }
+
+  getAllServices(): ServiceDefinition[] {
+    return this.services;
+  }
+
+  getEndpoint(method: string, path: string): EndpointDefinition | undefined {
+    const key = endpointKey(method, path);
+    return this.endpointMap.get(key);
+  }
+
+  matchEndpoint(method: string, path: string): { endpoint: EndpointDefinition; params: Record<string, string> } | undefined {
+    // First try exact match
+    const key = endpointKey(method, path);
+    const exactMatch = this.endpointMap.get(key);
+    if (exactMatch) {
+      return { endpoint: exactMatch, params: {} };
+    }
+
+    // Try to match path patterns with parameters
+    for (const [endpointKey, endpoint] of this.endpointMap.entries()) {
+      if (!endpointKey.startsWith(method + ' ')) {
+        continue;
+      }
+
+      const endpointPath = endpoint.path;
+      const match = this.matchPath(endpointPath, path);
+
+      if (match) {
+        return { endpoint, params: match };
+      }
+    }
+
+    return undefined;
+  }
+
+  private matchPath(pattern: string, path: string): Record<string, string> | null {
+    // Convert Express-style path parameters (:param) to regex with named groups
+    const paramNames: string[] = [];
+    const regexString = pattern
+      .replace(/:([^/]+)/g, (_, paramName) => {
+        paramNames.push(paramName);
+        return '([^/]+)';
+      })
+      .replace(/\//g, '\\/');
+
+    const regex = new RegExp(`^${regexString}$`);
+    const match = path.match(regex);
+
+    if (!match) {
+      return null;
+    }
+
+    // Extract parameter values
+    const params: Record<string, string> = {};
+    for (let i = 0; i < paramNames.length; i++) {
+      params[paramNames[i]] = match[i + 1];
+    }
+
+    return params;
+  }
+
+  listAllEndpoints(): EndpointDefinition[] {
+    return Array.from(this.endpointMap.values());
+  }
+
+  callEndpoint(options: CallEndpointOptions): Promise<any> {
+    return callEndpoint(this, options);
+  }
+}

package/src/app/callEndpoint.ts

@@ -0,0 +1,55 @@
+import { PrismApp } from './PrismApp.ts';
+import type { ServiceDefinition } from '../ServiceDefinition.ts';
+import { isHttpError, ResponseSchemaValidationError, SchemaValidationError } from '../Errors.ts';
+
+export interface CallEndpointOptions {
+  method: string;
+  path: string;
+  input?: any;
+  onResponseSchemaFail?: (error: any, result: any) => void;
+}
+
+/**
+ * Call an endpoint programmatically without going through HTTP
+ * This is useful for testing or for calling endpoints from scripts/tools
+ */
+export async function callEndpoint(app: PrismApp, options: CallEndpointOptions) {
+    // Find the endpoint using pattern matching
+    const match = app.matchEndpoint(options.method, options.path);
+
+    if (!match) {
+      throw new Error(`Endpoint not found: ${options.method} ${options.path}`);
+    }
+
+    const { endpoint, params } = match;
+
+    // Merge path parameters with input data
+    let input = { ...params, ...(options.input || {}) };
+
+    // Validate input if schema is provided
+    if (endpoint.requestSchema) {
+      const validationResult = endpoint.requestSchema.safeParse(input);
+      if (!validationResult.success) {
+        throw new SchemaValidationError('Schema validation failed', validationResult.error.issues);
+      }
+      input = validationResult.data;
+    }
+
+    // Call the handler
+    const result = await endpoint.handler(input);
+
+    // Validate output if schema is provided
+    if (endpoint.responseSchema) {
+      const validationResult = endpoint.responseSchema.safeParse(result);
+      if (!validationResult.success) {
+        const error = new ResponseSchemaValidationError('Response schema validation failed', validationResult.error.issues);
+        if (options.onResponseSchemaFail) {
+          options.onResponseSchemaFail(error, result);
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    return result;
+}

package/src/app/validateApp.ts

@@ -0,0 +1,78 @@
+import type { PrismApp } from './PrismApp.ts';
+import { getEffectiveOperationId } from '../endpoints/createEndpoint.ts';
+
+export interface ValidationError {
+    message: string;
+    endpoints?: string[];
+}
+
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+
+/**
+ * Validates a PrismApp configuration, checking for issues like duplicate operationIds.
+ * This should be run at server startup to catch configuration errors early.
+ */
+export function validateApp(app: PrismApp): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    // Check for duplicate operationIds
+    const duplicateError = checkDuplicateOperationIds(app);
+    if (duplicateError) {
+        errors.push(duplicateError);
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+
+/**
+ * Checks for duplicate operationIds across all endpoints.
+ * Returns an error if duplicates are found, null otherwise.
+ */
+function checkDuplicateOperationIds(app: PrismApp): ValidationError | null {
+    const endpoints = app.listAllEndpoints();
+    const operationIdToEndpoints = new Map<string, string[]>();
+
+    for (const endpoint of endpoints) {
+        const operationId = getEffectiveOperationId(endpoint);
+        const endpointKey = `${endpoint.method} ${endpoint.path}`;
+
+        const existing = operationIdToEndpoints.get(operationId) || [];
+        existing.push(endpointKey);
+        operationIdToEndpoints.set(operationId, existing);
+    }
+
+    // Find duplicates
+    const duplicates: string[] = [];
+    for (const [operationId, endpointKeys] of operationIdToEndpoints) {
+        if (endpointKeys.length > 1) {
+            duplicates.push(`operationId "${operationId}" is used by: ${endpointKeys.join(', ')}`);
+        }
+    }
+
+    if (duplicates.length > 0) {
+        return {
+            message: `Duplicate operationIds found. Each endpoint must have a unique operationId.\n${duplicates.join('\n')}`,
+            endpoints: duplicates,
+        };
+    }
+
+    return null;
+}
+
+/**
+ * Validates the app and throws an error if validation fails.
+ * Use this at server startup to ensure the app is properly configured.
+ */
+export function validateAppOrThrow(app: PrismApp): void {
+    const result = validateApp(app);
+    if (!result.valid) {
+        const errorMessages = result.errors.map(e => e.message).join('\n\n');
+        throw new Error(`PrismApp validation failed:\n${errorMessages}`);
+    }
+}

package/src/authorization/AuthSource.ts

@@ -0,0 +1,14 @@
+
+/*
+ * An 'auth source' is a verified authentication token or session that has been
+ * extracted from a request. This represents the source of identity for authorization
+ * decisions. Examples: a validated session cookie, a verified API key, etc.
+ */
+export interface AuthSource {
+  type: string;
+}
+
+export interface CookieAuthSource extends AuthSource {
+  type: 'cookie';
+  sessionId: string;
+}

package/src/authorization/Authorization.ts

@@ -0,0 +1,78 @@
+import type { CookieAuthSource, AuthSource } from './AuthSource.ts';
+import type { Resource } from './Resource.ts';
+
+// Base permission type - applications can extend this
+export type Permission = string;
+
+export interface UserPermissions {
+  userId: string;
+  permissions: Permission[];
+}
+
+/*
+ * Authorization
+ *
+ * Contains all of the authorization data for a single request.
+ * Stored on every RequestContext.
+ *
+ * This includes:
+ *  - The verified 'auth sources' which are the original source of all authorization.
+ *  - The 'resources' which this request has been granted access to.
+ *  - The 'permissions' which are fine-level permissions that the request has been granted.
+ */
+export class Authorization {
+  private resources: Map<Resource['type'], Resource>;
+  private authSources: AuthSource[];
+  private userPermissions?: UserPermissions;
+
+  constructor(resources: Resource[] = [], authSources: AuthSource[] = []) {
+    this.resources = new Map();
+    for (const resource of resources) {
+      this.resources.set(resource.type, resource);
+    }
+    this.authSources = [...authSources];
+  }
+
+  addResource(resource: Resource): void {
+    this.resources.set(resource.type, resource);
+  }
+
+  hasResource(type: Resource['type']): boolean {
+    return this.resources.has(type);
+  }
+
+  getResource(type: Resource['type']): Resource | undefined {
+    return this.resources.get(type);
+  }
+
+  getAllResources(): Resource[] {
+    return Array.from(this.resources.values());
+  }
+
+  addAuthSource(authSource: AuthSource): void {
+    this.authSources.push(authSource);
+  }
+
+  getAuthSources(): AuthSource[] {
+    return [...this.authSources];
+  }
+
+  getCookieAuthSource(): CookieAuthSource | undefined {
+    return this.authSources.find((c): c is CookieAuthSource => c.type === 'cookie');
+  }
+
+  setUserPermissions(userPermissions: UserPermissions): void {
+    this.userPermissions = userPermissions;
+  }
+
+  getUserPermissions(): UserPermissions | undefined {
+    return this.userPermissions;
+  }
+
+  hasPermission(permission: Permission): boolean {
+    if (!this.userPermissions) {
+      return false;
+    }
+    return this.userPermissions.permissions.includes(permission);
+  }
+}

package/src/authorization/Resource.ts

@@ -0,0 +1,8 @@
+/*
+ * A 'resource' is a piece of data that the user can have access to.
+ * This can be a user, a project, a session, or something else.
+ */
+export interface Resource {
+  type: 'user' | 'project' | 'session' | 'custom';
+  id: string;
+}

package/src/authorization/index.ts

@@ -0,0 +1,4 @@
+export { Authorization } from './Authorization.ts';
+export type { Permission, UserPermissions } from './Authorization.ts';
+export type { CookieAuthSource, AuthSource } from './AuthSource.ts';
+export type { Resource } from './Resource.ts';

package/src/databases/DatabaseInitializationOptions.ts

@@ -0,0 +1,9 @@
+import type { ServiceDefinition } from '../ServiceDefinition.ts';
+import type { LoadDatabaseFn, MigrationBehavior } from '@facetlayer/sqlite-wrapper';
+
+export interface DatabaseInitializationOptions {
+  migrationBehavior: MigrationBehavior;
+  databasePath: string;
+  services?: ServiceDefinition[];
+  loadDatabase: LoadDatabaseFn;
+}

package/src/databases/DatabaseSetup.ts

@@ -0,0 +1,19 @@
+import type { ServiceDefinition } from '../ServiceDefinition.ts';
+import type { LoadDatabaseFn, MigrationBehavior } from '@facetlayer/sqlite-wrapper';
+
+/*
+ * getStatementsForDatabase
+ *
+ * Returns all of the SQL statements for a given database name from the given services.
+ */
+export function getStatementsForDatabase(
+  databaseName: string,
+  services: ServiceDefinition[]
+): string[] {
+  return (services || [])
+    .map(service => {
+      const databases = service.databases as any;
+      return databases?.[databaseName]?.statements || [];
+    })
+    .flat();
+}

package/src/endpoints/createEndpoint.ts

@@ -0,0 +1,39 @@
+import { logWarn } from "../logging/index.ts";
+import type { EndpointDefinition } from "../web/ExpressEndpointSetup.ts";
+import { validateEndpointForOpenapi } from "../web/openapi/validateServicesForOpenapi.ts";
+import { isValidOperationId } from "./getEffectiveOperationId.ts";
+
+export { getEffectiveOperationId, isValidOperationId, generateOperationIdFromPath } from "./getEffectiveOperationId.ts";
+
+export function createEndpoint(
+    definition: EndpointDefinition
+): EndpointDefinition {
+    // Validate operationId if explicitly provided
+    if (definition.operationId !== undefined && !isValidOperationId(definition.operationId)) {
+        logWarn(`Misconfigured endpoint ${definition.path}: operationId "${definition.operationId}" is not allowed`);
+
+        return {
+            ...definition,
+            handler: () => {
+                throw new Error(`Misconfigured endpoint ${definition.path}: operationId "${definition.operationId}" is not allowed. Use a descriptive unique identifier.`);
+            },
+        }
+    }
+
+    const validationResult = validateEndpointForOpenapi(definition);
+    if (validationResult?.error) {
+        logWarn(`Misconfigured endpoint ${definition.path}: ${validationResult.error.errorMessage}`);
+        // Remove invalid schemas so they don't break OpenAPI generation for the entire service.
+        // The endpoint will still work, but won't appear correctly in OpenAPI docs.
+        return {
+            ...definition,
+            requestSchema: undefined,
+            responseSchema: undefined,
+            handler: () => {
+                throw new Error(`Misconfigured endpoint ${definition.path}: ${validationResult.error.errorMessage}`);
+            },
+        }
+    }
+
+    return definition;
+}