Found

The current age of the cached item.

This can be greater than max age when the item is stale.

Determines the number of cache hits to this cached item.

Note: this hit count only reflects the view of the server that supplied the cached item. Due to clustering, this count may vary between potentially many servers within the data center where the item is cached. See the clustering documentation for details, though note that the exact caching architecture of Compute is different from VCL services.

Determines whether the cached item is stale.

A cached item is stale if its age is greater than its max-age period.

Determines whether the cached item is usable.

A cached item is usable if its age is less than the sum of the max-age and stale-while-revalidate periods.

The size in bytes of the cached item, if known.

The length of the cached item may be unknown if the item is currently being streamed into the cache without a fixed length.

How long the cached item is/was considered fresh, starting from the start of the cached item's lifetime.

Note that this is the maximum possible "fresh" age, not the freshness time remaining; see remaining_ttl for that.

Returns the remaining TTL: how long this cached item has left before it is considered stale. Zero if the cached item is stale.

Note: this reports the remaining freshness period; max age reports the original / intitial TTL.

Retrieves the entire cached item as a Body that can be read in a streaming fashion.

Only one stream can be active at a time for a given Found. The stream must be fully consumed (read) before a new stream can be created from the same Found. Err(CacheError::InvalidOperation) will be returned if a stream is already active for this Found. This restriction may be lifted in future releases.

Retrieves a range of bytes from the cached item as a Body that can be read in a streaming fashion.

from and to will determine which bytes are returned:

• If from is provided and to is not provided, the stream will begin at the from byte and continue to the end of the body.
• If from and to are both provided, only the range from..=to will be provided. Note, both ends are inclusive.
• If to is provided but from is not provided, the last to bytes of the body will be provided.

Inherently invalid ranges

If to is strictly before from, this call returns a error immediately. (to == from is acceptable - the bounds are inclusive, so this addresses a single byte.)

Known size

The size of a cached item is known if it has completed streaming (StreamingBody::finish) or if the expected length was provided at insert time (TransactionInsertBuilder::known_length and similar).

If the size of the cached item is known, the range is respected only if the range is valid (to is before from, and both ranges are less than or equal to the size of the item). Otherwise, no error is returned, and the entire body is returned instead.

Unknown size

The size of a cached item may not be known (if known_length was not provided and the body is still being streamed). If the size of the cached item is unknown, by default, the range is ignored, and the entire cached item is returned.

This behavior can be overridden by calling TransactionLookupBuilder::always_use_requested_range. If provided, this call will block until the start of the interval is found, then begin streaming content. The Body will generate a read error if the end of the range is not reached.

Re-reading body

Only one stream can be active at a time for a given Found. The stream must be fully consumed (read) before a new stream can be created from the same Found. Err(CacheError::InvalidOperation) will be returned if a stream is already active for this Found. This restriction may be lifted in future releases.