@flancer32/teq-web 0.3.1 → 0.5.0

package/src/Back/{Server.js → Server.mjs}

@@ -1,35 +1,47 @@
+// @ts-check
+
 /**
  * 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.
+ * Handles incoming requests and delegates them to the Pipeline Engine.
  */
+export const __deps__ = Object.freeze({
+    http: 'node_http',
+    http2: 'node_http2',
+    DEF: 'Fl32_Web_Back_Defaults$',
+    logger: 'Fl32_Web_Back_Logger$',
+    pipelineEngine: 'Fl32_Web_Back_PipelineEngine$',
+    SERVER_TYPE: 'Fl32_Web_Back_Enum_Server_Type$',
+});
+
+/**
+ * @typedef {object} Fl32_Web_Back_ServerConstructorParams
+ * @property {typeof import('node:http')} http
+ * @property {typeof import('node:http2')} http2
+ * @property {import('./Defaults.mjs').default} DEF
+ * @property {Fl32_Web_Back_Logger} logger
+ * @property {Fl32_Web_Back_PipelineEngine} pipelineEngine
+ * @property {Fl32_Web_Back_Enum_Server_Type} SERVER_TYPE
+ */
+
 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
+     * @param {Fl32_Web_Back_ServerConstructorParams} deps
      */
     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,
+            http,
+            http2,
+            DEF,
+            logger,
+            pipelineEngine,
+            SERVER_TYPE,
         }
     ) {
         /* eslint-enable jsdoc/require-param-description,jsdoc/check-param-names */
         // VARS
-        const {createServer} = http;
-        const {createServer: createServerH2, createSecureServer} = http2;
+        const { createServer } = http;
+        const { createServer: createServerH2, createSecureServer } = http2;
         /** @type {module:http.Server} */
         let _instance;
 
@@ -41,12 +53,11 @@ export default class Fl32_Web_Back_Server {
 
         /**
          * Starts the server with optional configuration.
-         * @param {Fl32_Web_Back_Server_Config.Dto} [cfg] - Server configuration
+         * @param {Fl32_Web_Back_Server_Config} [cfg]
          * @returns {Promise<void>}
          */
         this.start = async function (cfg) {
-            // order handlers in the dispatcher
-            dispatcher.orderHandlers();
+            pipelineEngine.lockHandlers();
             // create server
             const port = cfg?.port ?? DEF.PORT;
             const type = cfg?.type ?? SERVER_TYPE.HTTP;
@@ -69,7 +80,7 @@ export default class Fl32_Web_Back_Server {
                 throw new Error(`Server type '${type}' is not supported`);
             }
 
-            _instance.on('request', dispatcher.onEventRequest);
+            _instance.on('request', pipelineEngine.handleRequest);
             _instance.listen(port);
         };
 
@@ -89,4 +100,4 @@ export default class Fl32_Web_Back_Server {
             }
         };
     }
-}
+}

package/types.d.ts

