Struct fastly::cache::core::TransactionInsertBuilder
source · pub struct TransactionInsertBuilder { /* private fields */ }
Expand description
A builder-style API for configuring a transactional cache insertion.
Implementations§
source§impl TransactionInsertBuilder
impl TransactionInsertBuilder
sourcepub fn vary_by<'a>(
self,
headers: impl IntoIterator<Item = &'a HeaderName>
) -> Self
pub fn vary_by<'a>( self, headers: impl IntoIterator<Item = &'a HeaderName> ) -> Self
Sets the list of headers that must match when looking up this cached item.
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. 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.
sourcepub fn initial_age(self, age: Duration) -> Self
pub fn initial_age(self, age: Duration) -> Self
Sets the initial age of the cached item, to be used in freshness calculations.
The initial age is Duration::ZERO
by default.
sourcepub fn stale_while_revalidate(self, duration: Duration) -> Self
pub fn stale_while_revalidate(self, duration: Duration) -> Self
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 Duration::ZERO
by default.
sourcepub fn surrogate_keys<'a>(self, keys: impl IntoIterator<Item = &'a str>) -> Self
pub fn surrogate_keys<'a>(self, keys: impl IntoIterator<Item = &'a str>) -> Self
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 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.
sourcepub fn known_length(self, length: u64) -> Self
pub fn known_length(self, length: u64) -> Self
Sets the size of the cached item, in bytes, when known prior to actually providing the bytes.
It is preferable to provide a length, if possible. Clients that begin streaming the item’s
contents before it is completely provided will see the promised length which allows them to,
for example, use content-length
instead of transfer-encoding: chunked
if the item is
used as the body of a Request
or Response
.
sourcepub fn user_metadata(self, user_metadata: Bytes) -> Self
pub fn user_metadata(self, user_metadata: Bytes) -> Self
Sets the user-defined metadata to associate with the cached item.
sourcepub fn sensitive_data(self, is_sensitive_data: bool) -> Self
pub fn sensitive_data(self, is_sensitive_data: bool) -> Self
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.
sourcepub fn execute(self) -> Result<StreamingBody, CacheError>
pub fn execute(self) -> Result<StreamingBody, CacheError>
Begin the insertion, returning a StreamingBody
for providing the cached object itself.
For the insertion to complete successfully, the object must be written into the StreamingBody
,
and then StreamingBody::finish
must be called. If the StreamingBody
is dropped before calling
StreamingBody::finish
, the insertion is considered incomplete, and any concurrent lookups that
may be reading from the object as it is streamed into the cache may encounter a streaming error.
sourcepub fn execute_and_stream_back(
self
) -> Result<(StreamingBody, Found), CacheError>
pub fn execute_and_stream_back( self ) -> Result<(StreamingBody, Found), CacheError>
Begin the insertion, and provide a Found
object that can be used to stream out of the
newly-inserted object.
For the insertion to complete successfully, the object must be written into the StreamingBody
,
and then StreamingBody::finish
must be called. If the StreamingBody
is dropped before calling
StreamingBody::finish
, the insertion is considered incomplete, and any concurrent lookups that
may be reading from the object as it is streamed into the cache may encounter a streaming error.
The returned Found
object allows the client inserting a cache item to efficiently read
back the contents of that item, avoiding the need to buffer contents for copying to multiple
destinations. This pattern is commonly required when caching an item that also must be
provided to, e.g., the client response.