Upsun User Documentation
Edit page

HTTP cache

Back to home

On this page

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
¹Terms and conditions apply
Activate your 15-day trial

Upsun supports HTTP caching at the server level. Caching is enabled by default, but is only applied to GET and HEAD requests.

The cache can be controlled using the cache key in your .upsun/config.yaml file.

If a request can be cached, Upsun builds a cache key from several request properties and stores the response associated with this key. When a request comes with the same cache key, the cached response is reused.

When caching is on…

  • you can configure cache behavior for different location blocks in your .upsun/config.yaml;
  • the router respects whatever cache headers are sent by the application;
  • cookies bypass the cache;
  • responses with the Cache-Control header set to Private, No-Cache, or No-Store aren’t cached.

You should not use the Upsun HTTP cache if you’re using Varnish or an external CDN such as Fastly or Cloudflare. Mixing cache services together most likely results in caches that are stale and can’t be cleared. For more details, see best practices on HTTP caching.

Basic usage Anchor to this heading

The HTTP cache is enabled by default, however you may wish to override this behavior.

To configure the HTTP cache, add a cache key to your route. You may like to start with the defaults:

.upsun/config.yaml
routes:
    https://{default}/:
        type: upstream
        upstream: app:http
        cache:
            enabled: true
            default_ttl: 0
            cookies: ['*']
            headers: ['Accept', 'Accept-Language']

Example Anchor to this heading

In this example, requests are cached based on the URI, the Accept header, Accept-Language header, and X-Language-Locale header. Any response that lacks a Cache-Control header is cached for 60 seconds. The presence of any cookie in the request disables caching of that response.

.upsun/config.yaml
routes:
    https://{default}/:
        type: upstream
        upstream: app:http
        cache:
            enabled: true
            headers: ['Accept', 'Accept-Language', 'X-Language-Locale']
            cookies: ['*']
            default_ttl: 60

How it works Anchor to this heading

The cache key Anchor to this heading

If a request can be cached, Upsun builds a cache key from several request properties and stores the response associated with this key. When a request comes with the same cache key, the cached response is reused.

There are two parameters that let you control this key: headers and cookies.

The default value for these keys are the following:

.upsun/config.yaml
routes:
    https://{default}/:
        # ...
            cache:
                enabled: true
                cookies: ['*']
                headers: ['Accept', 'Accept-Language']

Duration Anchor to this heading

The cache duration is decided based on the Cache-Control response header value. If no Cache-Control header is in the response, then the value of default_ttl key is used.

Conditional requests Anchor to this heading

Conditional requests using If-Modified-Since and If-None-Match are both supported. The web server doesn’t honor the Pragma request header.

Cache revalidation Anchor to this heading

When the cache is expired (indicated by Last-Modified header in the response) the web server sends a request to your application with If-Modified-Since header.

If the If-None-Match header is sent in the conditional request when Etag header is set in the cached response, your application can extend the validity of the cache by replying HTTP 304 Not Modified.

Flushing Anchor to this heading

The HTTP cache doesn’t support a complete cache flush, but you can invalidate the cache by setting cache: false. Alternatively, the cache clears on a rebuild, so triggering a rebuild (pushing a new commit) effectively causes a complete cache flush.

Cache configuration properties Anchor to this heading

enabled Anchor to this heading

Turns the cache on or off for a route.

headers Anchor to this heading

Adds specific header fields to the cache key, enabling caching of separate responses for those headers.

For example, if the headers key is the following, Upsun caches a different response for each value of the Accept HTTP request header only:

.upsun/config.yaml
routes:
    https://{default}/:
        # ...
            cache:
                enabled: true
                headers: ["Accept"]

Header behaviors Anchor to this heading

The cache is only applied to GET and HEAD requests. Some headers trigger specific behaviors in the cache.

Header field Cache behavior
Cache-Control Responses with the Cache-Control header set to Private, No-Cache, or No-Store aren’t cached. All other values override default_ttl.
Vary A list of header fields to be taken into account when constructing the cache key. Multiple header fields can be listed, separated by commas. The Cache key is the union of the values of the Header fields listed in Vary header, and whatever is listed in the .upsun/config.yaml file.
Set-Cookie Not cached
Accept-Encoding, Connection, Proxy-Authorization, TE, Upgrade Not allowed, and throws an error
Cookie Not allowed, and throws an error. Use the cookies value, instead.
Pragma Ignored

