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.
Distributions on the free pricing plan don't support network calls. For more information, see CloudFront flat-rate pricing plans.
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.
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.
Topics
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)
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 inoptions.originIdand 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, orOPTIONS. If this is not provided,GETis used.The value must be upper case. Unlike standard
fetch(), the method is not normalized, so a value such as'post'throws aTypeError. 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 anArrayBufferViewsuch as aUint8Array. To send JSON, useJSON.stringify().A body is not allowed with
GETorHEAD, including whenmethodis not provided and the defaultGETis used. A call with a body and one of these methods throws aTypeError(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,
falseis used. Set it totruewhen you need the body.Without
includeBody: true, every body accessor reads empty:text()resolves to"",json()resolves tonull, andbytes()andarrayBuffer()resolve to empty values. Nothing is consumed, sobodyUsedstaysfalse.
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-
trueifstatusis 200 to 299, otherwisefalse. headers-
A read-only property that holds the response headers as a Headers
object. It supports the get(),has(),getSetCookie(),forEach(),keys(),values(), andentries()methods, and you can iterate over it.Header names are case insensitive in
get()andhas().get()returnsnullwhen the header is not present.getSetCookie()returns an array of everySet-Cookievalue.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
SyntaxErrorif the body is not valid JSON. bytes()-
A promise that resolves to the raw body bytes as a
Uint8Array. Buffer methods such astoString('base64')work on the result. arrayBuffer()-
A promise that resolves to the raw body bytes as an
ArrayBuffer. bodyUsed-
trueonce the body has been read.
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, withOriginDnsError. 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.
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.
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.
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 inoptions.originIdand 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, orOPTIONS. Must be upper case. If this is not provided,GETis 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 anArrayBufferViewsuch as aUint8Array. To send JSON, useJSON.stringify(). A body is not allowed withGETorHEAD, including the defaultGET, and throws aTypeError. logDeliveryErrors(optional)-
Whether delivery failures are written to CloudWatch Logs. If this is not provided,
falseis used. Set it totrueto see beacons that fail after your function has returned. The errors go to the same log group asconsole.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
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-ForViaCDN-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-EncodingContent-LengthTETransfer-Encoding
Limitations
-
Distributions on the free pricing plan do not support network calls.
cf.fetch()andcf.beacon()throw aTypeError, for example"cloudfront.fetch" is not available on the free pricing plan. For more information, see CloudFront flat-rate pricing plans. -
Call
cf.fetch()andcf.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
TestFunctionAPI or the Test tab in the CloudFront console. The call throws aTypeError. -
CloudFront Functions doesn't support response body streaming.
text()decodes the body as UTF-8 and replaces invalid bytes.bytes()andarrayBuffer()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.