Skip to content

Commit 0c81a13

Browse files
tkornhammartkornhammar
committed
docs(cache): add Cache Response Rules documentation
Add new Cache Response Rules how-to section covering the http_response_cache_settings phase, including: - Overview and concept page with availability and troubleshooting - Available settings reference (fields, operators, actions) - API creation guide with examples for all three actions - Dashboard creation guide - Terraform example
1 parent 14a6ef9 commit 0c81a13

6 files changed

Lines changed: 656 additions & 1 deletion

File tree

‎src/content/docs/cache/concepts/cdn-cache-control.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@ pcx_content_type: concept
1010

1111
You have several options available to determine how `CDN-Cache-Control` directives interact with `Cache-Control` directives.
1212

13-
An origin can:
13+
If a [Cache Response Rule](/cache/how-to/cache-response-rules/) sets `Cache-Control` directives using the `set_cache_control` action, those directives take precedence over any origin-set `Cloudflare-CDN-Cache-Control` and `CDN-Cache-Control` headers.
14+
15+
When no Cache Response Rule applies, an origin can:
1416

1517
* Return the `CDN-Cache-Control` response header which Cloudflare evaluates to make caching decisions. `Cache-Control`, if also returned by the origin, is proxied as is and does not affect caching decisions made by Cloudflare. Additionally, `CDN-Cache-Control` is proxied downstream in case there are other CDNs between Cloudflare and the browser.
1618

