# Advanced Caching

smoxy provides a CDN caching layer that stores copies of your. 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.

***

### 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.