Skip to content

Commit efffffe

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 5dda6ff commit efffffe

5 files changed

Lines changed: 638 additions & 0 deletions

File tree

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

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
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 set all the Cache Response Rules of a zone to the rules included in the request. 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: Set max-age and remove stale-if-error">
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+
"stale-if-error": {
123+
operation: "remove"
124+
}
125+
}
126+
}
127+
]
128+
}}
129+
roles={false}
130+
/>
131+
132+
</Details>
133+
134+
<Details header="Example: Set private directive with qualifiers">
135+
136+
<APIRequest
137+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
138+
method="PUT"
139+
json={{
140+
rules: [
141+
{
142+
expression: 'http.request.uri.path starts_with "/user/"',
143+
description: "Mark user content as private",
144+
action: "set_cache_control",
145+
action_parameters: {
146+
"private": {
147+
operation: "set",
148+
qualifiers: ["X-User-Id", "X-Session-Token"]
149+
},
150+
"no-cache": {
151+
operation: "set"
152+
}
153+
}
154+
}
155+
]
156+
}}
157+
roles={false}
158+
/>
159+
160+
</Details>
161+
162+
<Details header="Example: Set immutable for static font assets">
163+
164+
<APIRequest
165+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
166+
method="PUT"
167+
json={{
168+
rules: [
169+
{
170+
expression: 'http.request.uri.path.extension in {"woff2" "woff" "ttf"}',
171+
description: "Mark fonts as immutable",
172+
action: "set_cache_control",
173+
action_parameters: {
174+
"immutable": {
175+
operation: "set"
176+
},
177+
"max-age": {
178+
operation: "set",
179+
value: 31536000
180+
}
181+
}
182+
}
183+
]
184+
}}
185+
roles={false}
186+
/>
187+
188+
</Details>
189+
190+
<Details header="Example: Multiple rules — strip headers, tag responses, and set cache control">
191+
192+
<APIRequest
193+
path="/zones/{zone_id}/rulesets/phases/http_response_cache_settings/entrypoint"
194+
method="PUT"
195+
json={{
196+
rules: [
197+
{
198+
expression: 'http.response.code eq 200 and http.request.uri.path.extension eq "html"',
199+
description: "Strip tracking headers from HTML responses",
200+
action: "set_cache_settings",
201+
action_parameters: {
202+
strip_etags: true,
203+
strip_set_cookie: true
204+
}
205+
},
206+
{
207+
expression: 'http.request.uri.path starts_with "/products/"',
208+
description: "Tag product pages for purging",
209+
action: "set_cache_tags",
210+
action_parameters: {
211+
operation: "add",
212+
values: ["product-catalog", "storefront"]
213+
}
214+
},
215+
{
216+
expression: "http.response.code eq 200",
217+
description: "Set cache control for all 200 responses",
218+
action: "set_cache_control",
219+
action_parameters: {
220+
"s-maxage": {
221+
operation: "set",
222+
value: 86400,
223+
cloudflare_only: true
224+
},
225+
"must-revalidate": {
226+
operation: "set"
227+
}
228+
}
229+
}
230+
]
231+
}}
232+
roles={false}
233+
/>
234+
235+
</Details>
236+
237+
## Required API token permissions
238+
239+
The API token used in API requests to manage Cache Response Rules must have the following permissions:
240+
241+
- *Zone* > *Cache Rules* > *Edit*
242+
- *Account Rulesets* > *Edit*
243+
- *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: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
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 <InlineBadge preset="beta" /> allow you to configure cache settings based on the **response** from the origin server, rather than only the incoming request. These rules execute in the `http_response_cache_settings` phase, which runs after Cloudflare receives the origin response, giving you access to both request and response fields for rule matching.
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+
- Modify Cache-Control header directives in 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+
- **Stacking** — Cache Response Rules stack the same way as Cache Rules. When multiple rules specify the same setting, the last matching rule wins.
49+
50+
### Example: OCC precedence over Edge TTL
51+
52+
Consider the following scenario:
53+
54+
1. A Cache Rule sets **Edge TTL** to `override_origin` with a value of `7200` seconds (2 hours).
55+
2. A Cache Response Rule uses `set_cache_control` to set `s-maxage` to `3600` seconds (1 hour) with `cloudflare_only` enabled.
56+
3. The origin responds with `Cache-Control: s-maxage=600`.
57+
58+
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.

0 commit comments

Comments
 (0)