fastify/sendNode.js-библиотека для потоковой передачи файлов в качестве HTTP-ответов с поддержкой частичного контента, условных запросов и настраиваемых заголовков кэширования. Предназначена для использования в веб-фреймворках, таких как Fastify.
# @fastify/send
[](https://github.com/fastify/send/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@fastify/send)
[](https://github.com/neostandard/neostandard)
Send — это библиотека для потоковой передачи файлов из файловой системы в виде HTTP-ответа,
поддерживающая частичные ответы (Ranges), согласование условного GET (If-Match,
If-Unmodified-Since, If-None-Match, If-Modified-Since), высокое покрытие тестами
и детализированные события, которые можно использовать для выполнения соответствующих действий в вашем
приложении или фреймворке.
## Установка
Это модуль [Node.js](https://nodejs.org/en/), доступный через
[реестр npm](https://www.npmjs.com/). Установка выполняется с помощью
[команды `npm install`](https://docs.npmjs.com/downloading-and-installing-packages-locally):
```bash
$ npm install @fastify/send
```
### TypeScript
Если вы хотите использовать TypeScript, необходимо применять `@types/mime@3`;
в `@types/mime@4` типы `mime` были удалены.
```bash
$ npm install -D @types/mime@3
```
## API
```js
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](https://www.npmjs.com/package/ms).
##### maxContentRangeChunkSize
Указывает максимальный размер содержимого ответа, по умолчанию равен полному размеру файла.
Это будет использоваться, когда `acceptRanges` равно true.
##### onFile
Вызывается с абсолютным путём окончательно выбранного файла и статистикой файловой системы
после разрешения файла, но до обработки ответа и создания потока файла.
Обратный вызов может быть синхронным или возвращать промис. Если он возвращает промис,
`send` ждёт его завершения. Если обратный вызов выбрасывает исключение или его возвращённый промис
отклоняется, операция прерывается и `send()` отклоняется.
##### root
Обслуживать файлы относительно `path`.
##### start
Байтовое смещение, на котором начинается поток, по умолчанию 0. Начало включается,
то есть `start: 2` включит 3-й байт в поток.
##### highWaterMark
Если указано, эта опция задаёт максимальное количество байтов, которое будет
содержать внутренний буфер перед приостановкой чтения из базового ресурса.
Если вы опустите эту опцию (или передадите undefined), Node.js вернётся к
своему встроенному значению по умолчанию для читаемых бинарных потоков.
### .mime
Экспорт `mime` — это глобальный экземпляр
[`mime` npm-модуля](https://www.npmjs.com/package/mime).
Он используется для настройки MIME-типов, связанных с расширениями файлов,
а также других параметров того, как определяется MIME-тип файла (например,
тип по умолчанию для неизвестного расширения файла).
## Кэширование
Он _не_ выполняет внутреннее кэширование; для этого следует использовать
обратный прокси-кэш, такой как Varnish, или эти модные штуки под названием CDN. Если ваше
приложение достаточно мало, чтобы получить выгоду от кэширования в памяти
одного узла, то оно достаточно мало, чтобы кэширование вообще не требовалось ;).
## Отладка
Чтобы включить вывод инструментации `debug()`, экспортируйте __NODE_DEBUG__:
```
$ NODE_DEBUG=send node app
```
## Запуск тестов
```
$ npm install
$ npm test
```
## Примеры
### Обслуживание конкретного файла
Этот простой пример будет отправлять конкретный файл на все запросы.
```js
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`.
```js
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)
```
### Пользовательские типы файлов
```js
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)
```
### Пользовательское представление индекса каталога
Это пример предоставления структуры каталогов с
пользовательской функцией для отображения списка содержимого каталога.
```js
const http = require('node:http')
const fs = require('node:fs')
const parseUrl = require('parseurl')
const send = require('@fastify/send')
// Transfer arbitrary files from within /www/example.com/public/*
// with a custom handler for directory listing
const server = http.createServer(async function onRequest (req, res) {
const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { index: false, root: '/www/public' })
if(type === 'directory') {
// get directory list
const list = await readdir(metadata.path)
// render an index for the directory
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
res.end(list.join('\n') + '\n')
} else {
res.writeHead(statusCode, headers)
stream.pipe(res)
}
})
server.listen(3000)
```
### Обслуживание из корневого каталога с пользовательской обработкой ошибок
```js
const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')
const server = http.createServer(async function onRequest (req, res) {
// transfer arbitrary files from within
// /www/example.com/public/*
const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
switch (type) {
case 'directory': {
// your custom directory handling logic:
res.writeHead(301, {
'Location': metadata.requestPath + '/'
})
res.end('Redirecting to ' + metadata.requestPath + '/')
break
}
case 'error': {
// your custom error-handling logic:
res.writeHead(metadata.error.status ?? 500, {})
res.end(metadata.error.message)
break
}
default: {
// your custom headers
// serve all files for download
res.setHeader('Content-Disposition', 'attachment')
res.writeHead(statusCode, headers)
stream.pipe(res)
}
}
})
server.listen(3000)
```
## Лицензия
Лицензировано под [MIT](https://github.com/fastify/send/blob/main/LICENSE).