@morojs/moro 1.3.0 → 1.4.0

package/src/core/config/validation.ts

@@ -0,0 +1,145 @@
+// TypeScript-based Configuration Validation
+// Simple validation functions that replace Zod for config system
+
+export class ConfigValidationError extends Error {
+  constructor(
+    public field: string,
+    public value: unknown,
+    message: string
+  ) {
+    super(`Configuration validation failed for '${field}': ${message}`);
+    this.name = 'ConfigValidationError';
+  }
+}
+
+// Type-safe validation functions
+export function validatePort(value: unknown, field = 'port'): number {
+  const num = Number(value);
+  if (isNaN(num) || num < 1 || num > 65535) {
+    throw new ConfigValidationError(field, value, 'Must be a number between 1 and 65535');
+  }
+  return num;
+}
+
+export function validateBoolean(value: unknown, field = 'boolean'): boolean {
+  if (value === 'true' || value === true) return true;
+  if (value === 'false' || value === false) return false;
+  if (value === '1' || value === 1) return true;
+  if (value === '0' || value === 0) return false;
+  throw new ConfigValidationError(field, value, 'Must be a boolean (true/false) or numeric (1/0)');
+}
+
+export function validateNumber(
+  value: unknown,
+  field = 'number',
+  options: { min?: number; max?: number } = {}
+): number {
+  const num = Number(value);
+  if (isNaN(num)) {
+    throw new ConfigValidationError(field, value, 'Must be a valid number');
+  }
+  if (options.min !== undefined && num < options.min) {
+    throw new ConfigValidationError(field, value, `Must be at least ${options.min}`);
+  }
+  if (options.max !== undefined && num > options.max) {
+    throw new ConfigValidationError(field, value, `Must be at most ${options.max}`);
+  }
+  return num;
+}
+
+export function validateString(value: unknown, field = 'string'): string {
+  if (typeof value !== 'string') {
+    throw new ConfigValidationError(field, value, 'Must be a string');
+  }
+  return value;
+}
+
+export function validateUrl(value: unknown, field = 'url'): string {
+  const str = validateString(value, field);
+  try {
+    new URL(str);
+    return str;
+  } catch {
+    throw new ConfigValidationError(field, value, 'Must be a valid URL');
+  }
+}
+
+export function validateEnum<T extends string>(
+  value: unknown,
+  validValues: readonly T[],
+  field = 'enum'
+): T {
+  const str = validateString(value, field);
+  if (!validValues.includes(str as T)) {
+    throw new ConfigValidationError(field, value, `Must be one of: ${validValues.join(', ')}`);
+  }
+  return str as T;
+}
+
+export function validateArray(value: unknown, field = 'array'): unknown[] {
+  if (!Array.isArray(value)) {
+    // Try to parse comma-separated string
+    if (typeof value === 'string') {
+      return value
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+    }
+    throw new ConfigValidationError(field, value, 'Must be an array or comma-separated string');
+  }
+  return value;
+}
+
+export function validateStringArray(value: unknown, field = 'string array'): string[] {
+  const arr = validateArray(value, field);
+  return arr.map((item, index) => validateString(item, `${field}[${index}]`));
+}
+
+export function validateOptional<T>(
+  value: unknown,
+  validator: (value: unknown, field: string) => T,
+  field: string
+): T | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  return validator(value, field);
+}
+
+// Coercion helpers for environment variables
+export function coerceEnvValue(value: string): unknown {
+  // Handle common patterns in environment variables
+
+  // Null/undefined
+  if (value === '' || value === 'null' || value === 'undefined') {
+    return undefined;
+  }
+
+  // Boolean
+  if (value === 'true' || value === 'false') {
+    return value === 'true';
+  }
+
+  // Number (but not if it starts with 0 - could be port, zip code, etc.)
+  if (/^-?\d+(\.\d+)?$/.test(value) && !value.startsWith('0')) {
+    const num = Number(value);
+    if (!isNaN(num)) {
+      return num;
+    }
+  }
+
+  // JSON (for complex objects/arrays)
+  if (
+    (value.startsWith('{') && value.endsWith('}')) ||
+    (value.startsWith('[') && value.endsWith(']'))
+  ) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      // Not valid JSON, treat as string
+    }
+  }
+
+  // Return as string for all other cases
+  return value;
+}

