Galerie und tage
This commit is contained in:
262
node_modules/got/readme.md
generated
vendored
262
node_modules/got/readme.md
generated
vendored
@@ -6,27 +6,15 @@
|
||||
<br>
|
||||
</h1>
|
||||
|
||||
> Simplified HTTP requests
|
||||
> Simplified HTTP/HTTPS requests
|
||||
|
||||
[](https://travis-ci.org/sindresorhus/got) [](https://coveralls.io/github/sindresorhus/got?branch=master) [](https://npmjs.com/got)
|
||||
[](https://travis-ci.org/sindresorhus/got) [](https://coveralls.io/github/sindresorhus/got?branch=master) [](https://npmjs.com/got)
|
||||
|
||||
A nicer interface to the built-in [`http`](http://nodejs.org/api/http.html) module.
|
||||
|
||||
Created because [`request`](https://github.com/request/request) is bloated *(several megabytes!)*.
|
||||
It supports following redirects, promises, streams, retries, automagically handling gzip/deflate and some convenience options.
|
||||
|
||||
|
||||
## Highlights
|
||||
|
||||
- [Promise & stream API](#api)
|
||||
- [Request cancelation](#aborting-the-request)
|
||||
- [Follows redirects](#followredirect)
|
||||
- [Retries on network failure](#retries)
|
||||
- [Handles gzip/deflate](#decompress)
|
||||
- [Timeout handling](#timeout)
|
||||
- [Errors with metadata](#errors)
|
||||
- [JSON mode](#json)
|
||||
- [WHATWG URL support](#url)
|
||||
- [Electron support](#useelectronnet)
|
||||
Created because [`request`](https://github.com/mikeal/request) is bloated *(several megabytes!)*.
|
||||
|
||||
|
||||
## Install
|
||||
@@ -39,9 +27,15 @@ $ npm install --save got
|
||||
## Usage
|
||||
|
||||
```js
|
||||
const fs = require('fs');
|
||||
const got = require('got');
|
||||
|
||||
// Callback mode
|
||||
got('todomvc.com', (error, body, response) => {
|
||||
console.log(body);
|
||||
//=> '<!doctype html> ...'
|
||||
});
|
||||
|
||||
// Promise mode
|
||||
got('todomvc.com')
|
||||
.then(response => {
|
||||
console.log(response.body);
|
||||
@@ -52,7 +46,7 @@ got('todomvc.com')
|
||||
//=> 'Internal server error ...'
|
||||
});
|
||||
|
||||
// Streams
|
||||
// Stream mode
|
||||
got.stream('todomvc.com').pipe(fs.createWriteStream('index.html'));
|
||||
|
||||
// For POST, PUT and PATCH methods got.stream returns a WritableStream
|
||||
@@ -64,27 +58,25 @@ fs.createReadStream('index.html').pipe(got.stream.post('todomvc.com'));
|
||||
|
||||
It's a `GET` request by default, but can be changed in `options`.
|
||||
|
||||
#### got(url, [options])
|
||||
|
||||
Returns a Promise for a `response` object with a `body` property, a `url` property with the request URL or the final URL after redirects, and a `requestUrl` property with the original request URL.
|
||||
#### got(url, [options], [callback])
|
||||
|
||||
##### url
|
||||
|
||||
Type: `string` `Object`
|
||||
Type: `string`, `object`
|
||||
|
||||
The URL to request as simple string, a [`http.request` options](https://nodejs.org/api/http.html#http_http_request_options_callback), or a [WHATWG `URL`](https://nodejs.org/api/url.html#url_class_url).
|
||||
The URL to request or a [`http.request` options](https://nodejs.org/api/http.html#http_http_request_options_callback) object.
|
||||
|
||||
Properties from `options` will override properties in the parsed `url`.
|
||||
|
||||
##### options
|
||||
|
||||
Type: `Object`
|
||||
Type: `object`
|
||||
|
||||
Any of the [`http.request`](http://nodejs.org/api/http.html#http_http_request_options_callback) options.
|
||||
|
||||
###### body
|
||||
|
||||
Type: `string` `Buffer` `stream.Readable`
|
||||
Type: `string`, `buffer`, `readableStream`, `object`
|
||||
|
||||
*This is mutually exclusive with stream mode.*
|
||||
|
||||
@@ -94,55 +86,40 @@ If present in `options` and `options.method` is not set, `options.method` will b
|
||||
|
||||
If `content-length` or `transfer-encoding` is not set in `options.headers` and `body` is a string or buffer, `content-length` will be set to the body length.
|
||||
|
||||
If `body` is a plain object, it will be stringified with [`querystring.stringify`](https://nodejs.org/api/querystring.html#querystring_querystring_stringify_obj_sep_eq_options) and sent as `application/x-www-form-urlencoded`.
|
||||
|
||||
###### encoding
|
||||
|
||||
Type: `string` `null`<br>
|
||||
Type: `string`, `null`
|
||||
Default: `'utf8'`
|
||||
|
||||
[Encoding](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to be used on `setEncoding` of the response data. If `null`, the body is returned as a Buffer.
|
||||
|
||||
###### form
|
||||
|
||||
Type: `boolean`<br>
|
||||
Default: `false`
|
||||
|
||||
*This is mutually exclusive with stream mode.*
|
||||
|
||||
If set to `true` and `Content-Type` header is not set, it will be set to `application/x-www-form-urlencoded`.
|
||||
|
||||
`body` must be a plain object or array and will be stringified.
|
||||
Encoding to be used on `setEncoding` of the response data. If `null`, the body is returned as a Buffer.
|
||||
|
||||
###### json
|
||||
|
||||
Type: `boolean`<br>
|
||||
Type: `boolean`
|
||||
Default: `false`
|
||||
|
||||
*This is mutually exclusive with stream mode.*
|
||||
|
||||
If set to `true` and `Content-Type` header is not set, it will be set to `application/json`.
|
||||
|
||||
Parse response body with `JSON.parse` and set `accept` header to `application/json`. If used in conjunction with the `form` option, the `body` will the stringified as querystring and the response parsed as JSON.
|
||||
|
||||
`body` must be a plain object or array and will be stringified.
|
||||
Parse response body with `JSON.parse` and set `accept` header to `application/json`.
|
||||
|
||||
###### query
|
||||
|
||||
Type: `string` `Object`<br>
|
||||
Type: `string`, `object`
|
||||
|
||||
Query string object that will be added to the request URL. This will override the query string in `url`.
|
||||
|
||||
###### timeout
|
||||
|
||||
Type: `number` `Object`
|
||||
Type: `number`
|
||||
|
||||
Milliseconds to wait for the server to end the response before aborting request with `ETIMEDOUT` error.
|
||||
|
||||
This also accepts an object with separate `connect`, `socket`, and `request` fields for connection, socket, and entire request timeouts.
|
||||
Milliseconds after which the request will be aborted and an error event with `ETIMEDOUT` code will be emitted.
|
||||
|
||||
###### retries
|
||||
|
||||
Type: `number` `Function`<br>
|
||||
Default: `2`
|
||||
Type: `number`, `function`
|
||||
Default: `5`
|
||||
|
||||
Number of request retries when network errors happens. Delays between retries counts with function `1000 * Math.pow(2, retry) + Math.random() * 100`, where `retry` is attempt number (starts from 0).
|
||||
|
||||
@@ -152,42 +129,32 @@ Option accepts `function` with `retry` and `error` arguments. Function must retu
|
||||
|
||||
###### followRedirect
|
||||
|
||||
Type: `boolean`<br>
|
||||
Type: `boolean`
|
||||
Default: `true`
|
||||
|
||||
Defines if redirect responses should be followed automatically.
|
||||
|
||||
Note that if a `303` is sent by the server in response to any request type (`POST`, `DELETE`, etc.), got will automatically
|
||||
request the resource pointed to in the location header via `GET`. This is in accordance with [the spec](https://tools.ietf.org/html/rfc7231#section-6.4.4).
|
||||
##### callback(error, data, response)
|
||||
|
||||
###### decompress
|
||||
Function to be called when error or data are received. If omitted, a promise will be returned.
|
||||
|
||||
Type: `boolean`<br>
|
||||
Default: `true`
|
||||
###### error
|
||||
|
||||
Decompress the response automatically.
|
||||
`Error` object with HTTP status code as `statusCode` property.
|
||||
|
||||
If this is disabled, a compressed response is returned as a `Buffer`. This may be useful if you want to handle decompression yourself or stream the raw compressed data.
|
||||
The data you requested.
|
||||
|
||||
###### useElectronNet
|
||||
###### response
|
||||
|
||||
Type: `boolean`<br>
|
||||
Default: `true`
|
||||
The [response object](http://nodejs.org/api/http.html#http_http_incomingmessage).
|
||||
|
||||
When used in Electron, Got will automatically use [`electron.net`](https://electron.atom.io/docs/api/net/) instead of the Node.js `http` module. It should be fully compatible, but you can turn it off here if you encounter a problem. Please open an issue if you do!
|
||||
|
||||
|
||||
#### Streams
|
||||
|
||||
#### got.stream(url, [options])
|
||||
|
||||
`stream` method will return Duplex stream with additional events:
|
||||
When in stream mode, you can listen for events:
|
||||
|
||||
##### .on('request', request)
|
||||
|
||||
`request` event to get the request object of the request.
|
||||
|
||||
**Tip**: You can use `request` event to abort request:
|
||||
__Tip__: You can use `request` event to abort request:
|
||||
|
||||
```js
|
||||
got.stream('github.com')
|
||||
@@ -206,19 +173,19 @@ got.stream('github.com')
|
||||
|
||||
`error` event emitted in case of protocol error (like `ENOTFOUND` etc.) or status error (4xx or 5xx). The second argument is the body of the server response in case of status error. The third argument is response object.
|
||||
|
||||
#### got.get(url, [options])
|
||||
#### got.post(url, [options])
|
||||
#### got.put(url, [options])
|
||||
#### got.patch(url, [options])
|
||||
#### got.head(url, [options])
|
||||
#### got.delete(url, [options])
|
||||
#### got.get(url, [options], [callback])
|
||||
#### got.post(url, [options], [callback])
|
||||
#### got.put(url, [options], [callback])
|
||||
#### got.patch(url, [options], [callback])
|
||||
#### got.head(url, [options], [callback])
|
||||
#### got.delete(url, [options], [callback])
|
||||
|
||||
Sets `options.method` to the method name and makes a request.
|
||||
|
||||
|
||||
## Errors
|
||||
|
||||
Each error contains (if available) `statusCode`, `statusMessage`, `host`, `hostname`, `method`, `path`, `protocol` and `url` properties to make debugging easier.
|
||||
Each error contains (if available) `statusCode`, `statusMessage`, `host`, `hostname`, `method` and `path` properties to make debugging easier.
|
||||
|
||||
In Promise mode, the `response` is attached to the error.
|
||||
|
||||
@@ -232,24 +199,15 @@ When reading from response stream fails.
|
||||
|
||||
#### got.ParseError
|
||||
|
||||
When `json` option is enabled, server response code is 2xx, and `JSON.parse` fails.
|
||||
When `json` option is enabled and `JSON.parse` fails.
|
||||
|
||||
#### got.HTTPError
|
||||
|
||||
When server response code is not 2xx. Includes `statusCode`, `statusMessage`, and `redirectUrls` properties.
|
||||
When server response code is not 2xx. Contains `statusCode` and `statusMessage`.
|
||||
|
||||
#### got.MaxRedirectsError
|
||||
|
||||
When server redirects you more than 10 times. Includes a `redirectUrls` property, which is an array of the URLs Got was redirected to before giving up.
|
||||
|
||||
#### got.UnsupportedProtocolError
|
||||
|
||||
When given an unsupported protocol.
|
||||
|
||||
|
||||
## Aborting the request
|
||||
|
||||
The promise returned by Got has a `.cancel()` function which, when called, aborts the request.
|
||||
When server redirects you more than 10 times.
|
||||
|
||||
|
||||
## Proxies
|
||||
@@ -266,7 +224,7 @@ got('todomvc.com', {
|
||||
host: 'localhost'
|
||||
}
|
||||
})
|
||||
});
|
||||
}, () => {});
|
||||
```
|
||||
|
||||
|
||||
@@ -286,56 +244,6 @@ got('google.com', {
|
||||
```
|
||||
|
||||
|
||||
## Form data
|
||||
|
||||
You can use the [`form-data`](https://github.com/form-data/form-data) module to create POST request with form data:
|
||||
|
||||
```js
|
||||
const fs = require('fs');
|
||||
const got = require('got');
|
||||
const FormData = require('form-data');
|
||||
const form = new FormData();
|
||||
|
||||
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));
|
||||
|
||||
got.post('google.com', {
|
||||
body: form
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
## OAuth
|
||||
|
||||
You can use the [`oauth-1.0a`](https://github.com/ddo/oauth-1.0a) module to create a signed OAuth request:
|
||||
|
||||
```js
|
||||
const got = require('got');
|
||||
const crypto = require('crypto');
|
||||
const OAuth = require('oauth-1.0a');
|
||||
|
||||
const oauth = OAuth({
|
||||
consumer: {
|
||||
key: process.env.CONSUMER_KEY,
|
||||
secret: process.env.CONSUMER_SECRET
|
||||
},
|
||||
signature_method: 'HMAC-SHA1',
|
||||
hash_function: (baseString, key) => crypto.createHmac('sha1', key).update(baseString).digest('base64')
|
||||
});
|
||||
|
||||
const token = {
|
||||
key: process.env.ACCESS_TOKEN,
|
||||
secret: process.env.ACCESS_TOKEN_SECRET
|
||||
};
|
||||
|
||||
const url = 'https://api.twitter.com/1.1/statuses/home_timeline.json';
|
||||
|
||||
got(url, {
|
||||
headers: oauth.toHeader(oauth.authorize({url, method: 'GET'}, token)),
|
||||
json: true
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
## Unix Domain Sockets
|
||||
|
||||
Requests can also be sent via [unix domain sockets](http://serverfault.com/questions/124517/whats-the-difference-between-unix-socket-and-tcp-ip-socket). Use the following URL scheme: `PROTOCOL://unix:SOCKET:PATH`.
|
||||
@@ -351,66 +259,32 @@ got('http://unix:/var/run/docker.sock:/containers/json');
|
||||
got('unix:/var/run/docker.sock:/containers/json');
|
||||
```
|
||||
|
||||
## AWS
|
||||
|
||||
Requests to AWS services need to have their headers signed. This can be accomplished by using the [`aws4`](https://www.npmjs.com/package/aws4) package. This is an example for querying an ["Elasticsearch Service"](https://aws.amazon.com/elasticsearch-service/) host with a signed request.
|
||||
|
||||
```js
|
||||
const url = require('url');
|
||||
const AWS = require('aws-sdk');
|
||||
const aws4 = require('aws4');
|
||||
const got = require('got');
|
||||
const config = require('./config');
|
||||
|
||||
// Reads keys from the environment or `~/.aws/credentials`. Could be a plain object.
|
||||
const awsConfig = new AWS.Config({ region: config.region });
|
||||
|
||||
function request(uri, options) {
|
||||
const awsOpts = {
|
||||
region: awsConfig.region,
|
||||
headers: {
|
||||
accept: 'application/json',
|
||||
'content-type': 'application/json'
|
||||
},
|
||||
method: 'GET',
|
||||
json: true
|
||||
};
|
||||
|
||||
// We need to parse the URL before passing it to `got` so `aws4` can sign the request
|
||||
const opts = Object.assign(url.parse(uri), awsOpts, options);
|
||||
aws4.sign(opts, awsConfig.credentials);
|
||||
|
||||
return got(opts);
|
||||
}
|
||||
|
||||
request(`https://${config.host}/production/users/1`);
|
||||
|
||||
request(`https://${config.host}/production/`, {
|
||||
// All usual `got` options
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
## Tips
|
||||
|
||||
### User Agent
|
||||
## Tip
|
||||
|
||||
It's a good idea to set the `'user-agent'` header so the provider can more easily see how their resource is used. By default, it's the URL to this repo.
|
||||
|
||||
```js
|
||||
const got = require('got');
|
||||
const pkg = require('./package.json');
|
||||
var got = require('got');
|
||||
var pkg = require('./package.json');
|
||||
|
||||
got('todomvc.com', {
|
||||
headers: {
|
||||
'user-agent': `my-module/${pkg.version} (https://github.com/username/my-module)`
|
||||
'user-agent': 'my-module/' + pkg.version + ' (https://github.com/username/my-module)'
|
||||
}
|
||||
});
|
||||
}, function () {});
|
||||
```
|
||||
|
||||
### 304 Responses
|
||||
|
||||
Bear in mind, if you send an `if-modified-since` header and receive a `304 Not Modified` response, the body will be empty. It's your responsibility to cache and retrieve the body contents.
|
||||
## Node.js 0.10.x
|
||||
|
||||
It is a known issue with old good Node 0.10.x [`http.Agent`](https://nodejs.org/docs/v0.10.39/api/http.html#http_class_http_agent) and `agent.maxSockets`, which is set to `5`. This can cause low performance and in rare cases deadlocks. To avoid this you can set it manually:
|
||||
|
||||
```js
|
||||
require('http').globalAgent.maxSockets = Infinity;
|
||||
require('https').globalAgent.maxSockets = Infinity;
|
||||
```
|
||||
|
||||
This should only ever be done if you have Node version 0.10.x and at the top-level app layer.
|
||||
|
||||
|
||||
## Related
|
||||
@@ -421,11 +295,11 @@ Bear in mind, if you send an `if-modified-since` header and receive a `304 Not M
|
||||
|
||||
## Created by
|
||||
|
||||
[](https://sindresorhus.com) | [](https://github.com/floatdrop) | [](https://alextes.me)
|
||||
---|---|---
|
||||
[Sindre Sorhus](https://sindresorhus.com) | [Vsevolod Strukchinsky](https://github.com/floatdrop) | [Alexander Tesfamichael](https://alextes.me)
|
||||
[](http://sindresorhus.com) | [](https://github.com/floatdrop)
|
||||
---|---
|
||||
[Sindre Sorhus](http://sindresorhus.com) | [Vsevolod Strukchinsky](https://github.com/floatdrop)
|
||||
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
MIT © [Sindre Sorhus](http://sindresorhus.com)
|
||||
|
||||
Reference in New Issue
Block a user