Advanced Caching
smoxy provides a CDN caching layer that stores copies of your content at the edge. This guide covers all caching configuration options available on your site, including TTL, cache key composition, cache tags, and stale cache behavior.
Cache TTL (Time-to-Live)
The cache TTL controls how long smoxy caches your content before requesting a fresh copy from your origin server.
| Setting | Value |
|---|---|
| Minimum | 300 seconds (5 minutes) |
| Maximum | 604,800 seconds (7 days) |
| Default | 604,800 seconds (7 days) |
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
| Component | Setting | Default | Description |
|---|---|---|---|
| URI | Always included | -- | The request path is always part of the cache key |
| Host | host_vary_enabled | Derived from config | Include the request hostname in the cache key |
| Cookie | cookie_vary_enabled | Enabled | Vary the cache based on specific cookie values |
Host Vary
When host vary is enabled, requests to different hostnames on the same site produce separate cache entries. This is important if multiple hostnames on the same site serve different content for the same path.
Example: With host vary enabled, www.example.com/about and shop.example.com/about are cached separately.
Cookie Vary
When cookie vary 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 by specifying cookie parameter names -- a comma-separated list of cookie names.
Example: If you set cookie vary params to language, a visitor with language=en and a visitor with language=de receive separately cached responses.
Cookie name rules: Only alphanumeric characters, hyphens, and underscores are allowed in cookie names.
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 (single character) |
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.
Cache Control Header
When enabled, smoxy respects the Cache-Control header from your origin server's response. This allows your origin to control caching behavior on a per-response basis.
| Setting | Default |
|---|---|
cache_control_header_enabled | Disabled |
When disabled, smoxy uses the configured TTL for all cacheable responses regardless of the origin's Cache-Control header.
The s-cache Response Header
When Acceleration or Image Optimization is 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:
- The Cache Control Header option is enabled and the origin returned
Cache-Control: no-cache,private, ormax-age=0. - 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.
- Cookie vary 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.