AWS.CloudFront reference

CachePolicy

Source: src/AWS/CloudFront/CachePolicy.ts

A CloudFront cache policy.

Cache policies determine the values CloudFront includes in the cache key, the headers, cookies and query strings it forwards to the origin, and the TTL bounds for cached responses. Policies are referenced by ID on a Distribution’s default behavior or per-path cache behaviors.

For AWS-managed policies (CachingOptimized, CachingDisabled, AllViewerExceptHostHeader) reference them by ID via the constants in ManagedPolicies instead of creating a custom policy.

CachePolicy: Creating Cache Policies

const cachePolicy = yield* CachePolicy("ApiCachePolicy", {
  comment: "Cache GETs by query string + Authorization",
  minTTL: 0,
  defaultTTL: "1 minute",
  maxTTL: "1 hour",
  parametersInCacheKeyAndForwardedToOrigin: {
    EnableAcceptEncodingGzip: true,
    EnableAcceptEncodingBrotli: true,
    HeadersConfig: {
      HeaderBehavior: "whitelist",
      Headers: { Quantity: 1, Items: ["Authorization"] },
    },
    CookiesConfig: { CookieBehavior: "none" },
    QueryStringsConfig: { QueryStringBehavior: "all" },
  },
});

CreateInvalidation

Source: src/AWS/CloudFront/CreateInvalidation.ts

Grants a Function permission to create CloudFront cache invalidations for a distribution at runtime — the classic post-publish/CMS purge pattern.

CreateInvalidation: Invalidating from a Function

const invalidate = yield* CloudFront.CreateInvalidation(distribution);

const response = yield* invalidate({
  InvalidationBatch: {
    CallerReference: crypto.randomUUID(),
    Paths: { Quantity: 1, Items: ["/blog/*"] },
  },
});
// response.Invalidation?.Id

DeleteKey

Source: src/AWS/CloudFront/DeleteKey.ts

Runtime binding for cloudfront-keyvaluestore:DeleteKey.

Deletes a single key from the bound KeyValueStore’s data plane. Writes use optimistic concurrency: pass the store’s current ETag as IfMatch (from DescribeKeyValueStore or a previous write’s response). Provide the implementation with Effect.provide(AWS.CloudFront.DeleteKeyHttp).

DeleteKey: Writing KeyValueStore Data

// init — bind the operations to the store
const describeStore = yield* CloudFront.DescribeKeyValueStore(store);
const deleteKey = yield* CloudFront.DeleteKey(store);

// runtime
const meta = yield* describeStore({});
yield* deleteKey({ Key: "routes:/about", IfMatch: meta.ETag });

DescribeKeyValueStore

Source: src/AWS/CloudFront/DescribeKeyValueStore.ts

Runtime binding for cloudfront-keyvaluestore:DescribeKeyValueStore.

Reads the bound KeyValueStore’s data-plane metadata — item count, total size, and the current ETag that write operations (PutKey, DeleteKey, UpdateKeys) require as IfMatch. Provide the implementation with Effect.provide(AWS.CloudFront.DescribeKeyValueStoreHttp).

DescribeKeyValueStore: Reading KeyValueStore Data

// init — bind the operation to the store
const describeStore = yield* CloudFront.DescribeKeyValueStore(store);

// runtime
const meta = yield* describeStore({});
console.log(meta.ETag, meta.ItemCount);

Distribution

Source: src/AWS/CloudFront/Distribution.ts

A CloudFront distribution.

Distribution manages the CDN layer for static sites and HTTP origins such as Lambda Function URLs and ALBs. It exposes the distribution domain and hosted zone ID needed for Route 53 alias records.

Distribution: Creating Distributions

CDN in Front of an HTTP Origin

import * as AWS from "alchemy/AWS";

const distribution = yield* AWS.CloudFront.Distribution("ApiCdn", {
  origins: [
    {
      id: "api",
      domainName: "abc123.lambda-url.us-west-2.on.aws",
      customOriginConfig: { originProtocolPolicy: "https-only" },
    },
  ],
  defaultCacheBehavior: {
    targetOriginId: "api",
    viewerProtocolPolicy: "redirect-to-https",
    cachePolicyId: AWS.CloudFront.MANAGED_CACHING_DISABLED_POLICY_ID,
    originRequestPolicyId:
      AWS.CloudFront.MANAGED_ALL_VIEWER_EXCEPT_HOST_HEADER_POLICY_ID,
  },
});

Private S3 Origin

