@flancer32/teq-web 0.4.0 → 0.6.0

package/ai/rules.md

@@ -0,0 +1,44 @@
+# Usage Rules
+
+## Structural Rules
+
+- The Pipeline Engine is the only request-lifecycle coordinator.
+- Request processing always uses the fixed stage sequence `INIT -> PROCESS -> FINALIZE`.
+- Handlers are registered during setup and must not be added, removed, or reordered after startup.
+- Handler ordering is declarative and derived from `name`, `before`, and `after`.
+
+## Completion Rules
+
+- Request completion is a monotonic flag for one request.
+- Only `PROCESS` handlers may call `context.complete()` or set completion to `true`.
+- `INIT` and `FINALIZE` handlers must never mark the request completed.
+- Completion cannot be reset once set.
+
+## Response Rules
+
+- Exactly one terminal HTTP response must result from each request.
+- If no `PROCESS` handler completes the request and the response is still writable, the Pipeline Engine returns `404 Not Found`.
+- If a `PROCESS` handler throws and the response is still writable, the Pipeline Engine returns `500 Internal Server Error` and stops further PROCESS handlers.
+- Exceptions in `INIT` and `FINALIZE` handlers are isolated and do not abort the pipeline.
+
+## Transport Boundary
+
+- Handlers work on request context and response specification only.
+- Handlers must not perform transport-level transmission or socket management.
+- Actual network response transmission belongs to the built-in `Server` or to the external transport framework that called the Pipeline Engine.
+
+## Environment Assumptions
+
+- Runtime is Node.js 20 or newer.
+- The package is intended for long-running server processes.
+- Process supervision, restart, scaling, reverse proxying, and load balancing are external concerns.
+- Multiple instances may run concurrently, but they are independent and must not rely on shared in-memory state.
+
+## DI Usage Rules
+
+- The package is designed for `@teqfw/di`.
+- Consumer code should resolve package modules through the `Fl32_Web_` namespace mapped to the package `src/` path.
+- Startup configuration for the built-in server should be supplied through `Fl32_Web_Back_Config_Runtime__Factory$` using the hierarchical configuration shape `{server: {...}}`.
+- TLS startup configuration belongs to the dedicated runtime component `Fl32_Web_Back_Config_Runtime_Tls$`, even though consumers read it through `config.server.tls`.
+- Configure runtime values during startup only; once the runtime configuration is frozen for use, consumers must treat `Fl32_Web_Back_Config_Runtime$` and `Fl32_Web_Back_Config_Runtime_Tls$` as immutable read-only state.
+- Treat helper internals under deep implementation paths as non-essential unless the task specifically requires them. Preferred consumer entry points are the Pipeline Engine, Server, handler API, DTO factories, enums, and built-in handlers.

package/package.json

