@flancer32/teq-web 0.1.0

package/src/Back/Server/Config.js

@@ -0,0 +1,69 @@
+/**
+ * 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/src/Back/Server.js

@@ -0,0 +1,92 @@
+/**
+ * Web server implementation supporting HTTP/1 and HTTP/2 protocols.
+ * Handles incoming requests and delegates them to the dispatcher.
+ *
+ * @property {function(): module:http.Server} getInstance - Returns the server instance.
+ * @property {function(Fl32_Web_Back_Server_Config.Dto): Promise<void>} start - Starts the server with given configuration.
+ * @property {function(): Promise<void>} stop - Stops the server.
+ */
+export default class Fl32_Web_Back_Server {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {typeof import('node:http')} http
+     * @param {typeof import('node:http2')} http2
+     * @param {Fl32_Web_Back_Defaults} DEF
+     * @param {Fl32_Web_Back_Logger} logger
+     * @param {Fl32_Web_Back_Dispatcher} dispatcher
+     * @param {typeof Fl32_Web_Back_Enum_Server_Type} SERVER_TYPE
+     */
+    constructor(
+        {
+            'node:http': http,
+            'node:http2': http2,
+            Fl32_Web_Back_Defaults$: DEF,
+            Fl32_Web_Back_Logger$: logger,
+            Fl32_Web_Back_Dispatcher$: dispatcher,
+            Fl32_Web_Back_Enum_Server_Type$: SERVER_TYPE,
+        }
+    ) {
+        /* eslint-enable jsdoc/require-param-description,jsdoc/check-param-names */
+        // VARS
+        const {createServer} = http;
+        const {createServer: createServerH2, createSecureServer} = http2;
+        /** @type {module:http.Server} */
+        let _instance;
+
+        // MAIN
+        /**
+         * @returns {module:http.Server}
+         */
+        this.getInstance = () => _instance;
+
+        /**
+         * Starts the server with optional configuration.
+         * @param {Fl32_Web_Back_Server_Config.Dto} [cfg] - Server configuration
+         * @returns {Promise<void>}
+         */
+        this.start = async function (cfg) {
+            // order handlers in the dispatcher
+            dispatcher.orderHandlers();
+            // create server
+            const port = cfg?.port ?? DEF.PORT;
+            const type = cfg?.type ?? SERVER_TYPE.HTTP;
+
+            if (type === SERVER_TYPE.HTTP2) {
+                _instance = createServerH2();
+                logger.info(`Starting server in HTTP/2 mode on port ${port}...`);
+            } else if (type === SERVER_TYPE.HTTP) {
+                _instance = createServer({});
+                logger.info(`Starting server in HTTP/1 mode on port ${port}...`);
+            } else if (type === SERVER_TYPE.HTTPS) {
+                if (!cfg.tls?.key || !cfg.tls?.cert) {
+                    logger.error('HTTPS server requires TLS key and certificate');
+                    throw new Error('TLS key and certificate are required for HTTPS server');
+                }
+                _instance = createSecureServer(cfg.tls);
+                logger.info(`Starting server in HTTPS (HTTP/2 + TLS) mode on port ${port}...`);
+            } else {
+                logger.error(`Unsupported server type: ${type}`);
+                throw new Error(`Server type '${type}' is not supported`);
+            }
+
+            _instance.on('request', dispatcher.onEventRequest);
+            _instance.listen(port);
+        };
+
+        /**
+         * Stops the server.
+         * @returns {Promise<void>}
+         */
+        this.stop = async function () {
+            if (_instance) {
+                await new Promise((resolve, reject) => {
+                    _instance.close(err => err ? reject(err) : resolve());
+                });
+                logger.info('Server stopped');
+                _instance = undefined;
+            } else {
+                logger.warn('Server is not running');
+            }
+        };
+    }
+}

package/test/accept/Server.test.mjs

@@ -0,0 +1,105 @@
+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 (real)', () => {
+  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);
+  });
+});