@@ -0,0 +1,30 @@
+declare global {
+  type Fl32_Web_Back_Api_Handler = import("./src/Back/Api/Handler.mjs").default;
+  type Fl32_Web_Back_Defaults = import("./src/Back/Defaults.mjs").default;
+  type Fl32_Web_Back_Dto_Info = import("./src/Back/Dto/Info.mjs").default;
+  type Fl32_Web_Back_Dto_Info$Factory = import("./src/Back/Dto/Info.mjs").Factory;
+  type Fl32_Web_Back_Dto_Source = import("./src/Back/Dto/Source.mjs").default;
+  type Fl32_Web_Back_Dto_Source$Factory = import("./src/Back/Dto/Source.mjs").Factory;
+  type Fl32_Web_Back_Enum_Server_Type = import("./src/Back/Enum/Server/Type.mjs").default;
+  type Fl32_Web_Back_Enum_Stage = import("./src/Back/Enum/Stage.mjs").default;
+  type Fl32_Web_Back_Handler_Pre_Log = import("./src/Back/Handler/Pre/Log.mjs").default;
+  type Fl32_Web_Back_Handler_Static = import("./src/Back/Handler/Static.mjs").default;
+  type Fl32_Web_Back_Handler_Static_A_Config = import("./src/Back/Handler/Static/A/Config.mjs").default;
+  type Fl32_Web_Back_Handler_Static_A_Fallback = import("./src/Back/Handler/Static/A/Fallback.mjs").default;
+  type Fl32_Web_Back_Handler_Static_A_FileService = import("./src/Back/Handler/Static/A/FileService.mjs").default;
+  type Fl32_Web_Back_Handler_Static_A_Registry = import("./src/Back/Handler/Static/A/Registry.mjs").default;
+  type Fl32_Web_Back_Handler_Static_A_Resolver = import("./src/Back/Handler/Static/A/Resolver.mjs").default;
+  type Fl32_Web_Back_Helper_Cast = import("./src/Back/Helper/Cast.mjs").default;
+  type Fl32_Web_Back_Helper_Mime = import("./src/Back/Helper/Mime.mjs").default;
+  type Fl32_Web_Back_Helper_Order_Kahn = import("./src/Back/Helper/Order/Kahn.mjs").default;
+  type Fl32_Web_Back_Helper_Respond = import("./src/Back/Helper/Respond.mjs").default;
+  type Fl32_Web_Back_Logger = import("./src/Back/Logger.mjs").default;
+  type Fl32_Web_Back_PipelineEngine = import("./src/Back/PipelineEngine.mjs").default;
+  type Fl32_Web_Back_Server = import("./src/Back/Server.mjs").default;
+  type Fl32_Web_Back_Server_Config = import("./src/Back/Server/Config.mjs").default;
+  type Fl32_Web_Back_Server_Config$Factory = import("./src/Back/Server/Config.mjs").Factory;
+  type Fl32_Web_Back_Server_Config_Tls = import("./src/Back/Server/Config/Tls.mjs").default;
+  type Fl32_Web_Back_Server_Config_Tls$Factory = import("./src/Back/Server/Config/Tls.mjs").Factory;
+}
+
+export {};

package/.github/workflows/npm-publish.yml

@@ -1,48 +0,0 @@
-name: npm publication
-
-on:
-  workflow_dispatch:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      # Checkout repository code
-      - uses: actions/checkout@v4
-
-      # Setup Node.js environment
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      # Install dependencies using package-lock.json
-      - run: npm ci
-
-      # Run unit tests
-      - run: npm run test:unit
-
-      # Run acceptance tests
-      - run: npm run test:accept
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      # Checkout repository code again for a separate job
-      - uses: actions/checkout@v4
-
-      # Setup Node.js and configure npm registry
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-
-      # Install dependencies again
-      - run: npm ci
-
-      # Publish package to npm registry with authentication token
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.npm_token }}

package/AGENTS.md

