#include <core.h>

Public Member Functions
TransactionUpdateBuilder	vary_by (std::vector< std::string > headers) &&
TransactionUpdateBuilder	age (std::chrono::nanoseconds age) &&
TransactionUpdateBuilder	deliver_node_max_age (std::chrono::nanoseconds duration) &&
	Sets the maximum time the cached item may live on a deliver node in a POP.
TransactionUpdateBuilder	stale_while_revalidate (std::chrono::nanoseconds duration) &&
TransactionUpdateBuilder	surrogate_keys (std::vector< std::string > keys) &&
TransactionUpdateBuilder	user_metadata (std::vector< std::uint8_t > metadata) &&
	Sets the user-defined metadata to associate with the cached item.
TransactionUpdateBuilder	on_behalf_of (std::string service) &&
tl::expected< void, CacheError >	execute () &&

Friends
class	Transaction

Detailed Description

A builder-style API for configuring a transactional cache update.

This builder is used to update an existing cached item's metadata, such as its age, without changing the object itself. All builder methods consume the builder and return it for method chaining.

Member Function Documentation

◆ age()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::age ( std::chrono::nanoseconds age ) &&

Sets the updated age of the cached item, to be used in freshness calculations.

The updated age is 0 by default.

◆ deliver_node_max_age()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::deliver_node_max_age ( std::chrono::nanoseconds duration ) &&

Sets the maximum time the cached item may live on a deliver node in a POP.

◆ execute()

tl::expected< void, CacheError > fastly::cache::core::TransactionUpdateBuilder::execute ( ) &&

Perform the update of the cache item's metadata.

This consumes the builder and executes the update operation.

◆ on_behalf_of()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::on_behalf_of ( std::string service ) &&

Perform this update 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.

◆ stale_while_revalidate()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::stale_while_revalidate ( std::chrono::nanoseconds duration ) &&

Sets the stale-while-revalidate period for the cached item, which is the time for which the item can be safely used despite being considered stale.

Having a stale-while-revalidate period provides a signal that the cache should be updated (or its contents otherwise revalidated for freshness) asynchronously, while the stale cached item continues to be used, rather than blocking on updating the cached item. The methods Found::is_usable and Found::is_stale can be used to determine the current state of a found item.

The stale-while-revalidate period is 0 by default.

◆ surrogate_keys()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::surrogate_keys ( std::vector< std::string > keys ) &&

Sets the surrogate keys that can be used for purging this cached item.

Surrogate key purges are the only means to purge specific items from the cache. At least one surrogate key must be set in order to remove an item without performing a purge-all, waiting for the item’s TTL to elapse, or overwriting the item with crate::cache::core::insert().

Surrogate keys must contain only printable ASCII characters (those between 0x21 and 0x7E, inclusive). Any invalid keys will be ignored.

See the Fastly surrogate keys guide for details.

◆ user_metadata()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::user_metadata ( std::vector< std::uint8_t > metadata ) &&

Sets the user-defined metadata to associate with the cached item.

◆ vary_by()

TransactionUpdateBuilder fastly::cache::core::TransactionUpdateBuilder::vary_by ( std::vector< std::string > headers ) &&

Sets the list of headers that must match when looking up this cached item.

The header values must be provided by calling TransactionLookupBuilder::header() or TransactionLookupBuilder::header_values(). The header values may be a subset or superset of the header names supplied here.

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.

◆ Transaction

friend class Transaction

friend

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

include/fastly/cache/core.h

Public Member Functions

Friends