@naman_deep_singh/server-utils 1.0.7 → 1.1.0

package/dist/esm/middleware.js

@@ -0,0 +1,229 @@
+// Logging middleware
+export function createLoggingMiddleware(format = 'simple') {
+    return (req, res, next) => {
+        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() {
+    return (err, req, res, next) => {
+        console.error('Error:', err);
+        if (res.headersSent) {
+            return next(err);
+        }
+        // Type guard for error objects
+        const errorObj = err;
+        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({
+            success: false,
+            message,
+            data: undefined,
+            error: {
+                message,
+                ...(process.env.NODE_ENV !== 'production' && { details: { stack: errorObj.stack } })
+            },
+            meta: null
+        });
+    };
+}
+// Request ID middleware
+export function createRequestIdMiddleware() {
+    return (req, res, next) => {
+        const requestId = Math.random().toString(36).substring(2, 15);
+        req.requestId = requestId;
+        res.setHeader('X-Request-ID', requestId);
+        next();
+    };
+}
+export function createValidationMiddleware(rules) {
+    return (req, res, next) => {
+        const errors = [];
+        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({
+                success: false,
+                message: 'Validation failed',
+                data: undefined,
+                error: {
+                    message: 'Validation failed',
+                    details: errors
+                },
+                meta: null
+            });
+        }
+        next();
+    };
+}
+const rateLimitStore = new Map();
+export function createRateLimitMiddleware(config = {}) {
+    const { windowMs = 15 * 60 * 1000, maxRequests = 100, message = 'Too many requests, please try again later', keyGenerator = (req) => req.ip || 'unknown' } = config;
+    return (req, res, next) => {
+        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({
+                success: false,
+                message,
+                data: undefined,
+                error: {
+                    message,
+                    details: {
+                        retryAfter: Math.ceil((record.resetTime - now) / 1000)
+                    }
+                },
+                meta: null
+            });
+        }
+        record.count++;
+        next();
+    };
+}
+export function createAuthMiddleware(config) {
+    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, res, next) => {
+        try {
+            const token = tokenExtractor(req);
+            if (!token) {
+                return res.status(401).json({
+                    success: false,
+                    message: unauthorizedMessage,
+                    data: undefined,
+                    error: {
+                        message: unauthorizedMessage
+                    },
+                    meta: null
+                });
+            }
+            const user = await tokenValidator(token);
+            req.user = user;
+            next();
+        }
+        catch (error) {
+            return res.status(401).json({
+                success: false,
+                message: unauthorizedMessage,
+                data: undefined,
+                error: {
+                    message: unauthorizedMessage
+                },
+                meta: null
+            });
+        }
+    };
+}
+// Plugin versions
+export function withLogging(format = 'simple') {
+    return (app) => {
+        app.use(createLoggingMiddleware(format));
+    };
+}
+export function withErrorHandler() {
+    return (app) => {
+        app.use(createErrorHandler());
+    };
+}
+export function withRequestId() {
+    return (app) => {
+        app.use(createRequestIdMiddleware());
+    };
+}
+export function withValidation(rules) {
+    return (app) => {
+        app.use(createValidationMiddleware(rules));
+    };
+}
+export function withRateLimit(config = {}) {
+    return (app) => {
+        app.use(createRateLimitMiddleware(config));
+    };
+}
+export function withAuth(config) {
+    return (app) => {
+        app.use(createAuthMiddleware(config));
+    };
+}
+// Convenience functions for route-specific middleware
+export function validateFields(rules) {
+    return createValidationMiddleware(rules);
+}
+export function rateLimit(config = {}) {
+    return createRateLimitMiddleware(config);
+}
+export function requireAuth(config) {
+    return createAuthMiddleware(config);
+}

package/dist/esm/periodic-health.d.ts

@@ -0,0 +1,11 @@
+import { PeriodicHealthCheckConfig } from './types';
+export declare class PeriodicHealthMonitor {
+    private intervals;
+    private config;
+    private serviceName;
+    constructor(config: PeriodicHealthCheckConfig, serviceName: string);
+    start(): void;
+    stop(): void;
+    private checkServiceHealth;
+    getHealthStatus(): Promise<Record<string, boolean>>;
+}

package/dist/esm/periodic-health.js

