View a markdown version of this page

Helper methods for network calls - Amazon CloudFront

Helper methods for network calls

This section applies if you send an HTTP request to an origin from inside your CloudFront Functions code. You can make network calls on viewer request or viewer response CloudFront Functions. CloudFront Functions has a module that provides helper methods to make network calls.

To use this module, create a CloudFront function using JavaScript runtime 2.0 and include the following statement in the first line of the function code:

import cf from "cloudfront";

For more information, see JavaScript runtime 2.0 features for CloudFront Functions.

The destination of the network call must be an origin that is already configured on the same distribution. You can't pass a URL with a host name. You must pass a path and the ID of the origin. In the CloudFront console this is the Name field on the origin, which is the same value that the CloudFront API and AWS CloudFormation call the origin Id. For more information, see Origin settings.

Sending the call through an origin takes advantage of CloudFront's origin handling capabilities. You don't have to reimplement any of the following in your function code:

  • Origin access control (OAC) signs the request with SigV4. You can call a private Amazon S3 bucket, a Lambda function URL, or another AWS origin without putting credentials in your function code.

  • With VPC origins, you can call a service in a private subnet, so the destination never needs a public endpoint.

  • Connection reuse means CloudFront usually already holds a warm connection to the origin, so the call avoids TCP and TLS setup.

  • Custom origin headers configured on the origin are sent on the call, so shared secrets and routing headers stay in your distribution configuration rather than in function code.

  • Origin mutual TLS (mTLS) configured on the origin applies to the call. CloudFront presents the origin's client certificate, so your function doesn't handle certificates or private keys.

The response timeout is the one origin setting that does not carry over. A network call times out after 1 second even when the origin is configured with a longer response timeout.

Note

Distributions on the free pricing plan don't support network calls. For more information, see CloudFront flat-rate pricing plans.

Note

Network calls are not supported when you test a function with the TestFunction API or the Test tab in the CloudFront console. In a test, cf.fetch() and cf.beacon() throw a TypeError ("cloudfront.fetch" is not available in test invocations). If your function does not catch the error, the test fails. Wrap the call in try and catch so the rest of the function can be tested.

Important

A function can make one network call per invocation. Both fetch() and beacon() count toward this one network call. A second network call throws an error.

Choose between a network call and CloudFront KeyValueStore

You can read data inside a function by using either a network call or Amazon CloudFront KeyValueStore. Your choice depends on how often the data changes and how current the answer needs to be.

A network call is most useful in the following situations:

  • When the data changes between requests and you need a current answer at request time, such as whether a token has been revoked or which segment a viewer belongs to.

  • When the dataset is too large to fit in a key value store. A key value store has a maximum total size, so a large dataset such as a full user table or a product catalog has to stay in the service that holds it.

CloudFront KeyValueStore is most useful in the following situations:

  • When the data is static or changes infrequently, such as redirect maps, lookup tables, or feature flags that change daily. CloudFront KeyValueStore reads at the edge with no external call, which gives better performance at lower cost.

  • When you need more than one lookup for a single request. A function can make only one network call per invocation, but it can read from CloudFront KeyValueStore repeatedly.

A function can use both. You might read an experiment configuration from CloudFront KeyValueStore to decide which test is active, then make a network call to assign the viewer a variant.

For more information about CloudFront KeyValueStore, see Helper methods for key value stores.

fetch() method

Use the fetch() method to send a request to an origin and read the response. The method returns a promise, so it must be used with await inside an async function.

Request

cf.fetch(path, options)
Important

Option names are case sensitive, and unknown options are ignored. For example, Method: 'POST' is ignored and the request is sent as GET, as with standard fetch(). If the call also has a body, it throws a TypeError, because a body is not allowed with GET.

The parameters can contain the following:

path (required)

The URI path, and optionally a query string, of the request. For example, /v1/authorize?scope=read. The path must start with /. CloudFront sends the request to the origin named in options.originId and appends the path to the origin's domain name. If the origin has an origin path configured, the path is appended after the origin path.