package/test/certs/ca.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDCTCCAfGgAwIBAgIUBpZ2v9fA8XfqVF83Nw5byUa0ylswDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDYwODA5MDA1N1oXDTI2MDYw
+ODA5MDA1N1owFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEAymikxJnbPFs3H/rRzetPjUdOPVuMOTfkz5oBDcP7s/2W
+O7135UPbDGzClYyYJvwAZm9i1Vivzm6KrNDZR0lawqYVf6COGJSAtMrkzx+bFSh7
+HWhuk4ByAdoZr6kFzpYBrxcfjSLU2oqaCyzb5vfksfrk1Yyr/i8DK6sw640OUlzP
+1rtKTuRCpYm8We/wrxEvrcdzk7FVFYLCzQfGOZLPmZpoDI3pdUJ/wkY4tjPAPFLn
+143L+07ZLN7Zuf0mpRAGpKve+MWzfId4xXoJ2XpGolLEkhJhfDNI9DCBjEZ3cYmJ
+LYSkpevQuTJNQm/89ivPk3FV0p3H4KjKKgtvtUaOZQIDAQABo1MwUTAdBgNVHQ4E
+FgQUjriVSWVYIJ/a21utkNLU2Cvjl1swHwYDVR0jBBgwFoAUjriVSWVYIJ/a21ut
+kNLU2Cvjl1swDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAkcHr
+TPlqzehyG1KGGb7VAGwCoqhUJfz0Pd3z2p+UOoKq/EmC8b1FRgKDZxSQHk0hhQWE
+M4f51tTbv2LgskfOF/S/tDoKBGnOwYS0oFmVqEstHuC2uto8ukj3FNvsZW58x4Q1
+DOGLkUqlPj5vAh8Zhw8GWokorF11dZlnKdPTC3NCdqyPTWNQPeSqd2qGsFgMBB2i
+q49QsUCNqiVc5ZfpbTBq+Jk1qHd1Pyf9Dlxm3Wi6RBguBcpHooZTAAYleSk+uhSa
+xH9f8v9E2aeYAk/zsZQt2f3x9sZQCAfjHPDOzXydiv568FasLxACY12/GkMNGdvy
+xlgkz6c0z3TS8kFxrQ==
+-----END CERTIFICATE-----

package/test/certs/cert.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDCTCCAfGgAwIBAgIUBpZ2v9fA8XfqVF83Nw5byUa0ylswDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDYwODA5MDA1N1oXDTI2MDYw
+ODA5MDA1N1owFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEAymikxJnbPFs3H/rRzetPjUdOPVuMOTfkz5oBDcP7s/2W
+O7135UPbDGzClYyYJvwAZm9i1Vivzm6KrNDZR0lawqYVf6COGJSAtMrkzx+bFSh7
+HWhuk4ByAdoZr6kFzpYBrxcfjSLU2oqaCyzb5vfksfrk1Yyr/i8DK6sw640OUlzP
+1rtKTuRCpYm8We/wrxEvrcdzk7FVFYLCzQfGOZLPmZpoDI3pdUJ/wkY4tjPAPFLn
+143L+07ZLN7Zuf0mpRAGpKve+MWzfId4xXoJ2XpGolLEkhJhfDNI9DCBjEZ3cYmJ
+LYSkpevQuTJNQm/89ivPk3FV0p3H4KjKKgtvtUaOZQIDAQABo1MwUTAdBgNVHQ4E
+FgQUjriVSWVYIJ/a21utkNLU2Cvjl1swHwYDVR0jBBgwFoAUjriVSWVYIJ/a21ut
+kNLU2Cvjl1swDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAkcHr
+TPlqzehyG1KGGb7VAGwCoqhUJfz0Pd3z2p+UOoKq/EmC8b1FRgKDZxSQHk0hhQWE
+M4f51tTbv2LgskfOF/S/tDoKBGnOwYS0oFmVqEstHuC2uto8ukj3FNvsZW58x4Q1
+DOGLkUqlPj5vAh8Zhw8GWokorF11dZlnKdPTC3NCdqyPTWNQPeSqd2qGsFgMBB2i
+q49QsUCNqiVc5ZfpbTBq+Jk1qHd1Pyf9Dlxm3Wi6RBguBcpHooZTAAYleSk+uhSa
+xH9f8v9E2aeYAk/zsZQt2f3x9sZQCAfjHPDOzXydiv568FasLxACY12/GkMNGdvy
+xlgkz6c0z3TS8kFxrQ==
+-----END CERTIFICATE-----

