@naman_deep_singh/server-utils 1.0.7 → 1.1.0

package/src/server.ts

@@ -1,412 +0,0 @@
-import express from 'express';
-import { Server } from 'http';
-import { ServerConfig, SocketIOConfig, SocketInstance } from './types';
-import { createGracefulShutdown } from './shutdown';
-import { PeriodicHealthMonitor, createPeriodicHealthMonitor } from './periodic-health';
-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 };
-  private healthMonitor?: PeriodicHealthMonitor;
-
-  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,
-      cookieParser: config.cookieParser ?? false,
-      customMiddleware: config.customMiddleware || [],
-      healthCheck: config.healthCheck ?? true,
-      gracefulShutdown: config.gracefulShutdown ?? true,
-      socketIO: config.socketIO,
-      periodicHealthCheck: config.periodicHealthCheck || { enabled: false }
-    };
-
-    // Apply middleware based on configuration
-    this.setupMiddleware();
-    
-    // Setup periodic health monitoring
-    this.setupPeriodicHealthMonitoring();
-  }
-
-  private setupMiddleware(): void {
-    // Apply CORS if enabled
-    if (this.config.cors) {
-      try {
-        const cors = require('cors');
-        const corsOptions = typeof this.config.cors === 'object' ? this.config.cors : undefined;
-        this.app.use(cors(corsOptions));
-      } catch (error) {
-        console.warn(`${this.config.name}: CORS middleware not available. Install cors package.`);
-      }
-    }
-
-    // Apply Helmet if enabled
-    if (this.config.helmet) {
-      try {
-        const helmet = require('helmet');
-        this.app.use(helmet());
-      } catch (error) {
-        console.warn(`${this.config.name}: Helmet middleware not available. Install helmet package.`);
-      }
-    }
-
-    // Apply JSON parser if enabled
-    if (this.config.json) {
-      this.app.use(express.json());
-    }
-
-    // Apply cookie parser if enabled
-    if (this.config.cookieParser) {
-      try {
-        const cookieParser = require('cookie-parser');
-        this.app.use(cookieParser());
-      } catch (error) {
-        console.warn(`${this.config.name}: Cookie parser middleware not available. Install cookie-parser package.`);
-      }
-    }
-
-    // Apply custom middleware
-    if (this.config.customMiddleware && this.config.customMiddleware.length > 0) {
-      this.config.customMiddleware.forEach(middleware => {
-        this.app.use(middleware);
-      });
-    }
-
-    // Add health check if enabled
-    if (this.config.healthCheck) {
-      const healthPath = typeof this.config.healthCheck === 'string' ? this.config.healthCheck : '/health';
-      this.app.get(healthPath, (req, res) => {
-        res.status(200).json({
-          status: 'healthy',
-          service: this.config.name,
-          version: this.config.version,
-          uptime: Date.now() - this.config.startTime.getTime(),
-          timestamp: new Date().toISOString()
-        });
-      });
-    }
-  }
-
-  private setupPeriodicHealthMonitoring(): void {
-    if (this.config.periodicHealthCheck?.enabled) {
-      this.healthMonitor = createPeriodicHealthMonitor(
-        this.config.periodicHealthCheck,
-        this.config.name
-      );
-    }
-  }
-
-  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';
-                // Stop health monitoring during shutdown
-                if (this.healthMonitor) {
-                  this.healthMonitor.stop();
-                }
-              }
-            });
-          }
-
-          // Start periodic health monitoring after server is running
-          if (this.healthMonitor) {
-            this.healthMonitor.start();
-          }
-
-          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 periodic health monitoring
-    if (this.healthMonitor) {
-      this.healthMonitor.stop();
-    }
-
-    // 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(`🔗 ${this.config.name} gRPC server running on port ${port}`);
-          }
-        );
-      } catch (error: unknown) {
-        console.warn(`${this.config.name}: 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(`📡 ${this.config.name} JSON-RPC server mounted on ${path}`);
-    } catch (error: unknown) {
-      console.warn(`${this.config.name}: 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(`🪝 ${this.config.name} webhook registered at ${config.path}${config.secret ? ' (with signature verification)' : ''}`);
-  }
-
-  addSocketIO(config: SocketIOConfig = {}): unknown {
-    if (!this.server) {
-      throw new Error(`${this.config.name}: 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(`🔌 ${this.config.name}: Socket connected [${typedSocket.id}]`);
-
-        // Call user-defined connection handler
-        if (config.onConnection) {
-          config.onConnection(socket);
-        }
-
-        // Handle disconnection
-        typedSocket.on('disconnect', (reason) => {
-          console.log(`🔌 ${this.config.name}: Socket disconnected [${typedSocket.id}] - ${reason}`);
-
-          // Call user-defined disconnection handler
-          if (config.onDisconnection) {
-            config.onDisconnection(socket, reason as string);
-          }
-        });
-      });
-
-      console.log(`🔌 ${this.config.name} Socket.IO server attached${config.path ? ` at ${config.path}` : ''}${config.cors ? ' (CORS enabled)' : ''}`);
-      return io;
-    } catch (error: unknown) {
-      console.warn(`${this.config.name}: 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/src/shutdown.ts

@@ -1,69 +0,0 @@
-import { Server } from 'http';
-import { GracefulShutdownConfig, ServerPlugin } from './types';
-
-export function createGracefulShutdown(server: Server, config: GracefulShutdownConfig = {}): void {
-  const { timeout = 10000, onShutdown, serverName, serverVersion } = config;
-  const nameVersion = serverName && serverVersion ? `${serverName} v${serverVersion}` : 'Server';
-
-  const shutdown = async (signal: string) => {
-    console.log(`🛑 ${nameVersion} received ${signal}, shutting down gracefully...`);
-    
-    const shutdownTimer = setTimeout(() => {
-      console.log(`⏰ ${nameVersion} 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(`👋 ${nameVersion} closed. Exiting now.`);
-        process.exit(0);
-      });
-    } catch (error) {
-      clearTimeout(shutdownTimer);
-      console.error(`❌ ${nameVersion} 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 = {},
-  serverName?: string,
-  serverVersion?: string
-): Server {
-  const server = app.listen(port, () => {
-    const nameVersion = serverName && serverVersion ? `${serverName} v${serverVersion}` : 'Server';
-    console.log(`🚀 ${nameVersion} running on http://localhost:${port}`);
-  });
-
-  // Apply graceful shutdown from stored config or provided config
-  const config = app.__gracefulShutdownConfig || shutdownConfig;
-  const enhancedConfig = {
-    ...config,
-    serverName,
-    serverVersion
-  };
-  createGracefulShutdown(server, enhancedConfig);
-
-  return server;
-}

package/src/types.ts

@@ -1,80 +0,0 @@
-import express from 'express';
-
-export interface CorsOptions {
-  origin?: string | string[] | boolean | RegExp | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
-  methods?: string | string[];
-  allowedHeaders?: string | string[];
-  exposedHeaders?: string | string[];
-  credentials?: boolean;
-  maxAge?: number;
-  preflightContinue?: boolean;
-  optionsSuccessStatus?: number;
-}
-
-export interface ServerConfig {
-  port?: number;
-  cors?: boolean | CorsOptions;
-  helmet?: boolean;
-  json?: boolean;
-  cookieParser?: boolean;
-  customMiddleware?: express.RequestHandler[];
-  healthCheck?: boolean | string;
-  gracefulShutdown?: boolean;
-  socketIO?: SocketIOConfig;
-  periodicHealthCheck?: PeriodicHealthCheckConfig;
-  name?: string;
-  version?: string;
-}
-
-export interface PeriodicHealthCheckConfig {
-  enabled?: boolean;
-  interval?: number;
-  services?: HealthCheckService[];
-}
-
-export interface HealthCheckService {
-  name: string;
-  url: string;
-  timeout?: number;
-}
-
-export interface SocketIOConfig {
-  enabled?: boolean;
-  cors?: boolean | {
-    origin?: string | string[] | boolean;
-    methods?: string[];
-    credentials?: boolean;
-  };
-  onConnection?: (socket: unknown) => void;
-  onDisconnection?: (socket: unknown, reason: string) => void;
-  path?: string;
-}
-
-export interface HealthCheckConfig {
-  path?: string;
-  customChecks?: HealthCheck[];
-}
-
-export interface HealthCheck {
-  name: string;
-  check: () => Promise<boolean>;
-}
-
-export interface GracefulShutdownConfig {
-  timeout?: number;
-  onShutdown?: () => Promise<void>;
-  serverName?: string;
-  serverVersion?: string;
-}
-
-export interface SocketInstance {
-  id: string;
-  emit: (event: string, data?: unknown) => void;
-  on: (event: string, handler: (...args: unknown[]) => void) => void;
-  broadcast: {
-    emit: (event: string, data?: unknown) => void;
-  };
-  disconnect: () => void;
-}
-
-export type ServerPlugin = (app: express.Application, config: ServerConfig) => void;

package/src/utils.ts

@@ -1,34 +0,0 @@
-// Environment utilities
-export function getEnv(key: string, defaultValue?: string): string {
-  const value = process.env[key];
-  if (value === undefined && defaultValue === undefined) {
-    throw new Error(`Environment variable ${key} is required`);
-  }
-  return value || defaultValue!;
-}
-
-export function getEnvNumber(key: string, defaultValue?: number): number {
-  const value = process.env[key];
-  if (value === undefined) {
-    if (defaultValue === undefined) {
-      throw new Error(`Environment variable ${key} is required`);
-    }
-    return defaultValue;
-  }
-  const parsed = parseInt(value, 10);
-  if (isNaN(parsed)) {
-    throw new Error(`Environment variable ${key} must be a number`);
-  }
-  return parsed;
-}
-
-export function getEnvBoolean(key: string, defaultValue?: boolean): boolean {
-  const value = process.env[key];
-  if (value === undefined) {
-    if (defaultValue === undefined) {
-      throw new Error(`Environment variable ${key} is required`);
-    }
-    return defaultValue;
-  }
-  return value.toLowerCase() === 'true';
-}

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "CommonJS",
-    "moduleResolution": "node",
-    "rootDir": "./src",
-    "outDir": "./dist",
-    "strict": true,
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "declaration": true,
-    "baseUrl": ".",
-    "paths": {
-      "*": ["*", "*.ts", "*.js"]
-    }
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}