Docs should mention that must read or resume knox responses in Node 0.10.x

[johnboxall]

When using knox to put ~800 files, I would seemingly randomly get an ENOTFOUND error.

Searching lead me to this comment:

nodejs/node-v0.x-archive#5545 (comment)

Which then led me to the the docs:

http://nodejs.org/api/http.html#http_class_http_clientrequest

I realized I was not consuming the responses I was receiving from S3! Now I've changed my put callbacks to call res.resume() and things are flying.

I believe that this issue was introduced with new style streams as the 0.8.25 docs don't seem to mention it: http://nodejs.org/docs/v0.8.25/api/all.html#all_class_http_clientrequest

Awesome lib thanks!

[domenic]

Hmm, what else would you be doing with them besides consuming them?

[johnboxall]

@domenic assuming that everything went awesome (no err? guess it worked!)

Digging through the source its apparent that you shouldn't be assuming that eg. you should be checking the status code etc to ensure your upload worked - but that burned me as I copied and pasted the examples and didn't dig into the source until I saw the errors.

[domenic]

I guess I'm not sure how this could cause ENOTFOUND. If you don't want to look at the response body, then you shouldn't need to resume it.

It'd probably be good to expand the doc examples to do status code checking though. It sounds more likely that you got some kind of error response and never realized??

Then again you said that adding res.resume() actually fixed things? How confusing.

[johnboxall]

@domenic so looking back at my codes, I added my own error handler to catch these errors as they were being raised after knox removed it's own error handler from the request object.

https://github.com/johnboxall/betty/blob/master/lib/client.js#L24
johnboxall/betty@472a557#L1L105

The issue I mentioned and it's related gist are exactly the behaviour I was seeing:

nodejs/node-v0.x-archive#5545 (comment)
https://gist.github.com/eelcocramer/5626801

The fix Isaacs recommends is to resume the response stream:

https://gist.github.com/isaacs/5785971

[domenic]

Ahh, the trick was the line

Since the data is never consumed, the fd is never read or destroyed, so it's never closed.

I didn't quite understand what the problem was with not having .resume() until I read that. How annoying. OK, thanks.