@flancer32/teq-web 0.1.0 → 0.3.0

package/src/Back/Handler/Static.js

@@ -1,137 +1,61 @@
 /**
- * Serves static files from a configured root directory.
- * Prevents directory traversal and streams file content to the response.
+ * Universal file handler serving files from multiple sources using helper modules.
  *
  * @implements Fl32_Web_Back_Api_Handler
  */
 export default class Fl32_Web_Back_Handler_Static {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {typeof import('node:fs')} fs - Node.js file system module.
-     * @param {typeof import('node:http2')} http2
-     * @param {typeof import('node:path')} path - Node.js path module.
-     * @param {Fl32_Web_Back_Logger} logger - Logger instance.
-     * @param {Fl32_Web_Back_Helper_Mime} helpMime - MIME helper for content type resolution.
-     * @param {Fl32_Web_Back_Helper_Respond} respond - Response helper with status utilities.
-     * @param {Fl32_Web_Back_Dto_Handler_Info} dtoInfo - DTO factory for handler registration.
-     * @param {typeof Fl32_Web_Back_Enum_Stage} STAGE - Enum of handler stages.
+     * @param {Fl32_Web_Back_Handler_Static_A_Registry} registry
+     * @param {Fl32_Web_Back_Handler_Static_A_FileService} fileService
+     * @param {Fl32_Web_Back_Helper_Respond} respond
+     * @param {Fl32_Web_Back_Logger} logger
+     * @param {Fl32_Web_Back_Dto_Handler_Info} dtoInfo
+     * @param {typeof Fl32_Web_Back_Enum_Stage} STAGE
      */
     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_Registry$: registry,
+            Fl32_Web_Back_Handler_Static_A_FileService$: fileService,
             Fl32_Web_Back_Helper_Respond$: respond,
+            Fl32_Web_Back_Logger$: logger,
             Fl32_Web_Back_Dto_Handler_Info$: dtoInfo,
             Fl32_Web_Back_Enum_Stage$: STAGE,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */
-        // VARS
-        const {promises: fsp} = fs;
-        const {constants: H2} = http2;
-        const {
-            HTTP2_HEADER_CONTENT_LENGTH,
-            HTTP2_HEADER_CONTENT_TYPE,
-            HTTP2_HEADER_LAST_MODIFIED,
-            HTTP_STATUS_OK,
-        } = H2;
 
-        /**
-         * Handler registration info.
-         * @type {Fl32_Web_Back_Dto_Handler_Info.Dto}
-         */
         const _info = dtoInfo.create();
         _info.name = this.constructor.name;
         _info.stage = STAGE.PROCESS;
         Object.freeze(_info);
 
         /**
-         * Root directory for static files.
-         * @type {string}
-         */
-        let _root;
-
-        /**
-         * Default filenames to try when a path is a directory.
-         * @type {string[]}
-         */
-        const _defaultFiles = ['index.html', 'index.htm', 'index.txt'];
-
-
-        /**
-         * Handles the incoming request by attempting to serve a static file.
+         * Initialize registry with provided sources.
          *
-         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req - HTTP request object.
-         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res - HTTP response object.
-         * @returns {Promise<boolean>} - True if the file was served, false otherwise.
+         * @param {{sources: Fl32_Web_Back_Dto_Handler_Source.Dto[]}} params
+         * @returns {Promise<void>}
          */
-        this.handle = async function (req, res) {
-            if (!respond.isWritable(res)) return false;
-
-            try {
-                const urlPath = decodeURIComponent(req.url.split('?')[0]);
-                let fsPath = path.resolve(_root, '.' + urlPath);
-
-                if (!fsPath.startsWith(_root)) return false;
-
-                let stat;
-                try {
-                    stat = await fsp.stat(fsPath);
-                } catch {
-                    return false;
-                }
-
-                // If a path is a directory — try default files
-                if (stat.isDirectory()) {
-                    for (const file of _defaultFiles) {
-                        const candidate = path.join(fsPath, file);
-                        try {
-                            const s = await fsp.stat(candidate);
-                            if (s.isFile()) {
-                                fsPath = candidate;
-                                stat = s;
-                                break;
-                            }
-                        } catch {
-                            // ignore and continue
-                        }
-                    }
-                    if (!stat.isFile()) return false;
-                }
-
-                const stream = fs.createReadStream(fsPath);
-                const ext = path.extname(fsPath).toLowerCase();
-                const headers = {
-                    [HTTP2_HEADER_CONTENT_LENGTH]: stat.size,
-                    [HTTP2_HEADER_CONTENT_TYPE]: helpMime.getByExt(ext),
-                    [HTTP2_HEADER_LAST_MODIFIED]: stat.mtime.toUTCString(),
-                };
-                res.writeHead(HTTP_STATUS_OK, headers);
-                stream.pipe(res);
-                return true;
-            } catch (e) {
-                logger.exception(e);
-                return false;
-            }
+        this.init = async ({sources = []} = {}) => {
+            registry.addConfigs(sources);
         };
 
         /**
-         * Initializes the handler with the root directory.
+         * Attempt to handle incoming request.
          *
-         * @param {object} params
-         * @param {string} params.rootPath - Absolute or relative path to the static root directory.
-         * @returns {Promise<void>}
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
+         * @returns {Promise<boolean>} True if file served
          */
-        this.init = async function ({rootPath}) {
-            _root = path.resolve(rootPath);
-            logger.info(`Static files root: ${_root}`);
+        this.handle = async (req, res) => {
+            if (!respond.isWritable(res)) return false;
+            const urlPath = decodeURIComponent(req.url.split('?')[0]);
+            const match = registry.find(urlPath);
+            if (!match) return false;
+            return fileService.serve(match.config, match.rel, req, res);
         };
 
         /**
-         * Returns the handler registration info.
          * @returns {Fl32_Web_Back_Dto_Handler_Info.Dto}
          */
         this.getRegistrationInfo = () => _info;

package/src/Back/Helper/Cast.js

@@ -83,4 +83,32 @@ export default class Fl32_Web_Back_Helper_Cast {
         }
         return undefined;
     }
+
+    /**
+     * Cast an object to a map with string keys and array-of-string values.
+     * Throws error on invalid structure or values.
+     *
+     * @param {*} data - Raw input to cast.
+     * @returns {Record<string, string[]>}
+     */
+    stringArrayMap(data) {
+        if (data === undefined) return {};
+        if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+            throw new Error('Invalid value for allow');
+        }
+        const res = {};
+        for (const [key, arr] of Object.entries(data)) {
+            if (!Array.isArray(arr)) throw new Error(`Invalid allow list for ${key}`);
+            const k = this.string(key);
+            if (!k) throw new Error('Invalid allow key');
+            const items = [];
+            for (const item of arr) {
+                const val = this.string(item);
+                if (!val) throw new Error(`Invalid allow list for ${k}`);
+                items.push(val);
+            }
+            res[k] = items;
+        }
+        return res;
+    }
 }

