[Mon Apr 21 12:51:27 PM EDT 2025] Add keep alive timeouts; Enhance the reliability of connections.

Author: patrickrizzardi

app/constants/connection.ts

@@ -23,6 +23,44 @@ export const ConnectionEvent = <const>{
 };
 
 /**
- * Default socket timeout in milliseconds (2 minutes)
+ * Default socket timeout in milliseconds (30 seconds)
+ *
+ * Standard timeout for most socket connections.
+ * It is long enough for slow clients but short enough to prevent idle connections from staying open indefinitely.
+ */
+export const DEFAULT_SOCKET_TIMEOUT = 30000;
+
+/**
+ * Default keep-alive timeout in milliseconds (65 seconds)
+ *
+ * This is the maximum time a connection can be idle before the server will close it.
+ * This is to allow for a connection to stay open for a period of time so subsequent requests can be handled without a new connection.
+ * This is also to prevent a connection from staying open indefinitely.
+ * This is also useful for load balancing and preventing a single server from being overwhelmed by a large number of connections.
+ * AWS recommends a keep-alive timeout of 65 seconds because there idle timeout is 60 seconds.
+ */
+export const DEFAULT_KEEP_ALIVE_TIMEOUT = 65000;
+
+/**
+ * Default headers timeout in milliseconds (66 seconds)
+ *
+ * This is the maximum time to wait for a header from the client.
+ * This is to allow for a connection to stay open for a period of time so subsequent requests can be handled without a new connection.
+ * This is also to prevent a connection from staying open indefinitely.
+ * This is also useful for load balancing and preventing a single server from being overwhelmed by a large number of connections.
+ * It is recommended to set this value to be greater than the keep-alive timeout to prevent the server from closing the connection prematurely
+ * before the keep-alive timeout has expired.
+ */
+export const DEFAULT_HEADERS_TIMEOUT = 66000;
+
+/**
+ * Default graceful shutdown timeout in milliseconds (30 seconds)
+ *
+ * This is the maximum time to wait for a connection to complete before the server will close it.
+ */
+export const DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT = 30000;
+
+/**
+ * Default port for the server
  */
-export const DEFAULT_SOCKET_TIMEOUT = 120000;
+export const DEFAULT_PORT = 5000;

app/core/ConfigManager.ts

@@ -1,4 +1,15 @@
 import type { IServerOptions } from 'types/Server.ts';
