http: add reusedSocket property on client request

Set ClientRequest.reusedSocket property when reusing socket for request,
so user can handle retry base on wether the request is reusing a socket.
Refs: request/request#3131
PR-URL: #29715
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Weijia Wang <starkwang@126.com>

Author: themez

doc/api/http.md

@@ -673,6 +673,62 @@ Removes a header that's already defined into headers object.
 request.removeHeader('Content-Type');
 ```
 
+### `request.reusedSocket`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {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
+consthttp=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
+consthttp=require('http');
+constagent=newhttp.Agent({ keepAlive:true });
+
+functionretriableRequest() {
+constreq= 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)`
 <!-- YAML
 added: v1.6.0

lib/_http_agent.js

@@ -340,6 +340,7 @@ Agent.prototype.keepSocketAlive = function keepSocketAlive(socket) {
 
 Agent.prototype.reuseSocket=functionreuseSocket(socket,req){
 debug('have free socket');
+req.reusedSocket=true;
 socket.ref();
 };
 

lib/_http_client.js

@@ -195,6 +195,7 @@ function ClientRequest(input, options, cb) {
 this.upgradeOrConnect=false;
 this.parser=null;
 this.maxHeadersCount=null;
+this.reusedSocket=false;
 
 letcalled=false;
 

test/parallel/test-http-agent-keepalive.js

@@ -63,7 +63,8 @@ function checkDataAndSockets(body) {
 
 functionsecond(){
 // Request second, use the same socket
-get('/second',common.mustCall((res)=>{
+constreq=get('/second',common.mustCall((res)=>{
+assert.strictEqual(req.reusedSocket,true);
 assert.strictEqual(res.statusCode,200);
 res.on('data',checkDataAndSockets);
 res.on('end',common.mustCall(()=>{
@@ -80,7 +81,8 @@ function second() {
 
 functionremoteClose(){
 // Mock remote server close the socket
-get('/remote_close',common.mustCall((res)=>{
+constreq=get('/remote_close',common.mustCall((res)=>{
+assert.deepStrictEqual(req.reusedSocket,true);
 assert.deepStrictEqual(res.statusCode,200);
 res.on('data',checkDataAndSockets);
 res.on('end',common.mustCall(()=>{
@@ -120,7 +122,8 @@ function remoteError() {
 server.listen(0,common.mustCall(()=>{
 name=`localhost:${server.address().port}:`;
 // Request first, and keep alive
-get('/first',common.mustCall((res)=>{
+constreq=get('/first',common.mustCall((res)=>{
+assert.strictEqual(req.reusedSocket,false);
 assert.strictEqual(res.statusCode,200);
 res.on('data',checkDataAndSockets);
 res.on('end',common.mustCall(()=>{