ts-packages 1.0.0

package/packages/server-utils/src/middleware.ts

@@ -0,0 +1,275 @@
+import express from 'express';
+import { ServerPlugin } from './types';
+
+// Logging middleware
+export function createLoggingMiddleware(format: 'simple' | 'detailed' = 'simple'): express.RequestHandler {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const start = Date.now();
+    
+    res.on('finish', () => {
+      const duration = Date.now() - start;
+      
+      if (format === 'detailed') {
+        console.log(`${req.method} ${req.url} - ${res.statusCode} - ${duration}ms - ${req.ip}`);
+      } else {
+        console.log(`${req.method} ${req.url} - ${res.statusCode}`);
+      }
+    });
+    
+    next();
+  };
+}
+
+// Error handling middleware
+export function createErrorHandler(): express.ErrorRequestHandler {
+  return (err: unknown, req: express.Request, res: express.Response, next: express.NextFunction) => {
+    console.error('Error:', err);
+    
+    if (res.headersSent) {
+      return next(err);
+    }
+    
+    // Type guard for error objects
+    const errorObj = err as { status?: number; statusCode?: number; message?: string; stack?: string };
+    
+    const status = errorObj.status || errorObj.statusCode || 500;
+    const message = process.env.NODE_ENV === 'production' 
+      ? 'Internal Server Error' 
+      : errorObj.message || 'Unknown error';
+    
+    res.status(status).json({
+      status: false,
+      message,
+      ...(process.env.NODE_ENV !== 'production' && { stack: errorObj.stack })
+    });
+  };
+}
+
+// Request ID middleware
+export function createRequestIdMiddleware(): express.RequestHandler {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const requestId = Math.random().toString(36).substring(2, 15);
+    (req as express.Request & { requestId: string }).requestId = requestId;
+    res.setHeader('X-Request-ID', requestId);
+    next();
+  };
+}
+
+// Validation middleware
+export interface ValidationRule {
+  field: string;
+  required?: boolean;
+  type?: 'string' | 'number' | 'email' | 'boolean';
+  minLength?: number;
+  maxLength?: number;
+  pattern?: RegExp;
+  custom?: (value: unknown) => boolean | string;
+}
+
+export function createValidationMiddleware(rules: ValidationRule[]): express.RequestHandler {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const errors: string[] = [];
+    
+    for (const rule of rules) {
+      const value = req.body[rule.field];
+      
+      if (rule.required && (value === undefined || value === null || value === '')) {
+        errors.push(`${rule.field} is required`);
+        continue;
+      }
+      
+      if (value === undefined || value === null) continue;
+      
+      if (rule.type) {
+        switch (rule.type) {
+          case 'email':
+            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+            if (!emailRegex.test(value)) {
+              errors.push(`${rule.field} must be a valid email`);
+            }
+            break;
+          case 'string':
+            if (typeof value !== 'string') {
+              errors.push(`${rule.field} must be a string`);
+            }
+            break;
+          case 'number':
+            if (typeof value !== 'number' && isNaN(Number(value))) {
+              errors.push(`${rule.field} must be a number`);
+            }
+            break;
+          case 'boolean':
+            if (typeof value !== 'boolean') {
+              errors.push(`${rule.field} must be a boolean`);
+            }
+            break;
+        }
+      }
+      
+      if (rule.minLength && value.length < rule.minLength) {
+        errors.push(`${rule.field} must be at least ${rule.minLength} characters`);
+      }
+      if (rule.maxLength && value.length > rule.maxLength) {
+        errors.push(`${rule.field} must be no more than ${rule.maxLength} characters`);
+      }
+      
+      if (rule.pattern && !rule.pattern.test(value)) {
+        errors.push(`${rule.field} format is invalid`);
+      }
+      
+      if (rule.custom) {
+        const result = rule.custom(value);
+        if (result !== true) {
+          errors.push(typeof result === 'string' ? result : `${rule.field} is invalid`);
+        }
+      }
+    }
+    
+    if (errors.length > 0) {
+      return res.status(400).json({
+        status: false,
+        message: 'Validation failed',
+        errors
+      });
+    }
+    
+    next();
+  };
+}
+
+// Rate limiting middleware
+export interface RateLimitConfig {
+  windowMs?: number;
+  maxRequests?: number;
+  message?: string;
+  keyGenerator?: (req: express.Request) => string;
+}
+
+const rateLimitStore = new Map<string, { count: number; resetTime: number }>();
+
+export function createRateLimitMiddleware(config: RateLimitConfig = {}): express.RequestHandler {
+  const {
+    windowMs = 15 * 60 * 1000,
+    maxRequests = 100,
+    message = 'Too many requests, please try again later',
+    keyGenerator = (req) => req.ip || 'unknown'
+  } = config;
+  
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const key = keyGenerator(req);
+    const now = Date.now();
+    const record = rateLimitStore.get(key);
+    
+    if (!record || now > record.resetTime) {
+      rateLimitStore.set(key, {
+        count: 1,
+        resetTime: now + windowMs
+      });
+      return next();
+    }
+    
+    if (record.count >= maxRequests) {
+      return res.status(429).json({
+        status: false,
+        message,
+        retryAfter: Math.ceil((record.resetTime - now) / 1000)
+      });
+    }
+    
+    record.count++;
+    next();
+  };
+}
+
+// Authentication middleware helper
+export interface AuthConfig {
+  tokenExtractor?: (req: express.Request) => string | null;
+  tokenValidator?: (token: string) => Promise<unknown> | unknown;
+  unauthorizedMessage?: string;
+}
+
+export function createAuthMiddleware(config: AuthConfig): express.RequestHandler {
+  const {
+    tokenExtractor = (req) => {
+      const authHeader = req.headers.authorization;
+      if (authHeader && authHeader.startsWith('Bearer ')) {
+        return authHeader.substring(7);
+      }
+      return req.cookies?.token || null;
+    },
+    tokenValidator = () => { throw new Error('Token validator not implemented'); },
+    unauthorizedMessage = 'Unauthorized access'
+  } = config;
+  
+  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    try {
+      const token = tokenExtractor(req);
+      
+      if (!token) {
+        return res.status(401).json({
+          status: false,
+          message: unauthorizedMessage
+        });
+      }
+      
+      const user = await tokenValidator(token);
+      (req as express.Request & { user: unknown }).user = user;
+      next();
+    } catch (error) {
+      return res.status(401).json({
+        status: false,
+        message: unauthorizedMessage
+      });
+    }
+  };
+}
+
+// Plugin versions
+export function withLogging(format: 'simple' | 'detailed' = 'simple'): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createLoggingMiddleware(format));
+  };
+}
+
+export function withErrorHandler(): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createErrorHandler());
+  };
+}
+
+export function withRequestId(): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createRequestIdMiddleware());
+  };
+}
+
+export function withValidation(rules: ValidationRule[]): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createValidationMiddleware(rules));
+  };
+}
+
+export function withRateLimit(config: RateLimitConfig = {}): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createRateLimitMiddleware(config));
+  };
+}
+
+export function withAuth(config: AuthConfig): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createAuthMiddleware(config));
+  };
+}
+
+// Convenience functions for route-specific middleware
+export function validateFields(rules: ValidationRule[]): express.RequestHandler {
+  return createValidationMiddleware(rules);
+}
+
+export function rateLimit(config: RateLimitConfig = {}): express.RequestHandler {
+  return createRateLimitMiddleware(config);
+}
+
+export function requireAuth(config: AuthConfig): express.RequestHandler {
+  return createAuthMiddleware(config);
+}

