@flancer32/teq-web 0.1.0

package/src/Back/Enum/Server/Type.js

@@ -0,0 +1,12 @@
+/**
+ * Enum for server types used to configure built-in web server.
+ * - 'http': HTTP/1.1
+ * - 'http2': HTTP/2 without TLS (cleartext)
+ * - 'https': HTTP/2 over TLS (via http2.createSecureServer)
+ */
+const Fl32_Web_Back_Enum_Server_Type = {
+    HTTP2: 'http2',
+    HTTP: 'http',
+    HTTPS: 'https'
+};
+export default Fl32_Web_Back_Enum_Server_Type;

package/src/Back/Enum/Stage.js

@@ -0,0 +1,10 @@
+/**
+ * Enum for web request processing stages in this plugin.
+ * Used to define processing phases in the web dispatcher specific to this plugin.
+ */
+const Fl32_Web_Back_Enum_Stage = {
+    PRE: 'pre',       // Pre-processing stage: initial request handling (e.g., logging, authentication)
+    PROCESS: 'process', // Main processing stage: routing and core logic
+    POST: 'post'      // Post-processing stage: final actions (e.g., logging response, cleanup)
+};
+export default Fl32_Web_Back_Enum_Stage;

package/src/Back/Handler/Pre/Log.js

@@ -0,0 +1,45 @@
+/**
+ * Logs basic request information at the beginning of the request lifecycle.
+ * @implements Fl32_Web_Back_Api_Handler
+ */
+export default class Fl32_Web_Back_Handler_Pre_Log {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {Fl32_Web_Back_Logger} logger
+     * @param {Fl32_Web_Back_Dto_Handler_Info} dtoInfo
+     * @param {typeof Fl32_Web_Back_Enum_Stage} STAGE
+     */
+    constructor(
+        {
+            Fl32_Web_Back_Logger$: logger,
+            Fl32_Web_Back_Dto_Handler_Info$: dtoInfo,
+            Fl32_Web_Back_Enum_Stage$: STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+        // VARS
+        const _info = dtoInfo.create();
+        _info.name = this.constructor.name;
+        _info.stage = STAGE.PRE;
+        Object.freeze(_info);
+
+        // MAIN
+
+        /**
+         * Log request method and URL.
+         *
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
+         * @returns {Promise<void>}
+         */
+        this.handle = async function (req) {
+            logger.debug(`${req.method} ${req.url}`);
+        };
+
+        /**
+         * Return handler registration info.
+         *
+         * @returns {Fl32_Web_Back_Dto_Handler_Info.Dto}
+         */
+        this.getRegistrationInfo = () => _info;
+    }
+}

package/src/Back/Handler/Static.js

@@ -0,0 +1,139 @@
+/**
+ * Serves static files from a configured root directory.
+ * Prevents directory traversal and streams file content to the response.
+ *
+ * @implements Fl32_Web_Back_Api_Handler
+ */
+export default class Fl32_Web_Back_Handler_Static {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {typeof import('node:fs')} fs - Node.js file system module.
+     * @param {typeof import('node:http2')} http2
+     * @param {typeof import('node:path')} path - Node.js path module.
+     * @param {Fl32_Web_Back_Logger} logger - Logger instance.
+     * @param {Fl32_Web_Back_Helper_Mime} helpMime - MIME helper for content type resolution.
+     * @param {Fl32_Web_Back_Helper_Respond} respond - Response helper with status utilities.
+     * @param {Fl32_Web_Back_Dto_Handler_Info} dtoInfo - DTO factory for handler registration.
+     * @param {typeof Fl32_Web_Back_Enum_Stage} STAGE - Enum of handler stages.
+     */
+    constructor(
+        {
+            'node:fs': fs,
+            'node:http2': http2,
+            'node:path': path,
+            Fl32_Web_Back_Logger$: logger,
+            Fl32_Web_Back_Helper_Mime$: helpMime,
+            Fl32_Web_Back_Helper_Respond$: respond,
+            Fl32_Web_Back_Dto_Handler_Info$: dtoInfo,
+            Fl32_Web_Back_Enum_Stage$: STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+        // VARS
+        const {promises: fsp} = fs;
+        const {constants: H2} = http2;
+        const {
+            HTTP2_HEADER_CONTENT_LENGTH,
+            HTTP2_HEADER_CONTENT_TYPE,
+            HTTP2_HEADER_LAST_MODIFIED,
+            HTTP_STATUS_OK,
+        } = H2;
+
+        /**
+         * Handler registration info.
+         * @type {Fl32_Web_Back_Dto_Handler_Info.Dto}
+         */
+        const _info = dtoInfo.create();
+        _info.name = this.constructor.name;
+        _info.stage = STAGE.PROCESS;
+        Object.freeze(_info);
+
+        /**
+         * Root directory for static files.
+         * @type {string}
+         */
+        let _root;
+
+        /**
+         * Default filenames to try when a path is a directory.
+         * @type {string[]}
+         */
+        const _defaultFiles = ['index.html', 'index.htm', 'index.txt'];
+
+
+        /**
+         * Handles the incoming request by attempting to serve a static file.
+         *
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req - HTTP request object.
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res - HTTP response object.
+         * @returns {Promise<boolean>} - True if the file was served, false otherwise.
+         */
+        this.handle = async function (req, res) {
+            if (!respond.isWritable(res)) return false;
+
+            try {
+                const urlPath = decodeURIComponent(req.url.split('?')[0]);
+                let fsPath = path.resolve(_root, '.' + urlPath);
+
+                if (!fsPath.startsWith(_root)) return false;
+
+                let stat;
+                try {
+                    stat = await fsp.stat(fsPath);
+                } catch {
+                    return false;
+                }
+
+                // If a path is a directory — try default files
+                if (stat.isDirectory()) {
+                    for (const file of _defaultFiles) {
+                        const candidate = path.join(fsPath, file);
+                        try {
+                            const s = await fsp.stat(candidate);
+                            if (s.isFile()) {
+                                fsPath = candidate;
+                                stat = s;
+                                break;
+                            }
+                        } catch {
+                            // ignore and continue
+                        }
+                    }
+                    if (!stat.isFile()) return false;
+                }
+
+                const stream = fs.createReadStream(fsPath);
+                const ext = path.extname(fsPath).toLowerCase();
+                const headers = {
+                    [HTTP2_HEADER_CONTENT_LENGTH]: stat.size,
+                    [HTTP2_HEADER_CONTENT_TYPE]: helpMime.getByExt(ext),
+                    [HTTP2_HEADER_LAST_MODIFIED]: stat.mtime.toUTCString(),
+                };
+                res.writeHead(HTTP_STATUS_OK, headers);
+                stream.pipe(res);
+                return true;
+            } catch (e) {
+                logger.exception(e);
+                return false;
+            }
+        };
+
+        /**
+         * Initializes the handler with the root directory.
+         *
+         * @param {object} params
+         * @param {string} params.rootPath - Absolute or relative path to the static root directory.
+         * @returns {Promise<void>}
+         */
+        this.init = async function ({rootPath}) {
+            _root = path.resolve(rootPath);
+            logger.info(`Static files root: ${_root}`);
+        };
+
+        /**
+         * Returns the handler registration info.
+         * @returns {Fl32_Web_Back_Dto_Handler_Info.Dto}
+         */
+        this.getRegistrationInfo = () => _info;
+    }
+}

package/src/Back/Helper/Cast.js

@@ -0,0 +1,86 @@
+export default class Fl32_Web_Back_Helper_Cast {
+
+    /**
+     * Cast input data into an array. Ensures the result is always an array.
+     * Optionally casts each item using the provided itemCast function.
+     *
+     * @param {*} data - Input data to be cast to array.
+     * @param {function(*): *} [itemCast] - Optional function to cast each item.
+     * @returns {Array}
+     */
+    array(data, itemCast) {
+        let arr = [];
+
+        if (Array.isArray(data)) {
+            arr = data;
+        } else if (data !== null) {
+            arr = [data];
+        }
+
+        return (typeof itemCast === 'function')
+            ? arr.map(itemCast).filter(v => v !== undefined)
+            : arr;
+    }
+
+
+    /**
+     * Cast input data into decimal 'number' data type.
+     * @param {*} data
+     * @returns {number|undefined}
+     */
+    decimal(data) {
+        const res = Number.parseFloat(data);
+        return ((typeof res === 'number') && (!isNaN(res))) ? res : undefined;
+    }
+
+    /**
+     * Cast input data into a valid enumeration value.
+     * Supports case normalization (upper/lower).
+     * If both `upper` and `lower` are true, `upper` takes precedence.
+     *
+     * @param {*} data - The input to cast.
+     * @param {object} enu - Object whose values represent valid enum values.
+     * @param {object} [params] - Parameters object.
+     * @param {boolean} [params.lower] - Normalize input to lower case before comparison.
+     * @param {boolean} [params.upper] - Normalize input to upper case before comparison.
+     * @returns {string|undefined}
+     */
+    enum(data, enu, {lower, upper} = {}) {
+        let norm = data;
+
+        if (typeof data === 'string') {
+            if (upper) norm = data.toUpperCase();
+            else if (lower) norm = data.toLowerCase();
+        }
+
+        const values = Object.values(enu);
+        return values.includes(norm) ? norm : undefined;
+    }
+
+    /**
+     * Cast input data into integer 'number' data type.
+     * @param {*} data - Input data to be cast to integer.
+     * @returns {number|undefined}
+     */
+    int(data) {
+        const norm = (typeof data === 'string') ? data.trim() : data;
+        const res = Number.parseInt(norm);
+        return ((typeof res === 'number') && (!isNaN(res))) ? res : undefined;
+    }
+
+    /**
+     * Cast input data into 'string' data type.
+     * @param {*} data - Input data to be cast to string.
+     * @returns {string|undefined}
+     */
+    string(data) {
+        if (typeof data === 'string') {
+            return data;
+        } else if (typeof data === 'number') {
+            return String(data);
+        } else if (typeof data === 'boolean') {
+            return (data) ? 'true' : 'false';
+        }
+        return undefined;
+    }
+}

package/src/Back/Helper/Mime.js

@@ -0,0 +1,90 @@
+/**
+ * MIME type helper with built-in mapping for common file extensions.
+ * Can be replaced or extended by the application via the DI container.
+ */
+export default class Fl32_Web_Back_Helper_Mime {
+    constructor() {
+        /**
+         * Mapping from file extension to MIME type.
+         * Keys must start with a dot, e.g. '.html'.
+         * @type {{[key: string]: string}}
+         */
+        const _types = Object.freeze({
+            '.aac': 'audio/aac',
+            '.abw': 'application/x-abiword',
+            '.avi': 'video/x-msvideo',
+            '.bmp': 'image/bmp',
+            '.bz': 'application/x-bzip',
+            '.bz2': 'application/x-bzip2',
+            '.css': 'text/css',
+            '.csv': 'text/csv',
+            '.doc': 'application/msword',
+            '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            '.eot': 'application/vnd.ms-fontobject',
+            '.epub': 'application/epub+zip',
+            '.gz': 'application/gzip',
+            '.gif': 'image/gif',
+            '.htm': 'text/html',
+            '.html': 'text/html',
+            '.ico': 'image/vnd.microsoft.icon',
+            '.ics': 'text/calendar',
+            '.jar': 'application/java-archive',
+            '.jpeg': 'image/jpeg',
+            '.jpg': 'image/jpeg',
+            '.js': 'application/javascript',
+            '.json': 'application/json',
+            '.mid': 'audio/midi',
+            '.midi': 'audio/midi',
+            '.mjs': 'application/javascript',
+            '.mp3': 'audio/mpeg',
+            '.mp4': 'video/mp4',
+            '.mpeg': 'video/mpeg',
+            '.mpkg': 'application/vnd.apple.installer+xml',
+            '.odp': 'application/vnd.oasis.opendocument.presentation',
+            '.ods': 'application/vnd.oasis.opendocument.spreadsheet',
+            '.odt': 'application/vnd.oasis.opendocument.text',
+            '.oga': 'audio/ogg',
+            '.ogv': 'video/ogg',
+            '.ogx': 'application/ogg',
+            '.otf': 'font/otf',
+            '.png': 'image/png',
+            '.pdf': 'application/pdf',
+            '.ppt': 'application/vnd.ms-powerpoint',
+            '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+            '.rar': 'application/x-rar-compressed',
+            '.rtf': 'application/rtf',
+            '.sh': 'application/x-sh',
+            '.svg': 'image/svg+xml',
+            '.swf': 'application/x-shockwave-flash',
+            '.tar': 'application/x-tar',
+            '.tif': 'image/tiff',
+            '.tiff': 'image/tiff',
+            '.ts': 'video/mp2t',
+            '.ttf': 'font/ttf',
+            '.txt': 'text/plain',
+            '.vsd': 'application/vnd.visio',
+            '.wav': 'audio/wav',
+            '.weba': 'audio/webm',
+            '.webm': 'video/webm',
+            '.webp': 'image/webp',
+            '.woff': 'font/woff',
+            '.woff2': 'font/woff2',
+            '.xhtml': 'application/xhtml+xml',
+            '.xls': 'application/vnd.ms-excel',
+            '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+            '.xml': 'application/xml',
+            '.zip': 'application/zip',
+            '.7z': 'application/x-7z-compressed',
+        });
+
+        /**
+         * Returns the MIME type for the given extension.
+         *
+         * @param {string} ext - File extension including leading dot (e.g. '.html').
+         * @returns {string} MIME type if known, otherwise 'application/octet-stream'.
+         */
+        this.getByExt = function (ext) {
+            return _types[ext.toLowerCase()] || 'application/octet-stream';
+        };
+    }
+}

package/src/Back/Helper/Order/Kahn.js

@@ -0,0 +1,66 @@
+/**
+ * Sorts named handlers by relative `before` / `after` constraints using Kahn's algorithm.
+ */
+export default class Fl32_Web_Back_Helper_Order_Kahn {
+
+    /**
+     * Topologically sorts handlers with `name`, `before`, `after` fields.
+     *
+     * @param {Fl32_Web_Back_Api_Handler[]} handlers - Handlers to sort.
+     * @returns {Fl32_Web_Back_Api_Handler[]} - Sorted list.
+     * @throws {Error} - If circular dependency is detected.
+     */
+    sort(handlers) {
+        const nameToHandler = new Map();
+        const graph = new Map(); // name => Set of downstream nodes
+        const inDegree = new Map(); // name => number of incoming edges
+
+        // Initialize maps
+        for (const h of handlers) {
+            const info = h.getRegistrationInfo();
+            const name = info.name;
+            nameToHandler.set(name, h);
+            graph.set(name, new Set());
+            inDegree.set(name, 0);
+        }
+
+        // Build graph
+        for (const h of handlers) {
+            const {name, after = [], before = []} = h.getRegistrationInfo();
+
+            for (const dep of after) {
+                if (!graph.has(dep)) continue;
+                graph.get(dep).add(name);
+                inDegree.set(name, inDegree.get(name) + 1);
+            }
+
+            for (const dep of before) {
+                if (!graph.has(dep)) continue;
+                graph.get(name).add(dep);
+                inDegree.set(dep, inDegree.get(dep) + 1);
+            }
+        }
+
+        // Kahn's algorithm
+        const queue = [];
+        for (const [name, count] of inDegree.entries()) {
+            if (count === 0) queue.push(name);
+        }
+
+        const sorted = [];
+        while (queue.length > 0) {
+            const name = queue.shift();
+            sorted.push(nameToHandler.get(name));
+            for (const neighbor of graph.get(name)) {
+                inDegree.set(neighbor, inDegree.get(neighbor) - 1);
+                if (inDegree.get(neighbor) === 0) queue.push(neighbor);
+            }
+        }
+
+        if (sorted.length !== handlers.length) {
+            throw new Error('Circular dependency detected among handlers');
+        }
+
+        return sorted;
+    }
+}

package/src/Back/Helper/Respond.js

@@ -0,0 +1,78 @@
+/* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+export default class Fl32_Web_Back_Helper_Respond {
+    /**
+     * @param {typeof import('node:http2')} http2
+     */
+    constructor(
+        {
+            'node:http2': http2,
+        }
+    ) {
+        // VARS
+        const {constants: H2} = http2;
+        const {
+            HTTP2_HEADER_ALLOW,
+            HTTP_STATUS_BAD_GATEWAY,
+            HTTP_STATUS_BAD_REQUEST,
+            HTTP_STATUS_CONFLICT,
+            HTTP_STATUS_CREATED,
+            HTTP_STATUS_FORBIDDEN,
+            HTTP_STATUS_FOUND,
+            HTTP_STATUS_INTERNAL_SERVER_ERROR,
+            HTTP_STATUS_METHOD_NOT_ALLOWED,
+            HTTP_STATUS_MOVED_PERMANENTLY,
+            HTTP_STATUS_NOT_FOUND,
+            HTTP_STATUS_NOT_MODIFIED,
+            HTTP_STATUS_NO_CONTENT,
+            HTTP_STATUS_OK,
+            HTTP_STATUS_PAYMENT_REQUIRED,
+            HTTP_STATUS_SEE_OTHER,
+            HTTP_STATUS_SERVICE_UNAVAILABLE,
+            HTTP_STATUS_UNAUTHORIZED,
+        } = H2;
+
+        // FUNC
+        /**
+         * Sends an HTTP response with a given status code.
+         *
+         * @param {object} params
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} params.res - HTTP response object.
+         * @param {{[key: string]: string}} [params.headers={}] - Custom headers.
+         * @param {string|object} [params.body=''] - Response body.
+         * @param {number} status - HTTP status code.
+         * @returns {boolean} - `true` if response was sent, `false` if headers were already sent.
+         */
+        function send({res, headers = {}, body = ''}, status) {
+            if (res.headersSent || res.writableEnded) return false;
+            res.writeHead(status, headers);
+            res.end(typeof body === 'string' ? body : JSON.stringify(body));
+            return true;
+        }
+
+        // MAIN
+
+        /** @see send */
+        this.code200_Ok = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_OK);
+        };
+
+        /** @see send */
+        this.code404_NotFound = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_NOT_FOUND);
+        };
+
+        /** @see send */
+        this.code500_InternalServerError = function ({res, headers = {}, body = 'Internal Server Error'}) {
+            return send({res, headers, body}, HTTP_STATUS_INTERNAL_SERVER_ERROR);
+        };
+
+        /**
+         * Checks if the response is writable and not yet sent.
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
+         * @returns {boolean}
+         */
+        this.isWritable = function (res) {
+            return !res.headersSent && !res.writableEnded;
+        };
+    }
+}

