@e22m4u/js-http-static-router 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-http-static-router",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "HTTP-маршрутизатор статичных ресурсов для Node.js",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -9,10 +9,10 @@
     "router",
     "http"
   ],
-  "homepage": "https://gitrepos.ru/e22m4u/js-http-static-router",
+  "homepage": "https://gitverse.ru/e22m4u/js-http-static-router",
   "repository": {
     "type": "git",
-    "url": "git+https://gitrepos.ru/e22m4u/js-http-static-router.git"
+    "url": "git+https://gitverse.ru/e22m4u/js-http-static-router.git"
   },
   "type": "module",
   "types": "./src/index.d.ts",
@@ -54,7 +54,7 @@
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
     "eslint-plugin-import": "~2.32.0",
-    "eslint-plugin-jsdoc": "~62.5.2",
+    "eslint-plugin-jsdoc": "~62.5.4",
     "eslint-plugin-mocha": "~11.2.0",
     "globals": "~17.3.0",
     "husky": "~9.1.7",

package/src/http-static-router.d.ts

@@ -1,53 +1,56 @@
 import {ServerResponse} from 'node:http';
 import {IncomingMessage} from 'node:http';
+import {StaticRouteDefinition} from './static-route.js';
 import {DebuggableService, ServiceContainer} from '@e22m4u/js-service';
 
 /**
- * Static file route.
+ * Http static router options.
  */
