Skip to content

doc: clarify cumulative output limits for zlib streams - #67373

Open
sboettch wants to merge 1 commit into
nodejs:mainfrom
sboettch:doc-zlib-stream-max-output-length
Open

sboettch wants to merge 1 commit into
nodejs:mainfrom
sboettch:doc-zlib-stream-max-output-length

Conversation

@sboettch

Copy link
Copy Markdown

Refs: https://github.com/nodejs/node/blob/main/doc/api/zlib.md

Hello nodejs/node documentation maintainers, and thank you for maintaining the node:zlib API reference across gzip, brotli, and zstd. I am a citizen applied data scientist working on WebHealth (an open public-interest security observatory), and while testing streaming decompression configurations locally across Node.js runtimes, I noticed a small point in doc/api/zlib.md where clarifying how maxOutputLength interacts with streaming decompressors could help callers bound memory safely.

doc/api/zlib.md documents maxOutputLength under Class: Options, Class: BrotliOptions, and Class: ZstdOptions for single-buffer convenience methods (zlib.gunzip(), zlib.brotliDecompress(), zlib.zstdDecompress(), and their *Sync counterparts). On Node.js v22.x, v24.x, and v26.5.0, passing { maxOutputLength } to streaming factories (zlib.createGunzip(), zlib.createBrotliDecompress(), zlib.createZstdDecompress()) bounds per-chunk internal buffer growth rather than cumulative decoded stream output across chunks (RFC 1952 / RFC 7932 / RFC 8878, CWE-409).

Clarify in doc/api/zlib.md (Class: Options, Class: BrotliOptions, and Class: ZstdOptions) that maxOutputLength caps total output on convenience methods rather than cumulative stream output across create*Decompress() streams, and document a node:stream/promises pipeline() + Transform byte-counter pattern that aborts streaming decompression and destroys the upstream Readable as soon as a cumulative byte limit is exceeded.

Validation:

  • Verified doc/api/zlib.md line wrapping (<= 80 columns), reference links ([convenience methods][], [pipeline()][], [stream.Transform][]), and whitespace (git diff --check) with zero warnings.
  • Verified the documented pipeline() + Transform guard across createGunzip(), createBrotliDecompress(), and createZstdDecompress() at exact 65,536 B (OK) and 65,537 B (RangeError + source.destroyed === true).

Thank you very much for your time and review. If a shorter inline note under maxOutputLength or a different location in doc/api/zlib.md fits the documentation style better, I am happy to adjust this however you prefer.

Warm regards,
Sophia Boettcher

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to Node.js documentation. zlib Issues and PRs related to the zlib module and its compression dependencies. labels Nov 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Welcome to Node.js, and thank you for your first contribution!

Before review, please take a moment to read:

Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal.

@MikeMcC399

This comment was marked as resolved.

Clarify in `doc/api/zlib.md` that `maxOutputLength` bounds single-call
convenience methods (`zlib.gunzip()`, `zlib.brotliDecompress()`,
`zlib.zstdDecompress()`, and `*Sync` variants) rather than cumulative
decoded output across `create*Decompress()` streams, and add a
`stream/promises` `pipeline()` example enforcing a cumulative byte
limit.

Signed-off-by: Sophia Boettcher <sboettcher@ub313.net>
@sboettch
sboettch force-pushed the doc-zlib-stream-max-output-length branch from f7c3c22 to 31b680e Compare November 14, 2026 19:42
@jasnell jasnell added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 16, 2026
@jasnell jasnell added commit-queue PRs queued for automated landing through the Commit Queue. and removed request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. labels Nov 16, 2026
@nodejs-github-bot nodejs-github-bot added commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. and removed commit-queue PRs queued for automated landing through the Commit Queue. labels Nov 16, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Commit Queue failed

   ⚠  Could not retrieve the email or name of the PR's author from user's GitHub profile!
   ✖  3 GitHub CI job(s) failed:
   ✖    - github-actions: ACTION_REQUIRED
   ✖    - github-actions: ACTION_REQUIRED
   ✖    - github-actions: ACTION_REQUIRED

The pull request was removed from the Commit Queue and labeled commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. . After resolving the failure, remove that label and add commit-queue PRs queued for automated landing through the Commit Queue. to retry.

Full Commit Queue output
�[36m⠋�[39m Loading data for nodejs/node/pull/67373
�[36m⠋�[39m Loading data for nodejs/node/pull/67373
�[36m⠋�[39m Getting collaborator contacts from README of nodejs/node
�[36m⠋�[39m Getting PR from nodejs/node/pull/67373
�[36m⠋�[39m Getting reviews from nodejs/node/pull/67373
�[36m⠋�[39m Getting comments from nodejs/node/pull/67373
�[36m⠋�[39m Getting commits from nodejs/node/pull/67373
✔  Done loading data for nodejs/node/pull/67373
----------------------------------- PR info ------------------------------------
Title      doc: clarify cumulative output limits for zlib streams (#67373)
   ⚠  Could not retrieve the email or name of the PR's author from user's GitHub profile!
Branch     sboettch:doc-zlib-stream-max-output-length -> nodejs:main
Labels     doc, zlib, commit-queue
Commits    1
 - doc: clarify cumulative output limits for zlib streams
Committers 1
 - sophia <sboettcher@ub313.net>
PR-URL: https://github.com/nodejs/node/pull/67373
Refs: https://github.com/nodejs/node/blob/main/doc/api/zlib.md
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/67373
Refs: https://github.com/nodejs/node/blob/main/doc/api/zlib.md
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Tue, 10 Nov 2026 07:25:41 GMT
   ✔  Approvals: 2
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/67373#pullrequestreview-5913661334
   ✔  - Ulises Gascón (@UlisesGascon): https://github.com/nodejs/node/pull/67373#pullrequestreview-5904204634
   ✖  3 GitHub CI job(s) failed:
   ✖    - github-actions: ACTION_REQUIRED
   ✖    - github-actions: ACTION_REQUIRED
   ✖    - github-actions: ACTION_REQUIRED
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

View workflow run

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. doc Issues and PRs related to Node.js documentation. zlib Issues and PRs related to the zlib module and its compression dependencies.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants