@fastify/compress 9.1.1 → 9.2.1

package/index.js

@@ -2,15 +2,14 @@
 
 const zlib = require('node:zlib')
 const { inherits, format } = require('node:util')
-const { pipeline, compose } = require('node:stream')
+const { pipeline, compose, Readable, PassThrough } = require('node:stream')
 
 const fp = require('fastify-plugin')
 const encodingNegotiator = require('@fastify/accept-negotiator')
 const mimedb = require('mime-db')
-const { Minipass } = require('minipass')
-const { Readable } = require('readable-stream')
 
 const {
+  computeSyncThreshold,
   isStream,
   isGzip,
   isDeflate,
@@ -22,6 +21,10 @@ const {
   createPeekTransform
 } = require('./lib/utils')
 
+// The default depends on how much parallelism the host offers, which cannot change while
+// the process runs, so it is computed once here rather than per registration or per request
+const defaultSyncThreshold = computeSyncThreshold()
+
 const InvalidRequestEncodingError = createError('FST_CP_ERR_INVALID_CONTENT_ENCODING', 'Unsupported Content-Encoding: %s', 415)
 const InvalidRequestCompressedPayloadError = createError('FST_CP_ERR_INVALID_CONTENT', 'Could not decompress the request payload using the provided encoding', 400)
 
@@ -128,13 +131,20 @@ function processCompressParams (opts) {
   }
 
   params.removeContentLengthHeader = typeof opts.removeContentLengthHeader === 'boolean' ? opts.removeContentLengthHeader : true
-  params.brotliOptions = params.global
-    ? { ...recommendedDefaultBrotliOptions, ...opts.brotliOptions }
-    : opts.brotliOptions
+  // The recommended defaults apply whatever the value of `global` is: with
+  // `global: false` the compression still runs, just through `reply.compress()`,
+  // and falling back to zlib's default quality of 11 there is needlessly slow.
+  params.brotliOptions = { ...recommendedDefaultBrotliOptions, ...opts.brotliOptions }
   params.zlibOptions = opts.zlibOptions
   params.onUnsupportedEncoding = opts.onUnsupportedEncoding
   params.inflateIfDeflated = opts.inflateIfDeflated === true
   params.threshold = typeof opts.threshold === 'number' ? opts.threshold : 1024
+  // Upper size bound of the synchronous compression path. Unlike `threshold`, which is a
+  // lower bound, this one is a ceiling: bigger payloads keep using the stream pipeline.
+  // The default scales with the parallelism the host can offer the stream path, see
+  // `computeSyncThreshold()`. An explicit value is always used as is, and `0` disables
+  // the synchronous path entirely.
+  params.syncThreshold = typeof opts.syncThreshold === 'number' ? opts.syncThreshold : defaultSyncThreshold
   params.compressibleTypes = opts.customTypes instanceof RegExp
     ? opts.customTypes.test.bind(opts.customTypes)
     : typeof opts.customTypes === 'function'
@@ -148,6 +158,22 @@ function processCompressParams (opts) {
   if (typeof ((opts.zlib || zlib).createZstdCompress || zlib.createZstdCompress) === 'function') {
     params.compressStream.zstd = () => ((opts.zlib || zlib).createZstdCompress || zlib.createZstdCompress)(params.zlibOptions)
   }
+  // Synchronous counterparts of `params.compressStream`, used for small buffered payloads.
+  // Encodings without a usable synchronous method are left out of the map so that they
+  // keep flowing through the stream pipeline.
+  params.compressSync = {}
+  for (const [encoding, streamMethod, syncMethod, options] of [
+    ['br', 'createBrotliCompress', 'brotliCompressSync', params.brotliOptions],
+    ['gzip', 'createGzip', 'gzipSync', params.zlibOptions],
+    ['deflate', 'createDeflate', 'deflateSync', params.zlibOptions],
+    ['zstd', 'createZstdCompress', 'zstdCompressSync', params.zlibOptions]
+  ]) {
+    const compressSync = resolveSyncCompressor(opts.zlib, streamMethod, syncMethod, options)
+    if (compressSync !== undefined) {
+      params.compressSync[encoding] = compressSync
+    }
+  }
+
   params.uncompressStream = {
     // Currently params.uncompressStream.br() is never called as we do not have any way to autodetect brotli compression in `fastify-compress`
     // Brotli documentation reference: [RFC 7932](https://www.rfc-editor.org/rfc/rfc7932)
@@ -175,6 +201,54 @@ function processCompressParams (opts) {
   return params
 }
 
+// Resolve the synchronous counterpart of a stream compressor.
+// A synchronous method is only picked when it comes from the same `zlib` implementation the
+// stream path would have used, so a custom `zlib` exposing just the stream constructor is
+// never bypassed: its encoding simply keeps using the stream pipeline.
+function resolveSyncCompressor (customZlib, streamMethod, syncMethod, options) {
+  let compressSync
+
+  if (customZlib != null && typeof customZlib[syncMethod] === 'function') {
+    compressSync = customZlib[syncMethod]
+  } else if ((customZlib == null || typeof customZlib[streamMethod] !== 'function') && typeof zlib[syncMethod] === 'function') {
+    // `zlib.zstdCompressSync` is only available on Node.js 22.15+/23.8+
+    compressSync = zlib[syncMethod]
+  } else {
+    return undefined
+  }
+
+  return (payload) => compressSync(payload, options)
+}
+
+// Compress an already buffered payload inline, bypassing the stream pipeline.
+// Small payloads are much cheaper to compress this way: no zlib context and no stream
+// pipeline are allocated per response, and the source payload is released immediately
+// instead of being pinned for as long as the response is in flight.
+// Returns `null` when the payload is not eligible and must be streamed instead.
+function compressPayloadSync (params, reply, encoding, payload, payloadSize) {
+  if (params.syncThreshold <= 0 || payloadSize > params.syncThreshold) return null
+
+  const compressSync = params.compressSync[encoding]
+  if (compressSync === undefined) return null
+
+  // Only strings and Buffers are fully buffered and can be compressed in one go.
+  // Fastify already turns every other buffered payload type into one of those two
+  // before this point, so this is a safety net rather than a reachable path.
+  /* c8 ignore next */
+  if (typeof payload !== 'string' && !Buffer.isBuffer(payload)) return null
+
+  // Fastify recomputes `content-length` for buffered payloads, so a caller provided value
+  // that the plugin has been asked to keep can only be honoured by the stream path
+  if (params.removeContentLengthHeader === false && reply.getHeader('content-length') !== undefined) return null
+
+  const buffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload)
+
+  // Mirror `zipStream()` and pass already gzip or deflate compressed payloads through as is
+  if (isCompressed(buffer) !== 0) return buffer
+
+  return compressSync(buffer)
+}
+
 function processDecompressParams (opts) {
   /* c8 ignore next 3 */
   if (!opts) {
@@ -253,14 +327,18 @@ function buildRouteCompress (_fastify, params, routeOptions, decorateOnly) {
   }
 
   function onSend (req, reply, payload, next) {
+    if (isFetchResponse(payload)) {
+      payload = unwrapFetchResponse(reply, payload)
+    }
+
     if (payload == null) {
-      return next()
+      return next(null, payload)
     }
 
     const responseEncoding = reply.getHeader('Content-Encoding')
     if (responseEncoding && responseEncoding !== 'identity') {
       // response is already compressed
-      return next()
+      return next(null, payload)
     }
 
     let stream, encoding
@@ -296,16 +374,30 @@ function buildRouteCompress (_fastify, params, routeOptions, decorateOnly) {
     }
 
     if (typeof payload.pipe !== 'function') {
-      if (isFetchResponse(payload)) {
-        payload = unwrapFetchResponse(reply, payload)
-      }
-
       if (isWebReadableStream(payload)) {
         payload = webStreamToNodeReadable(payload)
       } else {
-        if (Buffer.byteLength(payload) < params.threshold) {
+        const payloadSize = Buffer.byteLength(payload)
+        if (payloadSize < params.threshold) {
           return next()
         }
+
+        let compressedPayload = null
+        try {
+          compressedPayload = compressPayloadSync(params, reply, encoding, payload, payloadSize)
+        } catch (err) {
+          return next(err)
+        }
+
+        if (compressedPayload !== null) {
+          setVaryHeader(reply)
+          reply.header('Content-Encoding', encoding)
+          // The compressed size is known on this path, so an accurate `content-length` is
+          // set instead of dropping the header and falling back to a chunked response
+          reply.header('Content-Length', compressedPayload.length)
+          return next(null, compressedPayload)
+        }
+
         payload = Readable.from(intoAsyncIterator(payload))
       }
     }
@@ -393,6 +485,14 @@ function compress (params) {
       return
     }
 
+    if (isFetchResponse(payload)) {
+      if (payload.body === null) {
+        return this.send(payload)
+      }
+
+      payload = unwrapFetchResponse(this, payload)
+    }
+
     let stream, encoding
     const noCompress =
       // don't compress on x-no-compression header
@@ -425,10 +525,6 @@ function compress (params) {
     }
 
     if (typeof payload.pipe !== 'function') {
-      if (isFetchResponse(payload)) {
-        payload = unwrapFetchResponse(this, payload)
-      }
-
       if (isWebReadableStream(payload)) {
         payload = webStreamToNodeReadable(payload)
       } else if (!Buffer.isBuffer(payload) && typeof payload !== 'string') {
@@ -437,9 +533,27 @@ function compress (params) {
     }
 
     if (typeof payload.pipe !== 'function') {
-      if (Buffer.byteLength(payload) < params.threshold) {
+      const payloadSize = Buffer.byteLength(payload)
+      if (payloadSize < params.threshold) {
         return this.send(payload)
       }
+
+      let compressedPayload = null
+      try {
+        compressedPayload = compressPayloadSync(params, this, encoding, payload, payloadSize)
+      } catch (err) {
+        return this.send(err)
+      }
+
+      if (compressedPayload !== null) {
+        setVaryHeader(this)
+        this.header('Content-Encoding', encoding)
+        // The compressed size is known on this path, so an accurate `content-length` is
+        // set instead of dropping the header and falling back to a chunked response
+        this.header('Content-Length', compressedPayload.length)
+        return this.send(compressedPayload)
+      }
+
       payload = Readable.from(intoAsyncIterator(payload))
     }
 
@@ -565,8 +679,8 @@ function maybeUnzip (payload, serialize) {
 function zipStream (deflate, encoding) {
   return createPeekTransform(function (data) {
     switch (isCompressed(data)) {
-      case 1: return new Minipass()
-      case 2: return new Minipass()
+      case 1: return new PassThrough()
+      case 2: return new PassThrough()
     }
     return deflate[encoding]()
   })
@@ -582,7 +696,7 @@ function unzipStream (inflate, maxRecursion) {
       case 1: return compose(inflate.gzip(), unzipStream(inflate, maxRecursion - 1))
       case 2: return compose(inflate.deflate(), unzipStream(inflate, maxRecursion - 1))
     }
-    return new Minipass()
+    return new PassThrough()
   })
 }
 

package/lib/utils.js

@@ -1,7 +1,46 @@
 'use strict'
 
-const { Readable: NodeReadable } = require('node:stream')
-const { Transform } = require('readable-stream')
+const { Readable: NodeReadable, Transform } = require('node:stream')
+const { availableParallelism } = require('node:os')
+
+// Bounds of the computed default synchronous compression threshold
+const MIN_SYNC_THRESHOLD = 4096
+const MAX_SYNC_THRESHOLD = 65536
+// libuv's threadpool defaults to 4 threads, so at most 4 stream compressions can make
+// progress at once however many cores the host reports. `UV_THREADPOOL_SIZE` can raise
+// it, but it is not something this default can rely on.
+const MAX_USEFUL_PARALLELISM = 4
+
+/**
+ * Compute the default upper size bound of the synchronous compression path.
+ *
+ * The stream path hands compression to the libuv threadpool, so it only pays off when
+ * there are spare cores to overlap that work with the event loop. The more cores are
+ * available for that overlap, the smaller the payload at which streaming starts winning:
+ * measured over real sockets, the crossover sits around 4 KiB with four or more cores,
+ * while on a single core the synchronous path stays ahead across the whole range.
+ *
+ * The threshold is therefore divided by 8 for every core beyond the first, and clamped.
+ * The divisor is deliberately steep because the two errors are not symmetric: settling
+ * too low only forgoes some of the throughput win, while settling too high costs far
+ * more than it ever gains.
+ *
+ * `availableParallelism()` accounts for a cgroup CPU quota since libuv 1.49 (Node 22.12),
+ * so a container limited to whole cores reports those rather than the host's. Two cases
+ * still read as a wide host and so land on the low end of the range:
+ *
+ *   - Node.js before 22.12, where the quota is not consulted at all;
+ *   - a quota below one full core, such as Kubernetes `cpu: 500m`, which floors to zero
+ *     and falls back to the host's core count.
+ *
+ * Both err towards the small end, which is the safe direction: settling too low only
+ * forgoes some of the win. Such deployments can raise `syncThreshold` explicitly.
+ */
+function computeSyncThreshold (parallelism = availableParallelism()) {
+  const usableCores = Math.min(parallelism, MAX_USEFUL_PARALLELISM)
+  const threshold = MAX_SYNC_THRESHOLD >> (3 * (usableCores - 1))
+  return Math.min(Math.max(threshold, MIN_SYNC_THRESHOLD), MAX_SYNC_THRESHOLD)
+}
 
 // https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1
 function isZstd (buffer) {
@@ -192,6 +231,7 @@ function createPeekTransform (swapStream, peekSize = 10) {
 }
 
 module.exports = {
+  computeSyncThreshold,
   isZstd,
   isGzip,
   isDeflate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/compress",
-  "version": "9.1.1",
+  "version": "9.2.1",
   "description": "Fastify compression utils",
   "main": "index.js",
   "type": "commonjs",
@@ -8,9 +8,7 @@
   "dependencies": {
     "@fastify/accept-negotiator": "^2.0.0",
     "fastify-plugin": "^6.0.0",
-    "mime-db": "^1.52.0",
-    "minipass": "^7.0.4",
-    "readable-stream": "^4.5.2"
+    "mime-db": "^1.52.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
@@ -26,6 +24,7 @@
   "scripts": {
     "lint": "eslint",
     "lint:fix": "eslint --fix",
+    "benchmark": "node benchmark/sync-compression.mjs",
     "test": "npm run test:unit && npm run test:typescript",
     "test:typescript": "tstyche",
     "test:unit": "node --test",

package/test/global-compress.test.js

@@ -318,6 +318,98 @@ describe('When `global` is not set, it is `true` by default :', async () => {
     t.assert.equal(zlib.gunzipSync(response.rawPayload).toString('utf-8'), body)
   })
 
+  test('it should not compress a Fetch API Response holding a non-compressible `Content-Type`', async (t) => {
+    t.plan(2)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { threshold: 0 })
+
+    const body = 'data: hello from fetch response\n\n'
+    fastify.get('/fetch-resp', (_request, reply) => {
+      reply.send(new Response(body, { headers: { 'content-type': 'text/event-stream' } }))
+    })
+
+    const response = await fastify.inject({
+      url: '/fetch-resp',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    t.assert.equal(response.headers['content-encoding'], undefined)
+    t.assert.equal(response.rawPayload.toString('utf-8'), body)
+  })
+
+  test('it should not compress a Fetch API Response that is already compressed', async (t) => {
+    t.plan(2)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { threshold: 0 })
+
+    const body = 'hello from fetch response'
+    fastify.get('/fetch-resp', (_request, reply) => {
+      reply.send(new Response(zlib.brotliCompressSync(body), {
+        headers: {
+          'content-type': 'text/plain',
+          'content-encoding': 'br'
+        }
+      }))
+    })
+
+    const response = await fastify.inject({
+      url: '/fetch-resp',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    t.assert.equal(response.headers['content-encoding'], 'br')
+    t.assert.equal(zlib.brotliDecompressSync(response.rawPayload).toString('utf-8'), body)
+  })
+
+  test('it should not compress a partial Fetch API Response', async (t) => {
+    t.plan(3)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { threshold: 0 })
+
+    const body = 'hello fr'
+    fastify.get('/fetch-resp', (_request, reply) => {
+      reply.send(new Response(body, {
+        status: 206,
+        headers: {
+          'content-type': 'text/plain',
+          'content-range': 'bytes 0-7/25'
+        }
+      }))
+    })
+
+    const response = await fastify.inject({
+      url: '/fetch-resp',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    t.assert.equal(response.statusCode, 206)
+    t.assert.equal(response.headers['content-encoding'], undefined)
+    t.assert.equal(response.rawPayload.toString('utf-8'), body)
+  })
+
+  test('it should send a bodyless Fetch API Response as is', async (t) => {
+    t.plan(3)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { threshold: 0 })
+
+    fastify.get('/fetch-resp', (_request, reply) => {
+      reply.send(new Response(null, { status: 204, headers: { 'x-custom': 'kept' } }))
+    })
+
+    const response = await fastify.inject({
+      url: '/fetch-resp',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    t.assert.equal(response.statusCode, 204)
+    t.assert.equal(response.headers['x-custom'], 'kept')
+    t.assert.equal(response.rawPayload.length, 0)
+  })
+
   test('it should compress a Web ReadableStream body', async (t) => {
     t.plan(1)
 
@@ -2035,11 +2127,14 @@ describe('It should support stream1 :', async () => {
 })
 
 describe('It should remove `Content-Length` header :', async () => {
+  // `./package.json` is small enough to be compressed synchronously, and the synchronous
+  // path knows the compressed size, so it replaces the stale `Content-Length` with an
+  // accurate one instead of removing it. `syncThreshold: 0` restores the streamed behaviour.
   test('using `reply.compress()`', async (t) => {
     t.plan(4)
 
     const fastify = Fastify()
-    await fastify.register(compressPlugin, { global: true })
+    await fastify.register(compressPlugin, { global: true, syncThreshold: 0 })
 
     fastify.get('/', (_request, reply) => {
       readFile('./package.json', 'utf8', (err, data) => {
@@ -2099,7 +2194,7 @@ describe('It should remove `Content-Length` header :', async () => {
     t.plan(4)
 
     const fastify = Fastify()
-    await fastify.register(compressPlugin, { global: true })
+    await fastify.register(compressPlugin, { global: true, syncThreshold: 0 })
 
     fastify.get('/', (_request, reply) => {
       readFile('./package.json', 'utf8', (err, data) => {
@@ -2851,6 +2946,70 @@ describe('It should send data compressed according to `brotliOptions` :', async
     const compressedPayload = zlib.brotliCompressSync(file, defaultBrotliOptions)
     t.assert.deepEqual(response.rawPayload, compressedPayload)
   })
+
+  test('default BROTLI_PARAM_QUALITY to be 4 when `global` is `false`', async (t) => {
+    t.plan(2)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { global: false })
+
+    const file = readFileSync('./package.json', 'utf8')
+    fastify.get('/', (_request, reply) => {
+      reply
+        .type('text/plain')
+        .compress(file)
+    })
+
+    const response = await fastify.inject({
+      url: '/',
+      method: 'GET',
+      headers: {
+        'accept-encoding': 'br'
+      }
+    })
+
+    const defaultBrotliOptions = {
+      params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 4 }
+    }
+    const compressedPayload = zlib.brotliCompressSync(file, defaultBrotliOptions)
+    t.assert.deepEqual(response.rawPayload, compressedPayload)
+
+    // zlib's own default of quality 11 is far more expensive and must not be used
+    const maxQualityPayload = zlib.brotliCompressSync(file)
+    t.assert.notDeepEqual(response.rawPayload, maxQualityPayload)
+  })
+
+  test('user supplied `brotliOptions` still take precedence when `global` is `false`', async (t) => {
+    t.plan(1)
+
+    const brotliOptions = {
+      params: {
+        [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+        [zlib.constants.BROTLI_PARAM_QUALITY]: 8
+      }
+    }
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { global: false, brotliOptions })
+
+    const file = readFileSync('./package.json', 'utf8')
+    fastify.get('/', (_request, reply) => {
+      reply
+        .type('text/plain')
+        .compress(file)
+    })
+
+    const response = await fastify.inject({
+      url: '/',
+      method: 'GET',
+      headers: {
+        'accept-encoding': 'br'
+      }
+    })
+
+    const compressedPayload = zlib.brotliCompressSync(file, brotliOptions)
+    t.assert.deepEqual(response.rawPayload, compressedPayload)
+  })
 })
 
 describe('It should send data compressed according to `zlibOptions` :', async () => {

package/test/regression/issue-350.test.js

@@ -22,7 +22,9 @@ async function routes (fastify) {
 
 test('should compress large payload without premature close', async (t) => {
   const fastify = Fastify()
-  await fastify.register(fastifyCompress, { encodings: ['gzip'], global: true })
+  // `syncThreshold: 0` keeps this payload on the stream pipeline this regression covers,
+  // whatever default the host parallelism would otherwise produce
+  await fastify.register(fastifyCompress, { encodings: ['gzip'], global: true, syncThreshold: 0 })
   await fastify.register(routes)
 
   const response = await fastify.inject({

package/test/routes-compress.test.js

@@ -381,6 +381,32 @@ test('reply.compress should preserve a Fetch Response status and headers', async
   t.assert.equal(zlib.gunzipSync(res.rawPayload).toString('utf8'), 'from reply.compress')
 })
 
+test('reply.compress should not compress a Fetch Response holding a non-compressible `Content-Type`', async (t) => {
+  t.plan(2)
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, { global: true, threshold: 0 })
+  fastify.get('/', (_req, reply) => {
+    reply.compress(new Response('data: from reply.compress\n\n', {
+      headers: { 'content-type': 'text/event-stream' }
+    }))
+  })
+  const res = await fastify.inject({ url: '/', method: 'GET', headers: { 'accept-encoding': 'gzip' } })
+  t.assert.equal(res.headers['content-encoding'], undefined)
+  t.assert.equal(res.rawPayload.toString('utf8'), 'data: from reply.compress\n\n')
+})
+
+test('reply.compress should send a bodyless Fetch Response as is', async (t) => {
+  t.plan(2)
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, { global: true, threshold: 0 })
+  fastify.get('/', (_req, reply) => {
+    reply.compress(new Response(null, { status: 204 }))
+  })
+  const res = await fastify.inject({ url: '/', method: 'GET', headers: { 'accept-encoding': 'gzip' } })
+  t.assert.equal(res.statusCode, 204)
+  t.assert.equal(res.rawPayload.length, 0)
+})
+
 test('reply.compress should handle Web ReadableStream', async (t) => {
   t.plan(1)
   const fastify = Fastify()