package/src/Back/Helper/Respond.js

@@ -56,16 +56,93 @@ export default class Fl32_Web_Back_Helper_Respond {
             return send({res, headers, body}, HTTP_STATUS_OK);
         };
 
+        /** @see send */
+        this.code201_Created = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_CREATED);
+        };
+
+        /** @see send */
+        this.code204_NoContent = function ({res, headers = {}}) {
+            return send({res, headers}, HTTP_STATUS_NO_CONTENT);
+        };
+
+        /** @see send */
+        this.code301_MovedPermanently = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_MOVED_PERMANENTLY);
+        };
+
+        /** @see send */
+        this.code302_Found = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_FOUND);
+        };
+
+        /** @see send */
+        this.code303_SeeOther = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_SEE_OTHER);
+        };
+
+        /** @see send */
+        this.code304_NotModified = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_NOT_MODIFIED);
+        };
+
+        /** @see send */
+        this.code400_BadRequest = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_BAD_REQUEST);
+        };
+
+        /** @see send */
+        this.code401_Unauthorized = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_UNAUTHORIZED);
+        };
+
+        /** @see send */
+        this.code402_PaymentRequired = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_PAYMENT_REQUIRED);
+        };
+
+        /** @see send */
+        this.code403_Forbidden = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_FORBIDDEN);
+        };
+
         /** @see send */
         this.code404_NotFound = function ({res, headers = {}, body = ''}) {
             return send({res, headers, body}, HTTP_STATUS_NOT_FOUND);
         };
 
