Skip to content

Fix Cloud static cache cookie key docs #775

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timkelty merged 1 commit into from
Jun 2, 2026
+5 −5
Merged

Fix Cloud static cache cookie key docs #775

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/cloud/static-caching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ cache:
- message
- pattern: /referral
# Cache based on unique values for an `AD_SOURCE` cookie:
session:
cookies:
- AD_SOURCE
- REFERRER_NETWORK
- pattern: /
Expand All @@ -177,15 +177,15 @@ Cloud uses the first rule that matches, so you should declare them with _descend
Note that customizing `query-string` _replaces_ our default behavior and [exclusion list](#ignored-params).
:::

Each `pattern` uses the same URL matching logic as [rewrites and redirects](redirects.md), and must define at least a `query-string` or `session` key.
Each `pattern` uses the same URL matching logic as [rewrites and redirects](redirects.md), and must define at least a `query-string` or `cookies` key.

- **Query String** (`query-string`) — Two nested keys are required:
- `mode` — Determines the behavior for this rule. `include` treats the provided `keys` as an allow-list; `exclude` treats it as a deny-list.
- `keys` — The query string keys that are used as a mask for the chosen `mode`.
- **Cookies** (`session`) — Directly nest a list of strings corresponding to cookie names that should be incorporated into the cache key. There is no `mode` for cookie settings; when a key is provided _and present in a client’s request_, it is added to the cache key. Otherwise, cookies are ignored.
- **Cookies** (`cookies`) — Directly nest a list of strings corresponding to cookie names that should be incorporated into the cache key. There is no `mode` for cookie settings; when a key is provided _and present in a client’s request_, it is added to the cache key. Otherwise, cookies are ignored.

In both cases, keys _and their values_ are ultimately used to build cache keys—so pages matching the `session` rule above would be cached uniquely for clients with different `AD_SOURCE` cookie values.
You can combine `query-string` and `session` masks in a single rule for additional granularity.
In both cases, keys _and their values_ are ultimately used to build cache keys—so pages matching the `cookies` rule above would be cached uniquely for clients with different `AD_SOURCE` cookie values.
You can combine `query-string` and `cookies` masks in a single rule for additional granularity.

The default behavior can be represented as a catch-all rule, like this:

Expand Down
Loading