Metadata Retrieval & Fallbacks
Relevant source files
The following files were used as context for generating this wiki page:
The Metadata Retrieval & Fallbacks system is a core component of cargo-cooldown responsible for acquiring and managing crate release information. Its primary purpose is to determine the "freshness" of crate versions by retrieving accurate publication timestamps. The system prioritizes local registry index data for speed and privacy but implements a robust HTTP API fallback mechanism for cases where the local index is incomplete or missing required metadata.
This module acts as the data provider for the Cooldown Execution Loop, translating raw Cargo source identifiers into actionable release timelines. By consolidating information from local caches, registry indexes, and remote APIs, it ensures the resolver has the necessary context to enforce cooldown periods and perform lockfile pinning.
Sources: src/registry.rs:1-8, src/resolution_state.rs:1-10
Registry Store Architecture
The RegistryStore is the central coordinator for all metadata operations. It maintains internal caches to prevent redundant disk I/O and network requests during a single execution. It manages the lifecycle of registry contexts, release timelines, and local release metadata.
Components and Data Flow
The store operates by resolving a Cargo source_id into a RegistryContext, which contains the normalized URL and local path to the registry's index.
The diagram above shows the prioritized flow from initial ID resolution to the final cached release timeline.
Sources: src/registry.rs:88-120, src/registry.rs:154-175
Key Data Structures
| Structure | Description | Source File |
|---|---|---|
RegistryStore | Main coordinator holding HTTP clients, caches, and registry settings. | src/registry.rs:88-98 |
RegistryContext | Normalized registry identity including local paths and API endpoints. | src/registry.rs:69-77 |
ReleaseTimeline | Chronological list of crate releases with version and timestamp data. | src/registry.rs:46-49 |
Release | Metadata for a single version, including source of the timestamp. | src/registry.rs:38-43 |
Metadata Sources & Hierarchy
cargo-cooldown implements a tiered approach to metadata retrieval. This ensures that network dependencies are minimized while maintaining high data accuracy.
1. Local Registry Index
The primary source of truth is the local registry index (e.g., ~/.cargo/registry/index/...). The system uses the tame-index crate to read cached crate metadata directly from disk. This includes version numbers, yanked status, and publication times (if supported by the registry's index format).
Sources: src/registry.rs:163-165, src/registry.rs:271-285
2. Registry API Fallback
When local index data is insufficient—specifically when the pubtime field is missing—the system falls back to the registry's web API. This is common for crates.io before the adoption of the sparse index or for private registries that do not include timestamps in the index files.
Sources: src/registry.rs:167-175, src/registry.rs:232-248
3. On-Disk Persistence
To avoid hitting the Registry API on every run, API responses are cached locally in a directory specified by COOLDOWN_CACHE_DIR (or a default temporary location). This cache respects a configurable Time-To-Live (TTL).
Sources: src/registry.rs:105-111, src/config.rs:105-108
Detailed Retrieval Logic
The process of loading a timeline involves merging data from multiple sources to create a complete picture of a crate's history.
The sequence above illustrates the conditional fallback logic triggered when local metadata is incomplete.
Sources: src/registry.rs:154-180, src/registry.rs:315-356
Timeline Merging Rules
When merging index data with API data, the following rules apply:
- Authoritative Index: Index data is preferred for version lists and yanked status.
- Timestamp Augmentation: Missing
published_atvalues in the index are filled usingcreated_atvalues from the API. - Source Tracking: Each release is marked as
ReleaseSource::IndexorReleaseSource::Apito provide transparency in logs.
Sources: src/registry.rs:328-356
Registry Normalization & Skipping
Registries are identified by Source IDs, which can vary in format (Legacy vs. Sparse). The system normalizes these to ensure consistent cache keys and effective skip matching.
| Source Type | Example Format |
|---|---|
| Legacy crates.io | `registry+https://github.com/rust-lang/crates.io-index%60 |
| Sparse crates.io | sparse+https://index.crates.io/ |
| Normalized ID | https://index.crates.io/ (Canonicalized) |
Sources: src/registry.rs:25-26, src/registry.rs:215-230
Skipping Logic
If a registry is listed in skip_registries (configured via cooldown.toml or COOLDOWN_SKIP_REGISTRIES), its metadata is not inspected. Skipped registries return an empty ReleaseTimeline, and their packages are treated as exempt from cooldown enforcement.
Sources: src/registry.rs:159-161, src/resolution_state.rs:162-168
Technical Configuration Summary
The following configuration options directly impact how metadata is retrieved and cached:
| Option | Environment Variable | Default | Description |
|---|---|---|---|
http_retries | COOLDOWN_HTTP_RETRIES | 2 | Number of times to retry failed API requests (max 8). |
ttl_seconds | COOLDOWN_TTL_SECONDS | 86400 | Lifetime of the local API cache in seconds. |
cache_dir | COOLDOWN_CACHE_DIR | (temp) | Path to persist registry API responses. |
skip_registries | COOLDOWN_SKIP_REGISTRIES | [] | List of registries to ignore for metadata scanning. |
Sources: src/config.rs:175-188, src/registry.rs:105-115
Conclusion
The Metadata Retrieval & Fallbacks system provides the foundational data layer for cargo-cooldown. By intelligently merging local index data with remote API fallbacks and utilizing an efficient caching strategy, the system provides high-performance access to crate publication history. This architecture allows the tool to maintain security enforcement even when standard local indexes lack the necessary temporal metadata.
Sources: src/registry.rs, src/resolution_state.rs