A full list of HTTP headers is available on Wikipedia.

cookies Anchor to this heading

The cookies key allows you to define a list of cookies you want to include in the cache key, if any.

Possible values Description Default
['*'] Any request with a cookie bypasses the cache.

Note that this is achieved by Upsun adding the X-Platform-Cache: BYPASS HTTP header in the router, and that the same behaviour applies if the Set-Cookie header is present.		 Yes
[] Ignore all cookies. No
['cookie_1','cookie_2'] A list of allowed cookies to include in the cache key. All other cookies are ignored. No

Example with a single value Anchor to this heading

With the following configuration, the cache key depends on the value of the foo cookie in the request. Other cookies are ignored.

.upsun/config.yaml
routes:
    https://{default}/:
        # ...
            cache:
                enabled: true
                cookies: ["foo"]

Example with a regular expression Anchor to this heading

A cookie value can also be a regular expression. An entry that begins and ends with a / is interpreted as a PCRE regular expression to match the cookie name. For example:

.upsun/config.yaml
routes:
     https://{default}/:
         # ...
             cache:
                 enabled: true
                 cookies: ['/^SS?ESS/']

This configuration causes all cookies beginning with SESS or SSESS to be part of the cache key, as a single value. Other cookies are ignored for caching.

If your site uses a session cookie as well as third-party cookies, say from an analytics service, this is the recommended approach.

default_ttl Anchor to this heading

Defines the default time-to-live for the cache, in seconds, for non-static responses, when the response doesn’t specify one.

The cache duration is decided based on the Cache-Control response header value. If no Cache-Control header is in the response, then the value of default_ttl is used. If the application code returns a Cache-Control header or if your .upsun/config.yaml file is configured to set a cache lifetime, then this value is ignored in favor of the application headers.

The default_ttl only applies to non-static responses, that is, those generated by your application.

To set a cache lifetime for static resources configure that in your app configuration. All static assets have a Cache-Control header with a max age defaulting to 0 (which is the default for expires).

Debugging Anchor to this heading

Upsun adds an X-Platform-Cache header to each request which show whether your request is a cache HIT, MISS or BYPASS. This can be useful when trying to determine whether it’s your application, the HTTP cache, or another proxy or CDN which isn’t behaving as expected.

If in doubt, disable the cache using cache: false.

Advanced caching strategies Anchor to this heading

Cache per route Anchor to this heading

If you need fine-grained caching, you can set up caching rules for several routes separately:

.upsun/config.yaml
routes:
    https://{default}/:
        type: upstream
        upstream: app:http
        cache:
            enabled: true

    https://{default}/foo/:
        type: upstream
        upstream: app:http
        cache:
            enabled: false

  https://{default}/foo/bar/:
      type: upstream
      upstream: app:http
      cache:
          enabled: true

With this configuration, the following routes are cached:

  • https://{default}/
  • https://{default}/foo/bar/
  • https://{default}/foo/bar/baz/

And the following routes are not cached:

  • https://{default}/foo/
  • https://{default}/foo/baz/

Allowing only specific cookies Anchor to this heading

Some applications use cookies to invalidate cache responses, but expect other cookies to be ignored. This is a case of allowing only a subset of cookies to invalidate the cache.

.upsun/config.yaml
routes:
    https://{default}/:
    # ...
        cache:
            enabled: true
            cookies: ["MYCOOKIE"]

Cache HTTP and HTTPS separately using the Vary header Anchor to this heading

Set the Vary header to X-Forwarded-Proto custom request header to render content based on the request protocol (i.e. HTTP or HTTPS). By adding Vary: X-Forwarded-Proto to the response header, HTTP and HTTPS content would be cached separately.

Cache zipped content separately Anchor to this heading

Use Vary: Accept-Encoding to serve different content depending on the encoding. Useful for ensuring that gzipped content isn’t served to clients that can’t read it.

Is this page helpful?