This topic describes the Fetch API and the parameters of the Fetch API.

Fetch API methods

Fetch is an asynchronous thread. If you do not use the await keyword, Fetch does not block the execution of scripts. Fetch allows you to send up to 32 subrequests at a time. These subrequests are transmitted over persistent connections. Therefore, the performance is stable, and you do not need to manage connection pools.

You can call the Fetch API to send HTTP or HTTPS requests. Each redirect is considered as one request. Each Fetch API request supports up to 12 redirects.

  • Method definition

    fetch(arg, init) is used as the Fetch method. For more information about the Fetch method, see WorkerOrGlobalScope.fetch().

  • Method limits
    • The Fetch API supports domain names, but does not support IP addresses. HTTP requests use port 80 and HTTPS requests use port 443.
    • The credentials, referrer, referrerPolicy, cache, and integrity parameters in the init object are not used.
    • By default, the redirect parameter is set to manual, which specifies that fetch requests do not follow 3xx redirects. If you want fetch requests to follow 3xx redirects, set the redirect parameter to follow.
    Note
    • Browsers process fetch requests in different modes in the same way. For example, you can use CROS fetch to fetch resources from any origin servers by using Alibaba Cloud Dynamic Route for CDN (DCDN).
    • To modify the preceding limits, submit a ticket.

Redirect

The Fetch API supports 3xx redirects. Fetch requests can follow 3xx redirects. HTTP 3xx status codes include 301, 302, 303, 307, and 308. By default, the redirect parameter is set to manual, which specifies that fetch requests do not follow 3xx redirects. You can set the redirect parameter to one of the following values based on your business requirements:
  • {redirect: "manual"}: Fetch requests do not follow 3xx redirects. You must manually handle 3xx redirects.
  • {redirect: "error"}: Exceptions are thrown when 3xx redirects occur.
  • {redirect: "follow"}: Fetch requests follow 3xx redirects. The maximum number of 3xx redirects supported by the Fetch API is 20.
The following table describes 3xx redirects.
Status code Redirect description
301, 302, 303, and 308 The request method is changed to GET, and the body is ignored.
307 Fetch requests follow the redirect only if the request method is GET. If the request method is not GET, an exception is thrown.
Note The URL to which a request is redirected is contained in the Location header. If the Location header is missing, an exception is thrown.
  • The Location header can contain a list of URLs that are separated by commas (,). Requests are redirected only to the first URL in the list. Other URLs are ignored.
  • The Location header can contain absolute URLs or relative URLs.

Decompress

The Fetch API allows you to configure a decompression mode, for example, fetch("https://www.example.com",{decompress: "manual"}). The decompress parameter supports the following values:
  • manual: does not decompress data. If the server returns compressed data upon a fetch request, the data received by EdgeRoutine (ER) is also compressed.
  • decompress: automatically decompresses data. The Fetch API supports Gzip compression. ER automatically detects or decompresses data based on the Content-Encoding header. After ER decompresses data, ER changes the value of Content-Encoding. If the Gzip parameter is deleted, you can configure the following settings to prevent exceptions during data transmission:
    • content-encoding: gzip: ER recognizes the value of Content-Encoding and decompresses data.
    • content-encoding: gzip, identity: ER recognizes the value of Content-Encoding and decompresses data.
    Note Algorithms other than Gzip cause exceptions.
  • fallbackIdentity: The effect of this value is similar to the effect of the value decompress. If ER cannot recognize this value, ER does not decompress data.
Notice
  • The default value is decompress, which specifies that ER automatically uses Gzip to decompress data.
  • After the server compresses the data, you cannot pass the Content-Length header as needed if the response contains the Content-Length header. This is because the Content-Length header indicates the size of the data before decompression.

DcdnProxy

When you use the Fetch API to make subrequests in ER, ER directly sends HTTP requests to the Internet, as illustrated by Step 6 in the following figure. You can also use Alibaba Cloud DCDN as a proxy to process the subrequests, as shown in the following figure. In this case, the subrequests are processed in the following steps: 5→3. To use Alibaba Cloud DCDN as a proxy, set the dcdnProxy parameter, for example, fetch("http://www.example.com", {dcdnProxy: true}). If you use this method, the content retrieved from the URL specified in the Fetch API call is stored on DCDN nodes. Subsequent Fetch API calls can directly hit cache and return requested content to clients. This method does not need to fetch content from the origin servers.
Note The domain name, for example, www.example.com, from which you use the Fetch API to fetch resources must be added to Alibaba Cloud DCDN. If the domain name is not added to Alibaba Cloud DCDN, an HTTP 403 status code is returned. When you use Alibaba Cloud DCDN as a proxy, all configurations on Alibaba Cloud DCDN are triggered, including the caching and back-to-origin rules.
Workflow

