--- title: TransactionLookupBuilder summary: A builder-style API for configuring a transactional lookup. url: https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.TransactionLookupBuilder/ --- **Kind:** Struct **Module:** [core](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/) **Package:** fastly 0.13.1 **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#961 ```rust pub struct TransactionLookupBuilder { /* private fields */ } ``` A builder-style API for configuring a transactional lookup. ## Methods ### always_use_requested_range **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#1015 ```rust fn always_use_requested_range(self) -> Self ``` 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. **Parameters** - `self`: `Self` **Returns** `Self` ### execute **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#1043 ```rust fn execute(self) -> Result ``` Perform the lookup, entering a [`Transaction`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Transaction/). If the lookup hits an object being provided by another client, this call will block until that client provides the object's metadata or cancels. If a timeout was set via [`timeout()`](`TransactionLookupBuilder::timeout()`), this call returns [`CacheError::Timeout`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/enum.CacheError/) if that client does not provide the object's metadata within the timeout. Accessors like [`Transaction::found()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Transaction/#method-found) can be used to determine the outcome of the lookup. **Parameters** - `self`: `Self` **Returns** `Result` ### execute_async **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#1074 ```rust fn execute_async(self) -> Result ``` Perform the lookup, returning a [`PendingTransaction`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.PendingTransaction/). If the lookup hits an object being provided by another client, this call will not block. Instead, the returned [`PendingTransaction`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.PendingTransaction/) can be used to wait for the request collapsed lookup to complete. See the documentation of [`PendingTransaction`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.PendingTransaction/) for more details. **Parameters** - `self`: `Self` **Returns** `Result` ### header **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#991 ```rust fn header(self, name: impl ToHeaderName, value: impl ToHeaderValue) -> Self ``` 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](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.5), 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`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.InsertBuilder/#method-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](https://www.fastly.com/blog/best-practices-using-vary-header) 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. **Parameters** - `self`: `Self` - `name`: `impl ToHeaderName` - `value`: `impl ToHeaderValue` **Returns** `Self` ### header_values **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#975 ```rust fn header_values<'a>(self, name: impl ToHeaderName, values: impl IntoIterator) -> Self ``` 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](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.5), 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`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.InsertBuilder/#method-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](https://www.fastly.com/blog/best-practices-using-vary-header) 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. **Parameters** - `self`: `Self` - `name`: `impl ToHeaderName` - `values`: `impl IntoIterator` **Returns** `Self` ### on_behalf_of **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#1009 ```rust fn on_behalf_of(self, service: impl ToString) -> Self ``` 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. **Parameters** - `self`: `Self` - `service`: `impl ToString` **Returns** `Self` ### timeout **Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core.rs#1028 ```rust fn timeout(self, timeout: Duration) -> Self ``` Sets a timeout for the resulting lookup when it blocks under request collapsing. If this lookup blocks waiting for another caller to provide the item, and that caller does not do so within `timeout`, both [`execute()`](`TransactionLookupBuilder::execute()`) and [`PendingTransaction::wait()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.PendingTransaction/#method-wait) return [`CacheError::Timeout`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/enum.CacheError/). This is useful when a slow or wedged caller would otherwise block this lookup. [`PendingTransaction::wait_for()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.PendingTransaction/#method-wait_for) overrides this timeout for an individual wait. **Parameters** - `self`: `Self` - `timeout`: `Duration` **Returns** `Self` ## Auto trait implementations - `Freeze` - `RefUnwindSafe` - `Send` - `Sync` - `Unpin` - `UnsafeUnpin` - `UnwindSafe` ## Blanket implementations - `Any` - `Borrow` - `BorrowMut` - `Downcast` - `DowncastSync` - `ErasedDestructor` - `From` - `Into` - `IntoEither` - `Same` - `TryFrom` - `TryInto`