@fastify/compress 9.1.1 → 9.2.0

package/.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    uses: fastify/workflows/.github/workflows/plugins-ci.yml@2073dc8e1f9e172bf42daa3843c9dbd31af1e8cb # v6.0.0
+    uses: fastify/workflows/.github/workflows/plugins-ci.yml@ef591e2186785d5ab36b9fe6a79c7ce2f1d94e57 # v7.0.0
     with:
       license-check: true
       lint: true

package/.github/workflows/lock-threads.yml

@@ -16,4 +16,4 @@ jobs:
     permissions:
       issues: write
       pull-requests: write
-    uses: fastify/workflows/.github/workflows/lock-threads.yml@2073dc8e1f9e172bf42daa3843c9dbd31af1e8cb # v6.0.0
+    uses: fastify/workflows/.github/workflows/lock-threads.yml@ef591e2186785d5ab36b9fe6a79c7ce2f1d94e57 # v7.0.0

package/README.md

@@ -167,6 +167,84 @@ await fastify.register(
   { threshold: 2048 }
 )
 ```
+### syncThreshold
+The maximum byte size for compressing a response synchronously. Defaults to a value derived
+from `os.availableParallelism()`, between `4096` and `65536`.
+
+Payloads that are already fully in memory (a `string` or a `Buffer`) and are not larger than
+`syncThreshold` are compressed in one call instead of being pushed through a compression
+stream. This is faster for small responses — a per-response zlib stream costs more in setup
+and scheduling than the compression itself at these sizes — and it uses much less memory
+while the response is in flight, since no zlib context is allocated and the source payload
+is released immediately.
+
+Larger payloads, streams, [web `ReadableStream`s](#supported-payload-types) and fetch
+`Response`s always use the streaming path, so the event loop is never held for long. Set
+`syncThreshold` to `0` to compress every response through the streaming path.
+
+```js
+await fastify.register(
+  import('@fastify/compress'),
+  { syncThreshold: 65536 }
+)
+```
+
+#### How the default is chosen
+
+The streaming path hands compression to libuv's 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 to win, so the default
+shrinks as the host gets wider:
+
+| cores reported | default |
+| --- | --- |
+| 1 | `65536` |
+| 2 | `8192` |
+| 3 or more | `4096` |
+
+The scale stops at four because libuv's threadpool defaults to four threads: beyond that,
+extra cores cannot compress any more responses in parallel. The value is computed once at
+startup and is always overridden by an explicit `syncThreshold`.
+
+The memory saving does not depend on payload size — it comes from not allocating a zlib
+context per in-flight response — so it is retained in full even at the lowest default.
+
+#### Raising it on CPU-constrained deployments
+
+Since libuv 1.49 (Node.js 22.12), `os.availableParallelism()` accounts for a cgroup CPU
+quota, so a container limited to whole cores reports those rather than the host's and gets
+an appropriate default on its own. Two cases still read as a wide host and so get the
+smallest default:
+
+| deployment | reported | why |
+| --- | --- | --- |
+| Node.js before 22.12 | host cores | the quota is not consulted at all |
+| a quota below one core, e.g. Kubernetes `cpu: 500m` | host cores | the quota floors to zero and falls back to the host count |
+
+Both are precisely the deployments that benefit most from compressing synchronously: with
+little or no spare CPU, there is nothing for the streaming path to overlap with. Quotas are
+also floored rather than rounded, so `cpu: 2500m` reports two cores.
+
+If either applies to you, set `syncThreshold` explicitly:
+
+```js
+await fastify.register(
+  import('@fastify/compress'),
+  // a container pinned to ~1 CPU behaves like a single core host
+  { syncThreshold: 65536 }
+)
+```
+
+The default is biased towards the low end on purpose: choosing too low a value only forgoes
+part of the possible throughput gain, while choosing too high a value costs considerably
+more than it can ever return.
+
+Because the compressed size is known upfront, responses compressed synchronously carry an
+accurate `Content-Length` instead of being sent with chunked transfer encoding. Replies that
+already carry a `Content-Length` the plugin has been asked to keep
+(see [removeContentLengthHeader](#manage-content-length-header-removal-with-removecontentlengthheader))
+use the streaming path so the provided value is preserved.
+
 ### customTypes
 [mime-db](https://github.com/jshttp/mime-db) determines if a `content-type` should be compressed. Additional content types can be compressed via regex or a function.
 
@@ -268,6 +346,12 @@ By default, `@fastify/compress` removes the reply `Content-Length` header. Chang
   )
 ```
 
