Resource

entry

The outcome of a cache lookup (either bare or as part of a cache transaction)

resource entry;

F transaction-insert

transaction-insert: func(options: write-options) -> result<body, error>;

Inserts an object into the cache with the given metadata.

Can only be used in if the cache handle state includes the must-insert-or-update flag.

The returned handle is to a streaming body that is used for writing the object into the cache.

F transaction-insert-and-stream-back

transaction-insert-and-stream-back: func(options: write-options) -> result<tuple<body, entry>, error>;

Inserts an object into the cache with the given metadata, and return a readable stream of the bytes as they are stored.

This helps avoid the “slow reader” problem on a teed stream, for example when a program wishes to store a backend request in the cache while simultaneously streaming to a client in an HTTP response.

The returned body handle is to a streaming body that is used for writing the object into the cache. The returned cache handle provides a separate transaction for reading out the newly cached object to send elsewhere.

F transaction-update

transaction-update: func(options: write-options) -> result<_, error>;

Update the metadata of an object in the cache without changing its data.

Can only be used in if the cache handle state includes both of the flags:

found
must-insert-or-update

F get-state

get-state: func() -> result<lookup-state, error>;

Get the state of a cache lookup, waiting for the lookup to complete if necessary.

Note that FOUND == USABLE, and means "usable" (fresh or stale-while-revalidate). Some SDKs were released that checked only FOUND to infer "usable"; we preserve the equivalence for backwards compatibility.

F get-user-metadata

get-user-metadata: func(max-len: u64) -> result<option<list<u8>>, error>;

Gets the user metadata of the found object, returning ok(none) if no object was found.

F get-body

get-body: func(options: get-body-options) -> result<body, error>;

Gets a range of the found object body, returning ok(none) if there was no found object.

The returned body must be closed before calling this function again on the same entry.

Note: until the CacheD protocol is adjusted to fully support this functionality, the body of objects that are past the stale-while-revalidate period will not be available, even when other metadata is.

F get-length

get-length: func() -> result<option<object-length>, error>;

Gets the content length of the found object, returning ok(none) if there was no found object, or no content length was provided.

F get-max-age-ns

get-max-age-ns: func() -> result<option<duration-ns>, error>;

Gets the configured max age of the found object, returning ok(none) if there was no found object.

F get-stale-while-revalidate-ns

get-stale-while-revalidate-ns: func() -> result<option<duration-ns>, error>;

Gets the configured stale-while-revalidate period of the found object, returning ok(none) if there was no found object.

F get-age-ns

get-age-ns: func() -> result<option<duration-ns>, error>;

Gets the age of the found object, returning ok(none) if there was no found object.

F get-hits

get-hits: func() -> result<option<cache-hit-count>, error>;

Gets the number of cache hits for the found object, returning ok(none) if there was no found object.

F transaction-cancel

transaction-cancel: func() -> result<_, error>;

Cancel an obligation to provide an object to the cache.

Useful if there is an error before streaming is possible, for example if a backend is unreachable.

F step

step: func() -> option<pollable>;

Returns a pollable representing the next step of work for this entry. The pollable can be used to wait until this entry is unblocked.

The entry may require steps to complete. When this returns none, the entry is ready.

F lookup

lookup: func(key: list<u8>, options: lookup-options) -> result<entry, error>;

Performs a non-request-collapsing cache lookup.

Returns a result without waiting for any request collapsing that may be ongoing.

F transaction-lookup

transaction-lookup: func(key: list<u8>, options: lookup-options) -> result<entry, error>;

The entrypoint to the request-collapsing cache transaction API.

This operation always participates in request collapsing and may return stale objects. To bypass request collapsing, use entry.lookup or insert instead.

F transaction-lookup-async

transaction-lookup-async: func(key: list<u8>, options: lookup-options) -> result<pending-entry, error>;

The entrypoint to the request-collapsing cache transaction API, returning instead of waiting on busy.

This operation always participates in request collapsing and may return stale objects. To bypass request collapsing, use entry.lookup or insert instead.