const distribution = yield* Distribution("WebsiteCdn", {
  aliases: ["www.example.com"],
  origins: [
    {
      id: "site",
      domainName: bucket.bucketRegionalDomainName,
      s3Origin: true,
      originAccessControlId: oac.originAccessControlId,
    },
  ],
  defaultCacheBehavior: {
    targetOriginId: "site",
    viewerProtocolPolicy: "redirect-to-https",
    compress: true,
  },
  viewerCertificate: {
    acmCertificateArn: certificate.certificateArn,
    sslSupportMethod: "sni-only",
    minimumProtocolVersion: "TLSv1.2_2021",
  },
});

Distribution: Invalidating the Cache

// declaratively, whenever `version` changes:
yield* AWS.CloudFront.Invalidation("PurgeBlog", {
  distributionId: distribution.distributionId,
  paths: ["/blog/*"],
  version: buildId,
});

To purge at runtime from a Lambda Function, bind CloudFront.CreateInvalidation(distribution) instead.

Function

Source: src/AWS/CloudFront/Function.ts

A CloudFront Function for viewer request and response customization.

CloudFront Functions are lightweight JavaScript handlers that run at the edge and can be attached to distribution cache behaviors.

Function: Creating Functions

const fn = yield* Function("RouterRequestFunction", {
  code: `
async function handler(event) {
  event.request.headers["x-forwarded-host"] = {
    value: event.request.headers.host.value,
  };
  return event.request;
}
`,
});

GetInvalidation

Source: src/AWS/CloudFront/GetInvalidation.ts

Runtime binding for cloudfront:GetInvalidation.

Reads the status of a cache invalidation on the bound distribution — pairs with CreateInvalidation to poll a purge to Completed. Provide the implementation with Effect.provide(AWS.CloudFront.GetInvalidationHttp).

GetInvalidation: Inspecting Invalidations

// init — bind the operation to the distribution
const getInvalidation = yield* CloudFront.GetInvalidation(distribution);

// runtime
const res = yield* getInvalidation({ Id: invalidationId });
console.log(res.Invalidation?.Status); // "InProgress" | "Completed"

GetKey

Source: src/AWS/CloudFront/GetKey.ts

Runtime binding for cloudfront-keyvaluestore:GetKey.

Reads a single key’s value from the bound KeyValueStore’s data plane. Values are sensitive — distilled decodes them as Redacted<string>; unwrap with Redacted.value. Provide the implementation with Effect.provide(AWS.CloudFront.GetKeyHttp).

GetKey: Reading KeyValueStore Data

// init — bind the operation to the store
const getKey = yield* CloudFront.GetKey(store);

// runtime
const res = yield* getKey({ Key: "routes:/about" });
const value = typeof res.Value === "string" ? res.Value : Redacted.value(res.Value);

Invalidation

Source: src/AWS/CloudFront/Invalidation.ts

A CloudFront cache invalidation request.

Invalidation is a helper resource for website deployments that need to clear selected CloudFront cache paths after asset updates.

Invalidation: Creating Invalidations

const invalidation = yield* Invalidation("WebsiteInvalidation", {
  distributionId: distribution.distributionId,
  version: files.version,
});

KeyGroup

Source: src/AWS/CloudFront/KeyGroup.ts

A CloudFront key group.

Key groups bundle one or more PublicKey resources for use as TrustedKeyGroups on a Distribution’s cache behavior. CloudFront uses the keys in the group to verify the signatures on signed URLs and signed cookies for that behavior.

KeyGroup: Creating Key Groups

const primary = yield* PublicKey("PrimarySigningKey", {
  encodedKey: yield* fs.readFileString("./primary.pem"),
});
const secondary = yield* PublicKey("SecondarySigningKey", {
  encodedKey: yield* fs.readFileString("./secondary.pem"),
});

const keyGroup = yield* KeyGroup("SignedUrlKeys", {
  comment: "Trusted signers for /private",
  items: [primary.publicKeyId, secondary.publicKeyId],
});

KeyValueStore

Source: src/AWS/CloudFront/KeyValueStore.ts

A CloudFront KeyValueStore for edge metadata.

KeyValueStores can be associated with CloudFront Functions and are useful for routing metadata or other small edge-time lookup tables.

KeyValueStore: Creating KeyValueStores

const store = yield* KeyValueStore("RouterStore", {
  comment: "Route metadata",
});

KvEntries

Source: src/AWS/CloudFront/KvEntries.ts

Manages namespaced key-value entries in a CloudFront KeyValueStore.

Entries are stored with a {namespace}:{key} prefix to allow multiple logical groups within a single store. Updates use batched optimistic concurrency with automatic ETag retry.

KvEntries: Managing Entries

Basic Entries

const entries = yield* KvEntries("Routes", {
  store: store.keyValueStoreArn,
  namespace: "routes",
  entries: {
    "/": "/index.html",
    "/about": "/about.html",
  },
});

