--- title: Found summary: Represents a found cached item. This allows access to metadata and the cached body. url: https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/ --- **Kind:** Class **Module:** [core](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/) **Package:** compute-sdk-cpp 0.7.0 **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L534 Include `fastly/cache/core.h` to use this class. Represents a found cached item. This allows access to metadata and the cached body. A [`Found`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/) instance is returned from [`Transaction::found()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Transaction/#method-found) when the transaction has found a cached item during the lookup operation. ## Methods ### age **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L537 ```cpp std::chrono::nanoseconds fastly::cache::core::Found::age() const ``` The current age of the cached item. **Returns** `std::chrono::nanoseconds` ### hits **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L577 ```cpp uint64_t fastly::cache::core::Found::hits() const ``` 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](https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/clustering-in-vcl/) for details, though note that the exact caching architecture of Compute is different from VCL services. **Returns** `uint64_t` ### is_stale **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L560 ```cpp bool fastly::cache::core::Found::is_stale() const ``` Determines whether the cached item is stale. A cached item is stale if its age is greater than its max-age period. **Returns** `bool` ### is_usable **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L566 ```cpp bool fastly::cache::core::Found::is_usable() const ``` 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. **Returns** `bool` ### known_length **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L583 ```cpp std::optional fastly::cache::core::Found::known_length() const ``` 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. **Returns** `std::optional` ### max_age **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L544 ```cpp std::chrono::nanoseconds fastly::cache::core::Found::max_age() const ``` 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 age, not the freshness time remaining; see [`remaining_ttl()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/#method-remaining_ttl) for that. **Returns** `std::chrono::nanoseconds` ### remaining_ttl **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L551 ```cpp std::chrono::nanoseconds fastly::cache::core::Found::remaining_ttl() const ``` 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()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/#method-max_age) reports the maximum possible TTL. **Returns** `std::chrono::nanoseconds` ### stale_while_revalidate **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L555 ```cpp std::chrono::nanoseconds fastly::cache::core::Found::stale_while_revalidate() const ``` The time for which a cached item can safely be used despite being considered stale. **Returns** `std::chrono::nanoseconds` ### to_stream **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L596 ```cpp tl::expected fastly::cache::core::Found::to_stream() const ``` 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`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/). The stream must be fully consumed (read) before a new stream can be created from the same [`Found`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/). `CacheError::InvalidOperation` will be returned if a stream is already active for this [`Found`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/). This restriction may be lifted in future releases. **Returns** `tl::expected` ### to_stream_from_range **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L639 ```cpp tl::expected fastly::cache::core::Found::to_stream_from_range(std::optional from, std::optional to) const ``` 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 an 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 or if the expected length was provided at insert time ([`TransactionInsertBuilder::known_length`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.TransactionInsertBuilder/#method-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 after `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 overriden by calling [`TransactionLookupBuilder::always_use_requested_range`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.TransactionLookupBuilder/#method-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 exceeds the available data. **Parameters** - `from`: `std::optional` - `to`: `std::optional` **Returns** `tl::expected` ### user_metadata **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L586 ```cpp std::vector fastly::cache::core::Found::user_metadata() const ``` The user-controlled metadata associated with the cached item. **Returns** `std::vector`