Skip to content

stream,http,http2: use public stream state accessors - #67677

Open
mcollina wants to merge 1 commit into
nodejs:mainfrom
mcollina:refactor/stream-state-accessors
Open

mcollina wants to merge 1 commit into
nodejs:mainfrom
mcollina:refactor/stream-state-accessors

Conversation

@mcollina

@mcollina mcollina commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Motivation

lib/internal/http/*, lib/internal/fs/*, lib/zlib.js, lib/internal/console/*
and lib/internal/webstreams/* reach into _readableState / _writableState
directly. That couples non-streams modules to the internal state objects'
shape, so refactoring lib/internal/streams/ (e.g. replacing boolean flags
with bitmask fields) silently ripples outward.

This PR exposes the needed state through the same public accessor surface
already used for readableLength, writableLength, etc., and migrates every
call site that has a public equivalent. Depending on the internal state object
outside lib/internal/streams/ is reduced from 43 references to 17, and
the remaining ones are genuinely internal writes / state hand-offs with no
sensible public accessor.

New public accessors

Readable / Writable (and Duplex where applicable):

  • readableErrored / writableErrored — exposes the per-side errored
    state. On a Duplex, stream.errored reflects only the readable side, so
    the writable-side getter is wired into Duplex too. (Note: the
    Object.keys(Writable.prototype) copy loop that builds Duplex.prototype
    skips non-enumerable getters, so these are added explicitly.)
  • readableHighWaterMark / writableHighWaterMark — now settable, validated
    through a shared validateHighWaterMark helper that throws
    ERR_INVALID_ARG_VALUE on non-integer / negative values.
  • writableDefaultEncoding — getter.
  • readableErrorEmitted / writableErrorEmitted — getters.
  • readableResumeScheduled — getter. isPaused() is not equivalent:
    calling resume() while a 'readable' listener is attached leaves
    isPaused() true while resumeScheduled is set, so the flag is exposed
    verbatim to preserve behaviour.
  • autoDestroy — getter/setter on Readable and Writable. The Duplex
    accessor keeps _readableState.autoDestroy and _writableState.autoDestroy
    in sync when set dynamically, matching how destroyed is already handled.

Call sites migrated

  • lib/internal/http2/core.js
  • lib/internal/http/outgoing.js, incoming.js, agent.js, server.js
  • lib/internal/fs/streams.js
  • lib/zlib.js
  • lib/internal/console/constructor.js
  • lib/internal/http2/compat.js
  • lib/internal/webstreams/adapters.js (duck-typing checks switched to
    instanceof Readable / instanceof Duplex)

http2 receivedEnd

lib/internal/http2/core.js onStreamClose() now reads
Http2Stream[kState].receivedEnd instead of _readableState.ended. The flag
is set by an override of Http2Stream.prototype.push on any null push of the
readable side, so it mirrors _readableState.ended exactly and covers
server-initiated push streams whose readable side ends on a clean close (not a
peer END_STREAM).

This reconciles cleanly with the existing STREAM_FLAGS_CLEAN_REQUEST_RESET
handling: receivedEnd drives the "peer did not END_STREAM → abort the
request" decision, while the clean-reset flag governs keeping a client
response readable. Http2Stream._destroy() reads the same receivedEnd flag
instead of _readableState.ended when recording an incomplete request.

Fix a regression

Making the high-water-mark setter validating caused
new IncomingMessage(<truthy non-socket>) to throw ERR_INVALID_ARG_VALUE
with an undefined highWaterMark. lib/internal/http/incoming.js now only
syncs the socket high-water mark when it is defined.

Tests

New tests:

  • test/parallel/test-stream-errored-accessors.js
  • test/parallel/test-stream-settable-highwatermark.js
  • test/parallel/test-stream-state-accessors.js

And an extended test-stream-duplex-*/test-stream-* coverage for the
autoDestroy setter. Ran the full test/parallel stream, http2 (300, incl.
compat), http, fs, zlib and console suites.

@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/http
  • @nodejs/http2
  • @nodejs/net
  • @nodejs/streams

@nodejs-github-bot nodejs-github-bot added lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Nov 21, 2026
@mcollina mcollina added the semver-minor PRs that contain new features and should be released in the next minor version. label Nov 21, 2026
@mcollina

Copy link
Copy Markdown
Member Author

Validated locally against current main (rebased on ce44266): rebuilt out/Release and ran the affected suites.

