Lockfile Management

Relevant source files

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

• src/lockfile.rs
• src/executor.rs
• src/isolation.rs
• src/config.rs
• src/init.rs
• README.md

Lockfile Management in cargo-cooldown is the system responsible for snapshotting, speculatively modifying, and restoring the Cargo.lock file to enforce dependency cooldown periods. Because the tool speculatively rewrites lockfiles to find older compatible versions, it must ensure that the user's original state can be restored exactly if a resolution fails or if strict enforcement is triggered.

The system encompasses capturing initial state baselines, managing file system isolation through temporary workspaces, and performing atomic updates to the real lockfile. This ensures that users never keep a partial or invalid cooldown rewrite.

Lockfile Snapshotting and Baselines

At the start of any execution, cargo-cooldown captures a snapshot of the existing Cargo.lock. This snapshot serves two purposes: providing a byte-for-byte restoration point and establishing a "baseline" of currently locked registry versions.

Data Structures

The primary structures for this phase are LockfileSnapshot and LockfileBaseline.

Structure	Description
LockfileSnapshot	Contains the raw string contents of the lockfile and the parsed baseline index.
LockfileBaseline	A searchable index of registry packages (name, registry, version) used to calculate version floors.
LockfilePackageKey	A unique identifier for a package version consisting of its name, registry URL, and version string.

Sources: src/lockfile.rs:24-84

Snapshot Logic Flow

The following diagram illustrates how a snapshot is captured and used to derive a version baseline.

Speculative Workspace Isolation

Cargo's stable interface does not support resolving against an arbitrary lockfile path. To work around this, cargo-cooldown implements workspace isolation by copying the project to a temporary directory.

Workspace Copying and Mapping

The IsolatedWorkspace struct manages the lifecycle of this temporary environment. It copies the source tree, excluding the .git directory and the target/ directory to save space and time. It also "maps" the manifest path and current directory from the real workspace to the temporary one so that Cargo commands behave consistently.

Sources: src/isolation.rs:27-68, src/isolation.rs:244-270

Lockfile Hold Mechanism

To prevent external tools or users from modifying the lockfile while a cooldown run is in progress, the system employs a "Hold" mechanism.

1. Rename: The original Cargo.lock is renamed to a backup file with a unique ID (e.g., Cargo.lock.cooldown-backup.[ID]).
2. Sentinel: A sentinel file is written to the original path containing a "cargo-cooldown lockfile hold" prefix.
3. Validation: Before publishing results, the tool verifies the sentinel is unchanged to ensure no concurrent edits occurred.

Lockfile Rewriting Logic

The executor module performs the actual mutation of the lockfile contents. Instead of using a high-level TOML library that might reformat the entire file, it performs targeted updates to the [[package]] entries.

The Pinning Process

The write_lockfile_pin_assignment function modifies specific package entries based on LockfilePin data. It updates the version and checksum fields. The checksum is retrieved from the RegistryStore to ensure the resulting lockfile is valid for Cargo.

Sources: src/executor.rs:1143-1205

Baseline Modes

The way the lockfile is managed depends on the lockfile_baseline configuration.

Mode	Description
floor	Uses the versions in the initial lockfile as the minimum version. Cooldown will not downgrade below these versions.
ignore	Allows cooldown to select versions older than those currently in the lockfile.

Sources: src/config.rs:59-71, README.md:84-98

Restoration and Cleanup

Restoration occurs if a cooldown pass fails, if Cargo rejects a speculative assignment, or if strict enforcement is triggered by remaining fresh versions.

Restoration Logic

• If the snapshot came from an existing file, that content is written back.
• If the snapshot represented a missing lockfile (initial state), any generated lockfile is removed.
• The LockfileHoldGuard uses a Drop implementation to ensure that even if the process crashes, it attempts to restore the original lockfile from the backup.

Sources: src/lockfile.rs:71-82, src/isolation.rs:198-232

Summary of Configuration Options

Lockfile management behavior is governed by the following keys in cooldown.toml.

Option	Type	Default	Description
lockfile_baseline	String	"floor"	Determines if the initial lockfile acts as a version floor.
enforcement	String	"strict"	Determines if a run fails when fresh versions cannot be cooled.
skip_registries	List	[]	Registries whose packages should not be inspected or modified.

Sources: src/config.rs:121-141, src/init.rs:163-180

The lockfile management system ensures that cargo-cooldown provides a safe, transactional experience for users, leveraging file system isolation and robust snapshotting to maintain the integrity of the Rust project's dependency graph.

Sources: src/lockfile.rs, src/executor.rs, src/isolation.rs, src/config.rs, src/init.rs, README.md