Skip to main content
Version: 3.13.0

CoreCache.insert

Performs a non-transactional insertion into the cache, returning a FastlyBody instance for providing the cached object itself. For the insertion to complete successfully, the object must be written into the returned FastlyBody instance, and then FastlyBody.protoype.close must be called. If FastlyBody.prototype.close does not get called, the insertion is considered incomplete, and any concurrent lookups that may be reading from the object as it is streamed into the cache may encounter a streaming error.

Note: Like CoreCache.lookup(), CoreCache.insert() may race with concurrent lookups or insertions, and will unconditionally overwrite existing cached items rather than allowing for revalidation of an existing object. The transactional equivalent of this function is TransactionCacheEntry.insert(), which may only be called following a CoreCache.transactionLookup() call and the returned CacheEntry when has a state where CacheState.mustInsertOrUpdate() returns true.

Syntax​

insert(key, options)

Parameters​

  • key : string
    • A cache key which is a string with a length of up to 8,135 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.
  • options : object
    • headers : HeadersInit optional
      • The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via the vary property within TransactionInsertOptions.
      • A lookup will succeed when there is at least one cached item that matches lookup’s key, and all of the lookup’s headers included in the cache items’ vary list match the corresponding headers in that cached item.
      • A typical example is a cached HTTP response, where the request had an "Accept-Encoding" header. In that case, the origin server may or may not decide on a given encoding, and whether that same response is suitable for a request with a different (or missing) Accept-Encoding header is determined by whether Accept-Encoding is listed in Vary header in the origin’s response.
      • Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the HTTP Vary header.
    • maxAge : number optional
      • Sets the “time to live” for the cache item in milliseconds: The time for which the item will be considered fresh.
    • vary : array optional
      • Sets the list of headers that must match when looking up this cached item.
    • initialAge : number optional
      • Sets the initial age of the cached item, in milliseconds, to be used in freshness calculations.
      • The initial age is 0 by default.
    • staleWhileRevalidate : number optional
      • Sets the stale-while-revalidate period, in milliseconds for the cached item, which is the time for which the item can be safely used despite being considered stale.
      • Having a stale-while-revalidate period provides a signal that the cache should be updated (or its contents otherwise revalidated for freshness) asynchronously, while the stale cached item continues to be used, rather than blocking on updating the cached item.
      • The methods CacheState.protoype.usable and CacheState.protoype.stale can be used to determine the current state of an item.
      • The stale-while-revalidate period is 0 by default.
    • surrogateKeys : array optional
      • Sets the surrogate keys that can be used for purging this cached item.
      • Surrogate key purges are the only means to purge specific items from the cache. At least one surrogate key must be set in order to remove an item without performing a purge-all, waiting for the item’s TTL to elapse, or overwriting the item with insert().
      • Surrogate keys must contain only printable ASCII characters (those between 0x21 and 0x7E, inclusive). Any invalid keys will be ignored.
      • See the Fastly surrogate keys guide for details.
    • length : number optional
      • Sets the size of the cached item, in bytes, when known prior to actually providing the bytes.
      • It is preferable to provide a length, if possible.
      • Clients that begin streaming the item’s contents before it is completely provided will see the promised length which allows them to, for example, use content-length instead of transfer-encoding: chunked if the item is used as the body of a Request or Response.
    • userMetadata : ArrayBufferView | ArrayBuffer | URLSearchParams | string optional
      • Sets the user-defined metadata to associate with the cached item.
    • sensitive : boolean optional

Return value​

Returns a FastlyBody.

Exceptions​

  • If the provided key:
    • Cannot be coerced to a string
    • Is an empty string
    • Is longer than 8135 characters