@flancer32/teq-web 0.3.1 → 0.5.0

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.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"
-    }
-  }
-}

package/test/accept/ExternalServer.test.mjs

@@ -1,66 +0,0 @@
-import {describe, it} from 'node:test';
-import assert from 'node:assert/strict';
-import http from 'node:http';
-import {buildTestContainer} from '../unit/common.js';
-import Express from 'express';
-import Fastify from 'fastify';
-
-async function startExpress(port, dispatcher) {
-  const app = Express();
-  app.use(async (req, res) => {
-    await dispatcher.onEventRequest(req, res);
-  });
-  const server = await new Promise((resolve, reject) => {
-    const srv = app.listen(port, err => err ? reject(err) : resolve(srv));
-  });
-  return server;
-}
-
-async function startFastify(port, dispatcher) {
-  const fastify = Fastify();
-  fastify.all('*', async (request, reply) => {
-    const req = request.raw;
-    const res = reply.raw;
-    await dispatcher.onEventRequest(req, res);
-  });
-  await fastify.listen({port});
-  return fastify;
-}
-
-describe('Dispatcher integration with external servers', () => {
-  it('should respond via express', async () => {
-    const container = buildTestContainer();
-    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
-    const port = 3054;
-    const server = await startExpress(port, dispatcher);
-
-    const status = await new Promise((resolve, reject) => {
-      http.get(`http://localhost:${port}`, res => {
-        const {statusCode} = res;
-        res.resume();
-        res.on('end', () => resolve(statusCode));
-      }).on('error', reject);
-    });
-
-    assert.strictEqual(status, 404);
-    await new Promise(resolve => server.close(resolve));
-  });
-
-  it('should respond via fastify', async () => {
-    const container = buildTestContainer();
-    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
-    const port = 3055;
-    const fastify = await startFastify(port, dispatcher);
-
-    const status = await new Promise((resolve, reject) => {
-      http.get(`http://localhost:${port}`, res => {
-        const {statusCode} = res;
-        res.resume();
-        res.on('end', () => resolve(statusCode));
-      }).on('error', reject);
-    });
-
-    assert.strictEqual(status, 404);
-    await fastify.close();
-  });
-});

package/test/accept/Server.test.mjs

@@ -1,203 +0,0 @@
-import {describe, it} from 'node:test';
-import assert from 'node:assert/strict';
-import {readFileSync} from 'node:fs';
-import {join, dirname} from 'node:path';
-import {fileURLToPath} from 'node:url';
-import {buildTestContainer} from '../unit/common.js';
-
-async function waitListening(server) {
-  if (!server.getInstance().listening) {
-    await new Promise(res => server.getInstance().once('listening', res));
-  }
-}
-
-describe('Fl32_Web_Back_Server', () => {
-  it('should start and respond in HTTP/1 mode', async () => {
-    const container = buildTestContainer();
-    const server = await container.get('Fl32_Web_Back_Server$');
-    const SERVER_TYPE = await container.get('Fl32_Web_Back_Enum_Server_Type$');
-    const Config = await container.get('Fl32_Web_Back_Server_Config$');
-    const http = await container.get('node:http');
-
-    const cfg = Config.create({ port: 3051, type: SERVER_TYPE.HTTP });
-    await server.start(cfg);
-    await waitListening(server);
-
-    const status = await new Promise((resolve, reject) => {
-      http.get(`http://localhost:${cfg.port}`, res => {
-        const {statusCode} = res;
-        res.resume();
-        res.on('end', () => resolve(statusCode));
-      }).on('error', reject);
-    });
-
-    assert.strictEqual(status, 404);
-    await server.stop();
-    assert.strictEqual(server.getInstance(), undefined);
-  });
-
-  it('should start and respond in HTTP/2 mode', async () => {
-    const container = buildTestContainer();
-    const server = await container.get('Fl32_Web_Back_Server$');
-    const SERVER_TYPE = await container.get('Fl32_Web_Back_Enum_Server_Type$');
-    const Config = await container.get('Fl32_Web_Back_Server_Config$');
-    const http2 = await container.get('node:http2');
-
-    const cfg = Config.create({ port: 3052, type: SERVER_TYPE.HTTP2 });
-    await server.start(cfg);
-    await waitListening(server);
-
-    const status = await new Promise((resolve, reject) => {
-      const client = http2.connect(`http://localhost:${cfg.port}`);
-      client.on('error', reject);
-      const req = client.request({ ':path': '/' });
-      req.on('response', headers => {
-        resolve(headers[':status']);
-      });
-      req.on('end', () => client.close());
-      req.end();
-    });
-
-    assert.strictEqual(status, 404);
-    await server.stop();
-    assert.strictEqual(server.getInstance(), undefined);
-  });
-
-  it('should start and respond in HTTPS mode', async () => {
-    const container = buildTestContainer();
-    const server = await container.get('Fl32_Web_Back_Server$');
-    const SERVER_TYPE = await container.get('Fl32_Web_Back_Enum_Server_Type$');
-    const Config = await container.get('Fl32_Web_Back_Server_Config$');
-    const http2 = await container.get('node:http2');
-
-    const dir = dirname(fileURLToPath(import.meta.url));
-    const certDir = join(dir, '..', 'certs');
-    const key = readFileSync(join(certDir, 'key.pem'), 'utf8');
-    const cert = readFileSync(join(certDir, 'cert.pem'), 'utf8');
-    let ca;
-    try { ca = readFileSync(join(certDir, 'ca.pem'), 'utf8'); } catch {}
-
-    const cfg = Config.create({
-      port: 3053,
-      type: SERVER_TYPE.HTTPS,
-      tls: {key, cert, ca}
-    });
-    await server.start(cfg);
-    await waitListening(server);
-
-    const status = await new Promise((resolve, reject) => {
-      const client = http2.connect(`https://localhost:${cfg.port}`, {
-        rejectUnauthorized: false,
-      });
-      client.on('error', reject);
-      const req = client.request({ ':path': '/' });
-      req.on('response', headers => {
-        resolve(headers[':status']);
-      });
-      req.on('end', () => client.close());
-      req.end();
-    });
-
-    assert.strictEqual(status, 404);
-    await server.stop();
-    assert.strictEqual(server.getInstance(), undefined);
-  });
-});
-
-describe('Fl32_Web_Back_Api_Handler', () => {
-  it('should serve allowed NPM file', async () => {
-    const container = buildTestContainer();
-    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
-    const handler = await container.get('Fl32_Web_Back_Handler_Static$');
-    const Cfg = await container.get('Fl32_Web_Back_Dto_Handler_Source$');
-    await handler.init({
-      sources: [Cfg.create({
-        root: 'node_modules',
-        prefix: '/npm/',
-        allow: {
-          '@teqfw/di/src': ['.'],
-        },
-      })],
-    });
-    dispatcher.addHandler(handler);
-    dispatcher.orderHandlers();
-
-    const server = await container.get('Fl32_Web_Back_Server$');
-    const SERVER_TYPE = await container.get('Fl32_Web_Back_Enum_Server_Type$');
-    const Config = await container.get('Fl32_Web_Back_Server_Config$');
-    const http = await container.get('node:http');
-
-    const cfg = Config.create({ port: 3056, type: SERVER_TYPE.HTTP });
-    await server.start(cfg);
-    await waitListening(server);
-
-    const result = await new Promise((resolve, reject) => {
-      const req = http.get({
-        hostname: 'localhost',
-        port: cfg.port,
-        path: '/npm/@teqfw/di/src/Api/Container/Parser/Chunk.js',
-      }, res => {
-        const chunks = [];
-        res.on('data', ch => chunks.push(ch));
-        res.on('end', () => {
-          resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString() });
-        });
-      });
-      req.on('error', reject);
-    });
-
-    assert.strictEqual(result.status, 200);
-    assert.match(result.body, /class TeqFw_Di_Api_Container_Parser_Chunk/);
-
-    await server.stop();
-    assert.strictEqual(server.getInstance(), undefined);
-  });
-
-  it('should serve allowed source file', async () => {
-    const container = buildTestContainer();
-    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
-    const handler = await container.get('Fl32_Web_Back_Handler_Static$');
-    const Cfg = await container.get('Fl32_Web_Back_Dto_Handler_Source$');
-    await handler.init({
-      sources: [Cfg.create({
-        root: 'src',
-        prefix: '/sources/',
-        allow: {
-          Back: ['Server.js'],
-        },
-      })],
-    });
-    dispatcher.addHandler(handler);
-    dispatcher.orderHandlers();
-
-    const server = await container.get('Fl32_Web_Back_Server$');
-    const SERVER_TYPE = await container.get('Fl32_Web_Back_Enum_Server_Type$');
-    const Config = await container.get('Fl32_Web_Back_Server_Config$');
-    const http = await container.get('node:http');
-
-    const cfg = Config.create({ port: 3057, type: SERVER_TYPE.HTTP });
-    await server.start(cfg);
-    await waitListening(server);
-
-    const result = await new Promise((resolve, reject) => {
-      const req = http.get({
-        hostname: 'localhost',
-        port: cfg.port,
-        path: '/sources/Back/Server.js',
-      }, res => {
-        const chunks = [];
-        res.on('data', ch => chunks.push(ch));
-        res.on('end', () => {
-          resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString() });
-        });
-      });
-      req.on('error', reject);
-    });
-
-    assert.strictEqual(result.status, 200);
-    assert.match(result.body, /class Fl32_Web_Back_Server/);
-
-    await server.stop();
-    assert.strictEqual(server.getInstance(), undefined);
-  });
-});