@bjoernboss/mws 1.0.0

package/dist/log.js

@@ -0,0 +1,288 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright (c) 2024-2026 Bjoern Boss Henrichsen */
+import * as libFs from "fs";
+const DEFAULT_FILE_FLUSHING_DELAY = 2_000;
+const DEFAULT_FILE_BUF_MAXIMUM_LINES = 1_000;
+const DEFAULT_FILE_SIZE_SWAP_FILE = 10_000_000;
+const LoggerIdMap = {};
+const GlobalLogConsumers = new Set();
+function formatLevel(level) {
+    switch (level) {
+        case 'log':
+            return 'Log  ';
+        case 'trace':
+            return 'Trace';
+        case 'error':
+            return 'Error';
+        case 'info':
+            return 'Info ';
+        case 'warning':
+            return 'Warn ';
+    }
+}
+function formatLine(level, date, identity, msg, lineBreak) {
+    let printLevel = formatLevel(level);
+    if (lineBreak)
+        return `[${date}] ${printLevel}: [${identity}] ${msg}\n`;
+    return `[${date}] ${printLevel}: [${identity}] ${msg}`;
+}
+/* implementation of a console logger */
+export function createConsoleLogger() {
+    return (level, date, identity, msg) => {
+        if (level == null)
+            return;
+        let levelPrint = formatLevel(level);
+        if (process.stdout?.hasColors == null || !process.stdout.hasColors())
+            return console.log(formatLine(level, date, identity, msg, false));
+        let levelColor = '';
+        switch (level) {
+            case 'log':
+                levelColor = '\x1b[37m';
+                break;
+            case 'trace':
+                levelColor = '\x1b[94m';
+                break;
+            case 'error':
+                levelColor = '\x1b[31m';
+                break;
+            case 'info':
+                levelColor = '\x1b[92m';
+                break;
+            case 'warning':
+                levelColor = '\x1b[33m';
+                break;
+        }
+        console.log(`\x1b[90m[${date}] ${levelColor}${levelPrint}\x1b[0m: [\x1b[93m${identity}\x1b[0m] ${msg}`);
+    };
+}
+/* implementation of a logger which receives a well formatted line */
+export function createLineLogger(cb) {
+    return (level, date, identity, msg) => {
+        if (level != null)
+            cb(formatLine(level, date, identity, msg, false));
+    };
+}
+/* file overwriting preservation mode */
+export var PreserveMode;
+(function (PreserveMode) {
+    /* simply clear the log file once full */
+    PreserveMode[PreserveMode["none"] = 0] = "none";
+    /* preserve the last log file to 'filePath.old' */
+    PreserveMode[PreserveMode["last"] = 1] = "last";
+    /* preserve all last log files to 'filePath.%time%.old */
+    PreserveMode[PreserveMode["all"] = 2] = "all";
+})(PreserveMode || (PreserveMode = {}));
+/* implementation of a file logger, which logs into the file-path and optionally preserves old logs
+*	(Note: contains a timer, server shutdown should clear all loggers to ensure fast shutdown) */
+export function createFileLogger(filePath, options) {
+    /* setup the logging state (ignore any errors, as they cannot be logged) */
+    let fileHandle = null;
+    let logFileSize = 0;
+    try {
+        fileHandle = libFs.openSync(filePath, 'a');
+        logFileSize = libFs.fstatSync(fileHandle).size;
+    }
+    catch (_) { }
+    /* setup the file-flushing helper function */
+    let logBuffer = [];
+    let flushId = null;
+    const flushToFile = () => {
+        /* write the buffer to the file */
+        if (logBuffer.length > 0 && fileHandle != null) {
+            const content = Buffer.from(logBuffer.join(""), 'utf-8');
+            try {
+                libFs.writeFileSync(fileHandle, content);
+            }
+            catch (_) { }
+            logFileSize += content.length;
+        }
+        logBuffer = [];
+        /* clear any currently queued flushes */
+        if (flushId != null) {
+            clearTimeout(flushId);
+            flushId = null;
+        }
+    };
+    const flushingDelayMs = (options?.flushingDelayMs == null ? DEFAULT_FILE_FLUSHING_DELAY : options.flushingDelayMs);
+    const bufMaxLineCount = (options?.bufMaxLineCount == null ? DEFAULT_FILE_BUF_MAXIMUM_LINES : options.bufMaxLineCount);
+    const sizeSwapFile = (options?.sizeSwapFile == null ? DEFAULT_FILE_SIZE_SWAP_FILE : options.sizeSwapFile);
+    /* setup the actual closure handler */
+    return (level, date, identity, msg) => {
+        /* check if the logger is being disabled and reset the file state */
+        if (level == null) {
+            flushToFile();
+            if (fileHandle != null)
+                try {
+                    libFs.closeSync(fileHandle);
+                }
+                catch (_) { }
+            fileHandle = null;
+            return;
+        }
+        /* write the log to the buffer and check if the data need to be flushed inplace, or if the flushing can be delayed */
+        logBuffer.push(formatLine(level, date, identity, msg, true));
+        if (logBuffer.length >= bufMaxLineCount)
+            flushToFile();
+        else {
+            if (flushId != null)
+                clearTimeout(flushId);
+            flushId = setTimeout(flushToFile, flushingDelayMs);
+        }
+        /* check if the log-files need to be swapped */
+        if (logFileSize < sizeSwapFile)
+            return;
+        /* flush the buffered entries and close the current file */
+        flushToFile();
+        if (fileHandle != null) {
+            try {
+                libFs.closeSync(fileHandle);
+            }
+            catch (_) { }
+            fileHandle = null;
+        }
+        /* preserve the old file to be used or remove it */
+        if (options?.preserve == PreserveMode.all)
+            try {
+                libFs.renameSync(filePath, `${filePath}.${Date.now()}.old`);
+            }
+            catch (_) { }
+        else if (options?.preserve == PreserveMode.last)
+            try {
+                libFs.renameSync(filePath, `${filePath}.old`);
+            }
+            catch (_) { }
+        else
+            try {
+                libFs.unlinkSync(filePath);
+            }
+            catch (_) { }
+        try {
+            fileHandle = libFs.openSync(filePath, 'w');
+        }
+        catch (_) { }
+        logFileSize = 0;
+    };
+}
+/* implementation of a log filter, which can filter by matching level and identity including a given sub-string, and then forwards these logs to the target logger */
+export function createLogFilter(target, options) {
+    const filterLevel = (options?.level == null ? null : new Set(Array.isArray(options.level) ? options.level : [options.level]));
+    const filterIdentity = (options?.identity == null ? null : (Array.isArray(options.identity) ? options.identity : [options.identity]));
+    return (level, date, identity, msg) => {
+        if (level == null)
+            return target(null, '', '', '');
+        /* check if the level is supported */
+        if (filterLevel != null && !filterLevel.has(level))
+            return;
+        if (filterIdentity != null && !filterIdentity.some((value) => identity.includes(value)))
+            return;
+        target(level, date, identity, msg);
+    };
+}
+/* logger class to extend, supporting various logging classes, and writing to the registered log consumer */
+export class Logger {
+    _rootIdentity;
+    _logIdentity;
+    _logTagList;
+    constructor(identity) {
+        const id = (LoggerIdMap[identity] ?? 0) + 1;
+        LoggerIdMap[identity] = id;
+        this._rootIdentity = `${identity}!${id}`;
+        this._logIdentity = this._rootIdentity;
+        this._logTagList = [];
+    }
+    _updateLogIdentity() {
+        this._logIdentity = this._rootIdentity;
+        for (const tag of this._logTagList) {
+            if (tag.value != '')
+                this._logIdentity += `.${tag.value}`;
+        }
+    }
+    _performActualLog(level, msg, options) {
+        const identity = (options?.extension == null ? this._logIdentity : this._rootIdentity + (options.extension == '' ? '' : `.${options.extension}`));
+        logGlobal(level, identity, msg);
+    }
+    /* root identity tagged with unique id */
+    get logRoot() {
+        return this._rootIdentity;
+    }
+    /* tag extension appended to root identity to form full logging identity */
+    get logExtension() {
+        return this._logIdentity.substring(this._rootIdentity.length + 1);
+    }
+    /* full logging identity as shown in logs */
+    get logIdentity() {
+        return this._logIdentity;
+    }
+    /* tag the logging with the given identifier and return a callback to update the tag */
+    tagLog(identifier) {
+        let tag = { value: identifier };
+        this._logTagList.push(tag);
+        if (tag.value != '')
+            this._updateLogIdentity();
+        /* setup the handler responsible to update the logging */
+        return (value) => {
+            if (tag == null)
+                return;
+            /* check if the tag should be removed or if the value should just be updated */
+            if (value == null) {
+                this._logTagList = this._logTagList.filter((v) => v != tag);
+                tag = null;
+            }
+            else if (value != tag.value)
+                tag.value = value;
+            this._updateLogIdentity();
+        };
+    }
+    error(msg, options) {
+        this._performActualLog('error', msg, options);
+    }
+    info(msg, options) {
+        this._performActualLog('info', msg, options);
+    }
+    warning(msg, options) {
+        this._performActualLog('warning', msg, options);
+    }
+    log(msg, options) {
+        this._performActualLog('log', msg, options);
+    }
+    trace(msg, options) {
+        this._performActualLog('trace', msg, options);
+    }
+}
+/* create a logger class to create associated logs */
+export function createLogger(identity) {
+    return new Logger(identity);
+}
+/* register another global logger to receive the logs (returned detacher can be invoked to remove the log) */
+export function addLogger(cb) {
+    let detached = false;
+    const wrapped = (level, date, identity, msg) => {
+        if (detached)
+            return;
+        if (level == null) {
+            GlobalLogConsumers.delete(wrapped);
+            detached = true;
+        }
+        try {
+            if (detached)
+                cb(null, '', '', '');
+            else
+                cb(level, date, identity, msg);
+        }
+        catch (err) {
+            console.error(`Logger failed: ${err.message}`);
+            wrapped(null, '', '', '');
+        }
+    };
+    GlobalLogConsumers.add(wrapped);
+    return () => {
+        wrapped(null, '', '', '');
+    };
+}
+/* perform a global log to all registered loggers */
+export function logGlobal(level, identity, msg) {
+    const date = new Date().toUTCString();
+    for (const cb of GlobalLogConsumers)
+        cb(level, date, identity, msg);
+}
+//# sourceMappingURL=log.js.map

