---
title: core
summary: The Compute Core Cache API.
url: https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/
---

**Kind:** Module  
**Package:** fastly 0.13.1  
**Path:** `fastly::cache::core`

The Compute Core Cache API.

This API exposes the primitive operations required to implement high-performance cache
applications with advanced features such as [request
collapsing](https://developer.fastly.com/learning/concepts/request-collapsing/), [streaming
miss](https://docs.fastly.com/en/guides/streaming-miss),
[revalidation](https://developer.fastly.com/learning/concepts/stale/), and [surrogate key
purging](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys).

While this API contains affordances for some HTTP caching concepts such as `Vary` headers and
`stale-while-revalidate`, this API is **not** suitable for HTTP caching out-of-the-box. Future
SDK releases will add a more customizable HTTP Cache API with support for customizable
read-through caching, freshness lifetime inference, conditional request evaluation, automatic
revalidation, and more.

Cached items in this API consist of:

* **A cache key**: up to 4KiB of arbitrary bytes that identify a cached item. The cache key may
  not uniquely identify an item; **headers** can be used to augment the key when multiple items
  are associated with the same key. See [`LookupBuilder::header()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.LookupBuilder/#method-header) for more details.

* **General metadata**, such as expiry data (item age, when to expire, and surrogate keys for
  purging).

* **User-controlled metadata**: arbitrary bytes stored alongside the cached item contents that
  can be updated when revalidating the cached item.

* **The object itself**: arbitrary bytes read via [`Body`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/http/body/struct.Body/) and written via [`StreamingBody`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/http/body/struct.StreamingBody/).

In the simplest cases, the top-level [`insert()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/fn.insert/) and [`lookup()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/fn.lookup/) functions are used for
one-off operations on a cached item, and are appropriate when request collapsing and
revalidation capabilities are not required.

The API also supports more complex uses via [`Transaction`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Transaction/), which can collapse concurrent
lookups to the same item, including coordinating revalidation. See the [`Transaction`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Transaction/)
documentation for more details.

## Structs

| Name | Summary |
| --- | --- |
| [Found](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Found/) | A cached item returned by a lookup. |
| [InsertBuilder](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.InsertBuilder/) | A builder-style API for configuring a non-transactional insertion. |
| [LookupBuilder](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.LookupBuilder/) | A builder-style API for configuring a non-transactional lookup. |
| [PendingTransaction](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.PendingTransaction/) | A cache transaction suspended between lookup and response. |
| [Replace](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Replace/) | An in-progress Replace operation. |
| [ReplaceBuilder](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.ReplaceBuilder/) | A builder-style API for configuring a non-transactional replace. |
| [Transaction](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Transaction/) | A cache transaction initiated by [`Transaction::lookup()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Transaction/#method-lookup). |
| [TransactionInsertBuilder](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.TransactionInsertBuilder/) | A builder-style API for configuring a transactional cache insertion. |
| [TransactionLookupBuilder](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.TransactionLookupBuilder/) | A builder-style API for configuring a transactional lookup. |
| [TransactionUpdateBuilder](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.TransactionUpdateBuilder/) | A builder-style API for configuring a transactional cache update. |

## Enums

| Name | Summary |
| --- | --- |
| [CacheError](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/enum.CacheError/) | Errors arising from cache operations. |
| [ReplaceStrategy](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/enum.ReplaceStrategy/) | Strategy to use to replace the existing object |

## Type aliases

| Name | Summary |
| --- | --- |
| [CacheKey](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/type.CacheKey/) | A cache key consists of up to 4KiB of arbitrary bytes. |

## Functions

| Name | Summary |
| --- | --- |
| [insert](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/fn.insert/) | Returns an [`InsertBuilder`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.InsertBuilder/) that will perform a non-transactional cache insertion. |
| [lookup](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/fn.lookup/) | Returns a [`LookupBuilder`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.LookupBuilder/) that will perform a non-transactional cache lookup. |
| [replace](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/fn.replace/) | Returns a [`ReplaceBuilder`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.ReplaceBuilder/) that will perform a transactional cache replacement. |