An object representing http, https and http2 keys for http.Agent, https.Agent and http2wrapper.Agent instance.
This is necessary because a request to one protocol might redirect to another.
In such a scenario, Got will switch over to the right protocol agent for you.
If a key is not present, it will default to a global agent.
This will set the accept-encoding header to gzip, deflate, br unless you set it yourself.
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.
Milliseconds to wait for the server to end the response before aborting the request with got.TimeoutError error (a.k.a. request property).
By default, there's no timeout.
This also accepts an object with the following fields to constrain the duration of each phase of the request lifecycle:
lookup starts when a socket is assigned and ends when the hostname has been resolved.
Does not apply when using a Unix domain socket.
connect starts when lookup completes (or when the socket is assigned if lookup does not apply to the request) and ends when the socket is connected.
secureConnect starts when connect completes and ends when the handshaking process completes (HTTPS only).
When specified, prefixUrl will be prepended to url.
The prefix can be any valid URL, either relative or absolute.
A trailing slash / is optional - one will be added automatically.
Note: prefixUrl will be ignored if the url argument is a URL instance.
Note: Leading slashes in input are disallowed when using this option to enforce consistency and avoid confusion.
For example, when the prefix URL is https://example.com/foo and the input is /bar, there's ambiguity whether the resulting URL would become https://example.com/foo/bar or https://example.com/bar.
The latter is used by browsers.
Tip: Useful when used with got.extend() to create niche-specific Got instances.
Tip: You can change prefixUrl using hooks as long as the URL still includes the prefixUrl.
If the URL doesn't include it anymore, it will throw.
Note #1: The body option cannot be used with the json or form option.
Note #2: If you provide this option, got.stream() will be read-only.
Note #3: If you provide a payload with the GET or HEAD method, it will throw a TypeError unless the method is GET and the allowGetBody option is set to true.
Note #4: This option is not enumerable and will not be merged with the instance defaults.
The content-length header will be automatically set if body is a string / Buffer / FormData / form-data instance, and content-length and transfer-encoding are not manually set in options.headers.
Since Got 12, the content-length is not automatically set when body is a fs.createReadStream.
// The query string is overridden by `searchParams` awaitgot('https://example.com/?query=a b', {searchParams: {query:'a b'}}); //=> https://example.com/?query=a+b
An instance of CacheableLookup used for making DNS lookups.
Useful when making lots of requests to different public hostnames.
CacheableLookup uses dns.resolver4(..) and dns.resolver6(...) under the hood and fall backs to dns.lookup(...) when the first two fail, which may lead to additional delay.
Note: This should stay disabled when making requests to internal hostnames such as localhost, database.local etc.
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. You can optionally turn on this behavior also for other redirect codes - see methodRewriting.
Returns boolean
Default
true
set followRedirect(value): void
Parameters
value: boolean
Returns void
followRedirects
get followRedirects(): unknown
Returns unknown
set followRedirects(_value): void
Parameters
_value: unknown
Returns void
maxRedirects
get maxRedirects(): number
If exceeded, the request will be aborted and a MaxRedirectsError will be thrown.
Returns number
Default
10
set maxRedirects(value): void
Parameters
value: number
Returns void
cache
get cache(): | undefined | string | boolean | StorageAdapter
A cache adapter instance for storing cached response data.
Determines if a got.HTTPError is thrown for unsuccessful responses.
If this is disabled, requests that encounter an error status code will be resolved with the response instead of throwing.
This may be useful if you are checking for resource availability and are expecting error responses.
Returns boolean
Default
true
set throwHttpErrors(value): void
Parameters
value: boolean
Returns void
username
get username(): string
Returns string
set username(value): void
Parameters
value: string
Returns void
password
get password(): string
Returns string
set password(value): void
Parameters
value: string
Returns void
http2
get http2(): boolean
If set to true, Got will additionally accept HTTP2 requests.
It will choose either HTTP/1.1 or HTTP/2 depending on the ALPN protocol.
Note: This option requires Node.js 15.10.0 or newer as HTTP/2 support on older Node.js versions is very buggy.
Note: Overriding options.request will disable HTTP2 support.
Set this to true to allow sending body for the GET method.
However, the HTTP/2 specification says that An HTTP GET request includes request header fields and no payload body, therefore when using the HTTP/2 protocol this option will have no effect.
This option is only meant to interact with non-compliant servers when you have no other choice.
Note: The RFC 7231 doesn't specify any particular behavior for the GET method having a payload, therefore it's considered an anti-pattern.
Specifies if the HTTP request method should be rewritten as GET on redirects.
As the specification prefers to rewrite the HTTP method only on 303 responses, this is Got's default behavior.
Setting methodRewriting to true will also rewrite 301 and 302 responses, as allowed by the spec. This is the behavior followed by curl and browsers.
An object representing limit, calculateDelay, methods, statusCodes, maxRetryAfter and errorCodes fields for maximum retry count, retry handler, allowed methods, allowed status codes, maximum Retry-After time and allowed error codes.
Delays between retries counts with function 1000 * Math.pow(2, retry) + Math.random() * 100, where retry is attempt number (starts from 1).
The calculateDelay property is a function that receives an object with attemptCount, retryOptions, error and computedValue properties for current retry count, the retry options, error and default computed value.
The function must return a delay in milliseconds (or a Promise resolving with it) (0 return value cancels retry).
By default, it retries only on the specified methods, status codes, and on these network errors:
ETIMEDOUT: One of the timeout limits were reached.
ECONNRESET: Connection was forcibly closed by a peer.
EADDRINUSE: Could not bind to any free port.
ECONNREFUSED: Connection was refused by the server.
EPIPE: The remote side of the stream being written has been closed.
ENOTFOUND: Couldn't resolve the hostname to an IP address.
ENETUNREACH: No internet connection.
EAI_AGAIN: DNS lookup timed out.
Note: If maxRetryAfter is set to undefined, it will use options.timeout.
Note: If Retry-After header is greater than maxRetryAfter, it will cancel the request.
const [response, buffer, json] = Promise.all([responsePromise, bufferPromise, jsonPromise]); // `response` is an instance of Got Response // `buffer` is an instance of Buffer // `json` is an object
Example
// This constbody = awaitgot(url).json();
// is semantically the same as this constbody = awaitgot(url, {responseType:'json', resolveBodyOnly:true});
Custom request function. The main purpose of this is to support HTTP2 using a wrapper.