@@ -1,57 +1,63 @@
 {
   "name": "@flancer32/teq-web",
-  "version": "0.4.0",
-  "description": "Node.js web plugin supporting Express and Fastify integration, with built-in server for standalone operation",
+  "version": "0.6.0",
+  "description": "Server-side web request coordination infrastructure for TeqFW modular monolith applications.",
   "type": "module",
-  "types": "types.d.ts",
-  "keywords": [
-    "es6+",
-    "teqfw",
-    "tequila framework",
-    "web applications"
-  ],
-  "homepage": "https://github.com/flancer32/teq-web#readme",
-  "bugs": {
-    "url": "https://github.com/flancer32/teq-web/issues"
-  },
   "license": "Apache-2.0",
   "author": {
     "name": "Alex Gusev",
     "email": "alex@flancer64.com",
     "url": "https://github.com/flancer64"
   },
-  "files": [
-    "src/",
-    "CHANGELOG.md",
-    "LICENSE",
-    "README.md",
-    "teqfw.json",
-    "types.d.ts"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/flancer32/teq-web.git"
   },
-  "scripts": {
-    "eslint": "./node_modules/.bin/eslint ./src/",
-    "test:accept": "node --test $(find ./test/accept -name '*.test.mjs')",
-    "test:unit": "node --test $(find ./test/unit -name '*.test.mjs')"
+  "homepage": "https://github.com/flancer32/teq-web",
+  "bugs": {
+    "url": "https://github.com/flancer32/teq-web/issues"
+  },
+  "keywords": [
+    "teqfw",
+    "tequila-framework",
+    "web",
+    "dispatcher",
+    "request-pipeline",
+    "dependency-injection",
+    "modular-monolith",
+    "nodejs"
+  ],
+  "types": "types.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "teqfw": {
+    "namespaces": [
+      {
+        "prefix": "Fl32_Web_",
+        "path": "./src",
+        "ext": ".mjs"
+      }
+    ]
   },
   "dependencies": {
-    "@teqfw/di": "^1.1.3"
+    "@teqfw/di": "^2.1.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.25.0",
-    "eslint": "^9.25.0",
-    "eslint-plugin-jsdoc": "^50.6.8",
-    "express": "^4.18.2",
-    "fastify": "^4.27.2"
+    "@types/node": "^25.4.0",
+    "eslint": "^10.0.3"
   },
-  "engines": {
-    "node": ">=20"
+  "scripts": {
+    "test:unit": "find test/unit -name '*.test.mjs' -print0 | xargs -0 node --test",
+    "test:integration": "find test/integration -name '*.test.mjs' -print0 | xargs -0 node --test",
+    "test": "npm run test:unit && npm run test:integration"
   },
-  "funding": {
-    "type": "individual",
-    "url": "https://github.com/sponsors/teqfw"
-  }
+  "files": [
+    "ai/",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "types.d.ts"
+  ]
 }

package/src/Back/Api/Handler.mjs

@@ -0,0 +1,26 @@
+// @ts-check
+
+/**
+ * Interface for web request handlers used by the Pipeline Engine.
+ *
+ * @interface
+ */
+export default class Fl32_Web_Back_Api_Handler {
+    /* eslint-disable no-unused-vars */
+    /**
+     * Handles one request context in a pipeline stage.
+     * @param {Fl32_Web_Back_Dto_RequestContext} context
+     * @returns {Promise<void>}
+     */
+    async handle(context) {
+        throw new Error('Method not implemented');
+    }
+
+    /**
+     * Provides metadata for pipeline registration.
+     * @returns {Fl32_Web_Back_Dto_Info}
+     */
+    getRegistrationInfo() {
+        throw new Error('Method not implemented');
+    }
+}

package/src/Back/Config/Runtime/Tls.mjs

@@ -0,0 +1,89 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+});
+
+/**
+ * TLS runtime configuration.
+ */
+export class Data {
+    /** @type {string|undefined} */
+    ca;
+    /** @type {string|undefined} */
+    cert;
+    /** @type {string|undefined} */
+    key;
+}
+
+/** @type {Fl32_Web_Back_Config_Runtime_Tls} */
+const cfg = new Data();
+let frozen = false;
+
+/** @type {Fl32_Web_Back_Config_Runtime_Tls} */
+const proxy = new Proxy(cfg, {
+    get(target, prop) {
+        const isServiceProp = (prop === 'then') || (typeof prop === 'symbol');
+        if (!frozen && !isServiceProp) throw new Error('Runtime configuration is not initialized.');
+        return target[prop];
+    },
+    set() {
+        throw new Error('Runtime configuration is immutable.');
+    },
+    defineProperty(target, prop, descriptor) {
+        const current = Object.getOwnPropertyDescriptor(target, prop);
+        const isFreezeStep = current
+            && (descriptor?.configurable === false)
+            && (!('writable' in descriptor) || descriptor.writable === false)
+            && (!('value' in descriptor) || descriptor.value === current.value);
+        if (isFreezeStep) {
+            return Reflect.defineProperty(target, prop, descriptor);
+        }
+        throw new Error('Runtime configuration is immutable.');
+    },
+    deleteProperty() {
+        throw new Error('Runtime configuration is immutable.');
+    },
+});
+
+export default class Wrapper {
+    constructor() {
+        return proxy;
+    }
+}
+
+export class Factory {
+    /**
+     * @param {object} params
+     * @param {Fl32_Web_Back_Helper_Cast} params.cast
+     */
+    constructor({cast}) {
+        /**
+         * @param {Fl32_Web_Back_Config_Runtime_Tls_Params} [params]
+         * @returns {Fl32_Web_Back_Config_Runtime_Tls}
+         */
+        this.configure = function (params = {}) {
+            if (frozen) throw new Error('Runtime configuration is frozen.');
+            if (cfg.ca === undefined && params.ca !== undefined) {
+                cfg.ca = cast.string(params.ca);
+            }
+            if (cfg.cert === undefined && params.cert !== undefined) {
+                cfg.cert = cast.string(params.cert);
+            }
+            if (cfg.key === undefined && params.key !== undefined) {
+                cfg.key = cast.string(params.key);
+            }
+            return proxy;
+        };
+
+        /**
+         * @returns {Fl32_Web_Back_Config_Runtime_Tls}
+         */
+        this.freeze = function () {
+            if (frozen) return proxy;
+            Object.freeze(cfg);
+            frozen = true;
+            return proxy;
+        };
+    }
+}

