feat(server): enhance port and hostname validation, add dynamic port handling

Author: cyber-hari

src/object/object.utils.ts

@@ -424,7 +424,7 @@ function cloneObject(obj: any, seen: WeakMap<object, any>): any {
  */
 export function deepClone<T>(value: T): T {
   const seen = new WeakMap();
-  return _deepClone(value, seen);
+  return _deepClone(value, seen as WeakMap<object, any>);
 }
 
 /**

src/server/server.builder.ts

@@ -1,7 +1,7 @@
-import { deepClone, deepObjMerge } from '@catbee/utils/object';
+import { deepClone, deepObjMerge, isPlainObject } from '@catbee/utils/object';
 import type { CatbeeServerConfig } from '@catbee/utils/types';
 import { getCatbeeServerGlobalConfig } from '@catbee/utils/config';
-import { isPort } from '@catbee/utils/validation';
+import { isPort, isHostname } from '@catbee/utils/validation';
 
 export const BUILD_MARKER = Symbol.for('catbee.express.server.build');
 
@@ -29,18 +29,31 @@ export class ServerConfigBuilder {
    *
    * @private
    * @param port - The port number to validate
-   * @throws {Error} If port is not an integer or is outside the valid range (1-65535)
+   * @throws {Error} If port is not an integer or is outside the valid range (0-65535)
    */
   private validatePort(port: number): void {
-    if (!isPort(port)) {
-      throw new Error(`Port must be a valid number between 1 and 65535, got: ${port}`);
+    if (!isPort(port, true)) {
+      throw new Error(`Port must be a valid number between 0 and 65535, got: ${port}`);
+    }
+  }
+
+  /**
+   * Validates that a hostname is valid.
+   *
+   * @private
+   * @param host - The hostname to validate
+   * @throws {Error} If hostname is invalid
+   */
+  private validateHost(host: string): void {
+    if (!isHostname(host)) {
+      throw new Error(`Host must be a valid hostname or IP address, got: ${host}`);
     }
   }
 
   /**
    * Sets the port the server will listen on.
    *
-   * @param port - The port number (1-65535)
+   * @param port - The port number (0-65535). Use 0 for dynamic port assignment.
    * @returns The builder instance for chaining
    * @throws {Error} If port is invalid
    * @default 3000 (can be overridden via PORT env variable)
@@ -61,14 +74,17 @@ export class ServerConfigBuilder {
    *
    * @param host - The hostname (e.g., 'localhost', '0.0.0.0', '127.0.0.1')
    * @returns The builder instance for chaining
+   * @throws {Error} If hostname is invalid
    * @default '0.0.0.0' (can be overridden via HOST env variable)
    *
    * @example
    * ```typescript
    * builder.withHost('0.0.0.0') // Listen on all interfaces
+   * builder.withHost('localhost') // Listen on localhost only
    * ```
    */
   withHost(host: string): this {
+    this.validateHost(host);
     this.config.host = host;
     return this;
   }
@@ -512,13 +528,26 @@ export class ServerConfigBuilder {
    * ```
    */
   withBodyParser(opts: NonNullable<CatbeeServerConfig['bodyParser']>): this {
+    if (opts === true) {
+      this.config.bodyParser = getCatbeeServerGlobalConfig().bodyParser;
+      return this;
+    } else if (opts === false) {
+      this.config.bodyParser = false;
+      return this;
+    }
+
     this.config.bodyParser = {
-      ...this.config.bodyParser,
+      ...(this.config.bodyParser as object),
       ...opts
     };
     return this;
   }
 
+  disableBodyParser(): this {
+    this.config.bodyParser = false;
+    return this;
+  }
+
   /**
    * Configures cookie parsing middleware.
    *
@@ -676,7 +705,7 @@ export class ServerConfigBuilder {
     key: K,
     value: Partial<NonNullable<CatbeeServerConfig[K]>>
   ): void {
-    const current = this.config[key] && typeof this.config[key] === 'object' ? deepClone(this.config[key]!) : {};
+    const current = isPlainObject(this.config[key]) ? deepClone(this.config[key]!) : {};
     this.config[key] = deepObjMerge({}, current, value) as NonNullable<CatbeeServerConfig[K]>;
   }
 

src/server/server.ts

@@ -9,10 +9,10 @@ import { Env } from '@catbee/utils/env';
 import { getLogger } from '@catbee/utils/logger';
 import { InternalServerErrorException, ServiceUnavailableException, NotFoundException } from '@catbee/utils/exception';
 import { getCatbeeServerGlobalConfig } from '@catbee/utils/config';
-import { deepObjMerge } from '@catbee/utils/object';
+import { deepObjMerge, isPlainObject } from '@catbee/utils/object';
 import { fileExists, readFileSync, readFile } from '@catbee/utils/fs';
 import { CatbeeServerConfig, CatbeeServerHooks } from '@catbee/utils/types';
-import { isPort } from '@catbee/utils/validation';
+import { isPort, isHostname } from '@catbee/utils/validation';
 import { optionalRequire } from '@catbee/utils/async';
 import { BUILD_MARKER } from './server.builder';
 import { uuid } from '@catbee/utils/id';
@@ -109,14 +109,19 @@ export class ExpressServer {
    */
   constructor(config: Partial<CatbeeServerConfig>, hooks: CatbeeServerHooks = {}) {
     if (this.hasBuildMarker(config)) {
-      this.config = config as Required<CatbeeServerConfig>;
+      this.config = deepObjMerge({}, config) as Required<CatbeeServerConfig>;
     } else {
       // Deep merge config with user overrides
       this.config = deepObjMerge({}, getCatbeeServerGlobalConfig(), config) as Required<CatbeeServerConfig>;
     }
 
-    if (!isPort(this.config.port)) {
-      const msg = `Port must be a valid number between 1 and 65535, got: ${this.config.port}`;
+    // Normalize host (strip brackets from IPv6 addresses for server.listen compatibility)
+    if (this.config.host) {
+      this.config.host = this.normalizeHost(this.config.host);
+    }
+
+    if (!isPort(this.config.port, true)) {
+      const msg = `Port must be a valid number between 0 and 65535, got: ${this.config.port}`;
       getLogger().error(msg);
       throw new Error(msg);
     }
@@ -415,7 +420,6 @@ export class ExpressServer {
 
         const logger = getLogger();
         const incomingRequestMetaData = {
-          requestId: req.id,
           method: req.method,
           url: req.originalUrl || req.url,
           ip: req.ip
@@ -474,13 +478,23 @@ export class ExpressServer {
    * Set up body parsing middleware.
    */
   private setupBodyParsingMiddleware(): void {
-    if (this.config.bodyParser) {
+    if (isPlainObject(this.config.bodyParser)) {
       if (this.config.bodyParser.json) {
         this.app.use(express.json(this.config.bodyParser.json));
       }
       if (this.config.bodyParser.urlencoded) {
         this.app.use(express.urlencoded(this.config.bodyParser.urlencoded));
       }
+    } else if (this.config.bodyParser === true) {
+      const globalBodyParserConfig = getCatbeeServerGlobalConfig().bodyParser;
+      if (isPlainObject(globalBodyParserConfig)) {
+        if (globalBodyParserConfig.json) {
+          this.app.use(express.json(globalBodyParserConfig.json));
+        }
+        if (globalBodyParserConfig.urlencoded) {
+          this.app.use(express.urlencoded(globalBodyParserConfig.urlencoded));
+        }
+      }
     }
   }
 
@@ -864,7 +878,9 @@ export class ExpressServer {
    */
   private logServerStartInfo(): void {
     const protocol = this.config.https ? 'https' : 'http';
-    const url = `${protocol}://${this.config.host}:${this.config.port}`;
+    const port = this.getPort();
+    const host = this.formatHostForUrl(this.config.host || 'localhost');
+    const url = `${protocol}://${host}:${port}`;
     getLogger().info(`Server running on ${url}`);
 
     if (this.config.healthCheck?.path) {
@@ -1112,6 +1128,118 @@ export class ExpressServer {
     return this.config;
   }
 
+  /**
+   * Get the port the server is listening on.
+   * Returns the actual port if server is running (useful when config.port was 0),
+   * otherwise returns the configured port.
+   *
+   * @returns The port number
+   */
+  public getPort(): number {
+    const address = this.server?.address();
+    if (address && typeof address === 'object' && 'port' in address) {
+      return address.port;
+    }
+    return this.config.port;
+  }
+
+  /**
+   * Get the full URL the server is running on.
+   * Returns the actual URL if server is running (useful when config.port was 0),
+   * otherwise returns the configured URL.
+   *
+   * @returns The full server URL (e.g., "http://localhost:3000")
+   */
+  public getUrl(): string {
+    const protocol = this.config.https ? 'https' : 'http';
+    const port = this.getPort();
+    const host = this.formatHostForUrl(this.config.host || 'localhost');
+    return `${protocol}://${host}:${port}`;
+  }
+
+  /**
+   * Check if the server is configured for dynamic port assignment.
+   * Returns true if the original port configuration was 0.
+   *
+   * @returns True if using dynamic port assignment, false otherwise
+   */
+  public isPortDynamic(): boolean {
+    return this.config.port === 0;
+  }
+
+  /**
+   * Check if the server is currently running and listening for requests.
+   *
+   * @returns True if server is running, false otherwise
+   */
+  public isRunning(): boolean {
+    return this.server !== null && this.server.listening;
+  }
+
+  /**
+   * Get the host address the server is bound to.
+   *
+   * @returns The host address
+   */
+  public getHost(): string {
+    return this.config.host || 'localhost';
+  }
+
+  /**
+   * Get the protocol the server is using ('http' or 'https').
+   *
+   * @returns The protocol string
+   */
+  public getProtocol(): string {
+    return this.config.https ? 'https' : 'http';
+  }
+
+  /**
+   * Check if the server is configured to use HTTPS.
+   *
+   * @returns True if using HTTPS, false otherwise
+   */
+  public isHttps(): boolean {
+    return this.config.https !== undefined;
+  }
+
+  /**
+   * Set a new port for the server.
+   * Can only be called before the server starts listening.
+   * Useful for testing scenarios where you need to change the port dynamically.
+   *
+   * @param port - The new port number (0-65535)
+   * @throws Error if server is already running or port is invalid
+   */
+  public setPort(port: number): void {
+    if (this.server) {
+      throw new Error('Cannot change port after server has started');
+    }
+    if (!isPort(port, true)) {
+      throw new Error(`Port must be a valid number between 0 and 65535, got: ${port}`);
+    }
+    this.config.port = port;
+  }
+
+  /**
+   * Set a new host for the server.
+   * Can only be called before the server starts listening.
+   * Useful for testing scenarios where you need to change the host dynamically.
+   *
+   * @param host - The new host (e.g., "localhost", "0.0.0.0", "127.0.0.1", "::1", or "[::1]")
+   * @throws {Error} If server is already running or host is invalid
+   */
+  public setHost(host: string): void {
+    if (this.server) {
+      throw new Error('Cannot change host after server has started');
+    }
+    const normalizedHost = this.normalizeHost(host);
+    if (!isHostname(normalizedHost)) {
+      throw new Error(`Host must be a valid hostname or IP address, got: ${host}`);
+    }
+    this.config.host = normalizedHost;
+  }
+
   /**
    * Wait until server initialization (middleware + routes) has completed.
    * Useful for integration tests that inspect app before starting.
@@ -1120,6 +1248,32 @@ export class ExpressServer {
     await this.initPromise;
   }
 
+  /**
+   * Normalize host by stripping surrounding brackets from IPv6 addresses.
+   * This ensures the host value is compatible with server.listen().
+   * Brackets are URL syntax only and must be removed for Node.js binding.
+   */
+  private normalizeHost(host: string): string {
+    // Strip surrounding brackets from IPv6 addresses (e.g., "[::1]" -> "::1")
+    if (host.startsWith('[') && host.endsWith(']')) {
+      return host.slice(1, -1);
+    }
+    return host;
+  }
+
+  /**
+   * Format host for use in URLs.
+   * Wraps IPv6 addresses in brackets per RFC 3986.
+   */
+  private formatHostForUrl(host: string): string {
+    // IPv6 addresses contain colons and need to be wrapped in brackets
+    // Since we normalize at input (strip brackets), we never have pre-bracketed hosts
+    if (host.includes(':')) {
+      return `[${host}]`;
+    }
+    return host;
+  }
+
   private normalizePath(path: string, withGlobalPrefix = false): string {
     const sanitize = (p: string): string => {
       return (

src/types/server.ts

@@ -17,6 +17,7 @@ export interface CatbeeServerConfig {
   /** Server port
    *  - **default**: `3000`
    *  - **env**: `SERVER_PORT` || `PORT`
+   *  - Use `0` for dynamic port assignment (OS assigns available port)
    */
   port: number;
 
@@ -82,7 +83,7 @@ export interface CatbeeServerConfig {
    *    - `SERVER_BODY_PARSER_JSON_LIMIT`
    *    - `SERVER_BODY_PARSER_URLENCODED_LIMIT`
    */
-  bodyParser?: {
+  bodyParser?: ToggleConfig<{
     /** JSON body parser options
      *  - **default**: `{ limit: '1mb' }`
      */
@@ -92,7 +93,7 @@ export interface CatbeeServerConfig {
      *  - **default**: `{ extended: true, limit: '1mb' }`
      */
     urlencoded?: Parameters<typeof urlencoded>[0];
-  };
+  }>;
 
   /** Cookie parser toggle or options
    *  - **default**: `false`