@fastify/compress 9.1.0 → 9.2.0

package/lib/utils.js

@@ -1,8 +1,48 @@
 'use strict'
 
 const { Readable: NodeReadable } = require('node:stream')
+const { availableParallelism } = require('node:os')
 const { Transform } = require('readable-stream')
 
+// 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) {
   return (
@@ -64,6 +104,14 @@ function webStreamToNodeReadable (webStream) {
   return NodeReadable.fromWeb(webStream)
 }
 
+function unwrapFetchResponse (reply, response) {
+  reply.code(response.status)
+  for (const [name, value] of response.headers) {
+    reply.header(name, value)
+  }
+  return response.body
+}
+
 /**
  * Provide a async iteratable for Readable.from
  */
@@ -184,6 +232,7 @@ function createPeekTransform (swapStream, peekSize = 10) {
 }
 
 module.exports = {
+  computeSyncThreshold,
   isZstd,
   isGzip,
   isDeflate,
@@ -192,5 +241,6 @@ module.exports = {
   isWebReadableStream,
   isFetchResponse,
   webStreamToNodeReadable,
+  unwrapFetchResponse,
   createPeekTransform
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/compress",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "Fastify compression utils",
   "main": "index.js",
   "type": "commonjs",
@@ -14,8 +14,8 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
-    "adm-zip": "^0.5.12",
-    "c8": "^11.0.0",
+    "adm-zip": "^0.6.0",
+    "c8": "^12.0.0",
     "eslint": "^9.17.0",
     "fastify": "^5.0.0",
     "jsonstream": "^1.0.3",
@@ -26,6 +26,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

@@ -288,6 +288,128 @@ describe('When `global` is not set, it is `true` by default :', async () => {
     t.assert.equal(payload.toString('utf-8'), body)
   })
 
+  test('it should preserve a Fetch API Response status and headers', async (t) => {
+    t.plan(5)
+
+    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(body, {
+        status: 201,
+        headers: {
+          'content-type': 'text/plain',
+          'cache-control': 'public, max-age=120',
+          'set-cookie': 'a=b; HttpOnly'
+        }
+      }))
+    })
+
+    const response = await fastify.inject({
+      url: '/fetch-resp',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    t.assert.equal(response.statusCode, 201)
+    t.assert.equal(response.headers['content-type'], 'text/plain')
+    t.assert.equal(response.headers['cache-control'], 'public, max-age=120')
+    t.assert.equal(response.headers['set-cookie'], 'a=b; HttpOnly')
+    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)
 
@@ -2005,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) => {
@@ -2069,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) => {
@@ -2821,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

@@ -364,6 +364,49 @@ test('reply.compress should handle Fetch Response', async (t) => {
   t.assert.equal(zlib.gunzipSync(res.rawPayload).toString('utf8'), 'from reply.compress')
 })
 
+test('reply.compress should preserve a Fetch Response status and headers', async (t) => {
+  t.plan(4)
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, { global: true, threshold: 0 })
+  fastify.get('/', (_req, reply) => {
+    reply.compress(new Response('from reply.compress', {
+      status: 418,
+      headers: { 'content-type': 'text/plain', 'x-custom': 'kept' }
+    }))
+  })
+  const res = await fastify.inject({ url: '/', method: 'GET', headers: { 'accept-encoding': 'gzip' } })
+  t.assert.equal(res.statusCode, 418)
+  t.assert.equal(res.headers['content-type'], 'text/plain')
+  t.assert.equal(res.headers['x-custom'], 'kept')
+  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()