You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/workers/runtime-apis/cache.mdx
+8-39Lines changed: 8 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,10 +14,8 @@ The Cache API is available globally but the contents of the cache do not replica
14
14
15
15
:::caution[Tiered caching]
16
16
17
-
18
17
The `cache.put` method is not compatible with tiered caching. Refer to [Cache API](/workers/reference/how-the-cache-works/#cache-api) for more information. To perform tiered caching, use the [fetch API](/workers/reference/how-the-cache-works/#interact-with-the-cloudflare-cache).
19
18
20
-
21
19
:::
22
20
23
21
Workers deployed to custom domains have access to functional `cache` operations. So do [Pages functions](/pages/functions/), whether attached to custom domains or `*.pages.dev` domains.
@@ -26,10 +24,8 @@ However, any Cache API operations in the Cloudflare Workers dashboard editor and
26
24
27
25
:::note
28
26
29
-
30
27
This individualized zone cache object differs from Cloudflare’s Global CDN. For details, refer to [How the cache works](/workers/reference/how-the-cache-works/).
31
28
32
-
33
29
:::
34
30
35
31
***
@@ -49,7 +45,9 @@ You may create and manage additional Cache instances via the [`caches.open`](htt
49
45
let myCache =awaitcaches.open('custom:cache');
50
46
awaitmyCache.match(request);
51
47
```
48
+
52
49
:::note
50
+
53
51
When using the cache API, avoid overriding the hostname in cache requests, as this can lead to unnecessary DNS lookups and cache inefficiencies. Always use the hostname that matches the domain associated with your Worker.
Our implementation of the Cache API respects the following HTTP headers on the response passed to `put()`:
68
68
69
-
70
-
71
69
*`Cache-Control`
72
70
* Controls caching directives. This is consistent with [Cloudflare Cache-Control Directives](/cache/concepts/cache-control#cache-control-directives). Refer to [Edge TTL](/cache/how-to/configure-cache-status-code#edge-ttl) for a list of HTTP response codes and their TTL when `Cache-Control` directives are not present.
73
71
*`Cache-Tag`
@@ -79,18 +77,14 @@ Our implementation of the Cache API respects the following HTTP headers on the r
79
77
*`Last-Modified`
80
78
* Allows `cache.match()` to evaluate conditional requests with `If-Modified-Since`.
81
79
82
-
83
-
84
80
This differs from the web browser Cache API as they do not honor any headers on the request or response.
85
81
86
82
:::note
87
83
88
-
89
84
Responses with `Set-Cookie` headers are never cached, because this sometimes indicates that the response contains unique data. To store a response with a `Set-Cookie` header, either delete that header or set `Cache-Control: private=Set-Cookie` on the response before calling `cache.put()`.
90
85
91
86
Use the `Cache-Control` method to store the response without the `Set-Cookie` header.
92
87
93
-
94
88
:::
95
89
96
90
***
@@ -103,21 +97,17 @@ Use the `Cache-Control` method to store the response without the `Set-Cookie` he
103
97
cache.put(request, response);
104
98
```
105
99
106
-
107
-
108
100
* <code>put(request, response)</code> : Promise
109
101
110
102
* Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to `undefined` regardless of whether the cache successfully stored the response.
111
103
112
-
113
-
114
104
:::note
115
105
116
-
117
106
The `stale-while-revalidate` and `stale-if-error` directives are not supported when using the `cache.put` or `cache.match` methods.
118
-
#### Parameters
119
107
108
+
:::
120
109
110
+
#### Parameters
121
111
122
112
*`request` string | Request
123
113
@@ -126,8 +116,6 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w
126
116
*`response` Response
127
117
* A [`Response`](/workers/runtime-apis/response/) object to store under the given key.
128
118
129
-
130
-
131
119
#### Invalid parameters
132
120
133
121
`cache.put` will throw an error if:
@@ -146,21 +134,17 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w
* Returns a promise wrapping the response object keyed to that request.
154
140
155
-
156
-
157
141
:::note
158
142
159
-
160
143
The `stale-while-revalidate` and `stale-if-error` directives are not supported when using the `cache.put` or `cache.match` methods.
161
-
#### Parameters
144
+
:::
162
145
163
146
147
+
#### Parameters
164
148
165
149
*`request` string | Request
166
150
@@ -169,14 +153,10 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w
169
153
*`options`
170
154
* Can contain one possible property: `ignoreMethod` (Boolean). When `true`, the request is considered to be a `GET` request regardless of its actual value.
171
155
172
-
173
-
174
156
Unlike the browser Cache API, Cloudflare Workers do not support the `ignoreSearch` or `ignoreVary` options on `match()`. You can accomplish this behavior by removing query strings or HTTP headers at `put()` time.
175
157
176
158
Our implementation of the Cache API respects the following HTTP headers on the request passed to `match()`:
177
159
178
-
179
-
180
160
*`Range`
181
161
182
162
* Results in a `206` response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if an `Accept-Ranges` header is on the response.
@@ -193,7 +173,6 @@ Our implementation of the Cache API respects the following HTTP headers on the r
193
173
* Never sends a subrequest to the origin. If no matching response is found in cache, the promise that `cache.match()` returns is fulfilled with `undefined`.
194
174
195
175
196
-
197
176
#### Errors
198
177
199
178
`cache.match` generates a `504` error response when the requested content is missing or expired. The Cache API does not expose this `504` directly to the Worker script, instead returning `undefined`. Nevertheless, the underlying `504` is still visible in Cloudflare Logs.
@@ -206,38 +185,28 @@ If you use Cloudflare Logs, you may see these `504` responses with the `RequestS
Deletes the `Response` object from the cache and returns a `Promise` for a Boolean response:
216
191
217
192
*`true`: The response was cached but is now deleted
218
193
*`false`: The response was not in the cache at the time of deletion.
219
194
220
195
:::caution[Global purges]
221
196
222
-
223
197
The `cache.delete` method only purges content of the cache in the data center that the Worker was invoked. For global purges, refer to [Purging assets stored with the Cache API](/workers/reference/how-the-cache-works/#purge-assets-stored-with-the-cache-api).
224
198
225
-
226
199
:::
227
200
228
201
#### Parameters
229
202
230
-
231
-
232
203
*`request` string | Request
233
204
234
205
* The string or [`Request`](/workers/runtime-apis/request/) object used as the lookup key. Strings are interpreted as the URL for a new `Request` object.
235
206
236
207
*`options` object
237
208
* Can contain one possible property: `ignoreMethod` (Boolean). Consider the request method a GET regardless of its actual value.
0 commit comments