package/packages/server-utils/src/server.ts

@@ -0,0 +1,320 @@
+import express from 'express';
+import { Server } from 'http';
+import { ServerConfig, SocketIOConfig, SocketInstance } from './types';
+import { createGracefulShutdown } from './shutdown';
+import crypto from 'crypto';
+
+export interface GrpcService {
+  service: Record<string, unknown>;
+  implementation: Record<string, (...args: unknown[]) => unknown>;
+}
+
+export interface RpcMethod {
+  [key: string]: (params: unknown[], callback: (error: Error | null, result?: unknown) => void) => void;
+}
+
+export interface WebhookConfig {
+  path: string;
+  secret?: string;
+  handler: (payload: Record<string, unknown>, headers: Record<string, string | string[]>) => void | Promise<void>;
+}
+
+export interface GrpcServerInstance {
+  start(): void;
+  forceShutdown(): void;
+  addService(service: unknown, implementation: unknown): void;
+  bindAsync(address: string, credentials: unknown, callback: () => void): void;
+}
+
+
+
+export interface ServerInstanceConfig extends Required<Omit<ServerConfig, 'socketIO' | 'name' | 'version'>> {
+  name: string;
+  version: string;
+  startTime: Date;
+  socketIO?: SocketIOConfig;
+}
+
+export interface ServerInstance {
+  app: express.Application;
+  server?: Server;
+  config: ServerInstanceConfig;
+  start(): Promise<ServerInstance>;
+  stop(): Promise<void>;
+  getInfo(): ServerInfo;
+
+  // Multi-protocol support
+  addGrpcService(service: Record<string, unknown>, implementation: Record<string, (...args: unknown[]) => unknown>, port?: number): void;
+  addRpcMethods(methods: RpcMethod, path?: string): void;
+  addWebhook(config: WebhookConfig): void;
+  addSocketIO(config?: SocketIOConfig): unknown;
+}
+
+export interface ServerInfo {
+  name: string;
+  version: string;
+  port: number;
+  uptime: number;
+  status: 'starting' | 'running' | 'stopping' | 'stopped';
+  startTime: Date;
+}
+
+export class ExpressServer implements ServerInstance {
+  public app: express.Application;
+  public server?: Server;
+  public config: ServerInstanceConfig;
+  private status: 'starting' | 'running' | 'stopping' | 'stopped' = 'stopped';
+  private grpcServices: GrpcService[] = [];
+  private grpcServer?: GrpcServerInstance;
+  private rpcMethods: RpcMethod = {};
+  private socketIO?: { close(): void };
+
+  constructor(
+    name: string = 'Express Server',
+    version: string = '1.0.0',
+    config: ServerConfig = {}
+  ) {
+    this.app = express();
+    this.config = {
+      name,
+      version,
+      startTime: new Date(),
+      port: config.port || 3000,
+      cors: config.cors ?? true,
+      helmet: config.helmet ?? true,
+      json: config.json ?? true,
+      customMiddleware: config.customMiddleware || [],
+      healthCheck: config.healthCheck ?? true,
+      gracefulShutdown: config.gracefulShutdown ?? true,
+      socketIO: config.socketIO
+    };
+  }
+
+  async start(): Promise<ServerInstance> {
+    this.status = 'starting';
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.server = this.app.listen(this.config.port, () => {
+          this.status = 'running';
+          console.log(`🚀 ${this.config.name} v${this.config.version} running on http://localhost:${this.config.port}`);
+
+          if (this.config.gracefulShutdown) {
+            createGracefulShutdown(this.server!, {
+              onShutdown: async () => {
+                this.status = 'stopping';
+              }
+            });
+          }
+
+          resolve(this);
+        });
+
+        this.server.on('error', reject);
+      } catch (error: unknown) {
+        this.status = 'stopped';
+        reject(error);
+      }
+    });
+  }
+
+  async stop(): Promise<void> {
+    this.status = 'stopping';
+
+    // Stop gRPC server if running
+    if (this.grpcServer) {
+      this.grpcServer.forceShutdown();
+    }
+
+    // Stop Socket.IO server if running
+    if (this.socketIO) {
+      this.socketIO.close();
+    }
+
+    if (!this.server) {
+      this.status = 'stopped';
+      return;
+    }
+
+    return new Promise((resolve) => {
+      this.server!.close(() => {
+        this.status = 'stopped';
+        console.log(`👋 ${this.config.name} stopped`);
+        resolve();
+      });
+    });
+  }
+
+  getInfo(): ServerInfo {
+    return {
+      name: this.config.name,
+      version: this.config.version,
+      port: this.config.port,
+      uptime: Date.now() - this.config.startTime.getTime(),
+      status: this.status,
+      startTime: this.config.startTime
+    };
+  }
+
+  addGrpcService(service: Record<string, unknown>, implementation: Record<string, (...args: unknown[]) => unknown>, port: number = 50051): void {
+    this.grpcServices.push({ service, implementation });
+
+    // Lazy load gRPC to avoid dependency issues
+    if (!this.grpcServer) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const grpc = require('@grpc/grpc-js') as {
+          Server: new () => {
+            start(): void;
+            forceShutdown(): void;
+            addService(service: unknown, implementation: unknown): void;
+            bindAsync(address: string, credentials: unknown, callback: () => void): void;
+          };
+          ServerCredentials: { createInsecure(): unknown };
+        };
+        this.grpcServer = new grpc.Server();
+
+        // Add all services
+        this.grpcServices.forEach(({ service, implementation }) => {
+          this.grpcServer!.addService(service, implementation);
+        });
+
+        this.grpcServer.bindAsync(
+          `0.0.0.0:${port}`,
+          grpc.ServerCredentials.createInsecure(),
+          () => {
+            this.grpcServer!.start();
+            console.log(`🔗 gRPC server running on port ${port}`);
+          }
+        );
+      } catch (error: unknown) {
+        console.warn('gRPC not available. Install @grpc/grpc-js to use gRPC features.');
+      }
+    }
+  }
+
+  addRpcMethods(methods: RpcMethod, path: string = '/rpc'): void {
+    Object.assign(this.rpcMethods, methods);
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const jayson = require('jayson') as {
+        server: (methods: RpcMethod) => {
+          middleware(): express.RequestHandler;
+        };
+      };
+      const rpcServer = jayson.server(this.rpcMethods);
+      this.app.use(path, rpcServer.middleware());
+      console.log(`📡 JSON-RPC server mounted on ${path}`);
+    } catch (error: unknown) {
+      console.warn('JSON-RPC not available. Install jayson to use RPC features.');
+    }
+  }
+
+  addWebhook(config: WebhookConfig): void {
+    this.app.post(config.path, express.raw({ type: 'application/json' }), async (req, res) => {
+      try {
+        // Verify signature if secret provided
+        if (config.secret) {
+          const signature = req.headers['x-hub-signature-256'] || req.headers['x-signature-256'];
+          if (signature) {
+            const expectedSignature = crypto
+              .createHmac('sha256', config.secret)
+              .update(req.body)
+              .digest('hex');
+
+            const providedSignature = Array.isArray(signature) ? signature[0] : signature;
+            if (!providedSignature.includes(expectedSignature)) {
+              return res.status(401).json({ error: 'Invalid signature' });
+            }
+          }
+        }
+
+        // Parse JSON payload
+        const payload = JSON.parse(req.body.toString());
+
+        // Call handler
+        await config.handler(payload, req.headers as Record<string, string | string[]>);
+
+        res.status(200).json({ success: true });
+      } catch (error: unknown) {
+        console.error('Webhook error:', error);
+        res.status(500).json({ error: 'Webhook processing failed' });
+      }
+    });
+
+    console.log(`🪝 Webhook registered at ${config.path}`);
+  }
+
+  addSocketIO(config: SocketIOConfig = {}): unknown {
+    if (!this.server) {
+      throw new Error('Server must be started before adding Socket.IO');
+    }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { Server } = require('socket.io') as {
+        Server: new (server: Server, options?: {
+          cors?: {
+            origin?: string | string[] | boolean;
+            methods?: string[];
+            credentials?: boolean;
+          };
+          path?: string;
+        }) => {
+          on: (event: string, handler: (socket: unknown) => void) => void;
+          close: () => void;
+        };
+      };
+
+      // Configure CORS
+      const corsConfig = config.cors === true 
+        ? { origin: '*', methods: ['GET', 'POST'] }
+        : config.cors || undefined;
+
+      // Create Socket.IO server
+      const io = new Server(this.server, {
+        cors: config.cors ? corsConfig : undefined,
+        path: config.path || '/socket.io'
+      });
+
+      // Store reference for cleanup
+      this.socketIO = io;
+
+      // Handle connections
+      io.on('connection', (socket: unknown) => {
+        const typedSocket = socket as SocketInstance;
+        console.log(`🔌 Socket connected: ${typedSocket.id}`);
+
+        // Call user-defined connection handler
+        if (config.onConnection) {
+          config.onConnection(socket);
+        }
+
+        // Handle disconnection
+        typedSocket.on('disconnect', (reason) => {
+          console.log(`🔌 Socket disconnected: ${typedSocket.id} - ${reason}`);
+
+          // Call user-defined disconnection handler
+          if (config.onDisconnection) {
+            config.onDisconnection(socket, reason as string);
+          }
+        });
+      });
+
+      console.log(`🔌 Socket.IO server attached${config.path ? ` at ${config.path}` : ''}`);
+      return io;
+    } catch (error: unknown) {
+      console.warn('Socket.IO not available. Install socket.io to use WebSocket features.');
+      return null;
+    }
+  }
+}
+
+export function createServer(
+  name?: string,
+  version?: string,
+  config?: ServerConfig
+): ServerInstance {
+  return new ExpressServer(name, version, config);
+}