@@ -0,0 +1,64 @@
+export class PeriodicHealthMonitor {
+    constructor(config, serviceName) {
+        this.intervals = [];
+        this.config = config;
+        this.serviceName = serviceName;
+    }
+    start() {
+        if (!this.config.enabled || !this.config.services?.length) {
+            return;
+        }
+        const interval = this.config.interval || 30000;
+        this.config.services.forEach(service => {
+            const intervalId = setInterval(async () => {
+                await this.checkServiceHealth(service);
+            }, interval);
+            this.intervals.push(intervalId);
+        });
+        console.log(`📊 ${this.serviceName}: Periodic health monitoring enabled (${interval}ms interval) for ${this.config.services.length} service(s)`);
+    }
+    stop() {
+        this.intervals.forEach(interval => clearInterval(interval));
+        this.intervals = [];
+        console.log(`🛑 ${this.serviceName}: Periodic health monitoring stopped`);
+    }
+    async checkServiceHealth(service) {
+        try {
+            const controller = new AbortController();
+            const timeout = service.timeout || 5000;
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const response = await fetch(service.url, {
+                method: 'GET',
+                signal: controller.signal,
+                headers: {
+                    'User-Agent': `${this.serviceName}-health-monitor`
+                }
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                console.log(`🟢 ${service.name} is healthy`);
+                return true;
+            }
+            else {
+                console.log(`🔴 ${service.name} returned ${response.status}`);
+                return false;
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            console.log(`🔴 ${service.name} health check failed: ${errorMessage}`);
+            return false;
+        }
+    }
+    // Get current health status of all services
+    async getHealthStatus() {
+        if (!this.config.services?.length) {
+            return {};
+        }
+        const results = {};
+        await Promise.all(this.config.services.map(async (service) => {
+            results[service.name] = await this.checkServiceHealth(service);
+        }));
+        return results;
+    }
+}

package/dist/esm/server.d.ts

@@ -0,0 +1,69 @@
+import express from 'express';
+import { Server } from 'http';
+import { ServerConfig, SocketIOConfig } from './types';
+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;
+    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 declare class ExpressServer implements ServerInstance {
+    app: express.Application;
+    server?: Server;
+    config: ServerInstanceConfig;
+    private status;
+    private grpcServices;
+    private grpcServer?;
+    private rpcMethods;
+    private socketIO?;
+    private healthMonitor?;
+    constructor(name?: string, version?: string, config?: ServerConfig);
+    private setupMiddleware;
+    private setupPeriodicHealthMonitoring;
+    start(): Promise<ServerInstance>;
+    stop(): Promise<void>;
+    getInfo(): ServerInfo;
+    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 declare function createServer(name?: string, version?: string, config?: ServerConfig): ServerInstance;

package/dist/esm/server.js

@@ -0,0 +1,271 @@
+import express from 'express';
+import { createGracefulShutdown } from './shutdown';
+import { PeriodicHealthMonitor } from './periodic-health';
+import crypto from 'crypto';
+export class ExpressServer {
+    constructor(name = 'Express Server', version = '1.0.0', config = {}) {
+        this.status = 'stopped';
+        this.grpcServices = [];
+        this.rpcMethods = {};
+        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();
+    }
+    setupMiddleware() {
+        // 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()
+                });
+            });
+        }
+    }
+    setupPeriodicHealthMonitoring() {
+        if (this.config.periodicHealthCheck?.enabled) {
+            this.healthMonitor = new PeriodicHealthMonitor(this.config.periodicHealthCheck, this.config.name);
+        }
+    }
+    async start() {
+        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) {
+                this.status = 'stopped';
+                reject(error);
+            }
+        });
+    }
+    async stop() {
+        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() {
+        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, implementation, port = 50051) {
+        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');
+                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) {
+                console.warn(`${this.config.name}: gRPC not available. Install @grpc/grpc-js to use gRPC features.`);
+            }
+        }
+    }
+    addRpcMethods(methods, path = '/rpc') {
+        Object.assign(this.rpcMethods, methods);
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const jayson = require('jayson');
+            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) {
+            console.warn(`${this.config.name}: JSON-RPC not available. Install jayson to use RPC features.`);
+        }
+    }
+    addWebhook(config) {
+        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);
+                res.status(200).json({ success: true });
+            }
+            catch (error) {
+                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 = {}) {
+        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');
+            // 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) => {
+                const typedSocket = socket;
+                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);
+                    }
+                });
+            });
+            console.log(`🔌 ${this.config.name} Socket.IO server attached${config.path ? ` at ${config.path}` : ''}${config.cors ? ' (CORS enabled)' : ''}`);
+            return io;
+        }
+        catch (error) {
+            console.warn(`${this.config.name}: Socket.IO not available. Install socket.io to use WebSocket features.`);
+            return null;
+        }
+    }
+}
+export function createServer(name, version, config) {
+    return new ExpressServer(name, version, config);
+}

package/dist/esm/shutdown.d.ts

@@ -0,0 +1,5 @@
+import { Server } from 'http';
+import { GracefulShutdownConfig, ServerPlugin } from './types';
+export declare function createGracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
+export declare function withGracefulShutdown(config?: GracefulShutdownConfig): ServerPlugin;
+export declare function startServerWithShutdown(app: any, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;