+This option exists because the streaming path cannot know the compressed size upfront, so
+the reply `Content-Length` would otherwise describe the uncompressed payload. Responses
+taking the [synchronous path](#syncthreshold) do know the compressed size and always send an
+accurate `Content-Length`; a reply that already carries a `Content-Length` and sets
+`removeContentLengthHeader` to `false` is streamed instead, so the provided value is kept.
+
 ## Usage - Decompress request payloads
 This plugin adds a `preParsing` hook to decompress the request payload based on the `content-encoding` request header.
 

package/benchmark/sync-compression.mjs

@@ -0,0 +1,282 @@
+// Measures the synchronous compression path (`syncThreshold`) against the stream
+// pipeline it replaces for small buffered payloads.
+//
+//   node benchmark/sync-compression.mjs
+//   node benchmark/sync-compression.mjs --conns 100 --reps 5 --duration 8000
+//
+// Both configurations run against the same build: the baseline registers the plugin
+// with `syncThreshold: 0`, which always streams, and the candidate uses the default.
+//
+// A few things this harness deliberately does, because getting any of them wrong
+// produces numbers that look meaningful but are not:
+//
+//   * The server runs in a forked process. Compressing synchronously occupies the
+//     event loop, so a client sharing that loop would measure itself as much as
+//     the server.
+//   * Requests go over real sockets with real concurrency. `inject()` has neither,
+//     and cannot observe that the stream path hands work to the libuv threadpool
+//     and so overlaps with other cores.
+//   * Every size is measured several times, alternating between the two
+//     configurations, and reported as a median with its spread.
+//   * A control payload larger than the threshold is always included. Both
+//     configurations stream it, so its result must come out near zero. When it
+//     does not, the machine was too noisy and the whole run is rejected.
+
+import { fork } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { availableParallelism, loadavg } from 'node:os'
+import { gzipSync } from 'node:zlib'
+import http from 'node:http'
+import { performance } from 'node:perf_hooks'
+
+const require = createRequire(import.meta.url)
+
+// Payload sizes must straddle the threshold: the last one is the control.
+const CONTROL_SIZE = 131072
+const DEFAULT_SIZES = [1024, 2048, 4096, 8192, CONTROL_SIZE]
+// Above this, the control row is too far off for the run to mean anything.
+const CONTROL_TOLERANCE = 0.1
+const TARGET_RATIO = 8
+
+function parseArgs (argv) {
+  const args = {
+    conns: 50,
+    duration: 5000,
+    reps: 3,
+    warmup: 1000,
+    sizes: DEFAULT_SIZES
+  }
+  for (let i = 0; i < argv.length; i += 2) {
+    const key = argv[i].replace(/^--/, '')
+    const value = argv[i + 1]
+    if (!(key in args)) throw new Error(`Unknown option: ${argv[i]}`)
+    args[key] = key === 'sizes'
+      ? value.split(',').map(Number)
+      : Number(value)
+  }
+  return args
+}
+
+// Deterministic payload with a realistic compression ratio. Content structure drives
+// compression cost far more than length does, so a fixed ratio keeps sizes comparable.
+function makePayload (byteCount, randomFraction) {
+  const data = Buffer.alloc(byteCount)
+  let state = 0x12345678
+  for (let i = 0; i < byteCount; i++) {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0
+    if (state / 0x100000000 < randomFraction) data[i] = state >>> 24
+  }
+  return data
+}
+
+function makePayloadAtRatio (byteCount, ratio) {
+  let low = 0
+  let high = 1
+  let best
+  for (let i = 0; i < 20; i++) {
+    const fraction = (low + high) / 2
+    const payload = makePayload(byteCount, fraction)
+    const actual = byteCount / gzipSync(payload).byteLength
+    if (!best || Math.abs(actual - ratio) < Math.abs(best.ratio - ratio)) {
+      best = { payload, ratio: actual }
+    }
+    if (actual > ratio) low = fraction
+    else high = fraction
+  }
+  return best
+}
+
+/* ------------------------------------------------------------------ server role */
+
+if (process.env.BENCHMARK_ROLE === 'server') {
+  const Fastify = require('fastify')
+  const compress = require('../index.js')
+
+  const size = Number(process.env.BENCHMARK_SIZE)
+  const syncThreshold = process.env.BENCHMARK_SYNC_THRESHOLD === 'default'
+    ? undefined
+    : Number(process.env.BENCHMARK_SYNC_THRESHOLD)
+
+  const { payload } = makePayloadAtRatio(size, TARGET_RATIO)
+  const body = payload.toString('latin1')
+
+  const app = Fastify()
+  const options = { global: true }
+  if (syncThreshold !== undefined) options.syncThreshold = syncThreshold
+  await app.register(compress, options)
+
+  app.get('/payload', async (_request, reply) => {
+    reply.type('text/plain')
+    return body
+  })
+
+  const address = await app.listen({ port: 0, host: '127.0.0.1' })
+  const port = Number(new URL(address).port)
+
+  process.on('message', (message) => {
+    if (message === 'rss') process.send({ rssMiB: process.memoryUsage().rss / 1048576 })
+  })
+  process.send({ ready: true, port })
+} else {
+  await main()
+}
+
+/* ------------------------------------------------------------------ client role */
+
+function startServer (size, syncThreshold) {
+  return new Promise((resolve, reject) => {
+    const child = fork(import.meta.filename, [], {
+      env: {
+        ...process.env,
+        BENCHMARK_ROLE: 'server',
+        BENCHMARK_SIZE: String(size),
+        BENCHMARK_SYNC_THRESHOLD: String(syncThreshold)
+      },
+      stdio: ['ignore', 'ignore', 'inherit', 'ipc']
+    })
+    const onMessage = (message) => {
+      if (message.ready) {
+        child.off('message', onMessage)
+        resolve({ child, port: message.port })
+      }
+    }
+    child.on('message', onMessage)
+    child.once('error', reject)
+    child.once('exit', (code) => reject(new Error(`benchmark server exited early (${code})`)))
+  })
+}
+
+function rssOf (child) {
+  return new Promise((resolve) => {
+    const onMessage = (message) => {
+      if (message.rssMiB !== undefined) {
+        child.off('message', onMessage)
+        resolve(message.rssMiB)
+      }
+    }
+    child.on('message', onMessage)
+    child.send('rss')
+  })
+}
+
+function get (port, agent) {
+  return new Promise((resolve, reject) => {
+    const request = http.get(
+      { host: '127.0.0.1', port, path: '/payload', agent, headers: { 'accept-encoding': 'gzip' } },
+      (response) => {
+        response.resume()
+        response.once('end', () => resolve(response.headers['content-encoding']))
+        response.once('error', reject)
+      }
+    )
+    request.once('error', reject)
+  })
+}
+
+async function measure (port, { conns, duration, warmup }) {
+  const agent = new http.Agent({ keepAlive: true, maxSockets: conns })
+  const countFrom = performance.now() + warmup
+  const stopAt = countFrom + duration
+  let completed = 0
+  let encoding
+
+  // Requests keep flowing across the warmup boundary, so the measured window sees a
+  // server already at steady state rather than one still filling its connection pool.
+  const workers = Array.from({ length: conns }, async () => {
+    while (performance.now() < stopAt) {
+      encoding = await get(port, agent)
+      if (performance.now() >= countFrom) completed++
+    }
+  })
+
+  await Promise.all(workers)
+  agent.destroy()
+
+  return { reqPerSec: completed / (duration / 1000), encoding }
+}
+
+async function runCase (size, syncThreshold, args) {
+  const { child, port } = await startServer(size, syncThreshold)
+  try {
+    const result = await measure(port, args)
+    return { ...result, rssMiB: await rssOf(child) }
+  } finally {
+    child.kill('SIGKILL')
+  }
+}
+
+// Declared as a function so it is hoisted above the top-level `main()` call.
+function median (values) {
+  const sorted = [...values].sort((a, b) => a - b)
+  return sorted[Math.floor(sorted.length / 2)]
+}
+
+function formatSize (bytes) {
+  return bytes >= 1024 ? `${bytes / 1024} KiB` : `${bytes} B`
+}
+
+async function main () {
+  const args = parseArgs(process.argv.slice(2))
+  const { computeSyncThreshold } = require('../lib/utils.js')
+  const cores = availableParallelism()
+  const computed = computeSyncThreshold()
+
+  console.log('@fastify/compress — synchronous compression path')
+  console.log(`node ${process.version}  ${process.platform}/${process.arch}  ${cores} cores`)
+  console.log(`computed default syncThreshold: ${computed} bytes`)
+  console.log(`${args.conns} connections, ${args.duration} ms x ${args.reps} reps, target ratio ${TARGET_RATIO}:1\n`)
+
+  const load = loadavg()[0]
+  if (load > cores / 4) {
+    console.log(`WARNING: 1-minute load average is ${load.toFixed(2)} on ${cores} cores.`)
+    console.log('Results from a busy machine are not meaningful. Wait for it to settle.\n')
+  }
+
+  const results = new Map(args.sizes.map((size) => [size, { baseline: [], candidate: [] }]))
+
+  for (let rep = 1; rep <= args.reps; rep++) {
+    for (const size of args.sizes) {
+      // Alternate within a rep so slow drift hits both configurations equally.
+      const baseline = await runCase(size, 0, args)
+      const candidate = await runCase(size, 'default', args)
+      if (baseline.encoding !== 'gzip' || candidate.encoding !== 'gzip') {
+        throw new Error(`payload of ${size} B was not compressed — check the plugin threshold`)
+      }
+      results.get(size).baseline.push(baseline)
+      results.get(size).candidate.push(candidate)
+    }
+    console.log(`rep ${rep}/${args.reps} done`)
+  }
+
+  console.log('\npayload      streamed r/s   default r/s     change   streamed RSS   default RSS')
+  let controlChange = 0
+  for (const size of args.sizes) {
+    const { baseline, candidate } = results.get(size)
+    const base = median(baseline.map((r) => r.reqPerSec))
+    const cand = median(candidate.map((r) => r.reqPerSec))
+    const change = cand / base - 1
+    const isControl = size > Math.max(computed, ...args.sizes.filter((s) => s <= computed))
+    if (isControl) controlChange = Math.max(controlChange, Math.abs(change))
+    console.log(
+      formatSize(size).padEnd(12) +
+      base.toFixed(0).padStart(12) +
+      cand.toFixed(0).padStart(14) +
+      `${(change * 100).toFixed(0)}%`.padStart(11) +
+      `${median(baseline.map((r) => r.rssMiB)).toFixed(0)} MiB`.padStart(15) +
+      `${median(candidate.map((r) => r.rssMiB)).toFixed(0)} MiB`.padStart(14) +
+      (isControl ? '   <- control, expect ~0%' : '')
+    )
+  }
+
+  // The control streams in both configurations, so anything other than a near-zero
+  // result means the measurement environment, not the plugin, moved the numbers.
+  console.log('')
+  if (controlChange > CONTROL_TOLERANCE) {
+    console.log(`REJECTED: control moved by ${(controlChange * 100).toFixed(0)}%, above the ${CONTROL_TOLERANCE * 100}% tolerance.`)
+    console.log('Both configurations stream that payload, so the difference is machine noise.')
+    console.log('Re-run on an idle machine, or raise --reps, before drawing conclusions.')
+    process.exitCode = 1
+  } else {
+    console.log(`Control within ${(CONTROL_TOLERANCE * 100).toFixed(0)}% — run looks valid.`)
+  }
+}

package/index.js

@@ -11,6 +11,7 @@ const { Minipass } = require('minipass')
 const { Readable } = require('readable-stream')
 
 const {
+  computeSyncThreshold,
   isStream,
   isGzip,
   isDeflate,
@@ -22,6 +23,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 +133,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 +160,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 +203,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 +329,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 +376,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 +487,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 +527,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 +535,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))
     }
 

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 (
@@ -192,6 +232,7 @@ function createPeekTransform (swapStream, peekSize = 10) {
 }
 
 module.exports = {
+  computeSyncThreshold,
   isZstd,
   isGzip,
   isDeflate,