Configuration Reference

Relevant source files

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

• src/config.rs
• src/init.rs
• README.md
• CHANGELOG.md
• src/executor.rs
• src/main.rs

The cargo-cooldown configuration system manages how the tool identifies and handles "fresh" registry crates. It provides a multi-layered mechanism for defining cooldown durations, enforcement policies, and exceptions. Configuration is primarily stored in cooldown.toml files or supplied via environment variables to control the behavior of the cooldown resolver and its interaction with the Cargo dependency graph.

Sources: src/config.rs:1-13, README.md:65-71

Configuration Hierarchy and Precedence

The tool loads configuration from four distinct levels, merging them from weakest to strongest. Environment variables always take precedence over file-based settings.

1. Global Configuration: Loaded from $CARGO_HOME/cooldown.toml.
2. Workspace Configuration: Loaded from the workspace or crate root cooldown.toml.
3. Member Override: Active when exactly one workspace member is targeted, loaded from [member-dir]/cooldown.toml.
4. Environment Variables: Overrides all previous levels.

Sources: src/config.rs:88-100, README.md:73-78, src/main.rs:mod_project

Configuration Loading Flow

The following diagram illustrates how the Config struct is populated during tool execution.

The configuration is layered starting from the global directory down to specific environment overrides.
Sources: src/config.rs:88-100

Core Settings

Core settings define the fundamental operational parameters for cooling the dependency graph.

Option	Env Variable	Type	Default	Description
cooldown_minutes	COOLDOWN_MINUTES	u64	0	Minimum age in minutes for a crate version to be accepted.
enforcement	COOLDOWN_ENFORCEMENT	Enum	strict	Action taken when fresh versions remain.
cargo_compatible_accept	COOLDOWN_CARGO_COMPATIBLE_ACCEPT	Enum	prompt	Prompting behavior for unresolved fresh versions.
lockfile_baseline	COOLDOWN_LOCKFILE_BASELINE	Enum	floor	Use of initial Cargo.lock as a version floor.
verbose	COOLDOWN_VERBOSE	bool	false	Enables detailed debug logging.
skip_registries	COOLDOWN_SKIP_REGISTRIES	List	[]	Registries excluded from inspection.

Sources: src/config.rs:65-80, src/config.rs:175-188, README.md:65-71

Enforcement Modes

The enforcement setting determines tool behavior when the Cargo dependency graph cannot be fully cooled due to constraints (e.g., exact version requirements in Cargo.toml).

• strict: Fail-closed policy. If any fresh version remains that cannot be cooled, the tool fails and restores the original Cargo.lock.
• cargo_compatible: Warning-based policy. Keeps the best Cargo-valid lockfile even if some fresh versions remain, and warns the user.
• off: Bypasses all cooldown checks entirely.

Sources: src/config.rs:18-35, README.md:86-103

Lockfile Baseline Behavior

• floor: Uses versions present in the initial Cargo.lock as the minimum version floor. Cooldown will not downgrade packages below these versions.
• ignore: Allows cooldown to downgrade packages even below the versions found in the initial Cargo.lock, provided Cargo still accepts the resulting graph.

Sources: src/config.rs:48-63, README.md:86-103

Allow Rules

Allow rules provide granular exceptions to the global cooldown_minutes setting. They live under the [allow] section in cooldown.toml.

• allow.global: Sets a global maximum cooldown that overrides cooldown_minutes if lower.
• allow.package: Defines a specific cooldown duration for a named crate. Setting minutes = 0 excludes the crate from cooldown checks.
• allow.exact: Fully allows one specific crate version regardless of age.

Sources: src/init.rs:242-261, README.md:113-128

# Example Allow Rules
[allow.global]
minutes = 1440

[[allow.package]]
crate = "tokio"
minutes = 60

[[allow.exact]]
crate = "serde"
version = "1.0.218"

Sources: src/init.rs:253-268, README.md:113-121

Registry Configuration

Cargo's registry configuration acts as the source of truth for cargo-cooldown. The tool reads release timestamps from the local registry index and falls back to HTTP APIs if pubtime metadata is missing.

Skipping Registries

Specific registries can be excluded from inspection using skip_registries. Packages from these registries still shape the dependency graph but are never downgraded or flagged as fresh.

# In cooldown.toml
skip_registries = ["crates-io", "sparse+https://example.com/index/"]

Sources: src/config.rs:240-252, README.md:133-142

Initialization Wizard

The cargo cooldown init command provides an interactive setup wizard to generate a cooldown.toml file. It detects the project type (crate vs. workspace) and prompts for baseline configuration values.

Init Plan Logic

The wizard builds a plan based on the project structure and user selections before writing files to disk.
Sources: src/init.rs:37-124

Implementation Details

Data Structures

The configuration is managed internally using the Config and MergedConfig structs.

// src/config.rs:65-77
pub struct Config {
    pub cooldown_minutes: u64,
    pub enforcement: Enforcement,
    pub cargo_compatible_accept: CargoCompatibleAccept,
    pub lockfile_baseline: LockfileBaselineMode,
    pub now_override: Option<DateTime<Utc>>,
    pub ttl_seconds: u64,
    pub cache_dir: Option<PathBuf>,
    pub http_retries: u32,
    pub verbose: bool,
    pub skip_registries: Vec<String>,
    pub allow_rules: AllowRules,
}

Sources: src/config.rs:65-77

Internal Validation

The tool validates numeric ranges and enum strings during loading. For example, http_retries is capped at 8 to prevent excessive network wait times.

Sources: src/config.rs:260-266

Summary

The cargo-cooldown configuration reference provides developers with the controls necessary to balance supply-chain security with project stability. By utilizing a hierarchy of cooldown.toml files and environment variables, users can enforce strict version aging for specific registries while allowing immediate updates for trusted or critical packages via allow rules. In workspaces, this flexibility extends to per-member overrides, ensuring that different components of a project can have tailored security policies.