Cache
smoxy provides a CDN caching layer that stores copies of your content at the edge. This guide covers the caching configuration available on your zone -- caching behavior, TTL, cache key composition, cache tags, edge processing, and stale-cache behavior. For where the cache decision sits in the overall request flow, see the Request Lifecycle.
Dynamic Cache
The Dynamic cache toggle enables caching of your zone's text/html responses on smoxy's edge servers, reducing origin load and improving performance. Static assets are cached independently of this setting.
Good candidates for HTML caching: product and category pages, blog posts, landing pages, documentation -- any page whose HTML doesn't change per visitor. Not suitable: personalized pages (user dashboards, shopping carts), pages that must reflect real-time data, and dynamic API responses. For mixed pages (e.g. a product page with a personalized cart widget), SSI/ESI can cache the static parts separately from the dynamic fragments.
When HTML content changes, purge the cache so visitors see the latest version (Cache Invalidation). The configured TTL applies to HTML like any other cached content, and if HTML varies by cookie (language, login state), configure the cookie value component accordingly. Per-request control -- caching only specific paths, or none for logged-in users -- is available via Conditional Rules.
Respect Cache-Control
The Respect origin Cache-Control toggle -- enabled by default -- lets your origin control caching per response through its Cache-Control header. When on, smoxy does not cache responses marked no-cache, private, or max-age=0, so those requests continue to reach your origin.
s-maxage takes precedence. As a shared cache, smoxy honors the s-maxage directive over max-age. A response with Cache-Control: max-age=0, s-maxage=3600 is therefore cached -- max-age=0 only tells the browser not to cache, while s-maxage>0 explicitly allows proxy caches like smoxy to store it. Only when no positive s-maxage is present does max-age=0 cause a bypass. This combination is common in frameworks that separate browser and proxy caching, such as Shopware 6 or Symfony HttpCache.
| Setting | Default |
|---|---|
| Respect origin Cache-Control | Enabled |
When disabled, smoxy applies the configured TTL to all cacheable responses regardless of the origin's Cache-Control header.
Cache TTL (Time-to-Live)
The Default TTL controls how long smoxy caches your content before requesting a fresh copy from your origin. It is a dropdown of fixed presets:
5 minutes · 15 minutes · 30 minutes · 1 hour · 6 hours · 12 hours · 1 day · 2 days · 3 days · 7 days
The default is 7 days (604,800 seconds).
Cache Key
The cache key determines how smoxy identifies unique cached responses. Two requests with the same cache key return the same cached content. Understanding the cache key is essential for avoiding stale or incorrect content being served.
Components
By default, the cache key is built from the request URI and the query string. Two optional components can be added -- both off by default:
| Component | Control | Default | Description |
|---|---|---|---|
| Request URI | Always included | -- | The request path is always part of the cache key |
| Request Hostname | Toggle | Off | Include the request hostname so different hostnames cache apart |
| Cookie Value | Toggle | Off | Vary the cache based on specific cookie values |
Request Hostname
When Request Hostname is enabled, requests to different hostnames on the same zone produce separate cache entries. This matters if multiple hostnames on the same zone serve different content for the same path.
Example: With this enabled, www.example.com/about and shop.example.com/about are cached separately.
Cookie Value
When Cookie Value is enabled, smoxy includes specific cookie values in the cache key. This is useful for serving different content based on user preferences like language or region.
Configure which cookies to vary on under Cookie Name Values -- a list of cookie names.
Example: If you vary on language, a visitor with language=en and a visitor with language=de receive separately cached responses.
Excluded Query Parameters
By default, the full query string is part of the cache key. You can exclude specific query parameters that should not affect caching -- typically tracking parameters that don't change the page content.
Configure a comma-separated list of parameter names to exclude.
Common exclusions: utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid
Parameter name rules: Only alphanumeric characters and hyphens are allowed.
Cache Tags
Cache tags allow you to group cached content and purge it selectively. Your origin server sends cache tag values in HTTP response headers, and smoxy uses these to associate cached content with tags. When you purge a tag, all cached content associated with that tag is invalidated.
Configuration
You can configure up to 4 cache tag headers. Each header has a name and a separator character.
| Setting | Description |
|---|---|
| Header name | The HTTP response header that contains tag values |
| Separator | The character that separates multiple tags within the header -- one of space, ,, ;, or | |
Header name rules: Only alphanumeric characters and hyphens are allowed.
Defaults
smoxy comes preconfigured with two cache tag headers:
| Header | Separator | Example |
|---|---|---|
x-cache-tags | , (comma) | x-cache-tags: product-123,category-shoes |
xkey | (space) | xkey: product-123 category-shoes |
These defaults cover the most common cache tagging conventions. You can modify or add additional headers as needed.
Cache Tag Ignore List
You can configure a list of tag patterns to ignore. Tags matching these patterns are not stored, which can reduce cache metadata overhead for tags you never intend to purge.
Enter a comma-separated list of tag names or patterns.
Allowed characters: Alphanumeric, parentheses, braces, brackets, hyphens, underscores, periods, forward slashes, and asterisks.
SSI & ESI
smoxy supports Server Side Includes (SSI) and Edge Side Includes (ESI) for assembling pages from multiple fragments at the edge.
| Feature | Description |
|---|---|
| SSI | Process <!--#include --> directives in HTML responses |
| ESI | Process <esi:include> tags for edge-side page assembly |
INFO
Note: ESI can only be enabled when SSI is also enabled.
These features are useful for sites that compose pages from cacheable fragments with different TTLs (e.g., a static header cached for hours and a dynamic cart widget cached for seconds).
Stale Cache
The Stale cache controls let smoxy serve stale content from the CDN cache instead of failing or waiting on the origin. Two independent toggles:
| Toggle | Behavior |
|---|---|
| While offline | Serve cached content when the origin is unreachable |
| While updating | Serve cached content while a fresh copy is fetched in the background |
INFO
Note: Stale cache is CDN only.
Cache Error Responses
When enabled, error responses (HTTP 300+) from your origin are cached briefly -- about 5 seconds -- to shield it from repeated upstream failures.
INFO
Note: Cache error responses is CDN only.
Purge Token
Each zone has an automatically generated purge token that authenticates cache invalidation (purge) requests sent to smoxy's API. It is shown on the Cache page and cannot be set manually. Include it in your purge requests to authorize them.
See Cache Invalidation for how to send purge requests.
The s-cache Response Header
When the Dynamic cache or Optimization features are enabled, smoxy adds an s-cache response header to every response, telling you how the request was served. Use it to debug cache hit rate, verify rule behavior, and confirm that your origin's Cache-Control directives are honored.
HIT
The resource was found in smoxy's cache and served directly from the edge - no origin round-trip.
MISS
The resource was not in cache and was fetched from the origin. To prevent browsers from caching the miss response, smoxy sets cache-control: no-cache, no-store, must-revalidate on the response - this guarantees that the next request can be served as a HIT once smoxy has stored the content.
BYPASS
smoxy intentionally skipped the cache. This happens when:
- Respect origin Cache-Control is enabled and the origin returned
Cache-Control: no-cache,private, ormax-age=0without a positives-maxage-- ifs-maxage>0is present, the response is cached instead (see Respect Cache-Control). - The request carried an
http-bypassheader with a valid token or a base64-encoded form of your hostname. - The response Content-Type is not eligible for caching (see Supported MIME Types).
Important Considerations
- TTL trade-off: A longer TTL means less origin traffic but slower content updates. A shorter TTL means fresher content but more origin requests. Choose based on how frequently your content changes.
- Vary on cookies carefully: Only vary on cookies that actually affect the response content. Varying on session IDs or tracking cookies effectively disables caching since every visitor gets a unique cache entry.
- Exclude tracking parameters: Marketing parameters like UTM tags don't change your page content. Excluding them from the cache key significantly improves your cache hit rate.
- Cache tags require origin cooperation: Your origin server must send the configured tag headers in its responses. smoxy reads these headers and stores the association -- it does not generate tags automatically.