CDN Cache

Wasmer Edge can cache HTTP responses at the edge and reuse them for matching requests before they reach your app. This speeds up delivery of static assets, generated files, public API responses, and any other content that is safe to share across visitors.

How it works

When CDN Cache is enabled, Edge checks each incoming request before forwarding it to your app:

1. If a fresh cached response exists, Edge returns it directly.
2. Otherwise, Edge forwards the request to your app.
3. If the app’s response is cacheable, Edge stores it for future matching requests.

Your app stays in control: it decides what can be cached by returning standard headers such as Cache-Control, Expires, ETag, Last-Modified, and Vary.

The cache is scoped to the app version that served the response. Each deploy starts a new cache namespace, so a new version never reuses the previous version’s cached responses.

Enable CDN Cache

Add capabilities.cdn_cache.enabled: true to your app.yaml and deploy:

kind: wasmer.io/App.v0
owner: my-account
name: my-app
package: my-account/my-app
 
capabilities:
  cdn_cache:
    enabled: true

When enabled is omitted or set to false, CDN Cache is off.

You can also toggle it from the dashboard: open your app, go to App Settings, and open the CDN Cache section.

Purge cached responses

Because cache entries are scoped to an app version, deploying a new version with wasmer deploy automatically stops reuse of the old version’s cache.

To purge the current version’s cache explicitly, use either:

• The purge button in the dashboard, under App Settings > CDN Cache.

• The CLI:

  wasmer app cdn purge

  Run it from a directory containing the app’s app.yaml, or pass an app identifier as accepted by the other wasmer app commands.

What gets cached

Only GET and HEAD requests are eligible. All other methods bypass the cache and go straight to your app.

A request also bypasses the cache when it carries any of these headers or directives, so authenticated and personalized requests are never stored in the shared cache:

• Authorization
• Cookie
• Pragma: no-cache
• Cache-Control: no-store
• Cache-Control: no-cache
• Cache-Control: max-age=0

On the response side, caching is opt-in: a response must carry explicit caching headers (Cache-Control or Expires) to be stored. A response is not stored when it:

• includes Set-Cookie
• includes Vary: *
• has a 5xx status code
• omits Content-Length (including unknown-length streamed responses)
• exceeds the platform’s maximum CDN object size

Cache-Control

Cache-Control tells Edge whether a response can be stored and how long it stays fresh:

Cache-Control: public, max-age=3600

The response above can be cached for one hour. Common directives:

• public — allow storage in the shared CDN cache.
• private — forbid storage in the shared CDN cache.
• no-store — forbid storing the response at all.
• no-cache — allow storage, but require revalidation before each reuse.
• max-age=<seconds> — how long the response stays fresh.
• s-maxage=<seconds> — freshness for shared caches; takes precedence over max-age.
• must-revalidate / proxy-revalidate — require revalidation and forbid serving stale responses.

When Cache-Control is absent, Expires can still make a response cacheable. When both are present, Cache-Control wins.

Revalidation

Edge supports standard HTTP revalidation for stale responses. If the cached response includes ETag, Edge revalidates with If-None-Match; if it includes Last-Modified, Edge revalidates with If-Modified-Since. When your app returns 304 Not Modified, Edge keeps the cached body and refreshes its metadata from the response.

Cache-Control: public, max-age=60
ETag: "asset-v1"

After 60 seconds, Edge can ask your app whether the cached response is still valid instead of downloading the full body again.

Vary

Vary is honored when matching cached responses. A response with Vary: Accept-Language, for example, is cached separately per Accept-Language value:

Cache-Control: public, max-age=3600
Vary: Accept-Encoding

Vary: * prevents caching. When a response uses a non-identity Content-Encoding, Edge also keys the cache by Accept-Encoding, even if the origin forgot to send Vary: Accept-Encoding.

Stale responses

To smooth traffic spikes and stay available during brief upstream errors, Edge can serve stale responses for a short window during revalidation or upstream errors. Control this with standard directives:

Cache-Control: public, max-age=300, stale-while-revalidate=30, stale-if-error=600

Edge will not serve stale responses when the request includes Cache-Control: no-cache, or when the cached response requires revalidation via no-cache, must-revalidate, or proxy-revalidate.

Limitations

• CDN Cache is in beta.
• capabilities.cdn_cache.enabled is the only app-level setting. Path-based caching rules are not available yet — enablement applies to the whole app, and each response controls caching through HTTP headers.
• Dashboard and CLI purges clear the app’s CDN cache as a whole.