Caching Rules

Purpose of Caching#

Caching provides several benefits:

• Ensures the app remains functional when offline or degraded.
• Prevents rapid state changes caused by transient network issues.
• Reduces unnecessary network traffic.
• Maintains a consistent global baseline for the merge logic.
• Supports a permissionless architecture without background refresh.

The cache is treated as a first‑class input to the Awareness model.

Cache Contents#

The cache stores the most recent valid response from:

/.well-known/rtt-awareness

The stored data includes:

• The full JSON payload.
• The server‑declared timestamp.
• The local time when the document was fetched.

These values allow the app to determine freshness and fallback behavior.

Cache Lifetime#

The cache follows a simple lifetime model:

• Fresh — within the defined validity window.
• Stale — outside the validity window but still usable.
• Expired — beyond the maximum allowed age.

The validity window is intentionally conservative to avoid oscillation. The exact duration is platform‑agnostic and defined in implementation notes.

Fallback Behavior#

When the app cannot retrieve a fresh server state:

• Use the most recent cached value.
• If the cache is stale, treat the server state as Stable for merge purposes.
• If the cache is expired, treat the server state as Unknown.

Unknown behaves the same as Stable in the merge logic to ensure predictable behavior during outages.

Error Handling#

The app handles server errors gracefully:

• Network failure — retain the cached value.
• Invalid JSON — ignore the response and keep the previous value.
• Missing fields — treat the server state as Unknown.
• Unexpected fields — ignore without failing.

The cache is never cleared automatically due to malformed responses.

Refresh Strategy#

The app refreshes the server state opportunistically:

• On app launch.
• When returning to the foreground.
• At safe intervals during active use.

No background tasks or privileged APIs are used.

Consistency Guarantees#

The caching model provides several guarantees:

• The Awareness state never oscillates due to transient network issues.
• The app remains usable even during extended offline periods.
• The merge logic always receives a valid input, even if degraded.
• Server‑declared Awareness can evolve without requiring app updates.

These guarantees support the RTT‑App’s role as a stable, permissionless entry point into the RTT ecosystem.