@flancer32/teq-web 0.1.0 → 0.2.0

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

@@ -30,7 +30,7 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      # Checkout repository code again for separate job
+      # Checkout repository code again for a separate job
       - uses: actions/checkout@v4
 
       # Setup Node.js and configure npm registry

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [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.
+
+## [0.1.0] - 2025-06-11
+
+### Added
+- Initial release of `@flancer32/teq-web`, a TeqFW plugin for centralized HTTP(S) request handling.
+- Dispatcher with three-stage lifecycle: `pre`, `process`, and `post`, each with isolated execution logic.
+- Middleware registration with support for execution order via `before`/`after` dependencies.
+- Support for custom adapters to integrate with various web servers (e.g., Express, Fastify, Node.js `http`).
+- Basic Node.js HTTP server implementation for standalone use cases.
+- Unified interfaces for registering request handlers from other teq-plugins.
+- Modular architecture compatible with Tequila Framework philosophy.
+

package/README.md

@@ -81,12 +81,20 @@ 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({
+    allow: {
+        vue: ['dist/vue.global.prod.js'],
+        '@teqfw/di': ['src/Container.js'],
+    }
+});
 await staticHandler.init({rootPath: webRoot});
 
 // 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
@@ -105,10 +113,35 @@ 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.
 
 ---
 
+### Using with Express or Fastify
+
+The dispatcher can be connected to external web frameworks instead of the built-in server.
+
+```js
+// Express
+const app = Express();
+app.use(async (req, res) => {
+    await dispatcher.onEventRequest(req, res);
+});
+app.listen(3000);
+
+// Fastify
+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: 3000});
+```
+
+---
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flancer32/teq-web",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Node.js web plugin supporting Express and Fastify integration, with built-in server for standalone operation",
   "type": "module",
   "keywords": [
@@ -34,7 +34,9 @@
   "devDependencies": {
     "@eslint/js": "^9.25.0",
     "eslint": "^9.25.0",
-    "eslint-plugin-jsdoc": "^50.6.8"
+    "eslint-plugin-jsdoc": "^50.6.8",
+    "express": "^4.18.2",
+    "fastify": "^4.27.2"
   },
   "engines": {
     "node": ">=20"

package/src/Back/Handler/Npm.js

@@ -0,0 +1,161 @@
+/**
+ * Serves whitelisted files from ./node_modules directory.
+ * @implements Fl32_Web_Back_Api_Handler
+ */
+export default class Fl32_Web_Back_Handler_Npm {
+    /* 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_Helper_Respond} respond
+     * @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_Helper_Respond$: respond,
+            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;
+        const _root = path.resolve('node_modules');
+
+        /** @type {Fl32_Web_Back_Dto_Handler_Info.Dto} */
+        const _info = dtoInfo.create();
+        _info.name = this.constructor.name;
+        _info.stage = STAGE.PROCESS;
+        Object.freeze(_info);
+
+        /** @type {{[key: string]: string[]}} */
+        let _allow = {};
+
+        // MAIN
+        /**
+         * Handles request to serve allowed files from node_modules.
+         *
+         * @param {module:http.IncomingMessage|module:http2.Http2ServerRequest} req
+         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
+         * @returns {Promise<boolean>}
+         */
+        this.handle = async function (req, res) {
+            if (!respond.isWritable(res)) return false;
+
+            const urlPath = decodeURIComponent(req.url.split('?')[0]);
+            const prefix = '/node_modules/';
+            if (!urlPath.startsWith(prefix)) return false;
+
+            const rel = urlPath.slice(prefix.length);
+            if (rel.includes('..') || path.isAbsolute(rel)) {
+                logger.warn(`NPM static access denied: ${rel}`);
+                return false;
+            }
+
+            let pkg; let subPath;
+            for (const key of Object.keys(_allow)) {
+                if (rel === key || rel.startsWith(`${key}/`)) {
+                    pkg = key;
+                    subPath = rel.slice(key.length);
+                    if (subPath.startsWith('/')) subPath = subPath.slice(1);
+                    break;
+                }
+            }
+            if (!pkg) return false;
+
+            const rules = _allow[pkg] || [];
+            let allowed = false;
+            if (rules.includes('.')) {
+                allowed = true;
+            } else {
+                for (const p of rules) {
+                    if (subPath === p || subPath.startsWith(`${p}/`)) {
+                        allowed = true;
+                        break;
+                    }
+                }
+            }
+
+            if (!allowed) {
+                logger.warn(`NPM static access denied: ${rel}`);
+                return false;
+            }
+
+            const fsPath = path.resolve(_root, rel);
+            if (!fsPath.startsWith(_root)) {
+                logger.warn(`NPM static access denied: ${rel}`);
+                return false;
+            }
+
+            let stat;
+            try {
+                stat = await fsp.stat(fsPath);
+            } catch {
+                logger.warn(`NPM static file not found: ${rel}`);
+                return false;
+            }
+            if (!stat.isFile()) {
+                logger.warn(`NPM static file not found: ${rel}`);
+                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;
+        };
+
+        /**
+         * Initialize handler with allow list.
+         *
+         * @param {object} params
+         * @param {{[key: string]: string[]}} params.allow - Map of packages to paths
+         *   that can be served from `node_modules`.
+         * @returns {Promise<void>}
+         *
+         * @example
+         * // Allow a single file from a package
+         * await npmHandler.init({
+         *   allow: {
+         *     vue: ['dist/vue.global.prod.js'],
+         *   },
+         * });
+         *
+         * @example
+         * // Allow all files from a subfolder
+         * await npmHandler.init({
+         *   allow: {
+         *     '@teqfw/di/src': ['.'],
+         *   },
+         * });
+         */
+        this.init = async function ({allow}) {
+            _allow = allow || {};
+        };
+
+        /** @returns {Fl32_Web_Back_Dto_Handler_Info.Dto} */
+        this.getRegistrationInfo = () => _info;
+    }
+}

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,48 @@ 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_Npm$');
+    await handler.init({
+      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: '/node_modules/@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);
+  });
+});

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

@@ -4,6 +4,7 @@ export default class App_Plugin_Start {
      * @param {typeof import('node:url')} url
      * @param {Fl32_Web_Back_Dispatcher} dispatcher
      * @param {Fl32_Web_Back_Handler_Pre_Log} hndlRequestLog
+     * @param {Fl32_Web_Back_Handler_Npm} hndlNpm
      * @param {Fl32_Web_Back_Handler_Static} hndlStatic
      */
     constructor(
@@ -12,6 +13,7 @@ export default class App_Plugin_Start {
             'node:url': url,
             Fl32_Web_Back_Dispatcher$: dispatcher,
             Fl32_Web_Back_Handler_Pre_Log$: hndlRequestLog,
+            Fl32_Web_Back_Handler_Npm$: hndlNpm,
             Fl32_Web_Back_Handler_Static$: hndlStatic,
         }
     ) {
@@ -29,9 +31,11 @@ export default class App_Plugin_Start {
 
         return async function () {
             // Set up handlers
+            await hndlNpm.init({allow: {'@teqfw/di': ['src/Container.js']}});
             await hndlStatic.init({rootPath: webRoot});
             // Register handlers
             dispatcher.addHandler(hndlRequestLog);
+            dispatcher.addHandler(hndlNpm);
             dispatcher.addHandler(hndlStatic);
         };
     }

package/test/unit/Back/Handler/Npm.test.mjs

@@ -0,0 +1,69 @@
+import {describe, it, beforeEach} from 'node:test';
+import assert from 'node:assert/strict';
+import {Writable} from 'node:stream';
+import {buildTestContainer} from '../../common.js';
+
+class MockRes extends Writable {
+    constructor() {
+        super();
+        this.data = Buffer.alloc(0);
+        this.statusCode = undefined;
+        this.headers = undefined;
+        this._headersSent = false;
+        this._ended = false;
+    }
+    get headersSent() { return this._headersSent; }
+    get writableEnded() { return this._ended; }
+    writeHead(status, headers) {
+        this.statusCode = status;
+        this.headers = headers;
+        this._headersSent = true;
+    }
+    _write(chunk, enc, cb) {
+        this.data = Buffer.concat([this.data, chunk]);
+        cb();
+    }
+    end(chunk) {
+        if (chunk) this.data = Buffer.concat([this.data, Buffer.from(chunk)]);
+        this._ended = true;
+        super.end();
+    }
+}
+
+describe('Fl32_Web_Back_Handler_Npm', () => {
+    let container;
+    const log = [];
+
+    beforeEach(() => {
+        container = buildTestContainer();
+        container.register('Fl32_Web_Back_Logger$', {
+            warn: (...args) => log.push(['warn', ...args]),
+            exception: (...args) => log.push(['exception', ...args]),
+        });
+        log.length = 0;
+    });
+
+    it('should serve allowed file', async () => {
+        const handler = await container.get('Fl32_Web_Back_Handler_Npm$');
+        await handler.init({allow: {'@teqfw/di': ['package.json']}});
+        const req = {url: '/node_modules/@teqfw/di/package.json'};
+        const res = new MockRes();
+        const ok = await handler.handle(req, res);
+        await new Promise(resolve => res.on('finish', resolve));
+        assert.strictEqual(ok, true);
+        assert.strictEqual(res.statusCode, 200);
+        assert.match(res.data.toString(), /@teqfw\/di/);
+        assert.strictEqual(log.length, 0);
+    });
+
+    it('should deny disallowed path', async () => {
+        const handler = await container.get('Fl32_Web_Back_Handler_Npm$');
+        await handler.init({allow: {'@teqfw/di': ['package.json']}});
+        const req = {url: '/node_modules/@teqfw/di/secret.js'};
+        const res = new MockRes();
+        const ok = await handler.handle(req, res);
+        assert.strictEqual(ok, false);
+        assert.strictEqual(res.headersSent, false);
+        assert.ok(log[0][0] === 'warn');
+    });
+});