Home & Quick Start

Relevant source files

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

• README.md
• src/main.rs
• src/init.rs
• src/config.rs
• src/executor.rs
• src/project.rs
• Cargo.toml

cargo-cooldown is a specialized Cargo wrapper designed to improve supply chain security by enforcing a "cooldown" window for freshly published registry crates. It prevents Cargo from immediately adopting the latest versions of dependencies, allowing time for potential security issues or bugs to be identified by the community before they reach your local development environment or production builds.

The tool works by allowing Cargo to resolve the dependency graph as usual and then programmatically replacing any "fresh" versions (those published within a specific timeframe) with the newest older compatible versions that still satisfy the project's semantic versioning requirements. It supports various enforcement policies, from strict blocking to warned compatibility.

Sources: README.md:3-8, src/main.rs:1-12, Cargo.toml:1-10

Installation and Setup

cargo-cooldown can be installed via standard Rust toolchain methods or prebuilt artifacts. Once installed, it must be initialized within a project to create a configuration file.

Installation Methods

Users can install the tool using cargo install or cargo-binstall for faster CI integration.

# Standard installation
cargo install --locked cargo-cooldown

# CI-optimized installation via cargo-binstall
cargo install cargo-binstall --locked
cargo binstall cargo-cooldown --no-confirm

Sources: README.md:12-23

Project Initialization

The init command launches an interactive wizard that detects the project structure (single crate or workspace) and guides the user through setting up the initial cooldown.toml.

cargo cooldown init

The wizard performs the following steps:

1. Project Detection: Identifies the workspace root and members.
2. Template Selection: Asks for base settings like cooldown minutes and enforcement level.
3. Override Planning: In workspaces, it allows per-member configuration overrides.
4. Safety Check: Refuses to overwrite existing cooldown.toml files.

Sources: src/init.rs:36-70, README.md:35-37

Architecture and Execution Flow

The system operates as a wrapper that intercepts Cargo commands. It utilizes an isolated execution model to ensure that speculative dependency resolutions do not corrupt the primary workspace state.

High-Level Component Interaction

The diagram shows how the CLI entry point initiates project discovery and configuration loading before handing off to the Executor, which manages the lifecycle of the cooldown process within an isolated environment.
Sources: src/main.rs:17-40, src/executor.rs:51-120

Execution Logic (Pinning Flow)

When a guarded command (e.g., check, build, update) is run, cargo-cooldown follows a multi-pass pinning flow:

1. Capture: It takes a snapshot of the current Cargo.lock.
2. Scan: It reads Cargo metadata to identify all reachable registry packages.
3. Inspect: It queries the registry (local index or HTTP fallback) for release timestamps.
4. Resolve: It identifies crates inside the cooldown window.
5. Pin: It attempts to find older compatible candidates and rewrites the lockfile.
6. Validate: It asks Cargo to validate the proposed lockfile. If valid, the new graph is kept.

Sources: src/executor.rs:88-150, src/main.rs:334-375

Configuration Options

cargo-cooldown uses a cooldown.toml file for configuration. Settings are merged with a specific precedence: environment variables > active member config > workspace root config > global config.

Core Configuration Parameters

Parameter	Type	Default	Description
cooldown_minutes	u64	0	Age required for a release to be accepted.
enforcement	String	strict	Policy when fresh versions remain: strict, cargo_compatible, or off.
cargo_compatible_accept	String	prompt	Policy for accepting fresh versions: prompt or auto.
lockfile_baseline	String	floor	floor uses initial versions as minimum; ignore allows downgrades.
skip_registries	List	[]	Registries to exclude from cooldown inspection.

Sources: src/config.rs:85-115, README.md:46-60

Enforcement Modes

The tool's behavior when encountering fresh versions is governed by the enforcement and lockfile_baseline settings:

The flowchart illustrates the decision matrix for how the tool handles dependencies based on user configuration.
Sources: README.md:65-85, src/config.rs:18-35

Quick Start Commands

Commonly used commands through the cooldown wrapper:

• Initialize project: cargo cooldown init
• Check code: cargo cooldown check
• Build project: cargo cooldown build
• Run tests: cargo cooldown test
• Update lockfile: cargo cooldown update

The update command specifically allows Cargo to resolve the newest possible graph first, then applies the cooldown logic to "cool down" the resulting updated lockfile before it is committed to the workspace.

Sources: README.md:39-44, src/main.rs:100-140

Conclusion

cargo-cooldown provides a necessary buffer in the Rust dependency lifecycle. By integrating directly with Cargo's resolution metadata and registry indices, it offers a transparent way to delay the adoption of new code, mitigating the risk of zero-day supply chain attacks while maintaining compatibility with standard Cargo workflows.