@flancer32/teq-web 0.2.0 → 0.3.1

package/AGENTS.md

@@ -0,0 +1,101 @@
+# 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/CHANGELOG.md

@@ -1,11 +1,29 @@
 # Changelog
 
+## [0.3.1] - 2025-08-21
+
+### Added
+- Added TeqFW descriptor to define package namespace for @teqfw/core.
+
+## [0.3.0] - 2025-06-26
+
+### Added
+- Generalized NPM handler into a Source handler with DTO-based configuration.
+- Unit tests for the dispatcher and built-in handlers.
+
+### Changed
+- Static handler refactored into modular components with before/after ordering.
+
+### Fixed
+- Improved validation messages for static handler configuration.
+- File service now reports specific filesystem errors.
+
 ## [0.2.0] - 2025-06-21
 
 ### Added
-- Integration test covering NPM handler with the built-in server.
-- Built-in NPM handler for serving files from `node_modules`.
-- JSDoc examples for NPM handler initialization.
+- Integration test covering static file serving from `node_modules`.
+- Static handler can serve files from `node_modules` via `Handler_Source`.
+- JSDoc examples for initializing the static handler with a `Handler_Source` DTO.
 
 ## [0.1.0] - 2025-06-11
 

package/README.md

@@ -62,6 +62,11 @@ This example shows how to create a minimal application that:
 * Registers two handlers: a logger and a static file server
 * Starts a secure HTTPS server using built-in components
 
