Resource

entry

An HTTP Cache transaction.

resource entry;

F transaction-insert

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

Inserts a response into the cache with the given options, returning a streaming body handle that is ready for writing or appending.

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

The response is consumed.

F transaction-insert-and-stream-back

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

Inserts a response into the cache with the given options, and return a fresh cache handle that can be used to retrieve and stream the response while it's being inserted.

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 response is consumed.

F transaction-update

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

Updates freshness lifetime, response headers, and caching settings without updating the response body.

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

found
must-insert-or-update

The response is consumed.

F transaction-update-and-return-fresh

transaction-update-and-return-fresh: func(resp-handle: response, options: write-options) -> result<entry, error>;

Updates freshness lifetime, response headers, and caching settings without updating the response body, and return a fresh cache handle that can be used to retrieve and stream the stored response.

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

found
must-insert-or-update

The response is consumed.

F transaction-choose-stale

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

Fulfill an obligation to provide a response to the cache by selecting a stale-if-error response.

A guest that is obligated to insert/update the cache may not be able to produce an acceptable response (e.g. unreachable backend, 5xx response). If the cache contains a response in the stale-if-error period, the guest may prefer to use that response rather than returning an error. If so, they can call transaction-choose-stale, after which the cache handle will reflect the stale response (via get-found-response, get-state, etc).

transaction-choose-stale is an alternative to transaction-update-and-return-fresh or transaction-insert-and-stream-back. Like those methods, it completes a request collapse, providing the stale response to all collapsed transactions; and, after calling transaction-choose-stale, the cache handle provides the (stale) response to send to the client.

However, transaction-choose-stale does not change the cached item. The next lookup will again collapse and/or get an obligation to revalidate.

F transaction-record-not-cacheable

transaction-record-not-cacheable: func(options: write-options) -> result<_, error>;

Fulfill an obligation to provide a response to the cache by disabling request collapsing and response caching for this cache entry.

In Varnish terms, this function stores a hit-for-pass object.

Only the max age and, optionally, the vary rule are read from the options argument.

F get-suggested-backend-request

get-suggested-backend-request: func() -> result<request, error>;

Prepares a suggested request to make to a backend to satisfy the looked-up request.

If there is a stored, stale response, this suggested request may be for revalidation. If the looked-up request is ranged, the suggested request will be unranged in order to try caching the entire response.

F get-suggested-write-options

get-suggested-write-options: func(response: borrow<response>) -> result<suggested-write-options, error>;

Prepares a suggested set of cache write options for a given request and response pair.

The response is not consumed.

F prepare-response-for-storage

prepare-response-for-storage: func(response: borrow<response>) -> result<tuple<storage-action, response>, error>;

Adjusts a response into the appropriate form for storage and provides a storage action recommendation.

For example, if the looked-up request contains conditional headers, this function will interpret a 304 Not Modified response for revalidation by updating headers.

In addition to the updated response, this function returns the recommended storage action.

F get-found-response

get-found-response: func(transform-for-client: u32) -> result<option<response-with-body>, error>;

Retrieves a stored response from the cache, returning ok(none) if there was no response found.

If transform-for-client is set, the response will be adjusted according to the looked-up request. For example, a response retrieved for a range request may be transformed into a 206 Partial Content response with an appropriate content-range header.

F get-state

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

Gets the state of a cache transaction.

Primarily useful after performing the lookup to determine what subsequent operations are possible and whether any insertion or update obligations exist.

F get-length

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

Gets the length of the found response, returning ok(none) if there was no response found or no 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 response in nanoseconds, returning ok(none) if there was no response found.

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 response in nanoseconds, returning ok(none) if there was no response found.

F get-stale-if-error-ns

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

Gets the configured stale-if-error period of the found response in nanoseconds, returning ok(none) if there was no response found.

F get-age-ns

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

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

F get-hits

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

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

This figure only reflects hits for a stored response in a particular cache server or cluster, not the entire Fastly network.

F get-sensitive-data

get-sensitive-data: func() -> result<option<bool>, error>;

Gets whether a found response is marked as containing sensitive data, returning ok(none) if there was no response found.

F get-surrogate-keys

get-surrogate-keys: func(max-len: u64) -> result<option<string>, error>;

Gets the surrogate keys of the found response, returning ok(none) if there was no response found.

The output is a list of surrogate keys separated by spaces.

If the full list requires more than max-len bytes, an error.buffer-len error is returned containing the required size.

F get-vary-rule

get-vary-rule: func(max-len: u64) -> result<option<string>, error>;

Gets the vary rule of the found response, returning ok(none) if there was no response found.

The output is a list of header names separated by spaces.

If the full list requires more than max-len bytes, an error.buffer-len error is returned containing the required size.

F transaction-abandon

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

Abandons an obligation to provide a response to the cache.

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

If there are other requests collapsed on this transaction, one of those other requests will be awoken and given the obligation to provide a response. If subsequent requests are unlikely to yield cacheable responses, this may lead to undesired serialization of requests. Consider using transaction-record-not-cacheable to make lookups for this request bypass the cache.

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 transaction-lookup

transaction-lookup: func(req-handle: borrow<request>, options: lookup-options) -> result<entry, error>;

Performs a cache lookup based on the given request.

This operation always participates in request collapsing and may return an obligation to insert or update responses, and/or stale responses.

The request is not consumed.