fastly::cache::core::LookupBuilder Class Reference

#include <core.h>

Public Member Functions
LookupBuilder	header_values (std::string_view name, std::span< const http::HeaderValue > values) &&
LookupBuilder	header (std::string_view name, const http::HeaderValue &value) &&
LookupBuilder	on_behalf_of (std::string service) &&
LookupBuilder	always_use_requested_range () &&
tl::expected< std::optional< Found >, CacheError >	execute () &&

Friends
LookupBuilder	lookup (std::span< const std::uint8_t > key)

Detailed Description

A builder-style API for configuring a non-transactional cache lookup.

In contrast to Transaction::lookup(), a non-transactional lookup will not attempt to coordinate with any concurrent cache lookups. If two instances of the service perform a lookup at the same time for the same cache key, and the item is not yet cached, they will both get Ok(None) from the eventual lookup execution.

To resolve races between concurrent lookups, use Transaction::lookup() instead.

Member Function Documentation

always_use_requested_range()

LookupBuilder fastly::cache::core::LookupBuilder::always_use_requested_range

(

)

&&

Respect the range in to_stream_with_range even when the body length is not yet known.

When a cache item is Found, the length of the cached item may or may not be known:

• the item may be fully cached;
• the item may be streaming in, but have a known length; or
• the item may be streaming in progressively, without a known length.

By default (legacy behavior), if a range is specified but the length is not known, the contents of the entire item will be provided instead of the requested range.

always_use_requested_range indicates any cached item returned by this lookup should provide only the requested range, regardless of whether the length is known. An invalid range will eventually return a read error, possibly after providing some data.

NOTE: In the future, the always_use_requested_range behavior will be the default, and this method will be removed.

execute()

tl::expected< std::optional< Found >, CacheError > fastly::cache::core::LookupBuilder::execute

(

)

&&

Perform the lookup, returning a Found object if a usable cached item was found.

A cached item is usable if its age is less than the sum of its max_age and its stale-while-revalidate period. Items beyond that age are unusably stale.

header()

LookupBuilder fastly::cache::core::LookupBuilder::header	(	std::string_view	name,
		const http::HeaderValue &	value ) &&

Sets a single-value header for this lookup, discarding any previous values associated with the header name. Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the HTTP Vary header, but the APIs in this module are not suitable for HTTP caching out-of-the-box. Future SDK releases will contain an HTTP Cache API.

The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via e.g. crate::cache::core::InsertBuilder::vary_by. A lookup will succeed when there is at least one cached item that matches lookup’s cache key, and all of the lookup’s headers included in the cache items’ vary_by 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.

header_values()

LookupBuilder fastly::cache::core::LookupBuilder::header_values	(	std::string_view	name,
		std::span< const http::HeaderValue >	values ) &&

Sets a multi-value header for this lookup, discarding any previous values associated with the header name.

Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the HTTP Vary header, but the APIs in this module are not suitable for HTTP caching out-of-the-box. Future SDK releases will contain an HTTP Cache API.

The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via e.g. crate::cache::core::InsertBuilder::vary_by. A lookup will succeed when there is at least one cached item that matches lookup’s cache key, and all of the lookup’s headers included in the cache items’ vary_by 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.

on_behalf_of()

LookupBuilder fastly::cache::core::LookupBuilder::on_behalf_of

(

std::string

service

)

&&

Perform this lookup on behalf of another service, using its data store.

Internal / Privileged This operation is privileged, and attempts to use this functionality without proper privileges will cause errors. If you are interested in having two or more of your services share the same cache, please talk to your Fastly account representative. While we have no plans to offer this ability widely – this capability is only currently allowed for Fastly-internal services – we may revisit this decision given sufficient customer input.

Friends And Related Symbol Documentation

lookup

LookupBuilder lookup ( std::span< const std::uint8_t > key )

friend

Returns a LookupBuilder that will perform a non-transactional cache lookup.

In contrast to Transaction::lookup(), a non-transactional lookup will not attempt to coordinate with any concurrent cache lookups. If two instances of the service perform a lookup at the same time for the same cache key, and the item is not yet cached, they will both get nothing from the eventual lookup execution. Without further coordination, they may both end up performing the work needed to insert() the item (which usually involves origin requests and/or computation) and racing with each other to insert.

To resolve such races between concurrent lookups, use Transaction::lookup() instead.

---

The documentation for this class was generated from the following file:

• include/fastly/cache/core.h