@bjoernboss/mws 1.0.0

package/dist/helper.js

@@ -0,0 +1,363 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright (c) 2026 Bjoern Boss Henrichsen */
+import * as libBase from "./base.js";
+import * as libLog from "./log.js";
+import * as libUrl from "url";
+import * as libPath from "path";
+const helperLogger = libLog.createLogger('helper');
+/* setup the reverse list of file-endings to media types and encoding-names to encoding types */
+const FileEndingToMediaTypeMapping = {};
+const EncodingNameToEncodingTypeMapping = {};
+for (const media of Object.values(libBase.Media)) {
+    for (const fileEnding of media.fileEnding)
+        FileEndingToMediaTypeMapping[fileEnding] = media;
+}
+for (const encoding of Object.values(libBase.Encoding))
+    EncodingNameToEncodingTypeMapping[encoding.name] = encoding;
+/* lookup the encoding for a given name */
+export function lookupEncoding(name) {
+    return EncodingNameToEncodingTypeMapping[name.toLowerCase()] ?? null;
+}
+/* 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) */
+export function lookupMediaTypeFromFile(filePath) {
+    const fileExtension = splitFilePath(filePath)[2];
+    if (fileExtension != '') {
+        const type = FileEndingToMediaTypeMapping[fileExtension.substring(1).toLowerCase()] ?? null;
+        if (type != null)
+            return type;
+    }
+    return null;
+}
+/* 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) */
+export function negotiateEncoding(accept, atLeastSize, media) {
+    if (!media.compressible || accept == null)
+        return null;
+    if (atLeastSize != null && atLeastSize < libBase.MIN_ENCODING_SIZE)
+        return null;
+    /* parse the encoding types and their score */
+    const scores = {};
+    let bestScore = null;
+    for (const part of splitAndTrimList(accept, ',', false)) {
+        const segments = splitAndTrimList(part, ';', false);
+        const name = segments[0].toLowerCase();
+        /* check if the name is even supported and otherwise drop it */
+        if (!(name in EncodingNameToEncodingTypeMapping) && name != '*')
+            continue;
+        /* parse the weight score of the value but default to 1.0 if none was given (ignore any with invalid quality) */
+        let score = 1.0;
+        for (let i = 1; i < segments.length; ++i) {
+            const match = segments[i].match(/^\s*q\s*=\s*(\d+\.?\d*)\s*$/i);
+            if (match != null) {
+                score = parseFloat(match[1]);
+                break;
+            }
+        }
+        if (score < 0 || score > 1)
+            continue;
+        /* update the scores and best match */
+        scores[name] = (name in scores ? Math.max(scores[name], score) : score);
+        if (bestScore == null || scores[bestScore] < score)
+            bestScore = name;
+        else if (scores[bestScore] == score && (bestScore == name || bestScore == 'identity' || (bestScore == '*' && name != 'identity')))
+            bestScore = name;
+    }
+    /* check if a best-match has been found */
+    if (bestScore == null || scores[bestScore] <= 0)
+        return null;
+    if (bestScore != null && bestScore != '*')
+        return (bestScore == 'identity' ? null : EncodingNameToEncodingTypeMapping[bestScore]);
+    /* lookup the best entry not mentioned (because '*' was the best match) */
+    for (const encoding in EncodingNameToEncodingTypeMapping) {
+        if (!(encoding in scores))
+            return EncodingNameToEncodingTypeMapping[encoding];
+    }
+    return null;
+}
+export var RangeState;
+(function (RangeState) {
+    RangeState[RangeState["noRange"] = 0] = "noRange";
+    RangeState[RangeState["valid"] = 1] = "valid";
+    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) */
+export function parseRangeHeader(range, fileSize) {
+    if (range == null)
+        return { first: 0, last: fileSize - 1, state: RangeState.noRange };
+    /* ignore unknown range units (range units are case-insensitive) */
+    if (range.length < 6 || range.substring(0, 6).toLowerCase() != 'bytes=')
+        return { first: 0, last: fileSize - 1, state: RangeState.noRange };
+    range = range.substring(6);
+    /* extract the first number */
+    let numberLength = 0, firstNumber = '', lastNumber = '';
+    while (numberLength < range.length && (range[numberLength] >= '0' && range[numberLength] <= '9'))
+        ++numberLength;
+    firstNumber = range.substring(0, numberLength);
+    range = range.substring(numberLength);
+    /* check if the separator exists */
+    if (!range.startsWith('-'))
+        return { first: 0, last: 0, state: RangeState.malformed };
+    range = range.substring(1);
+    /* extract the second number */
+    numberLength = 0;
+    while (numberLength < range.length && (range[numberLength] >= '0' && range[numberLength] <= '9'))
+        ++numberLength;
+    lastNumber = range.substring(0, numberLength);
+    range = range.substring(numberLength).trimStart();
+    /* check if a valid end has been found or another range (only the first
+    *	range will be respected) and that at least one number has been given */
+    if (range != '' && !range.startsWith(','))
+        return { first: 0, last: 0, state: RangeState.malformed };
+    if (firstNumber == '' && lastNumber == '')
+        return { first: 0, last: 0, state: RangeState.malformed };
+    /* parse the two numbers */
+    let first = (firstNumber.length == 0 ? null : parseInt(firstNumber));
+    let last = (lastNumber.length == 0 ? null : parseInt(lastNumber));
+    /* check if the range has an offset and potentially also an end */
+    if (first != null) {
+        if (last == null)
+            last = fileSize - 1;
+        if (first > last || last >= fileSize)
+            return { first: 0, last: 0, state: RangeState.issue };
+        return { first, last, state: RangeState.valid };
+    }
+    /* validate the offset at the end */
+    if (last > fileSize || last == 0)
+        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]
+*	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)
+        return false;
+    const list = splitAndTrimList(header, ',', true);
+    if (list.length == 1 && list[0] == '*')
+        return true;
+    if (strong && etag.startsWith('W/'))
+        return false;
+    const target = etag.startsWith('W/') ? etag.substring(2) : etag;
+    for (const entry of list) {
+        const current = ((strong || !entry.startsWith('W/')) ? entry : entry.substring(2));
+        if (target == current)
+            return true;
+    }
+    return false;
+}
+/* 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))
+        return null;
+    const _b = new Date(b).getTime();
+    if (isNaN(_b))
+        return null;
+    return (_a - _b);
+}
+/* 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 [];
+    let output = [], current = '', inQuote = false;
+    for (const c of content) {
+        if (c == '"' && quotesAware)
+            inQuote = !inQuote, current += c;
+        else if (c != separator || inQuote)
+            current += c;
+        else
+            output.push(current.trim()), current = '';
+    }
+    if (inQuote)
+        return [];
+    output.push(current.trim());
+    return output;
+}
+/* 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) {
+        switch (content[i]) {
+            case '&':
+                out += '&amp;';
+                break;
+            case '<':
+                out += '&lt;';
+                break;
+            case '>':
+                out += '&gt;';
+                break;
+            case '"':
+                out += '&quot;';
+                break;
+            case '\'':
+                out += '&#39;';
+                break;
+            default:
+                out += content[i];
+                break;
+        }
+    }
+    return out;
+}
+/* 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) {
+        /* check if this is not the start/end of a placeholder, in which case it can just be added to the current set */
+        if (!content.startsWith(placeholder ? '}' : '{#', i)) {
+            if (placeholder)
+                name += content[i];
+            else
+                out += content[i];
+            continue;
+        }
+        /* check if a name is being started and if its potentially just an escape sequence */
+        if (!placeholder) {
+            if (content.startsWith('{##', i))
+                out += '{#', i += 2;
+            else
+                name = '', placeholder = true, ++i;
+            continue;
+        }
+        placeholder = false;
+        if (name in args)
+            out += (htmlEscape ? escapeHtml(args[name]) : args[name]);
+        else
+            helperLogger.warning(`Undefined placeholder [${name}] encountered`);
+    }
+    if (placeholder)
+        helperLogger.warning('Content ends with an incomplete placeholder');
+    return out;
+}
+/* escape all placeholders in the content */
+export function escapePlaceholders(content) {
+    let out = '';
+    /* construct the new escaped output content */
+    for (let i = 0; i < content.length; ++i) {
+        if (!content.startsWith('{#', i))
+            out += content[i];
+        else
+            out += '{##', ++i;
+    }
+    return out;
+}
+/* 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 = '/';
+    if (path.startsWith('/'))
+        relative = false;
+    /* iterate over the characters and write them to the output
+    *	(i == path.length is a final implicit slash to catch trailing '/..') */
+    for (let i = 0; i <= path.length; ++i) {
+        /* check if the character can just be written out */
+        if (i < path.length && path[i] != '/' && path[i] != '\\') {
+            out += path[i];
+            continue;
+        }
+        /* check if the slash can be ignored as the string ends in a slash */
+        if (out.endsWith('/'))
+            continue;
+        /* check if its a relative path step and remove it */
+        if (out.endsWith('/.'))
+            out = out.substring(0, out.length - 1);
+        /* check if its just an arbitrary sequence */
+        else if (!out.endsWith('/..')) {
+            if (i + 1 >= path.length)
+                break;
+            out += '/';
+        }
+        /* process the backwards walking */
+        else if (relative && (out.endsWith('/../..') || out == '/..')) {
+            if (i < path.length)
+                out += '/';
+        }
+        else if (!relative && out == '/..')
+            out = '/';
+        else
+            out = out.substring(0, out.lastIndexOf('/', out.length - 4) + 1);
+    }
+    /* check if its not the root and remove trailing slashes and patch the relative path */
+    if (out != '/') {
+        if (out.endsWith('/'))
+            out = out.substring(0, out.length - 1);
+        if (relative)
+            out = out.substring(1);
+    }
+    else if (relative)
+        out = '.';
+    return out;
+}
+/* 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);
+    const aSlash = a.endsWith('/'), bSlash = b.startsWith('/');
+    if (aSlash)
+        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 */
+export function isSubPath(base, path) {
+    if (base.length > path.length)
+        return false;
+    if (base.length == path.length)
+        return (base == path);
+    if (!path.startsWith(base))
+        return false;
+    return (path[base.length] == '/' || base.endsWith('/'));
+}
+/* check if the sanitized path is a true sub-path of the sanitized base path */
+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 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) */
+export function rebasePath(oldBase, newBase, path) {
+    return joinSanitized(newBase, childPath(oldBase, 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) {
+    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
+*	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;
+    let name = path.length - 1;
+    for (; name >= 0 && (path[name] != '/' && path[name] != '\\'); --name) {
+        if (path[name] == '.' && dot == null)
+            dot = name;
+    }
+    if (dot == null || dot == name + 1)
+        dot = path.length;
+    return [path.substring(0, name + 1), path.substring(name + 1, dot), path.substring(dot)];
+}
+//# sourceMappingURL=helper.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./base.js";
+export * from "./cache.js";
+export * from "./client.js";
+export * from "./handler.js";
+export * from "./helper.js";
+export * from "./log.js";
+export * from "./server.js";
+export * as build from "./builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright (c) 2026 Bjoern Boss Henrichsen */
+export * from "./base.js";
+;
+export * from "./cache.js";
+export * from "./client.js";
+export * from "./handler.js";
+export * from "./helper.js";
+export * from "./log.js";
+export * from "./server.js";
+export * as build from "./builder.js";
+//# sourceMappingURL=index.js.map

package/dist/log.d.ts

@@ -0,0 +1,52 @@
+export type LogLevel = 'error' | 'info' | 'warning' | 'log' | 'trace';
+export type LogConsumer = (level: LogLevel | null, date: string, identity: string, msg: string) => void;
+export type Detacher = () => void;
+export type TagUpdate = (value?: string) => void;
+export declare function createConsoleLogger(): LogConsumer;
+export declare function createLineLogger(cb: (line: string) => void): LogConsumer;
+export declare enum PreserveMode {
+    none = 0,
+    last = 1,
+    all = 2
+}
+export declare function createFileLogger(filePath: string, options?: {
+    flushingDelayMs?: number;
+    bufMaxLineCount?: number;
+    sizeSwapFile?: number;
+    preserve?: PreserveMode;
+}): LogConsumer;
+export declare function createLogFilter(target: LogConsumer, options?: {
+    level?: LogLevel | LogLevel[];
+    identity?: string | string[];
+}): LogConsumer;
+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;
+    error(msg: string, options?: {
+        extension?: string;
+    }): void;
+    info(msg: string, options?: {
+        extension?: string;
+    }): void;
+    warning(msg: string, options?: {
+        extension?: string;
+    }): void;
+    log(msg: string, options?: {
+        extension?: string;
+    }): void;
+    trace(msg: string, options?: {
+        extension?: string;
+    }): void;
+}
+export declare function createLogger(identity: string): Logger;
+export declare function addLogger(cb: LogConsumer): Detacher;
+export declare function logGlobal(level: LogLevel, identity: string, msg: string): void;
+//# sourceMappingURL=log.d.ts.map