@flancer32/teq-web 0.4.0 → 0.6.0

package/src/Back/Dto/Handler/Info.js

@@ -1,68 +0,0 @@
-/**
- * Factory for dispatcher handler registration metadata.
- *
- * Produces validated DTOs for registering web request handlers.
- *
- * @see TeqFw_Core_Shared_Api_Factory
- */
-export default class Fl32_Web_Back_Dto_Handler_Info {
-    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
-    /**
-     * @param {Fl32_Web_Back_Helper_Cast} cast
-     * @param {typeof Fl32_Web_Back_Enum_Stage} STAGE
-     */
-    constructor(
-        {
-            Fl32_Web_Back_Helper_Cast$: cast,
-            Fl32_Web_Back_Enum_Stage$: STAGE,
-        }
-    ) {
-        /* eslint-enable jsdoc/check-param-names */
-        /**
-         * Create a validated DTO for handler registration.
-         *
-         * @param {*} [data] - Optional raw object.
-         * @returns {Dto}
-         */
-        this.create = function (data) {
-            const res = (data && typeof data === 'object' && !Array.isArray(data))
-                ? Object.assign(new Dto(), data)
-                : new Dto();
-            res.after = cast.array(data?.after, cast.string);
-            res.before = cast.array(data?.before, cast.string);
-            res.name = cast.string(data?.name);
-            res.stage = cast.enum(data?.stage, STAGE, {lower: true});
-            return res;
-        };
-    }
-}
-
-/**
- * @memberOf Fl32_Web_Back_Dto_Handler_Info
- */
-class Dto {
-    /**
-     * Handlers to run before this one.
-     * @type {string[]}
-     */
-    after;
-
-    /**
-     * Handlers to run after this one.
-     * @type {string[]}
-     */
-    before;
-
-    /**
-     * Unique handler name for ordering.
-     * @type {string}
-     */
-    name;
-
-    /**
-     * Execution stage: 'pre', 'process', or 'post'.
-     * @type {string}
-     * @see Fl32_Web_Back_Enum_Stage
-     */
-    stage;
-}

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

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,10 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,63 +0,0 @@
-/**
- * Universal file handler serving files from multiple sources using helper modules.
- *
- * @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 {Fl32_Web_Back_Handler_Static_A_Registry} registry
-     * @param {Fl32_Web_Back_Handler_Static_A_FileService} fileService
-     * @param {Fl32_Web_Back_Helper_Respond} respond
-     * @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_Handler_Static_A_Registry$: registry,
-            Fl32_Web_Back_Handler_Static_A_FileService$: fileService,
-            Fl32_Web_Back_Helper_Respond$: respond,
-            Fl32_Web_Back_Logger$: logger,
-            Fl32_Web_Back_Dto_Handler_Info$: dtoInfo,
-            Fl32_Web_Back_Enum_Stage$: STAGE,
-        }
-    ) {
-        /* eslint-enable jsdoc/check-param-names */
-
-        const _info = dtoInfo.create();
-        _info.name = this.constructor.name;
-        _info.stage = STAGE.PROCESS;
-        Object.freeze(_info);
-
-        /**
-         * Initialize registry with provided sources.
-         *
-         * @param {{sources: Fl32_Web_Back_Dto_Handler_Source.Dto[]}} params
-         * @returns {Promise<void>}
-         */
-        this.init = async ({sources = []} = {}) => {
-            registry.addConfigs(sources);
-        };
-
-        /**
-         * Attempt to handle incoming request.
-         *
-         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
-         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
-         * @returns {Promise<boolean>} True if file served
-         */
-        this.handle = async (req, res) => {
-            if (!respond.isWritable(res)) return false;
-            const urlPath = decodeURIComponent(req.url.split('?')[0]);
-            const match = registry.find(urlPath);
-            if (!match) return false;
-            return fileService.serve(match.config, match.rel, req, res);
-        };
-
-        /**
-         * @returns {Fl32_Web_Back_Dto_Handler_Info.Dto}
-         */
-        this.getRegistrationInfo = () => _info;
-    }
-}

package/src/Back/Helper/Cast.js

@@ -1,114 +0,0 @@
-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;
-    }
-
-    /**
-     * 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[]>}
-     */
-    stringArrayMap(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/Order/Kahn.js

@@ -1,66 +0,0 @@
-/**
- * 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/Logger.js

@@ -1,53 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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;
-}

package/src/Back/Server/Config.js

@@ -1,69 +0,0 @@
-/**
- * Factory for server configuration DTO.
- * Supports HTTP, HTTPS and HTTP2 server types with TLS configuration.
- */
-export default class Fl32_Web_Back_Server_Config {
-    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
-    /**
-     * @param {Fl32_Web_Back_Helper_Cast} cast
-     * @param {typeof Fl32_Web_Back_Enum_Server_Type} SERVER_TYPE
-     * @param {Fl32_Web_Back_Server_Config_Tls} tlsFactory
-     */
-    constructor(
-        {
-            Fl32_Web_Back_Helper_Cast$: cast,
-            Fl32_Web_Back_Enum_Server_Type$: SERVER_TYPE,
-            Fl32_Web_Back_Server_Config_Tls$: tlsFactory,
-        }
-    ) {
-        /* eslint-enable jsdoc/require-param-description,jsdoc/check-param-names */
-        // INSTANCE METHODS
-        /**
-         * Creates a new DTO instance with properly casted attributes.
-         * Ensures valid values for enums and numerical fields.
-         * Validates TLS configuration when type is HTTPS.
-         *
-         * @param {Fl32_Web_Back_Server_Config.Dto|object} [data] - Raw input data for the DTO.
-         * @returns {Dto} - A properly structured DTO instance.
-         * @throws {Error} When HTTPS type is specified without TLS configuration.
-         */
-        this.create = function (data) {
-            const res = Object.assign(new Dto(), data);
-            if (data) {
-                res.port = cast.int(data.port);
-                res.type = cast.enum(data.type, SERVER_TYPE, {lower: true});
-
-                if (data.tls) {
-                    res.tls = tlsFactory.create(data.tls);
-                }
-
-                if (res.type === SERVER_TYPE.HTTPS && !res.tls) {
-                    throw new Error('TLS configuration is required for HTTPS server type');
-                }
-            }
-            return res;
-        };
-    }
-}
-
-/**
- * @memberOf Fl32_Web_Back_Server_Config
- */
-class Dto {
-    /**
-     * Port to listening (3000).
-     *
-     * @type {number}
-     */
-    port;
-    /**
-     * @type {string}
-     * @see Fl32_Web_Back_Enum_Server_Type
-     */
-    type;
-    /**
-     * TLS configuration for HTTPS server.
-     * @type {Fl32_Web_Back_Server_Config_Tls.Dto|undefined}
-     */
-    tls;
-}

package/teqfw.json

@@ -1,8 +0,0 @@
-{
-  "@teqfw/di": {
-    "autoload": {
-      "ns": "Fl32_Web_",
-      "path": "./src"
-    }
-  }
-}