
Biblioteca Node.js para streaming de arquivos como respostas HTTP com suporte a conteúdo parcial, requisições condicionais e cabeçalhos de cache configuráveis. Projetada para uso em frameworks web como Fastify.
Send é uma biblioteca para transmitir arquivos do sistema de arquivos como uma resposta HTTP, com suporte a respostas parciais (Ranges), negociação conditional-GET (If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since), alta cobertura de testes e eventos granulares que podem ser aproveitados para tomar ações apropriadas em sua aplicação ou framework.
Este é um módulo Node.js disponível através do
registro npm. A instalação é feita usando o
comando npm install:
$ npm install @fastify/send
@types/mime@3 deve ser usado se quiser usar TypeScript;
@types/mime@4 removeu os tipos de mime.
$ npm install -D @types/mime@3
const send = require('@fastify/send')
Fornece statusCode, headers e stream para o caminho fornecido a enviar para um
res. O req é o pedido HTTP do Node.js e o path é um caminho codificado em URL
a enviar (codificado em URL, não o caminho real do sistema de ficheiros).
Ativa ou desativa a aceitação de pedidos com intervalo, o valor predefinido é true.
Desativar isto não enviará Accept-Ranges e ignorará o conteúdo
do cabeçalho de pedido Range.
Ativa ou desativa a definição do cabeçalho de resposta Cache-Control, o valor predefinido é
true. Desativar isto ignorará as opções immutable e maxAge.
Por predefinição, esta biblioteca utiliza o módulo mime para definir o Content-Type
da resposta com base na extensão do ficheiro pedido.
Para desativar esta funcionalidade, defina contentType como false.
O cabeçalho Content-Type terá de ser definido manualmente se for desativado.
Define como os "dotfiles" são tratados quando encontrados. Um dotfile é um ficheiro
ou diretório que começa com um ponto ("."). Note que esta verificação é feita no
próprio caminho sem verificar se o caminho existe no
disco. Se root for especificado, apenas os dotfiles acima da raiz são
verificados (ou seja, a própria raiz pode estar dentro de um dotfile quando definido
como "deny").
'allow' Sem tratamento especial para dotfiles.'deny' Envia um 403 para qualquer pedido de um dotfile.'ignore' Finge que o dotfile não existe e devolve 404.O valor predefinido é semelhante a 'ignore', com a exceção de que
esta predefinição não ignorará os ficheiros dentro de um diretório que começa
com um ponto, por compatibilidade retroativa.
Deslocamento em bytes no qual o stream termina, o valor predefinido é o comprimento do ficheiro
menos 1. O fim é inclusivo no stream, ou seja, end: 3 incluirá
o 4.º byte no stream.
Ativa ou desativa a geração de etag, o valor predefinido é true.
Se um determinado ficheiro não existir, tenta acrescentar uma das extensões fornecidas,
pela ordem indicada. Por predefinição, isto está desativado (definido como false). Um
valor de exemplo que servirá ficheiros HTML sem extensão: ['html', 'htm'].
Isto é ignorado se o ficheiro pedido já tiver uma extensão.
Ativa ou desativa a diretiva immutable no cabeçalho de resposta Cache-Control,
o valor predefinido é false. Se definido como true, a opção maxAge também deve
ser especificada para ativar a colocação em cache. A diretiva immutable impedirá
os clientes compatíveis de fazer pedidos condicionais durante a vigência da
opção maxAge para verificar se o ficheiro foi alterado.
Por predefinição, o send suporta ficheiros "index.html"; para desativar isto
defina false ou, para fornecer um novo índice, passe uma string ou um array
pela ordem preferida.
Ativa ou desativa o cabeçalho Last-Modified, o valor predefinido é true. Utiliza o valor
de última modificação do sistema de ficheiros.
Fornece um max-age em milissegundos para colocação em cache HTTP, o valor predefinido é 0. Isto também pode ser uma string aceite pelo módulo ms.
Especifica o tamanho máximo do conteúdo da resposta, o valor predefinido é o tamanho total do ficheiro.
Isto será utilizado quando acceptRanges for true.
Chamado com o caminho absoluto do ficheiro final selecionado e as estatísticas do sistema de ficheiros
após a resolução do ficheiro, mas antes do processamento da resposta e da criação do stream do ficheiro.
O callback pode ser síncrono ou devolver uma promise. Se devolver uma promise,
o send aguarda que esta seja resolvida. Se o callback lançar uma exceção ou a sua promise
devolvida for rejeitada, a operação é abortada e send() é rejeitado.
Serve ficheiros relativamente a path.
Deslocamento em bytes no qual o stream começa, o valor predefinido é 0. O início é inclusivo,
ou seja, start: 2 incluirá o 3.º byte no stream.
Quando fornecido, esta opção define o número máximo de bytes que o buffer interno irá conter antes de pausar as leituras do recurso subjacente. Se omitir esta opção (ou passar undefined), o Node.js recorre à sua predefinição incorporada para streams binários legíveis.
A exportação mime é a instância global do
módulo npm mime.
Isto é usado para configurar os tipos MIME que estão associados a extensões de ficheiro, bem como outras opções sobre como resolver o tipo MIME de um ficheiro (como o tipo predefinido a usar para uma extensão de ficheiro desconhecida).
Não realiza caching interno; deve usar um cache de proxy reverso como o Varnish para isso, ou essas coisas sofisticadas chamadas CDNs. Se a sua aplicação for suficientemente pequena para beneficiar de caching em memória de nó único, então é suficientemente pequena para não precisar de caching de todo ;).
Para ativar a saída de instrumentação debug(), exporte NODE_DEBUG:
$ NODE_DEBUG=send node app
$ npm install
$ npm test
Este exemplo simples enviará um arquivo específico para todas as requisições.
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)
Este exemplo simples irá apenas servir todos os arquivos de um
determinado diretório como nível superior. Por exemplo, uma requisição
GET /foo.txt retornará /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'