+import type { TErrorFunction } from 'types/Response.ts';
+import type { Context } from 'core/Context.ts';
+import type { TResponseBody } from 'types/http/Response.ts';
+import {
+  DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT,
+  DEFAULT_HEADERS_TIMEOUT,
+  DEFAULT_KEEP_ALIVE_TIMEOUT,
+  DEFAULT_PORT,
+  DEFAULT_SOCKET_TIMEOUT,
+} from 'constants/connection.ts';
+import { HttpStatusCode } from 'constants/http.ts';
 
 /**
  * Manages application configuration in a centralized way
@@ -8,44 +19,94 @@ import type { IServerOptions } from 'types/Server.ts';
  * passing options through multiple layers.
  */
 export class ConfigManager {
-  private readonly options: IServerOptions;
+  readonly port: number;
+  readonly errorHandler: TErrorFunction;
+  readonly connectionOptions: Required<IServerOptions>['connectionOptions'];
+  readonly parserOptions: Required<IServerOptions>['parserOptions'];
 
   constructor(options?: IServerOptions) {
-    this.options = options ?? {};
+    this.port = this._setPort(options?.port);
+    this.errorHandler = this._setErrorHandler(options?.errorHandler);
+    this.connectionOptions = this._setConnectionOptions(options?.connectionOptions);
+    this.parserOptions = this._setParserOptions(options?.parserOptions);
   }
 
   /**
-   * Get parser options
+   * Sets the port number and normalizes it to a number
    */
-  get parserOptions(): IServerOptions['parserOptions'] {
-    return this.options.parserOptions;
+  private _setPort(port?: number | string): number {
+    const normalizedPort = typeof port === 'string' ? parseInt(port, 10) : (port ?? DEFAULT_PORT);
+    if (isNaN(normalizedPort) || normalizedPort < 0 || normalizedPort > 65535) {
+      throw new Error('Invalid port number');
+    }
+    return normalizedPort;
   }
 
   /**
-   * Get connection options
+   * Sets the error handler with validation
    */
-  get connectionOptions(): IServerOptions['connectionOptions'] {
-    return this.options.connectionOptions;
+  private _setErrorHandler(handler?: TErrorFunction): TErrorFunction {
+    if (handler && typeof handler !== 'function') {
+      throw new Error('Error handler must be a function');
+    }
+    return (
+      handler ??
+      (({ response }: Context, error: unknown): TResponseBody<unknown> => {
+        console.error('Server error: \n', error);
+        response.setStatus(HttpStatusCode.INTERNAL_SERVER_ERROR);
+        if (error instanceof Error) {
+          return { success: false, message: error.message };
+        }
+        return { success: false, message: 'An unknown error occurred' };
+      })
+    );
   }
 
   /**
-   * Get error handler
+   * Sets and validates connection options
    */
-  get errorHandler(): IServerOptions['errorHandler'] {
-    return this.options.errorHandler;
+  private _setConnectionOptions(options?: IServerOptions['connectionOptions']): Required<IServerOptions>['connectionOptions'] {
+    const normalizedOptions = {
+      socketTimeout: this._normalizeTimeout(options?.socketTimeout, DEFAULT_SOCKET_TIMEOUT),
+      gracefulShutdownTimeout: this._normalizeTimeout(options?.gracefulShutdownTimeout, DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT),
+      keepAliveTimeout: this._normalizeTimeout(options?.keepAliveTimeout, DEFAULT_KEEP_ALIVE_TIMEOUT),
+      headersTimeout: this._normalizeTimeout(options?.headersTimeout, DEFAULT_HEADERS_TIMEOUT),
+    };
+
+    if (normalizedOptions.headersTimeout <= normalizedOptions.keepAliveTimeout) {
+      throw new Error('headersTimeout must be greater than keepAliveTimeout');
+    }
+
+    return normalizedOptions;
   }
 
   /**
-   * Get port
+   * Normalizes a timeout value to a positive number
    */
-  get port(): number | undefined {
-    return this.options.port;
+  private _normalizeTimeout(value: number | string | undefined, defaultValue: number): number {
+    const normalized = typeof value === 'string' ? parseInt(value, 10) : (value ?? defaultValue);
+    if (isNaN(normalized) || normalized < 0) {
+      throw new Error('Timeout must be a positive number');
+    }
+    return normalized;
   }
 
   /**
-   * Get the full options object
+   * Sets and validates parser options
    */
-  getOptions(): IServerOptions {
-    return { ...this.options };
+  private _setParserOptions(options?: IServerOptions['parserOptions']): Required<IServerOptions>['parserOptions'] {
+    const normalizedOptions = options ?? {};
+
+    // Validate JSON parser options
+    if (normalizedOptions.json?.raw !== undefined && typeof normalizedOptions.json.raw !== 'boolean') {
+      throw new Error('JSON parser raw option must be a boolean');
+    }
+
+    // Validate YAML parser options
+    if (normalizedOptions.yaml?.raw !== undefined && typeof normalizedOptions.yaml.raw !== 'boolean') {
+      throw new Error('YAML parser raw option must be a boolean');
+    }
+
+    return normalizedOptions;
   }
 }

app/core/ConnectionManager.ts

@@ -1,6 +1,7 @@
 import type { Server, Socket } from 'net';
 import { EventEmitter } from 'events';
-import { ConnectionEvent, DEFAULT_SOCKET_TIMEOUT } from 'constants/connection.ts';
+import type { ConfigManager } from './ConfigManager.ts';
+import { ConnectionEvent } from 'constants/connection.ts';
 import type { IConnectionStats } from 'types/Connection.ts';
 
 /**
@@ -25,17 +26,17 @@ export class ConnectionManager extends EventEmitter {
   private _totalConnections = 0;
   /** Total connection errors */
   private _connectionErrors = 0;
-  /** Default socket timeout in milliseconds */
-  private readonly _socketTimeout: number;
+  /** Config manager instance */
+  private readonly _configManager: ConfigManager;
 
   /**
    * Creates a new ConnectionManager instance
    *
-   * @param socketTimeout Optional socket timeout in milliseconds (default: 2 minutes)
+   * @param configManager The config manager instance
    */
-  constructor(socketTimeout?: number) {
+  constructor(configManager: ConfigManager) {
     super();
-    this._socketTimeout = socketTimeout ?? DEFAULT_SOCKET_TIMEOUT;
+    this._configManager = configManager;
   }
 
   /**
@@ -57,12 +58,17 @@ export class ConnectionManager extends EventEmitter {
    * Adds a socket connection to the manager and sets up event listeners
    *
    * @param socket The client socket connection
-   * @param timeout Optional timeout for this specific connection
    */
-  addConnection(socket: Socket, timeout?: number): void {
+  addConnection(socket: Socket): void {
     try {
+      // Get socket timeout from config
+      const { socketTimeout, keepAliveTimeout } = this._configManager.connectionOptions;
+
       // Configure socket timeout
-      socket.setTimeout(timeout ?? this._socketTimeout);
+      socket.setTimeout(socketTimeout);
+
+      // Enable TCP keepalive
+      socket.setKeepAlive(true, keepAliveTimeout);
 
       // Add to active connections
       this._connections.add(socket);
@@ -83,7 +89,7 @@ export class ConnectionManager extends EventEmitter {
       });
 
       socket.on('timeout', () => {
-        // Destroy the socket on timeout
+        // Send HTTP timeout response before closing
         socket.end('HTTP/1.1 408 Request Timeout\r\n\r\n');
         socket.destroy();
       });
@@ -164,10 +170,9 @@ export class ConnectionManager extends EventEmitter {
   /**
    * Closes all active connections gracefully
    *
-   * @param gracePeriod Optional grace period in milliseconds before forcefully closing connections
    * @returns Promise that resolves when all connections are closed
    */
-  async closeAllConnections(gracePeriod?: number): Promise<void> {
+  async closeAllConnections(): Promise<void> {
     // If there are no connections, resolve immediately
     if (this._connections.size === 0) {
       this.emit(ConnectionEvent.ALL_CONNECTIONS_CLOSED);
@@ -177,8 +182,11 @@ export class ConnectionManager extends EventEmitter {
     // Create a copy of the connections to avoid modification during iteration
     const connections = [...this._connections];
 
+    // Get graceful shutdown timeout from config
+    const { gracefulShutdownTimeout } = this._configManager.connectionOptions;
+
     // If grace period is provided, attempt graceful shutdown
-    if (gracePeriod !== undefined && gracePeriod > 0) {
+    if (gracefulShutdownTimeout > 0) {
       // End each connection with a proper HTTP response
       for (const socket of connections) {
         try {
@@ -190,7 +198,7 @@ export class ConnectionManager extends EventEmitter {
 
       // Wait for the grace period
       await new Promise<void>((resolve) => {
-        setTimeout(() => resolve(), gracePeriod);
+        setTimeout(() => resolve(), gracefulShutdownTimeout);
       });
     }
 

app/core/Request/RequestHandler.ts

@@ -30,7 +30,7 @@ export class RequestHandler {
     this.routeFinder = routeFinder;
     this.hooksManager = hooksManager;
     this.configManager = configManager;
-    this.errorHandler = configManager.errorHandler ?? this._defaultErrorHandler;
+    this.errorHandler = configManager.errorHandler;
   }
 
   /**
@@ -58,14 +58,7 @@ export class RequestHandler {
     }
   }
 
-  /**
-   * Default error handler if none is provided
-   */
-  private readonly _defaultErrorHandler: TErrorFunction = ({ response }, error): unknown => {
-    console.error('Server error: \n', error);
-    response.setStatus(HttpStatusCode.INTERNAL_SERVER_ERROR);
-    return { success: false, message: 'Internal server error' };
-  };
+
 
   /**
    * Sends an HTTP response through the socket