‎src/content/docs/cache/how-to/cache-response-rules/create-api.mdx‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Create a rule via API
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 4
6+
head:
7+
- tag: title
8+
content: Create a Cache Response Rule via API
9+
---
10+
11+
import { Details, APIRequest } from "~/components";
12+
13+
Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create a Cache Response Rule via API. To configure the Cloudflare API, refer to the [API documentation](/fundamentals/api/get-started/).
14+
15+
## Basic rule settings
16+
17+
When creating a Cache Response Rule via API, make sure you:
18+
19+
- Set the rule action to one of the [available actions](/cache/how-to/cache-response-rules/settings/#available-actions).
20+
- Define the parameters in the `action_parameters` field according to the [settings](/cache/how-to/cache-response-rules/settings/) you wish to configure for matching responses.
21+
- Deploy the rule to the `http_response_cache_settings` phase entry point ruleset.
22+
23+
## Procedure
24+
25+
1. Use the [List zone rulesets](/api/resources/rulesets/methods/list/) method to check if a ruleset already exists for the `http_response_cache_settings` phase.
26+
2. If the phase ruleset does not exist, create it using the [Create a zone ruleset](/api/resources/rulesets/methods/create/) operation. In the new ruleset properties, set the following values:
27+
- kind: `zone`
28+
- phase: `http_response_cache_settings`
29+
3. Use the [Update a zone ruleset](/api/resources/rulesets/methods/update/) operation to add rules to the ruleset. Alternatively, include the rules in the [Create a zone ruleset](/api/resources/rulesets/methods/create/) request mentioned in the previous step.
30+
31+
## Example requests
32+
33+
These examples demonstrate all the available actions in Cache Response Rules using request and response matching criteria. Using these examples directly will cause any existing rules in the phase to be replaced.
34+
35+
<Details header="Example: Strip response headers from JS files before caching">
36+
37+
<APIRequest
38+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
39+
method="PUT"
40+
json={{
41+
rules: [
42+
{
43+
expression: 'http.request.uri.path.extension eq "js"',
44+
description: "Strip caching headers from JS files",
45+
action: "set_cache_settings",
46+
action_parameters: {
47+
strip_etags: true,
48+
strip_set_cookie: true,
49+
strip_last_modified: true
50+
}
51+
}
52+
]
53+
}}
54+
roles={false}
55+
/>
56+
57+
</Details>
58+
59+
<Details header="Example: Set static cache tags on API responses">
60+
61+
<APIRequest
62+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
63+
method="PUT"
64+
json={{
65+
rules: [
66+
{
67+
expression: 'http.request.uri.path starts_with "/api/"',
68+
description: "Tag API responses for targeted purging",
69+
action: "set_cache_tags",
70+
action_parameters: {
71+
operation: "set",
72+
values: ["api-response", "dynamic-content"]
73+
}
74+
}
75+
]
76+
}}
77+
roles={false}
78+
/>
79+
80+
</Details>
81+
82+
<Details header="Example: Add cache tags from a response header using an expression">
83+
84+
<APIRequest
85+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
86+
method="PUT"
87+
json={{
88+
rules: [
89+
{
90+
expression: 'any(http.response.headers.names[*] == "Surrogate-Keys")',
91+
description: "Extract cache tags from alternative CDN response header",
92+
action: "set_cache_tags",
93+
action_parameters: {
94+
operation: "add",
95+
expression: 'split(http.response.headers["Surrogate-Keys"][0], ",", 1)'
96+
}
97+
}
98+
]
99+
}}
100+
roles={false}
101+
/>
102+
103+
</Details>
104+
105+
<Details header="Example: Override cache-control with max-age ">
106+
107+
<APIRequest
108+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
109+
method="PUT"
110+
json={{
111+
rules: [
112+
{
113+
expression: "http.response.code eq 200",
114+
description: "Override cache-control for successful responses",
115+
action: "set_cache_control",
116+
action_parameters: {
117+
"max-age": {
118+
operation: "set",
119+
value: 3600,
120+
cloudflare_only: true
121+
},
122+
}
123+
}
124+
]
125+
}}
126+
roles={false}
127+
/>
128+
129+
</Details>
130+
131+
<Details header="Example: Set private directive with qualifiers">
132+
133+
<APIRequest
134+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
135+
method="PUT"
136+
json={{
137+
rules: [
138+
{
139+
expression: 'http.request.uri.path starts_with "/user/"',
140+
description: "Mark user content as private",
141+
action: "set_cache_control",
142+
action_parameters: {
143+
"private": {
144+
operation: "set",
145+
qualifiers: ["X-User-Id", "X-Session-Token"]
146+
},
147+
"no-cache": {
148+
operation: "set"
149+
}
150+
}
151+
}
152+
]
153+
}}
154+
roles={false}
155+
/>
156+
157+
</Details>
158+
159+
<Details header="Example: Set immutable for static font assets">
160+
161+
<APIRequest
162+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
163+
method="PUT"
164+
json={{
165+
rules: [
166+
{
167+
expression: 'http.request.uri.path.extension in {"woff2" "woff" "ttf"}',
168+
description: "Mark fonts as immutable",
169+
action: "set_cache_control",
170+
action_parameters: {
171+
"immutable": {
172+
operation: "set"
173+
},
174+
"max-age": {
175+
operation: "set",
176+
value: 31536000
177+
}
178+
}
179+
}
180+
]
181+
}}
182+
roles={false}
183+
/>
184+
185+
</Details>
186+
187+
<Details header="Example: Multiple rules — strip headers, tag responses, and set cache control">
188+
189+
<APIRequest
190+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
191+
method="PUT"
192+
json={{
193+
rules: [
194+
{
195+
expression: 'http.response.code eq 200 and http.request.uri.path.extension eq "html"',
196+
description: "Strip tracking headers from HTML responses",
197+
action: "set_cache_settings",
198+
action_parameters: {
199+
strip_etags: true,
200+
strip_set_cookie: true
201+
}
202+
},
203+
{
204+
expression: 'http.request.uri.path starts_with "/products/"',
205+
description: "Tag product pages for purging",
206+
action: "set_cache_tags",
207+
action_parameters: {
208+
operation: "add",
209+
values: ["product-catalog", "storefront"]
210+
}
211+
},
212+
{
213+
expression: "http.response.code eq 200",
214+
description: "Set cache control for all 200 responses",
215+
action: "set_cache_control",
216+
action_parameters: {
217+
"s-maxage": {
218+
operation: "set",
219+
value: 86400,
220+
cloudflare_only: true
221+
},
222+
"must-revalidate": {
223+
operation: "set"
224+
}
225+
}
226+
}
227+
]
228+
}}
229+
roles={false}
230+
/>
231+
232+
</Details>
233+
234+
## Required API token permissions
235+
236+
The API token used in API requests to manage Cache Response Rules must have the following permissions:
237+
238+
- *Zone* > *Cache Rules* > *Edit*
239+
- *Account Rulesets* > *Edit*
240+
- *Account Filter Lists* > *Edit*

‎src/content/docs/cache/how-to/cache-response-rules/create-dashboard.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Create a rule in the dashboard
4+
sidebar:
5+
order: 3
6+
head:
7+
- tag: title
8+
content: Create a Cache Response Rule in the dashboard
9+
---
10+
11+
import { Render, DashButton } from "~/components";
12+
13+
1. In the Cloudflare dashboard, go to **Cache** > **Cache Rules**.
14+
15+
<DashButton url="/?to=/:account/:zone/caching/cache-rules" />
16+
17+
2. Select the **Cache Response Rules** tab.
18+
3. Select **Create rule**.
19+
20+
4. Enter a descriptive name for the rule in **Rule name**.
21+
5. Under **When incoming requests match**, select **All incoming requests** if you want the rule to apply to all traffic or **Custom filter expression** if you want the rule to only apply to traffic matching the custom expression.
22+
6. If you selected **Custom filter expression**, define the [rule expression](/ruleset-engine/rules-language/expressions/edit-expressions/#expression-builder). Use the **Field** drop-down list to choose an HTTP property and select an **Operator**. Both request fields (such as URI path or hostname) and response fields (such as response status code or response headers) are available for matching. Refer to [Available settings](/cache/how-to/cache-response-rules/settings/) for the full list of available fields and operators.
23+
24+
:::note
25+
Rules can be further customized by using the **Edit expression** option. You can find more information in [Edit expressions in the dashboard](/ruleset-engine/rules-language/expressions/edit-expressions/).
26+
:::
27+
28+
7. Following the selection of the field and operator, enter the corresponding value that will trigger the Cache Response Rule. For example, if the selected field is `Hostname` and the operator is `equals`, a value of `example.com` would mean the rule matches any request to that hostname.
29+
8. Under **Then**, select the action you want to apply. Refer to [Available settings](/cache/how-to/cache-response-rules/settings/#available-actions) for the list of available actions and their parameters.
30+
9. Under **Place at**, from the dropdown, you can select the order of your rule. From the main page, you can also change the order of the rules you have created.
31+
10. To save and deploy your rule, select **Deploy**. If you are not ready to deploy your rule, select **Save as Draft**.
32+
33+
<Render file="rules-creation-dash-dns-popup" product="rules" />

‎src/content/docs/cache/how-to/cache-response-rules/index.mdx‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Cache Response Rules
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 2
6+
---
7+
8+
import { FeatureTable, InlineBadge, Render } from "~/components";
9+
10+
Cache Response Rules allow you to configure cache settings based on request and response attributes. These rules execute prior to caching in the in the `http_response_cache_settings` phase, which runs after Cloudflare receives the origin response.
11+
12+
With Cache Response Rules you can:
13+
14+
- Strip specific headers (ETags, Set-Cookie, Last-Modified) from origin responses before caching.
15+
- Add, remove, or set cache tags on responses for targeted [cache purging](/cache/how-to/purge-cache/).
16+
- Set the Cache-Control header directives for the origin response.
17+
18+
Cache Response Rules apply to both cached and non-cached (dynamic) responses from the origin. For example, you can strip Set-Cookie headers from responses that are not eligible for caching.
19+
20+
Cache Response Rules can be created in the [dashboard](/cache/how-to/cache-response-rules/create-dashboard/), via [API](/cache/how-to/cache-response-rules/create-api/), or [Terraform](/cache/how-to/cache-response-rules/terraform-example/).
21+
22+
:::note
23+
24+
Cache Response Rules require that you [proxy the DNS records](/dns/proxy-status/) of your domain (or subdomain) through Cloudflare.
25+
26+
:::
27+
28+
## Availability
29+
30+
The following table describes Cache Response Rules availability per plan.
31+
32+
<FeatureTable id="cache.cache_rules" />
33+
34+
<Render
35+
file="troubleshoot-rules-with-trace"
36+
product="rules"
37+
params={{ rulesFeatureName: "Cache Response Rules" }}
38+
/>
39+
40+
## Relationship with Cache Rules
41+
42+
Cache Response Rules operate on the origin response, while [Cache Rules](/cache/how-to/cache-rules/) operate on the incoming request. When settings from both rule types conflict, Cache Response Rules take precedence.
43+
44+
Key differences:
45+
46+
- **Cache eligibility** ΓÇö Cache Rules remain the only mechanism to decide whether content is eligible for caching. However, Cache Response Rules can make a cacheable asset non-cacheable by setting the `no-store` directive using the `set_cache_control` action.
47+
- **Origin Cache Control (OCC)** ΓÇö If any rule in the `http_response_cache_settings` phase matches, Cloudflare defaults to Origin Cache Control behavior (`origin_cache_control = true`).
48+
- **CDN-Cache-Control precedence** ΓÇö `Cache-Control` directives set by Cache Response Rules take precedence over origin-set `Cloudflare-CDN-Cache-Control` and `CDN-Cache-Control` headers. For more information, refer to [CDN-Cache-Control header precedence](/cache/concepts/cdn-cache-control/#header-precedence).
49+
- **Stacking** ΓÇö Cache Response Rules stack the same way as Cache Rules. When multiple rules specify the same setting, the last matching rule wins.
50+
51+
### Example: OCC precedence over Edge TTL
52+
53+
Consider the following scenario:
54+
55+
1. A Cache Rule sets **Edge TTL** to `override_origin` with a value of `7200` seconds (2 hours).
56+
2. A Cache Response Rule uses `set_cache_control` to set `s-maxage` to `3600` seconds (1 hour) with `cloudflare_only` enabled.
57+
3. The origin responds with `Cache-Control: s-maxage=600`.
58+
59+
In this case, the Cache Response Rule takes precedence. Cloudflare caches the asset for `3600` seconds (1 hour) based on the `s-maxage` directive set by the Cache Response Rule, while visitors still receive the original `s-maxage=600` from the origin because `cloudflare_only` is enabled.
60+
61+
## Notes
62+
63+
- If you strip last modified then Smart Edge Revalidation will be turned off.
64+
- Cache Response Rules ignore HTTP Response 1xx as it is treated as informational responses.

0 commit comments

Comments
 (0)