redweb 0.7.7 → 0.8.0

package/README.md

@@ -22,8 +22,10 @@ const {
   BaseHttpServer,      // Express app builder for advanced composition
   BaseHandler,         // WebSocket message handler base
   sendJson,            // Utility to stringify+send
+  HTTP_OPTIONS,        // Defaults for HTTP servers
+  ENCODINGS,           // json/urlencoded encoding names
   SOCKET_OPTIONS,      // Defaults for socket servers
-  METHODS              // Express method helpers: get/post/put/delete
+  METHODS              // Express method helpers
 } = require('redweb');
 ```
 
@@ -41,7 +43,10 @@ Options:
 - `listenCallback` (function): invoked after `.listen`.
 - `encoding` (`'json' | 'urlencoded'`): body parser selection.
 - `corsOptions`: passed to `cors`.
+- `corsOptions: false`: disables the CORS middleware entirely.
 - `enableHtmxRendering` (boolean): render `.htmx` files with the built-in renderer.
+- `exposeErrors` (boolean): include HTMX rendering details in responses; defaults to `false`.
+- `logger`: an object with optional `log`, `warn`, and `error` methods. Pass `null` to disable library logging.
 
 Example:
 
@@ -79,6 +84,10 @@ const name = 'RedWeb';
 
 Requesting `/example.htmx` returns rendered HTML.
 
+Templates are trusted server-side code. They may load relative modules within their configured public directory, execute for at most one second by default, and interpolate raw HTML. Never render user-supplied template files.
+
+CORS remains permissive by default for backward compatibility. CORS is not authorization; configure `corsOptions`, add authentication middleware to `server.app`, or disable the middleware as appropriate.
+
 ## WebSocket servers
 
 `SocketServer` uses `ws` and routes connections to `SocketRoute` instances. Clients must send JSON containing a `type` that matches a handler name.
@@ -188,6 +197,7 @@ class ImageHandler extends BaseHandler {
 ### WebSocket route options
 
 `SocketRoute` accepts `websocketOptions`, which are passed to `new WebSocketServer(...)`. Use this for `ws` server settings such as `maxPayload` or `perMessageDeflate`.
+Redweb controls `noServer`, `path`, `server`, and `port`; do not include them in `websocketOptions`. Route selection is performed once by Redweb so strict matching and optional root fallback behave consistently. Handshake authentication can use the `ws` `verifyClient` option, although authenticating in the surrounding HTTP upgrade flow is preferable for complex applications.
 
 ```js
 class ClipboardRoute extends SocketRoute {
@@ -204,6 +214,16 @@ class ClipboardRoute extends SocketRoute {
 }
 ```
 
+Other route options:
+
+- `trustProxy`: use the first `X-Forwarded-For` value as the connection identity. Enable this only behind a trusted proxy.
+- `getClientKey(req)`: provide application-specific connection identity logic instead of IP-based identity.
+- `exposeErrors`: return handler exception messages to clients; defaults to `false`.
+- `logger`: route logger with optional `log`, `warn`, and `error` methods; pass `null` to disable it.
+- `shutdownTimeoutMs`: grace period before non-cooperating peers are terminated during shutdown; defaults to `1000`.
+
+`BaseHandler.validateMessage(message, socket)` may return `false` or a promise resolving to `false` to reject a message. Text and binary handlers may be asynchronous; rejected promises are caught and converted to safe error responses.
+
 ### Sharing an HTTP/HTTPS server
 
 Use `listen: false` on `HttpServer` to build the Express app and Node server without binding a port. Then pass `httpServer.server` to `SocketServer`. When `SocketServer` receives a prebuilt `server`, it attaches upgrade handling but does not call `.listen()` unless you explicitly set `listen: true`.
@@ -268,9 +288,20 @@ Helpers: `add`, `remove(itemOrId, byKey = 'id')`, `all()`, `count()`.
 - HTTP defaults: port `80`, bind `0.0.0.0`, `listen: true`.
 - WebSocket defaults: port `3000`, single connection per IP unless `allowDuplicateConnections` is set.
 - `SocketServer` owns and listens on its own server by default; if you pass `server`, you own calling `.listen()` unless you also pass `listen: true`.
+- Upgrade paths are matched strictly by default. Set `fallbackToRoot: true` for legacy behavior that sends unmatched paths to `/`.
 - If you do not supply `routes`, `SocketServer` registers a default route at `/` with `DefaultHandler` (it expects messages with `type: 'DefaultHandler'`).
-- `BaseSocketServer.shutdown()` closes all routes, services, and the underlying server.
+- `shutdown()` closes routes and services. It closes an owned listener, but leaves a supplied listener running unless `closeServerOnShutdown: true` is set.
+- Shutdown is best-effort: all hooks, clients, routes, and owned listeners are processed before collected cleanup errors are reported.
+- `HttpServer` and `HttpsServer` expose an idempotent async `shutdown()` helper.
+
+## 0.8 migration notes
+
+- Unmatched WebSocket paths are rejected unless `fallbackToRoot: true` is configured.
+- Handler exception details are hidden unless `exposeErrors: true` is configured.
+- Shutting down a WebSocket server no longer closes a caller-supplied HTTP/HTTPS server by default.
+- `bind` is now honored by HTTP, HTTPS, WebSocket, and secure WebSocket listeners.
+- `shutdown()` is asynchronous; await it when deterministic cleanup matters.
 
 ## Developing
 
-- Run tests with `npm test` (Jest).
+- Run tests with `npm test` (Jest). The suite includes mock-free HTTP, HTTPS, WebSocket, and secure WebSocket integration tests plus unit tests, with 100% coverage enforced for statements, branches, functions, and lines.

package/index.d.ts

@@ -4,6 +4,7 @@ declare module 'redweb' {
     import { Server as NodeHttpServer } from 'http';
     import { WebSocket, ServerOptions } from 'ws';
     import { Buffer } from 'buffer';
+    import { EventEmitter } from 'events';
 
     /** ─────────────────── HTTP / CORE ─────────────────── */
 
@@ -19,19 +20,41 @@ declare module 'redweb' {
         encoding?: RedWebEncoding;
         ssl?: { key: string; cert: string };
         server?: Application;
-        corsOptions?: CorsOptions;
-        enableHtmxRendering?: boolean;
-    }
+        corsOptions?: CorsOptions | false;
+        enableHtmxRendering?: boolean;
+        exposeErrors?: boolean;
+        logger?: RedWebLogger | null;
+    }
+
+    export type RedWebSocket = WebSocket & {
+        clientKey: string;
+        __redwebClientKey: string;
+        remoteAddress: string;
+        isAssigned: boolean;
+        sendJson(data: unknown): boolean;
+        broadcast(data: unknown): number;
+    };
 
     /** ─────────────────── SOCKET SERVER ─────────────────── */
 
     export interface SocketServerOptions {
         server?: NodeHttpServer;
         port?: number;
+        bind?: string;
         listen?: boolean;
         routes?: Array<new () => SocketRoute>;
-        ssl?: { key: string; cert: string };
-    }
+        ssl?: { key: string; cert: string };
+        fallbackToRoot?: boolean;
+        closeServerOnShutdown?: boolean;
+        listenCallback?: () => void;
+        logger?: RedWebLogger | null;
+    }
+
+    export interface RedWebLogger {
+        log?(message?: any, ...optionalParams: any[]): void;
+        warn?(message?: any, ...optionalParams: any[]): void;
+        error?(message?: any, ...optionalParams: any[]): void;
+    }
 
     /** ─────────────────── ROUTES & HANDLERS ─────────────────── */
 
@@ -40,14 +63,20 @@ declare module 'redweb' {
         handlers: Array<new () => BaseHandler>;
         services?: Array<new () => SocketService>;
         allowDuplicateConnections?: boolean;
-        websocketOptions?: ServerOptions;
+        websocketOptions?: Omit<ServerOptions, 'noServer' | 'path' | 'server' | 'port'>;
+        trustProxy?: boolean;
+        getClientKey?: (request: import('http').IncomingMessage) => string;
+        exposeErrors?: boolean;
+        logger?: RedWebLogger | null;
+        shutdownTimeoutMs?: number;
     }
 
     /** Socket‑side autonomous service (game loops, timers, etc.) */
-    export abstract class SocketService {
-        name: string;
-        tickRateMs?: number;
-        protected _tickHandle?: NodeJS.Timeout;
+    export abstract class SocketService {
+        name: string;
+        tickRateMs: number | null;
+        route: SocketRoute;
+        protected _tickHandle: NodeJS.Timeout | null;
 
         constructor(name: string, tickRateMs?: number);
 
@@ -67,50 +96,56 @@ declare module 'redweb' {
         constructor(name: string);
 
         handleMessage(
-            socket: WebSocket & {
-                sendJson: (message: object) => void;
-                broadcast: (message: object) => void;
-            },
+            socket: RedWebSocket,
             message: any
-        ): void;
-
-        onMessage(socket: WebSocket, message: any): void;
-        acceptsBinary?(socket: WebSocket, buffer: Buffer): boolean;
-        handleBinaryMessage(socket: WebSocket, buffer: Buffer): void;
-        onBinaryMessage(socket: WebSocket, buffer: Buffer): void;
-        onInitialContact(socket: WebSocket): void;
+        ): Promise<unknown>;
+
+        validateMessage(message: any, socket: RedWebSocket): boolean | Promise<boolean>;
+        onMessage(socket: RedWebSocket, message: any): unknown;
+        acceptsBinary?(socket: RedWebSocket, buffer: Buffer): boolean;
+        handleBinaryMessage(socket: RedWebSocket, buffer: Buffer): Promise<unknown>;
+        onBinaryMessage(socket: RedWebSocket, buffer: Buffer): unknown;
+        onInitialContact(socket: RedWebSocket, request?: import('http').IncomingMessage): unknown;
     }
 
-    export class SocketRoute {
+    export class SocketRoute {
         path: string;
         handlers: BaseHandler[];
-        clients: Map<string, WebSocket>;
+        services: SocketService[];
+        clients: Map<string, RedWebSocket>;
         allowDuplicateConnections?: boolean;
-        websocketOptions?: ServerOptions;
+        websocketOptions?: SocketRouteConfig['websocketOptions'];
 
         constructor(config: SocketRouteConfig);
 
-        addHandler(handler: new () => BaseHandler): void;
-        handleMessage(sock: WebSocket, data: any): void;
-        handleBinaryMessage(socket: WebSocket, buffer: Buffer): void;
+        addHandler(handler: new () => BaseHandler): boolean;
+        resolveRemoteAddress(request: import('http').IncomingMessage): string;
+        connectionOpenCallback(socket: RedWebSocket, request?: import('http').IncomingMessage): unknown;
+        connectionCloseCallback?(socket: RedWebSocket): unknown;
+        handleMessage(sock: RedWebSocket, data: any): Promise<boolean>;
+        handleBinaryMessage(socket: RedWebSocket, buffer: Buffer): Promise<boolean>;
+        shutdown(): Promise<void>;
     }
 
     /** ─────────────────── SERVER BASE ─────────────────── */
 
     export class BaseSocketServer {
-        clients: Map<string, WebSocket>;
         server: NodeHttpServer;
-        routes: SocketRoute[];
+        routes: SocketRoute[];
+        ownsServer: boolean;
 
         constructor(server: NodeHttpServer, options?: SocketServerOptions);
 
-        addRoute(route: new () => SocketRoute): void;
+        addRoute(route: new () => SocketRoute): SocketRoute;
+        shutdown(): Promise<void>;
     }
 
-    /** ─────────────────── REGISTRY & UTIL TYPES ─────────────────── */
+    /** ─────────────────── REGISTRY & UTIL TYPES ─────────────────── */
+
+    export function sendJson(socket: WebSocket, data: unknown): boolean;
 
     export interface SocketWrapper {
-        socket: WebSocket;
+        socket: RedWebSocket;
         id: string;
         send: (type: string, payload: Record<string, any>) => void;
         getSanitized?(): Record<string, any>;
@@ -159,14 +194,17 @@ declare module 'redweb' {
         app: Application;
         server?: NodeHttpServer;
         constructor(options?: RedWebOptions);
+        shutdown?(): Promise<void>;
     }
 
     export class HttpServer extends BaseHttpServer {
         constructor(options?: RedWebOptions);
+        shutdown(): Promise<void>;
     }
 
     export class HttpsServer extends BaseHttpServer {
         constructor(options?: RedWebOptions);
+        shutdown(): Promise<void>;
     }
 
     /** ─────────────────── CONSTANTS ─────────────────── */
@@ -174,8 +212,12 @@ declare module 'redweb' {
     export const METHODS: {
         GET: 'get';
         POST: 'post';
-        PUT: 'put';
-        DELETE: 'delete';
+        PUT: 'put';
+        PATCH: 'patch';
+        DELETE: 'delete';
+        OPTIONS: 'options';
+        HEAD: 'head';
+        ALL: 'all';
     };
 
     export const ENCODINGS: {

package/index.js

@@ -1,4 +1,5 @@
 const { BaseHttpServer, METHODS } = require('./src/http');
+const { ENCODINGS, HTTP_OPTIONS } = require('./src/http/BaseHttpServer');
 const { sendJson } = require('./src/ws/util');
 const { SocketServer, SecureSocketServer, SOCKET_OPTIONS, SocketRoute, SocketService, SocketRegistry } = require('./src/ws');
 const { BaseHandler } = require('./src/ws/BaseHandler');
@@ -15,6 +16,8 @@ module.exports = {
     SocketService,
     SocketRegistry,
     sendJson,
-    SOCKET_OPTIONS,
-    METHODS
-};
+    SOCKET_OPTIONS,
+    HTTP_OPTIONS,
+    ENCODINGS,
+    METHODS
+};

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "redweb",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "A way to quickly set up an express server",
   "main": "index.js",
-  "scripts": {
-    "test": "npx jest"
+  "types": "index.d.ts",
+  "scripts": {
+    "pretest": "tsc -p tests/types/tsconfig.json",
+    "test": "npx jest"
   },
   "files": [
     "src/*",
@@ -13,15 +15,19 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "dependencies": {
-    "cors": "^2.8.5",
+  "dependencies": {
+    "@types/express": "^4.17.21",
+    "@types/cors": "2.8.19",
+    "@types/node": "20.19.24",
+    "@types/ws": "^8.18.1",
+    "cors": "^2.8.5",
     "express": "^4.19.2",
     "ws": "^8.17.0"
   },
-  "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/jest": "^29.5.12",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
     "jest": "^29.7.0",
-    "supertest": "^7.0.0"
+    "supertest": "^7.0.0",
+    "typescript": "^5.9.3"
   }
 }

package/src/htmx/HtmxRenderer.js

@@ -8,7 +8,7 @@ class HtmxRenderer {
      * @param {string} filePath - Path to the .htmx file.
      * @returns {string} Rendered HTML string with normalized whitespace.
      */
-    static render(filePath) {
+    static render(filePath, { rootDir = path.dirname(path.resolve(filePath)), timeoutMs = 1000 } = {}) {
         if (!fs.existsSync(filePath)) {
             throw new Error(`Template file not found: ${filePath}`);
         }
@@ -32,9 +32,17 @@ class HtmxRenderer {
         `;
 
         // Create a custom require function that resolves paths relative to the template
-        const customRequire = (modulePath) => {
-            const absolutePath = path.resolve(path.dirname(filePath), modulePath);
-            return require(absolutePath);
+        const resolvedRoot = path.resolve(rootDir);
+        const customRequire = (modulePath) => {
+            if (typeof modulePath !== 'string' || !modulePath.startsWith('.')) {
+                throw new Error('Templates may only require relative modules');
+            }
+            const absolutePath = path.resolve(path.dirname(filePath), modulePath);
+            const relative = path.relative(resolvedRoot, absolutePath);
+            if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                throw new Error('Template module is outside the allowed root');
+            }
+            return require(absolutePath);
         };
 
         // Execute the script in a sandbox
@@ -48,7 +56,7 @@ class HtmxRenderer {
         vm.createContext(sandbox);
 
         // Get the rendered output
-        let result = script.runInContext(sandbox);
+        let result = script.runInContext(sandbox, { timeout: timeoutMs });
 
         // Normalize spaces but preserve those in content
         result = result

package/src/http/BaseHttpServer.js

@@ -1,9 +1,9 @@
-const express = require('express');
-const bodyParser = require('body-parser');
-const path = require('path');
+const express = require('express');
+const path = require('path');
 const cors = require('cors');
 const fs = require('fs');
-const HtmxRenderer = require('../htmx/HtmxRenderer'); // Import the HtmxRenderer module
+const HtmxRenderer = require('../htmx/HtmxRenderer'); // Import the HtmxRenderer module
+const { validateListenerOptions } = require('../serverLifecycle');
 
 /**
  * @typedef {'json' | 'urlencoded'} RedWebEncoding
@@ -39,8 +39,46 @@ const HTTP_OPTIONS = {
     ssl: null,
     server: undefined,
     corsOptions: undefined,
-    enableHtmxRendering: false, // New option for HTMX rendering
-};
+    enableHtmxRendering: false, // New option for HTMX rendering
+    exposeErrors: false,
+    logger: console,
+};
+
+function assertOptions(options) {
+    validateListenerOptions(options);
+    if (!Object.values(ENCODINGS).includes(options.encoding)) {
+        throw new TypeError('`encoding` must be either "json" or "urlencoded".');
+    }
+    if (!Array.isArray(options.publicPaths)) {
+        throw new TypeError('`publicPaths` must be an array.');
+    }
+    if (options.publicPaths.some(publicPath => typeof publicPath !== 'string' || !publicPath)) {
+        throw new TypeError('Every public path must be a non-empty string.');
+    }
+    if (!Array.isArray(options.services)) {
+        throw new TypeError('`services` must be an array.');
+    }
+
+    options.services.forEach((service) => {
+        if (!service || typeof service.serviceName !== 'string' || !service.serviceName) {
+            throw new TypeError('Every service must have a non-empty `serviceName`.');
+        }
+        if (!['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'all'].includes(service.method)) {
+            throw new TypeError(`Unsupported HTTP service method: ${service.method}`);
+        }
+        if (typeof service.function !== 'function') {
+            throw new TypeError(`Service ${service.serviceName} must provide a function.`);
+        }
+    });
+    if (options.services.filter(service => service.serviceName === '*').length > 1) {
+        throw new TypeError('Only one catch-all service may be registered.');
+    }
+}
+
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
 
 /**
  * Base HTTP Server
@@ -48,60 +86,77 @@ const HTTP_OPTIONS = {
  * @return {Object} Express application instance.
  */
 function BaseHttpServer(options = {}) {
-    this.options = { ...HTTP_OPTIONS, ...options };
-    this.app = this.options.server || express();
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('HTTP server options must be an object.');
+    }
+    const mergedOptions = { ...HTTP_OPTIONS, ...options };
+    assertOptions(mergedOptions);
+    this.options = {
+        ...mergedOptions,
+        publicPaths: [...mergedOptions.publicPaths],
+        services: [...mergedOptions.services],
+    };
+    this.app = this.options.server === undefined ? express() : this.options.server;
+    if (typeof this.app.use !== 'function') {
+        throw new TypeError('`server` must be an Express-compatible application.');
+    }
     Object.assign(this, this.options);
 
     // Middleware to parse request bodies based on the specified encoding
-    if (this.encoding === ENCODINGS.json) {
-        this.app.use(bodyParser.json());
-    } else if (this.encoding === ENCODINGS.urlencoded) {
-        this.app.use(bodyParser.urlencoded({ extended: true }));
-    }
-
-    this.app.use(cors(this.options.corsOptions));
+    if (this.encoding === ENCODINGS.json) {
+        this.app.use(express.json());
+    } else {
+        this.app.use(express.urlencoded({ extended: true }));
+    }
+
+    if (this.options.corsOptions !== false) {
+        this.app.use(cors(this.options.corsOptions));
+    }
 
     // Enable HTMX rendering if the flag is set
     if (this.enableHtmxRendering) {
-        this.app.get('*.htmx', (req, res) => {
-            // Find the file in one of the publicPaths
-            const filePath = this.publicPaths
-                .map(publicPath => path.join(process.cwd(), publicPath, req.path))
-                .find(fullPath => fs.existsSync(fullPath)); // Check if the file exists
-    
-            if (!filePath) {
-                return res.status(404).send(`Error rendering HTMX file: Template file not found: ${req.path}`);
-            }
-    
-            try {
-                const renderedContent = HtmxRenderer.render(filePath);
-                res.type('html').send(renderedContent);
-            } catch (error) {
-                res.status(500).send(`Error rendering HTMX file: ${error.message}`);
-            }
-        });
+        this.app.get('*.htmx', (req, res) => {
+            const match = this.publicPaths
+                .map(publicPath => {
+                    const root = path.resolve(process.cwd(), publicPath);
+                    const filePath = path.resolve(root, `.${req.path}`);
+                    return { root, filePath };
+                })
+                .find(({ root, filePath }) => isWithin(root, filePath) && fs.existsSync(filePath));
+    
+            if (!match) {
+                return res.status(404).send('HTMX template not found');
+            }
+    
+            try {
+                const renderedContent = HtmxRenderer.render(match.filePath, { rootDir: match.root });
+                res.type('html').send(renderedContent);
+            } catch (error) {
+                const message = this.exposeErrors ? `Error rendering HTMX file: ${error.message}` : 'Unable to render HTMX template';
+                res.status(500).send(message);
+            }
+        });
     }
     
 
-    // Serve static files from public paths
-    this.publicPaths.forEach((publicPath) =>
-        this.app.use(express.static(path.join(process.cwd(), publicPath)))
-    );
+    // Serve static files from public paths
+    this.publicPaths.forEach((publicPath) =>
+        this.app.use(express.static(path.resolve(process.cwd(), publicPath)))
+    );
 
-    const catchAll = this.services.find((service) => service.serviceName === '*');
-    if (catchAll) this.services.splice(this.services.indexOf(catchAll), 1);
-    this.services.forEach((service) =>
-        this.app[service.method](service.serviceName, service.function)
-    );
+    const catchAll = this.services.find((service) => service.serviceName === '*');
+    this.services.filter((service) => service !== catchAll).forEach((service) =>
+        this.app[service.method](service.serviceName, service.function)
+    );
     if (catchAll) this.app[catchAll.method](catchAll.serviceName, catchAll.function);
 
     return this;
 }
 
 
-module.exports = {
-    BaseHttpServer,
-    ENCODINGS,
-    HTTP_OPTIONS,
-    METHODS: { GET: 'get', POST: 'post', PUT: 'put', DELETE: 'delete' },
-};
+module.exports = {
+    BaseHttpServer,
+    ENCODINGS,
+    HTTP_OPTIONS,
+    METHODS: { GET: 'get', POST: 'post', PUT: 'put', PATCH: 'patch', DELETE: 'delete', OPTIONS: 'options', HEAD: 'head', ALL: 'all' },
+};

package/src/http/HttpServer.js

@@ -1,16 +1,24 @@
 const http = require('http');
 const { BaseHttpServer } = require('./BaseHttpServer');
+const { listenServer, closeServer } = require('../serverLifecycle');
 
 /**
  * HTTP Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpServer(options = {}) {
+function HttpServer(options) {
     BaseHttpServer.call(this, options);
     this.server = http.createServer(this.app);
+    this.shutdown = () => closeServer(this.server);
     if (this.listen !== false) {
-        this.server.listen(this.port, this.listenCallback ? this.listenCallback : () => console.log(`RedWeb HttpServer listening on port ${this.port}`));
+        listenServer(this.server, {
+            port: this.port,
+            bind: this.bind,
+            callback: this.listenCallback,
+            logger: this.logger,
+            name: 'HttpServer',
+        });
     }
     return this;
 }

package/src/http/HttpsServer.js

@@ -1,21 +1,29 @@
 const https = require('https');
 const { BaseHttpServer } = require('./BaseHttpServer');
-const loadSslConfig = require('../sslConfig');
+const loadSslConfig = require('../sslConfig');
+const { listenServer, closeServer } = require('../serverLifecycle');
 
 /**
  * HTTPS Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpsServer(options = {}) {
+function HttpsServer(options) {
     BaseHttpServer.call(this, options);
     const sslOptions = loadSslConfig(this.ssl);
     this.server = https.createServer(sslOptions, this.app);
+    this.shutdown = () => closeServer(this.server);
     if (this.listen === false) {
         return this;
     }
 
-    this.server.listen(this.port, this.listenCallback ? this.listenCallback : () => console.log(`RedWeb HttpsServer listening on port ${this.port}`));
+    listenServer(this.server, {
+        port: this.port,
+        bind: this.bind,
+        callback: this.listenCallback,
+        logger: this.logger,
+        name: 'HttpsServer',
+    });
     return this;
 }
 

package/src/serverLifecycle.js

@@ -0,0 +1,46 @@
+function listenServer(server, { port, bind, callback, logger = console, name = 'Server' }) {
+    const onListening = callback || (() => logger?.log?.(`RedWeb ${name} listening on ${bind}:${port}`));
+    server.listen(port, bind, onListening);
+}
+
+function validateListenerOptions(options) {
+    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+        throw new TypeError('`port` must be an integer between 0 and 65535.');
+    }
+    if (typeof options.bind !== 'string' || !options.bind) {
+        throw new TypeError('`bind` must be a non-empty string.');
+    }
+    if (typeof options.listen !== 'boolean') {
+        throw new TypeError('`listen` must be a boolean.');
+    }
+    if (options.listenCallback !== undefined && typeof options.listenCallback !== 'function') {
+        throw new TypeError('`listenCallback` must be a function.');
+    }
+}
+
+async function settleTasks(tasks) {
+    const results = await Promise.allSettled(tasks.map(task => Promise.resolve().then(task)));
+    return results.filter(result => result.status === 'rejected').map(result => result.reason);
+}
+
+function throwCleanupErrors(errors, message) {
+    if (!errors.length) return;
+    const aggregate = new Error(message);
+    aggregate.errors = errors;
+    throw aggregate;
+}
+
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        if (!server?.listening) return resolve();
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}
+
+module.exports = {
+    listenServer,
+    closeServer,
+    settleTasks,
+    throwCleanupErrors,
+    validateListenerOptions,
+};