@flancer32/teq-web 0.3.1 → 0.5.0

package/ai/rules.md

@@ -0,0 +1,41 @@
+# 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.
+- 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,18 +1,8 @@
 {
   "name": "@flancer32/teq-web",
-  "version": "0.3.1",
-  "description": "Node.js web plugin supporting Express and Fastify integration, with built-in server for standalone operation",
+  "version": "0.5.0",
+  "description": "Server-side web request coordination infrastructure for TeqFW modular monolith applications.",
   "type": "module",
-  "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",
@@ -23,26 +13,51 @@
     "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": ">=0.34.0"
+    "@teqfw/di": "^2.0.4"
   },
   "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_PipelineEngine_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/{Defaults.js → Defaults.mjs}

@@ -1,6 +1,11 @@
+// @ts-check
+
 /**
  * Plugin constants (hardcoded configuration) for backend code.
  */
 export default class Fl32_Web_Back_Defaults {
-    PORT = 3000;
+    constructor() {
+        this.PORT = 3000;
+        Object.freeze(this);
+    }
 }

package/src/Back/Dto/Info.mjs

@@ -0,0 +1,66 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Dto_InfoFactoryParams
+ * @property {Fl32_Web_Back_Helper_Cast} cast
+ * @property {Fl32_Web_Back_Enum_Stage} 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 {Fl32_Web_Back_Dto_InfoFactoryParams} params
+     */
+    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/{Handler/Source.js → Source.mjs}

@@ -1,46 +1,49 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    cast: 'Fl32_Web_Back_Helper_Cast$',
+});
+
 /**
- * Factory for file source configuration DTO used by Static handler.
+ * @typedef {object} Fl32_Web_Back_Dto_SourceFactoryParams
+ * @property {Fl32_Web_Back_Helper_Cast} cast
  */
-export default class Fl32_Web_Back_Dto_Handler_Source {
+
+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 {Fl32_Web_Back_Dto_SourceFactoryParams} params
      */
     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,59 @@
+// @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$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_Pre_LogConstructorParams
+ * @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_Pre_Log {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {Fl32_Web_Back_Handler_Pre_LogConstructorParams} params
+     */
+    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_PipelineEngine_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,23 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    path: 'node_path',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_Static_A_ConfigConstructorParams
+ * @property {typeof import('node:path')} 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 {Fl32_Web_Back_Handler_Static_A_ConfigConstructorParams} params
      */
     constructor(
         {
-            'node:path': path,
+            path,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */
@@ -14,7 +25,7 @@ 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
+         * @param {Fl32_Web_Back_Dto_Source} dto
          * @returns {{root:string,prefix:string,allow?:Record<string,string[]>,defaults:string[]}}
          * @throws {Error} When required fields are missing or invalid.
          */

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

@@ -1,13 +1,25 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    fs: 'node_fs',
+    path: 'node_path',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_Static_A_FallbackConstructorParams
+ * @property {typeof import('node:fs')} fs
+ * @property {typeof import('node:path')} 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 {Fl32_Web_Back_Handler_Static_A_FallbackConstructorParams} params
      */
     constructor(
         {
-            'node:fs': fs,
-            'node:path': path,
+            fs,
+            path,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */

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

@@ -1,23 +1,40 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    fs: 'node_fs',
+    http2: 'node_http2',
+    path: 'node_path',
+    logger: 'Fl32_Web_Back_Logger$',
+    helpMime: 'Fl32_Web_Back_Helper_Mime$',
+    resolver: 'Fl32_Web_Back_Handler_Static_A_Resolver$',
+    fallback: 'Fl32_Web_Back_Handler_Static_A_Fallback$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_Static_A_FileServiceConstructorParams
+ * @property {typeof import('node:fs')} fs
+ * @property {typeof import('node:http2')} http2
+ * @property {typeof import('node:path')} path
+ * @property {Fl32_Web_Back_Logger} logger
+ * @property {Fl32_Web_Back_Helper_Mime} helpMime
+ * @property {Fl32_Web_Back_Handler_Static_A_Resolver} resolver
+ * @property {Fl32_Web_Back_Handler_Static_A_Fallback} fallback
+ */
+
 export default class Fl32_Web_Back_Handler_Static_A_FileService {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {typeof import('node:fs')} fs
-     * @param {typeof import('node:http2')} http2
-     * @param {typeof import('node:path')} path
-     * @param {Fl32_Web_Back_Logger} logger
-     * @param {Fl32_Web_Back_Helper_Mime} helpMime
-     * @param {Fl32_Web_Back_Handler_Static_A_Resolver} resolver
-     * @param {Fl32_Web_Back_Handler_Static_A_Fallback} fallback
+     * @param {Fl32_Web_Back_Handler_Static_A_FileServiceConstructorParams} params
      */
     constructor(
         {
-            'node:fs': fs,
-            'node:http2': http2,
-            'node:path': path,
-            Fl32_Web_Back_Logger$: logger,
-            Fl32_Web_Back_Helper_Mime$: helpMime,
-            Fl32_Web_Back_Handler_Static_A_Resolver$: resolver,
-            Fl32_Web_Back_Handler_Static_A_Fallback$: fallback,
+            fs,
+            http2,
+            path,
+            logger,
+            helpMime,
+            resolver,
+            fallback,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */

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

@@ -1,24 +1,36 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    configFactory: 'Fl32_Web_Back_Handler_Static_A_Config$',
+    logger: 'Fl32_Web_Back_Logger$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_Static_A_RegistryConstructorParams
+ * @property {Fl32_Web_Back_Handler_Static_A_Config} configFactory
+ * @property {Fl32_Web_Back_Logger} logger
+ */
+
 export default class Fl32_Web_Back_Handler_Static_A_Registry {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {Fl32_Web_Back_Handler_Static_A_Config} configFactory
-     * @param {Fl32_Web_Back_Logger} logger
+     * @param {Fl32_Web_Back_Handler_Static_A_RegistryConstructorParams} params
      */
     constructor(
         {
-            Fl32_Web_Back_Handler_Static_A_Config$: configFactory,
-            Fl32_Web_Back_Logger$: logger,
+            configFactory,
+            logger,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */
-        /** @type {Fl32_Web_Back_Dto_Handler_Source.Dto[]} */
+        /** @type {Fl32_Web_Back_Dto_Source[]} */
         let _configs = [];
 
         /**
          * Add configurations ensuring unique prefixes.
          * Existing entries are not modified.
          *
-         * @param {Fl32_Web_Back_Dto_Handler_Source.Dto[]} dtoList
+         * @param {Fl32_Web_Back_Dto_Source[]} dtoList
          */
         this.addConfigs = function (dtoList = []) {
             const list = dtoList.map(dto => configFactory.create(dto));

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

@@ -1,12 +1,23 @@
+// @ts-check
+
 /**
  * Enforces allow‐list rules and security checks when resolving
  * a relative URL to an absolute filesystem path under a given root.
  */
+export const __deps__ = Object.freeze({
+    path: 'node_path',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_Handler_Static_A_ResolverConstructorParams
+ * @property {typeof import('node:path')} path
+ */
+
 export default class Fl32_Web_Back_Handler_Static_A_Resolver {
     /**
-     * @param {typeof import('node:path')} path
+     * @param {Fl32_Web_Back_Handler_Static_A_ResolverConstructorParams} params
      */
-    constructor({'node:path': path}) {
+    constructor({path}) {
         /**
          * Resolve a filesystem path for given config and relative URL part.
          * Applies allow rules and prevents path traversal.

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;
+    }
+}