Struct CachedCatalog 

pub struct CachedCatalog<C: MetricCatalog + ?Sized> { /* private fields */ }

Cache layer for any MetricCatalog implementation.

Catalog data is small and slow-changing (per-session: it can only grow, never shrink). The cache absorbs the repeated queries that completion fires on every keystroke and amortises the backend round-trip across them. For sqlite-backed sessions the speedup is modest (the queries are already cheap); for remote backends it’s the difference between “completion feels instant” and “every tab spawns an HTTP roundtrip.”

Invalidation

Three layers, evaluated in order:

1. Time-based TTL — every cached entry expires after CachedCatalog::ttl (default: 1 second). Aggressive by design: completion users tap repeatedly, so the cache absorbs bursts but yields to fresh data quickly.
2. Generation counter — CachedCatalog::invalidate bumps a process-local generation to force the next read. Used by integration tests + by callers that know the underlying state changed (e.g. a writer just landed a new metric family).
3. Backend-supplied mtime — when the CachedCatalog holds a mtime_fn, every read consults it; if the timestamp moved past the cached snapshot’s read time, the entry expires immediately. This is the path the sqlite adapter uses to detect on-disk db changes (writer flushed).

The cache is a soft hint — if any layer says “stale,” the next call refetches and rebuilds. There’s no invariant that two concurrent readers of the same just-invalidated key see the same fresh result; both may run the underlying query. That’s acceptable because catalog reads are idempotent and side-effect-free.

Implementations

impl<C: MetricCatalog + ?Sized + 'static> CachedCatalog<C>

pub fn new(inner: Arc<C>) -> Self

Wrap an inner catalog with a default 1-second TTL and no backend-mtime hook.

pub fn with_ttl(self, ttl: Duration) -> Self

Builder: set the TTL window. Setting Duration::ZERO disables the TTL layer (entries still expire on generation bump or mtime change).

pub fn with_mtime_fn<F>(self, mtime_fn: F) -> Self

where F: Fn() -> Option<Instant> + Send + Sync + 'static,

Builder: install a backend-mtime hook. The closure returns the latest backend-side mtime as a monotonic Instant; entries cached before the latest mtime are considered stale on the next read.

None from the closure (e.g. the underlying file disappeared) keeps the existing entries — the behaviour matches “mtime unknown ⇒ trust the TTL.”

pub fn invalidate(&self)

Force the next read of every key to refetch. Internally bumps the generation counter; existing entries become stale at next access.

Trait Implementations

impl<C: MetricCatalog + ?Sized + 'static> MetricCatalog for CachedCatalog<C>

fn metric_families(&self) -> Result<Vec<MetricFamilyMeta>, DataSourceError>

Every metric family known to the backend, with its OpenMetrics metadata. Order is backend-chosen (sqlite-backed impls return alphabetical; remote backends typically don’t promise an order).

fn label_keys( &self, family_filter: Option<&str>, ) -> Result<Vec<String>, DataSourceError>

Distinct label keys observed across the catalog, optionally restricted to one metric family by exact name. family_filter = None returns every key the backend has seen anywhere.

fn label_values( &self, key: &str, family_filter: Option<&str>, ) -> Result<Vec<String>, DataSourceError>

Distinct values observed for key, optionally restricted to one metric family. Returns an empty list if the key has no values observed (or doesn’t exist) — no error, since “no values yet” is a normal state for a fresh session.

fn series(&self, matchers: &[Matcher]) -> Result<Vec<LabelSet>, DataSourceError>

Distinct label sets in the catalog matching every Matcher. The result is the series identity surface — one entry per (family + label set) tuple that satisfies the selector. Used by callers that need to know “which concrete series exist that satisfy this shape” without fetching their samples.

fn exemplars( &self, matchers: &[Matcher], time_range: Option<(i64, i64)>, ) -> Result<Vec<ExemplarPoint>, DataSourceError>

OpenMetrics §4.6.1 exemplars matching matchers, optionally restricted to a [start_ms, end_ms] window on sample_timestamp_ms. Returns one ExemplarPoint per stored exemplar; series with no exemplars contribute nothing.