|
| 1 | +// Package simple provides the Simple Cache API, a simplified interface |
| 2 | +// to inserting and retrieving entries from Fastly's cache. |
| 3 | +// |
| 4 | +// Cache operations are local to the Fastly POP serving the request. |
| 5 | +// Purging can also be performed globally. |
| 6 | +// |
| 7 | +// For more advanced uses, see the Core Cache API in the |
| 8 | +// [github.com/fastly/compute-sdk-go/cache/core] package. |
| 9 | +package simple |
| 10 | + |
| 11 | +import ( |
| 12 | + "crypto/sha256" |
| 13 | + "encoding/hex" |
| 14 | + "io" |
| 15 | + "os" |
| 16 | + "strings" |
| 17 | + "time" |
| 18 | + |
| 19 | + "github.com/fastly/compute-sdk-go/cache/core" |
| 20 | + "github.com/fastly/compute-sdk-go/purge" |
| 21 | +) |
| 22 | + |
| 23 | +// Get retrieves the object stored in the cache for the given key. If |
| 24 | +// the key is not cached, [core.ErrNotFound] is returned. Keys can be |
| 25 | +// up to 4096 bytes in length. |
| 26 | +// |
| 27 | +// The returned [io.ReadCloser] must be closed by the caller when |
| 28 | +// finished. |
| 29 | +func Get(key []byte) (io.ReadCloser, error) { |
| 30 | + f, err := core.Lookup(key, core.LookupOptions{}) |
| 31 | + if err != nil { |
| 32 | + return nil, err |
| 33 | + } |
| 34 | + return f.Body, nil |
| 35 | +} |
| 36 | + |
| 37 | +// CacheEntry contains the contents and TTL (time-to-live) for an item |
| 38 | +// to be added to the cache via [GetOrSet] or [GetOrSetContents]. |
| 39 | +type CacheEntry struct { |
| 40 | + // The contents of the cached object. |
| 41 | + Body io.Reader |
| 42 | + |
| 43 | + // The time-to-live for the cached object. |
| 44 | + TTL time.Duration |
| 45 | +} |
| 46 | + |
| 47 | +// GetOrSet retrieves the object stored in the cache for the given key |
| 48 | +// if it exists, or inserts and returns the contents by running the |
| 49 | +// provided setFn function. |
| 50 | +// |
| 51 | +// The setFn function is only run when no value is present for the key, |
| 52 | +// and no other client is in the process of setting it. The function |
| 53 | +// should return a populated [CacheEntry] or an error. |
| 54 | +// |
| 55 | +// If the setFn function returns an error, nothing will be saved to the |
| 56 | +// cache and the error will be returned from the GetOrSet function. |
| 57 | +// Other concurrent readers will also see an error while reading. |
| 58 | +// |
| 59 | +// The returned [io.ReadCloser] must be closed by the caller when |
| 60 | +// finished. |
| 61 | +func GetOrSet(key []byte, setFn func() (CacheEntry, error)) (io.ReadCloser, error) { |
| 62 | + tx, err := core.NewTransaction(key, core.LookupOptions{}) |
| 63 | + if err != nil { |
| 64 | + return nil, err |
| 65 | + } |
| 66 | + defer tx.Close() |
| 67 | + |
| 68 | + if tx.MustInsertOrUpdate() { |
| 69 | + e, err := setFn() |
| 70 | + if err != nil { |
| 71 | + return nil, err |
| 72 | + } |
| 73 | + |
| 74 | + w, f, err := tx.InsertAndStreamBack(core.WriteOptions{ |
| 75 | + TTL: e.TTL, |
| 76 | + SurrogateKeys: []string{ |
| 77 | + SurrogateKeyForCacheKey(key, PurgeScopePOP), |
| 78 | + SurrogateKeyForCacheKey(key, PurgeScopeGlobal), |
| 79 | + }, |
| 80 | + }) |
| 81 | + if err != nil { |
| 82 | + return nil, err |
| 83 | + } |
| 84 | + defer w.Close() |
| 85 | + |
| 86 | + if _, err := io.Copy(w, e.Body); err != nil { |
| 87 | + w.Abandon() |
| 88 | + return nil, err |
| 89 | + } |
| 90 | + |
| 91 | + if err := w.Close(); err != nil { |
| 92 | + w.Abandon() |
| 93 | + return nil, err |
| 94 | + } |
| 95 | + |
| 96 | + return f.Body, nil |
| 97 | + } |
| 98 | + |
| 99 | + f, err := tx.Found() |
| 100 | + if err != nil { |
| 101 | + return nil, err |
| 102 | + } |
| 103 | + |
| 104 | + return f.Body, nil |
| 105 | +} |
| 106 | + |
| 107 | +// GetOrSetEntry retrieves the object stored in the cache for the given |
| 108 | +// key if it exists, or inserts and returns the contents provided in the |
| 109 | +// [CacheEntry]. |
| 110 | +// |
| 111 | +// The cache entry is only inserted when no value is present for the |
| 112 | +// key, and no other client is in the process of setting it. |
| 113 | +// |
| 114 | +// If the cache entry body content is costly to compute, consider using |
| 115 | +// [GetOrSet] instead to avoid creating its [io.Reader] in the case |
| 116 | +// where the value is already present. |
| 117 | +// |
| 118 | +// The returned [io.ReadCloser] must be closed by the caller when |
| 119 | +// finished. |
| 120 | +func GetOrSetEntry(key []byte, entry CacheEntry) (io.ReadCloser, error) { |
| 121 | + return GetOrSet(key, func() (CacheEntry, error) { |
| 122 | + return entry, nil |
| 123 | + }) |
| 124 | +} |
| 125 | + |
| 126 | +// PurgeScope controls the scope of a purge operation. It is used in |
| 127 | +// the [PurgeOptions] struct. |
| 128 | +type PurgeScope uint32 |
| 129 | + |
| 130 | +const ( |
| 131 | + // PurgeScopePOP purges the entry only from the local POP cache. |
| 132 | + PurgeScopePOP PurgeScope = iota |
| 133 | + // PurgeScopeGlobal purges the entry from all POP caches. |
| 134 | + PurgeScopeGlobal |
| 135 | +) |
| 136 | + |
| 137 | +// PurgeOptions controls the behavior of the [Purge] function. |
| 138 | +type PurgeOptions struct { |
| 139 | + Scope PurgeScope |
| 140 | +} |
| 141 | + |
| 142 | +// Purge removes the entry associated with the given cache key, if one |
| 143 | +// exists. |
| 144 | +// |
| 145 | +// The scope of the purge can be controlled with the PurgeOptions. |
| 146 | +// |
| 147 | +// Purges are handled asynchronously, and the cached object may persist |
| 148 | +// in cache for a short time (~150ms or less) after this function |
| 149 | +// returns. |
| 150 | +func Purge(key []byte, opts PurgeOptions) error { |
| 151 | + sk := SurrogateKeyForCacheKey(key, opts.Scope) |
| 152 | + return purge.PurgeSurrogateKey(sk, purge.PurgeOptions{}) |
| 153 | +} |
| 154 | + |
| 155 | +// SurrogateKeyForCacheKey creates a surrogate key for the given cache |
| 156 | +// key and purge scope that is compatible with the Simple Cache API. |
| 157 | +// Each cache entry for the Simple Cache API is configured with |
| 158 | +// surrogate keys from this function. |
| 159 | +// |
| 160 | +// This function is provided as a convenience for implementors wishing |
| 161 | +// to add a Simple Cache-compatible surrogate key manually via the Core |
| 162 | +// Cache API ([github.com/fastly/compute-sdk-go/cache/core]) for |
| 163 | +// interoperability with [Purge]. |
| 164 | +func SurrogateKeyForCacheKey(cacheKey []byte, scope PurgeScope) string { |
| 165 | + // The values are SHA-256 digests of the cache key (plus the local POP |
| 166 | + // for the local surrogate key), converted to uppercase hexadecimal. |
| 167 | + // This scheme must be kept consistent across all compute SDKs. |
| 168 | + h := sha256.New() |
| 169 | + h.Write(cacheKey) |
| 170 | + if scope == PurgeScopePOP { |
| 171 | + h.Write([]byte(os.Getenv("FASTLY_POP"))) |
| 172 | + } |
| 173 | + |
| 174 | + return strings.ToUpper(hex.EncodeToString(h.Sum(nil))) |
| 175 | +} |
0 commit comments