+The static handler reads from one or more **sources** described by the
+`Handler_Source` DTO. To expose selected files from `node_modules`, create a
+source with `root: 'node_modules'` and pass it to `Handler_Static` during
+initialization.
+
 ```js
 import Container from '@teqfw/di';
 import {readFileSync} from 'node:fs';
@@ -81,20 +86,22 @@ resolver.addNamespaceRoot('Fl32_Web_', './node_modules/@flancer32/teq-web/src');
 
 // Get and configure built-in handlers
 const logHandler = await container.get('Fl32_Web_Back_Handler_Pre_Log$');
-const npmHandler = await container.get('Fl32_Web_Back_Handler_Npm$');
 const staticHandler = await container.get('Fl32_Web_Back_Handler_Static$');
-await npmHandler.init({
+const SourceCfg = await container.get('Fl32_Web_Back_Dto_Handler_Source$');
+const srcNpm = SourceCfg.create({
+    root: 'node_modules',
+    prefix: '/node_modules/',
     allow: {
         vue: ['dist/vue.global.prod.js'],
         '@teqfw/di': ['src/Container.js'],
     }
 });
-await staticHandler.init({rootPath: webRoot});
+const srcWeb = SourceCfg.create({ root: webRoot, prefix: '/' });
+await staticHandler.init({sources: [srcNpm, srcWeb]});
 
 // Register handlers
 const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
 dispatcher.addHandler(logHandler);
-dispatcher.addHandler(npmHandler);
 dispatcher.addHandler(staticHandler);
 
 // Create and start the server
@@ -113,8 +120,7 @@ await server.start({
 This will start an HTTPS server on port `3443` with:
 
 * `Fl32_Web_Back_Handler_Pre_Log` logging each request method and URL;
-* `Fl32_Web_Back_Handler_Npm` serving allowed files from `node_modules`;
-* `Fl32_Web_Back_Handler_Static` serving files from the `/web` folder.
+* `Fl32_Web_Back_Handler_Static` serving files from `node_modules` and the `/web` folder.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flancer32/teq-web",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Node.js web plugin supporting Express and Fastify integration, with built-in server for standalone operation",
   "type": "module",
   "keywords": [

package/src/AGENTS.md

@@ -0,0 +1,108 @@
+# 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/Dto/Handler/Source.js

@@ -0,0 +1,46 @@
+/**
+ * Factory for file source configuration DTO used by Static handler.
+ */
+export default class Fl32_Web_Back_Dto_Handler_Source {
+    /* eslint-disable jsdoc/require-param-description */
+    /**
+     * @param {Fl32_Web_Back_Helper_Cast} cast
+     */
+    constructor(
+        {
+            Fl32_Web_Back_Helper_Cast$: cast,
+        }
+    ) {
+        /* eslint-enable jsdoc/require-param-description */
+        /**
+         * Create validated DTO for source configuration.
+         *
+         * @param {*} [data]
+         * @returns {Dto}
+         */
+        this.create = function (data) {
+            const res = new Dto();
+            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;
+        };
+    }
+}
+
+/**
+ * @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/Handler/Static/A/Config.js

@@ -0,0 +1,58 @@
+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
+     */
+    constructor(
+        {
+            'node:path': path,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+
+        /**
+         * 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[]}}
+         * @throws {Error} When required fields are missing or invalid.
+         */
+        this.create = (dto) => {
+            if (!dto || typeof dto.root !== 'string') {
+                throw new Error("Field 'root' must be a string");
+            }
+            let prefix = dto.prefix ?? '/';
+            if (typeof prefix !== 'string') {
+                throw new Error("Field 'prefix' must be a string");
+            }
+            if (!prefix.endsWith('/')) prefix += '/';
+
+            const root = path.resolve(dto.root);
+
+            let allow;
+            if (dto.allow !== undefined) {
+                if (typeof dto.allow !== 'object' || dto.allow === null || Array.isArray(dto.allow)) {
+                    throw new Error("Field 'allow' must be an object");
+                }
+                for (const [k, arr] of Object.entries(dto.allow)) {
+                    if (!Array.isArray(arr) || arr.some(v => typeof v !== 'string')) {
+                        throw new Error(`Field 'allow.${k}' must be an array of strings`);
+                    }
+                }
+                allow = dto.allow;
+            }
+
+            let defaults = dto.defaults;
+            if (defaults !== undefined && defaults.length) {
+                if (!Array.isArray(defaults) || defaults.some(v => typeof v !== 'string')) {
+                    throw new Error("Field 'defaults' must be an array of strings");
+                }
+            } else {
+                defaults = Fl32_Web_Back_Handler_Static_A_Config.DEFAULT_FILES;
+            }
+
+            return {root, prefix, allow, defaults};
+        };
+    }
+}

package/src/Back/Handler/Static/A/Fallback.js

@@ -0,0 +1,39 @@
+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
+     */
+    constructor(
+        {
+            'node:fs': fs,
+            'node:path': path,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+
+        /**
+         * Apply default index fallback for directories.
+         *
+         * @param {string} fsPath
+         * @param {string[]} defaults
+         * @returns {Promise<string|null>} Path to existing file or null.
+         */
+        this.apply = async (fsPath, defaults) => {
+            let stat;
+            try { stat = await fs.promises.stat(fsPath); } catch { return null; }
+
+            if (stat.isDirectory()) {
+                for (const file of defaults) {
+                    const candidate = path.join(fsPath, file);
+                    try {
+                        const s = await fs.promises.stat(candidate);
+                        if (s.isFile()) return candidate;
+                    } catch { /* ignore */ }
+                }
+                return null;
+            }
+            return stat.isFile() ? fsPath : null;
+        };
+    }
+}

package/src/Back/Handler/Static/A/FileService.js

@@ -0,0 +1,69 @@
+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
+     */
+    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,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+        const {constants: H2} = http2;
+
+        /**
+         * Serve a file for given config and relative path.
+         *
+         * @param {*} config
+         * @param {string} rel
+         * @param {*} req
+         * @param {*} res
+         * @returns {Promise<boolean>} true if served
+         */
+        this.serve = async (config, rel, req, res) => {
+            let fsPath;
+            try {
+                fsPath = resolver.resolve(config, rel);
+                if (!fsPath) return false;
+
+                fsPath = await fallback.apply(fsPath, config.defaults);
+                if (!fsPath) return false;
+
+                const stat = await fs.promises.stat(fsPath);
+                if (!stat.isFile()) return false;
+
+                const stream = fs.createReadStream(fsPath);
+                const ext = path.extname(fsPath).toLowerCase();
+                const headers = {
+                    [H2.HTTP2_HEADER_CONTENT_LENGTH]: stat.size,
+                    [H2.HTTP2_HEADER_CONTENT_TYPE]: helpMime.getByExt(ext),
+                    [H2.HTTP2_HEADER_LAST_MODIFIED]: stat.mtime.toUTCString(),
+                };
+                res.writeHead(H2.HTTP_STATUS_OK, headers);
+                stream.pipe(res);
+                return true;
+            } catch (e) {
+                if (e?.code === 'ENOENT') {
+                    logger.info(`File not found: ${fsPath}`);
+                } else if (e?.code === 'EACCES' || e?.code === 'EPERM') {
+                    logger.warn(`Access denied: ${fsPath}`);
+                } else {
+                    logger.exception(e);
+                }
+                return false;
+            }
+        };
+    }
+}

package/src/Back/Handler/Static/A/Registry.js

@@ -0,0 +1,52 @@
+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
+     */
+    constructor(
+        {
+            Fl32_Web_Back_Handler_Static_A_Config$: configFactory,
+            Fl32_Web_Back_Logger$: logger,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+        /** @type {Fl32_Web_Back_Dto_Handler_Source.Dto[]} */
+        let _configs = [];
+
+        /**
+         * Add configurations ensuring unique prefixes.
+         * Existing entries are not modified.
+         *
+         * @param {Fl32_Web_Back_Dto_Handler_Source.Dto[]} dtoList
+         */
+        this.addConfigs = function (dtoList = []) {
+            const list = dtoList.map(dto => configFactory.create(dto));
+            for (const cfg of list) {
+                if (!_configs.some(c => c.prefix === cfg.prefix)) {
+                    _configs.push(cfg);
+                } else {
+                    logger.warn(`Static config with prefix ${cfg.prefix} already exists`);
+                }
+            }
+            _configs.sort((a, b) => b.prefix.length - a.prefix.length);
+        };
+
+
+        /**
+         * Find configuration by matching URL prefix.
+         *
+         * @param {string} url
+         * @returns {{config: *, rel: string}|null}
+         */
+        this.find = function (url) {
+            for (const cfg of _configs) {
+                if (url.startsWith(cfg.prefix)) {
+                    const rel = url.slice(cfg.prefix.length);
+                    return {config: cfg, rel};
+                }
+            }
+            return null;
+        };
+    }
+}

package/src/Back/Handler/Static/A/Resolver.js

@@ -0,0 +1,83 @@
+/**
+ * Enforces allow‐list rules and security checks when resolving
+ * a relative URL to an absolute filesystem path under a given root.
+ */
+export default class Fl32_Web_Back_Handler_Static_A_Resolver {
+    /**
+     * @param {typeof import('node:path')} path
+     */
+    constructor({'node:path': path}) {
+        /**
+         * Resolve a filesystem path for given config and relative URL part.
+         * Applies allow rules and prevents path traversal.
+         *
+         * @param {{root: string, prefix: string, allow?: Record<string,string[]>}} config
+         * @param {string} rel
+         * @returns {string|null}
+         * @throws {Error} On traversal or absolute rel paths.
+         */
+        this.resolve = (config, rel) => {
+            // disallow path‐traversal or absolute rel
+            if (rel.includes('..') || path.isAbsolute(rel)) {
+                throw new Error('Static access denied');
+            }
+
+            let pkgName;
+            let subPath = '';
+
+            if (!config.allow) {
+                let fsPath = path.resolve(config.root, rel);
+                if (/[\\/]$/.test(fsPath) && fsPath.length > 1) {
+                    fsPath = fsPath.replace(/[\\/]+$/, '');
+                }
+                if (!fsPath.startsWith(config.root)) {
+                    throw new Error('Resolved path is outside the root');
+                }
+                return fsPath;
+            }
+
+            // root‐level allow: '.' rules permit any rel under root
+            if (config.allow?.['.'] != null) {
+                pkgName = '.';
+                subPath = rel;
+            } else if (config.allow) {
+                for (const key of Object.keys(config.allow)) {
+                    if (rel === key || rel.startsWith(`${key}/`)) {
+                        pkgName = key;
+                        const offset = key.length + (rel[key.length] === '/' ? 1 : 0);
+                        subPath = rel.slice(offset);
+                        break;
+                    }
+                }
+            }
+
+            if (!pkgName) {
+                return null;
+            }
+
+            const rules = config.allow[pkgName] || [];
+            let allowed = rules.includes('.');
+            if (!allowed) {
+                for (const rule of rules) {
+                    if (subPath === rule || subPath.startsWith(`${rule}/`)) {
+                        allowed = true;
+                        break;
+                    }
+                }
+            }
+            if (!allowed) {
+                return null;
+            }
+
+            let fsPath = path.resolve(config.root, rel);
+            if (/[\\/]$/.test(fsPath) && fsPath.length > 1) {
+                fsPath = fsPath.replace(/[\\/]+$/, '');
+            }
+            if (!fsPath.startsWith(config.root)) {
+                throw new Error('Resolved path is outside the root');
+            }
+
+            return fsPath;
+        };
+    }
+}