package/src/Back/Logger.js

@@ -0,0 +1,53 @@
+/**
+ * Simple logger implementation that delegates to the native console.
+ */
+export default class Fl32_Web_Back_Logger {
+    /**
+     * Logs an error message.
+     * @param {...any} args - The error message or data.
+     */
+    error(...args) {
+        console.error('[ERROR]', ...args);
+    }
+
+    /**
+     * Logs a warning message.
+     * @param {...any} args - The warning message or data.
+     */
+    warn(...args) {
+        console.warn('[WARN]', ...args);
+    }
+
+    /**
+     * Logs an informational message.
+     * @param {...any} args - The informational message or data.
+     */
+    info(...args) {
+        console.info('[INFO]', ...args);
+    }
+
+    /**
+     * Logs a debug message.
+     * @param {...any} args - The debug message or data.
+     */
+    debug(...args) {
+        console.debug('[DEBUG]', ...args);
+    }
+
+    /**
+     * Logs a trace message.
+     * @param {...any} args - The trace message or data.
+     */
+    trace(...args) {
+        console.trace('[TRACE]', ...args);
+    }
+
+    /**
+     * Logs an exception with optional additional context.
+     * @param {Error} exception - The exception to log.
+     * @param {...any} context - Additional context or metadata.
+     */
+    exception(exception, ...context) {
+        console.error('[EXCEPTION]', exception.stack || exception.toString(), ...context);
+    }
+}

