What is the role of https.Agent in Node?

Question

In the Node https module docs, regarding https.request, an example is shown:

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
});

This example is slightly ambiguous in my opinion, and I've asked an SO question regarding this ambiguity and following a comment reaffirming the strange wording, opened an issue for this.

Regardless, I am still trying to understand the part that the Agent plays in this scenario, seeing as the https.Agent module does accept TLS connection options:

interface AgentOptions extends http.AgentOptions, tls.ConnectionOptions

The definition of the https.Agent object is:

An Agent object for HTTPS similar to http.Agent.

And the definition for the http.Agent object is:

An Agent is responsible for managing connection persistence and reuse for HTTP clients.

From this I understand that an Agent is 'in charge' of managing a connection - and clearly, the fact that https.Agent exists on top of the 'plain' http.Agent exists would imply that it is 'in charge' of managing an HTTPS connection - hence the TLS configuration options it may receive.

My question is this - does this mean that the Agent in this case has an added responsibility of configuring the network security of the requests? this is a strange API if this is true - I would have expected to see the network connection config on a separate key for the https.request (as is shown in the example after the snippet above). Why overload the same object for another responsibility? Really, why have an https.Agent at all? The http.Agent should control connection pooling and keeping connections alive, while another layer should control configuring the actual requests. The https.Agent object doesn't seem well-defined to me.

Answer 1

Actually the HTTPS doc points to some good resources, it also contains a link to HTTPS module source code, which reveals a lot. But to answer your questions:

does this mean that the Agent in this case has an added responsibility of configuring the network security of the requests

Yes sort of, your HTTPS agent can perform custom security feature, or even use external HTTPS implementations, but for the built-in https.Agent, the native TLS module is used, and the options you passed to constructor is ultimately passed to tls.connect, allowing you to configure custom TLS options.

Why overload the same object for another responsibility? Really, why have an https.Agent at all?

Because HTTPS runs on TLS. Actually https.Agent internally calls and constructs with http.Agent. The extra bits are mainly the use of SSL "session" over TCP "socket", if you search getName in https.Agent source and compare that to http.Agent's, you will find the SSL session cache are based on many more fields, like DHparams, client cert, etc. things that does not exist for HTTP at all.