package/dist/server.d.ts

@@ -0,0 +1,66 @@
+import * as libLog from "./log.js";
+import * as libClient from "./client.js";
+import * as libHandler from "./handler.js";
+import * as libCache from "./cache.js";
+import * as libHttp from "http";
+import * as libNet from "net";
+export declare class Server extends libLog.Logger {
+    private _stop;
+    private _cache;
+    private _config;
+    private _nextId;
+    constructor(config?: ServerConfig);
+    private handleClient;
+    private fetchAddress;
+    private performServerCleanup;
+    private emitEventSync;
+    private makeServer;
+    listen(handler: libHandler.ModuleHandler, options?: ListenOptions): Listener;
+    stop(): Promise<void>;
+    get cache(): libCache.CacheHost;
+    get config(): BurntServerConfig;
+    get stopped(): Promise<void>;
+    get running(): boolean;
+    linkModule(module: libHandler.ModuleHandler, unlinked?: () => void): libHandler.AttachedModule;
+}
+export interface Listener {
+    stop(): Promise<void>;
+    on<K extends keyof ListenerEvents>(event: K, listener: ListenerEvents[K]): Listener;
+    off<K extends keyof ListenerEvents>(event: K, listener: ListenerEvents[K]): Listener;
+    once<K extends keyof ListenerEvents>(event: K, listener: ListenerEvents[K]): Listener;
+}
+type ListenerEvents = {
+    'listening': (address: libNet.AddressInfo) => void;
+    'failed': (err: Error) => void;
+    'stopped': () => void;
+};
+export interface ListenOptions {
+    port?: number;
+    hostname?: string;
+    client?: libClient.ClientConfig | libClient.BurntClientConfig;
+    tls?: {
+        key: string;
+        cert: string;
+    };
+    server?: {
+        server: libHttp.Server;
+        secure: boolean;
+    };
+}
+export declare function createServer(config?: ServerConfig): Server;
+export interface ServerConfig {
+    headerTimeout?: number;
+    connectionTimeout?: number;
+    keepAliveTimeout?: number;
+    client?: libClient.ClientConfig | libClient.BurntClientConfig;
+    cache?: libCache.CacheHost | libCache.CacheConfig | libCache.BurntCacheConfig;
+}
+export declare class BurntServerConfig {
+    readonly headerTimeout: number;
+    readonly connectionTimeout: number;
+    readonly keepAliveTimeout: number;
+    readonly client: libClient.BurntClientConfig;
+    constructor(config?: ServerConfig);
+}
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,257 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright (c) 2024-2026 Bjoern Boss Henrichsen */
+import * as libLog from "./log.js";
+import * as libClient from "./client.js";
+import * as libCache from "./cache.js";
+import * as libHttps from "https";
+import * as libHttp from "http";
+import * as libWs from "ws";
+import * as libFs from "fs";
+import * as libEvents from "events";
+const CONNECTION_TIMEOUT_CHECKING = 10_000;
+export class Server extends libLog.Logger {
+    _stop;
+    _cache;
+    _config;
+    _nextId;
+    constructor(config) {
+        super('server');
+        this.info(`Server created`);
+        this._config = new BurntServerConfig(config);
+        if (config?.cache instanceof libCache.CacheHost)
+            this._cache = config.cache;
+        else
+            this._cache = libCache.createCache(config?.cache);
+        this._nextId = 0;
+        let stoppedResolver = () => { };
+        this._stop = { listener: [], stoppedPromise: new Promise((res) => stoppedResolver = res), stoppedResolver: () => { }, stopping: false };
+        this._stop.stoppedResolver = stoppedResolver;
+    }
+    async handleClient(request, client, handler, id) {
+        this.log(`Listener[${id}]: Client [${client.logIdentity}] connected using [method: ${request.method ?? '_'}] from [${request.socket.remoteAddress}]:${request.socket.remotePort} to [${client.url.hostname}]:[${request.url}] (user-agent: [${request.headers['user-agent'] ?? ''}])`);
+        try {
+            await handler.handle(client);
+        }
+        catch (err) {
+            client.respondInternalError(`Uncaught exception: ${err.message}`);
+        }
+        /* kill the connection on any errors, as the finalizing normally ensures that the response is completed */
+        try {
+            await client.finalizeConnection();
+        }
+        catch (err) {
+            this.error(`Fatal error while finalizing client: ${err.message}`);
+            request.destroy(new Error('Unhandled exception'));
+        }
+        this.log(`Listener[${id}]: Client [${client.logIdentity}] completed`);
+    }
+    fetchAddress(server) {
+        const raw = server.address();
+        if (raw == null)
+            return null;
+        if (typeof raw == 'string')
+            return { address: raw, port: 0, family: 'unix' };
+        return raw;
+    }
+    async performServerCleanup(server, id, who, attached, wss) {
+        /* close the server and any existing connections within it */
+        const address = this.fetchAddress(server);
+        if (address != null && id != null)
+            this.info(`Stopping ${who} on [${address.address}]:${address.port} [family: ${address.family}] as listener [${id}] with handler [${attached.module.logIdentity}]`);
+        const serverStopped = new Promise((res) => server.close(() => res()));
+        server.closeAllConnections();
+        /* close all of the web-sockets (after unlinking the module to
+        *	ensure it has a chance to clean the connections itself) */
+        await attached.unlink();
+        const sockets = [];
+        for (const ws of [...wss.clients]) {
+            if (ws.readyState == libWs.WebSocket.CLOSED)
+                continue;
+            sockets.push(new Promise((res) => ws.on('close', () => res())));
+            ws.terminate();
+        }
+        await Promise.all(sockets);
+        /* await the server being fully stopped */
+        await serverStopped;
+    }
+    emitEventSync(emitter, event, ...args) {
+        try {
+            emitter.emit(event, ...args);
+        }
+        catch (err) {
+            this.error(`Unhandled exception in ${event} listener: ${err.message}`);
+        }
+    }
+    makeServer(options) {
+        if (options?.tls != null) {
+            const config = {
+                requireHostHeader: true,
+                key: libFs.readFileSync(options.tls.key),
+                cert: libFs.readFileSync(options.tls.cert),
+                connectionsCheckingInterval: CONNECTION_TIMEOUT_CHECKING
+            };
+            return libHttps.createServer(config);
+        }
+        if (options?.server != null)
+            return options.server.server;
+        return libHttp.createServer({ requireHostHeader: true, connectionsCheckingInterval: CONNECTION_TIMEOUT_CHECKING });
+    }
+    /* listener is automatically stopped when the server is stopped or the handler stops itself */
+    listen(handler, options) {
+        const protocol = ((options?.tls != null || options?.server?.secure === true) ? 'https' : 'http');
+        const who = `${protocol}:${options?.hostname ?? ''}:${options?.port ?? 0}`, idListener = this._nextId++;
+        const emitter = new libEvents.EventEmitter();
+        /* setup the listener interface to be returned */
+        let stopping = null, listenLogged = false;
+        let server = null;
+        const listener = {
+            on: function (event, cb) { emitter.on(event, cb); return this; },
+            once: function (event, cb) { emitter.once(event, cb); return this; },
+            off: function (event, cb) { emitter.off(event, cb); return this; },
+            stop: () => {
+                if (stopping != null)
+                    return stopping;
+                /* already setup the promise to ensure nested stop-calls will already see it set */
+                let resolver = () => { };
+                stopping = new Promise((res) => resolver = res);
+                (async () => {
+                    if (server != null)
+                        await this.performServerCleanup(server, (listenLogged ? idListener : null), who, attached, wss);
+                    /* check if the cleanup can be removed from the stop list (only if stopping is not already in progress) */
+                    if (!this._stop.stopping)
+                        this._stop.listener = this._stop.listener.filter((v) => v != listener.stop);
+                    this.emitEventSync(emitter, 'stopped');
+                    resolver();
+                })();
+                return stopping;
+            }
+        };
+        const performFailure = (err) => {
+            /* defer the failure to allow the caller to attach listeners */
+            process.nextTick(() => {
+                if (stopping == null)
+                    this.emitEventSync(emitter, 'failed', err);
+                listener.stop();
+            });
+        };
+        /* check if the server is being stopped, in which case nothing will be listened to */
+        if (this._stop.stopping) {
+            this.error(`Stopped server cannot listen to ${who}`);
+            performFailure(new Error('Server already stopped'));
+            return listener;
+        }
+        /* setup the origin server */
+        try {
+            server = this.makeServer(options);
+        }
+        catch (err) {
+            this.error(`Error creating server ${who}: ${err.message}`);
+            performFailure(err);
+            return listener;
+        }
+        /* register the handler properly and register the cleanup callback */
+        const attached = handler._rootAttachToServer(this, () => listener.stop());
+        const wss = new libWs.WebSocketServer({ noServer: true });
+        this._stop.listener.push(listener.stop);
+        /* register the corresponding connection handlers and error handlers */
+        const clientConfig = (options?.client != null ? libClient.BurntClientConfig.from(options.client) : this._config.client);
+        server.on('request', (req, resp) => {
+            const client = libClient.ClientRequest.fromRequest(protocol, req, resp, { cache: this._cache, config: clientConfig });
+            this.handleClient(req, client, attached, idListener);
+        });
+        server.on('upgrade', (req, sock, head) => {
+            const client = libClient.ClientRequest.fromUpgrade(protocol, req, sock, head, { cache: this._cache, config: clientConfig, wss });
+            this.handleClient(req, client, attached, idListener);
+        });
+        server.once('error', (err) => {
+            if (stopping != null)
+                return;
+            this.error(`Error while listening to ${who}: ${err.message}`);
+            this.emitEventSync(emitter, 'failed', err);
+            listener.stop();
+        });
+        server.on('listening', () => {
+            if (stopping != null)
+                return;
+            const address = this.fetchAddress(server);
+            this.info(`Successfully started ${who} on [${address.address}]:${address.port} [family: ${address.family}] as listener [${idListener}] with handler [${handler.logIdentity}]`);
+            listenLogged = true;
+            this.emitEventSync(emitter, 'listening', address);
+        });
+        /* configure the server to have a minimum header receive timeout, overall connection-loss timeout,
+        *	and keep-alive timeout (no request-timeout, as this is handled manually by the throughput control) */
+        server.headersTimeout = this._config.headerTimeout;
+        server.timeout = this._config.connectionTimeout;
+        server.keepAliveTimeout = this._config.keepAliveTimeout;
+        server.requestTimeout = 0;
+        /* start the actual server listening */
+        try {
+            server.listen(options?.port, options?.hostname);
+        }
+        catch (err) {
+            this.error(`Error starting listener ${who}: ${err.message}`);
+            performFailure(err);
+        }
+        return listener;
+    }
+    /* shutdown the server and unlink all modules (immediately kills all open connections and listener; can be called multiple times) */
+    async stop() {
+        if (this._stop.stopping)
+            return this._stop.stoppedPromise;
+        this._stop.stopping = true;
+        /* stop all connections and listener */
+        this.info('Stopping server connections and modules');
+        const promises = [];
+        for (const cb of this._stop.listener)
+            promises.push(cb());
+        await Promise.all(promises);
+        this.info('Server stopped');
+        this._stop.stoppedResolver();
+        return this._stop.stoppedPromise;
+    }
+    /* cache host used by this server */
+    get cache() {
+        return this._cache;
+    }
+    /* configuration used by this server */
+    get config() {
+        return this._config;
+    }
+    /* resolves once the server has stopped */
+    get stopped() {
+        return this._stop.stoppedPromise;
+    }
+    /* check if the server is still running */
+    get running() {
+        return !this._stop.stopping;
+    }
+    /* link the given module to the server (automatically unlinked upon server stop) */
+    linkModule(module, unlinked) {
+        const cleanup = () => attached.unlink();
+        this._stop.listener.push(cleanup);
+        const attached = module._rootAttachToServer(this, () => {
+            if (unlinked != null)
+                unlinked();
+            if (!this._stop.stopping)
+                this._stop.listener = this._stop.listener.filter((v) => v != cleanup);
+        });
+        return attached;
+    }
+}
+/* wrapper to create a simple server */
+export function createServer(config) {
+    return new Server(config);
+}
+export class BurntServerConfig {
+    headerTimeout;
+    connectionTimeout;
+    keepAliveTimeout;
+    client;
+    constructor(config) {
+        this.headerTimeout = config?.headerTimeout ?? 30_000;
+        this.connectionTimeout = config?.connectionTimeout ?? 90_000;
+        this.keepAliveTimeout = config?.keepAliveTimeout ?? 10_000;
+        this.client = libClient.BurntClientConfig.from(config?.client);
+    }
+}
+//# sourceMappingURL=server.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@bjoernboss/mws",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "Modular Web Server — a TypeScript framework for hosting isolated modules behind HTTP/HTTPS+WebSocket endpoints",
+	"license": "BSD-3-Clause",
+	"author": "Bjoern Boss Henrichsen <bjoernbossdev@gmail.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/BjoernBoss/mws.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./*.js": {
+			"types": "./dist/*.d.ts",
+			"default": "./dist/*.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist/**/*.js",
+		"dist/**/*.d.ts"
+	],
+	"scripts": {
+		"prepare": "tsc"
+	},
+	"dependencies": {
+		"ws": "^8.18.1",
+		"@types/ws": "^8.18.1"
+	},
+	"devDependencies": {
+		"@types/node": "^25.6.0",
+		"typescript": "^6.0.3"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	}
+}