Repository navigation
http.compressionThreshold: docs say default 1200, shipped config sets 0 (compression off by default) #656
Description
Activity
Adding a second, distinct error found while fixing #655 — same root cause, but a separate wrong claim.
Two locations say streaming responses are compressed
regardless of this setting. They are not.reference/http/configuration.md:119- "Streaming query responses are always compressed for supporting clients, regardless of this setting (since their size is unknown upfront)."reference/http/overview.md:104- "Streaming query responses are always compressed for clients that support it."
The streaming compression branch sits inside the same gate as everything else.
server/serverHelpers/contentTypes.ts:let stream = serializer.serializer.serializeStream(responseData, responseObject); if (canCompress) { // <- same gate responseObject.headers.set('Content-Encoding', 'br'); stream = stream.pipe(createBrotliCompress({ ... }));
with
canCompress = COMPRESSION_THRESHOLD && ...accept-encoding...includes('br')at:373. So a falsy threshold disables compression for streaming responses too. There is no bypass.The "since their size is unknown upfront" reasoning is sound as far as it goes - a streaming response cannot be compared against a byte threshold, so the threshold is not applied as a size test. But it is still used as an on/off flag, which is exactly what the current wording denies.
So the fix has two parts, not one:
- The default value (
0shipped vs1200documented) - the original report above. - This: the threshold is a feature flag as well as a size threshold, and streaming responses are gated by it. Whatever the ruling on part 1, this sentence is wrong today in both places.
Both were verified against harper
origin/main. Full count of affected locations is six:configuration/options.md:37,http/configuration.md:111/:119/:123/:318,http/overview.md:104,configuration/operations.md:106.One caution for whoever picks this up: the v4 versioned copies under
reference_versioned_docs/version-v4/carry the same claims and should be checked against a v4 harper ref before editing - do not assume v4 also shipped0.sent with Claude Opus 5
What's wrong
The docs state that
http.compressionThresholddefaults to 1200 bytes, so Brotli response compression is on out of the box. Harper's shipped configuration sets it to 0, and the runtime treats 0 as "off" — so on a default install, Brotli response compression never happens.The root cause is not in this repo. Harper contradicts itself, and our docs faithfully mirror the half of it that isn't what actually ships.
Evidence (harper
origin/main)config-root.schema.json:25-31config-root.schema.json:774examplesblock:"compressionThreshold": 1200static/defaultConfig.yaml:4compressionThreshold: 0— this is what gets written into a new install's configvalidation/configValidator.ts:329compressionThreshold: number.optional()— no default injectedserver/serverHelpers/contentTypes.ts:362const COMPRESSION_THRESHOLD = envMgr.get(CONFIG_PARAMS.HTTP_COMPRESSIONTHRESHOLD)— no||fallback, so a configured 0 stays 0server/serverHelpers/contentTypes.ts:373canCompress = COMPRESSION_THRESHOLD && request.headers...includes('br')— 0 is falsy, so compression is skipped entirelySo the schema documents 1200, the shipped template sets 0, and the runtime honors 0. There is no code-level 1200 default anywhere.
Note this is specifically
http.compressionThreshold. The unrelatedstorage.compressionThreshold(LMDB record compression) does have a real code default —(storage.pageSize || 4096) - 60atresources/databases.ts:102— which makes this easy to conflate when grepping.Affected pages in this repo
reference/configuration/options.md:37- "Default:1200(bytes)"reference/http/configuration.md:111- thehttp.compressionThresholdsection, plus1200in examples at:123and:318reference/http/overview.md:104- "Compression applies when the response body exceeds the configuredcompressionThreshold(default 1200 bytes)"reference/configuration/operations.md:106-"compressionThreshold": 1200in a config response exampleThe question that has to be answered first
Is
compressionThreshold: 0in the shipped config intentional? The docs fix depends entirely on the answer, and the two outcomes are very different:static/defaultConfig.yaml. Our docs then need no change beyond possibly noting the versions affected.config-root.schema.jsonshould be corrected alongside.Either way one of the two harper locations is wrong, so this likely wants a companion harper issue; transferring or cross-linking is fine.
Why it matters beyond a wrong number
Two things downstream depend on this:
contentTypes.ts:410-425pipesserializeStream's return value intocreateBrotliCompress()whenevercanCompressis true, but theapplication/x-msgpackhandler returns aBuffer(not a stream) for a plain array.Accept: application/x-msgpack+Accept-Encoding: br+ an array body would throwTypeError: stream.pipe is not a function. That is currently unreachable only because compression ships disabled - so if the default is "corrected" to 1200 without fixing the pipe path first, this becomes reachable the same day. Sequencing matters. Surfaced in docs(http): correct serializeStream return type - follow-up to #641 #655.Suggested fix
static/defaultConfig.yamlon whether 0 is intended..pipe()normalization separately, and land it before any change that turns compression on by default.sent with Claude Opus 5