doc: http2 documentation

doc/api/http.markdown

@@ -394,10 +394,10 @@ Options:
 - `path`: Request path. Should include query string and fragments if any.
    E.G. `'/index.html?page=12'`
 - `headers`: An object containing request headers.
-- `agent`: Controls `Agent` behavior. Possible values:
+- `agent`: Controls `Agent` behavior. When an Agent is used request will default to Connection:keep-alive. Possible values:
  - `undefined` (default): use default `Agent` for this host and port.
  - `Agent` object: explicitly use the passed in `Agent`.
- - `false`: explicitly generate a new `Agent` for this host and port. `Agent` will not be re-used.
+ - `false`: opts out of connection pooling with an Agent, defaults request to Connection:close.
 
 `http.request()` returns an instance of the `http.ClientRequest`
 class. The `ClientRequest` instance is a writable stream. If one needs to
@@ -472,19 +472,84 @@ Example:
 
 
 ## http.Agent
-## http.getAgent(options)
 
-`http.request()` uses a special `Agent` for managing multiple connections to
-an HTTP server. Normally `Agent` instances should not be exposed to user
-code, however in certain situations it's useful to check the status of the
-agent. The `http.getAgent()` function allows you to access the agents.
+## http.globalAgent
+
+Global instance of Agent which is used as the default for all http client requests.
+
+### agent.maxSockets
+
+By default set to 5. Determines how many concurrent sockets the agent can have open per host.
+
+### agent.sockets
+
+An object which contains arrays of sockets currently in use by the Agent. Do not modify.
+
+### agent.requests
+
+An object which contains queues of requests that have not yet been assigned to sockets. Do not modify.
+
+
+## http.ClientRequest
+
+This object is created internally and returned from `http.request()`.  It
+represents an _in-progress_ request whose header has already been queued.  The
+header is still mutable using the `setHeader(name, value)`, `getHeader(name)`,
+`removeHeader(name)` API.  The actual header will be sent along with the first
+data chunk or when closing the connection.
+
+To get the response, add a listener for `'response'` to the request object.
+`'response'` will be emitted from the request object when the response
+headers have been received.  The `'response'` event is executed with one
+argument which is an instance of `http.ClientResponse`.
+
+During the `'response'` event, one can add listeners to the
+response object; particularly to listen for the `'data'` event. Note that
+the `'response'` event is called before any part of the response body is received,
+so there is no need to worry about racing to catch the first part of the
+body. As long as a listener for `'data'` is added during the `'response'`
+event, the entire body will be caught.
+
+
+    // Good
+    request.on('response', function (response) {
+      response.on('data', function (chunk) {
+        console.log('BODY: ' + chunk);
+      });
+    });
+
+    // Bad - misses all or part of the body
+    request.on('response', function (response) {
+      setTimeout(function () {
+        response.on('data', function (chunk) {
+          console.log('BODY: ' + chunk);
+        });
+      }, 10);
+    });
+
+This is a `Writable Stream`.
+
+This is an `EventEmitter` with the following events:
+
+### Event 'response'
+
+`function (response) { }`
+
+Emitted when a response is received to this request. This event is emitted only once. The
+`response` argument will be an instance of `http.ClientResponse`.
 
 Options:
 
 - `host`: A domain name or IP address of the server to issue the request to.
 - `port`: Port of remote server.
 - `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
 
+### Event: 'socket'
+
+`function (socket) { }`
+
+Emitted after a socket is assigned to this request.
+
 ### Event: 'upgrade'
 
 `function (response, socket, head) { }`
@@ -518,10 +583,7 @@ A client server pair that show you how to listen for the `upgrade` event using `
     srv.listen(1337, '127.0.0.1', function() {
 
       // make a request
-      var agent = http.getAgent('127.0.0.1', 1337);
-
       var options = {
-        agent: agent,
         port: 1337,
         host: '127.0.0.1',
         headers: {
@@ -533,85 +595,21 @@ A client server pair that show you how to listen for the `upgrade` event using `
       var req = http.request(options);
       req.end();
 
-      agent.on('upgrade', function(res, socket, upgradeHead) {
+      req.on('upgrade', function(res, socket, upgradeHead) {
         console.log('got upgraded!');
         socket.end();
         process.exit(0);
       });
     });
 
-
-### agent.maxSockets
-
-By default set to 5. Determines how many concurrent sockets the agent can have open.
-
-### agent.sockets
-
-An array of sockets currently in use by the Agent. Do not modify.
-
-### agent.queue
-
-A queue of requests waiting to be sent to sockets.
-
-
-
-## http.ClientRequest
-
-This object is created internally and returned from `http.request()`.  It
-represents an _in-progress_ request whose header has already been queued.  The
-header is still mutable using the `setHeader(name, value)`, `getHeader(name)`,
-`removeHeader(name)` API.  The actual header will be sent along with the first
-data chunk or when closing the connection.
-
-To get the response, add a listener for `'response'` to the request object.
-`'response'` will be emitted from the request object when the response
-headers have been received.  The `'response'` event is executed with one
-argument which is an instance of `http.ClientResponse`.
-
-During the `'response'` event, one can add listeners to the
-response object; particularly to listen for the `'data'` event. Note that
-the `'response'` event is called before any part of the response body is received,
-so there is no need to worry about racing to catch the first part of the
-body. As long as a listener for `'data'` is added during the `'response'`
-event, the entire body will be caught.
-
-
-    // Good
-    request.on('response', function (response) {
-      response.on('data', function (chunk) {
-        console.log('BODY: ' + chunk);
-      });
-    });
-
-    // Bad - misses all or part of the body
-    request.on('response', function (response) {
-      setTimeout(function () {
-        response.on('data', function (chunk) {
-          console.log('BODY: ' + chunk);
-        });
-      }, 10);
-    });
-
-This is a `Writable Stream`.
-
-This is an `EventEmitter` with the following events:
-
 ### Event: 'continue'
 
-`function () { }`
+`function ()`
 
 Emitted when the server sends a '100 Continue' HTTP response, usually because
 the request contained 'Expect: 100-continue'. This is an instruction that
 the client should send the request body.
 
-### Event 'response'
-
-`function (response) { }`
-
-Emitted when a response is received to this request. This event is emitted only once. The
-`response` argument will be an instance of `http.ClientResponse`.
-
-
 ### request.write(chunk, encoding='utf8')
 
 Sends a chunk of the body.  By calling this method