package/src/Back/Config/Runtime.mjs

@@ -0,0 +1,114 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+    SERVER_TYPE: 'Fl32_Web_Back_Enum_Server_Type$',
+    tlsFactory: 'Fl32_Web_Back_Config_Runtime_Tls__Factory$',
+});
+
+/**
+ * Backend runtime configuration.
+ */
+export class Data {
+    /** @type {Fl32_Web_Back_Config_Runtime_Server|undefined} */
+    server;
+}
+
+/**
+ * Built-in server runtime configuration subtree.
+ */
+export class Server {
+    /** @type {number|undefined} */
+    port;
+    /** @type {string|undefined} */
+    type;
+    /** @type {Fl32_Web_Back_Config_Runtime_Tls|undefined} */
+    tls;
+}
+
+/** @type {Fl32_Web_Back_Config_Runtime} */
+const cfg = new Data();
+let frozen = false;
+
+/** @type {Fl32_Web_Back_Config_Runtime} */
+const proxy = new Proxy(cfg, {
+    get(target, prop) {
+        const isServiceProp = (prop === 'then') || (typeof prop === 'symbol');
+        if (!frozen && !isServiceProp) throw new Error('Runtime configuration is not initialized.');
+        return target[prop];
+    },
+    set() {
+        throw new Error('Runtime configuration is immutable.');
+    },
+    defineProperty(target, prop, descriptor) {
+        const current = Object.getOwnPropertyDescriptor(target, prop);
+        const isFreezeStep = current
+            && (descriptor?.configurable === false)
+            && (!('writable' in descriptor) || descriptor.writable === false)
+            && (!('value' in descriptor) || descriptor.value === current.value);
+        if (isFreezeStep) {
+            return Reflect.defineProperty(target, prop, descriptor);
+        }
+        throw new Error('Runtime configuration is immutable.');
+    },
+    deleteProperty() {
+        throw new Error('Runtime configuration is immutable.');
+    },
+});
+
+export default class Wrapper {
+    constructor() {
+        return proxy;
+    }
+}
+
+export class Factory {
+    /**
+     * @param {object} params
+     * @param {Fl32_Web_Back_Helper_Cast} params.cast
+     * @param {Fl32_Web_Back_Enum_Server_Type} params.SERVER_TYPE
+     * @param {Fl32_Web_Back_Config_Runtime_Tls$Factory} params.tlsFactory
+     */
+    constructor({ cast, SERVER_TYPE, tlsFactory }) {
+        /**
+         * @param {Fl32_Web_Back_Config_Runtime_Params} [params]
+         * @returns {Fl32_Web_Back_Config_Runtime}
+         */
+        this.configure = function (params = {}) {
+            if (frozen) throw new Error('Runtime configuration is frozen.');
+            if (cfg.server === undefined) cfg.server = new Server();
+            if (cfg.server.port === undefined && params.server?.port !== undefined) {
+                cfg.server.port = cast.int(params.server.port);
+            }
+            if (cfg.server.type === undefined && params.server?.type !== undefined) {
+                cfg.server.type = cast.enum(params.server.type, SERVER_TYPE, { lower: true });
+            }
+            if (params.server?.tls !== undefined) {
+                tlsFactory.configure(params.server.tls);
+            }
+            return proxy;
+        };
+
+        /**
+         * @returns {Fl32_Web_Back_Config_Runtime}
+         */
+        this.freeze = function () {
+            if (frozen) return proxy;
+            if (cfg.server === undefined) cfg.server = new Server();
+            if (cfg.server.port === undefined) cfg.server.port = 3000;
+            if (cfg.server.type === undefined) cfg.server.type = SERVER_TYPE.HTTP;
+            const tls = tlsFactory.freeze();
+            if (cfg.server.tls === undefined) cfg.server.tls = tls;
+            if (cfg.server.type === SERVER_TYPE.HTTPS && cfg.server.tls === undefined) {
+                throw new Error('TLS configuration is required for HTTPS server type');
+            }
+            if (cfg.server.type === SERVER_TYPE.HTTPS && (!cfg.server.tls.key || !cfg.server.tls.cert)) {
+                throw new Error('TLS configuration is required for HTTPS server type');
+            }
+            Object.freeze(cfg.server);
+            Object.freeze(cfg);
+            frozen = true;
+            return proxy;
+        };
+    }
+}