@@ -1,101 +0,0 @@
-# AGENTS.md
-
-## Project: @flancer32/teq-web
-
-This project implements a request dispatcher plugin for Tequila Framework (TeqFW).  
-The plugin provides a multi-stage handler system (`pre`, `process`, `post`) and integrates directly with Node.js servers (`http`, `http2`, `https`) without external dependencies.
-
----
-
-## Project Structure
-
-| Directory                  | Description                                                                |
-|----------------------------|----------------------------------------------------------------------------|
-| `/src/Back/Api/Handler.js` | Interface for all request handlers.                                        |
-| `/src/Back/Dispatcher.js`  | Core dispatcher that orchestrates handler execution.                       |
-| `/src/Back/Handler/`       | Built-in request handlers (`Pre_Log`, `Static`, `Source`, etc).            |
-| `/src/Back/Helper/`        | Internal helpers (`Mime`, `Respond`, `Order_Kahn`, etc).                   |
-| `/src/Back/Dto/`           | DTO factories used to pass typed configuration and metadata.               |
-| `/src/Back/Server.js`      | Standalone HTTP(S) server implementation using built-in Node.js libraries. |
-
----
-
-## Execution Agents
-
-### Dispatcher
-
-- File: `Back/Dispatcher.js`
-- Role: Core runtime coordinator for HTTP requests.
-- Interface: uses `Fl32_Web_Back_Api_Handler` and topological ordering via `Order_Kahn`.
-
-### Server
-
-- File: `Back/Server.js`
-- Role: HTTP/1.1, HTTP/2, or HTTPS web server.
-- Launches `Dispatcher.onEventRequest()` on each request.
-
-### Handlers
-
-- Files: `Back/Handler/Pre_Log.js`, `.../Static.js`, `.../Source.js`
-- Role: Modular request processors, registered via `Dispatcher.addHandler()`.
-- Lifecycle: Initialized once, executed per request by dispatcher.
-
----
-
-## Code Style
-
-- Language: Modern JavaScript (ES2022+).
-- No static imports (uses DI-based module resolution).
-- All comments and messages must be in English (strict rule).
-- File naming: PascalCase with dot-separated exports, e.g. `Fl32_Web_Back_Enum_Stage`.
-
----
-
-## Testing
-
-- Unit tests must be provided for all runtime agents (Dispatcher, Handlers).
-- Test framework: `node:test`.
-- Mocks: registered via custom `buildTestContainer()` helper.
-- Location: colocated or `/test/` folder depending on iteration.
-
----
-
-## Build & Execution
-
-- This project is a TeqFW plugin. It is not compiled or bundled.
-- Executed in-place by Tequila runtime.
-- Requires a DI container to resolve dependencies at runtime.
-
----
-
-## Contribution Rules (for AI Agents)
-
-- When creating new Handlers, they **must** implement `Fl32_Web_Back_Api_Handler` and provide `getRegistrationInfo()`.
-- Handlers must be registered with `Dispatcher.addHandler()` and ordered with `orderHandlers()`.
-- All request-handling code **must** call `respond.isWritable(res)` before sending a response.
-- Do not modify existing dispatcher logic directly — create a new handler or helper instead.
-
----
-
-## Conventions for AI Tools (Codex, etc.)
-
-- Start by inspecting `Dispatcher.js` and `Handler/` folder to locate runtime behavior.
-- DTOs are created via `*.create(data)` methods and used to validate configs.
-- Use `getRegistrationInfo().stage` to determine when a handler runs (`pre`, `process`, `post`).
-- Prefer composition over inheritance. Avoid using `extends`.
-- Respect topological order defined via `before`/`after`.
-
----
-
-## CI/Automation
-
-- No CI defined yet. Future CI will:
-    - Validate handler registration structure.
-    - Enforce code style and comment policy.
-    - Run full test suite before merge.
-
----
-
-## License
-
-This project is licensed under the Apache-2.0 license.

package/eslint.config.js

@@ -1,37 +0,0 @@
-import js from '@eslint/js';
-import jsdoc from 'eslint-plugin-jsdoc';
-import {defineConfig} from 'eslint/config';
-import globals from 'globals';
-
-export default defineConfig([
-    {
-        files: ['**/*.js', '**/*.mjs'],
-        plugins: {
-            js,
-            jsdoc,
-        },
-        extends: ['js/recommended'],
-        languageOptions: {
-            ecmaVersion: 'latest',
-            sourceType: 'module',
-            globals: {
-                ...globals.browser,
-                ...globals.node,
-                myCustomGlobal: 'readonly',
-            },
-        },
-        rules: {
-            // Recommended ESLint rules
-            'no-unused-vars': 'warn',
-            'no-console': 'off',
-            'eqeqeq': 'error',
-            'curly': ['error', 'multi-line'],
-            'semi': ['error', 'always'],
-            // Your JSDoc rules
-            'jsdoc/check-alignment': 'error',
-            'jsdoc/check-param-names': 'error',
-            'jsdoc/check-types': 'error',
-            'jsdoc/require-param-description': 'warn',
-        },
-    },
-]);

package/src/AGENTS.md

