#include <core.h>

Public Member Functions
tl::expected< http::StreamingBody, CacheError >	execute (std::chrono::nanoseconds max_age) &&
const std::optional< Found > &	existing_object () const
	The existing object, if one exists. The existing object may be stale.
Replace	header_values (std::string_view name, std::span< const http::HeaderValue > values) &&
Replace	header (std::string_view name, const http::HeaderValue &value) &&
Replace	vary_by (std::vector< std::string > headers) &&
	Sets the list of headers that must match when looking up this cached item.
Replace	initial_age (std::chrono::nanoseconds age) &&
Replace	stale_while_revalidate (std::chrono::nanoseconds duration) &&
Replace	surrogate_keys (std::vector< std::string > keys) &&
Replace	known_length (std::uint64_t length) &&
	Sets the known length of the cached item.
Replace	user_metadata (std::vector< std::uint8_t > metadata) &&
	Sets the user-defined metadata to associate with the cached item.
Replace	sensitive_data (bool is_sensitive) &&
Replace	deliver_node_max_age (std::chrono::nanoseconds duration) &&
	Sets the maximum time the cached item may live on a deliver node in a POP.

Friends
class	ReplaceBuilder

Detailed Description

An in-progress Replace operation.

This type is returned from ReplaceBuilder::begin().

Member Function Documentation

◆ deliver_node_max_age()

Replace fastly::cache::core::Replace::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< http::StreamingBody, CacheError > fastly::cache::core::Replace::execute ( std::chrono::nanoseconds max_age ) &&

Finish using the existing object and start writing a replacement object to the StreamingBody.

The required max_age argument is the "time to live" for the replacement cache item: the time for which the item will be considered fresh, starting from the start of its history (now, unless initial_age was provided).

◆ existing_object()

const std::optional< Found > & fastly::cache::core::Replace::existing_object ( ) const

inline

The existing object, if one exists. The existing object may be stale.

◆ header()

Replace fastly::cache::core::Replace::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()

Replace fastly::cache::core::Replace::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.

◆ initial_age()

Replace fastly::cache::core::Replace::initial_age ( std::chrono::nanoseconds age ) &&

Sets the initial age of the cached item, to be used in freshness calculations. The initial age is zero by default.

◆ known_length()

Replace fastly::cache::core::Replace::known_length ( std::uint64_t length ) &&

Sets the known length of the cached item.

◆ sensitive_data()

Replace fastly::cache::core::Replace::sensitive_data ( bool is_sensitive ) &&

Enable or disable PCI/HIPAA-compliant non-volatile caching.

By default, this is false.

See the Fastly PCI-Compliant Caching and Delivery documentation for details.

◆ stale_while_revalidate()

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

Sets the time for which a cached item can safely be used despite being considered stale.

◆ surrogate_keys()

Replace fastly::cache::core::Replace::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()

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

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

◆ vary_by()

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

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

◆ ReplaceBuilder

friend class ReplaceBuilder

friend

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

include/fastly/cache/core.h

Public Member Functions

Friends