package/src/Back/Dto/Info.mjs

@@ -0,0 +1,62 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+});
+
+export default class Fl32_Web_Back_Dto_Info {
+    /**
+     * 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|undefined}
+     */
+    name;
+
+    /**
+     * Execution stage: `INIT`, `PROCESS`, or `FINALIZE`.
+     * @type {string|undefined}
+     * @see Fl32_Web_Back_Enum_Stage
+     */
+    stage;
+}
+
+export class Factory {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {object} params
+     * @param {Fl32_Web_Back_Helper_Cast} params.cast
+     * @param {Fl32_Web_Back_Enum_Stage} params.STAGE
+     */
+    constructor(
+        {
+            cast,
+            STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+        /**
+         * @param {*} [data]
+         * @returns {Fl32_Web_Back_Dto_Info}
+         */
+        this.create = function (data) {
+            const res = new Fl32_Web_Back_Dto_Info();
+            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, {upper: true});
+            return Object.freeze(res);
+        };
+    }
+}

package/src/Back/Dto/RequestContext.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+
+/**
+ * Request context passed through the pipeline lifecycle.
+ */
+export default class Fl32_Web_Back_Dto_RequestContext {
+    /** @type {Fl32_Web_Node_Http_IncomingMessage|Fl32_Web_Node_Http2_ServerRequest} */
+    request;
+
+    /** @type {Fl32_Web_Back_Response_Target} */
+    response;
+
+    /** @type {Record<string, unknown>} */
+    data = {};
+
+    /** @type {boolean} */
+    completed = false;
+
+    /** @type {() => void} */
+    complete;
+
+    /** @type {() => boolean} */
+    isCompleted;
+}
+
+export class Factory {
+    /**
+     * @returns {Fl32_Web_Back_Dto_RequestContext}
+     */
+    create() {
+        return new Fl32_Web_Back_Dto_RequestContext();
+    }
+}

package/src/Back/Dto/{Handler/Source.js → Source.mjs}

@@ -1,46 +1,45 @@
-/**
- * Factory for file source configuration DTO used by Static handler.
- */
-export default class Fl32_Web_Back_Dto_Handler_Source {
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+});
+
+export default class Fl32_Web_Back_Dto_Source {
+    /** @type {string} */
+    root;
+    /** @type {string} */
+    prefix;
+    /** @type {{[key: string]: string[]}} */
+    allow = {};
+    /** @type {string[]} */
+    defaults = [];
+}
+
+export class Factory {
     /* eslint-disable jsdoc/require-param-description */
     /**
-     * @param {Fl32_Web_Back_Helper_Cast} cast
+     * @param {object} params
+     * @param {Fl32_Web_Back_Helper_Cast} params.cast
      */
     constructor(
         {
-            Fl32_Web_Back_Helper_Cast$: cast,
+            cast,
         }
     ) {
         /* eslint-enable jsdoc/require-param-description */
         /**
-         * Create validated DTO for source configuration.
-         *
          * @param {*} [data]
-         * @returns {Dto}
+         * @returns {Fl32_Web_Back_Dto_Source}
          */
         this.create = function (data) {
-            const res = new Dto();
+            const res = new Fl32_Web_Back_Dto_Source();
             if (data) {
                 res.root = cast.string(data.root);
                 res.prefix = cast.string(data.prefix);
                 res.allow = cast.stringArrayMap(data.allow);
                 res.defaults = cast.array(data.defaults, cast.string);
             }
-            return res;
+            return Object.freeze(res);
         };
     }
 }
