http: overridable keep-alive behavior of Agent

Introduce two overridable `Agent` methods:
* `keepSocketAlive(socket)`
* `reuseSocket(socket, req)`
These methods can be overridden by particular `Agent` class child to
make keep-alive behavior customizable.
Motivation: destroy persisted sockets after some configurable timeout.
It is very non-trivial to do it with available primitives. Such program
will most likely need to poke with undocumented events and methods of
`Agent`. With introduced API such behavior is easy to implement.
Backport-PR-URL: #18168
PR-URL: #13005
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

Author: indutny

doc/api/http.md

@@ -159,6 +159,42 @@ socket/stream from this function, or by passing the socket/stream to `callback`.
 
 `callback` has a signature of `(err, stream)`.
 
+### agent.keepSocketAlive(socket)
+<!-- YAML
+added: REPLACEME
+-->
+
+*`socket` {net.Socket}
+
+Called when `socket` is detached from a request and could be persisted by the
+Agent. Default behavior is to:
+
+```js
+socket.unref();
+socket.setKeepAlive(agent.keepAliveMsecs);
+```
+
+This method can be overridden by a particular `Agent` subclass. If this
+method returns a falsy value, the socket will be destroyed instead of persisting
+it for use with the next request.
+
+### agent.reuseSocket(socket, request)
+<!-- YAML
+added: REPLACEME
+-->
+
+*`socket` {net.Socket}
+*`request` {http.ClientRequest}
+
+Called when `socket` is attached to `request` after being persisted because of
+the keep-alive options. Default behavior is to:
+
+```js
+socket.ref();
+```
+
+This method can be overridden by a particular `Agent` subclass.
+
 ### agent.destroy()
 <!-- YAML
 added: v0.11.4

lib/_http_agent.js

@@ -67,14 +67,15 @@ function Agent(options) {
 
 if(count>self.maxSockets||freeLen>=self.maxFreeSockets){
 socket.destroy();
-}else{
+}elseif(self.keepSocketAlive(socket)){
 freeSockets=freeSockets||[];
 self.freeSockets[name]=freeSockets;
-socket.setKeepAlive(true,self.keepAliveMsecs);
-socket.unref();
 socket._httpMessage=null;
 self.removeSocket(socket,options);
 freeSockets.push(socket);
+}else{
+// Implementation doesn't want to keep socket alive
+socket.destroy();
 }
 }else{
 socket.destroy();
@@ -142,13 +143,12 @@ Agent.prototype.addRequest = function(req, options) {
 if(freeLen){
 // we have a free socket, so use that.
 varsocket=this.freeSockets[name].shift();
-debug('have free socket');
 
 // don't leak
 if(!this.freeSockets[name].length)
 deletethis.freeSockets[name];
 
-socket.ref();
+this.reuseSocket(socket,req);
 req.onSocket(socket);
 this.sockets[name].push(socket);
 }elseif(sockLen<this.maxSockets){
@@ -279,7 +279,19 @@ Agent.prototype.removeSocket = function removeSocket(s, options) {
 }
 };
 
-Agent.prototype.destroy=function(){
+Agent.prototype.keepSocketAlive=functionkeepSocketAlive(socket){
+socket.setKeepAlive(true,this.keepAliveMsecs);
+socket.unref();
+
+returntrue;
+};
+
+Agent.prototype.reuseSocket=functionreuseSocket(socket,req){
+debug('have free socket');
+socket.ref();
+};
+
+Agent.prototype.destroy=functiondestroy(){
 varsets=[this.freeSockets,this.sockets];
 for(vars=0;s<sets.length;s++){
 varset=sets[s];

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

@@ -0,0 +1,67 @@
+'use strict';
+constcommon=require('../common');
+constassert=require('assert');
+
+consthttp=require('http');
+
+constserver=http.createServer((req,res)=>{
+res.end('ok');
+}).listen(0,common.mustCall(()=>{
+constagent=http.Agent({
+keepAlive: true,
+maxSockets: 5,
+maxFreeSockets: 2
+});
+
+constkeepSocketAlive=agent.keepSocketAlive;
+constreuseSocket=agent.reuseSocket;
+
+letcalled=0;
+letexpectedSocket;
+agent.keepSocketAlive=common.mustCall((socket)=>{
+assert(socket);
+
+called++;
+if(called===1){
+returnfalse;
+}elseif(called===2){
+expectedSocket=socket;
+returnkeepSocketAlive.call(agent,socket);
+}
+
+assert.strictEqual(socket,expectedSocket);
+returnfalse;
+},3);
+
+agent.reuseSocket=common.mustCall((socket,req)=>{
+assert.strictEqual(socket,expectedSocket);
+assert(req);
+
+returnreuseSocket.call(agent,socket,req);
+},1);
+
+functionreq(callback){
+http.request({
+method: 'GET',
+path: '/',
+ agent,
+port: server.address().port
+},common.mustCall((res)=>{
+res.resume();
+res.once('end',common.mustCall(()=>{
+setImmediate(callback);
+}));
+})).end();
+}
+
+// Should destroy socket instead of keeping it alive
+req(common.mustCall(()=>{
+// Should keep socket alive
+req(common.mustCall(()=>{
+// Should reuse the socket
+req(common.mustCall(()=>{
+server.close();
+}));
+}));
+}));
+}));