parsing only. It parses a message into headers and body but it does not
parse the actual headers or the body.
-HTTPS is supported if OpenSSL is available on the underlying platform.
## http.Server
followed by `response.end()`.
-## http.Client
+## http.request(options, callback)
-An HTTP client is constructed with a server address as its
-argument, the returned handle is then used to issue one or more
-requests. Depending on the server connected to, the client might
-pipeline the requests or reestablish the stream after each
-stream. _Currently the implementation does not pipeline requests._
+Node maintains several connections per server to make HTTP requests.
+This function allows one to transparently issue requests.
-Example of connecting to `google.com`:
+Options:
- var http = require('http');
- var google = http.createClient(80, 'www.google.com');
- var request = google.request('GET', '/',
- {'host': 'www.google.com'});
- request.end();
- request.on('response', function (response) {
- console.log('STATUS: ' + response.statusCode);
- console.log('HEADERS: ' + JSON.stringify(response.headers));
- response.setEncoding('utf8');
- response.on('data', function (chunk) {
+- `host`: A domain name or IP address of the server to issue the request to.
+- `port`: Port of remote server.
+- `method`: A string specifing the HTTP request method. Possible values:
+ `'GET'` (default), `'POST'`, `'PUT'`, and `'DELETE'`.
+- `path`: Request path. Should include query string and fragments if any.
+ E.G. `'/index.html?page=12'`
+- `headers`: An object containing request headers.
+
+`http.request()` returns an instance of the `http.ClientRequest`
+class. The `ClientRequest` instance is a writable stream. If one needs to
+upload a file with a POST request, then write to the `ClientRequest` object.
+
+Example:
+
+ var options = {
+ host: 'www.google.com',
+ port: 80,
+ path: '/upload',
+ method: 'POST'
+ };
+
+ var req = http.request(options, function(res) {
+ console.log('STATUS: ' + res.statusCode);
+ console.log('HEADERS: ' + JSON.stringify(res.headers));
+ res.setEncoding('utf8');
+ res.on('data', function (chunk) {
console.log('BODY: ' + chunk);
});
});
-There are a few special headers that should be noted.
+ // write data to request body
+ req.write('data\n');
+ req.write('data\n');
+ req.end();
+
+Note that in the example `req.end()` was called. With `http.request()` one
+must always call `req.end()` to signify that you're done with the request -
+even if there is no data being written to the request body.
-* The 'Host' header is not added by Node, and is usually required by
- website.
+If any error is encountered during the request (be that with DNS resolution,
+TCP level errors, or actual HTTP parse errors) an `'error'` event is emitted
+on the returned request object.
+
+There are a few special headers that should be noted.
* Sending a 'Connection: keep-alive' will notify Node that the connection to
the server should be persisted until the next request.
and listen for the `continue` event. See RFC2616 Section 8.2.3 for more
information.
+## http.get(options, callback)
+
+Since most requests are GET requests without bodies, Node provides this
+convience method. The only difference between this method and `http.request()` is
+that it sets the method to GET and calls `req.end()` automatically.
+
+Example:
+
+ var options = {
+ host: 'www.google.com',
+ port: 80,
+ path: '/index.html'
+ };
+
+ http.get(options, function(res) {
+ console.log("Got response: " + res.statusCode);
+ }).on('error', function(e) {
+ console.log("Got error: " + e.message);
+ });
+
+
+## http.Agent
+
+`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.
### Event: 'upgrade'
the request contained 'Expect: 100-continue'. This is an instruction that
the client should send the request body.
+### agent.maxSockets
-### http.createClient(port, host='localhost', secure=false, [credentials])
-
-Constructs a new HTTP client. `port` and
-`host` refer to the server to be connected to. A
-stream is not established until a request is issued.
-
-`secure` is an optional boolean flag to enable https support and `credentials` is an optional
-credentials object from the crypto module, which may hold the client's private key,
-certificate, and a list of trusted CA certificates.
-
-If the connection is secure, but no explicit CA certificates are passed
-in the credentials, then node.js will default to the publicly trusted list
-of CA certificates, as given in <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
+By default set to 5. Determines how many concurrent sockets the agent can have open.
-### client.request(method='GET', path, [request_headers])
+### agent.sockets
-Issues a request; if necessary establishes stream. Returns a `http.ClientRequest` instance.
+An array of sockets currently inuse by the Agent. Do not modify.
-`method` is optional and defaults to 'GET' if omitted.
+### agent.queue
-`request_headers` is optional.
-Additional request headers might be added internally
-by Node. Returns a `ClientRequest` object.
+A queue of requests waiting to be sent to sockets.
-Do remember to include the `Content-Length` header if you
-plan on sending a body. If you plan on streaming the body, perhaps
-set `Transfer-Encoding: chunked`.
-
-*NOTE*: the request is not complete. This method only sends the header of
-the request. One needs to call `request.end()` to finalize the request and
-retrieve the response. (This sounds convoluted but it provides a chance for
-the user to stream a body to the server with `request.write()`.)
-
-### client.verifyPeer()
-
-Returns true or false depending on the validity of the server's certificate
-in the context of the defined or default list of trusted CA certificates.
-
-### client.getPeerCertificate()
-
-Returns a JSON structure detailing the server's certificate, containing a dictionary
-with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`.
## http.ClientRequest
-This object is created internally and returned from the `request()` method
-of a `http.Client`. It represents an _in-progress_ request whose header has
-already been sent.
+This object is created internally and returned from `http.request()`. It
+represents an _in-progress_ request whose header has already been sent.
To get the response, add a listener for `'response'` to the request object.
`'response'` will be emitted from the request object when the response
## http.ClientResponse
-This object is created when making a request with `http.Client`. It is
+This object is created when making a request with `http.request()`. It is
passed to the `'response'` event of the request object.
The response implements the `Readable Stream` interface.
Emitted when a piece of the message body is received.
- Example: A chunk of the body is given as the single
- argument. The transfer-encoding has been decoded. The
- body chunk a String. The body encoding is set with
- `response.setBodyEncoding()`.
### Event: 'end'
### response.resume()
Resumes a paused response.
-
-### response.client
-
-A reference to the `http.Client` that this response belongs to.
projects / platform / upstream / nodejs.git / commitdiff