Skip to content

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

Merged
nodejs-github-bot merged 1 commit into
nodejs:mainfrom
sboettch:doc-zlib-stream-max-output-length
Nov 18, 2026
Merged

nodejs-github-bot merged 1 commit into
nodejs:mainfrom
sboettch:doc-zlib-stream-max-output-length

Conversation

@sboettch

Copy link
Copy Markdown
Contributor

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.

@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

@MikeMcC399

MikeMcC399 commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

There are two different GitHub users involved here:

https://github.com/sboettcher-ub313 committed and signed
https://github.com/sboettch submitted this PR (Edit: typo corrected)

This is causing landing checks to fail.

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 <93076268+sboettch@users.noreply.github.com>
@sboettch
sboettch force-pushed the doc-zlib-stream-max-output-length branch from 31b680e to b11a65b Compare November 18, 2026 02:31
@sboettch

Copy link
Copy Markdown
Contributor Author

thank you @MikeMcC399, and i am really sorry for the mix-up and the extra Commit Queue trouble.. @sboettch submitted this PR - that's my Stanford/Encode dedicated GitHub, while @sboettcher-ub313 (sboettcher@ub313.net) is for my personal projects. since they're both logged in on my machine, local git config picked up my personal email and caused the problem. it also looks like sboettcher is someone else who shares my last name (funny, i also studied at the University of Freiburg for a little exchange in undergrad.. it's an unusual last name!!), so sorry for the confusion there too!

the amended commit's Author, Committer, and Signed-off-by now match @sboettch (Sophia Boettcher <93076268+sboettch@users.noreply.github.com>) with the identical doc/api/zlib.md diff.. if Commit Queue also needs a public email on @sboettch's profile rather than users.noreply.github.com, i'm happy to set one right away.

thanks, sophia!

@MikeMcC399 MikeMcC399 added commit-queue PRs queued for automated landing through the Commit Queue. author ready PRs with CI started, the required approvals, and no outstanding review comments. and removed commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. labels Nov 18, 2026
@nodejs-github-bot
nodejs-github-bot merged commit f551bb5 into nodejs:main Nov 18, 2026
22 checks passed
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Landed in f551bb5

@nodejs-github-bot nodejs-github-bot removed the commit-queue PRs queued for automated landing through the Commit Queue. label Nov 18, 2026
@MikeMcC399

Copy link
Copy Markdown
Member

Thank you for correcting the commit! The PR has now landed successfully!

I'm sorry for my typo referring to a completely different user https://github.com/sboettcher ! I corrected that above.

@sboettch

Copy link
Copy Markdown
Contributor Author

thank you so much @MikeMcC399 for catching the commit-queue issue and helping with this!

thanks for all your hard work defending the internet!
sophia

aduh95 pushed a commit that referenced this pull request Nov 19, 2026
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 <93076268+sboettch@users.noreply.github.com>
PR-URL: #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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author ready PRs with CI started, the required approvals, and no outstanding review comments. 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.

5 participants