content-length

If you configure the Content-Length header in a fetch request, data is encoded in the format that is specified in the Content-Length header, and the method used by the Fetch API to transmit data is changed. If you do not configure the Content-Length header, the Fetch API automatically fetches all data in the body stream and transmits the data. The transmitted data is encoded by using the chunked transfer encoding scheme.
  • Configure Content-Length
    • If the Content-Length header is set to a non-negative value, the Fetch API fetches data from the body stream based on the Content-Length header and transmits the fetched data. If Content-Length is set to 0, no data is transmitted.
    • If the Content-Length header is set to an invalid value, the Fetch API transmits all values in the body. The transmitted data is encoded by using the chunked transfer encoding scheme.
  • Examples
    The Fetch API automatically decompresses data. After the data is decompressed, the Content-Length header is retained in the response. The Content-Length header indicates the size of data before the data is decompressed. If you call the Fetch API after you modify the body, check whether the Content-Length header needs to be modified. If the Content-Length header needs to be modified, but you do not modify it, the content that is transmitted may be incorrect. For more information, see the following example:
    addEventListener('fetch', (event) => {
      event.respondWith(h(event));
    });
    
    async function h(event) {
      return fetch("http://www.example.com", {
        headers: event.request.headers,
        method: event.request.method,
        body: "SomeData"
      });
    }

    In the preceding example, a POST request that contains the Content-Length header is sent from a client. When you call the Fetch API to fetch data, the request body uses the Headers object from the client request. The value of the Content-Length header may be different from the actual size of the body. If the Headers object is transmitted, check whether the size of the body is changed.

Headers

  • Definition

    For more information about the Headers object, see Headers.

  • Limits

    A header records the amount of consumed memory resources. The maximum size of a Headers object is 8 KB. If the size of a Headers object exceeds this limit, a JavaScript exception is thrown.

  • Blacklist
    The Fetch API uses a header blacklist. If you attempt to read or write a header that is in the blacklist, an exception is thrown. The following table describes the headers that are included in the blacklist.
    • expect
    • te
    • trailer
    • upgrade
    • proxy-connection
    • connection
    • keep-alive
    • dnt
    • host
    • Reserved headers

Request

  • Definition

    For more information about the Request operation, see Request.

  • Limits
    The following properties of the Request object are not used.
    • context
    • credentials
    • destination
    • integrity
    • mode
    • referrer
    • referrerPolicy
    • cache
  • Use cases of the Request operation
    • Fetches the request method: request.method.
    • Fetches the request URL: request.url.
    • Fetches the request header: request.header.
    • Fetches the request payload: request.body. The Body property (body) is a ReadableStream object.
    • Fetches JSON data: await request.json().
    • Fetches form data: await request.formData().
    • Fetches strings encoded in UTF-8: await request.text().

    The Request operation is a standard API operation. The Request operation ignores the body when it fetches all values of the body without the need to consume the memory resources of ER. This minimizes the garbage collection (GC) pause time and ensures that all values of the request body are fetched from the underlying sockets. If you do not need to read the fetched body, you can call request.ignore in await request.ignore() for all fetch requests. After the body of a request is fetched, ER automatically sends the request to the connection pool for future use.

Response

  • Definition

    For more information about the Response operation, see Response.

  • Limits

    The useFinalURLS and error properties of the Response object are not used.

  • Use cases of the Response operation
    • Fetches the response code: response.status.
    • Fetches the reason phrase of a response: response.statusText.
    • Fetches the response header: response.headers.
    • Fetches the response URL: response.url.
    • Fetches a list of URLs that redirect to other URLs: response.urlList. This method is a non-standard method, which is similar to the implementation of the Body mixin by the Request object. You can use similar methods to fetch the Body object.

FormData

  • Definition

    For more information about the FormData operation, see FormData.

  • Limits

    The FormData operation is similar to the Headers operation. FormData limits the size of headers. If the size of a header exceeds the upper limit, an exception is thrown. If you send FormData as an HTTP request body, content-type is set to form-data/multipart by default.

URLSearchParams

  • Definition

    For more information about the URLSearchParams operation, see URLSearchParams().

  • Limits

    If you send URLSearchParams as an HTTP request body, content-type is set to application/x-www-form-urlencode by default. The data size cannot exceed 1,000 bytes.

Blob and File

  • Definition
    • For more information about the File operation, see File.
    • For more information about the Blob operation, see Blob.
  • Limits

    ER supports the Blob and File classes, which meet the standards of the Blob and File operations. ER cannot read or write files. You can pass the Blob and File classes supported by ER to the response body. The value of the content-type header is the same as the value of the MIME type parameter in the Blob or File operation.