<!--introduced_in=v0.10.0-->

To use the HTTP server and client one must `require('http')`.

of the protocol which have been traditionally difficult to use.

In particular, large, possibly chunk-encoded, messages. The interface is

careful to never buffer entire requests or responses--the

user is able to stream data.

HTTP message headers are represented by an object like this:

{ 'content-length': '123',

'content-type': 'text/plain',

'connection': 'keep-alive',

'host': 'mysite.com',

'accept': '*/*' }

```

Keys are lowercased. Values are not modified.

HTTP API is very low-level. It deals with stream handling and message

parsing only. It parses a message into headers and body but it does not

parse the actual headers or the body.

The raw headers as they were received are retained in the `rawHeaders`

property, which is an array of `[key, value, key2, value2, ...]`. For

example, the previous message header object might have a `rawHeaders`

list like the following:

[ 'ConTent-Length', '123456',

'content-LENGTH', '123',

'content-type', 'text/plain',

'CONNECTION', 'keep-alive',

'Host', 'mysite.com',

'accepT', '*/*' ]

```

<!-- YAML

added: v0.3.4

-->

An `Agent` is responsible for managing connection persistence

and reuse for HTTP clients. It maintains a queue of pending requests

for a given host and port, reusing a single socket connection for each

until the queue is empty, at which time the socket is either destroyed

or put into a pool where it is kept to be used again for requests to the

same host and port. Whether it is destroyed or pooled depends on the

`keepAlive` [option](#http_new_agent_options).

Pooled connections have TCP Keep-Alive enabled for them, but servers may

still close idle connections, in which case they will be removed from the

pool and a new connection will be made when a new HTTP request is made for

that host and port. Servers may also refuse to allow multiple requests

over the same connection, in which case the connection will have to be

remade for every request and cannot be pooled. The `Agent` will still make

the requests to that server, but each one will occur over a new connection.

When a connection is closed by the client or the server, it is removed

from the pool. Any unused sockets in the pool will be unrefed so as not

to keep the Node.js process running when there are no outstanding requests.

(see [socket.unref()]).

It is good practice, to [`destroy()`][] an `Agent` instance when it is no

longer in use, because unused sockets consume OS resources.

```js

http.get(options, (res) => {

// Do stuff

}).on('socket', (socket) => {

socket.emit('agentRemove');

});

```

`{agent: false}` as an option to the `http.get()` or `http.request()`

functions, a one-time use `Agent` with default options will be used

for the client connection.

```js

http.get({

hostname: 'localhost',

port: 80,

path: '/',

agent: false // create a new agent just for this one request

}, (res) => {

// Do stuff with response

<!-- YAML

added: v0.3.4

-->

* `options` {Object} Set of configurable options to set on the agent.

Can have the following fields:

having to reestablish a TCP connection. Defaults to `false`

* `keepAliveMsecs` {number} When using the `keepAlive` option, specifies

options.agent = keepAliveAgent;

http.request(options, onResponseCallback);

```

<!-- YAML

added: v0.11.4

-->

* `options` {Object} Options containing connection details. Check

[`net.createConnection()`][] for the format of the options

* `callback` {Function} Callback function that receives the created socket

* Returns: {net.Socket}

Produces a socket/stream to be used for HTTP requests.

By default, this function is the same as [`net.createConnection()`][]. However,

A socket/stream can be supplied in one of two ways: by returning the

socket/stream from this function, or by passing the socket/stream to `callback`.

`callback` has a signature of `(err, stream)`.

### agent.keepSocketAlive(socket)

<!-- YAML

-->

* `socket` {net.Socket}

Called when `socket` is detached from a request and could be persisted by the

Agent. Default behavior is to:

```js

```

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

-->

* `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.

<!-- YAML

added: v0.11.4

-->

sockets may hang open for quite a long time before the server

terminates them.

<!-- YAML

added: v0.11.4

-->

* {Object}

<!-- YAML

added: v0.11.4

-->

* `host` {string} A domain name or IP address of the server to issue the

request to

* `port` {number} Port of remote server

* `localAddress` {string} Local interface to bind for network connections

connection can be reused. For an HTTP agent, this returns

`host:port:localAddress` or `host:port:localAddress:family`. For an HTTPS agent,

the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options

that determine socket reusability.

<!-- YAML

added: v0.11.7

-->

sets the maximum number of sockets that will be left open in the free

state.

<!-- YAML

added: v0.3.6

-->

<!-- YAML

added: v0.5.9

-->

* {Object}

An object which contains queues of requests that have not yet been assigned to

sockets. Do not modify.

<!-- YAML

added: v0.3.6

-->

* {Object}

<!-- YAML

added: v0.1.17

-->

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 calling [`request.end()`][].

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

entirely discarded. However, if a [`'response'`][] event handler is added,

then the data from the response object **must** be consumed, either by

calling `response.read()` whenever there is a `'readable'` event, or

by adding a `'data'` handler, or by calling the `.resume()` method.

Until the data is consumed, the `'end'` event will not fire. Also, until

the data is read it will consume memory that can eventually lead to a

'process out of memory' error.

<!-- YAML

added: v1.4.1

-->

Emitted when the request has been aborted by the client. This event is only

emitted on the first call to `abort()`.

<!-- YAML

added: v0.7.0

-->

* `response` {http.IncomingMessage}

* `socket` {net.Socket}

* `head` {Buffer}

Emitted each time a server responds to a request with a `CONNECT` method. If

this event is not being listened for, clients receiving a `CONNECT` method will

have their connections closed.

```js

const http = require('http');

const net = require('net');

const url = require('url');

// Create an HTTP tunneling proxy

res.end('okay');

});

proxy.on('connect', (req, cltSocket, head) => {

// connect to an origin server

const srvUrl = url.parse(`http://${req.url}`);

const srvSocket = net.connect(srvUrl.port, srvUrl.hostname, () => {

cltSocket.write('HTTP/1.1 200 Connection Established\r\n' +

'Proxy-agent: Node.js-Proxy\r\n' +

'\r\n');

srvSocket.write(head);

srvSocket.pipe(cltSocket);

cltSocket.pipe(srvSocket);

});

});

// now that proxy is running

proxy.listen(1337, '127.0.0.1', () => {

// make a request to a tunneling proxy

port: 1337,

hostname: '127.0.0.1',

method: 'CONNECT',

path: 'www.google.com:80'

};

req.end();

req.on('connect', (res, socket, head) => {

console.log('got connected!');

// make a request over an HTTP tunnel

socket.write('GET / HTTP/1.1\r\n' +

'Host: www.google.com:80\r\n' +

'Connection: close\r\n' +

'\r\n');

socket.on('data', (chunk) => {

console.log(chunk.toString());

socket.on('end', () => {

proxy.close();

});

});

```

<!-- YAML

added: v0.3.2

-->

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: 'information'

<!-- YAML

added: REPLACEME

-->

Emitted when the server sends a 1xx response (excluding 101 Upgrade). This

event is emitted with a callback containing an object with a status code.

```js

const http = require('http');

const options = {

hostname: '127.0.0.1',

port: 8080,

path: '/length_request'

};

// Make a request

const req = http.request(options);

req.end();

req.on('information', (res) => {

});

```

101 Upgrade statuses do not fire this event due to their break from the

traditional HTTP request/response chain, such as web sockets, in-place TLS

upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the

[`'upgrade'`][] event instead.

<!-- YAML

added: v0.1.0

-->

<!-- YAML

added: v0.5.3

-->