doc: add domain post mortem #6159

trevnorris · 2016-04-11T22:34:36Z

Checklist

documentation is changed or added
the commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

The domain module did not live a long and fruitful life. Instead it was
ultimately deprecated and abandon. The domain postmortem addresses why
this happened so that it doesn't happen again in the future.

Also included is an example script that accompanies the postmortem
analysis.

R=@Fishrock123
R=@nodejs/documentation

cjihrig · 2016-04-11T22:51:53Z

doc/topics/domain-postmortem.md

+built-in http benchmark, `http_simple.js`, without domains it can handle over
+22,000 requests/second. Whereas if it's run with `NODE_USE_DOMAINS=1` that
+number drops down to under 17,000 requests/second. In this case there is only
+as single global domain. If we edit the benchmark so the http request callback


as -> a

a single domain?

global is more technically correct. though even more so if it said a single active global domain. since the domain is activated at startup and left active for the remainder of the script.

eljefedelrodeodeljefe · 2016-04-11T22:56:18Z

docs-wise LGTM with nits. Good write-up.

cjihrig · 2016-04-11T23:02:52Z

doc/topics/domain-postmortem.md

+intercept the exceptions of unrelated code in a different module. Preventing
+the originator of the code from knowing about its own exceptions.
+
+Another is the how domains route errors automatically if no `'error'` handler


Starting with "Another" sounds kind of funny here. Maybe change it to "Domains also route errors..."

Perhaps "Another issue is that domains route errors automatically...."

mscdex · 2016-04-12T00:01:39Z

While on the topic, are there any thoughts about replacements and/or the way forward? Would it be beneficial to include at least a little information on that at the end of this document or no?

trevnorris · 2016-04-12T01:51:49Z

@mscdex I'm hopeful that AsyncWrap can assume the functionality of continuous local storage. The postmortem intended to demonstrate the difficulty in properly implementing asynchronous error handling, and how anything mildly complex leads to a situation where reliable resource cleanup is impossible.

Since my initial inception of AsyncListener, and its error handling implementation, I've reiterated on how to make this more feasible. After the initial features are implemented I'll write up a design doc for review.

Knighton910 · 2016-04-12T02:23:35Z

doc/topics/domain-postmortem.md

+
+As we can see from this example a lot more must be done to properly clean up
+resources when something fails than what can be done strictly through the
+domain API. All domains offer us is an exception aggregation mechanism. Even


All domains offer us looks a bit weird. @trevnorris Is this the right wording?

Knighton910 · 2016-04-12T02:26:37Z

LGTM ✅

trevnorris · 2016-04-12T06:18:57Z

All nits addressed.

@mscdex Would you like a small section about how we plan on moving forward now that this functionality has been deprecated? Would also like input from others on how this should be addressed.

benjamingr · 2016-04-12T10:58:41Z

doc/topics/domain-postmortem.md

+`domain.enter()`. Which then acts as a catch-all for any exception in the
+future that couldn't be observed by the thrower. Allowing a module author to
+intercept the exceptions of unrelated code in a different module. Preventing
+the originator of the code from knowing about its own exceptions.


A code sample here would do wonders to explain this to people considering domains.

benjamingr · 2016-04-12T11:11:50Z

I left some comments @trevnorris - otherwise excellently written 👏

mscdex · 2016-04-12T12:56:10Z

@trevnorris It's up to you, but after reading all of it it just seemed to kind of leave me hanging at the end.

jasnell · 2016-04-12T15:17:50Z

LGTM

trevnorris · 2016-04-14T06:41:17Z

@benjamingr Added two examples, changed error message and added a new section, with example, on using domain for data propagation.

@mscdex See your point. I'll try to get something written up, but no promises.

NOTE: Been working on this too long and too late. I don't take corrections to my grammar personally, so feel free to request changes. I know there are improvements that can be made, but too tired to see them.

benjamingr · 2016-04-14T06:51:11Z

Very nice.

Fishrock123 · 2016-04-14T14:32:52Z

I think domain-resource-cleanup.js should be domain-resource-cleanup-example.js

Or examples/domain-resource-cleanup.js, though I think domain-resource-cleanup-example.js should be fine.

Fishrock123 · 2016-04-14T14:33:01Z

LGTM otherwise.

rvagg · 2016-04-14T16:34:16Z

doc/topics/domain-postmortem.md

+
+### API Gaps
+
+While APIs based using `EventEmitter` can use `bind()` and errback style


"based using" -> "based on using"?

rvagg · 2016-04-14T16:39:53Z

Nice work @trevnorris, so good to have all of this in one place that we can point to when it comes up.

I think this needs an intro to explain why this doc exists in the first place, something along the lines of "The Domains API has been deprecated, this document explains some of the major problems observed with Domains and why the decision was made to scrap, rather than attempt to fix the API".

Another possible addition here could be a section on complexity and the overhead that Domains has introduced in maintenance of so many parts of core.

/cc @misterdjules who may have some good insight to add on this topic.

bengl · 2016-04-14T16:58:00Z

doc/topics/domain-postmortem.md

+Even manually removing the connection via `d.remove(c)` does not prevent the
+connection's error from being automatically intercepted.
+
+A failure that plagues both error routing and exception handling are the


Grammar nit: "A failure ... are ..." <-- singular subject, plural verb.

trevnorris · 2016-04-15T20:16:18Z

@mscdex I've added a "Looking Ahead" section at the end. Hopefully that's along the lines of what you were looking for.

@rvagg I would be happy to add a prologue or such if you have more details of what you're looking for.

mscdex · 2016-04-15T20:18:36Z

@trevnorris LGTM

Do to various reasons, outlined in the committed document, domains were only in core for 2 years before being deprecated. This outline explains why they received criticism from the community and never gained traction with module authors. Also included is an example script that accompanies the postmortem analysis. PR-URL: nodejs#6159 Reviewed-By: Robert Lindstädt <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Brian White <[email protected]>

trevnorris · 2016-04-15T21:13:34Z

Thanks all. Landed in 4a74fc9.

Do to various reasons, outlined in the committed document, domains were only in core for 2 years before being deprecated. This outline explains why they received criticism from the community and never gained traction with module authors. Also included is an example script that accompanies the postmortem analysis. PR-URL: #6159 Reviewed-By: Robert Lindstädt <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Brian White <[email protected]>

MylesBorins · 2016-04-21T06:37:51Z

@trevnorris I've gone ahead and marked this don't land on v4

Please let me know if you think it should be backported to lts docs

Do to various reasons, outlined in the committed document, domains were only in core for 2 years before being deprecated. This outline explains why they received criticism from the community and never gained traction with module authors. Also included is an example script that accompanies the postmortem analysis. PR-URL: #6159 Reviewed-By: Robert Lindstädt <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Brian White <[email protected]>

Do to various reasons, outlined in the committed document, domains were only in core for 2 years before being deprecated. This outline explains why they received criticism from the community and never gained traction with module authors. Also included is an example script that accompanies the postmortem analysis. PR-URL: nodejs#6159 Reviewed-By: Robert Lindstädt <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Brian White <[email protected]>

Do to various reasons, outlined in the committed document, domains were only in core for 2 years before being deprecated. This outline explains why they received criticism from the community and never gained traction with module authors. Also included is an example script that accompanies the postmortem analysis. PR-URL: #6159 Reviewed-By: Robert Lindstädt <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Brian White <[email protected]>

trevnorris · 2016-04-26T20:49:21Z

@thealphanerd Sounds fine. This is only informative.

trevnorris added doc Issues and PRs related to the documentations. domain Issues and PRs related to the domain subsystem. labels Apr 11, 2016

cjihrig reviewed Apr 11, 2016
View reviewed changes

Knighton910 reviewed Apr 12, 2016
View reviewed changes

trevnorris force-pushed the domain-postmortem branch from 1362cf0 to e51b4b1 Compare April 12, 2016 06:17

benjamingr reviewed Apr 12, 2016
View reviewed changes

trevnorris force-pushed the domain-postmortem branch from e51b4b1 to 9c82e15 Compare April 14, 2016 06:38

trevnorris force-pushed the domain-postmortem branch from 9c82e15 to c096e6a Compare April 14, 2016 06:50

rvagg reviewed Apr 14, 2016
View reviewed changes

bengl reviewed Apr 14, 2016
View reviewed changes

trevnorris force-pushed the domain-postmortem branch from 6f6782a to ab675f2 Compare April 15, 2016 20:14

trevnorris force-pushed the domain-postmortem branch from ab675f2 to b026231 Compare April 15, 2016 21:11

trevnorris force-pushed the domain-postmortem branch from b026231 to 4a74fc9 Compare April 15, 2016 21:12

trevnorris closed this Apr 15, 2016

trevnorris deleted the domain-postmortem branch April 15, 2016 21:13

trevnorris merged commit 4a74fc9 into nodejs:master Apr 15, 2016

MylesBorins mentioned this pull request Apr 20, 2016

V5.10.2 proposal #6311

Closed

This was referenced Apr 21, 2016

V5.11.0 proposal #6321

Closed

V5.11.0 proposal #6322

Closed

Audit commits not found on v4.x #5647

Closed

MylesBorins added the dont-land-on-v4.x label Apr 21, 2016

benjamingr mentioned this pull request Jun 15, 2016

Bluebird leaks domains on exception thrown in a then() function. petkaantonov/bluebird#1125

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add domain post mortem #6159

doc: add domain post mortem #6159

trevnorris commented Apr 11, 2016

cjihrig Apr 11, 2016

eljefedelrodeodeljefe Apr 11, 2016

trevnorris Apr 12, 2016

eljefedelrodeodeljefe commented Apr 11, 2016

cjihrig Apr 11, 2016

bengl Apr 12, 2016

mscdex commented Apr 12, 2016

trevnorris commented Apr 12, 2016

Knighton910 Apr 12, 2016

Knighton910 commented Apr 12, 2016

trevnorris commented Apr 12, 2016

benjamingr Apr 12, 2016

trevnorris Apr 14, 2016

benjamingr commented Apr 12, 2016

mscdex commented Apr 12, 2016

jasnell commented Apr 12, 2016

trevnorris commented Apr 14, 2016

benjamingr commented Apr 14, 2016

Fishrock123 commented Apr 14, 2016

Fishrock123 commented Apr 14, 2016

rvagg Apr 14, 2016

trevnorris Apr 14, 2016

rvagg commented Apr 14, 2016

bengl Apr 14, 2016

trevnorris Apr 14, 2016

trevnorris commented Apr 15, 2016

mscdex commented Apr 15, 2016

trevnorris commented Apr 15, 2016

MylesBorins commented Apr 21, 2016

trevnorris commented Apr 26, 2016


		### API Gaps

		While APIs based using `EventEmitter` can use `bind()` and errback style

doc: add domain post mortem #6159

doc: add domain post mortem #6159

Conversation

trevnorris commented Apr 11, 2016

Checklist

Affected core subsystem(s)

Description of change

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eljefedelrodeodeljefe commented Apr 11, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mscdex commented Apr 12, 2016

trevnorris commented Apr 12, 2016

Choose a reason for hiding this comment

Knighton910 commented Apr 12, 2016

trevnorris commented Apr 12, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benjamingr commented Apr 12, 2016

mscdex commented Apr 12, 2016

jasnell commented Apr 12, 2016

trevnorris commented Apr 14, 2016

benjamingr commented Apr 14, 2016

Fishrock123 commented Apr 14, 2016

Fishrock123 commented Apr 14, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rvagg commented Apr 14, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trevnorris commented Apr 15, 2016

mscdex commented Apr 15, 2016

trevnorris commented Apr 15, 2016

MylesBorins commented Apr 21, 2016

trevnorris commented Apr 26, 2016