@bjoernboss/mws 1.0.0 → 1.1.0

package/dist/helper.js

@@ -14,15 +14,15 @@ for (const media of Object.values(libBase.Media)) {
 }
 for (const encoding of Object.values(libBase.Encoding))
     EncodingNameToEncodingTypeMapping[encoding.name] = encoding;
-/* lookup the encoding for a given name */
+/** lookup the encoding for a given name */
 export function lookupEncoding(name) {
     return EncodingNameToEncodingTypeMapping[name.toLowerCase()] ?? null;
 }
-/* list of all supported encodings */
+/** list of all supported encodings */
 export function supportedEncodingNames() {
     return Object.keys(EncodingNameToEncodingTypeMapping);
 }
-/* map extension of file-path/file-name to media type (null if no match was found) */
+/** map extension of file-path/file-name to media type (null if no match was found) */
 export function lookupMediaTypeFromFile(filePath) {
     const fileExtension = splitFilePath(filePath)[2];
     if (fileExtension != '') {
@@ -32,13 +32,13 @@ export function lookupMediaTypeFromFile(filePath) {
     }
     return null;
 }
-/* format the media type to the proper http header identifier */
+/** format the media type to the proper http header identifier */
 export function buildMediaTypeIdentifier(media) {
     if (media.encoding == '')
         return media.mediaType;
     return `${media.mediaType}; ${media.encoding}`;
 }
-/* does not respect 'no-identity' encoding requests; unknown at-least-size is considered valid (defaults 'identity' to null) */
+/** does not respect 'no-identity' encoding requests; unknown at-least-size is considered valid (defaults 'identity' to null) */
 export function negotiateEncoding(accept, atLeastSize, media) {
     if (!media.compressible || accept == null)
         return null;
@@ -90,7 +90,7 @@ export var RangeState;
     RangeState[RangeState["issue"] = 2] = "issue";
     RangeState[RangeState["malformed"] = 3] = "malformed";
 })(RangeState || (RangeState = {}));
