Clarification on http agent documentation

[AJ ONeal (Home)]

It seems to me that it's rather uncommon for people to use their own http.Agent instances, but I'm creating a system with trusted peers and I found the existing docs to be unclear.

I have some questions here and if there is someone who understands that code well willing to answer me, I'd much appreciate it.
https://github.com/joyent/node/issues/8412

Certainly I want to be reusing the agent and some of the parameters don't need to / shouldn't be specified in the request each time.

After poking around the docs and code a bit I'm guessing that the example should be more like this:

var agent = new https.Agent({
  ca: [fs.readFileSync('test/fixtures/keys/agent2-ca.pem')]
, key: fs.readFileSync('test/fixtures/keys/agent2-key.pem')
, cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')

, maxSockets: 256

});

var req1 = https.request({

  agent: agent
, method: 'GET'

, hostname: 'site-a.example.com'
, port: 443
, path: '/one-thing'
}, function(res) {
  ...
}

var req1 = https.request({

  agent: agent
, method: 'GET'

, hostname: 'site-b.example.com'
, port: 443
, path: '/two-thing'
}, function(res) {
  ...
}

Or perhaps like this:

var agent = new https.Agent({ maxSockets: 256 });

var req1 = https.request({

  agent: agent
, method: 'GET'

, hostname: 'site-a.example.com'
, port: 443
, path: '/one-thing'
, ca: [fs.readFileSync('test/fixtures/keys/agent2-ca.pem')]
, key: fs.readFileSync('test/fixtures/keys/agent2-key.pem')
, cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
}, function(res) {
  ...
}

var req1 = https.request({

  agent: agent
, method: 'GET'

, hostname: 'site-b.example.com'
, port: 443
, path: '/two-thing'
, ca: [fs.readFileSync('test/fixtures/keys/agent2-ca.pem')]
, key: fs.readFileSync('test/fixtures/keys/agent2-key.pem')
, cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
}, function(res) {
  ...
}

Or maybe even


var agent = new https.Agent({
  maxSockets: 256
, hostname: 'site-b.example.com'

, port: 443
, ca: [fs.readFileSync('test/fixtures/keys/agent2-ca.pem')]
, key: fs.readFileSync('test/fixtures/keys/agent2-key.pem')
, cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
});

var req1 = https.request({

  agent: agent
, method: 'GET'

, path: '/one-thing'
}, function(res) {
  ...
}

var req1 = https.request({

  agent: agent
, method: 'GET'
, path: '/two-thing'

}, function(res) {
  ...
}

AJ ONeal

[CoolAJ86]

bump. Is there anyone familiar with the http module that can answer this?

[Jimb Esser]

I don't know the specifics, and I'm not sure what your actual question is, however, from my understanding of TLS and HTTP, your second example would not be valid - TLS (SSL) happens per-connection, and an agent pools connections, and multiple requests go out on each connection, so you could not reasonably put your SSL keys in the call to request(), since it may be re-using already established connections cached on the agent.  I suspect request() only uses the SSL options if passing agent: null to indicate no agent or connection pooling going on.

As for passing host/port to the Agent, in previous versions of node, IIRC, Agents used to be host+port specific, but now have their own cache of connections to arbitrary host+ports, I suspect that some of the examples including those may just be vestigial, though you should be able to test that trivially.