---
title: core
summary: Package core provides the Fastly Core Cache API.
url: https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/
---

**Kind:** Module  
**Package:** compute-sdk-go v1.11.0  
**Path:** `github.com/fastly/compute-sdk-go/cache/core`

Package core provides the Fastly Core Cache API.

This package 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 4096 bytes of arbtirary data that identify a
    cached object.  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.

  - 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 object that can be updated when revalidating the cached
    object.

  - The object itself: arbitrary bytes read via an [io.ReadCloser](https://pkg.go.dev/io#ReadCloser) and
    written via a [WriteCloseAbandoner](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/interface.WriteCloseAbandoner/).

In the simplest cases, the top-level [Insert](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/fn.Insert/) and [Lookup](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/fn.Lookup/) functions
are used for one-off operations on a cached object, 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/go/compute-sdk-go/cache/core/struct.Transaction/), which can
collapse concurrent lookups to the same item, including coordinating
revalidation.

## Structs

| Name | Summary |
| --- | --- |
| [Found](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Found/) | Found represents a cached object found by a cache lookup. |
| [LookupOptions](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.LookupOptions/) | LookupOptions control the behavior of cache lookups and the objects returned. |
| [Transaction](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.Transaction/) | Transaction represents a construct to coordinate concurrent actions for the same cache key. |
| [WriteOptions](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/struct.WriteOptions/) | WriteOptions control the behavior of cache inserts and updates.  TTL is required, but all other fields are optional. |

## Interfaces

| Name | Summary |
| --- | --- |
| [WriteCloseAbandoner](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/interface.WriteCloseAbandoner/) | WriteCloseAbandoner is an interface returned by cache insert operations.  It is an [io.WriteCloser](https://pkg.go.dev/io#WriteCloser) that also supports abandoning the stream.  When Abandon is called, the insert operation is canceled and content written is not saved into the cache. |

## Functions

| Name | Summary |
| --- | --- |
| [Insert](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/fn.Insert/) | Insert creates a [WriteCloseAbandoner](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/interface.WriteCloseAbandoner/) used for inserting an object into the cache for the given key.  For the insertion to complete successfully, the object must be fully written to the writer and its Close method called. |
| [Lookup](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/fn.Lookup/) | Lookup performs a simple, non-transactional lookup for the given key. If the key is not cached, [ErrNotFound] is returned.  Keys can be up to 4096 bytes in length. |
| [NewTransaction](https://www.fastly.com/documentation/reference/compute/sdks/go/compute-sdk-go/cache/core/fn.NewTransaction/) | NewTransaction creates a new cache transaction for the given key. |

## Variables

### ErrInvalidArgument

**Type:** `error`  
**Default:** `errors.New("cache: invalid argument")`  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L64

ErrInvalidArgument is returned when an argument passed to a
function is invalid.

### ErrInvalidOperation

**Type:** `error`  
**Default:** `errors.New("cache: invalid operation")`  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L68

ErrInvalidOperation is returned when an operation to be performed
is not valid given the state of the cached object.

### ErrLimitExceeded

**Type:** `error`  
**Default:** `errors.New("cache: operation limit exceeded")`  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L72

ErrLimitExceeded is returned when a cache operation exceeds the
limits allowed for this service.

### ErrNotFound

**Type:** `error`  
**Default:** `errors.New("cache: object not found")`  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L60

ErrNotFound is returned when a cache lookup fails to find a
cached object with the provided key.

### ErrUnexpected

**Type:** `error`  
**Default:** `errors.New("cache: unexpected error")`  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L79

ErrUnexpected is returned when an unexpected error occurs.

### ErrUnsupported

**Type:** `error`  
**Default:** `errors.New("cache: operation not supported")`  
**Source:** https://github.com/fastly/compute-sdk-go/blob/d6bf71b04516ed72d6018cab6fff701a865f86e5/cache/core/core.go#L76

ErrUnsupported is returned when a cache operation is not
supported.