+        /** @see send */
+        this.code405_MethodNotAllowed = function ({res, headers = {}, body = '', allowed = 'HEAD, GET, POST'}) {
+            return send(
+                {
+                    res,
+                    headers: {...headers, [HTTP2_HEADER_ALLOW]: allowed},
+                    body,
+                },
+                HTTP_STATUS_METHOD_NOT_ALLOWED
+            );
+        };
+
+        /** @see send */
+        this.code409_Conflict = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_CONFLICT);
+        };
+
         /** @see send */
         this.code500_InternalServerError = function ({res, headers = {}, body = 'Internal Server Error'}) {
             return send({res, headers, body}, HTTP_STATUS_INTERNAL_SERVER_ERROR);
         };
 
+        /** @see send */
+        this.code502_BadGateway = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_BAD_GATEWAY);
+        };
+
+        /** @see send */
+        this.code503_ServiceUnavailable = function ({res, headers = {}, body = ''}) {
+            return send({res, headers, body}, HTTP_STATUS_SERVICE_UNAVAILABLE);
+        };
+
         /**
          * Checks if the response is writable and not yet sent.
          * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res

package/test/accept/ExternalServer.test.mjs

@@ -0,0 +1,66 @@
+import {describe, it} from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import {buildTestContainer} from '../unit/common.js';
+import Express from 'express';
+import Fastify from 'fastify';
+
+async function startExpress(port, dispatcher) {
+  const app = Express();
+  app.use(async (req, res) => {
+    await dispatcher.onEventRequest(req, res);
+  });
+  const server = await new Promise((resolve, reject) => {
+    const srv = app.listen(port, err => err ? reject(err) : resolve(srv));
+  });
+  return server;
+}
+
+async function startFastify(port, dispatcher) {
+  const fastify = Fastify();
+  fastify.all('*', async (request, reply) => {
+    const req = request.raw;
+    const res = reply.raw;
+    await dispatcher.onEventRequest(req, res);
+  });
+  await fastify.listen({port});
+  return fastify;
+}
+
+describe('Dispatcher integration with external servers', () => {
+  it('should respond via express', async () => {
+    const container = buildTestContainer();
+    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
+    const port = 3054;
+    const server = await startExpress(port, dispatcher);
+
+    const status = await new Promise((resolve, reject) => {
+      http.get(`http://localhost:${port}`, res => {
+        const {statusCode} = res;
+        res.resume();
+        res.on('end', () => resolve(statusCode));
+      }).on('error', reject);
+    });
+
+    assert.strictEqual(status, 404);
+    await new Promise(resolve => server.close(resolve));
+  });
+
+  it('should respond via fastify', async () => {
+    const container = buildTestContainer();
+    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
+    const port = 3055;
+    const fastify = await startFastify(port, dispatcher);
+
+    const status = await new Promise((resolve, reject) => {
+      http.get(`http://localhost:${port}`, res => {
+        const {statusCode} = res;
+        res.resume();
+        res.on('end', () => resolve(statusCode));
+      }).on('error', reject);
+    });
+
+    assert.strictEqual(status, 404);
+    await fastify.close();
+  });
+});

package/test/accept/Server.test.mjs

@@ -11,7 +11,7 @@ async function waitListening(server) {
   }
 }
 
-describe('Fl32_Web_Back_Server (real)', () => {
+describe('Fl32_Web_Back_Server', () => {
   it('should start and respond in HTTP/1 mode', async () => {
     const container = buildTestContainer();
     const server = await container.get('Fl32_Web_Back_Server$');
@@ -103,3 +103,101 @@ describe('Fl32_Web_Back_Server (real)', () => {
     assert.strictEqual(server.getInstance(), undefined);
   });
 });
+
+describe('Fl32_Web_Back_Api_Handler', () => {
+  it('should serve allowed NPM file', async () => {
+    const container = buildTestContainer();
+    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
+    const handler = await container.get('Fl32_Web_Back_Handler_Static$');
+    const Cfg = await container.get('Fl32_Web_Back_Dto_Handler_Source$');
+    await handler.init({
+      sources: [Cfg.create({
+        root: 'node_modules',
+        prefix: '/npm/',
+        allow: {
+          '@teqfw/di/src': ['.'],
+        },
+      })],
+    });
+    dispatcher.addHandler(handler);
+    dispatcher.orderHandlers();
+
+    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: 3056, type: SERVER_TYPE.HTTP });
+    await server.start(cfg);
+    await waitListening(server);
+
+    const result = await new Promise((resolve, reject) => {
+      const req = http.get({
+        hostname: 'localhost',
+        port: cfg.port,
+        path: '/npm/@teqfw/di/src/Api/Container/Parser/Chunk.js',
+      }, res => {
+        const chunks = [];
+        res.on('data', ch => chunks.push(ch));
+        res.on('end', () => {
+          resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString() });
+        });
+      });
+      req.on('error', reject);
+    });
+
+    assert.strictEqual(result.status, 200);
+    assert.match(result.body, /class TeqFw_Di_Api_Container_Parser_Chunk/);
+
+    await server.stop();
+    assert.strictEqual(server.getInstance(), undefined);
+  });
+
+  it('should serve allowed source file', async () => {
+    const container = buildTestContainer();
+    const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
+    const handler = await container.get('Fl32_Web_Back_Handler_Static$');
+    const Cfg = await container.get('Fl32_Web_Back_Dto_Handler_Source$');
+    await handler.init({
+      sources: [Cfg.create({
+        root: 'src',
+        prefix: '/sources/',
+        allow: {
+          Back: ['Server.js'],
+        },
+      })],
+    });
+    dispatcher.addHandler(handler);
+    dispatcher.orderHandlers();
+
+    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: 3057, type: SERVER_TYPE.HTTP });
+    await server.start(cfg);
+    await waitListening(server);
+
+    const result = await new Promise((resolve, reject) => {
+      const req = http.get({
+        hostname: 'localhost',
+        port: cfg.port,
+        path: '/sources/Back/Server.js',
+      }, res => {
+        const chunks = [];
+        res.on('data', ch => chunks.push(ch));
+        res.on('end', () => {
+          resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString() });
+        });
+      });
+      req.on('error', reject);
+    });
+
+    assert.strictEqual(result.status, 200);
+    assert.match(result.body, /class Fl32_Web_Back_Server/);
+
+    await server.stop();
+    assert.strictEqual(server.getInstance(), undefined);
+  });
+});

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

@@ -5,6 +5,7 @@ export default class App_Plugin_Start {
      * @param {Fl32_Web_Back_Dispatcher} dispatcher
      * @param {Fl32_Web_Back_Handler_Pre_Log} hndlRequestLog
      * @param {Fl32_Web_Back_Handler_Static} hndlStatic
+     * @param {Fl32_Web_Back_Dto_Handler_Source} dtoCfg
      */
     constructor(
         {
@@ -13,6 +14,7 @@ export default class App_Plugin_Start {
             Fl32_Web_Back_Dispatcher$: dispatcher,
             Fl32_Web_Back_Handler_Pre_Log$: hndlRequestLog,
             Fl32_Web_Back_Handler_Static$: hndlStatic,
+            Fl32_Web_Back_Dto_Handler_Source$: dtoCfg,
         }
     ) {
         // VARS
@@ -28,9 +30,9 @@ export default class App_Plugin_Start {
         const webRoot = join(root, 'web');
 
         return async function () {
-            // Set up handlers
-            await hndlStatic.init({rootPath: webRoot});
-            // Register handlers
+            const srcNpm = dtoCfg.create({root: 'node_modules', prefix: '/npm/', allow: {'@teqfw/di': ['src/Container.js']}});
+            const srcWeb = dtoCfg.create({root: webRoot, prefix: '/'});
+            await hndlStatic.init({sources: [srcNpm, srcWeb]});
             dispatcher.addHandler(hndlRequestLog);
             dispatcher.addHandler(hndlStatic);
         };

package/test/unit/AGENTS.md

@@ -0,0 +1,106 @@
+# AI Agent Unit Testing Instructions for @flancer32/teq-web
+
+This document outlines project-specific guidelines for writing and maintaining unit tests in the `@flancer32/teq-web` plugin. Follow these rules to ensure consistency and reliability.
+
+---
+
+## 1. Test File Location & Naming
+
+* Mirror `src/` structure under `test/unit/`, using the same path and filenames.
+* Use `.test.mjs` suffix for test files, e.g. `Config.test.mjs`, `Kahn.test.mjs`.
+* Top-level `describe` must reference the full DI key:
+
+  ```js
+  describe('Fl32_Web_Back_Handler_Static_A_Config', () => { /* ... */ });
+  ```
+
+## 2. Dependency Injection via DI Container
+
+* Always call `buildTestContainer()` from `test/unit/common.js` and then:
+
+  ```js
+  /** @type {Fl32_Web_Back_Handler_Static_A_Config} */
+  const config = await container.get('Fl32_Web_Back_Handler_Static_A_Config$');
+  ```
+* **Do not** import production modules (`node:path`, etc.) directly—register or mock everything through the container.
+* Use `container.register(depId, mock)` to override dependencies in test mode.
+
+## 3. Asynchronous Subject Retrieval
+
+* Declare your `it` or `beforeEach` callbacks as `async` if you call `await container.get(...)`.
+* Always `await container.get('Your_Service_Key$')` to obtain the actual instance before invoking its methods.
+
+## 4. Testing Patterns
+
+* Use Node’s built-in test runner and assertion library:
+
+  ```js
+  import { describe, it } from 'node:test';
+  import assert from 'node:assert/strict';
+  ```
+* **Success cases**:
+
+    * `assert.strictEqual(actual, expected)` for primitives.
+    * `assert.deepStrictEqual(actual, expected)` for objects/arrays.
+* **Error cases**:
+
+    * `assert.throws(() => fn(), /message/)` matching a key fragment of the error.
+
+## 5. DTO Shape & Defaults
+
+* Pass a full DTO to `factory.create(dto)`.
+* To test fallback/default logic, supply `[]` for optional arrays.
+
+## 6. Comments & Documentation
+
+* All inline comments must be in **English**.
+* Comment only non-trivial logic; don’t restate obvious assertions.
+
+## 7. Mocks & Helpers
+
+* Use plain JS objects or small factory functions for mocks.
+* No external mocking libraries—rely on `@teqfw/di` test mode.
+
+## 8. Maintenance
+
+* One behavior per `it` block—keep tests focused and concise.
+* Update tests when API or default constants change.
+* Ensure CI runs all tests automatically.
+
+---
+
+## Test Mode Support in `@teqfw/di`
+
+When you enable test mode, you can inject or override any dependency—built-in or custom—without touching production code:
+
+```js
+const container = buildTestContainer();
+container.enableTestMode();
+
+// override a service or Node builtin
+container.register('Fl32_Web_Back_Logger$', mockLogger);
+container.register('node:fs', { /* mock fs.promises.stat… */});
+```
+
+* **register** vs. **registerInstance**
+  Use `container.register(depId, instanceOrFactory)` to bind mocks. Avoid `registerInstance`, which is not part of the public test-mode API.
+
+### Mocking Node.js Built-ins
+
+```js
+// simulate filesystem behavior
+container.register('node:fs', {
+    promises: {
+        stat: async (p) => { /* … */ }
+    },
+    createReadStream: (p) => { /* … */ }
+});
+
+// adjust path logic
+container.register('node:path', {
+    join: (...parts) => parts.join('/'),
+    resolve: (p) => `/abs/${p}`
+});
+```
+
+These overrides are injected into every module that asks for `node:fs` or `node:path`, enabling isolated, deterministic tests without side effects.