Purge Stale Keys

const entries = yield* KvEntries("Routes", {
  store: store.keyValueStoreArn,
  namespace: "routes",
  entries: { "/": "/index.html" },
  purge: true,
});

KvRoutesUpdate

Source: src/AWS/CloudFront/KvRoutesUpdate.ts

Manages a single route entry in a JSON array stored in a CloudFront KeyValueStore.

The routes array is stored at key {namespace}:{key} and supports automatic chunking when the serialized array exceeds 1000 characters.

KvRoutesUpdate: Managing Routes

const update = yield* KvRoutesUpdate("MyRoute", {
  store: store.keyValueStoreArn,
  namespace: "app",
  key: "routes",
  entry: "site,mysite,*,/",
});

ListInvalidations

Source: src/AWS/CloudFront/ListInvalidations.ts

Runtime binding for cloudfront:ListInvalidations.

Lists the cache invalidations of the bound distribution (paginated via Marker/MaxItems). Provide the implementation with Effect.provide(AWS.CloudFront.ListInvalidationsHttp).

ListInvalidations: Inspecting Invalidations

// init — bind the operation to the distribution
const listInvalidations = yield* CloudFront.ListInvalidations(distribution);

// runtime
const res = yield* listInvalidations({ MaxItems: 10 });
console.log(res.InvalidationList?.Items?.map((i) => i.Id));

ListKeys

Source: src/AWS/CloudFront/ListKeys.ts

Runtime binding for cloudfront-keyvaluestore:ListKeys.

Lists key/value pairs in the bound KeyValueStore’s data plane (paginated via NextToken/MaxResults). Provide the implementation with Effect.provide(AWS.CloudFront.ListKeysHttp).

ListKeys: Reading KeyValueStore Data

// init — bind the operation to the store
const listKeys = yield* CloudFront.ListKeys(store);

// runtime
const res = yield* listKeys({ MaxResults: 50 });
console.log(res.Items?.map((item) => item.Key));

OriginAccessControl

Source: src/AWS/CloudFront/OriginAccessControl.ts

A CloudFront Origin Access Control for private origins.

OriginAccessControl is the recommended CloudFront access model for private S3 origins and newer signed-origin integrations.

OriginAccessControl: Creating Origin Access Controls

const oac = yield* OriginAccessControl("SiteOriginAccess", {
  originType: "s3",
});

OriginRequestPolicy

Source: src/AWS/CloudFront/OriginRequestPolicy.ts

A CloudFront origin request policy.

Origin request policies control which values from the viewer request (in addition to those used in the cache key) CloudFront includes when sending a request to the origin. They are referenced by ID on a Distribution’s default behavior or per-path cache behaviors.

OriginRequestPolicy: Creating Origin Request Policies

const originRequestPolicy = yield* OriginRequestPolicy("AppOriginRequest", {
  comment: "Forward auth + locale",
  headersConfig: {
    HeaderBehavior: "whitelist",
    Headers: { Quantity: 2, Items: ["Authorization", "Accept-Language"] },
  },
  cookiesConfig: { CookieBehavior: "all" },
  queryStringsConfig: { QueryStringBehavior: "all" },
});

PublicKey

Source: src/AWS/CloudFront/PublicKey.ts

A CloudFront public key.

Public keys are uploaded ahead of being grouped into a KeyGroup and used by Distributions for signed URL or signed cookie verification.

The key body is immutable after creation — changing encodedKey triggers a replacement (CloudFront returns no API to rotate a key in place).

PublicKey: Creating Public Keys

const key = yield* PublicKey("SignedUrlKey", {
  encodedKey: Redacted.make(yield* fs.readFileString("./public_key.pem")),
  comment: "RSA-2048 signed URL key for /private",
});

PutKey

Source: src/AWS/CloudFront/PutKey.ts

Runtime binding for cloudfront-keyvaluestore:PutKey.

Creates or replaces a single key in the bound KeyValueStore’s data plane. Writes use optimistic concurrency: pass the store’s current ETag as IfMatch (from DescribeKeyValueStore or a previous write’s response). Provide the implementation with Effect.provide(AWS.CloudFront.PutKeyHttp).

PutKey: Writing KeyValueStore Data

// init — bind the operations to the store
const describeStore = yield* CloudFront.DescribeKeyValueStore(store);
const putKey = yield* CloudFront.PutKey(store);

// runtime
const meta = yield* describeStore({});
const res = yield* putKey({
  Key: "routes:/about",
  Value: "/about.html",
  IfMatch: meta.ETag,
});
// res.ETag is the store's new entity tag

RealtimeLogConfig

Source: src/AWS/CloudFront/RealtimeLogConfig.ts