package/test/certs/key.pem

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKaKTEmds8Wzcf
++tHN60+NR049W4w5N+TPmgENw/uz/ZY7vXflQ9sMbMKVjJgm/ABmb2LVWK/Oboqs
+0NlHSVrCphV/oI4YlIC0yuTPH5sVKHsdaG6TgHIB2hmvqQXOlgGvFx+NItTaipoL
+LNvm9+Sx+uTVjKv+LwMrqzDrjQ5SXM/Wu0pO5EKlibxZ7/CvES+tx3OTsVUVgsLN
+B8Y5ks+ZmmgMjel1Qn/CRji2M8A8UufXjcv7Ttks3tm5/SalEAakq974xbN8h3jF
+egnZekaiUsSSEmF8M0j0MIGMRndxiYkthKSl69C5Mk1Cb/z2K8+TcVXSncfgqMoq
+C2+1Ro5lAgMBAAECggEAEva0lUI6/aUoKC62Ox4++6QWIFPe8o9vjcRxMSp5qcvq
+Uu+LTPzLXZclBfZAXSACzkDFAusbvEdeu8FCJ4EnvTvqoLoDW38yWH3367CbiuMa
+NyT30zRXZMqxLw7ddJUDqbViEeA/uWKp+xO5Xfg/bNjDrtROsEe++szqY5n5dl2B
+aJLPEtg2OQW7GWKF7PX9YyZmbZds+L7WFhTE+42zfO6MMQm5jaTr8er74u6FnEA2
+ewrJmB7i9CS1DfYhCnJCwqOIxr9rPp9WMvRNfmL8wwqAr+4f1TidI7aKpA3vt2d0
+HOrnNws+08tlcqQYHHyasLzBzsYGAZRTvCoCxjVd8wKBgQDkWjNxp9TmNxQXxvhB
+J42lmo+9xBYzKUzmMMSvS7RoPFG8myf1s82qPTiwZZzGlpR6XIXfSZKQ45YhYz7S
+8i8VbhjVtGyOmExBRYryI3y8pC1aVHk6bPQl8rATIkqsIGN8VHSiwCMeV+j6VWUP
+ZYjb0iqS2zKhhXD9CVcXIT/SfwKBgQDi6lG64nI/ECjakXfrXa+J1T5NJE+OEP3J
+AR9nqRiR/VcwAFMBiJwFfm07dv4WHLbfI1qdx+OU4aSsBohyLg3X9WO0Y8iGw2w4
+V6GGiwGK009OfzdrwTM9QjVHhk23SlFeQFPib4uRGcRnjimMNY6M1E3qvXHpyVXV
+rpvxyGElGwKBgGjcXwlPJ738BvcQQIoy7qHggyeCdytRSOXf+UICQrsnD+XLXiM/
+SS9m47RlRQQQu+ggur0ZnPt590Qnvf7ChgqSP0dLjhpBJ6tFkxO0ZiB+R/FWH0FM
+LSWL930h3yaBzQ2X/uOJ1damSe9C7aCPYLSJI1HC5NI1Y/hepKaTdypjAoGAEfkr
+ZhkfoX0fL0jMbdkq2UkJuUSCBKe14mDzYtuS9aVSbZvo9zsh2JGOB2LCd2/o0D3V
+pJ+7mARTbcjKr/iT4iIutpAcxwfdn4zZX3XNNnjMVFRhSGiyLUz8OWEa8MSzMzr3
+Kf1Z2bFnzCgHhHKNivwZ+9jrl+/5m4ZMFdegUjcCgYEAu/cKxIBc3Lb4gVZx6nHp
+bPr9flDbdCKQk20kpVPvNxq67FuVyKy3n0svRX+fZ9uPhuv20IWkTBue3yCGKpjD
+kUJ2A9Y9FZGSwhU3LSo6grdEv3pIW1YLTl95nUO20bRWCWcwsoV5/GEhFkEZWq06
+wZCQXFhIY78gzd4gk+qJQpg=
+-----END PRIVATE KEY-----