-/* parse an http header range request (first and last are correct for all valid range states; will be [0,-1] for an emtpy file) */
+/** parse an http header range request (first and last are correct for all valid range states; will be [0,-1] for an emtpy file) */
 export function parseRangeHeader(range, fileSize) {
     if (range == null)
         return { first: 0, last: fileSize - 1, state: RangeState.noRange };
@@ -136,7 +136,7 @@ export function parseRangeHeader(range, fileSize) {
         return { first: 0, last: 0, state: RangeState.issue };
     return { first: fileSize - last, last: fileSize - 1, state: RangeState.valid };
 }
-/* check if the [etag] matches the list (i.e. in list or list is '*'), will not match for undefined list; if [strong]
+/** check if the [etag] matches the list (i.e. in list or list is '*'), will not match for undefined list; if [strong]
 *	comparison, both must be non-weak, opaque-tags equal (strip W/ prefix and compare opaque-tags regardless of weakness) */
 export function etagMatchesList(etag, header, strong) {
     if (header == null)
@@ -154,7 +154,7 @@ export function etagMatchesList(etag, header, strong) {
     }
     return false;
 }
-/* returns null on invalid times, [>0] for a being greater, [<0] for a being smaller, [=0] for same time */
+/** returns null on invalid times, [>0] for a being greater, [<0] for a being smaller, [=0] for same time */
 export function timestampCompare(a, b) {
     const _a = new Date(a).getTime();
     if (isNaN(_a))
@@ -164,7 +164,7 @@ export function timestampCompare(a, b) {
         return null;
     return (_a - _b);
 }
-/* split a list value while removing whitespace and optionally respecting quotes (returns empty list on validly quoted strings) */
+/** split a list value while removing whitespace and optionally respecting quotes (returns empty list on validly quoted strings) */
 export function splitAndTrimList(content, separator, quotesAware) {
     if (content == null)
         return [];
@@ -182,7 +182,7 @@ export function splitAndTrimList(content, separator, quotesAware) {
     output.push(current.trim());
     return output;
 }
-/* escape all html-special characters to prevent injection when embedding untrusted values */
+/** escape all html-special characters to prevent injection when embedding untrusted values */
 export function escapeHtml(content) {
     let out = '';
     for (let i = 0; i < content.length; ++i) {
@@ -209,7 +209,7 @@ export function escapeHtml(content) {
     }
     return out;
 }
-/* expand the placeholders in the content (format: {#name}, with '{#' being escaped as '{##'; optionally html-escape values) */
+/** expand the placeholders in the content (format: {#name}, with '{#' being escaped as '{##'; optionally html-escape values) */
 export function expandPlaceholders(content, args, htmlEscape) {
     let out = '', name = '', placeholder = false;
     for (let i = 0; i < content.length; ++i) {
@@ -239,7 +239,7 @@ export function expandPlaceholders(content, args, htmlEscape) {
         helperLogger.warning('Content ends with an incomplete placeholder');
     return out;
 }
-/* escape all placeholders in the content */
+/** escape all placeholders in the content */
 export function escapePlaceholders(content) {
     let out = '';
     /* construct the new escaped output content */
@@ -251,7 +251,7 @@ export function escapePlaceholders(content) {
     }
     return out;
 }
-/* sanitize path and remove relative path components and convert it to an absolute path */
+/** sanitize path and remove relative path components and convert it to an absolute path */
 export function sanitize(path, relative) {
     /* treat the path as absolute, but preserve backward traversals into the root */
     let out = '/';
@@ -298,7 +298,7 @@ export function sanitize(path, relative) {
         out = '.';
     return out;
 }
-/* join two paths into the sanitized absolute server path-environment */
+/** join two paths into the sanitized absolute server path-environment */
 export function joinSanitized(a, b) {
     if (a.length == 0 || b.length == 0)
         return sanitize(a.length == 0 ? b : a, false);
@@ -307,7 +307,7 @@ export function joinSanitized(a, b) {
         return sanitize(bSlash ? a + b.substring(1) : a + b, false);
     return sanitize(bSlash ? a + b : `${a}/${b}`, false);
 }
-/* check if the sanitized path is a sub-path of or equal to the sanitized base path */
+/** check if the sanitized path is a sub-path of or equal to the sanitized base path (can be /base or /base/...) */
 export function isSubPath(base, path) {
     if (base.length > path.length)
         return false;
@@ -317,37 +317,37 @@ export function isSubPath(base, path) {
         return false;
     return (path[base.length] == '/' || base.endsWith('/'));
 }
-/* check if the sanitized path is a true sub-path of the sanitized base path */
+/** check if the sanitized path is a true sub-path of the sanitized base path (must be truly inside: /base/...) */
 export function isInside(base, path) {
     if (base.length >= path.length)
         return false;
     if (!path.startsWith(base))
         return false;
-    return (path[base.length] == '/' || base.endsWith('/'));
+    return ((path[base.length] == '/' && base.length + 1 < path.length) || base.endsWith('/'));
 }
-/* return the remaining path for the sub directory path in base (must be a true sub-directory) */
+/** return the remaining path for the sub directory path in base (must be a true sub-directory) */
 export function childPath(base, path) {
     const out = path.substring(base.endsWith('/') ? base.length - 1 : base.length);
     return (out == '' ? '/' : out);
 }
-/* rebase the path from the old base directory onto the new base (must be a true sub-directory) */
+/** rebase the path from the old base directory onto the new base (must be a true sub-directory) */
 export function rebasePath(oldBase, newBase, path) {
     return joinSanitized(newBase, childPath(oldBase, path));
 }
-/* create path-creator, which returns sanitized paths relative to [path] */
+/** create path-creator, which returns sanitized paths relative to [path] */
 export function createPathLocation(path) {
     return function (p) {
         return libPath.join(path, sanitize(p, false));
     };
 }
-/* create path-creator, which returns paths relative to the file url path (like the script itself using 'import.meta.url') and optionally the nested path [path] */
-export function createPathSelf(urlFilePath, path = null) {
+/** create path-creator, which returns paths relative to the file url path (like the script itself using 'import.meta.url') and optionally changed by relative [path] */
+export function createPathSelf(urlFilePath, path) {
     let dirName = libPath.dirname(libUrl.fileURLToPath(urlFilePath));
     if (path != null)
         dirName = libPath.join(dirName, sanitize(path, true));
     return createPathLocation(dirName);
 }
-/* split the path in three components ['/base/', 'name', '.extension'] (extension will be empty if the path
+/** split the path in three components ['/base/', 'name', '.extension'] (extension will be empty if the path
 *	does not contain a distinct extension; path will be empty if the path does not contain a distinct path) */
 export function splitFilePath(path) {
     let dot = null;

package/dist/log.d.ts

@@ -1,52 +1,63 @@
+/** supported log level */
 export type LogLevel = 'error' | 'info' | 'warning' | 'log' | 'trace';
+/** if [level] is null: is not a log, but the callback is being unregistered */
 export type LogConsumer = (level: LogLevel | null, date: string, identity: string, msg: string) => void;
+/** type to invoke to detach the given logger */
 export type Detacher = () => void;
-export type TagUpdate = (value?: string) => void;
+/** implementation of a console logger */
 export declare function createConsoleLogger(): LogConsumer;
+/** implementation of a logger which receives a well formatted line */
 export declare function createLineLogger(cb: (line: string) => void): LogConsumer;
+/** file overwriting preservation mode */
 export declare enum PreserveMode {
+    /** simply clear the log file once full */
     none = 0,
+    /** preserve the last log file to 'filePath.old' */
     last = 1,
+    /** preserve all last log files to 'filePath.%time%.old */
     all = 2
 }
+/** 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 declare function createFileLogger(filePath: string, options?: {
     flushingDelayMs?: number;
     bufMaxLineCount?: number;
     sizeSwapFile?: number;
     preserve?: PreserveMode;
 }): LogConsumer;
+/** 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 declare function createLogFilter(target: LogConsumer, options?: {
     level?: LogLevel | LogLevel[];
     identity?: string | string[];
 }): LogConsumer;
+/** logger class to extend, supporting various logging classes, and writing to the registered log consumer */
+export declare function createLogger(identity: string): Logger;
 export declare class Logger {
-    private _rootIdentity;
     private _logIdentity;
-    private _logTagList;
     constructor(identity: string);
-    private _updateLogIdentity;
     private _performActualLog;
-    get logRoot(): string;
-    get logExtension(): string;
-    get logIdentity(): string;
-    tagLog(identifier: string): TagUpdate;
+    /** update the log identity */
+    protected logSetIdentity(identity: string): void;
+    /** logging identity as shown in logs */
+    get identity(): string;
     error(msg: string, options?: {
-        extension?: string;
+        identity?: string;
     }): void;
     info(msg: string, options?: {
-        extension?: string;
+        identity?: string;
     }): void;
     warning(msg: string, options?: {
-        extension?: string;
+        identity?: string;
     }): void;
     log(msg: string, options?: {
-        extension?: string;
+        identity?: string;
     }): void;
     trace(msg: string, options?: {
-        extension?: string;
+        identity?: string;
     }): void;
 }
-export declare function createLogger(identity: string): Logger;
+/** register another global logger to receive the logs (returned detacher can be invoked to remove the log) */
 export declare function addLogger(cb: LogConsumer): Detacher;
+/** perform a global log to all registered loggers */
 export declare function logGlobal(level: LogLevel, identity: string, msg: string): void;
 //# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -26,7 +26,7 @@ function formatLine(level, date, identity, msg, lineBreak) {
         return `[${date}] ${printLevel}: [${identity}] ${msg}\n`;
     return `[${date}] ${printLevel}: [${identity}] ${msg}`;
 }
-/* implementation of a console logger */
+/** implementation of a console logger */
 export function createConsoleLogger() {
     return (level, date, identity, msg) => {
         if (level == null)
@@ -55,24 +55,24 @@ export function createConsoleLogger() {
         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 */
+/** 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 */
+/** file overwriting preservation mode */
 export var PreserveMode;
 (function (PreserveMode) {
-    /* simply clear the log file once full */
+    /** simply clear the log file once full */
     PreserveMode[PreserveMode["none"] = 0] = "none";
-    /* preserve the last log file to 'filePath.old' */
+    /** preserve the last log file to 'filePath.old' */
     PreserveMode[PreserveMode["last"] = 1] = "last";
-    /* preserve all last log files to 'filePath.%time%.old */
+    /** 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
+/** 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) */
@@ -163,7 +163,7 @@ export function createFileLogger(filePath, options) {
         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 */
+/** 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]));
@@ -178,61 +178,29 @@ export function createLogFilter(target, options) {
         target(level, date, identity, msg);
     };
 }
-/* logger class to extend, supporting various logging classes, and writing to the registered log consumer */
+/** logger class to extend, supporting various logging classes, and writing to the registered log consumer */
+export function createLogger(identity) {
+    return new Logger(identity);
+}
 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}`;
-        }
+        this._logIdentity = `${identity}!${id}`;
     }
     _performActualLog(level, msg, options) {
-        const identity = (options?.extension == null ? this._logIdentity : this._rootIdentity + (options.extension == '' ? '' : `.${options.extension}`));
+        const identity = (options?.identity == null ? this._logIdentity : options.identity);
         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);
+    /** update the log identity */
+    logSetIdentity(identity) {
+        this._logIdentity = identity;
     }
-    /* full logging identity as shown in logs */
-    get logIdentity() {
+    /** logging identity as shown in logs */
+    get identity() {
         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);
     }
@@ -249,11 +217,7 @@ export class Logger {
         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) */
+/** 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) => {
@@ -279,7 +243,7 @@ export function addLogger(cb) {
         wrapped(null, '', '', '');
     };
 }
-/* perform a global log to all registered loggers */
+/** perform a global log to all registered loggers */
 export function logGlobal(level, identity, msg) {
     const date = new Date().toUTCString();
     for (const cb of GlobalLogConsumers)

package/dist/server.d.ts

@@ -4,55 +4,112 @@ import * as libHandler from "./handler.js";
 import * as libCache from "./cache.js";
 import * as libHttp from "http";
 import * as libNet from "net";
+import * as libStream from "stream";
+type ListenerEvents = {
+    'listening': (address: libNet.AddressInfo | null) => void;
+    'failed': (err: Error) => void;
+    'stopped': () => void;
+};
 export declare class Server extends libLog.Logger {
     private _stop;
     private _cache;
     private _config;
-    private _nextId;
+    private _nextEndpoint;
     constructor(config?: ServerConfig);
-    private handleClient;
-    private fetchAddress;
-    private performServerCleanup;
-    private emitEventSync;
-    private makeServer;
+    /** listener is automatically stopped when the server is stopped or the handler stops itself */
     listen(handler: libHandler.ModuleHandler, options?: ListenOptions): Listener;
+    /** shutdown the server and unlink all modules (immediately kills all open connections and listener; can be called multiple times) */
     stop(): Promise<void>;
+    /** cache host used by this server */
     get cache(): libCache.CacheHost;
+    /** configuration used by this server */
     get config(): BurntServerConfig;
+    /** resolves once the server has stopped */
     get stopped(): Promise<void>;
+    /** check if the server is still running */
     get running(): boolean;
+    /** link the given module to the server (automatically unlinked upon server stop) */
     linkModule(module: libHandler.ModuleHandler, unlinked?: () => void): libHandler.AttachedModule;
 }
-export interface Listener {
+/**
+*	Either 'listening' or 'failed' is fired, followed at some point by a 'stopped' event.
+*	'address' of 'listening' event is null for serverless listener.
+*/
+export declare class Listener {
+    private _host;
+    private _self;
+    private _stop;
+    private _native;
+    private _handling;
+    private _emitter;
+    private _config;
+    private constructor();
+    private emitEventSync;
+    private performServerListening;
+    private handleClient;
+    private configure;
+    static _fromParams(server: Server, handler: libHandler.ModuleHandler, id: number, hostStop: {
+        stopping: boolean;
+        list: (() => Promise<void>)[];
+    }, options: ListenOptions): Listener;
+    /** manually pass a request through the listener (takes ownership of the request; will kill the connection if the listener is not running anymore) */
+    handleRequest(request: libHttp.IncomingMessage, response: libHttp.ServerResponse): Promise<void>;
+    /** manually pass an upgrade through the listener (takes ownership of the connection; immediately closes the connection if the listener is not running anymore) */
+    handleUpgrade(request: libHttp.IncomingMessage, socket: libStream.Duplex, head: Buffer): Promise<void>;
+    /** server this listener belongs to */
+    get server(): Server;
+    /** client configuration used for this listener */
+    get config(): libClient.BurntClientConfig;
+    /** stop the listener and return promise which resolves once fully stopped */
     stop(): Promise<void>;
+    /** resolves once the server has stopped */
+    get stopped(): Promise<void>;
+    /** check if the server is still running */
+    get running(): boolean;
     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;
+    off<K extends keyof ListenerEvents>(event: K, listener: ListenerEvents[K]): Listener;
 }
-type ListenerEvents = {
-    'listening': (address: libNet.AddressInfo) => void;
-    'failed': (err: Error) => void;
-    'stopped': () => void;
-};
+/** server order: (tls > server > shallow > http.Server) */
 export interface ListenOptions {
+    /** port to listen on (omit/0 for an OS-assigned port) */
     port?: number;
+    /** hostname/interface to bind to (omit to listen on all interfaces) */
     hostname?: string;
+    /** client configuration to use for this listener, otherwise the server's is used */
     client?: libClient.ClientConfig | libClient.BurntClientConfig;
+    /** tls configuration to be used */
     tls?: {
         key: string;
         cert: string;
     };
+    /** custom configured server to be used (connectionsCheckingInterval must be configured
+     *	accordingly beforehand; ownership will be taken; secure to encode https compared to http) */
     server?: {
         server: libHttp.Server;
         secure: boolean;
     };
+    /** create a serverless listener, designed to only be passed connections to */
+    serverless?: {
+        secure: boolean;
+    };
 }
+/** wrapper to create a simple server */
 export declare function createServer(config?: ServerConfig): Server;
 export interface ServerConfig {
+    /** logging string used for the server (default: server) */
+    name?: string;
+    /** default timeout for request headers to be fully received [0 disables the timeout; in milliseconds; Default: 30_000] */
     headerTimeout?: number;
+    /** default inactivity timeout — connection is closed if no data is sent or received; resets on any I/O activity, so active transfers are not affected;
+     *	is temporarily cleared by clients, which handle it themselves via throughput [0 disables the timeout; in milliseconds; Default: 90_000] */
     connectionTimeout?: number;
+    /** idle time allowed between requests before closing a keep-alive connection [0 falls back to connectionTimeout; in milliseconds; Default: 10_000] */
     keepAliveTimeout?: number;
+    /** default client configuration to be used */
     client?: libClient.ClientConfig | libClient.BurntClientConfig;
+    /** default cache configuration to be used
+     *	Important: cache host should be shared where possible as otherwise multiple unshared caches could exist and immutable ids might overwrite each other */
     cache?: libCache.CacheHost | libCache.CacheConfig | libCache.BurntCacheConfig;
 }
 export declare class BurntServerConfig {