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

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 18, 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.

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.

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
- lib/internal/http2/core.js onStreamClose() now reads
  Http2Stream[kState].receivedEnd (set on any null push of the readable
  side) 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 -> 18.
@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 95.83333% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.59%. Comparing base (ce44266) to head (a4033fd).
⚠️ Report is 2 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/stream_base_commons.js 0.00% 1 Missing ⚠️
lib/internal/webstreams/adapters.js 50.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #67677      +/-   ##
==========================================
- Coverage   90.60%   90.59%   -0.01%     
==========================================
  Files         801      801              
  Lines      281056   281192     +136     
  Branches    54253    54288      +35     
==========================================
+ Hits       254660   254759      +99     
- Misses      16577    16614      +37     
  Partials     9819     9819              
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.65% <100.00%> (-0.20%) ⬇️
lib/internal/http2/compat.js 97.30% <100.00%> (ø)
lib/internal/http2/core.js 95.07% <100.00%> (+0.01%) ⬆️
lib/internal/streams/readable.js 98.95% <100.00%> (+0.02%) ⬆️
lib/internal/streams/state.js 98.41% <100.00%> (+0.13%) ⬆️
lib/internal/streams/writable.js 98.23% <100.00%> (+0.06%) ⬆️
... and 5 more

... and 33 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.

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