package/test/dev/app/Plugin/Start.js

@@ -0,0 +1,38 @@
+export default class App_Plugin_Start {
+    /**
+     * @param {typeof import('node:path')} path
+     * @param {typeof import('node:url')} url
+     * @param {Fl32_Web_Back_Dispatcher} dispatcher
+     * @param {Fl32_Web_Back_Handler_Pre_Log} hndlRequestLog
+     * @param {Fl32_Web_Back_Handler_Static} hndlStatic
+     */
+    constructor(
+        {
+            'node:path': path,
+            'node:url': url,
+            Fl32_Web_Back_Dispatcher$: dispatcher,
+            Fl32_Web_Back_Handler_Pre_Log$: hndlRequestLog,
+            Fl32_Web_Back_Handler_Static$: hndlStatic,
+        }
+    ) {
+        // VARS
+        const {dirname, join} = path;
+        const {fileURLToPath} = url;
+
+        // MAIN
+        /* Resolve a path to the root folder. */
+        const metaUrl = new URL(import.meta.url);
+        const script = fileURLToPath(metaUrl);
+        const cur = dirname(script);
+        const root = join(cur, '..', '..');
+        const webRoot = join(root, 'web');
+
+        return async function () {
+            // Set up handlers
+            await hndlStatic.init({rootPath: webRoot});
+            // Register handlers
+            dispatcher.addHandler(hndlRequestLog);
+            dispatcher.addHandler(hndlStatic);
+        };
+    }
+}

