doc: mark accessing IPC channel fd as undefined #17545

bzoz · 2017-12-08T11:12:48Z

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is undefined.

This adds to what was done in #17460

~~Fixes: #16491~~

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

docs

seishun · 2017-12-08T11:18:28Z

doc/api/child_process.md

+
+   *Note*: Accessing the IPC channel fd in any way other than
+   [`process.send()`][] or using the IPC channel with a child process
+   that is not a Node.js instance is undefined.


What does "undefined" mean? Did you mean "undefined behavior"?

Nit: I'd prefer we remove *Note*: and just let the paragraph/sentence stand on its own. There are already 29 Notes in the doc as it is. We overuse that pattern. And the italicized Note: doesn't really call attention to things IMO.

Using the IPC channel with a non-node child process used to be documented, and basically still is, though it looks like the purpose of the text got lost a bit in various rewrites:

Node.js processes launched with a custom execPath will communicate with the parent process using the file descriptor (fd) identified using the environment variable NODE_CHANNEL_FD on the child process. The input and output on this fd is expected to be line delimited JSON objects.

It now sounds like the env var and the JSON protocol is only to be used by node.js child processes, but that is a bit odd, if so, this information would be entirely implementation detail (like the protocol used internally by the cluster module, which is entirely undocumented). The only purpose to describe the env var and protocol so specifically is so that it can be used by non-node.js child processes. If node explodes when the protocol is abused, that's a bug - though a bug of the "doctor it hurts when I hit myself with a hammer" variety - should be fixed, but not very severe.

I would prefer if we stated explicitly that the IPC channel should not be used if not through process.send()

minor suggestion: I would just drop the *Note*: prefix.

seishun · 2017-12-08T11:23:15Z