package/src/core/docs/openapi-generator.ts

@@ -2,7 +2,8 @@
 // Extracts route information from intelligent routing and generates OpenAPI 3.0 specs
 
 import { CompiledRoute, RouteSchema } from '../routing';
-import { zodToOpenAPI, generateExampleFromSchema, OpenAPISchema } from './zod-to-openapi';
+import { OpenAPISchema } from './zod-to-openapi';
+import { schemaToOpenAPI, generateExampleFromValidationSchema } from './schema-to-openapi';
 import { createFrameworkLogger } from '../logger';
 
 const logger = createFrameworkLogger('OpenAPIGenerator');
@@ -241,7 +242,7 @@ export class OpenAPIGenerator {
 
     // Path parameters
     if (route.validation?.params) {
-      const paramSchema = zodToOpenAPI(route.validation.params, this.options);
+      const paramSchema = schemaToOpenAPI(route.validation.params, this.options);
       if (paramSchema.properties) {
         for (const [name, schema] of Object.entries(paramSchema.properties)) {
           parameters.push({
@@ -258,7 +259,7 @@ export class OpenAPIGenerator {
 
     // Query parameters
     if (route.validation?.query) {
-      const querySchema = zodToOpenAPI(route.validation.query, this.options);
+      const querySchema = schemaToOpenAPI(route.validation.query, this.options);
       if (querySchema.properties) {
         for (const [name, schema] of Object.entries(querySchema.properties)) {
           const isRequired = querySchema.required?.includes(name) || false;
@@ -276,7 +277,7 @@ export class OpenAPIGenerator {
 
     // Header parameters
     if (route.validation?.headers) {
-      const headerSchema = zodToOpenAPI(route.validation.headers, this.options);
+      const headerSchema = schemaToOpenAPI(route.validation.headers, this.options);
       if (headerSchema.properties) {
         for (const [name, schema] of Object.entries(headerSchema.properties)) {
           const isRequired = headerSchema.required?.includes(name) || false;
@@ -309,9 +310,9 @@ export class OpenAPIGenerator {
       };
     }
 
-    const bodySchema = zodToOpenAPI(route.validation.body, this.options);
+    const bodySchema = schemaToOpenAPI(route.validation.body, this.options);
     const example = this.options.includeExamples
-      ? generateExampleFromSchema(route.validation.body)
+      ? generateExampleFromValidationSchema(route.validation.body)
       : undefined;
 
     return {

package/src/core/docs/schema-to-openapi.ts

@@ -0,0 +1,148 @@
+// Universal Schema to OpenAPI Converter
+// Converts ValidationSchema (Zod, Joi, etc.) to OpenAPI 3.0 schema definitions
+
+import { ValidationSchema } from '../validation/schema-interface';
+import { OpenAPISchema } from './zod-to-openapi';
+import { createFrameworkLogger } from '../logger';
+
+const logger = createFrameworkLogger('SchemaToOpenAPI');
+
+// Check if a schema is a Zod schema
+function isZodSchema(schema: any): boolean {
+  return (
+    schema && typeof schema === 'object' && schema._def && typeof schema.parseAsync === 'function'
+  );
+}
+
+// Check if schema is Joi
+function isJoiSchema(schema: any): boolean {
+  return (
+    schema &&
+    typeof schema === 'object' &&
+    schema.type &&
+    typeof schema.validateAsync === 'function'
+  );
+}
+
+// Convert any ValidationSchema to OpenAPI
+export function schemaToOpenAPI(
+  schema: ValidationSchema,
+  options: { includeExamples?: boolean; includeDescriptions?: boolean } = {}
+): OpenAPISchema {
+  // If it's a Zod schema, use the existing zod converter
+  if (isZodSchema(schema)) {
+    try {
+      // Import zod converter dynamically
+      const { zodToOpenAPI } = require('./zod-to-openapi');
+      return zodToOpenAPI(schema, options);
+    } catch (error) {
+      logger.warn('Zod converter not available, using fallback', String(error));
+    }
+  }
+
+  // If it's a Joi schema, convert from Joi
+  if (isJoiSchema(schema)) {
+    return convertJoiToOpenAPI(schema as any, options);
+  }
+
+  // For other schemas (custom validators, etc.), return a generic object schema
+  logger.debug('Using generic schema conversion for unknown validation type');
+  return {
+    type: 'object',
+    description: options.includeDescriptions ? 'Validated object' : undefined,
+    additionalProperties: true,
+  };
+}
+
+// Generate example from any ValidationSchema
+export function generateExampleFromValidationSchema(schema: ValidationSchema): any {
+  // If it's a Zod schema, use existing example generator
+  if (isZodSchema(schema)) {
+    try {
+      const { generateExampleFromSchema } = require('./zod-to-openapi');
+      return generateExampleFromSchema(schema);
+    } catch (error) {
+      logger.warn('Zod example generator not available', String(error));
+    }
+  }
+
+  // For other schemas, return a generic example
+  return {
+    example: 'Validated data structure',
+  };
+}
+
+// Convert Joi schema to OpenAPI (basic implementation)
+function convertJoiToOpenAPI(
+  joiSchema: any,
+  options: { includeDescriptions?: boolean }
+): OpenAPISchema {
+  const schemaType = joiSchema.type;
+
+  switch (schemaType) {
+    case 'string':
+      return {
+        type: 'string',
+        description: options.includeDescriptions ? joiSchema._description : undefined,
+        minLength: joiSchema._rules?.find((r: any) => r.name === 'min')?.args?.limit,
+        maxLength: joiSchema._rules?.find((r: any) => r.name === 'max')?.args?.limit,
+        pattern: joiSchema._rules?.find((r: any) => r.name === 'pattern')?.args?.regex?.source,
+      };
+
+    case 'number':
+      return {
+        type: 'number',
+        description: options.includeDescriptions ? joiSchema._description : undefined,
+        minimum: joiSchema._rules?.find((r: any) => r.name === 'min')?.args?.limit,
+        maximum: joiSchema._rules?.find((r: any) => r.name === 'max')?.args?.limit,
+      };
+
+    case 'boolean':
+      return {
+        type: 'boolean',
+        description: options.includeDescriptions ? joiSchema._description : undefined,
+      };
+
+    case 'object': {
+      const properties: Record<string, OpenAPISchema> = {};
+      const required: string[] = [];
+
+      if (joiSchema._inner?.children) {
+        for (const child of joiSchema._inner.children) {
+          const key = child.key;
+          properties[key] = convertJoiToOpenAPI(child.schema, options);
+
+          if (child.schema._flags?.presence === 'required') {
+            required.push(key);
+          }
+        }
+      }
+
+      return {
+        type: 'object',
+        properties,
+        required: required.length > 0 ? required : undefined,
+        description: options.includeDescriptions ? joiSchema._description : undefined,
+      };
+    }
+
+    case 'array':
+      return {
+        type: 'array',
+        items: joiSchema._inner?.items?.[0]
+          ? convertJoiToOpenAPI(joiSchema._inner.items[0], options)
+          : { type: 'object' },
+        description: options.includeDescriptions ? joiSchema._description : undefined,
+        minItems: joiSchema._rules?.find((r: any) => r.name === 'min')?.args?.limit,
+        maxItems: joiSchema._rules?.find((r: any) => r.name === 'max')?.args?.limit,
+      };
+
+    default:
+      logger.warn(`Unsupported Joi schema type: ${schemaType}`);
+      return {
+        type: 'object',
+        additionalProperties: true,
+        description: options.includeDescriptions ? 'Complex validation schema' : undefined,
+      };
+  }
+}

package/src/core/docs/zod-to-openapi.ts

@@ -33,6 +33,8 @@ export interface OpenAPISchema {
   maximum?: number;
   minLength?: number;
   maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
   pattern?: string;
   default?: any;
   oneOf?: OpenAPISchema[];

package/src/core/framework.ts

@@ -1,10 +1,9 @@
-// src/core/framework.ts
+// Core Moro Framework with Pluggable WebSocket Adapters
 import { createServer, Server } from 'http';
 import {
   createSecureServer as createHttp2SecureServer,
   createServer as createHttp2Server,
 } from 'http2';
-import { Server as SocketIOServer } from 'socket.io';
 import { EventEmitter } from 'events';
 import { MoroHttpServer, HttpRequest, HttpResponse, middleware } from './http';
 import { Router } from './http';
@@ -16,6 +15,7 @@ import { MoroEventBus } from './events';
 import { createFrameworkLogger, logger as globalLogger } from './logger';
 import { ModuleConfig, InternalRouteDefinition } from '../types/module';
 import { LogLevel, LoggerOptions } from '../types/logger';
+import { WebSocketAdapter, WebSocketAdapterOptions } from './networking/websocket-adapter';
 
 export interface MoroOptions {
   http2?: boolean;
@@ -28,23 +28,27 @@ export interface MoroOptions {
     enabled?: boolean;
     threshold?: number;
   };
-  websocket?: {
-    compression?: boolean;
-    customIdGenerator?: () => string;
-  };
+  websocket?:
+    | {
+        enabled?: boolean;
+        adapter?: WebSocketAdapter;
+        compression?: boolean;
+        customIdGenerator?: () => string;
+        options?: WebSocketAdapterOptions;
+      }
+    | false;
   logger?: LoggerOptions | boolean;
 }
 
 export class Moro extends EventEmitter {
   private httpServer: MoroHttpServer;
   private server: Server | any; // HTTP/2 server type
-  private io: SocketIOServer;
+  private websocketAdapter?: WebSocketAdapter;
   private container: Container;
   private moduleLoader: ModuleLoader;
-  private websocketManager: WebSocketManager;
+  private websocketManager?: WebSocketManager;
   private circuitBreakers = new Map<string, CircuitBreaker>();
   private rateLimiters = new Map<string, Map<string, { count: number; resetTime: number }>>();
-  private ioInstance: SocketIOServer;
   // Enterprise-grade event system
   private eventBus: MoroEventBus;
   // Framework logger
@@ -99,23 +103,12 @@ export class Moro extends EventEmitter {
       this.server = this.httpServer.getServer();
     }
 
-    this.io = new SocketIOServer(this.server, {
-      cors: { origin: '*' },
-      path: '/socket.io/',
-    });
-
-    this.ioInstance = this.io;
     this.container = new Container();
     this.moduleLoader = new ModuleLoader(this.container);
-    this.websocketManager = new WebSocketManager(this.io, this.container);
-
-    // Configure WebSocket advanced features
-    if (options.websocket?.customIdGenerator) {
-      this.websocketManager.setCustomIdGenerator(options.websocket.customIdGenerator);
-    }
 
-    if (options.websocket?.compression) {
-      this.websocketManager.enableCompression();
+    // Setup WebSocket adapter if enabled
+    if (options.websocket !== false) {
+      this.setupWebSockets(options.websocket || {});
     }
 
     // Initialize enterprise event bus
@@ -153,6 +146,71 @@ export class Moro extends EventEmitter {
     this.httpServer.use(this.errorBoundaryMiddleware());
   }
 
+  /**
+   * Setup WebSocket adapter and manager
+   */
+  private async setupWebSockets(wsConfig: any): Promise<void> {
+    try {
+      // Use provided adapter or try to auto-detect
+      if (wsConfig.adapter) {
+        this.websocketAdapter = wsConfig.adapter;
+      } else {
+        this.websocketAdapter = (await this.detectWebSocketAdapter()) || undefined;
+      }
+
+      if (this.websocketAdapter) {
+        await this.websocketAdapter.initialize(this.server, wsConfig.options);
+        this.websocketManager = new WebSocketManager(this.websocketAdapter, this.container);
+
+        // Configure adapter features
+        if (wsConfig.compression) {
+          this.websocketAdapter.setCompression(true);
+        }
+        if (wsConfig.customIdGenerator) {
+          this.websocketAdapter.setCustomIdGenerator(wsConfig.customIdGenerator);
+        }
+
+        this.logger.info(
+          `WebSocket adapter initialized: ${this.websocketAdapter.getAdapterName()}`,
+          'WebSocketSetup'
+        );
+      }
+    } catch (error) {
+      this.logger.warn(
+        'WebSocket setup failed, continuing without WebSocket support',
+        'WebSocketSetup',
+        { error: error instanceof Error ? error.message : String(error) }
+      );
+    }
+  }
+
+  /**
+   * Auto-detect available WebSocket adapter
+   */
+  private async detectWebSocketAdapter(): Promise<WebSocketAdapter | null> {
+    // Try socket.io first
+    try {
+      const { SocketIOAdapter } = await import('./networking/adapters');
+      return new SocketIOAdapter();
+    } catch {
+      // socket.io not available
+    }
+
+    // Try native ws library
+    try {
+      const { WSAdapter } = await import('./networking/adapters');
+      return new WSAdapter();
+    } catch {
+      // ws not available
+    }
+
+    this.logger.warn(
+      'No WebSocket adapter found. Install socket.io or ws for WebSocket support',
+      'AdapterDetection'
+    );
+    return null;
+  }
+
   private requestTrackingMiddleware() {
     return (req: HttpRequest, res: HttpResponse, next: () => void) => {
       const startTime = Date.now();
@@ -206,8 +264,31 @@ export class Moro extends EventEmitter {
   }
 
   // Public API for accessing Socket.IO server
+  /**
+   * Get WebSocket adapter (for backward compatibility)
+   * @deprecated Use getWebSocketAdapter() instead
+   */
   getIOServer() {
-    return this.io;
+    if (!this.websocketAdapter) {
+      throw new Error(
+        'WebSocket adapter not available. Install socket.io or configure a WebSocket adapter.'
+      );
+    }
+    return this.websocketAdapter;
+  }
+
+  /**
+   * Get the WebSocket adapter
+   */
+  getWebSocketAdapter(): WebSocketAdapter | undefined {
+    return this.websocketAdapter;
+  }
+
+  /**
+   * Get the WebSocket manager
+   */
+  getWebSocketManager(): WebSocketManager | undefined {
+    return this.websocketManager;
   }
 
   async loadModule(moduleConfig: ModuleConfig): Promise<void> {
@@ -392,7 +473,7 @@ export class Moro extends EventEmitter {
               : undefined,
             events: moduleEventBus, // Use pre-created event bus
             app: {
-              get: (key: string) => (key === 'io' ? this.ioInstance : undefined),
+              get: (key: string) => (key === 'io' ? this.websocketAdapter : undefined),
             },
           };
           this.logger.debug(`Database available: ${!!requestToUse.database}`, 'Handler', {
@@ -466,7 +547,15 @@ export class Moro extends EventEmitter {
   }
 
   private async setupWebSocketHandlers(config: ModuleConfig): Promise<void> {
-    const namespace = this.io.of(`/${config.name}`);
+    if (!this.websocketAdapter || !this.websocketManager) {
+      this.logger.warn(
+        `Module ${config.name} defines WebSocket handlers but no WebSocket adapter is available`,
+        'WebSocketSetup'
+      );
+      return;
+    }
+
+    const namespace = this.websocketAdapter.createNamespace(`/${config.name}`);
 
     for (const wsConfig of config.websockets || []) {
       await this.websocketManager.registerHandler(namespace, wsConfig, config);
@@ -530,13 +619,17 @@ export class Moro extends EventEmitter {
   // Compatibility method for existing controllers
   set(key: string, value: any): void {
     if (key === 'io') {
-      this.ioInstance = value;
+      // Deprecated: Use websocket adapter instead
+      this.logger.warn(
+        'Setting io instance is deprecated. Use websocket adapter configuration.',
+        'Deprecated'
+      );
     }
   }
 
   get(key: string): any {
     if (key === 'io') {
-      return this.ioInstance;
+      return this.websocketAdapter;
     }
     return undefined;
   }

package/src/core/networking/adapters/index.ts

@@ -0,0 +1,16 @@
+// WebSocket Adapters for Moro Framework
+// Export all available adapters from this centralized location
+
+export { SocketIOAdapter } from './socketio-adapter';
+export { WSAdapter } from './ws-adapter';
+
+// Re-export the adapter interface for convenience
+export type {
+  WebSocketAdapter,
+  WebSocketAdapterOptions,
+  WebSocketNamespace,
+  WebSocketConnection,
+  WebSocketEmitter,
+  WebSocketMiddleware,
+  WebSocketEventHandler,
+} from '../websocket-adapter';