options (required)

The options can contain the following:

originId (required)

The ID of the origin to send the request to. Must exactly match the ID of an origin on the same distribution. In the CloudFront console, this is the Name field on the origin.

method (optional)

The HTTP method. One of GET, HEAD, POST, PUT, PATCH, DELETE, or OPTIONS. If this is not provided, GET is used.

The value must be upper case. Unlike standard fetch(), the method is not normalized, so a value such as 'post' throws a TypeError.

headers (optional)

Request headers as a plain object. Each property name is a header name and each value is a string, for example { 'content-type': 'application/json' }.

This format is not the same as event.request.headers. In the event structure, headers use the shape { 'content-type': { value: 'application/json' } }. Copying the event shape into the options throws an error.

For the headers that you can't set, see How CloudFront builds the request.

body (optional)

The request body. Can be a string, an ArrayBuffer, or an ArrayBufferView such as a Uint8Array. To send JSON, use JSON.stringify().

A body is not allowed with GET or HEAD, including when method is not provided and the default GET is used. A call with a body and one of these methods throws a TypeError (options.body is not allowed with GET or HEAD).

includeBody (optional)

Whether CloudFront reads the response body and makes it available to your function. If this is not provided, false is used. Set it to true when you need the body.

Without includeBody: true, every body accessor reads empty: text() resolves to "", json() resolves to null, and bytes() and arrayBuffer() resolve to empty values. Nothing is consumed, so bodyUsed stays false.

Response

The method returns a promise that resolves to a Response object. The object can contain the following:

status

The HTTP status code from the origin as a number.

ok

true if status is 200 to 299, otherwise false.

headers

A read-only property that holds the response headers as a Headers object. It supports the get(), has(), getSetCookie(), forEach(), keys(), values(), and entries() methods, and you can iterate over it.

Header names are case insensitive in get() and has(). get() returns null when the header is not present. getSetCookie() returns an array of every Set-Cookie value.

const type = response.headers.get('content-type'); const cookies = response.headers.getSetCookie();
text()

A promise that resolves to the body decoded as UTF-8 text. Invalid byte sequences are replaced.

json()

A promise that resolves to the body parsed as JSON. Rejects with SyntaxError if the body is not valid JSON.

bytes()

A promise that resolves to the raw body bytes as a Uint8Array. Buffer methods such as toString('base64') work on the result.

arrayBuffer()

A promise that resolves to the raw body bytes as an ArrayBuffer.

bodyUsed

true once the body has been read.

Important

You can read the body only once. After text(), json(), bytes(), or arrayBuffer(), any further read rejects with TypeError: body already read. Use bodyUsed to check whether it has been read. If you need the body more than once, keep the first result in a variable.

A network call response carries its own x-amz-cf-id, and it is not the same as the one on the viewer request that triggered your function. They are two separate requests with two separate identifiers. If you are investigating the network call, the identifier from the network call response is the one that matters. You can read it with response.headers.get('x-amz-cf-id').

Error handling

Wrap every await cf.fetch() in a try and catch block. Then decide whether your function should fail open and let the request through, or fail closed and block it. If an error is not caught, the function fails and CloudFront returns HTTP 503 to the viewer. This is the same as any other unhandled function error.

Invalid arguments reject the promise that fetch() returns, so an await inside a try and catch block handles both argument errors and errors from the call itself.

The method can throw the following errors:

TypeError

The call is invalid or the origin couldn't be reached. This could be from a bad argument, a disallowed header, a request or response that is too large, an unknown origin ID, or a distribution that does not support network calls.

It also covers an origin that CloudFront could not reach or complete the call with: a DNS failure, a connection failure, a TLS failure, origin response headers that are too large for CloudFront, or the origin closing the connection. The message names the reason, for example The request could not be completed due to OriginDnsError. Origins that resolve to loopback or reserved IP addresses are refused in the same way, with OriginDnsError.

TimeoutError