A CloudFront real-time log configuration.

Real-time logs deliver per-request records to a Kinesis data stream within seconds. Attach the configuration to a distribution’s cache behavior via Distribution (realtimeLogConfigArn).

RealtimeLogConfig: Creating Real-Time Log Configs

const stream = yield* Kinesis.Stream("EdgeLogs", {});

const role = yield* IAM.Role("EdgeLogsRole", {
  assumeRolePolicyDocument: {
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { Service: "cloudfront.amazonaws.com" },
        Action: "sts:AssumeRole",
      },
    ],
  },
  inlinePolicies: {
    kinesis: {
      Version: "2012-10-17",
      Statement: [
        {
          Effect: "Allow",
          Action: [
            "kinesis:DescribeStreamSummary",
            "kinesis:DescribeStream",
            "kinesis:PutRecord",
            "kinesis:PutRecords",
          ],
          Resource: stream.streamArn,
        },
      ],
    },
  },
});

const logConfig = yield* RealtimeLogConfig("EdgeLogConfig", {
  samplingRate: 100,
  fields: ["timestamp", "c-ip", "cs-uri-stem", "sc-status"],
  endpoints: [{ streamArn: stream.streamArn, roleArn: role.roleArn }],
});

ResponseHeadersPolicy

Source: src/AWS/CloudFront/ResponseHeadersPolicy.ts

A CloudFront response headers policy.

Response headers policies add or remove headers in viewer responses, including CORS, standard security headers (HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, etc.), Server-Timing, custom headers and explicit header removal. They are referenced by ID on a Distribution’s default behavior or per-path cache behaviors.

ResponseHeadersPolicy: Creating Response Headers Policies

const responseHeadersPolicy = yield* ResponseHeadersPolicy("AppResponseHeaders", {
  comment: "Default app security + CORS",
  corsConfig: {
    AccessControlAllowOrigins: { Quantity: 1, Items: ["https://app.example.com"] },
    AccessControlAllowMethods: { Quantity: 2, Items: ["GET", "OPTIONS"] },
    AccessControlAllowHeaders: { Quantity: 1, Items: ["Authorization"] },
    AccessControlAllowCredentials: false,
    OriginOverride: true,
  },
  securityHeadersConfig: {
    StrictTransportSecurity: {
      AccessControlMaxAgeSec: 31536000,
      IncludeSubdomains: true,
      Preload: true,
      Override: true,
    },
    ContentTypeOptions: { Override: true },
    FrameOptions: { FrameOption: "DENY", Override: true },
    ReferrerPolicy: { ReferrerPolicy: "no-referrer", Override: true },
  },
});

UpdateKeys

Source: src/AWS/CloudFront/UpdateKeys.ts

Runtime binding for cloudfront-keyvaluestore:UpdateKeys.

Puts and/or deletes multiple keys in the bound KeyValueStore’s data plane as a single all-or-nothing batch. Writes use optimistic concurrency: pass the store’s current ETag as IfMatch (from DescribeKeyValueStore or a previous write’s response). Provide the implementation with Effect.provide(AWS.CloudFront.UpdateKeysHttp).

UpdateKeys: Writing KeyValueStore Data

// init — bind the operations to the store
const describeStore = yield* CloudFront.DescribeKeyValueStore(store);
const updateKeys = yield* CloudFront.UpdateKeys(store);

// runtime
const meta = yield* describeStore({});
yield* updateKeys({
  IfMatch: meta.ETag,
  Puts: [{ Key: "routes:/", Value: "/index.html" }],
  Deletes: [{ Key: "routes:/legacy" }],
});

VpcOrigin

Source: src/AWS/CloudFront/VpcOrigin.ts

A CloudFront VPC origin.

VpcOrigin lets a CloudFront distribution route to a private Application Load Balancer, Network Load Balancer, or EC2 instance inside a VPC without exposing it to the public internet. Reference the resulting vpcOriginId from a distribution origin’s vpcOriginConfig.

VpcOrigin: Creating VPC Origins

Private ALB Origin

const vpcOrigin = yield* VpcOrigin("AppOrigin", {
  arn: loadBalancer.arn,
  httpPort: 80,
  httpsPort: 443,
  originProtocolPolicy: "https-only",
});

Attaching a VPC Origin to a Distribution

const distribution = yield* Distribution("AppCdn", {
  origins: [
    {
      id: "app",
      domainName: loadBalancer.dnsName,
      vpcOriginConfig: { vpcOriginId: vpcOrigin.vpcOriginId },
    },
  ],
  defaultCacheBehavior: {
    targetOriginId: "app",
    viewerProtocolPolicy: "redirect-to-https",
  },
});