js-http-static-router

@e22m4u/js-http-static-router

HTTP-маршрутизатор статичных ресурсов для Node.js.

Модуль удобен для встраивания документации или административных панелей непосредственно в серверное приложение, позволяя избежать развертывания дополнительной инфраструктуры.

• Интеграция в существующий http-сервер.
• Управление доступом к файловой системе через маршруты.
• Использование потоков для экономии оперативной памяти.

Содержание

• Установка
• Базовый пример
• Маршрутизатор
  • Создание экземпляра
  • Регистрация маршрута
  • Обработка запросов
• Тесты
• Лицензия

Установка

Модуль поддерживает ESM и CommonJS стандарты.

ESM

CommonJS

Базовый пример

Пример предполагает следующую структуру проекта.

Создание маршрутизатора, определение маршрутов и запуск сервера.

Запуск Node.js процесса.

Маршрутизатор

Класс

является основным компонентом модуля. Он отвечает за хранение определений маршрутов, сопоставление входящих HTTP-запросов с ресурсами файловой системы и потоковую передачу данных клиенту.

Создание экземпляра

Конструктор маршрутизатора принимает объект настроек, который позволяет задать базовые параметры работы.

Сигнатура:

Параметры

• baseDir: string
  - абсолютный путь к базовой директории.
  Если параметр указан, все относительные пути при регистрации маршрутов будут разрешаться относительно этой директории.

Пример

Создание экземпляра с указанием базовой директории.

i. Доступ к переменной

(директория текущего модуля) возможен только при использовании ESM стандарта, начиная с версии Node.js 20.11.0. Для более ранних версий или CommonJS используется

__dirname

.

Регистрация маршрута

Метод

добавляет новое правило маршрутизации, связывая виртуальный путь (URL) с реальным файлом или директорией на сервере. В момент вызова данного метода маршрутизатор проверяет физическое существование указанного ресурса в файловой системе.

Сигнатура:

Параметры

• remotePath: string
  
  Префикс URL-адреса, с которого должен начинаться входящий запрос
  (обязательно должен начинаться со слеша
  /
  ).

• resourcePath: string
  
  Путь к существующему файлу или директории в файловой системе.

i. Если при создании экземпляра маршрутизатора не была указана опция

, значение параметра

resourcePath

обязано быть абсолютным путем.

Примеры

Регистрация конкретного файла. Запрос по указанному пути в параметре

вернет содержимое связанного файла. Маршрутизатор учитывает наличие/отсутствие завершающего слеша в конце пути.

Экспозиция содержимого директории. Если маршрут указывает на директорию, дополнительная часть URL-адреса будет автоматически добавлена к пути файловой системы.

Регистрация маршрута с использованием абсолютного пути.

i. Маршрутизатор выполняет проверку безопасности. Если при запросе клиент попытается выйти за пределы каталога с помощью относительных переходов (например,

), обработчик прервет поиск и файл не будет отправлен.

Обработка запросов

Метод

выполняет сопоставление входящего HTTP-запроса с зарегистрированными маршрутами и выполняет отправку найденного файла клиенту. При чтении файла маршрутизатор использует потоки, что позволяет безопасно отдавать файлы большого размера без переполнения оперативной памяти сервера.

Маршрутизатор автоматически определяет MIME-тип ресурса на основе его расширения, устанавливает необходимые заголовки, а также корректно обрабатывает обрыв соединения со стороны клиента, своевременно закрывая файловый поток для предотвращения утечек памяти.

Сигнатура:

Параметры

• request: IncomingMessage
  - нативный поток входящего запроса Node.js;
• response: ServerResponse
  - нативный поток исходящего ответа Node.js;

Возвращаемое значение

Метод возвращает

, который разрешается логическим значением

false

, если маршрут не совпал, целевой файл физически отсутствует или метод запроса не поддерживается. Во всех остальных случаях значением будет

true

, что позволяет определить, взял ли на себя ответственность за обработку запроса маршрутизатор.

Пример

Интеграция метода в обработчик событий нативного HTTP-сервера. Если

возвращает

false

, сервер берет на себя ответственность за отправку ответа с ошибкой клиенту.

Маршрутизатор обрабатывает исключительно запросы с методами

и

HEAD

. При получении запроса с любым другим методом, обработка прерывается и метод возвращает

false

. В случае

HEAD

запроса маршрутизатор корректно вычисляет размер файла и отправляет соответствующие заголовки, пропуская отправку тела ответа.

Тесты

Лицензия

MIT