diff options
Diffstat (limited to 'deps/npm/node_modules/request/README.md')
| -rw-r--r-- | deps/npm/node_modules/request/README.md | 218 |
1 files changed, 199 insertions, 19 deletions
diff --git a/deps/npm/node_modules/request/README.md b/deps/npm/node_modules/request/README.md index b05695d2c9..1878fdfbb8 100644 --- a/deps/npm/node_modules/request/README.md +++ b/deps/npm/node_modules/request/README.md @@ -1,6 +1,6 @@ -# Request -- Simplified HTTP client +# Request — Simplified HTTP client -[](https://nodei.co/npm/request/) +[](https://nodei.co/npm/request/) ## Super simple to use @@ -81,6 +81,106 @@ http.createServer(function (req, resp) { You can still use intermediate proxies, the requests will still follow HTTP forwards, etc. +## Proxies + +If you specify a `proxy` option, then the request (and any subsequent +redirects) will be sent via a connection to the proxy server. + +If your endpoint is an `https` url, and you are using a proxy, then +request will send a `CONNECT` request to the proxy server *first*, and +then use the supplied connection to connect to the endpoint. + +That is, first it will make a request like: + +``` +HTTP/1.1 CONNECT endpoint-server.com:80 +Host: proxy-server.com +User-Agent: whatever user agent you specify +``` + +and then the proxy server make a TCP connection to `endpoint-server` +on port `80`, and return a response that looks like: + +``` +HTTP/1.1 200 OK +``` + +At this point, the connection is left open, and the client is +communicating directly with the `endpoint-server.com` machine. + +See (the wikipedia page on HTTP +Tunneling)[http://en.wikipedia.org/wiki/HTTP_tunnel] for more +information. + +By default, when proxying `http` traffic, request will simply make a +standard proxied `http` request. This is done by making the `url` +section of the initial line of the request a fully qualified url to +the endpoint. + +For example, it will make a single request that looks like: + +``` +HTTP/1.1 GET http://endpoint-server.com/some-url +Host: proxy-server.com +Other-Headers: all go here + +request body or whatever +``` + +Because a pure "http over http" tunnel offers no additional security +or other features, it is generally simpler to go with a +straightforward HTTP proxy in this case. However, if you would like +to force a tunneling proxy, you may set the `tunnel` option to `true`. + +If you are using a tunneling proxy, you may set the +`proxyHeaderWhiteList` to share certain headers with the proxy. + +By default, this set is: + +``` +accept +accept-charset +accept-encoding +accept-language +accept-ranges +cache-control +content-encoding +content-language +content-length +content-location +content-md5 +content-range +content-type +connection +date +expect +max-forwards +pragma +proxy-authorization +referer +te +transfer-encoding +user-agent +via +``` + +Note that, when using a tunneling proxy, the `proxy-authorization` +header is *never* sent to the endpoint server, but only to the proxy +server. All other headers are sent as-is over the established +connection. + +## UNIX Socket + +`request` supports the `unix://` protocol for all requests. The path is assumed to be absolute to the root of the host file system. + +HTTP paths are extracted from the supplied URL by testing each level of the full URL against net.connect for a socket response. + +Thus the following request will GET `/httppath` from the HTTP server listening on `/tmp/unix.socket` + +```javascript +request.get('unix://tmp/unix.socket/httppath') +``` + ## Forms `request` supports `application/x-www-form-urlencoded` and `multipart/form-data` form uploads. For `multipart/related` refer to the `multipart` API. @@ -96,12 +196,20 @@ request.post('http://service.com/upload').form({key:'value'}) For `multipart/form-data` we use the [form-data](https://github.com/felixge/node-form-data) library by [@felixge](https://github.com/felixge). You don’t need to worry about piping the form object or setting the headers, `request` will handle that for you. ```javascript -var r = request.post('http://service.com/upload') +var r = request.post('http://service.com/upload', function optionalCallback (err, httpResponse, body) { + if (err) { + return console.error('upload failed:', err); + } + console.log('Upload successful! Server responded with:', body); +}) var form = r.form() form.append('my_field', 'my_value') form.append('my_buffer', new Buffer([1, 2, 3])) -form.append('my_file', fs.createReadStream(path.join(__dirname, 'doodle.png')) +form.append('my_file', fs.createReadStream(path.join(__dirname, 'doodle.png'))) form.append('remote_file', request('http://google.com/doodle.png')) + +// Just like always, `r` is a writable stream, and can be used as such (you have until nextTick to pipe it, etc.) +// Alternatively, you can provide a callback (that's what this example does — see `optionalCallback` above). ``` ## HTTP Authentication @@ -116,14 +224,37 @@ request.get('http://some.server.com/', { 'sendImmediately': false } }); +// or +request.get('http://some.server.com/').auth(null, null, true, 'bearerToken'); +// or +request.get('http://some.server.com/', { + 'auth': { + 'bearer': 'bearerToken' + } +}); ``` -If passed as an option, `auth` should be a hash containing values `user` || `username`, `password` || `pass`, and `sendImmediately` (optional). The method form takes parameters `auth(username, password, sendImmediately)`. +If passed as an option, `auth` should be a hash containing values `user` || `username`, `pass` || `password`, and `sendImmediately` (optional). The method form takes parameters `auth(username, password, sendImmediately)`. `sendImmediately` defaults to `true`, which causes a basic authentication header to be sent. If `sendImmediately` is `false`, then `request` will retry with a proper authentication header after receiving a `401` response from the server (which must contain a `WWW-Authenticate` header indicating the required authentication method). +Note that you can also use for basic authentication a trick using the URL itself, as specified in [RFC 1738](http://www.ietf.org/rfc/rfc1738.txt). +Simply pass the `user:password` before the host with an `@` sign. + +```javascript +var username = 'username', + password = 'password', + url = 'http://' + username + ':' + password + '@some.server.com'; + +request({url: url}, function (error, response, body) { + // Do more stuff with 'body' here +}); +``` + Digest authentication is supported, but it only works with `sendImmediately` set to `false`; otherwise `request` will send basic authentication on the initial request, which will probably cause the request to fail. +Bearer authentication is supported, and is activated when the `bearer` value is available. The value may be either a `String` or a `Function` returning a `String`. Using a function to supply the bearer token is particularly useful if used in conjuction with `defaults` to allow a single function to supply the last known token at the time or sending a request or to compute one on the fly. + ## OAuth Signing ```javascript @@ -158,7 +289,7 @@ request.post({url:url, oauth:oauth}, function (e, r, body) { , token: perm_token.oauth_token , token_secret: perm_token.oauth_token_secret } - , url = 'https://api.twitter.com/1/users/show.json?' + , url = 'https://api.twitter.com/1.1/users/show.json?' , params = { screen_name: perm_token.screen_name , user_id: perm_token.user_id @@ -172,14 +303,14 @@ request.post({url:url, oauth:oauth}, function (e, r, body) { }) ``` -### Custom HTTP Headers +## Custom HTTP Headers HTTP Headers, such as `User-Agent`, can be set in the `options` object. In the example below, we call the github API to find out the number of stars and forks for the request repository. This requires a custom `User-Agent` header as well as https. -``` +```javascript var request = require('request'); var options = { @@ -200,7 +331,7 @@ function callback(error, response, body) { request(options, callback); ``` -### request(options, callback) +## request(options, callback) The first argument can be either a `url` or an `options` object. The only required option is `uri`; all others are optional. @@ -209,11 +340,11 @@ The first argument can be either a `url` or an `options` object. The only requir * `method` - http method (default: `"GET"`) * `headers` - http headers (default: `{}`) * `body` - entity body for PATCH, POST and PUT requests. Must be a `Buffer` or `String`. -* `form` - when passed an object, this sets `body` to a querystring representation of value, and adds `Content-type: application/x-www-form-urlencoded; charset=utf-8` header. When passed no options, a `FormData` instance is returned (and is piped to request). -* `auth` - A hash containing values `user` || `username`, `password` || `pass`, and `sendImmediately` (optional). See documentation above. +* `form` - when passed an object or a querystring, this sets `body` to a querystring representation of value, and adds `Content-type: application/x-www-form-urlencoded; charset=utf-8` header. When passed no options, a `FormData` instance is returned (and is piped to request). +* `auth` - A hash containing values `user` || `username`, `pass` || `password`, and `sendImmediately` (optional). See documentation above. * `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header. Additionally, parses the response body as JSON. * `multipart` - (experimental) array of objects which contains their own headers and `body` attribute. Sends `multipart/related` request. See example below. -* `followRedirect` - follow HTTP 3xx responses as redirects (default: `true`) +* `followRedirect` - follow HTTP 3xx responses as redirects (default: `true`). This property can also be implemented as function which gets `response` object as a single argument and should return `true` if redirects should continue or `false` otherwise. * `followAllRedirects` - follow non-GET HTTP 3xx responses as redirects (default: `false`) * `maxRedirects` - the maximum number of redirects to follow (default: `10`) * `encoding` - Encoding to be used on `setEncoding` of response data. If `null`, the `body` is returned as a `Buffer`. @@ -224,17 +355,24 @@ The first argument can be either a `url` or an `options` object. The only requir * `oauth` - Options for OAuth HMAC-SHA1 signing. See documentation above. * `hawk` - Options for [Hawk signing](https://github.com/hueniverse/hawk). The `credentials` key must contain the necessary signing info, [see hawk docs for details](https://github.com/hueniverse/hawk#usage-example). * `strictSSL` - If `true`, requires SSL certificates be valid. **Note:** to use your own certificate authority, you need to specify an agent that was created with that CA as an option. -* `jar` - If `true`, remember cookies for future use (or define your custom cookie jar; see examples section) +* `jar` - If `true` and `tough-cookie` is installed, remember cookies for future use (or define your custom cookie jar; see examples section) * `aws` - `object` containing AWS signing information. Should have the properties `key`, `secret`. Also requires the property `bucket`, unless you’re specifying your `bucket` as part of the path, or the request doesn’t use a bucket (i.e. GET Services) * `httpSignature` - Options for the [HTTP Signature Scheme](https://github.com/joyent/node-http-signature/blob/master/http_signing.md) using [Joyent's library](https://github.com/joyent/node-http-signature). The `keyId` and `key` properties must be specified. See the docs for other options. * `localAddress` - Local interface to bind for network connections. +* `gzip` - If `true`, add an `Accept-Encoding` header to request compressed content encodings from the server (if not already present) and decode supported content encodings in the response. +* `tunnel` - If `true`, then *always* use a tunneling proxy. If + `false` (default), then tunneling will only be used if the + destination is `https`, or if a previous request in the redirect + chain used a tunneling proxy. +* `proxyHeaderWhiteList` - A whitelist of headers to send to a + tunneling proxy. The callback argument gets 3 arguments: -1. An `error` when applicable (usually from the `http.Client` option, not the `http.ClientRequest` object) -2. An `http.ClientResponse` object -3. The third is the `response` body (`String` or `Buffer`) +1. An `error` when applicable (usually from [`http.ClientRequest`](http://nodejs.org/api/http.html#http_class_http_clientrequest) object) +2. An [`http.IncomingMessage`](http://nodejs.org/api/http.html#http_http_incomingmessage) object +3. The third is the `response` body (`String` or `Buffer`, or JSON object if the `json` option is supplied) ## Convenience methods @@ -244,6 +382,22 @@ There are also shorthand methods for different HTTP METHODs and some other conve This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it. +**Note:** You can call `.defaults()` on the wrapper that is returned from `request.defaults` to add/override defaults that were previously defaulted. + +For example: +```javascript +//requests using baseRequest() will set the 'x-token' header +var baseRequest = request.defaults({ + headers: {x-token: 'my-token'} +}) + +//requests using specialRequest() will include the 'x-token' header set in +//baseRequest and will also include the 'special' header +var specialRequest = baseRequest.defaults({ + headers: {special: 'special value'} +}) +``` + ### request.put Same as `request()`, but defaults to `method: "PUT"`. @@ -334,7 +488,7 @@ request.jar() ) ``` -Cookies are disabled by default (else, they would be used in subsequent requests). To enable cookies, set `jar` to `true` (either in `defaults` or `options`). +Cookies are disabled by default (else, they would be used in subsequent requests). To enable cookies, set `jar` to `true` (either in `defaults` or `options`) and install `tough-cookie`. ```javascript var request = request.defaults({jar: true}) @@ -343,7 +497,7 @@ request('http://www.google.com', function () { }) ``` -To use a custom cookie jar (instead `request`’s global cookie jar), set `jar` to an instance of `request.jar()` (either in `defaults` or `options`) +To use a custom cookie jar (instead of `request`’s global cookie jar), set `jar` to an instance of `request.jar()` (either in `defaults` or `options`) ```javascript var j = request.jar() @@ -352,13 +506,39 @@ request('http://www.google.com', function () { request('http://images.google.com') }) ``` + OR ```javascript +// `npm install --save tough-cookie` before this works var j = request.jar() var cookie = request.cookie('your_cookie_here') -j.add(cookie) +j.setCookie(cookie, uri); request({url: 'http://www.google.com', jar: j}, function () { request('http://images.google.com') }) ``` + +To inspect your cookie jar after a request + +```javascript +var j = request.jar() +request({url: 'http://www.google.com', jar: j}, function () { + var cookie_string = j.getCookieString(uri); // "key1=value1; key2=value2; ..." + var cookies = j.getCookies(uri); + // [{key: 'key1', value: 'value1', domain: "www.google.com", ...}, ...] +}) +``` + +## Debugging + +There are at least three ways to debug the operation of `request`: + +1. Launch the node process like `NODE_DEBUG=request node script.js` + (`lib,request,otherlib` works too). + +2. Set `require('request').debug = true` at any time (this does the same thing + as #1). + +3. Use the [request-debug module](https://github.com/nylen/request-debug) to + view request and response headers and bodies. |