package/packages/server-utils/src/shutdown.ts

@@ -0,0 +1,60 @@
+import { Server } from 'http';
+import { GracefulShutdownConfig, ServerPlugin } from './types';
+
+export function createGracefulShutdown(server: Server, config: GracefulShutdownConfig = {}): void {
+  const { timeout = 10000, onShutdown } = config;
+
+  const shutdown = async (signal: string) => {
+    console.log(`🛑 Received ${signal}, shutting down gracefully...`);
+    
+    const shutdownTimer = setTimeout(() => {
+      console.log('⏰ Shutdown timeout reached, forcing exit');
+      process.exit(1);
+    }, timeout);
+
+    try {
+      // Run custom shutdown logic
+      if (onShutdown) {
+        await onShutdown();
+      }
+
+      // Close server
+      server.close(() => {
+        clearTimeout(shutdownTimer);
+        console.log('👋 Server closed. Exiting now.');
+        process.exit(0);
+      });
+    } catch (error) {
+      clearTimeout(shutdownTimer);
+      console.error('❌ Error during shutdown:', error);
+      process.exit(1);
+    }
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+export function withGracefulShutdown(config: GracefulShutdownConfig = {}): ServerPlugin {
+  return (app, serverConfig) => {
+    // This plugin needs to be applied after server.listen()
+    // Store config for later use
+    (app as any).__gracefulShutdownConfig = config;
+  };
+}
+
+export function startServerWithShutdown(
+  app: any, 
+  port: number, 
+  shutdownConfig: GracefulShutdownConfig = {}
+): Server {
+  const server = app.listen(port, () => {
+    console.log(`🚀 Server running on http://localhost:${port}`);
+  });
+
+  // Apply graceful shutdown from stored config or provided config
+  const config = app.__gracefulShutdownConfig || shutdownConfig;
+  createGracefulShutdown(server, config);
+
+  return server;
+}