@fastify/send

Send ist eine Bibliothek zum Streamen von Dateien aus dem Dateisystem als HTTP-Antwort mit Unterstützung für partielle Antworten (Ranges), Conditional-GET-Aushandlung (If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since), hoher Testabdeckung und granularen Events, die genutzt werden können, um geeignete Maßnahmen in Ihrer Anwendung oder Ihrem Framework zu ergreifen.

Installation

Dies ist ein Node.js-Modul, das über die npm registry verfügbar ist. Die Installation erfolgt mit dem npm install-Befehl:

$ npm install @fastify/send

TypeScript

@types/mime@3 muss verwendet werden, wenn TypeScript genutzt werden soll; @types/mime@4 hat die mime-Typen entfernt.

$ npm install -D @types/mime@3

API

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

send(req, path, [options])

Stellt statusCode, headers und stream für den angegebenen Pfad bereit, um sie an eine res zu senden. Die req ist die Node.js-HTTP-Anfrage und der path ist ein urlencodierter Pfad zum Senden (urlencoded, nicht der tatsächliche Dateisystempfad).

Optionen

acceptRanges

Aktiviert oder deaktiviert das Akzeptieren von Bereichsanfragen, Standard ist true. Bei Deaktivierung wird Accept-Ranges nicht gesendet und der Inhalt des Range-Anfrage-Headers ignoriert.

cacheControl

Aktiviert oder deaktiviert das Setzen des Cache-Control-Antwort-Headers, Standard ist true. Bei Deaktivierung werden die Optionen immutable und maxAge ignoriert.

contentType

Standardmäßig verwendet diese Bibliothek das mime-Modul, um den Content-Type der Antwort basierend auf der Dateiendung der angeforderten Datei zu setzen.

Um diese Funktionalität zu deaktivieren, setzen Sie contentType auf false. Der Content-Type-Header muss dann manuell gesetzt werden.

dotfiles

Legt fest, wie mit "Dotfiles" umgegangen wird, wenn sie auftreten. Ein Dotfile ist eine Datei oder ein Verzeichnis, das mit einem Punkt (".") beginnt. Beachten Sie, dass diese Prüfung auf dem Pfad selbst erfolgt, ohne zu prüfen, ob der Pfad auf der Festplatte existiert. Wenn root angegeben ist, werden nur die Dotfiles oberhalb des Root geprüft (d. h. der Root selbst kann sich innerhalb eines Dotfiles befinden, wenn "deny" gesetzt ist).

• 'allow' Keine besondere Behandlung für Dotfiles.
• 'deny' Sendet ein 403 für jede Anfrage nach einem Dotfile.
• 'ignore' Tut so, als ob das Dotfile nicht existiert, und sendet 404.

Der Standardwert ist ähnlich zu 'ignore', mit der Ausnahme, dass dieser Standard die Dateien innerhalb eines Verzeichnisses, das mit einem Punkt beginnt, aus Gründen der Abwärtskompatibilität nicht ignoriert.

end

Byte-Offset, an dem der Stream endet, Standard ist die Länge der Datei minus 1. Das Ende ist inklusiv im Stream, das heißt end: 3 schließt das 4. Byte im Stream ein.

etag

Aktiviert oder deaktiviert die etag-Generierung, Standard ist true.

extensions

Wenn eine angegebene Datei nicht existiert, wird versucht, eine der angegebenen Erweiterungen in der angegebenen Reihenfolge anzuhängen. Standardmäßig ist dies deaktiviert (auf false gesetzt). Ein Beispielwert, der Dateien ohne Erweiterung als HTML ausliefert: ['html', 'htm']. Dies wird übersprungen, wenn die angeforderte Datei bereits eine Erweiterung hat.

immutable

Aktiviert oder deaktiviert die immutable-Direktive im Cache-Control-Antwort- Header, Standard ist false. Wenn auf true gesetzt, sollte auch die maxAge-Option angegeben werden, um Caching zu ermöglichen. Die immutable-Direktive verhindert, dass unterstützte Clients während der Laufzeit der maxAge-Option bedingte Anfragen stellen, um zu prüfen, ob sich die Datei geändert hat.

index

Standardmäßig unterstützt send "index.html"-Dateien; um dies zu deaktivieren, setzen Sie false, oder um einen neuen Index anzugeben, übergeben Sie einen String oder ein Array in der bevorzugten Reihenfolge.

lastModified

Aktiviert oder deaktiviert den Last-Modified-Header, Standard ist true. Verwendet den zuletzt geänderten Wert des Dateisystems.

maxAge

Gibt eine max-age in Millisekunden für HTTP-Caching an, Standard ist 0. Dies kann auch ein String sein, der vom ms-Modul akzeptiert wird.

maxContentRangeChunkSize

Gibt die maximale Größe des Antwortinhalts an, Standard ist die gesamte Dateigröße. Dies wird verwendet, wenn acceptRanges true ist.

onFile

Wird mit dem absoluten Pfad der letztendlich ausgewählten Datei und den Dateisystem-Statistiken nach der Dateiauflösung aufgerufen, aber vor der Antwortverarbeitung und der Erstellung des Dateistreams. Der Callback kann synchron sein oder ein Promise zurückgeben. Wenn er ein Promise zurückgibt, wartet send auf dessen Abschluss. Wenn der Callback eine Ausnahme wirft oder sein zurückgegebenes Promise abgelehnt wird, wird der Vorgang abgebrochen und send() wird abgelehnt.

root

Liefert Dateien relativ zu path aus.

start

Byte-Offset, an dem der Stream beginnt, Standard ist 0. Der Start ist inklusiv, das heißt start: 2 schließt das 3. Byte im Stream ein.

highWaterMark

Wenn angegeben, legt diese Option die maximale Anzahl von Bytes fest, die der interne Puffer hält, bevor das Lesen aus der zugrunde liegenden Ressource pausiert wird. Wenn Sie diese Option weglassen (oder undefined übergeben), greift Node.js auf seinen integrierten Standard für lesbare Binärstreams zurück.

.mime

Der mime-Export ist die globale Instanz des mime-npm-Moduls.

Dies wird verwendet, um die MIME-Typen zu konfigurieren, die Dateiendungen zugeordnet sind, sowie andere Optionen dafür, wie der MIME-Typ einer Datei aufgelöst wird (wie der Standardtyp, der für eine unbekannte Dateiendung verwendet wird).

Caching

Es führt kein internes Caching durch; Sie sollten hierfür einen Reverse-Proxy-Cache wie Varnish verwenden oder diese schicken Dinger namens CDNs. Wenn Ihre Anwendung klein genug ist, dass sie von einem Single-Node-Memory-Caching profitieren würde, ist sie klein genug, dass sie überhaupt kein Caching benötigt ;).

Debugging

Um die Ausgabe der debug()-Instrumentierung zu aktivieren, exportieren Sie NODE_DEBUG:

$ NODE_DEBUG=send node app

Tests ausführen

$ npm install
$ npm test

Beispiele

Eine bestimmte Datei bereitstellen

Dieses einfache Beispiel sendet eine bestimmte Datei an alle Anfragen.

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)

Alle Dateien aus einem Verzeichnis bereitstellen

Dieses einfache Beispiel stellt einfach alle Dateien in einem gegebenen Verzeichnis als oberste Ebene bereit. Zum Beispiel wird eine Anfrage GET /foo.txt die Datei /www/public/foo.txt zurücksenden.

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)
})