Skip to content

Component and Thunder Cache Behavior

This page documents the current cache semantics for component model reads and Thunder reads.

Overview

Caching is enabled server-side, but callers control freshness with cacheTTL.

  • cacheTTL > 0: cached responses can be served if the cached entry age is within TTL.
  • cacheTTL = 0: cache reads are bypassed and fresh data is fetched from storage.

Even when cacheTTL = 0, the backend may still repopulate shared cache entries for other callers.

Freshness Model

Cached entries use an envelope with a cached_at timestamp.

At read time:

  1. The server compares now - cached_at against requested cacheTTL.
  2. If entry age is within TTL, the cached payload is returned.
  3. If stale, missing, or cacheTTL = 0, the server reads from DB and refreshes cache.

Field Projection (only)

Projection support is intentionally split by version:

  • V3 component model: only is intentionally unsupported.
  • V4 component model: only is supported.
  • Thunder reads: only is supported.

Validation rules for only:

  • * means wildcard (no field projection stage is applied).
  • _id is rejected.
  • Empty field names are rejected.
  • Valid names must match ^[a-zA-Z_][a-zA-Z0-9_.]*$.

Cache Key Canonicalization

For V4 component and Thunder reads, only is sorted before hash construction.

This prevents cache fragmentation when callers send equivalent field lists in different orders.

Dashboard (TLS) Fresh-Read Policy

Dashboard UI calls to component and Thunder endpoints are forced to fresh-read mode.

The frontend sends X-Cache-Ttl: 0 for:

  • /v3/system/component/...
  • /v4/system/component/...
  • /v3/system/thunder...

When request payload contains options.cacheTTL, the frontend also forces it to 0.

This ensures dashboard users see current data instead of cached reads.