@fastify/send

Send es una librería para transmitir archivos del sistema de archivos como respuesta HTTP, con soporte para respuestas parciales (Ranges), negociación condicional GET (If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since), alta cobertura de pruebas y eventos granulares que pueden aprovecharse para tomar las acciones adecuadas en tu aplicación o framework.

Instalación

Este es un módulo de Node.js disponible a través del npm registry. La instalación se realiza mediante el comando npm install:

$ npm install @fastify/send

TypeScript

Se debe usar @types/mime@3 si se desea utilizar TypeScript; @types/mime@4 eliminó los tipos de mime.

$ npm install -D @types/mime@3

API

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

send(req, path, [options])

Proporciona statusCode, headers y stream para la ruta dada, para enviarlos a un res. req es la solicitud HTTP de Node.js y path es una ruta codificada en URL (codificada en URL, no la ruta real del sistema de archivos).

Opciones

acceptRanges

Habilita o deshabilita la aceptación de solicitudes con rangos; el valor por defecto es true. Al deshabilitar esto, no se enviará Accept-Ranges y se ignorará el contenido de la cabecera de solicitud Range.

cacheControl

Habilita o deshabilita el establecimiento de la cabecera de respuesta Cache-Control; el valor por defecto es true. Deshabilitar esto ignorará las opciones immutable y maxAge.

contentType

Por defecto, esta librería utiliza el módulo mime para establecer el Content-Type de la respuesta según la extensión del archivo solicitado.

Para deshabilitar esta funcionalidad, establece contentType a false. La cabecera Content-Type deberá establecerse manualmente si está deshabilitada.

dotfiles

Define cómo se tratan los "dotfiles" cuando se encuentran. Un dotfile es un archivo o directorio que comienza con un punto ("."). Ten en cuenta que esta verificación se realiza sobre la propia ruta, sin comprobar si la ruta existe en el disco. Si se especifica root, solo se verifican los dotfiles por encima de la raíz (es decir, la raíz misma puede estar dentro de un dotfile cuando se establece en "deny").

• 'allow' Sin tratamiento especial para dotfiles.
• 'deny' Envía un 403 para cualquier solicitud de un dotfile.
• 'ignore' Simula que el dotfile no existe y devuelve 404.

El valor por defecto es similar a 'ignore', con la excepción de que este valor predeterminado no ignorará los archivos dentro de un directorio que comience con un punto, por compatibilidad hacia atrás.

end

Desplazamiento en bytes en el que termina el flujo; el valor por defecto es la longitud del archivo menos 1. El final es inclusivo en el flujo, lo que significa que end: 3 incluirá el 4.º byte en el flujo.

etag

Habilita o deshabilita la generación de etag; el valor por defecto es true.

extensions

Si un archivo determinado no existe, intenta añadir una de las extensiones dadas, en el orden dado. Por defecto, esto está deshabilitado (establecido en false). Un ejemplo de valor que servirá archivos HTML sin extensión: ['html', 'htm']. Esto se omite si el archivo solicitado ya tiene una extensión.

immutable

Habilita o deshabilita la directiva immutable en la cabecera de respuesta Cache-Control; el valor por defecto es false. Si se establece en true, la opción maxAge también debe especificarse para habilitar el almacenamiento en caché. La directiva immutable evitará que los clientes compatibles realicen solicitudes condicionales durante la vida de la opción maxAge para comprobar si el archivo ha cambiado.

index

Por defecto, send admite archivos "index.html"; para deshabilitar esto, establece false o, para proporcionar un nuevo index, pasa una cadena o un array en el orden preferido.

lastModified

Habilita o deshabilita la cabecera Last-Modified; el valor por defecto es true. Utiliza el valor de última modificación del sistema de archivos.

maxAge

Proporciona una edad máxima en milisegundos para el almacenamiento en caché HTTP; el valor por defecto es 0. También puede ser una cadena aceptada por el módulo ms.

maxContentRangeChunkSize

Especifica el tamaño máximo del contenido de la respuesta; el valor por defecto es el tamaño completo del archivo. Esto se usará cuando acceptRanges sea true.

root

Sirve archivos relativos a path.

start

Desplazamiento en bytes en el que comienza el flujo; el valor por defecto es 0. El inicio es inclusivo, lo que significa que start: 2 incluirá el 3.er byte en el flujo.

highWaterMark

Cuando se proporciona, esta opción establece el número máximo de bytes que el búfer interno retendrá antes de pausar las lecturas del recurso subyacente. Si omites esta opción (o pasas undefined), Node.js recurre a su valor predeterminado integrado para flujos binarios legibles.

.mime

La exportación mime es la instancia global del módulo npm mime.

Esto se utiliza para configurar los tipos MIME asociados con extensiones de archivo, así como otras opciones sobre cómo resolver el tipo MIME de un archivo (como el tipo predeterminado a utilizar para una extensión de archivo desconocida).

Caché

No realiza caché interna; deberías usar un caché de proxy inverso como Varnish para esto, o esas cosas elegantes llamadas CDN. Si tu aplicación es lo suficientemente pequeña como para beneficiarse de un caché en memoria de un solo nodo, es lo suficientemente pequeña como para no necesitar caché en absoluto ;).

Depuración

Para habilitar la salida de instrumentación de debug(), exporta NODE_DEBUG:

$ NODE_DEBUG=send node app

Ejecutar pruebas

$ npm install
$ npm test

Ejemplos

Servir un archivo específico

Este sencillo ejemplo enviará un archivo específico a todas las solicitudes.

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)

Servir todos los archivos de un directorio

Este sencillo ejemplo simplemente servirá todos los archivos de un directorio determinado como nivel superior. Por ejemplo, una solicitud GET /foo.txt enviará de vuelta /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)

Tipos de archivo personalizados

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

// Tipos desconocidos predeterminados a text/plain
send.mime.default_type = 'text/plain'

// Agregar un tipo personalizado
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)

Vista personalizada de índice de directorio

Este es un ejemplo de cómo servir una estructura de directorios con una función personalizada para renderizar un listado de un directorio.

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

// Transferir archivos arbitrarios desde dentro de /www/example.com/public/*
// con un controlador personalizado para el listado de directorios
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') {
    // obtener la lista del directorio
    const list = await readdir(metadata.path)
    // renderizar un índice para el directorio
    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)

Servir desde un directorio raíz con manejo de errores personalizado

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

const server = http.createServer(async function onRequest (req, res) {
  // transferir archivos arbitrarios desde dentro
  // /www/example.com/public/*
  const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  switch (type) {
    case 'directory': {
      // tu lógica personalizada de manejo de directorios:
      res.writeHead(301, {
        'Location': metadata.requestPath + '/'
      })
      res.end('Redirigiendo a ' + metadata.requestPath + '/')
      break
    }
    case 'error': {
      // tu lógica personalizada de manejo de errores:
      res.writeHead(metadata.error.status ?? 500, {})
      res.end(metadata.error.message)
      break
    }
    default: {
      // tus cabeceras personalizadas
      // servir todos los archivos para descarga
      res.setHeader('Content-Disposition', 'attachment')
      res.writeHead(statusCode, headers)
      stream.pipe(res)
    }
  }
})

server.listen(3000)

Licencia

Licenciado bajo MIT.