The origin did not return a complete response within 1 second. The limit applies to the whole call, including connection setup and reading the body.

InternalError

The call failed inside CloudFront.

SyntaxError

Thrown by response.json() when the body is not valid JSON. Check what your origin returns.

Note

A TLS failure to a distant origin, or an origin on a private IP address, can surface as a TimeoutError rather than an origin error, because the 1 second limit is reached first. To call a service in a private network, use VPC origins.

Warning

Only one network call is allowed per invocation, so promise combinators can't be used to make more than one. Passing two cf.fetch() calls to Promise.all() throws an error. For more information about promise combinators and function memory, see Use async and await.

Example: Authorization check that fails closed

This function only lets the request through if the authorization service approves it. If the service can't be reached, the request is blocked.

Replace /v1/authorize with the path on your origin, and auth-service with the ID of your origin.

The following JavaScript example sends the viewer's token to an authorization service:

import cf from 'cloudfront'; async function handler(event) { const request = event.request; const auth = request.headers['authorization']; if (!auth) { return { statusCode: 401, statusDescription: 'Unauthorized' }; } try { const response = await cf.fetch('/v1/authorize', { originId: 'auth-service', method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token: auth.value, uri: request.uri }), includeBody: true, }); if (!response.ok) { console.log('authorize returned ' + response.status); return { statusCode: 403, statusDescription: 'Forbidden' }; } const result = await response.json(); request.headers['x-user-id'] = { value: result.userId }; return request; } catch (e) { console.log('Authorization check failed: ' + e.name + ': ' + e.message); return { statusCode: 503, statusDescription: 'Service Unavailable' }; } }
Example: Read dynamic configuration from Amazon S3

This function reads a configuration object from an Amazon S3 origin and uses it to tag the request. The method option is omitted because GET is the default. If the Amazon S3 bucket is private and origin access control (OAC) is set up on the origin, CloudFront signs the request to the bucket. This function fails open, because a missing configuration should not block the viewer.

Replace /config/experiments.json with the path of your object, and config-bucket with the ID of your origin.

The following JavaScript example reads the configuration object:

import cf from 'cloudfront'; async function handler(event) { const request = event.request; try { const response = await cf.fetch('/config/experiments.json', { originId: 'config-bucket', includeBody: true, }); if (response.ok) { const config = await response.json(); request.headers['x-experiment'] = { value: config.activeExperiment }; } } catch (e) { console.log('Config lookup failed: ' + e.name); } return request; }

beacon() method

Use the beacon() method to send a request to an origin without waiting for the response. Use it for analytics events, audit records, and anything else where the viewer should not wait on delivery. A beacon counts against the network call quota. Each invocation can make one network call in total, using either fetch() or beacon(), not one of each. Call beacon() inside the handler. It doesn't work from global scope.

Important

A beacon is best effort. Don't use it for anything that must succeed. Argument errors throw immediately and can be caught in a try and catch block, but failures that happen after the function has moved on are not surfaced to your function. Setting logDeliveryErrors to true is the only way to see those errors.

Request

cf.beacon(path, options)

The parameters can contain the following:

path (required)

The URI path, and optionally a query string, of the request. For example, /v1/events?source=edge. The path must start with /. CloudFront sends the request to the origin named in options.originId and appends the path to the origin's domain name. If the origin has an origin path configured, the path is appended after the origin path.

options (required)

The options can contain the following:

originId (required)

The ID of the origin to send the request to. Must exactly match the ID of an origin on the same distribution. In the CloudFront console, this is the Name field on the origin.

method (optional)

The HTTP method. One of GET, HEAD, POST, PUT, PATCH, DELETE, or OPTIONS. Must be upper case. If this is not provided, GET is used.

headers (optional)

Request headers as a plain object. Each property name is a header name and each value is a string, for example { 'content-type': 'application/json' }.

This format is not the same as event.request.headers. In the event structure, headers use the shape { 'content-type': { value: 'application/json' } }. Copying the event shape into the options throws an error.

body (optional)

