doc: clarify http.Agent constructor options

PR-URL: #26412Fixes: #26357 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Masashi Hirano <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Author: lpinca

doc/api/http.md

@@ -116,13 +116,19 @@ added: v0.3.4
  Can have the following fields:
 *`keepAlive`{boolean} Keep sockets around even when there are no
  outstanding requests, so they can be used for future requests without
- having to reestablish a TCP connection. **Default:**`false`.
+ having to reestablish a TCP connection. Not to be confused with the
+`keep-alive` value of the `Connection` header. The `Connection: keep-alive`
+ header is always sent when using an agent except when the `Connection`
+ header is explicitly specified or when the `keepAlive` and `maxSockets`
+ options are respectively set to `false` and `Infinity`, in which case
+`Connection: close` will be used. **Default:**`false`.
 *`keepAliveMsecs`{number} When using the `keepAlive` option, specifies
  the [initial delay](net.html#net_socket_setkeepalive_enable_initialdelay)
  for TCP Keep-Alive packets. Ignored when the
 `keepAlive` option is `false` or `undefined`. **Default:**`1000`.
 *`maxSockets`{number} Maximum number of sockets to allow per
- host. **Default:**`Infinity`.
+ host. Each request will use a new socket until the maximum is reached.
+**Default:**`Infinity`.
 *`maxFreeSockets`{number} Maximum number of sockets to leave open
  in a free state. Only relevant if `keepAlive` is set to `true`.
 **Default:**`256`.