@fastify/send

Send — это библиотека для потоковой передачи файлов из файловой системы в виде HTTP-ответа, поддерживающая частичные ответы (Ranges), согласование условного GET (If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since), высокое покрытие тестами и детализированные события, которые можно использовать для выполнения соответствующих действий в вашем приложении или фреймворке.

Установка

Это модуль Node.js, доступный через реестр npm. Установка выполняется с помощью команды npm install:

$ npm install @fastify/send

TypeScript

Если вы хотите использовать TypeScript, необходимо применять @types/mime@3; в @types/mime@4 типы mime были удалены.

$ npm install -D @types/mime@3

API

const send = require('@fastify/send')

send(req, path, [options])

Предоставляет statusCode, headers и stream для указанного пути для отправки в res. req — это HTTP-запрос Node.js, а path — это urlencoded путь для отправки (urlencoded, а не фактический путь в файловой системе).

Опции

acceptRanges

Включает или отключает приём запросов диапазона, по умолчанию true. Отключение не будет отправлять Accept-Ranges и игнорировать содержимое заголовка запроса Range.

cacheControl

Включает или отключает установку заголовка ответа Cache-Control, по умолчанию true. Отключение будет игнорировать опции immutable и maxAge.

contentType

По умолчанию эта библиотека использует модуль mime для установки Content-Type ответа на основе расширения файла запрошенного файла.

Чтобы отключить эту функциональность, установите contentType в false. Заголовок Content-Type нужно будет установить вручную, если отключено.

dotfiles

Задаёт, как обрабатываются "dotfiles" при обнаружении. Dotfile — это файл или каталог, который начинается с точки ("."). Обратите внимание, что эта проверка выполняется на самом пути без проверки, существует ли путь на диске. Если указан root, проверяются только dotfiles выше root (т.е. сам root может находиться внутри dotfile, если установлено "deny").

• 'allow' Никакой специальной обработки для dotfiles.
• 'deny' Отправлять 403 на любой запрос к dotfile.
• 'ignore' Вести себя так, как будто dotfile не существует, и 404.

Значение по умолчанию похоже на 'ignore', за исключением того, что это значение по умолчанию не будет игнорировать файлы внутри каталога, который начинается с точки, для обратной совместимости.

end

Байтовое смещение, на котором заканчивается поток, по умолчанию равно длине файла минус 1. Конец включается в поток, то есть end: 3 включит 4-й байт в поток.

etag

Включает или отключает генерацию etag, по умолчанию true.

extensions

Если заданный файл не существует, попробуйте добавить одно из заданных расширений, в заданном порядке. По умолчанию это отключено (установлено в false). Пример значения, которое будет обслуживать HTML-файлы без расширения: ['html', 'htm']. Это пропускается, если запрошенный файл уже имеет расширение.

immutable

Включает или отключает директиву immutable в заголовке ответа Cache-Control, по умолчанию false. Если установлено в true, опцию maxAge также следует указать для включения кэширования. Директива immutable предотвратит условные запросы поддерживаемых клиентов в течение срока действия опции maxAge для проверки, изменился ли файл.

index

По умолчанию send поддерживает файлы "index.html", чтобы отключить это, установите false или чтобы указать новый индекс, передайте строку или массив в предпочтительном порядке.

lastModified

Включает или отключает заголовок Last-Modified, по умолчанию true. Использует значение последнего изменения файловой системы.

maxAge

Указывает max-age в миллисекундах для HTTP-кэширования, по умолчанию 0. Это также может быть строка, принимаемая модулем ms.

maxContentRangeChunkSize

Указывает максимальный размер содержимого ответа, по умолчанию равен полному размеру файла. Это будет использоваться, когда acceptRanges равно true.

onFile

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

root

Обслуживать файлы относительно path.

start

Байтовое смещение, на котором начинается поток, по умолчанию 0. Начало включается, то есть start: 2 включит 3-й байт в поток.

highWaterMark

Если указано, эта опция задаёт максимальное количество байтов, которое будет содержать внутренний буфер перед приостановкой чтения из базового ресурса. Если вы опустите эту опцию (или передадите undefined), Node.js вернётся к своему встроенному значению по умолчанию для читаемых бинарных потоков.

.mime

Экспорт mime — это глобальный экземпляр mime npm-модуля.

Он используется для настройки MIME-типов, связанных с расширениями файлов, а также других параметров того, как определяется MIME-тип файла (например, тип по умолчанию для неизвестного расширения файла).

Кэширование

Он не выполняет внутреннее кэширование; для этого следует использовать обратный прокси-кэш, такой как Varnish, или эти модные штуки под названием CDN. Если ваше приложение достаточно мало, чтобы получить выгоду от кэширования в памяти одного узла, то оно достаточно мало, чтобы кэширование вообще не требовалось ;).

Отладка

Чтобы включить вывод инструментации debug(), экспортируйте NODE_DEBUG:

$ NODE_DEBUG=send node app

Запуск тестов

$ npm install
$ npm test

Примеры

Обслуживание конкретного файла

Этот простой пример будет отправлять конкретный файл на все запросы.

const http = require('node:http')
const send = require('send')

const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, '/path/to/index.html')
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)

Обслуживание всех файлов из каталога

Этот простой пример просто обслуживает все файлы в заданном каталоге как корневом. Например, запрос GET /foo.txt вернёт /www/public/foo.txt.

const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)

Пользовательские типы файлов

const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

// Default unknown types to text/plain
send.mime.default_type = 'text/plain'

// Add a custom type
send.mime.define({
  'application/x-my-type': ['x-mt', 'x-mtt']
})

const server = http.createServer(function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)