serve-buffer

Serve a Buffer via HTTP, with Range, conditional GET and GZip/Brotli compression support.

Note: If you want to serve files with support for Range, conditional GET and compression, use send. If you want to serve an entire directory of files, use serve-static.

There is a surprising number of difficult-to-understand corner cases in the HTTP RFCs. I tried my best here, so that others don't have to write quick-and-dirty (which in the HTTP realm usually means slightly wrong) implementations. This library supports the following request headers:

• Accept-Encoding
• Range & If-Range
• If-None-Match/If-Match & If-Modified-Since/If-Unmodified-Since

Installation

npm install serve-buffer

Usage

const express = require('express')
const serveBuffer = require('serve-buffer')

const app = express()

let data = Buffer.from('a lot of data here…', 'utf8')
app.use('/data', (req, res) => {
    serveBuffer(req, res, data)
})

// change buffer later
data = Buffer.from('entirely different buffer', 'utf8')

allow caching via timeModified & etag

const computeEtag = require('etag')

let data = Buffer.from('a lot of data here…', 'utf8')
let timeModified = new Date()
let etag = computeEtag(data)

app.use('/data', (req, res) => {
    serveBuffer(req, res, data, {timeModified, etag})
})

// change buffer later
data = Buffer.from('entirely different buffer', 'utf8')
timeModified = new Date()
etag = computeEtag(data)

serve gzipped & Brotli-compressed data

Serving compressed data reduces the amount of transferred data at the cost of higher CPU load, so it is usually worth it if your data rarely changes, or if you have slowly connected (or a lot of) consumers.

If buf is reasonably small (<=10mb for GZip, <= 512kb for Brotli), serve-buffer will compress it by default. If you don't want this, pass opt.gzip: false and/or opt.brotliCompress: false; Instead, you can also customise the size limits via opt.gzipMaxSize & opt.brotliCompressMaxSize.

If you never mutate the buffer(s) that you pass into serveBuffer, you can tell it to cache each buffer's compressed version as long as the instance exists (using a WeakMap) by passing opt.unmutatedBuffers: true:

const data = Buffer.from('a lot of data here…', 'utf8')
const timeModified = new Date()
const etag = computeEtag(data)

app.use('/data', (req, res) => {
    serveBuffer(req, res, data, {
        timeModified,
        etag,
        // Only do this if you never mutate `data`!
        unmutatedBuffers: true,
    })
})

API

serveBuffer(req, res, buf, opt = {}, cb = () => {})

opt overrides the default config, which looks like this:

{
    contentType: 'application/octet-stream',
    timeModified: new Date(),
    etag: require('etag')(buf),

    gzip: true, // or `false` or `async (buf) => ({compressedBuffer, compressedEtag})`
    gzipMaxSize: 10 * 1024 * 1024, // 10mb
    brotliCompress: true, // or `false` or `async (buf) => ({compressedBuffer, compressedEtag})`
    brotliCompressMaxSize: 512 * 1024, // 512kb
    // Assume that Buffers passed in as `buf` never get mutated? If `true`, each compressed buffer & compressed ETag will be cached as long as the buffer instance exists.
    unmutatedBuffers: false,

    cacheControl: true, // send cache-control header?
    maxAge: 0, // for cache-control, in milliseconds
    immutable: false, // for cache-control

    // hook functions for modifying serve-buffer's behavior
    beforeSend: (req, res, body, opt) => {},
}

cb will be called once the response headers and body (if applicable) have been sent.

Related

• send-stream – Streaming file server with Range and conditional-GET support from file system or other streaming sources. (Very similar to serve-buffer.)
• send – Streaming static file server with Range and conditional-GET support
• http-file-response – Send a file back as a HTTP response with support for range queries etc.

Contributing

If you have a question or need support using serve-buffer, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, use the issues page.