A Content Delivery Network (CDN) is a geographically distributed network of servers that work together to provide fast delivery of internet content. By caching content in locations closer to your users, a CDN can significantly reduce latency and decrease the load on your application's origin servers. It can also improve security by providing a layer of defense against DDoS attacks.

Under the hood, Stacktape uses Amazon CloudFront, which has over 300 points of presence (PoPs) worldwide.

How a CDN works

A CDN acts as a layer between your application (the origin) and your clients.

• Instead of sending requests directly to your application, clients send them to the CDN.
• The CDN routes the request to the nearest PoP.
• The PoP retrieves the response from your application (the origin).
• The PoP sends the response to the client and caches it for future requests.
• Subsequent requests for the same content can be served directly from the cache (a cache hit), which is much faster.

You can control which responses are cached and for how long. See the section on cache control for more information.

Basic usage

In Stacktape, you configure a CDN on a resource, which then becomes the default origin for the CDN. You can use a CDN with a bucket, HTTP API Gateway, or Application Load Balancer.

resources:
  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true

You can also configure route rewrites to forward requests for specific paths to different origins. This allows you to create hybrid infrastructures where, for example, static content is served from a bucket and dynamic content is served from an API.

CDN with a bucket

You can enable a CDN for a bucket with just two lines of configuration. By default, content from the bucket is cached for six months. This is a common pattern for serving static websites.

resources:
  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true

CDN with an HTTP API Gateway

You can also enable a CDN for an HTTP API Gateway. By default, the CDN does not cache any content from an API gateway, as it's assumed to be dynamic. You can control the caching behavior by setting the Cache-Control header in your API's responses.

resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true

CDN with an Application Load Balancer

Similarly, you can enable a CDN for an Application Load Balancer. As with an API gateway, content is not cached by default.

resources:
  myLoadBalancer:
    type: application-load-balancer
    properties:
      cdn:
        enabled: true

Custom domain names

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        customDomains:
          - domainName: mydomain.com

Edge Lambda functions

You can run Lambda functions at the edge to customize the content that the CDN delivers. For more information, see the Edge Lambda Functions page.

resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts

  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true
        edgeFunctions:
          onRequest: authFunction

Cache control

You can control the caching behavior of the CDN in two ways:

1. Using the Cache-Control header (recommended): This gives you fine-grained control over the caching behavior for each response from your origin.
2. Using CDN caching options: This allows you to set basic caching rules but is less flexible.

Cache-Control header with buckets

You can set the Cache-Control header for objects in a bucket using metadata. When you use the directory upload feature, Stacktape can automatically set the correct headers for you using presets.

resources:
  myBucket:
    type: bucket
    properties:
      directoryUpload:
        directoryPath: my-web/build
        headersPreset: static-website
      cdn:
        enabled: true

Cache-Control header with an HTTP API Gateway or Application Load Balancer

When using a CDN with an API gateway or an ALB, you can set the Cache-Control header in the responses from your application.

resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true

  myFunction:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: hello.ts
      events:
        - type: http-api-gateway
          properties:
            httpApiGatewayName: myApiGateway
            method: GET
            path: /hello

export default async (event, context) => {
  return {
    statusCode: 200,
    statusDescription: '200 OK',
    isBase64Encoded: false,
    headers: {
      'Content-Type': 'text/plain',
      'Cache-Control': 'max-age=30'
    },
    body: 'Hello !!!'
  };
};

For more information on the Cache-Control header, see the MDN docs.

CDN caching options

You can specify default caching behavior for your CDN. Different caching options can be set for each route rewrite.

If you don't specify any caching options, Stacktape uses the following defaults:

Origin type	minTTL	maxTTL	defaultTTL
Bucket	0	31536000	15768000
HTTP API Gateway	0	31536000	0
Application Load Balancer	0	31536000	0

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        cachingOptions:
          defaultTTL: 60
        routeRewrites:
          - path: /static/*
            cachingOptions:
              defaultTTL: 604800

Controlling the cache key

The cache key is a unique identifier for each object in the cache. It determines whether a request results in a cache hit. By default, the cache key is based on the URL path, but you can configure it to include headers, cookies, or query parameters.

If you don't specify a cache key, Stacktape uses the following defaults:

Origin type	Parts of request included in cache key
Bucket	URL path
HTTP API Gateway	URL path, all query params, and the Authorization header
Application Load Balancer	URL path, all query params, and the Authorization header

For example, if your origin uses the Accept-Language header to return different content based on the client's language, you should include that header in the cache key.

resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        cachingOptions:
          cacheKeyParameters:
            headers:
              whitelist:
                - Accept-Language

CDN forwarding options

Forwarding options specify which parts of a request are forwarded to the origin. You can also filter which request methods are forwarded.

If you don't specify any forwarding options, Stacktape uses the following defaults:

Origin type	Parts of request forwarded to origin
Bucket	URL path
HTTP API Gateway	URL path, all query params, all headers, and all cookies
Application Load Balancer	URL path, all query params, all headers, and all cookies

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        forwardingOptions:
          allowedMethods:
            - 'GET'
            - 'POST'

Route rewrites

Route rewrites allow you to route incoming requests to different origins based on the URL path.

Routing to a bucket

In this example, requests with a URL path starting with /static are routed to a bucket, while all other requests are routed to an HTTP API Gateway.

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /static/*
            routeTo:
              type: bucket
              properties:
                bucketName: myBucket
                disableUrlNormalization: true

  myBucket:
    type: 'bucket'

Routing to an Application Load Balancer

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'application-load-balancer'
              properties:
                loadBalancerName: myLoadBalancer

  myLoadBalancer:
    type: 'application-load-balancer'

Routing to an HTTP API Gateway

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'http-api-gateway'
              properties:
                httpApiGatewayName: appApiGateway

  appApiGateway:
    type: 'http-api-gateway'

Routing to a custom origin

resources:
  myLoadBalancer:
    type: 'application-load-balancer'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /external/*
            routeTo:
              type: custom-origin
              properties:
                domainName: my-custom-origin.example.com

Automatic invalidation

You can disable the automatic cache invalidation that occurs after each deployment by setting invalidateAfterDeploy to false.

resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        invalidateAfterDeploy: false

Price class

You can set a price class to reduce the cost of your CDN by limiting the number of edge locations from which it serves traffic.

resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        cloudfrontPriceClass: PriceClass_200

Firewall

You can protect your CDN with a web application firewall.

To learn more, see the Web Application Firewall documentation.

resources:
  myFirewall:
    type: web-app-firewall
    properties:
      scope: cdn
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        useFirewall: myFirewall

API reference