The request body. Can be a string, an ArrayBuffer, or an ArrayBufferView such as a Uint8Array. To send JSON, use JSON.stringify(). A body is not allowed with GET or HEAD, including the default GET, and throws a TypeError.

logDeliveryErrors (optional)

Whether delivery failures are written to CloudWatch Logs. If this is not provided, false is used. Set it to true to see beacons that fail after your function has returned. The errors go to the same log group as console.log() messages from the function. For more information, see CloudFront Functions logs.

A beacon counts as delivered when the origin returns a 2xx or 3xx status. Any other origin status is logged as "cloudfront.beacon": origin returned status.

Note

The includeBody option of the fetch() method is not supported, because there is no response to read. Passing this option throws a TypeError.

Response

The method returns undefined immediately and your function continues.

Example: Send an analytics event

The handler is not async, because there is nothing to await.

The following JavaScript example sends an event without waiting for a response:

import cf from 'cloudfront'; function handler(event) { const request = event.request; cf.beacon('/events', { originId: 'analytics-service', method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ uri: request.uri, viewerIp: event.viewer.ip }), logDeliveryErrors: true, }); return request; }

How CloudFront builds the request

CloudFront constructs each network call from scratch. Except for the proxy headers listed below, it does not copy the viewer's headers, cookies, or query string onto the request. If your origin needs something from the viewer request, pass it explicitly in headers or body.

You can set the host header on a network call to a custom origin that doesn't use origin access control. This differs from the viewer request, where the host header in the Request object is read only. Use it when the destination routes by host, such as a service that serves multiple hostnames from one endpoint. On an Amazon S3 origin or an origin with origin access control, setting host throws a TypeError (Host header override is not supported for the provided origin). An invalid host value also throws a TypeError.

If the origin has origin access control (OAC) configured, CloudFront signs the network call with SigV4 on your behalf, so you don't implement signing in your function or put credentials in your function code. Signing follows the signing behavior of the origin. With never, CloudFront doesn't sign the call. With no-override, CloudFront doesn't sign the call when your function sets an Authorization header or the origin has an Authorization custom header. For more information, see Advanced settings for origin access control.

CloudFront adds the x-amz-content-sha256 header for you. It is UNSIGNED-PAYLOAD for a call with a body and the hash of an empty string for a call without one. The exception is a POST or PUT with a body to a Lambda function URL, which doesn't accept unsigned payloads. For those calls, your function must add an x-amz-content-sha256 header with the SHA-256 digest of the body.

CloudFront copies the following headers from the viewer request. If you supply them in your function, CloudFront ignores them.

  • X-Forwarded-For

  • Via

  • CDN-Loop

In addition to the existing Disallowed headers for CloudFront Functions, CloudFront doesn't allow the following headers on network calls. Supplying any of them throws a TypeError.

  • Accept-Encoding

  • Content-Length

  • TE

  • Transfer-Encoding

Limitations

  • Distributions on the free pricing plan do not support network calls. cf.fetch() and cf.beacon() throw a TypeError, for example "cloudfront.fetch" is not available on the free pricing plan. For more information, see CloudFront flat-rate pricing plans.

  • Call cf.fetch() and cf.beacon() only inside the handler. They don't work from global scope.

  • Only one network call per invocation.

  • Network calls are not supported when you test a function with the TestFunction API or the Test tab in the CloudFront console. The call throws a TypeError.

  • CloudFront Functions doesn't support response body streaming. text() decodes the body as UTF-8 and replaces invalid bytes. bytes() and arrayBuffer() return the raw bytes.

  • AWS WAF does not inspect network calls. The web ACL associated with your distribution evaluates viewer requests, not requests your function makes.

  • CloudFront doesn't cache network call responses. Every invocation that reaches a network call makes one.

  • Connection Functions do not support network calls.

  • Distributions that use continuous deployment do not support network calls.

For quotas, including the network call timeout and the maximum request and response body sizes, see Quotas on CloudFront Functions network calls.