Cache control

On this page

Advertising a result as reusable by the client.

constant CACHE_ETAG_KEY

source

pub const CACHE_ETAG_KEY: &str = “vgi.cache.etag”;

Description

Strong validator (opaque quoted string) for conditional revalidation.

constant CACHE_EXPIRES_KEY

source

pub const CACHE_EXPIRES_KEY: &str = “vgi.cache.expires”;

Description

Absolute RFC 3339 UTC freshness deadline.

constant CACHE_IF_MODIFIED_SINCE_KEY

source

pub const CACHE_IF_MODIFIED_SINCE_KEY: &str = “vgi.cache.if_modified_since”;

Description

The client’s stored Last-Modified, sent on a conditional revalidation request. Companion to [CACHE_IF_NONE_MATCH_KEY].

constant CACHE_IF_NONE_MATCH_KEY

source

pub const CACHE_IF_NONE_MATCH_KEY: &str = “vgi.cache.if_none_match”;

Description

The client’s stored ETag, sent on a conditional revalidation request. Surfaced to a producer via TableProducer::on_conditional_request (in the vgi worker crate).

constant CACHE_LAST_MODIFIED_KEY

source

pub const CACHE_LAST_MODIFIED_KEY: &str = “vgi.cache.last_modified”;

Description

Weaker RFC 3339 UTC validator; fallback when no ETag.

constant CACHE_NOT_MODIFIED_KEY

source

pub const CACHE_NOT_MODIFIED_KEY: &str = “vgi.cache.not_modified”;

Description

304-equivalent, set on a 0-row batch in reply to a conditional request.

constant CACHE_NO_STORE_KEY

source

pub const CACHE_NO_STORE_KEY: &str = “vgi.cache.no_store”;

Description

Explicit “never cache”; overrides any freshness key.

constant CACHE_PARTITION_SCOPE_KEY

source

pub const CACHE_PARTITION_SCOPE_KEY: &str = “vgi.cache.partition_scope”;

Description

Opt in to per-partition result caching (SINGLE_VALUE_PARTITIONS only).

constant CACHE_PER_VALUE_KEY

source

pub const CACHE_PER_VALUE_KEY: &str = “vgi.cache.per_value”;

Description

Opt in to per-VALUE memoization for an exchange-mode MAP (default OFF).

constant CACHE_REVALIDATABLE_KEY

source

pub const CACHE_REVALIDATABLE_KEY: &str = “vgi.cache.revalidatable”;

Description

The worker can check freshness cheaply without recomputing.

constant CACHE_SCOPE_CATALOG

source

pub const CACHE_SCOPE_CATALOG: &str = “catalog”;

Description

Reusable across transactions within the calling catalog identity (default).

constant CACHE_SCOPE_KEY

source

pub const CACHE_SCOPE_KEY: &str = “vgi.cache.scope”;

Description

Reuse scope: [CACHE_SCOPE_CATALOG] or [CACHE_SCOPE_TRANSACTION].

constant CACHE_SCOPE_TRANSACTION

source

pub const CACHE_SCOPE_TRANSACTION: &str = “transaction”;

Description

Reused only within the transaction that produced it.

constant CACHE_STALE_IF_ERROR_KEY

source

pub const CACHE_STALE_IF_ERROR_KEY: &str = “vgi.cache.stale_if_error”;

Description

Grace window (seconds) to serve stale if a revalidation RPC fails.

constant CACHE_STALE_WHILE_REVALIDATE_KEY

source

pub const CACHE_STALE_WHILE_REVALIDATE_KEY: &str = “vgi.cache.stale_while_revalidate”;

Description

Grace window (seconds) to serve stale while revalidating in the background.

constant CACHE_TTL_KEY

source

pub const CACHE_TTL_KEY: &str = “vgi.cache.ttl”;

Description

Freshness lifetime in whole seconds, relative to full-result receipt.

struct CacheControl

source

pub struct CacheControl {
  pub ttl_seconds: Option<i64>,
  pub expires: Option<String>,
  pub scope: String,
  pub no_store: bool,
  pub etag: Option<String>,
  pub last_modified: Option<String>,
  pub revalidatable: bool,
  pub stale_while_revalidate: Option<i64>,
  pub stale_if_error: Option<i64>,
  pub not_modified: bool,
  pub partition_scope: bool,
  pub per_value: bool,
}

