Module cache 

Local cache for read-only browse data, in one SQLite database at <cache dir>/cache.sqlite (WAL, mode 0600, inside a 0700 directory).

It has three parts:

• Responses (entries): the raw upstream JSON of read-only calls (search results, menus, store details, category lists), keyed by the SHA-256 of a canonical request identity that includes the rounded delivery location, with a per-kind TTL. Raw responses (not parsed structs) are stored so struct changes never change what an entry means.
• Catalog (catalog): normalized, queryable restaurants, the locations they were seen from, menu categories and menu items, with FTS5 word + trigram indexes. Service crates upsert into it whenever they fetch list or menu data, and query it for offline (--local) search.
• Images (images): content-addressed image files under <cache dir>/images/, indexed in SQLite and evicted LRU by total size.

The cache is best-effort: if the database can’t be opened or a row can’t be decoded, reads miss and writes are skipped. A broken cache never fails a browse command.

Safety: what may be cached

Only the read-only kinds in CacheKind exist, and every cached call must pick one. There is deliberately no kind for quotes, carts, vouchers, auth/session/token responses, order submission, order history or tracking: those must always be fetched live, and adding a kind for them is a safety regression. The catalog tables likewise only hold restaurant, menu and item data. Commands on the cart → quote → order path use CacheMode::Off (or call the API directly) so prices and availability are always fresh before money moves; with the mode off nothing is read from or written to any part of the cache.

Usage from a service crate

let key = CacheKey::new("food", CacheKind::Menu, "merchant")
    .param("id", merchant_id)
    .location(loc.latitude, loc.longitude);
let raw: serde_json::Value = ctx.cached_call(&key, &req).await?;
// with the entry's age (for "(cached 4m ago)" markers):
let hit = ctx.cached_call_meta(&key, &req).await?;
// or, for anything that isn't a single request:
let cache = ctx.cache().clone();
let raw: serde_json::Value = cache.get_or_fetch(&key, || ctx.call(&req)).await?;

Re-exports

pub use catalog::CategoryRow;

pub use catalog::ItemHit;

pub use catalog::ItemQuery;

pub use catalog::ItemRow;

pub use catalog::Near;

pub use catalog::RestaurantHit;

pub use catalog::RestaurantQuery;

pub use catalog::RestaurantRow;

pub use images::CachedImage;

pub use images::image_url_allowed;

Modules

catalog

The normalized catalog: restaurants/stores, where they were seen from, menu categories and menu items, with FTS5 indexes for offline search.

images

Content-addressed image store: <cache dir>/images/ab/cd/<sha256>.<ext> (files 0600, dirs 0700), indexed in the images table by URL. Several URLs with identical bytes share one file. When the total size of distinct files exceeds [cache] image_max_mb (default 500), the least recently used files are evicted.

Structs

Cache

A handle on the cache database plus the active mode and TTLs. Cheap to clone (clones share one connection); clone it out of the Context to use get_or_fetch with a closure that borrows the context. The database is opened on first use.

CacheConfig

[cache] in config.toml. Every key is optional.

CacheKey

The identity of a cached request: service namespace, kind, endpoint name and normalized parameters. Two keys with the same identity share an entry.

CacheStats

grab cache stats.

CacheTtls

Per-kind TTL overrides in seconds.

ClearReport

What grab cache clear --all removed.

Fetched

A value plus where it came from: cached_at is the time the cached response was fetched, or None if it was just fetched live.

ImageStats

Image store numbers in CacheStats.

KindStats

Per-kind numbers in CacheStats.

PruneReport

What grab cache prune removed.

Enums

CacheKind

What is being cached. Only read-only browse data has a kind; see the module docs before adding one.

CacheMode

How a command uses the cache.

Constants

DEFAULT_IMAGE_MAX_MB

Default image store cap ([cache] image_max_mb).

DEFAULT_INDEX_MAX_AGE_DAYS

Default age after which grab cache prune drops catalog rows.

NO_CACHE_ENV

Environment variable that disables the cache when set to a truthy value.

Functions

human_age

4m, 2h, 3d — for “(cached 4m ago)” markers.