package/src/Back/Server/Config/Tls.js

@@ -0,0 +1,55 @@
+/**
+ * Factory for TLS configuration DTO.
+ * Produces validated DTOs for HTTPS server configuration.
+ */
+export default class Fl32_Web_Back_Server_Config_Tls {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {Fl32_Web_Back_Helper_Cast} cast
+     */
+    constructor(
+        {
+            Fl32_Web_Back_Helper_Cast$: cast,
+        }
+    ) {
+        /* eslint-enable jsdoc/require-param-description,jsdoc/check-param-names */
+        /**
+         * Create a validated DTO for TLS configuration.
+         *
+         * @param {*} [data] - Optional raw object.
+         * @returns {Dto}
+         */
+        this.create = function (data) {
+            const res = Object.assign(new Dto(), data);
+            if (data) {
+                res.ca = cast.string(data?.ca);
+                res.cert = cast.string(data.cert);
+                res.key = cast.string(data.key);
+            }
+            return res;
+        };
+    }
+}
+
+/**
+ * @memberOf Fl32_Web_Back_Server_Config_Tls
+ */
+class Dto {
+    /**
+     * Trusted CA certificates in PEM format.
+     * @type {string|undefined}
+     */
+    ca;
+
+    /**
+     * Certificate in PEM format.
+     * @type {string}
+     */
+    cert;
+
+    /**
+     * Private key in PEM format.
+     * @type {string}
+     */
+    key;
+}