Description

Cacheability advertised by a table function on its first result batch.

Presence of ttl or expires is what makes a result cacheable; no_store overrides any freshness key. scope defaults to [CACHE_SCOPE_CATALOG].

Build one with [CacheControl::ttl] / [CacheControl::no_store] / [CacheControl::default] plus the with_* setters, then render it with to_metadata.

Methods

method from_metadata

source

pub fn from_metadata(md: &HashMap<String, String>) -> Option<Self>

Read directives back off a batch’s vgi.cache.* metadata.

The inverse of [CacheControl::to_metadata], and the half a client needs: a worker states its caching policy on the first data batch, and the client decides what to do with the result on that basis.

Returns None when the map carries no vgi.cache.* key at all, which is the common case — a worker that says nothing is not asking for anything to be cached. A malformed value (a ttl that is not an integer, say) is ignored rather than fatal: cache directives are advice, and refusing to scan because of a bad hint would be the wrong trade.

method is_cacheable

source

pub fn is_cacheable(&self) -> bool

Whether this result may be stored at all.

no_store overrides everything; otherwise a freshness key (ttl or expires) is the opt-in. A worker that sets neither is not asking to be cached.

method no_store

source

pub fn no_store() -> Self

Never cache this result, whatever else is advertised.

method to_metadata

source

pub fn to_metadata(&self) -> HashMap<String, String>

Render to the vgi.cache.* batch-metadata map.

Booleans render as "1" and are omitted when false; unset optional fields are omitted entirely. scope is always emitted so the client never has to infer the default.

method ttl

source

pub fn ttl(seconds: i64) -> Self

Cacheable for seconds after the client receives the full result. Negative values clamp to 0 (immediately stale).

method with_etag

source

pub fn with_etag(mut self, etag: impl Into<String>) -> Self

Attach a strong validator for conditional revalidation.

method with_expires

source

pub fn with_expires(mut self, expires: impl Into<String>) -> Self

Absolute RFC 3339 UTC freshness deadline.

method with_last_modified

source

pub fn with_last_modified(mut self, last_modified: impl Into<String>) -> Self

Attach an RFC 3339 UTC Last-Modified validator.

method with_not_modified

source

pub fn with_not_modified(mut self) -> Self

Mark this a 304 reply: the client’s stored payload is still fresh. Emit it on a 0-row batch in answer to a conditional request.

method with_partition_scope

source

pub fn with_partition_scope(mut self) -> Self

Opt in to per-partition caching (see [CacheControl::partition_scope]). Only has an effect on a SINGLE_VALUE_PARTITIONS table function.

method with_per_value

source

pub fn with_per_value(mut self) -> Self

Opt in to per-VALUE memoization (see [CacheControl::per_value]). Only worth setting when one call to this function is more expensive than a cache probe plus a decode.

method with_revalidatable

source

pub fn with_revalidatable(mut self) -> Self

Declare that freshness can be rechecked without recomputing the result, so the client may send conditional requests instead of full scans.

method with_stale_if_error

source

pub fn with_stale_if_error(mut self, seconds: i64) -> Self

Serve stale for up to seconds when a revalidation RPC fails.

method with_stale_while_revalidate

source

pub fn with_stale_while_revalidate(mut self, seconds: i64) -> Self

Serve stale for up to seconds while revalidating in the background.

method with_transaction_scope

source

pub fn with_transaction_scope(mut self) -> Self

Restrict reuse to the producing transaction.

struct ConditionalRequest

source

pub struct ConditionalRequest {
  pub if_none_match: Option<String>,
  pub if_modified_since: Option<String>,
}

Description

The validators a client sends when revalidating a stale-but-revalidatable cached result. Handed to TableProducer::on_conditional_request (in the vgi worker crate) before the producer’s first batch; both fields are None on a normal call.

A producer that advertised [CacheControl::with_revalidatable] compares if_none_match against its current ETag and, when unchanged, emits a 0-row batch carrying [CacheControl::with_not_modified] instead of re-streaming the payload.

Methods

method is_conditional

source

pub fn is_conditional(&self) -> bool

Whether the client sent any validator at all.