FetchRequest
Represents a request for a resource using a URI.
By default, the supported schemes are HTTP, HTTPS, data:, and IPFS:.
Additional schemes can be added globally using registerGateway.
Example
req = new FetchRequest('https://www.ricmoo.com');
resp = await req.send();
resp.body.length;
Implements
Iterable<[string,string]>
Constructors
new FetchRequest()
new FetchRequest(url): FetchRequest
Create a new FetchRequest instance with default values.
Once created, each property may be set before issuing a .send() to make the request.
Parameters
| Parameter | Type |
|---|---|
url | string |
Returns
Source
Accessors
allowGzip
get allowGzip(): boolean
Enable and request gzip-encoded responses. The response will automatically be decompressed. (default: true)
Returns
boolean
Source
allowInsecureAuthentication
get allowInsecureAuthentication(): boolean
Allow Authentication credentials to be sent over insecure channels. (default: false)
Returns
boolean
Source
body
get body(): null | Uint8Array
The fetch body, if any, to send as the request body. (default: null)
When setting a body, the intrinsic Content-Type is automatically set and will be used if not overridden by
setting a custom header.
If body is null, the body is cleared (along with the intrinsic Content-Type).
If body is a string, the intrinsic Content-Type is set to text/plain.
If body is a Uint8Array, the intrinsic Content-Type is set to application/octet-stream.
If body is any other object, the intrinsic Content-Type is set to application/json.
Returns
null | Uint8Array
Source
credentials
get credentials(): null | string
The value that will be sent for the Authorization header.
To set the credentials, use the setCredentials method.
Returns
null | string
Source
getUrlFunc
get getUrlFunc(): FetchGetUrlFunc
This function is called to fetch content from HTTP and HTTPS URLs and is platform specific (e.g. nodejs vs browsers).
This is by default the currently registered global getUrl function, which can be changed using
registerGetUrl. If this has been set, setting is to null will cause this
FetchRequest (and any future clones) to revert back to using the currently registered global getUrl function.
Setting this is generally not necessary, but may be useful for developers that wish to intercept requests or to configurege a proxy or other agent.
Returns
Source
headers
get headers(): Record<string, string>
The headers that will be used when requesting the URI. All keys are lower-case.
This object is a copy, so any changes will NOT be reflected in the FetchRequest.
To set a header entry, use the setHeader method.
Returns
Record<string, string>
Source
method
get method(): string
The HTTP method to use when requesting the URI. If no method has been explicitly set, then GET is used if the
body is null and POST otherwise.
Returns
string
Source
preflightFunc
get preflightFunc(): null | FetchPreflightFunc
This function is called prior to each request, for example during a redirection or retry in case of server throttling.
This offers an opportunity to populate headers or update content before sending a request.
Returns
null | FetchPreflightFunc
Source
processFunc
get processFunc(): null | FetchProcessFunc
This function is called after each response, offering an opportunity to provide client-level throttling or updating response data.
Any error thrown in this causes the send() to throw.
To schedule a retry attempt (assuming the maximum retry limit has not been reached), use FetchResponse.throwThrottleError.
Returns
null | FetchProcessFunc
Source
retryFunc
get retryFunc(): null | FetchRetryFunc
This function is called on each retry attempt.
Returns
null | FetchRetryFunc
Source
timeout
get timeout(): number
The timeout (in milliseconds) to wait for a complete response. (default: 5 minutes)
Returns
number
Source
url
get url(): string
The fetch URL to request.
Returns
string
Source
Methods
cancel()
cancel(): void
Cancels the inflight response, causing a CANCELLED error to be rejected from the
send.
Returns
void
Source
clearHeaders()
clearHeaders(): void
Clear all headers, resetting all intrinsic headers.
Returns
void
Source
clone()
clone(): FetchRequest
Create a new copy of this request.
Returns
The new request.
Source
getHeader()
getHeader(key): string
Get the header for key, ignoring case.
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The header key to retrieve. |
Returns
string
The header value.
Source
hasBody()
hasBody(): this is FetchRequest & Object
Returns true if the request has a body.
Returns
this is FetchRequest & Object
Source
redirect()
redirect(location): FetchRequest
Returns a new FetchRequest that represents the redirection to location.
Parameters
| Parameter | Type | Description |
|---|---|---|
location | string | The location to redirect to. |
Returns
The new request.
Source
send()
send(): Promise<FetchResponse>
Resolves to the response by sending the request.
Returns
Promise<FetchResponse>
Source
setCredentials()
setCredentials(username, password): void
Sets an Authorization for username with password.
Parameters
| Parameter | Type | Description |
|---|---|---|
username | string | The username to use for basic authentication. |
password | string | The password to use for basic authentication. |
Returns
void
Throws
If the username contains a colon.
Source
setHeader()
setHeader(key, value): void
Set the header for key to value. All values are coerced to a string.
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The header key to set. |
value | string | number | The header value to set. |
Returns
void
Source
setThrottleParams()
setThrottleParams(params): void
Update the throttle parameters used to determine maximum attempts and exponential-backoff properties.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | FetchThrottleParams | The throttle parameters to set. |
Returns
void
Throws
If the slotInterval is not a positive integer.
Source
createDataGateway()
static createDataGateway(): FetchGatewayFunc
Creates a function that can “fetch” data URIs.
Note that this is automatically done internally to support data URIs, so it is not necessary to register it.
This is not generally something that is needed, but may be useful in a wrapper to perfom custom data URI functionality.
Returns
The gateway function.
Source
createGetUrlFunc()
static createGetUrlFunc(options?): FetchGetUrlFunc
Creates a getUrl function that fetches content from HTTP and HTTPS URLs.
The available options are dependent on the platform implementation of the default getUrl function.
This is not generally something that is needed, but is useful when trying to customize simple behaviour when fetching HTTP content.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | Record<string, any> | The options to use when creating the getUrl function. |
Returns
The getUrl function.
Throws
If the gateways are locked.
Source
createIpfsGatewayFunc()
static createIpfsGatewayFunc(baseUrl): FetchGatewayFunc
Creates a function that will fetch IPFS (unvalidated) from a custom gateway baseUrl.
The default IPFS gateway used internally is "https://gateway.ipfs.io/ipfs/".
Parameters
| Parameter | Type | Description |
|---|---|---|
baseUrl | string | The base URL of the IPFS gateway. |
Returns
The gateway function.
Source
getGateway()
static getGateway(scheme): null | FetchGatewayFunc
Get the current Gateway function for scheme.
Parameters
| Parameter | Type | Description |
|---|---|---|
scheme | string | The scheme to get the gateway for. |
Returns
null | FetchGatewayFunc
The gateway function, or null if not found.
Source
lockConfig()
static lockConfig(): void
Locks all static configuration for gateways and FetchGetUrlFunc registration.
Returns
void
Source
registerGateway()
static registerGateway(scheme, func): void
Use the func when fetching URIs using scheme.
This method affects all requests globally.
If lockConfig has been called, no change is made and this throws.
Parameters
| Parameter | Type | Description |
|---|---|---|
scheme | string | The scheme to register the gateway for. |
func | FetchGatewayFunc | The gateway function to use. |
Returns
void
Throws
If the scheme is http or https.
Source
registerGetUrl()
static registerGetUrl(getUrl): void
Use getUrl when fetching URIs over HTTP and HTTPS requests.
This method affects all requests globally.
If lockConfig has been called, no change is made and this throws.
Parameters
| Parameter | Type | Description |
|---|---|---|
getUrl | FetchGetUrlFunc | The function to use for fetching HTTP and HTTPS URIs. |
Returns
void
Throws
If the gateways are locked.
Source
Was this page helpful?