diff --git a/doc/api/http.md b/doc/api/http.md index cfe26a812927e7..2f6b27e10c652e 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -673,6 +673,62 @@ Removes a header that's already defined into headers object. request.removeHeader('Content-Type'); ``` +### `request.reusedSocket` + + + +* {boolean} Whether the request is send through a reused socket. + +When sending request through a keep-alive enabled agent, the underlying socket +might be reused. But if server closes connection at unfortunate time, client +may run into a 'ECONNRESET' error. + +```js +const http = require('http'); + +// Server has a 5 seconds keep-alive timeout by default +http + .createServer((req, res) => { + res.write('hello\n'); + res.end(); + }) + .listen(3000); + +setInterval(() => { + // Adapting a keep-alive agent + http.get('http://localhost:3000', { agent }, (res) => { + res.on('data', (data) => { + // Do nothing + }); + }); +}, 5000); // Sending request on 5s interval so it's easy to hit idle timeout +``` + +By marking a request whether it reused socket or not, we can do +automatic error retry base on it. + +```js +const http = require('http'); +const agent = new http.Agent({ keepAlive: true }); + +function retriableRequest() { + const req = http + .get('http://localhost:3000', { agent }, (res) => { + // ... + }) + .on('error', (err) => { + // Check if retry is needed + if (req.reusedSocket && err.code === 'ECONNRESET') { + retriableRequest(); + } + }); +} + +retriableRequest(); +``` + ### `request.setHeader(name, value)`