@flancer32/teq-web 0.4.0 → 0.5.0

package/src/Back/Handler/Static.mjs

@@ -0,0 +1,83 @@
+// @ts-check
+
+/**
+ * Universal static-file PROCESS handler.
+ *
+ * @implements Fl32_Web_Back_Api_Handler
+ */
+export const __deps__ = Object.freeze({
+    registry: 'Fl32_Web_Back_Handler_Static_A_Registry$',
+    fileService: 'Fl32_Web_Back_Handler_Static_A_FileService$',
+    respond: 'Fl32_Web_Back_Helper_Respond$',
+    logger: 'Fl32_Web_Back_Logger$',
+    dtoInfoFactory: 'Fl32_Web_Back_Dto_Info__Factory$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_StaticConstructorParams
+ * @property {Fl32_Web_Back_Handler_Static_A_Registry} registry
+ * @property {Fl32_Web_Back_Handler_Static_A_FileService} fileService
+ * @property {Fl32_Web_Back_Helper_Respond} respond
+ * @property {Fl32_Web_Back_Logger} logger
+ * @property {Fl32_Web_Back_Dto_Info$Factory} dtoInfoFactory
+ * @property {Fl32_Web_Back_Enum_Stage} STAGE
+ */
+
+export default class Fl32_Web_Back_Handler_Static {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {Fl32_Web_Back_Handler_StaticConstructorParams} params
+     */
+    constructor(
+        {
+            registry,
+            fileService,
+            respond,
+            logger,
+            dtoInfoFactory,
+            STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+
+        const _info = dtoInfoFactory.create({
+            name: this.constructor.name,
+            stage: STAGE.PROCESS,
+        });
+
+        /**
+         * Initialize registry with provided sources.
+         *
+         * @param {{sources: Fl32_Web_Back_Dto_Source[]}} params
+         * @returns {Promise<void>}
+         */
+        this.init = async ({sources = []} = {}) => {
+            registry.addConfigs(sources);
+        };
+
+        /**
+         * Attempt to handle incoming request.
+         *
+         * @param {Fl32_Web_Back_PipelineEngine_RequestContext} context
+         * @returns {Promise<void>}
+         */
+        this.handle = async (context) => {
+            const req = context.request;
+            const res = context.response;
+            if (!respond.isWritable(res)) return;
+            const urlPath = decodeURIComponent(req.url.split('?')[0]);
+            const match = registry.find(urlPath);
+            if (!match) return;
+            const served = await fileService.serve(match.config, match.rel, req, res);
+            if (served) {
+                context.complete();
+            }
+        };
+
+        /**
+         * @returns {Fl32_Web_Back_Dto_Info}
+         */
+        this.getRegistrationInfo = () => _info;
+    }
+}

package/src/Back/Helper/Cast.mjs

@@ -0,0 +1,116 @@
+// @ts-check
+
+export default class Fl32_Web_Back_Helper_Cast {
+    constructor() {
+        /**
+         * 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}
+         */
+        this.array = function (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}
+         */
+        this.decimal = function (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}
+         */
+        this.enum = function (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}
+         */
+        this.int = function (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}
+         */
+        this.string = function (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;
+        };
+
+        /**
+         * Cast an object to a map with string keys and array-of-string values.
+         * Throws error on invalid structure or values.
+         *
+         * @param {*} data - Raw input to cast.
+         * @returns {Record<string, string[]>}
+         */
+        this.stringArrayMap = function (data) {
+            if (data === undefined) return {};
+            if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+                throw new Error('Invalid value for allow');
+            }
+            const res = {};
+            for (const [key, arr] of Object.entries(data)) {
+                if (!Array.isArray(arr)) throw new Error(`Invalid allow list for ${key}`);
+                const k = this.string(key);
+                if (!k) throw new Error('Invalid allow key');
+                const items = [];
+                for (const item of arr) {
+                    const val = this.string(item);
+                    if (!val) throw new Error(`Invalid allow list for ${k}`);
+                    items.push(val);
+                }
+                res[k] = items;
+            }
+            return res;
+        };
+    }
+}

package/src/Back/Helper/{Mime.js → Mime.mjs}

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * MIME type helper with built-in mapping for common file extensions.
  * Can be replaced or extended by the application via the DI container.

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

@@ -0,0 +1,69 @@
+// @ts-check
+
+/**
+ * Sorts named handlers by relative `before` / `after` constraints using Kahn's algorithm.
+ */
+export default class Fl32_Web_Back_Helper_Order_Kahn {
+    constructor() {
+        /**
+         * 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.
+         */
+        this.sort = function (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 → Respond.mjs}

@@ -1,11 +1,22 @@
+// @ts-check
+
 /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+export const __deps__ = Object.freeze({
+    http2: 'node_http2',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Helper_RespondConstructorParams
+ * @property {typeof import('node:http2')} http2
+ */
+
 export default class Fl32_Web_Back_Helper_Respond {
     /**
-     * @param {typeof import('node:http2')} http2
+     * @param {Fl32_Web_Back_Helper_RespondConstructorParams} params
      */
     constructor(
         {
-            'node:http2': http2,
+            http2,
         }
     ) {
         // VARS
@@ -152,4 +163,4 @@ export default class Fl32_Web_Back_Helper_Respond {
             return !res.headersSent && !res.writableEnded;
         };
     }
-}
+}

package/src/Back/Logger.mjs

@@ -0,0 +1,57 @@
+// @ts-check
+
+/**
+ * Simple logger implementation that delegates to the native console.
+ */
+export default class Fl32_Web_Back_Logger {
+    constructor() {
+        /**
+         * Logs an error message.
+         * @param {...any} args - The error message or data.
+         */
+        this.error = function (...args) {
+            console.error('[ERROR]', ...args);
+        };
+
+        /**
+         * Logs a warning message.
+         * @param {...any} args - The warning message or data.
+         */
+        this.warn = function (...args) {
+            console.warn('[WARN]', ...args);
+        };
+
+        /**
+         * Logs an informational message.
+         * @param {...any} args - The informational message or data.
+         */
+        this.info = function (...args) {
+            console.info('[INFO]', ...args);
+        };
+
+        /**
+         * Logs a debug message.
+         * @param {...any} args - The debug message or data.
+         */
+        this.debug = function (...args) {
+            console.debug('[DEBUG]', ...args);
+        };
+
+        /**
+         * Logs a trace message.
+         * @param {...any} args - The trace message or data.
+         */
+        this.trace = function (...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.
+         */
+        this.exception = function (exception, ...context) {
+            console.error('[EXCEPTION]', exception.stack || exception.toString(), ...context);
+        };
+    }
+}

package/src/Back/PipelineEngine.mjs

@@ -0,0 +1,228 @@
+// @ts-check
+
+/**
+ * Pipeline Engine is the single request-lifecycle coordination component.
+ * It executes handlers in three deterministic stages:
+ * `INIT -> PROCESS -> FINALIZE`.
+ */
+export const __deps__ = Object.freeze({
+    logger: 'Fl32_Web_Back_Logger$',
+    respond: 'Fl32_Web_Back_Helper_Respond$',
+    helpOrder: 'Fl32_Web_Back_Helper_Order_Kahn$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_PipelineEngineConstructorParams
+ * @property {Fl32_Web_Back_Logger} logger
+ * @property {Fl32_Web_Back_Helper_Respond} respond
+ * @property {Fl32_Web_Back_Helper_Order_Kahn} helpOrder
+ * @property {Fl32_Web_Back_Enum_Stage} STAGE
+ */
+
+/**
+ * @typedef {object} Fl32_Web_Back_PipelineEngine_RequestContext
+ * @property {module:http.IncomingMessage|module:http2.Http2ServerRequest} request
+ * @property {module:http.ServerResponse|module:http2.Http2ServerResponse} response
+ * @property {Record<string, unknown>} data
+ * @property {boolean} completed
+ * @property {() => void} complete
+ * @property {() => boolean} isCompleted
+ */
+
+const KEY_STAGE = Symbol('stage');
+
+export default class Fl32_Web_Back_PipelineEngine {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {Fl32_Web_Back_PipelineEngineConstructorParams} params
+     */
+    constructor(
+        {
+            logger,
+            respond,
+            helpOrder,
+            STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/require-param-description,jsdoc/check-param-names */
+        /** @type {Map<string, Fl32_Web_Back_Api_Handler>} */
+        const handlers = new Map();
+        /** @type {Fl32_Web_Back_Api_Handler[]} */
+        let initHandlers = [];
+        /** @type {Fl32_Web_Back_Api_Handler[]} */
+        let processHandlers = [];
+        /** @type {Fl32_Web_Back_Api_Handler[]} */
+        let finalizeHandlers = [];
+        let isLocked = false;
+
+        /**
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} request
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} response
+         * @returns {Fl32_Web_Back_PipelineEngine_RequestContext}
+         */
+        function createRequestContext(request, response) {
+            let completed = false;
+            /** @type {Fl32_Web_Back_PipelineEngine_RequestContext & {[KEY_STAGE]: string|null}} */
+            const context = {
+                request,
+                response,
+                data: {},
+                completed: false,
+                complete: () => {
+                    context.completed = true;
+                },
+                isCompleted: () => completed,
+                [KEY_STAGE]: null,
+            };
+
+            Object.defineProperty(context, 'completed', {
+                configurable: false,
+                enumerable: true,
+                get() {
+                    return completed;
+                },
+                set(value) {
+                    if (value !== true && value !== false) {
+                        throw new Error('Request completion flag accepts only boolean values');
+                    }
+                    if (value === false && completed) {
+                        throw new Error('Request completion flag cannot be reset');
+                    }
+                    if (value === true && !completed) {
+                        if (context[KEY_STAGE] !== STAGE.PROCESS) {
+                            throw new Error('Only PROCESS handlers may complete request processing');
+                        }
+                        completed = true;
+                    }
+                },
+            });
+
+            return context;
+        }
+
+        /**
+         * @param {Fl32_Web_Back_Api_Handler} handler
+         * @param {string} stage
+         * @param {Fl32_Web_Back_PipelineEngine_RequestContext & {[KEY_STAGE]: string|null}} context
+         * @returns {Promise<void>}
+         */
+        async function runHandler(handler, stage, context) {
+            context[KEY_STAGE] = stage;
+            await handler.handle(context);
+        }
+
+        /**
+         * @returns {void}
+         */
+        this.orderHandlers = function () {
+            const init = [];
+            const process = [];
+            const finalize = [];
+
+            for (const handler of handlers.values()) {
+                const info = handler.getRegistrationInfo();
+                if (info.stage === STAGE.INIT) {
+                    init.push(handler);
+                } else if (info.stage === STAGE.PROCESS) {
+                    process.push(handler);
+                } else if (info.stage === STAGE.FINALIZE) {
+                    finalize.push(handler);
+                } else {
+                    throw new Error(`Unsupported handler stage '${String(info.stage)}'`);
+                }
+            }
+
+            initHandlers = helpOrder.sort(init);
+            processHandlers = helpOrder.sort(process);
+            finalizeHandlers = helpOrder.sort(finalize);
+            isLocked = true;
+        };
+
+        /**
+         * @returns {void}
+         */
+        this.lockHandlers = () => this.orderHandlers();
+
+        /**
+         * @param {Fl32_Web_Back_Api_Handler} handler
+         * @returns {void}
+         */
+        this.addHandler = function (handler) {
+            if (isLocked) {
+                throw new Error('Handler registration is locked after pipeline ordering');
+            }
+            const info = handler.getRegistrationInfo();
+            if (!info?.name) {
+                throw new Error('Handler registration requires a non-empty name');
+            }
+            handlers.set(info.name, handler);
+        };
+
+        /**
+         * @param {Fl32_Web_Back_Api_Handler} handler
+         * @returns {void}
+         */
+        this.registerHandler = (handler) => this.addHandler(handler);
+
+        /**
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
+         * @returns {Promise<void>}
+         */
+        this.onEventRequest = async function (req, res) {
+            if (!isLocked) {
+                this.orderHandlers();
+            }
+            /** @type {Fl32_Web_Back_PipelineEngine_RequestContext & {[KEY_STAGE]: string|null}} */
+            const context = createRequestContext(req, res);
+
+            try {
+                for (const handler of initHandlers) {
+                    try {
+                        await runHandler(handler, STAGE.INIT, context);
+                    } catch (error) {
+                        logger.exception(error);
+                    }
+                }
+
+                for (const handler of processHandlers) {
+                    if (context.isCompleted()) {
+                        break;
+                    }
+                    try {
+                        await runHandler(handler, STAGE.PROCESS, context);
+                    } catch (error) {
+                        logger.exception(error);
+                        if (respond.isWritable(res)) {
+                            respond.code500_InternalServerError({res, body: 'Internal Server Error'});
+                        }
+                        context.completed = true;
+                        break;
+                    }
+                }
+
+                if (!context.isCompleted() && respond.isWritable(res)) {
+                    logger.error(`404 Not Found: ${req.url}`);
+                    respond.code404_NotFound({res});
+                }
+            } finally {
+                for (const handler of finalizeHandlers) {
+                    try {
+                        await runHandler(handler, STAGE.FINALIZE, context);
+                    } catch (error) {
+                        logger.exception(error);
+                    }
+                }
+                context[KEY_STAGE] = null;
+            }
+        };
+
+        /**
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
+         * @returns {Promise<void>}
+         */
+        this.handleRequest = async (req, res) => this.onEventRequest(req, res);
+    }
+}

package/src/Back/Server/Config/{Tls.js → Tls.mjs}

@@ -1,55 +1,57 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+});
+
 /**
- * Factory for TLS configuration DTO.
- * Produces validated DTOs for HTTPS server configuration.
+ * @typedef {object} Fl32_Web_Back_Server_Config_TlsFactoryParams
+ * @property {Fl32_Web_Back_Helper_Cast} cast
  */
+
 export default class Fl32_Web_Back_Server_Config_Tls {
+    /**
+     * 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;
+}
+
+export class Factory {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {Fl32_Web_Back_Helper_Cast} cast
+     * @param {Fl32_Web_Back_Server_Config_TlsFactoryParams} params
      */
     constructor(
         {
-            Fl32_Web_Back_Helper_Cast$: 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}
+         * @param {*} [data]
+         * @returns {Fl32_Web_Back_Server_Config_Tls}
          */
         this.create = function (data) {
-            const res = Object.assign(new Dto(), data);
+            const res = new Fl32_Web_Back_Server_Config_Tls();
             if (data) {
                 res.ca = cast.string(data?.ca);
                 res.cert = cast.string(data.cert);
                 res.key = cast.string(data.key);
             }
-            return res;
+            return Object.freeze(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;
-}