Struct worker::Cache

pub struct Cache { /* private fields */ }

Provides access to the Cache API. Because match is a reserved keyword in Rust, the match method has been renamed to get.

Our implementation of the Cache API respects the following HTTP headers on the response passed to put():

• Cache-Control
  • Controls caching directives. This is consistent with Cloudflare Cache-Control Directives. Refer to Edge TTL for a list of HTTP response codes and their TTL when Cache-Control directives are not present.
• Cache-Tag
  • Allows resource purging by tag(s) later (Enterprise only).
• ETag
  • Allows cache.get() to evaluate conditional requests with If-None-Match.
• Expires
  • A string that specifies when the resource becomes invalid.
• Last-Modified
  • Allows cache.get() to evaluate conditional requests with If-Modified-Since.

This differs from the web browser Cache API as they do not honor any headers on the request or response.

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().

Use the Cache-Control method to store the response without the Set-Cookie header.

Implementations

impl Cache

pub async fn open(name: String) -> Self

Opens a Cache by name. To access the default global cache, use Cache::default().

pub async fn put<'a, K: Into<CacheKey<'a>>>(
    &self,
    key: K,
    response: Response
) -> Result<()>

Adds to the cache a Response keyed to the given request.

The Response should include a cache-control header with max-age or s-maxage directives, otherwise the Cache API will not cache the response. The stale-while-revalidate and stale-if-error directives are not supported when using the cache.put or cache.get methods. For more information about how the Cache works, visit the documentation at Cache API and Cloudflare Cache-Control Directives

The Cache API will throw an error if:

• the request passed is a method other than GET.
• the response passed has a status of 206 Partial Content.
• the response passed contains the header Vary: * (required by the Cache API specification).

pub async fn get<'a, K: Into<CacheKey<'a>>>(
    &self,
    key: K,
    ignore_method: bool
) -> Result<Option<Response>>

Returns the Response object keyed to that request. Never sends a subrequest to the origin. If no matching response is found in cache, returns None.

Unlike the browser Cache API, Cloudflare Workers do not support the ignoreSearch or ignoreVary options on get(). You can accomplish this behavior by removing query strings or HTTP headers at put() time. In addition, the stale-while-revalidate and stale-if-error directives are not supported when using the cache.put or cache.get methods.

Our implementation of the Cache API respects the following HTTP headers on the request passed to get():

• Range
  • 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.
• If-Modified-Since
  • Results in a 304 response if a matching response is found with a Last-Modified header with a value after the time specified in If-Modified-Since.
• If-None-Match
  • Results in a 304 response if a matching response is found with an ETag header with a value that matches a value in If-None-Match.

pub async fn delete<'a, K: Into<CacheKey<'a>>>(
    &self,
    key: K,
    ignore_method: bool
) -> Result<CacheDeletionOutcome>

Deletes the Response object associated with the key.

Returns:

• Success, if the response was cached but is now deleted
• ResponseNotFound, if the response was not in the cache at the time of deletion

Trait Implementations

impl Debug for Cache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Cache

fn default() -> Self

Returns the “default value” for a type.