Allow Rules

Relevant source files

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

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

Allow Rules are a specialized configuration mechanism within cargo-cooldown designed to grant exceptions or modifications to the standard cooldown period for specific registry crates. While the primary goal of the tool is to delay the adoption of freshly published versions to reduce supply-chain risk, Allow Rules provide the granularity needed to bypass these delays for trusted dependencies or exact known-safe versions.

These rules are embedded within the cooldown.toml configuration file and operate by reducing the effective cooldown window. They allow developers to define global overrides, package-specific window reductions, or full exemptions for exact crate versions. Allow Rules only serve to reduce the effective cooldown window; they cannot be used to make a crate wait longer than the globally configured cooldown_minutes.
Sources: src/allow_rules.rs:1-5, README.md:104-121

Rule Architecture and Data Structures

Allow Rules are structured into three distinct categories: Global, Package, and Exact. These are managed through a hierarchical data structure that facilitates parsing from TOML and merging across different configuration levels (e.g., workspace vs. member).

Data Models

The following structures define the schema for allow rules:

Structure	Description	Fields
AllowRules	Root object for rule management.	allow: AllowSection
AllowSection	Container for various rule types.	exact, package, global
AllowGlobal	Sets a new default cooldown for all crates.	minutes: Option<u64>
AllowPackage	Overrides the window for a specific crate name.	crate: String, minutes: Option<u64>
AllowExact	Fully exempts a specific version of a crate.	crate: String, version: String

Sources: src/allow_rules.rs:9-52

Class Relationship Diagram

The following diagram illustrates the relationship between the configuration structures:

Logic and Effective Window Calculation

The system calculates the "effective" cooldown window by comparing the global default against specific allow rules. The logic follows a "minimum value" priority: the actual cooldown applied is the lowest value found among the applicable rules.

Resolution Priority

1. Global Default: The cooldown_minutes defined in the main config.
2. Global Allow Rule: If allow.global.minutes exists, it can lower the global default.
3. Package Allow Rule: If an allow.package exists for the specific crate, it can further lower the window.
4. Exact Match: If an allow.exact matches the name and version, the effective cooldown requirement is effectively bypassed.

Configuration and Implementation

Allow Rules are typically initialized through the cargo cooldown init wizard, which provides commented examples in the generated cooldown.toml.

Example Configuration

# Allow a specific version of serde to bypass cooldown
[[allow.exact]]
crate = "serde"
version = "1.0.218"

# Reduce cooldown for tokio to 60 minutes
[[allow.package]]
crate = "tokio"
minutes = 60

# Fully exclude openssl from cooldown (minutes = 0)
[[allow.package]]
crate = "openssl"
minutes = 0

Sources: src/init.rs:205-220, README.md:104-118

Integration in Execution Flow

During the run_pinning_flow_with_snapshot execution, the executor uses the parsed AllowRules to identify which crates are "baseline exempt" or meet the age requirements based on their modified windows. This is performed during the "Inspecting release ages" phase.
Sources: src/executor.rs:114-135, src/main.rs:mod resolution_state

Merging and Precedence

cargo-cooldown supports hierarchical configuration where rules from different files are merged. Merging follows specific deduplication and override logic:

• Global Rules: Overwritten by the last defined rule (higher precedence levels like member-specific configs).
• Package Rules: Overwritten based on the crate_name key.
• Exact Rules: Appended to the list, with deduplication based on the combination of crate_name and version.

Sources: src/allow_rules.rs:92-117, src/config.rs:104-115

Config Precedence (Strongest to Weakest)

1. Environment Variables
2. Active Member cooldown.toml (if targeting exactly one workspace member)
3. Workspace or Crate Root cooldown.toml
4. $CARGO_HOME/cooldown.toml

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

Summary

Allow Rules provide a necessary safety valve for the strict versioning policies of cargo-cooldown. By allowing for exact version pins, package-specific window reductions, and global rule modifications, the system remains flexible enough to accommodate trusted dependencies and emergency updates while maintaining a high security baseline. These rules are resolved through a "lowest-win" logic and are managed via a robust merging system that respects workspace and environment hierarchies.