Registry Caching

Relevant source files

The following files were used as context for generating this wiki page:

• src/cache.rs
• src/registry.rs
• src/config.rs
• src/executor.rs
• src/resolution_state.rs

Registry Caching is a critical system within cargo-cooldown designed to provide efficient, time-limited access to crate release metadata. Its primary purpose is to avoid redundant network requests and expensive local index reloads during the dependency resolution and "cooling" process. The system manages two distinct layers of caching: an in-memory layer within the RegistryStore for active execution sessions and a persistent, filesystem-backed JSON cache for HTTP API fallback data.

The scope of this system covers the resolution of Cargo source IDs to effective registry contexts, the retrieval of chronological release timelines, and the storage of external API responses when local index metadata lacks necessary publication timestamps. By prioritizing local index data and only falling back to cached API results, the system ensures that cooldown decisions are made using the most accurate information available while maintaining high performance.

Sources: src/registry.rs:1-12, src/registry.rs:118-135, src/cache.rs:1-12

System Architecture

The registry caching architecture is centered around the RegistryStore, which coordinates access to various metadata sources and manages the lifecycle of cached data.

Component Overview

Component	Description
RegistryStore	The primary coordinator that manages in-memory caches for registry contexts, timelines, and release metadata.
Cache	A filesystem-backed utility that handles the persistence of serialized JSON entries with TTL (Time-To-Live) enforcement.
RegistryContext	Stores resolved registry identity, including index locations, API endpoints, and unique cache fingerprints.
ReleaseTimeline	An in-memory chronological list of crate releases used for freshness decisions.

Sources: src/registry.rs:118-140, src/cache.rs:15-20, src/registry.rs:88-97

Data Flow for Metadata Retrieval

The following diagram illustrates how the system attempts to resolve release metadata, moving from local authoritative sources to cached fallbacks and finally to remote APIs.

The system prioritizes the local registry index. If the index is missing publication timestamps (pubtime), it consults the persistent disk cache before attempting a network request. Sources: src/registry.rs:172-192, src/registry.rs:242-255

Persistent Storage (Cache)

The Cache struct provides the logic for time-limited on-disk storage. It is used primarily to store responses from registry APIs (such as crates.io) when the local sparse or legacy index does not contain pubtime metadata.

Cache Entry Structure

Each entry on disk is wrapped in a CacheEntry container that tracks the fetch time:

struct CacheEntry<T> {
    fetched_at: u64,
    value: T,
}

Sources: src/cache.rs:10-14

Logic and Path Sanitization

The cache organizes files by keys that often contain registry URLs or crate names. To ensure filesystem compatibility, segments are sanitized:

• Root Directory: Defaults to the platform's standard cache directory (e.g., via dirs::cache_dir()) under a cargo-cooldown subfolder.
• Sanitization: Characters outside of alphanumeric and a small set of symbols (-, _, ., @) are replaced with underscores.
• TTL Enforcement: During a get operation, the system compares the current epoch to fetched_at. If the difference exceeds the configured ttl_seconds, the entry is treated as missing.

Sources: src/cache.rs:22-32, src/cache.rs:43-55, src/config.rs:114-116

Registry Context and Fingerprinting

Before caching metadata, cargo-cooldown must resolve the "effective" registry. This is necessary because Cargo may use mirrors, source replacement, or different protocols (sparse vs. git).

Fingerprinting Logic

To prevent collisions between different registries, the system generates a cache_fingerprint for every resolved RegistryContext. This is calculated as a stable hash (FNV-like) of the effective index URL. This fingerprint is then used as a directory prefix in the persistent cache.

Sources: src/registry.rs:434-441, src/registry.rs:159-166

Interaction with Resolution State

The caching system is tightly integrated with the ResolutionState, which is built during every pass of the executor.

1. Inspection Cache: During a resolution pass, an inspection_cache (Map of ReleaseInspectionKey to ReleaseInspection) is used to store the results of release age checks.
2. Authoritative Merging: When timeline_for is called, the store merges local data with API data. If the local index is authoritative (contains pubtime), the HTTP fallback is skipped entirely.
3. Efficiency: The RegistryStore is instantiated once per cooldown run, ensuring that within that execution, the same crate's metadata is never loaded or calculated more than once.

Sources: src/resolution_state.rs:43-60, src/registry.rs:180-192, src/executor.rs:77-85

Configuration Options

Caching behavior is controlled by several configuration parameters available in cooldown.toml or via environment variables.

Option	Type	Default	Description
ttl_seconds	u64	86,400 (24h)	Time-to-live for persistent cache entries.
cache_dir	PathBuf	Platform Default	Override for the directory where JSON metadata is stored.
http_retries	u32	2	Number of retries for registry API requests on failure.

Sources: src/config.rs:114-118, src/config.rs:191-193, src/cache.rs:22-30

Registry Caching ensures that cargo-cooldown remains performant even when processing large dependency graphs. By effectively balancing in-memory speed, persistent reliability, and authoritative local index data, the system provides a robust foundation for making accurate crate freshness decisions.

Sources: src/registry.rs:1-8, src/executor.rs:150-165