diff options
Diffstat (limited to 'deps/npm/node_modules/request/README.md')
| -rw-r--r-- | deps/npm/node_modules/request/README.md | 122 |
1 files changed, 52 insertions, 70 deletions
diff --git a/deps/npm/node_modules/request/README.md b/deps/npm/node_modules/request/README.md index 2317391149..b91623d2e3 100644 --- a/deps/npm/node_modules/request/README.md +++ b/deps/npm/node_modules/request/README.md @@ -28,6 +28,7 @@ request('http://www.google.com', function (error, response, body) { ## Table of contents - [Streaming](#streaming) +- [Promises & Async/Await](#promises--asyncawait) - [Forms](#forms) - [HTTP Authentication](#http-authentication) - [Custom HTTP Headers](#custom-http-headers) @@ -142,6 +143,22 @@ You can still use intermediate proxies, the requests will still follow HTTP forw --- +## Promises & Async/Await + +`request` supports both streaming and callback interfaces natively. If you'd like `request` to return a Promise instead, you can use an alternative interface wrapper for `request`. These wrappers can be useful if you prefer to work with Promises, or if you'd like to use `async`/`await` in ES2017. + +Several alternative interfaces are provided by the request team, including: +- [`request-promise`](https://github.com/request/request-promise) (uses [Bluebird](https://github.com/petkaantonov/bluebird) Promises) +- [`request-promise-native`](https://github.com/request/request-promise-native) (uses native Promises) +- [`request-promise-any`](https://github.com/request/request-promise-any) (uses [any-promise](https://www.npmjs.com/package/any-promise) Promises) + + +[back to top](#table-of-contents) + + +--- + + ## Forms `request` supports `application/x-www-form-urlencoded` and `multipart/form-data` form uploads. For `multipart/related` refer to the `multipart` API. @@ -170,7 +187,7 @@ var formData = { // Pass a simple key-value pair my_field: 'my_value', // Pass data via Buffers - my_buffer: new Buffer([1, 2, 3]), + my_buffer: Buffer.from([1, 2, 3]), // Pass data via Streams my_file: fs.createReadStream(__dirname + '/unicycle.jpg'), // Pass multiple values /w an Array @@ -204,7 +221,7 @@ For advanced cases, you can access the form-data object itself via `r.form()`. T var r = request.post('http://service.com/upload', function optionalCallback(err, httpResponse, body) {...}) var form = r.form(); form.append('my_field', 'my_value'); -form.append('my_buffer', new Buffer([1, 2, 3])); +form.append('my_buffer', Buffer.from([1, 2, 3])); form.append('custom_file', fs.createReadStream(__dirname + '/unicycle.jpg'), {filename: 'unicycle.jpg'}); ``` See the [form-data README](https://github.com/form-data/form-data) for more information & examples. @@ -608,7 +625,7 @@ request.get(options); ### Using `options.agentOptions` -In the example below, we call an API requires client side SSL certificate +In the example below, we call an API that requires client side SSL certificate (in PEM format) with passphrase protected private key (in PEM format) and disable the SSLv3 protocol: ```js @@ -667,7 +684,7 @@ request.get({ The `options.har` property will override the values: `url`, `method`, `qs`, `headers`, `form`, `formData`, `body`, `json`, as well as construct multipart data and read files from disk when `request.postData.params[].fileName` is present without a matching `value`. -a validation step will check if the HAR Request format matches the latest spec (v1.2) and will skip parsing if not matching. +A validation step will check if the HAR Request format matches the latest spec (v1.2) and will skip parsing if not matching. ```js var request = require('request') @@ -726,7 +743,7 @@ The first argument can be either a `url` or an `options` object. The only requir - `qs` - object containing querystring values to be appended to the `uri` - `qsParseOptions` - object containing options to pass to the [qs.parse](https://github.com/hapijs/qs#parsing-objects) method. Alternatively pass options to the [querystring.parse](https://nodejs.org/docs/v0.12.0/api/querystring.html#querystring_querystring_parse_str_sep_eq_options) method using this format `{sep:';', eq:':', options:{}}` - `qsStringifyOptions` - object containing options to pass to the [qs.stringify](https://github.com/hapijs/qs#stringifying) method. Alternatively pass options to the [querystring.stringify](https://nodejs.org/docs/v0.12.0/api/querystring.html#querystring_querystring_stringify_obj_sep_eq_options) method using this format `{sep:';', eq:':', options:{}}`. For example, to change the way arrays are converted to query strings using the `qs` module pass the `arrayFormat` option with one of `indices|brackets|repeat` -- `useQuerystring` - If true, use `querystring` to stringify and parse +- `useQuerystring` - if true, use `querystring` to stringify and parse querystrings, otherwise use `qs` (default: `false`). Set this option to `true` if you need arrays to be serialized as `foo=bar&foo=baz` instead of the default `foo[0]=bar&foo[1]=baz`. @@ -735,7 +752,7 @@ The first argument can be either a `url` or an `options` object. The only requir - `body` - entity body for PATCH, POST and PUT requests. Must be a `Buffer`, `String` or `ReadStream`. If `json` is `true`, then `body` must be a JSON-serializable object. - `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` header. When passed no options, a `FormData` instance is returned (and is piped to request). See "Forms" section above. -- `formData` - Data to pass for a `multipart/form-data` request. See +- `formData` - data to pass for a `multipart/form-data` request. See [Forms](#forms) section above. - `multipart` - array of objects which contain their own headers and `body` attributes. Sends a `multipart/related` request. See [Forms](#forms) section @@ -752,11 +769,11 @@ The first argument can be either a `url` or an `options` object. The only requir --- -- `auth` - A hash containing values `user` || `username`, `pass` || `password`, and `sendImmediately` (optional). See documentation above. -- `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). -- `aws` - `object` containing AWS signing information. Should have the properties `key`, `secret`, and optionally `session` (note that this only works for services that require session as part of the canonical string). 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). If you want to use AWS sign version 4 use the parameter `sign_version` with value `4` otherwise the default is version 2. **Note:** you need to `npm install aws4` first. -- `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. +- `auth` - a hash containing values `user` || `username`, `pass` || `password`, and `sendImmediately` (optional). See documentation above. +- `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). +- `aws` - `object` containing AWS signing information. Should have the properties `key`, `secret`, and optionally `session` (note that this only works for services that require session as part of the canonical string). 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). If you want to use AWS sign version 4 use the parameter `sign_version` with value `4` otherwise the default is version 2. If you are using SigV4, you can also include a `service` property that specifies the service name. **Note:** you need to `npm install aws4` first. +- `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. --- @@ -768,9 +785,9 @@ The first argument can be either a `url` or an `options` object. The only requir --- -- `encoding` - Encoding to be used on `setEncoding` of response data. If `null`, the `body` is returned as a `Buffer`. Anything else **(including the default value of `undefined`)** will be passed as the [encoding](http://nodejs.org/api/buffer.html#buffer_buffer) parameter to `toString()` (meaning this is effectively `utf8` by default). (**Note:** if you expect binary data, you should set `encoding: null`.) -- `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. **Note:** Automatic decoding of the response content is performed on the body data returned through `request` (both through the `request` stream and passed to the callback function) but is not performed on the `response` stream (available from the `response` event) which is the unmodified `http.IncomingMessage` object which may contain compressed data. See example below. -- `jar` - If `true`, remember cookies for future use (or define your custom cookie jar; see examples section) +- `encoding` - encoding to be used on `setEncoding` of response data. If `null`, the `body` is returned as a `Buffer`. Anything else **(including the default value of `undefined`)** will be passed as the [encoding](http://nodejs.org/api/buffer.html#buffer_buffer) parameter to `toString()` (meaning this is effectively `utf8` by default). (**Note:** if you expect binary data, you should set `encoding: null`.) +- `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. **Note:** Automatic decoding of the response content is performed on the body data returned through `request` (both through the `request` stream and passed to the callback function) but is not performed on the `response` stream (available from the `response` event) which is the unmodified `http.IncomingMessage` object which may contain compressed data. See example below. +- `jar` - if `true`, remember cookies for future use (or define your custom cookie jar; see examples section) --- @@ -778,14 +795,14 @@ The first argument can be either a `url` or an `options` object. The only requir - `agentClass` - alternatively specify your agent's class name - `agentOptions` - and pass its options. **Note:** for HTTPS see [tls API doc for TLS/SSL options](http://nodejs.org/api/tls.html#tls_tls_connect_options_callback) and the [documentation above](#using-optionsagentoptions). - `forever` - set to `true` to use the [forever-agent](https://github.com/request/forever-agent) **Note:** Defaults to `http(s).Agent({keepAlive:true})` in node 0.12+ -- `pool` - An object describing which agents to use for the request. If this option is omitted the request will use the global agent (as long as your options allow for it). Otherwise, request will search the pool for your custom agent. If no custom agent is found, a new agent will be created and added to the pool. **Note:** `pool` is used only when the `agent` option is not specified. +- `pool` - an object describing which agents to use for the request. If this option is omitted the request will use the global agent (as long as your options allow for it). Otherwise, request will search the pool for your custom agent. If no custom agent is found, a new agent will be created and added to the pool. **Note:** `pool` is used only when the `agent` option is not specified. - A `maxSockets` property can also be provided on the `pool` object to set the max number of sockets for all agents created (ex: `pool: {maxSockets: Infinity}`). - Note that if you are sending multiple requests in a loop and creating multiple new `pool` objects, `maxSockets` will not work as intended. To work around this, either use [`request.defaults`](#requestdefaultsoptions) with your pool options or create the pool object with the `maxSockets` property outside of the loop. -- `timeout` - Integer containing the number of milliseconds to wait for a +- `timeout` - integer containing the number of milliseconds to wait for a server to send response headers (and start the response body) before aborting the request. Note that if the underlying TCP connection cannot be established, the OS-wide TCP connection timeout will overrule the `timeout` option ([the @@ -795,9 +812,9 @@ default in Linux can be anywhere from 20-120 seconds][linux-timeout]). --- -- `localAddress` - Local interface to bind for network connections. -- `proxy` - An HTTP proxy to be used. Supports proxy Auth with Basic Auth, identical to support for the `url` parameter (by embedding the auth info in the `uri`) -- `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. +- `localAddress` - local interface to bind for network connections. +- `proxy` - an HTTP proxy to be used. Supports proxy Auth with Basic Auth, identical to support for the `url` parameter (by embedding the auth info in the `uri`) +- `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. - `tunnel` - controls the behavior of [HTTP `CONNECT` tunneling](https://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_tunneling) as follows: @@ -805,14 +822,14 @@ default in Linux can be anywhere from 20-120 seconds][linux-timeout]). - `true` - always tunnel to the destination by making a `CONNECT` request to the proxy - `false` - request the destination as a `GET` request. -- `proxyHeaderWhiteList` - A whitelist of headers to send to a +- `proxyHeaderWhiteList` - a whitelist of headers to send to a tunneling proxy. -- `proxyHeaderExclusiveList` - A whitelist of headers to send +- `proxyHeaderExclusiveList` - a whitelist of headers to send exclusively to a tunneling proxy and not to destination. --- -- `time` - If `true`, the request-response cycle (including all redirects) is timed at millisecond resolution. When set, the following properties are added to the response object: +- `time` - if `true`, the request-response cycle (including all redirects) is timed at millisecond resolution. When set, the following properties are added to the response object: - `elapsedTime` Duration of the entire request/response in milliseconds (*deprecated*). - `responseStartTime` Timestamp when the response began (in Unix Epoch milliseconds) (*deprecated*). - `timingStart` Timestamp of the start of the request (in Unix Epoch milliseconds). @@ -830,7 +847,7 @@ default in Linux can be anywhere from 20-120 seconds][linux-timeout]). - `download`: Duration of HTTP download (`timings.end` - `timings.response`) - `total`: Duration entire HTTP round-trip (`timings.end`) -- `har` - A [HAR 1.2 Request Object](http://www.softwareishard.com/blog/har-12-spec/#request), will be processed from HAR format into options overwriting matching values *(see the [HAR 1.2 section](#support-for-har-1.2) for details)* +- `har` - a [HAR 1.2 Request Object](http://www.softwareishard.com/blog/har-12-spec/#request), will be processed from HAR format into options overwriting matching values *(see the [HAR 1.2 section](#support-for-har-1.2) for details)* - `callback` - alternatively pass the request's callback in the options object The callback argument gets 3 arguments: @@ -874,55 +891,19 @@ var specialRequest = baseRequest.defaults({ }) ``` -### request.put +### request.METHOD() -Same as `request()`, but defaults to `method: "PUT"`. +These HTTP method convenience functions act just like `request()` but with a default method already set for you: -```js -request.put(url) -``` - -### request.patch +- *request.get()*: Defaults to `method: "GET"`. +- *request.post()*: Defaults to `method: "POST"`. +- *request.put()*: Defaults to `method: "PUT"`. +- *request.patch()*: Defaults to `method: "PATCH"`. +- *request.del() / request.delete()*: Defaults to `method: "DELETE"`. +- *request.head()*: Defaults to `method: "HEAD"`. +- *request.options()*: Defaults to `method: "OPTIONS"`. -Same as `request()`, but defaults to `method: "PATCH"`. - -```js -request.patch(url) -``` - -### request.post - -Same as `request()`, but defaults to `method: "POST"`. - -```js -request.post(url) -``` - -### request.head - -Same as `request()`, but defaults to `method: "HEAD"`. - -```js -request.head(url) -``` - -### request.del / request.delete - -Same as `request()`, but defaults to `method: "DELETE"`. - -```js -request.del(url) -request.delete(url) -``` - -### request.get - -Same as `request()` (for uniformity). - -```js -request.get(url) -``` -### request.cookie +### request.cookie() Function that creates a new cookie. @@ -1036,7 +1017,8 @@ the server sent a compressed response. console.log('server encoded the data as: ' + (response.headers['content-encoding'] || 'identity')) console.log('the decoded data is: ' + body) } - ).on('data', function(data) { + ) + .on('data', function(data) { // decompressed data as it is received console.log('decoded chunk: ' + data) }) |