-
-/**
- * @memberOf Fl32_Web_Back_Dto_Handler_Source
- */
-class Dto {
-    /** @type {string} */
-    root;
-    /** @type {string} */
-    prefix;
-    /** @type {{[key: string]: string[]}} */
-    allow = {};
-    /** @type {string[]} */
-    defaults = [];
-}

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

@@ -0,0 +1,13 @@
+// @ts-check
+
+/**
+ * Enum-like DTO for built-in server transport modes.
+ */
+export default class Fl32_Web_Back_Enum_Server_Type {
+    constructor() {
+        this.HTTP2 = 'http2';
+        this.HTTP = 'http';
+        this.HTTPS = 'https';
+        Object.freeze(this);
+    }
+}

package/src/Back/Enum/Stage.mjs

@@ -0,0 +1,13 @@
+// @ts-check
+
+/**
+ * Enum-like DTO for web request processing stages.
+ */
+export default class Fl32_Web_Back_Enum_Stage {
+    constructor() {
+        this.INIT = 'INIT';
+        this.PROCESS = 'PROCESS';
+        this.FINALIZE = 'FINALIZE';
+        Object.freeze(this);
+    }
+}

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

@@ -0,0 +1,55 @@
+// @ts-check
+
+/**
+ * Logs basic request information at the beginning of the request lifecycle.
+ *
+ * @implements Fl32_Web_Back_Api_Handler
+ */
+export const __deps__ = Object.freeze({
+    logger: 'Fl32_Web_Back_Logger$',
+    dtoInfoFactory: 'Fl32_Web_Back_Dto_Info__Factory$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+});
+
+export default class Fl32_Web_Back_Handler_Pre_Log {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {object} params
+     * @param {Fl32_Web_Back_Logger} params.logger
+     * @param {Fl32_Web_Back_Dto_Info$Factory} params.dtoInfoFactory
+     * @param {Fl32_Web_Back_Enum_Stage} params.STAGE
+     */
+    constructor(
+        {
+            logger,
+            dtoInfoFactory,
+            STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+        // VARS
+        const _info = dtoInfoFactory.create({
+            name: this.constructor.name,
+            stage: STAGE.INIT,
+        });
+
+        // MAIN
+
+        /**
+         * Log request method and URL.
+         *
+         * @param {Fl32_Web_Back_Dto_RequestContext} context
+         * @returns {Promise<void>}
+         */
+        this.handle = async function (context) {
+            logger.debug(`${context.request.method} ${context.request.url}`);
+        };
+
+        /**
+         * Return handler registration info.
+         *
+         * @returns {Fl32_Web_Back_Dto_Info}
+         */
+        this.getRegistrationInfo = () => _info;
+    }
+}

package/src/Back/Handler/Static/A/{Config.js → Config.mjs}

@@ -1,12 +1,19 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    path: 'node_path',
+});
+
 export default class Fl32_Web_Back_Handler_Static_A_Config {
     static DEFAULT_FILES = ['index.html', 'index.htm', 'index.txt'];
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {typeof import('node:path')} path
+     * @param {object} params
+     * @param {Fl32_Web_Node_Path} params.path
      */
     constructor(
         {
-            'node:path': path,
+            path,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */
@@ -14,8 +21,8 @@ export default class Fl32_Web_Back_Handler_Static_A_Config {
         /**
          * Normalize DTO fields into configuration object.
          *
-         * @param {Fl32_Web_Back_Dto_Handler_Source.Dto} dto
-         * @returns {{root:string,prefix:string,allow?:Record<string,string[]>,defaults:string[]}}
+         * @param {Fl32_Web_Back_Dto_Source} dto
+         * @returns {Fl32_Web_Back_Handler_Static_A_Config_Value}
          * @throws {Error} When required fields are missing or invalid.
          */
         this.create = (dto) => {

package/src/Back/Handler/Static/A/{Fallback.js → Fallback.mjs}

@@ -1,13 +1,21 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    fs: 'node_fs',
+    path: 'node_path',
+});
+
 export default class Fl32_Web_Back_Handler_Static_A_Fallback {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {typeof import('node:fs')} fs
-     * @param {typeof import('node:path')} path
+     * @param {object} params
+     * @param {Fl32_Web_Node_Fs} params.fs
+     * @param {Fl32_Web_Node_Path} params.path
      */
     constructor(
         {
-            'node:fs': fs,
-            'node:path': path,
+            fs,
+            path,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */