http: overridable `clientError`

Make default `clientError` behavior (close socket immediately)
overridable. With this APIs it is possible to write a custom error
handler, and to send, for example, a 400 HTTP response.

    http.createServer(...).on('clientError', function(err, socket) {
      socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
      socket.destroy();
    });

Fix: #4543
PR-URL: https://github.com/nodejs/node/pull/4557
Reviewed-By: Brian White <mscdex@mscdex.net>

1 files changed, 5 insertions, 0 deletions

diff --git a/doc/api/http.markdown b/doc/api/http.markdown
index aedc35208f..34e3417b51 100644
--- a/doc/api/http.markdown
+++ b/doc/api/http.markdown
@@ -421,6 +421,11 @@ not be emitted.
 `function (exception, socket) { }`
 
 If a client connection emits an `'error'` event, it will be forwarded here.
+Listener of this event is responsible for closing/destroying the underlying
+socket. For example, one may wish to more gracefully close the socket with an
+HTTP '400 Bad Request' response instead of abruptly severing the connection.
+
+Default behavior is to destroy the socket immediately on malformed request.
 
 `socket` is the [`net.Socket`][] object that the error originated from.