ReplaceBuilder

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.

Begin the replace, returning a Replace for reading the object to be replaced (if it exists) which is also used to provide the new replacement object.

A Replace gives access to the existing object, if one is stored, that may be used to construct the replacement object. Use Replace::execute() to get a StreamingBody to write the replacement object into. The existing object cannot be accessed after calling Replace::execute().

For the replace 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 replacement 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.

Sets a single-value header for looking up an existing object to replace, 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.

Sets a multi-value header for looking up an existing object to replace, 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.

Sets the strategy for performing the replace.

See ReplaceStrategy for details.