doc: add notes about non-conforming streams #29895

ronag · 2019-10-09T06:46:44Z

A lot of streams in the ecosystem are overriding public stream methods that lead to very subtle and hard to find bugs. Discourage this usage and encourage using the existing framework.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

BridgeAR

I am in general fine with the note but isn't this a general problem we have? There are still lots of "internal" APIs used and or overridden in the wild.

We also do not have "internal" events, so it's even more difficult to prevent any such usage.

ronag · 2019-10-09T17:49:58Z

t isn't this a general problem we have? There are still lots of "internal" APIs used and or overridden in the wild.

Yes, nothing we can do about that... but we can still discourage it so future users are able to implement streams as correctly as possible?

We also do not have "internal" events, so it's even more difficult to prevent any such usage.

What do you mean? 'error'? It's javascript we can't prevent some stuff but at least users should be aware of what they should and should not do.

I don't think most people that override public methods are aware of the problems it might cause.

doc/api/stream.md

Trott · 2019-10-12T05:17:26Z

typo in commit message: s/confirming/conforming/

doc/api/stream.md

Trott · 2019-10-12T05:19:13Z

Text looks fine to me but would prefer reviews from @nodejs/streams to mine.

Trott · 2019-10-12T15:39:48Z

LIte CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3988/

lpinca · 2019-10-20T19:30:00Z

doc/api/stream.md

@@ -1667,6 +1667,12 @@ of a stream that are intended for use by consumers (as described in the
 [API for Stream Consumers][] section). Doing so may lead to adverse side effects
 in application code consuming the stream.

+It is highly discouraged to override any public method or to emit
+`'error'` events manually through `.emit(err)` instead of using API-provided


We also do not have "internal" events, so it's even more difficult to prevent any such usage.

I think that @BridgeAR was referring to events like 'data', 'finish', 'end', 'close', etc. not only 'error'.

I see. Not sure what to do with that though? Should I add "internal events" to the paragraph?

ronag · 2019-11-17T18:34:46Z

Maybe a quick review from @mcollina?

mcollina

lgtm, good note.

doc/api/stream.md

Co-Authored-By: Ruben Bridgewater <ruben@bridgewater.de>

ronag · 2019-11-24T20:08:00Z

@Trott: I believe this can land?

ronag · 2019-11-24T20:08:33Z

Maybe @lundibundi & @yorkie has some last minute feedback?

doc/api/stream.md

lundibundi

👍

doc/api/stream.md

Trott · 2019-11-25T02:41:15Z

I left a bunch of small suggestions, but none of them are blocking.

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/4087/

Co-Authored-By: Rich Trott <rtrott@gmail.com>

PR-URL: #29895 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

Trott · 2019-11-25T22:35:35Z

Landed in d67c377

PR-URL: #29895 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>

nodejs-github-bot added doc Issues and PRs related to the documentations. stream Issues and PRs related to the stream subsystem. labels Oct 9, 2019

doc: add notes about non-confirming streams

7ce4453

ronag force-pushed the notes-about-override branch from 6c7173d to 7ce4453 Compare October 9, 2019 06:47

BridgeAR reviewed Oct 9, 2019

View reviewed changes

Trott reviewed Oct 9, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott reviewed Oct 9, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott reviewed Oct 9, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott reviewed Oct 12, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott changed the title ~~doc: add notes about non-confirming streams~~ doc: add notes about non-conforming streams Oct 12, 2019

lpinca approved these changes Oct 20, 2019

View reviewed changes

lpinca reviewed Oct 20, 2019

View reviewed changes

fixup

e2207eb

ronag force-pushed the notes-about-override branch from a963259 to e2207eb Compare October 20, 2019 21:14

fixup

1ac15d1

ronag force-pushed the notes-about-override branch from 3c45c5a to 1ac15d1 Compare October 20, 2019 21:16

ronag requested review from BridgeAR and Trott November 17, 2019 18:34

mcollina approved these changes Nov 17, 2019

View reviewed changes

Trott added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Nov 17, 2019

addaleax approved these changes Nov 19, 2019

View reviewed changes

BridgeAR reviewed Nov 19, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

addaleax removed the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Nov 19, 2019

Update doc/api/stream.md

fc5029d

Co-Authored-By: Ruben Bridgewater <ruben@bridgewater.de>

BridgeAR approved these changes Nov 19, 2019

View reviewed changes

devnexen approved these changes Nov 19, 2019

View reviewed changes

yorkie reviewed Nov 24, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

lundibundi approved these changes Nov 24, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

yorkie approved these changes Nov 24, 2019

View reviewed changes

fixup: provide examples of methods

fdba619

ronag force-pushed the notes-about-override branch from 9a3f364 to fdba619 Compare November 24, 2019 21:06

Trott reviewed Nov 25, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott reviewed Nov 25, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott reviewed Nov 25, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott reviewed Nov 25, 2019

View reviewed changes

doc/api/stream.md Outdated Show resolved Hide resolved

Trott added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Nov 25, 2019

ronag and others added 3 commits November 25, 2019 09:16

Apply suggestions from code review

6f4b705

Co-Authored-By: Rich Trott <rtrott@gmail.com>

fixup: line wrap

50a3d5a

fixup: events plural

687ead7

Trott approved these changes Nov 25, 2019

View reviewed changes

Trott closed this Nov 25, 2019

BridgeAR mentioned this pull request Dec 3, 2019

v13.3.0 proposal #30774

Merged

BethGriggs mentioned this pull request Dec 9, 2019

v12.13.2 proposal #30865

Closed

BethGriggs mentioned this pull request Dec 23, 2019

v12.14.1 proposal #31069

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add notes about non-conforming streams #29895

doc: add notes about non-conforming streams #29895

ronag commented Oct 9, 2019

BridgeAR left a comment

ronag commented Oct 9, 2019 •

edited

Loading

Trott commented Oct 12, 2019

Trott commented Oct 12, 2019

Trott commented Oct 12, 2019

lpinca Oct 20, 2019 •

edited

Loading

ronag Oct 20, 2019

ronag commented Nov 17, 2019

mcollina left a comment

ronag commented Nov 24, 2019

ronag commented Nov 24, 2019

lundibundi left a comment

Trott commented Nov 25, 2019

Trott commented Nov 25, 2019

doc: add notes about non-conforming streams #29895

doc: add notes about non-conforming streams #29895

Conversation

ronag commented Oct 9, 2019

Checklist

BridgeAR left a comment

Choose a reason for hiding this comment

ronag commented Oct 9, 2019 • edited Loading

Trott commented Oct 12, 2019

Trott commented Oct 12, 2019

Trott commented Oct 12, 2019

lpinca Oct 20, 2019 • edited Loading

Choose a reason for hiding this comment

ronag Oct 20, 2019

Choose a reason for hiding this comment

ronag commented Nov 17, 2019

mcollina left a comment

Choose a reason for hiding this comment

ronag commented Nov 24, 2019

ronag commented Nov 24, 2019

lundibundi left a comment

Choose a reason for hiding this comment

Trott commented Nov 25, 2019

Trott commented Nov 25, 2019

ronag commented Oct 9, 2019 •

edited

Loading

lpinca Oct 20, 2019 •

edited

Loading