-export type HttpStaticRoute = {
-  remotePath: string;
-  resourcePath: string;
-  regexp: RegExp;
-  isFile: boolean;
+export type HttpStaticRouterOptions = {
+  rootDir?: string;
 };
 
 /**
  * Http static router.
  */
-export class HttpStaticRouter extends DebuggableService {
+export declare class HttpStaticRouter extends DebuggableService {
   /**
    * Constructor.
-   * 
-   * @param container 
+   *
+   * @param container
    */
-  constructor(container?: ServiceContainer);
+  constructor(container: ServiceContainer);
 
   /**
-   * Add route.
+   * Constructor.
+   *
+   * @param options
+   */
+  constructor(options: HttpStaticRouterOptions);
+
+  /**
+   * Constructor.
    *
-   * @param remotePath
-   * @param resourcePath
+   * @param container
+   * @param options
    */
-  addRoute(remotePath: string, resourcePath: string): this;
+  constructor(container: ServiceContainer, options: HttpStaticRouterOptions);
 
   /**
-   * Match route.
+   * Define route.
    *
-   * @param req
+   * @param routeDef
    */
-  matchRoute(req: IncomingMessage): HttpStaticRoute | undefined;
+  defineRoute(routeDef: StaticRouteDefinition): this;
 
   /**
-   * Send file by route.
+   * Handle request.
    *
-   * @param route
-   * @param req
-   * @param res
+   * @param request
+   * @param response
    */
-  sendFileByRoute(
-    route: HttpStaticRoute,
-    req: IncomingMessage,
-    res: ServerResponse,
-  ): void;
+  handleRequest(
+    request: IncomingMessage,
+    response: ServerResponse,
+  ): Promise<boolean>;
 }

package/src/http-static-router.js

@@ -1,9 +1,17 @@
 import path from 'path';
 import mimeTypes from 'mime-types';
+import {IncomingMessage} from 'http';
 import fs, {createReadStream} from 'fs';
-import {escapeRegexp, normalizePath} from './utils/index.js';
-import {DebuggableService} from '@e22m4u/js-service';
+import {StaticRoute} from './static-route.js';
+import {getPathnameFromUrl} from './utils/index.js';
 import {InvalidArgumentError} from '@e22m4u/js-format';
+import {DebuggableService, isServiceContainer} from '@e22m4u/js-service';
+
+/**
+ * @typedef {object} FileInfo
+ * @property {string} path
+ * @property {number} size
+ */
 
 /**
  * Http static router.
@@ -13,54 +21,108 @@ export class HttpStaticRouter extends DebuggableService {
    * Routes.
    *
    * @protected
+   * @type {StaticRoute[]}
    */
   _routes = [];
 
+  /**
+   * Options.
+   *
+   * @type {import('./http-static-router.js').HttpStaticRouterOptions}
+   * @protected
+   */
+  _options = {};
+
   /**
    * Constructor.
    *
-   * @param {import('@e22m4u/js-service').ServiceContainer} container
+   * @param {import('@e22m4u/js-service').ServiceContainer|import('./http-static-router.js').HttpStaticRouterOptions} containerOrOptions
+   * @param {import('./http-static-router.js').HttpStaticRouterOptions} options
    */
-  constructor(container) {
-    super(container, {
+  constructor(containerOrOptions, options) {
+    const debugOptions = {
       noEnvironmentNamespace: true,
       namespace: 'jsHttpStaticRouter',
-    });
+    };
+    if (isServiceContainer(containerOrOptions)) {
+      super(containerOrOptions, debugOptions);
+    } else if (containerOrOptions !== undefined) {
+      if (
+        !containerOrOptions ||
+        typeof containerOrOptions !== 'object' ||
+        Array.isArray(containerOrOptions)
+      ) {
+        throw new InvalidArgumentError(
+          'Parameter "containerOrOptions" must be an Object ' +
+            'or an instance of ServiceContainer, but %v was given.',
+          options,
+        );
+      }
+      super(undefined, debugOptions);
+      if (options === undefined) {
+        options = containerOrOptions;
+        containerOrOptions = undefined;
+      }
+    } else {
+      super(undefined, debugOptions);
+    }
+    // options
+    if (options !== undefined) {
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new InvalidArgumentError(
+          'Parameter "options" must be an Object, but %v was given.',
+          options,
+        );
+      }
+      // options.rootDir
+      if (options.rootDir !== undefined) {
+        if (typeof options.rootDir !== 'string') {
+          throw new InvalidArgumentError(
+            'Option "rootDir" must be a String, but %v was given.',
+            options.rootDir,
+          );
+        }
+        if (!path.isAbsolute(options.rootDir)) {
+          throw new InvalidArgumentError(
+            'Option "rootDir" must be an absolute path, but %v was given.',
+            options.rootDir,
+          );
+        }
+      }
+      this._options = {...options};
+    }
+    Object.freeze(this._options);
   }
 
   /**
-   * Add route.
+   * Define route.
    *
-   * @param {string} remotePath
-   * @param {string} resourcePath
-   * @returns {object}
+   * @param {import('./static-route.js').StaticRouteDefinition} routeDef
+   * @returns {this}
    */
-  addRoute(remotePath, resourcePath) {
-    const debug = this.getDebuggerFor(this.addRoute);
-    resourcePath = path.resolve(resourcePath);
-    debug('Adding a new route.');
-    debug('Resource path is %v.', resourcePath);
-    debug('Remote path is %v.', remotePath);
-    let stats;
-    try {
-      stats = fs.statSync(resourcePath);
-    } catch (error) {
-      // если ресурс не существует в момент старта,
-      // это может быть ошибкой конфигурации
-      console.error(error);
+  defineRoute(routeDef) {
+    if (!routeDef || typeof routeDef !== 'object' || Array.isArray(routeDef)) {
       throw new InvalidArgumentError(
-        'Static resource path does not exist %v.',
-        resourcePath,
+        'Parameter "routeDef" must be an Object, but %v was given.',
+        routeDef,
+      );
+    }
+    if (
+      this._options.rootDir !== undefined &&
+      !path.isAbsolute(routeDef.resourcePath)
+    ) {
+      routeDef = {...routeDef};
+      routeDef.resourcePath = path.join(
+        this._options.rootDir,
+        routeDef.resourcePath,
       );
     }
-    const isFile = stats.isFile();
-    debug('Resource type is %s.', isFile ? 'File' : 'Folder');
-    const normalizedRemotePath = normalizePath(remotePath);
-    const escapedRemotePath = escapeRegexp(normalizedRemotePath);
-    const regexp = isFile
-      ? new RegExp(`^${escapedRemotePath}$`)
-      : new RegExp(`^${escapedRemotePath}(?:$|\\/)`);
-    const route = {remotePath, resourcePath, regexp, isFile};
+    const debug = this.getDebuggerFor(this.defineRoute);
+    const route = new StaticRoute(routeDef);
+    debug('Adding a new route.');
+    debug('Resource path is %v.', route.resourcePath);
+    debug('Remote path is %v.', route.remotePath);
+    debug('Resource type is %s.', route.isFile ? 'File' : 'Folder');
     this._routes.push(route);
     // самые длинные пути проверяются первыми,
     // чтобы избежать коллизий при поиске маршрута
@@ -69,141 +131,188 @@ export class HttpStaticRouter extends DebuggableService {
   }
 
   /**
-   * Match route.
+   * Handle request.
    *
-   * @param {import('http').IncomingMessage} req
-   * @returns {object|undefined}
+   * @param {import('http').IncomingMessage} request
+   * @param {import('http').ServerResponse} response
+   * @returns {Promise<boolean>}
    */
-  matchRoute(req) {
-    const debug = this.getDebuggerFor(this.matchRoute);
-    debug('Matching routes with incoming request.');
-    const url = (req.url || '/').replace(/\?.*$/, '');
-    debug('Incoming request is %s %v.', req.method, url);
-    if (req.method !== 'GET' && req.method !== 'HEAD') {
-      debug('Method not allowed.');
-      return;
+  async handleRequest(request, response) {
+    const fileInfo = await this._findFileForRequest(request);
+    if (fileInfo !== undefined) {
+      this._sendFile(request, response, fileInfo);
+      return true;
     }
-    debug('Walking through %v routes.', this._routes.length);
-    const route = this._routes.find(route => {
-      const res = route.regexp.test(url);
-      const phrase = res ? 'matched' : 'not matched';
-      debug('Resource %v %s.', route.resourcePath, phrase);
-      return res;
-    });
-    route
-      ? debug('Resource %v matched.', route.resourcePath)
-      : debug('No route matched.');
-    return route;
+    return false;
   }
 
   /**
-   * Send file by route.
+   * Find file for request.
    *
-   * @param {object} route
-   * @param {import('http').IncomingMessage} req
-   * @param {import('http').ServerResponse} res
+   * @param {import('http').IncomingMessage} request
+   * @returns {Promise<FileInfo|undefined>|undefined}
    */
-  sendFileByRoute(route, req, res) {
-    const reqUrl = req.url || '/';
-    const reqPath = reqUrl.replace(/\?.*$/, '');
-    // если ресурс ссылается на папку, то из адреса запроса
-    // извлекается дополнительная часть (если присутствует),
-    // и добавляется к адресу ресурса
-    let targetPath = route.resourcePath;
-    if (!route.isFile) {
-      // извлечение относительного пути в дополнение к адресу
-      // ресурса путем удаления из адреса запроса той части,
-      // которая была указана при объявлении маршрута
-      const relativePath = reqPath.replace(route.regexp, '');
-      // объединение адреса ресурса
-      // с дополнительной частью
-      targetPath = path.join(route.resourcePath, relativePath);
+  async _findFileForRequest(request) {
+    if (!(request instanceof IncomingMessage)) {
+      throw new InvalidArgumentError(
+        'Parameter "request" must be an instance of IncomingMessage, ' +
+          'but %v was given.',
+        request,
+      );
     }
-    // если обнаружена попытка выхода за пределы
-    // корневой директории, то выбрасывается ошибка
-    targetPath = path.resolve(targetPath);
-    const resourceRoot = path.resolve(route.resourcePath);
-    if (!targetPath.startsWith(resourceRoot)) {
-      res.writeHead(403, {'content-type': 'text/plain'});
-      res.end('403 Forbidden');
+    const debug = this.getDebuggerFor(this._findFileForRequest);
+    debug('File finding for an incoming request.');
+    debug('Incoming request %s %v.', request.method, request.url);
+    let requestPath;
+    try {
+      requestPath = decodeURIComponent(getPathnameFromUrl(request.url || ''));
+    } catch {
+      debug('Invalid URL encoding .');
       return;
     }
-    // подстановка индекс-файла (для папок),
-    // установка заголовков и отправка потока
-    fs.stat(targetPath, (statsError, stats) => {
-      if (statsError) {
-        return _handleFsError(statsError, res);
-      }
-      if (stats.isDirectory()) {
-        // так как в html обычно используются относительные пути,
-        // то адрес директории статических ресурсов должен завершаться
-        // косой чертой, чтобы файлы стилей и изображений загружались
-        // именно из нее, а не обращались на уровень выше
-        if (/[^/]$/.test(reqPath)) {
-          const searchMatch = reqUrl.match(/\?.*$/);
-          const search = searchMatch ? searchMatch[0] : '';
-          const normalizedPath = reqUrl.replace(/\/{2,}/g, '/');
-          res.writeHead(302, {location: `${normalizedPath}/${search}`});
-          res.end();
-          return;
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      debug('Method not allowed.');
+      return;
+    }
+    if (requestPath.includes('//')) {
+      debug('Request path contains duplicate slashes.');
+      return;
+    }
+    if (!this._routes.length) {
+      debug('No registered routes.');
+      return;
+    }
+    debug('Walking through %v routes.', this._routes.length);
+    for (const route of this._routes) {
+      const isMatched = route.regexp.test(requestPath);
+      if (isMatched) {
+        debug('Matched route %v.', route.remotePath);
+        // если ресурс ссылается на папку, то из адреса запроса
+        // извлекается дополнительная часть (если присутствует),
+        // и формируется целевой путь файловой системы
+        let targetPath = route.resourcePath;
+        if (!route.isFile) {
+          // извлечение относительного пути в дополнение к адресу
+          // ресурса путем удаления из адреса запроса той части,
+          // которая была указана при объявлении маршрута
+          const relativePath = requestPath.replace(route.regexp, '');
+          // объединение адреса ресурса
+          // с дополнительной частью
+          targetPath = path.join(route.resourcePath, relativePath);
         }
-        // если адрес запроса содержит дублирующие слеши,
-        // то адрес нормализуется и выполняется редирект
-        if (/\/{2,}/.test(reqUrl)) {
-          const normalizedUrl = reqUrl.replace(/\/{2,}/g, '/');
-          res.writeHead(302, {location: normalizedUrl});
-          res.end();
+        // если обнаружена попытка выхода за пределы
+        // директории маршрута, то возвращается undefined
+        targetPath = path.resolve(targetPath);
+        const resourceRoot = path.resolve(route.resourcePath);
+        if (
+          targetPath !== resourceRoot &&
+          !targetPath.startsWith(resourceRoot + path.sep)
+        ) {
           return;
         }
-        // если целевой путь указывает на папку,
-        // то подставляется index.html
-        targetPath = path.join(targetPath, 'index.html');
-      }
-      // формирование заголовка "content-type"
-      // в зависимости от расширения файла
-      const extname = path.extname(targetPath);
-      const contentType =
-        mimeTypes.contentType(extname) || 'application/octet-stream';
-      // файл читается и отправляется частями,
-      // что значительно снижает использование памяти
-      const fileStream = createReadStream(targetPath);
-      fileStream.on('error', error => {
-        _handleFsError(error, res);
-      });
-      // отправка заголовка 200, только после
-      // этого начинается отдача файла
-      fileStream.on('open', () => {
-        res.writeHead(200, {'content-type': contentType});
-        // для HEAD запроса отправляются
-        // только заголовки (без тела)
-        if (req.method === 'HEAD') {
-          res.end();
-          return;
+        // с определением размера файла одновременно выполняется
+        // отсечение отсутствующих файлов и директорий, в таких
+        // случаях значение размера будет является undefined
+        const fileSize = await new Promise(resolve => {
+          fs.stat(targetPath, (statsError, stats) => {
+            if (statsError || stats.isDirectory()) {
+              resolve(undefined);
+              return;
+            }
+            resolve(stats.size);
+            return;
+          });
+        });
+        // если размер файла определен, то поиск
+        // прерывается и возвращается информация
+        if (fileSize !== undefined) {
+          // если файл найден, но запрос заканчивается
+          // на слеш, то файл должен быть проигнорирован
+          if (requestPath.endsWith('/')) {
+            continue;
+          }
+          debug('File found %v.', targetPath);
+          return {path: targetPath, size: fileSize};
         }
-        fileStream.pipe(res);
+      }
+    }
+    debug('File not found.');
+  }
+
+  /**
+   * Send file.
+   *
+   * @param {import('http').IncomingMessage} request
+   * @param {import('http').ServerResponse} response
+   * @param {FileInfo} fileInfo
+   */
+  _sendFile(request, response, fileInfo) {
+    const debug = this.getDebuggerFor(this._sendFile);
+    debug('File sending for an incoming request.');
+    debug('Incoming request %s %v.', request.method, request.url);
+    debug('File path %v.', fileInfo.path);
+    debug('File size %v bytes.', fileInfo.size);
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      debug('Method not allowed.');
+      return;
+    }
+    // формирование заголовка "content-type"
+    // в зависимости от расширения файла
+    const extname = path.extname(fileInfo.path);
+    const contentType =
+      mimeTypes.contentType(extname) || 'application/octet-stream';
+    // файл читается и отправляется частями,
+    // что значительно снижает использование памяти
+    const fileStream = createReadStream(fileInfo.path);
+    fileStream.on('error', error => {
+      debug('Unable to open a file stream.');
+      this._handleFsError(error, response);
+    });
+    // отправка заголовка 200, только после
+    // этого начинается отдача файла
+    fileStream.on('open', () => {
+      response.writeHead(200, {
+        'Content-Type': contentType,
+        'Content-Length': fileInfo.size,
       });
+      // для HEAD запроса отправляются
+      // только заголовки (без тела)
+      if (request.method === 'HEAD') {
+        response.end();
+        debug('Response has been sent without a body for the HEAD request.');
+        // важно закрыть файловый поток, чтобы операционная
+        // система не исчерпала лимит открытых файлов
+        fileStream.destroy();
+        return;
+      }
+      fileStream.pipe(response);
+    });
+    request.on('close', () => {
+      debug('File has been sent.');
+      fileStream.destroy();
     });
   }
-}
 
-/**
- * Handle filesystem error.
- *
- * @param {object} error
- * @param {object} res
- * @returns {undefined}
- */
-function _handleFsError(error, res) {
-  if (res.headersSent) {
-    return;
-  }
-  if ('code' in error && error.code === 'ENOENT') {
-    res.writeHead(404, {'content-type': 'text/plain'});
-    res.write('404 Not Found');
-    res.end();
-  } else {
-    res.writeHead(500, {'content-type': 'text/plain'});
-    res.write('500 Internal Server Error');
-    res.end();
+  /**
+   * Handle filesystem error.
+   *
+   * @param {object} error
+   * @param {object} response
+   * @returns {undefined}
+   */
+  _handleFsError(error, response) {
+    if (response.headersSent) {
+      response.destroy();
+      return;
+    }
+    if ('code' in error && error.code === 'ENOENT') {
+      response.writeHead(404, {'Content-Type': 'text/plain'});
+      response.write('404 Not Found');
+      response.end();
+    } else {
+      response.writeHead(500, {'Content-Type': 'text/plain'});
+      response.write('500 Internal Server Error');
+      response.end();
+    }
   }
 }

package/src/index.d.ts

@@ -1 +1,2 @@
+export * from './static-route.js';
 export * from './http-static-router.js';

package/src/index.js

@@ -1 +1,2 @@
+export * from './static-route.js';
 export * from './http-static-router.js';

package/src/static-route.d.ts

@@ -0,0 +1,48 @@
+
+/**
+ * Static route definition.
+ */
+export type StaticRouteDefinition = {
+  remotePath: string;
+  resourcePath: string;
+}
+
+/**
+ * Static route.
+ */
+export class StaticRoute {
+  /**
+   * Remote path.
+   *
+   * @type {string}
+   */
+  readonly remotePath: string;
+
+  /**
+   * Resource path.
+   *
+   * @type {string}
+   */
+  readonly resourcePath: string;
+
+  /**
+   * RegExp.
+   *
+   * @type {RegExp}
+   */
+  readonly regexp: RegExp;
+
+  /**
+   * Is file.
+   *
+   * @type {boolean}
+   */
+  readonly isFile: boolean;
+
+  /**
+   * Constructor.
+   * 
+   * @param routeDef
+   */
+  constructor(routeDef: StaticRouteDefinition);
+}