Test results (all green):

  • test-parallel/test-stream-errored-accessors.js, test-stream-settable-highwatermark.js, test-stream-state-accessors.js (3)
  • test-parallel/test-http2-*.js (317, incl. compat)
  • test-parallel/test-stream-*.js + test-streams-*.js (233)
  • test-parallel/test-http-*.js (full)
  • test-parallel/test-zlib-*.js, test-console-*.js, test-fs-stream-*.js, test-fs-readfile-*.js, test-fs-writefile-*.js (141)
  • test-parallel/test-webstreams-*.js + test-stream-base-*.js (16)

Also: eslint (--max-warnings=0) and node --check clean on all changed files; tools/lint-md clean on doc/api/stream.md.

@codecov

codecov Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.44970% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.60%. Comparing base (ce44266) to head (d47e881).
⚠️ Report is 13 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/streams/duplex.js 88.46% 3 Missing ⚠️
lib/internal/fs/streams.js 50.00% 2 Missing ⚠️
lib/internal/webstreams/adapters.js 50.00% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff            @@
##             main   #67677    +/-   ##
========================================
  Coverage   90.60%   90.60%            
========================================
  Files         801      801            
  Lines      281056   281226   +170     
  Branches    54253    54296    +43     
========================================
+ Hits       254660   254818   +158     
+ Misses      16577    16576     -1     
- Partials     9819     9832    +13     
Files with missing lines Coverage Δ
lib/internal/console/constructor.js 98.18% <100.00%> (ø)
lib/internal/http/agent.js 96.63% <100.00%> (ø)
lib/internal/http/incoming.js 97.66% <100.00%> (ø)
lib/internal/http/outgoing.js 98.00% <100.00%> (ø)
lib/internal/http/server.js 96.78% <100.00%> (-0.07%) ⬇️
lib/internal/http2/compat.js 97.40% <100.00%> (+0.09%) ⬆️
lib/internal/http2/core.js 95.07% <100.00%> (+0.01%) ⬆️
lib/internal/stream_base_commons.js 95.03% <100.00%> (+0.17%) ⬆️
lib/internal/streams/readable.js 98.95% <100.00%> (+0.02%) ⬆️
lib/internal/streams/state.js 98.41% <100.00%> (+0.13%) ⬆️
... and 5 more

... and 37 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Replace direct _readableState/_writableState access outside
lib/internal/streams/ with the public accessors so internal modules no
longer depend on the state objects' shape.

Added accessors:
- readableErrored / writableErrored (per-side; on a Duplex stream.errored
  only reflects the readable side, and writable-side getters must be wired
  into Duplex because the non-enumerable property copy loop skips them)
- settable readableHighWaterMark / writableHighWaterMark (validated via a
  shared validateHighWaterMark helper, ERR_INVALID_ARG_VALUE)
- writableDefaultEncoding, readableErrorEmitted / writableErrorEmitted
- readableResumeScheduled (isPaused() is not equivalent: resume() with a
  'readable' listener leaves isPaused() true while resumeScheduled is set)
- autoDestroy get/set on Readable and Writable; a Duplex accessor keeps
  _readableState/_writableState.autoDestroy in sync when set dynamically

Call sites migrated to the accessors:
- lib/internal/http2/core.js, lib/internal/http/outgoing.js,
  lib/internal/http/incoming.js, lib/internal/http/agent.js,
  lib/internal/http/server.js, lib/internal/http2/compat.js,
  lib/zlib.js, lib/internal/console/constructor.js,
  lib/internal/fs/streams.js
- lib/internal/webstreams/adapters.js drops duck-typing checks for
  instanceof Readable / Duplex

http2 receivedEnd: Http2Stream tracks when its readable side reached EOF via
a receivedEnd flag set on any null push (an exact mirror of
_readableState.ended). onStreamClose() and _destroy() read
stream[kState].receivedEnd instead of _readableState.ended, so a
server-initiated push stream that ends cleanly is no longer misclassified
as an abort.

Also fix a regression from the settable high-water-mark setter: its
validation made new IncomingMessage(<truthy non-socket>) throw
ERR_INVALID_ARG_VALUE, so http/incoming.js now only syncs the socket HWM
when it is defined.

Non-streams-core _readableState/_writableState references: 43 -> 17.
@mcollina
mcollina force-pushed the refactor/stream-state-accessors branch from a4033fd to d47e881 Compare November 22, 2026 08:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. semver-minor PRs that contain new features and should be released in the next minor version.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants