error docs / guide

[stevemao]

I have been working with streams and I had a lot of trouble handling errors (as you can see I've raised a lot of issues). A lot of error handling guides are scattered across GitHub issues, tweets, blog posts and even joyent website. I want to improve docs/api/errors page. This is probably not on the roadmap, but it's definitely related some of them. It might help to make the direction of stream more clear. It will cover nodejs/node#4491

This is for error handling in general, but a bit more focused on error handling in stream.

[chrisdickinson]

/cc'ing @davepacheco, who I understand is the author of the Joyent error document from which much of the content of the Node errors document is derived, to advise.

[stevemao]

I know people would start arguing (from my research you have fundamentally different views). I have panicked in other threads so I try not to complain :)
Unfortunately this is pretty much the only "official" docs we have :(
I'll write something anyways just to kick it off.

[chrisdickinson]

@stevemao Ah — our views aren't fundamentally different. I think @davepacheco would be an excellent person to consult in order to improve the doc. My first draft of the existing error doc was derived from his original Joyent doc in an attempt to catalogue the common error codes, and his input would be super valuable for the future direction of the document.

[stevemao]

Here's another related issue: groundwater/nodejs-symposiums#5

[davepacheco]

I'd heard there was some interest in integrating some of the content from the Joyent error handling guide into the Node core docs. I think it would be great to see that happen. That document came out of a design discussion with several community members, and we spent a lot of time trying to make sure that document provided appropriate context as well as a holistic discussion, and also that it matched guidelines used in other communities.

Since you mentioned streams: I'd also be really interested to see some of the details around errors be better incorporated into other core API docs. There are some conventions people use, like: when 'error' is emitted from any EventEmitter, the object will usually emit no more events [except maybe 'close'] and cannot be used for anything else. This could be documented under EventEmitter or Streams. It would also be great if more core APIs documented exactly what operational errors they can experience. A lot of times this will include system-specific errors, in which case even a clause like "...and any system errors that can be returned by fork(2) on current system" would help.

[stevemao]

I'd heard there was some interest in integrating some of the content from the Joyent error handling guide into the Node core docs.

It'll be a very good start :) instead of a guide, it should be a rule because if streams handle error differently, they can't work together well. People should be enforced and educated to follow the same convention.

[benjamingr]

There is a fundamental disagreement inside Core about how errors should be handled. I for example disagree with the "recommended" error handling in that blog post and find it extremely irresponsible and risky to run servers doing it. Others feel the same way about the flow I use.

I'm fine with a solution that lets both sides express their views.

[stevemao]

There is a fundamental disagreement inside Core about how errors should be handled.

That's what I'm saying. I met @rvagg in person and expressed the feeling. He's pretty confident that there will be a solution soon :) Current situation is a bit unfortunate.

[eljefedelrodeodeljefe]

@benjamingr what exactly is your take on it? Since I find the article very educated, presenting options though a little biased (I like restify, sorry).

@bcantrill what was your opinion about this? Likely the article?

Concerning streams: Can't something as simple as the following just go into the docs into the stream.md? Basically saying: handle stream like so, and for broader discussion about errors go to the errors guide?

var a = createStream();
a.on('error', function(e){handleError(e)})
.pipe(b)
.on('error', function(e){handleError(e)})
.pipe(c)
.on('error', function(e){handleError(e)});

// or 

var a = createReadableStream()
var b = anotherTypeOfStream()
var c = createWriteStream()

a.on('error', handler)
b.on('error', handler)
c.on('error', handler)

a.pipe(b).pipe(c)

function handler (err) { console.log(err) }

taken from http://stackoverflow.com/questions/21771220/error-handling-with-node-js-streams

[bcantrill]

Yes, my opinion on this was to show agreement with the article, as it very much reflects our experiences running critical node.js-based services in production. I'll apologize for a bit of a drive-by in terms of thumbs-downing @benjamingr's comment, but I take (strong) issue with the characterization of the article as "extremely irresponsible" and "risky" -- especially without any more specific detail. As a practical matter, I assume @benjamingr is denigrating the recommendation that fatal programmer errors be fatal to the program -- from which I can only infer a naïveté with respect to how highly reliable systems actually get that way.

[eljefedelrodeodeljefe]

Calling for this to be on the agenda of the next docs-wg meeting with a priority.