@nodejs/collaborators This is a bit of a philosophical question: is it acceptable for Node.js to crash with an assertion error (or possibly a segfault if it's a release build) if you write some innocuous-looking code that's actually disallowed by a note in the documentation? Or should Node.js turn it into an exception?

lpinca · 2017-12-08T11:30:16Z

Or should Node.js turn it into an exception?

I think this is preferable.

bzoz · 2017-12-08T12:54:02Z

I've tried fixing #16491 (commit here). While it fixed that issue, it turns out fs.write would still fail on Windows. OTOH using process.stdout.write triggers assert on Linux.

IMHO fixing this by marking it as undefined behavior in the documentation is the way to go at this point. There is nothing preventing us from making Node.js fire an exception instead of crashing in another PR and keeping this note. Or even at some point in the future, fixing this on all platforms and removing this note from documentation. But right now users are trying to access the IPC channel and it explodes for undocumented reasons.

Trott · 2017-12-08T19:50:56Z

I'm OK with this doc note if we open an issue for it where the preferable behavior is described and attention is called to this doc note, explaining that it will need to be removed or changed once the preferable behavior is implemented. (EDIT: Maybe just remove the "Fixes" here so that issue stays open?)

BridgeAR · 2017-12-12T21:56:48Z

@bzoz can you elaborate in what way it can not be turned into a exception right now / why that is not ideal right now?

bzoz · 2017-12-21T11:36:35Z

Updated, removed Fixes , PTAL.

bzoz · 2017-12-21T11:57:37Z

@BridgeAR I guess that this is rather easy on Windows, making libuv return error instead of firing an assert. I'm not sure about Linux, it seems like it works but then Node dies when exiting:

node: ../deps/uv/src/unix/core.c:881: uv__io_stop: Assertion `loop->watchers[w->fd] == w' failed.

It is definitely possible to fix. We can even change the implementation to use normal named pipe instead of this IPC pipe that is causing problems. But it all will take time testing and implementing, for now lets document this.

BridgeAR · 2017-12-21T12:24:03Z

@bzoz there seems to be a strong preference to try to throw an error instead of having this documentation change. I understand that it might be difficult to get it working everywhere but maybe it would be best to just open a PR that works on Windows and ask someone else to look into the Linux?

seishun · 2017-12-21T12:59:38Z

According to @bnoordhuis, libuv works as intended (#16491 (comment)). So the fix would be in Node.js proper, and thus would most likely be the same for both Windows and Linux.

bzoz · 2017-12-21T13:57:02Z

@seishun that comment is reffering to the the fact that libuv complains about garbage in the IPC chanell. This has to be changed in libuv, since it is the libuv that fires an assert when unexpected data is received.

@BridgeAR I don't know when I'll have time to do this, and it will be only a partial solution. I will get back to this at some point, but for now lets document what is the current state.

BridgeAR · 2017-12-21T14:06:27Z

@bzoz I will abstain from giving a +-1 and so far everyone else did the same. So I personally have the feeling this is not going to land as is.

seishun · 2017-12-21T14:07:08Z

@bzoz If you disagree with that comment, why? If not, why do you think the assert has to be changed in libuv anyway?

bzoz · 2017-12-21T14:32:37Z

@BridgeAR Fixing this would be better, but IMHO it will not be an easy fix and not one that we can expect to be made soon.

@seishun If libuv detects that the IPC pipe is misused, it will terminate the process. Asserts like this one will have to be changed to returning an error.

BridgeAR · 2018-01-05T01:56:07Z

@nodejs/collaborators PTAL

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is not supported.

bzoz · 2018-02-15T10:04:51Z

Updated, PTAL

mcollina

LGTM

BridgeAR · 2018-02-16T23:54:58Z

I removed this from the TSC agenda again as I was the one who put it there.

I feel the changed text is good to land as is.

BridgeAR · 2018-02-17T14:15:40Z

CI https://ci.nodejs.org/job/node-test-commit-light/290/

BridgeAR · 2018-02-17T14:25:11Z

Landed in ea1a076 🎉

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is not supported. PR-URL: nodejs#17545 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is not supported. PR-URL: #17545 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is not supported. PR-URL: nodejs#17545 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is not supported. PR-URL: #17545 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

nodejs-github-bot added child_process Issues and PRs related to the child_process subsystem. doc Issues and PRs related to the documentations. labels Dec 8, 2017

bzoz mentioned this pull request Dec 8, 2017

Accidentally writing garbage to the IPC channel blows up parent in debug build #16491

Closed

seishun reviewed Dec 8, 2017

View reviewed changes

MylesBorins force-pushed the master branch from b7405ab to 7f086dd Compare December 8, 2017 16:38

bzoz force-pushed the bartek-ipc-write-undefined branch from 4a60a68 to 1eb4954 Compare December 21, 2017 11:10

maclover7 force-pushed the master branch from bb5575a to 993b716 Compare January 26, 2018 22:02

cjihrig force-pushed the master branch from 993b716 to 082f952 Compare January 26, 2018 22:36

BridgeAR added the tsc-review label Jan 31, 2018

BridgeAR requested a review from a team January 31, 2018 02:42

BridgeAR added the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label Feb 7, 2018

BridgeAR requested review from mcollina, jasnell, addaleax, seishun and joyeecheung February 7, 2018 03:41

mhdawson mentioned this pull request Feb 12, 2018

Node.js Foundation Technical Steering Committee (TSC) Meeting 2018-02-14 nodejs/TSC#491

Closed

doc: mark accessing IPC channel fd as undefined

6346c42

Adds note that accessing the fd of the IPC channel in any other way than process.send, or using the IPC channel with child processes that is not Node.js is not supported.

bzoz force-pushed the bartek-ipc-write-undefined branch from 1eb4954 to 6346c42 Compare February 15, 2018 10:03

mcollina approved these changes Feb 15, 2018

View reviewed changes

jasnell approved these changes Feb 15, 2018

View reviewed changes

BridgeAR approved these changes Feb 15, 2018

View reviewed changes

BridgeAR added author ready PRs that have at least one approval, no pending requests for changes, and a CI started. and removed tsc-agenda Issues and PRs to discuss during the meetings of the TSC. tsc-review labels Feb 16, 2018

BridgeAR closed this Feb 17, 2018

MylesBorins mentioned this pull request Feb 21, 2018

v9.6.0 proposal #18902

Merged

MylesBorins mentioned this pull request Aug 16, 2018

v8.12.0 proposal #21593

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: mark accessing IPC channel fd as undefined #17545

doc: mark accessing IPC channel fd as undefined #17545

bzoz commented Dec 8, 2017 •

edited

Loading

seishun Dec 8, 2017

Trott Dec 8, 2017

sam-github Dec 9, 2017 •

edited

Loading

mcollina Dec 21, 2017

jasnell Jan 31, 2018

seishun commented Dec 8, 2017

lpinca commented Dec 8, 2017

bzoz commented Dec 8, 2017

Trott commented Dec 8, 2017 •

edited

Loading

BridgeAR commented Dec 12, 2017

bzoz commented Dec 21, 2017

bzoz commented Dec 21, 2017

BridgeAR commented Dec 21, 2017

seishun commented Dec 21, 2017

bzoz commented Dec 21, 2017

BridgeAR commented Dec 21, 2017

seishun commented Dec 21, 2017

bzoz commented Dec 21, 2017

BridgeAR commented Jan 5, 2018

bzoz commented Feb 15, 2018

mcollina left a comment

BridgeAR commented Feb 16, 2018

BridgeAR commented Feb 17, 2018

BridgeAR commented Feb 17, 2018

doc: mark accessing IPC channel fd as undefined #17545

doc: mark accessing IPC channel fd as undefined #17545

Conversation

bzoz commented Dec 8, 2017 • edited Loading

Checklist

Affected core subsystem(s)

seishun Dec 8, 2017

Choose a reason for hiding this comment

Trott Dec 8, 2017

Choose a reason for hiding this comment

sam-github Dec 9, 2017 • edited Loading

Choose a reason for hiding this comment

mcollina Dec 21, 2017

Choose a reason for hiding this comment

jasnell Jan 31, 2018

Choose a reason for hiding this comment

seishun commented Dec 8, 2017

lpinca commented Dec 8, 2017

bzoz commented Dec 8, 2017

Trott commented Dec 8, 2017 • edited Loading

BridgeAR commented Dec 12, 2017

bzoz commented Dec 21, 2017

bzoz commented Dec 21, 2017

BridgeAR commented Dec 21, 2017

seishun commented Dec 21, 2017

bzoz commented Dec 21, 2017

BridgeAR commented Dec 21, 2017

seishun commented Dec 21, 2017

bzoz commented Dec 21, 2017

BridgeAR commented Jan 5, 2018

bzoz commented Feb 15, 2018

mcollina left a comment

Choose a reason for hiding this comment

BridgeAR commented Feb 16, 2018

BridgeAR commented Feb 17, 2018

BridgeAR commented Feb 17, 2018

bzoz commented Dec 8, 2017 •

edited

Loading

sam-github Dec 9, 2017 •

edited

Loading

Trott commented Dec 8, 2017 •

edited

Loading