@@ -1,108 +0,0 @@
-# AI Agents Configuration for Source Directory
-
-This document defines **long-term, project-agnostic** conventions that AI agents must follow when reading, creating, refactoring, or testing code under any `src/` directory. These guidelines are **permanent** and apply to **all** tasks in this area.
-
----
-
-## 1. Directory & File Organization
-
-* **AZ-structuring**
-
-    * **A-struct**: decompose a single “root” module into its private implementation parts under an `A/` subfolder.
-
-      ```text
-      src/Feature/Component.js
-      src/Feature/Component/A/Part1.js
-      src/Feature/Component/A/Part2.js
-      ```
-
-      Files under `A/` are private to their parent.
-    * **Z-struct**: helper modules whose changes do not affect siblings live under a `Z/` subfolder.
-
-* **Visibility boundaries**: anything **outside** `A/` or `Z/` is public API.
-
-* **Role → Feature layering**
-
-    * First level: by architectural layer (e.g. `Back/`, `Front/`, `Shared/`).
-    * Second level: by business feature or component.
-
-* **Mirror in tests**
-
-    * For every `src/.../X.js` there must be a matching `test/unit/.../X.test.mjs` with the same relative path and filename.
-
----
-
-## 2. Class Naming (FQN)
-
-* Map file path to fully qualified class name (FQN). Example:
-
-  ```text
-  src/Back/Handler/Static/A/Config.js => class Back_Handler_Static_A_Config
-  ```
-
----
-
-## 3. Dependency Injection, `this` & Closures
-
-* **DI Container**
-
-    * Inject all external services (file system, path, network, helpers, loggers, factories, enums) via a DI container.
-* **Private state via closure**
-
-    * Do **not** assign injected dependencies to `this`.
-    * Capture each in a `const` inside the constructor and expose only public methods.
-
-```js
-class Example {
-    constructor({helperService, logger}) {
-        this.handle = (req, res) => {
-            if (!helperService.isWritable(res)) return false;
-            logger.info('Processing');
-            return true;
-        };
-    }
-}
-```
-
----
-
-## 4. Comments & Annotations
-
-* **Language**: all comments and JSDoc must be in **English**.
-* **JSDoc**: use `@param {Type}` and `@returns {Type}` on every public method.
-* **Class annotation**: annotate all classes with a JSDoc `@class` tag and description.
-
----
-
-## 5. Error Handling
-
-* **Module-level**
-
-    * Do **not** catch all exceptions in each module.
-    * Catch only **expected, domain-specific** errors when a meaningful fallback exists.
-* **Top-level handler**
-
-    * Wrap the entire pipeline in a single `try/catch` at the entry point.
-    * In that catch, use `logger.exception(error)` and return a safe default (`false`, `null`, or `[]`).
-
----
-
-## 6. Testing Conventions
-
-Refer to the [AI Agent Unit Testing Instructions](../test/unit/AGENTS.md) for project-specific testing guidelines.
-
----
-
-## 7. Ongoing Responsibilities
-
-AI agents must always:
-
-1. **Enforce AZ-structuring** when adding or refactoring code.
-2. **Preserve FQN mapping** between file paths and class names.
-3. **Use DI + closures**—never attach injected services to `this`.
-4. **Write English JSDoc** for every new or modified public API, including `@class` on all classes.
-5. **Catch and log errors** at the top level; handle known cases locally.
-6. **Generate or update unit tests** with full coverage for every behavior change (see unit testing guidelines).
-7. **Maintain test-source mirror** so no source file exists without a corresponding test.
-
-These policies are **permanent** and must be validated on every code change.

package/src/Back/Api/Handler.js

@@ -1,26 +0,0 @@
-/**
- * Interface for web request handlers used by the dispatcher in this plugin.
- * Defines the structure and behavior of a handler.
- *
- * @interface
- */
-export default class Fl32_Web_Back_Api_Handler {
-    /* eslint-disable no-unused-vars */
-    /**
-     * Handles the incoming web request.
-     * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req - The incoming HTTP request object.
-     * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res - The HTTP response object.
-     * @returns {Promise<boolean>} - Returns true if the request was handled, false otherwise.
-     */
-    async handle(req, res) {
-        throw new Error('Method not implemented');
-    }
-
-    /**
-     * Provides metadata for dispatcher registration.
-     * @returns {Fl32_Web_Back_Dto_Handler_Info.Dto}
-     */
-    getRegistrationInfo() {
-        throw new Error('Method not implemented');
-    }
-}