package/test/dev/app.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * A test script to emulate an app that uses the web server.
+ */
+import {dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {readFileSync} from 'node:fs';
+import Container from '@teqfw/di';
+
+// VARS
+/* Resolve a path to the root folder. */
+const url = new URL(import.meta.url);
+const script = fileURLToPath(url);
+const cur = dirname(script);
+const root = join(cur, '..', '..');
+
+// Create a new instance of the container
+const container = new Container();
+
+// Get the resolver from the container
+const resolver = container.getResolver();
+resolver.addNamespaceRoot('Fl32_Web_', join(root, 'src'));
+resolver.addNamespaceRoot('App_', join(cur, 'app'));
+
+// init the app (add the handlers to the Dispatcher)
+/** @type {function} */
+const appStart = await container.get('App_Plugin_Start$');
+await appStart();
+
+// order handlers in the Dispatcher
+/** @type {Fl32_Web_Back_Dispatcher} */
+const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
+dispatcher.orderHandlers();
+
+// configure and run the server
+/** @type {Fl32_Web_Back_Server} */
+const server = await container.get('Fl32_Web_Back_Server$');
+/** @type {typeof Fl32_Web_Back_Enum_Server_Type} */
+const SERVER_TYPE = await container.get('Fl32_Web_Back_Enum_Server_Type$');
+/** @type {Fl32_Web_Back_Server_Config} */
+const factConfig = await container.get('Fl32_Web_Back_Server_Config$');
+
+// Read TLS certificates
+const certsDir = join(cur, '..', 'certs');
+const key = readFileSync(join(certsDir, 'key.pem'), 'utf8');
+const cert = readFileSync(join(certsDir, 'cert.pem'), 'utf8');
+let ca;
+try {
+    ca = readFileSync(join(certsDir, 'ca.pem'), 'utf8');
+} catch (e) {
+    // CA certificate is optional
+}
+
+console.log('Starting HTTPS server on port 3443...');
+const cfg = factConfig.create({
+    port: 3443,
+    type: SERVER_TYPE.HTTPS,
+    tls: {
+        key,
+        cert,
+        ca
+    }
+});
+await server.start(cfg);

package/test/dev/web/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1.0">
+    <title>@flancer32/teq-web</title>
+</head>
+<body>
+<p>Hello, from `@flancer32/teq-web`!</p>
+</body>
+</html>

package/test/unit/Back/Helper/Order/Kahn.test.mjs

@@ -0,0 +1,59 @@
+import {describe, it} from 'node:test';
+import assert from 'node:assert/strict';
+import {buildTestContainer} from '../../../common.js';
+
+describe('Fl32_Web_Back_Helper_Order_Kahn', () => {
+
+    describe('sort', () => {
+        it('should sort handlers respecting after/before constraints', async () => {
+            const container = buildTestContainer();
+            const sorter = await container.get('Fl32_Web_Back_Helper_Order_Kahn$');
+
+            // Mock handlers with dependencies
+            const mk = (name, after = [], before = []) => ({
+                getRegistrationInfo: () => ({name, after, before})
+            });
+
+            const a = mk('a');                  // no deps
+            const b = mk('b', ['a']);           // after a
+            const c = mk('c', [], ['b']);       // before b (== b after c)
+            const d = mk('d', ['b', 'c']);      // after b and c
+
+            const result = sorter.sort([a, b, c, d]);
+            const names = result.map(h => h.getRegistrationInfo().name);
+            assert.deepStrictEqual(names, ['a', 'c', 'b', 'd']);
+        });
+
+        it('should detect circular dependency', async () => {
+            const container = buildTestContainer();
+            const sorter = await container.get('Fl32_Web_Back_Helper_Order_Kahn$');
+
+            const mk = (name, after = [], before = []) => ({
+                getRegistrationInfo: () => ({name, after, before})
+            });
+
+            const x = mk('x', ['y']);
+            const y = mk('y', ['x']);
+
+            assert.throws(() => {
+                sorter.sort([x, y]);
+            }, /Circular dependency detected/);
+        });
+
+        it('should ignore references to unknown handlers', async () => {
+            const container = buildTestContainer();
+            const sorter = await container.get('Fl32_Web_Back_Helper_Order_Kahn$');
+
+            const mk = (name, after = [], before = []) => ({
+                getRegistrationInfo: () => ({name, after, before})
+            });
+
+            const a = mk('a', ['ghost']); // ghost does not exist
+            const b = mk('b');
+
+            const result = sorter.sort([a, b]);
+            const names = result.map(h => h.getRegistrationInfo().name);
+            assert.deepStrictEqual(names.sort(), ['a', 'b']); // Order can vary, but no crash
+        });
+    });
+});

package/test/unit/Back/Server.test.mjs

@@ -0,0 +1,112 @@
+import {describe, it, beforeEach} from 'node:test';
+import assert from 'node:assert/strict';
+import {buildTestContainer} from '../common.js';
+
+describe('Fl32_Web_Back_Server (mocked)', () => {
+
+    /** @type {import('@teqfw/di').Container} */
+    let container;
+    /** @type {Array<*>} */
+    const log = [];
+
+    // Mocks for HTTP/1 and HTTP/2 servers
+    const mockHttp = {
+        createServer: () => ({
+            listen: () => { log.push('http.listen'); },
+            on: () => { log.push('http.on'); },
+            close: (cb) => { log.push('http.close'); cb && cb(); },
+        }),
+    };
+
+    const mockHttp2 = {
+        createServer: () => ({
+            listen: () => { log.push('http2.listen'); },
+            on: () => { log.push('http2.on'); },
+            close: (cb) => { log.push('http2.close'); cb && cb(); },
+        }),
+        createSecureServer: (tlsOpts) => ({
+            listen: () => { log.push('http2s.listen'); },
+            on: () => { log.push('http2s.on'); },
+            close: (cb) => { log.push('http2s.close'); cb && cb(); },
+        })
+    };
+
+    beforeEach(() => {
+        log.length = 0;
+        container = buildTestContainer();
+
+        container.register('node:http', mockHttp);
+        container.register('node:http2', mockHttp2);
+
+        container.register('Fl32_Web_Back_Logger$', {
+            info: (...args) => log.push(['info', ...args]),
+            error: (...args) => log.push(['error', ...args]),
+        });
+
+        container.register('Fl32_Web_Back_Dispatcher$', {
+            orderHandlers: () => log.push('dispatcher.orderHandlers'),
+            onEventRequest: () => {},
+        });
+    });
+
+    it('should start in HTTP/1 mode by default', async () => {
+        const server = await container.get('Fl32_Web_Back_Server$');
+        await server.start(); // default mode is HTTP/1
+        assert.deepStrictEqual(log, [
+            'dispatcher.orderHandlers',
+            ['info', 'Starting server in HTTP/1 mode on port 3000...'],
+            'http.on',
+            'http.listen',
+        ]);
+    });
+
+    it('should start in HTTP/2 mode if specified', async () => {
+        const server = await container.get('Fl32_Web_Back_Server$');
+        await server.start({type: 'http2', port: 8080});
+        assert.deepStrictEqual(log, [
+            'dispatcher.orderHandlers',
+            ['info', 'Starting server in HTTP/2 mode on port 8080...'],
+            'http2.on',
+            'http2.listen',
+        ]);
+    });
+
+    it('should start in HTTPS/2 mode with TLS config', async () => {
+        const server = await container.get('Fl32_Web_Back_Server$');
+        await server.start({type: 'https', port: 8443, tls: {key: 'a', cert: 'b'}});
+        assert.deepStrictEqual(log, [
+            'dispatcher.orderHandlers',
+            ['info', 'Starting server in HTTPS (HTTP/2 + TLS) mode on port 8443...'],
+            'http2s.on',
+            'http2s.listen',
+        ]);
+    });
+
+    it('should throw error if TLS config is missing in HTTPS mode', async () => {
+        const server = await container.get('Fl32_Web_Back_Server$');
+        await assert.rejects(
+            () => server.start({type: 'https', port: 1234}),
+            /TLS key and certificate are required/
+        );
+        assert.deepStrictEqual(log.at(-1), ['error', 'HTTPS server requires TLS key and certificate']);
+    });
+
+    it('should throw error on unsupported server type', async () => {
+        const server = await container.get('Fl32_Web_Back_Server$');
+        await assert.rejects(
+            () => server.start({type: 'ftp', port: 21}),
+            /not supported/
+        );
+        assert.deepStrictEqual(log.at(-1), ['error', 'Unsupported server type: ftp']);
+    });
+
+    it('should stop the server', async () => {
+        const server = await container.get('Fl32_Web_Back_Server$');
+        await server.start();
+        await server.stop();
+        assert.deepStrictEqual(log.slice(-2), [
+            'http.close',
+            ['info', 'Server stopped'],
+        ]);
+    });
+});

package/test/unit/common.js

@@ -0,0 +1,22 @@
+/**
+ * Provides a utility to create a configured TeqFW DI container for unit testing.
+ */
+import path from 'node:path';
+import Container from '@teqfw/di';
+
+// Resolve the plugin source path relative to this script
+const SRC = path.resolve(import.meta.dirname, '../../src');
+
+/**
+ * Builds a test DI container for unit tests.
+ * Registers plugin namespace and enables test mode.
+ *
+ * @returns {TeqFw_Di_Container} Test container instance.
+ */
+export function buildTestContainer() {
+    const container = new Container();
+    const resolver = container.getResolver();
+    resolver.addNamespaceRoot('Fl32_Web_', SRC);
+    container.enableTestMode();
+    return container;
+}