package/src/Back/Dispatcher.js

@@ -1,115 +0,0 @@
-/**
- * Dispatcher for HTTP(S) requests with three-stage handler execution: pre, process, post.
- *
- * Handlers are registered via `addHandler()` and activated by `orderHandlers()`.
- * On each request, pre-handlers run first, then process-handlers (until one returns true),
- * and finally post-handlers are always executed.
- *
- * If no process handler responds, a 404 is sent. If one throws, a 500 is returned.
- */
-export default class Fl32_Web_Back_Dispatcher {
-    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
-    /**
-     * @param {Fl32_Web_Back_Logger} logger
-     * @param {Fl32_Web_Back_Helper_Respond} respond
-     * @param {Fl32_Web_Back_Helper_Order_Kahn} helpOrder
-     * @param {typeof Fl32_Web_Back_Enum_Stage} STAGE
-     */
-    constructor(
-        {
-            Fl32_Web_Back_Logger$: logger,
-            Fl32_Web_Back_Helper_Respond$: respond,
-            Fl32_Web_Back_Helper_Order_Kahn$: helpOrder,
-            Fl32_Web_Back_Enum_Stage$: STAGE,
-        }
-    ) {
-        /* eslint-enable jsdoc/check-param-names */
-        // VARS
-        /** @type {Map<string, Fl32_Web_Back_Api_Handler>} */
-        const _handlers = new Map();
-
-        /** @type {Fl32_Web_Back_Api_Handler[]} */
-        let _pre = [], _process = [], _post = [];
-
-        // MAIN
-
-        /**
-         * Registers a handler. Requires a unique name and stage.
-         *
-         * @param {Fl32_Web_Back_Api_Handler} handler
-         */
-        this.addHandler = function (handler) {
-            const info = handler.getRegistrationInfo();
-            _handlers.set(info.name, handler);
-        };
-
-        /**
-         * Executes registered handlers for one HTTP request.
-         *
-         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
-         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
-         * @returns {Promise<void>}
-         */
-        this.onEventRequest = async function (req, res) {
-            try {
-                // Execute all pre-handlers (errors are isolated)
-                for (const h of _pre) {
-                    try {
-                        await h.handle(req, res);
-                    } catch (e) {
-                        logger.exception(e);
-                    }
-                }
-
-                // Execute process-handlers (stop at first successful)
-                let handled = false;
-                for (const h of _process) {
-                    try {
-                        handled = await h.handle(req, res);
-                        if (handled) break;
-                    } catch (e) {
-                        logger.exception(e);
-                        respond.code500_InternalServerError({res, body: e?.message});
-                        break;
-                    }
-                }
-
-                // If not handled at all and no error occurred
-                if (respond.isWritable(res)) {
-                    logger.error(`404 Not Found: ${req.url}`);
-                    respond.code404_NotFound({res});
-                }
-            } finally {
-                // Always run all post-handlers (errors are isolated)
-                for (const h of _post) {
-                    try {
-                        await h.handle(req, res);
-                    } catch (e) {
-                        logger.exception(e);
-                    }
-                }
-            }
-        };
-
-        /**
-         * Sorts registered handlers by stage.
-         */
-        this.orderHandlers = function () {
-            const pre = [], process = [], post = [];
-
-            for (const handler of _handlers.values()) {
-                const dto = handler.getRegistrationInfo();
-                if (dto.stage === STAGE.PRE) {
-                    pre.push(handler);
-                } else if (dto.stage === STAGE.PROCESS) {
-                    process.push(handler);
-                } else if (dto.stage === STAGE.POST) post.push(handler);
-            }
-
-            _pre = helpOrder.sort(pre);
-            _process = helpOrder.sort(process);
-            _post = helpOrder.sort(post);
-        };
-    }
-
-}

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;