Workspace Isolation
Relevant source files
The following files were used as context for generating this wiki page:
Workspace Isolation is a core architectural component of cargo-cooldown designed to facilitate speculative Cargo lockfile resolutions without corrupting the user's primary workspace. Because Cargo's stable interface does not natively support resolving against alternate lockfile paths, the system clones the workspace into a temporary directory to perform its "cooling" operations—repeatedly testing version assignments and validating them through Cargo's resolver.
This mechanism ensures that the production Cargo.lock is only updated once a valid, cooled state is achieved. While the speculation occurs in the isolated environment, the real Cargo.lock is protected by a sentinel hold to prevent concurrent modifications.
Sources: src/isolation.rs:1-8, src/executor.rs:25-34
Architecture and Components
The isolation system is composed of several key structures that manage the lifecycle of the temporary environment, from creation to final publication of the cooled lockfile.
IsolatedWorkspace
The IsolatedWorkspace struct represents the temporary environment. It contains the path to the temporary directory, a mapped version of the project manifest, and a guard for the real lockfile.
| Field | Type | Description |
|---|---|---|
_temp_dir | TempDir | Owns the temporary directory on disk; deleted when dropped. |
current_dir | PathBuf | The mapped current working directory inside the temp workspace. |
manifest | Manifest | Mapped manifest path pointing to the temp workspace. |
lockfile_path | PathBuf | The path to the Speculative Cargo.lock in the isolated directory. |
real_lockfile | LockfileHoldGuard | Manages the sentinel and backup of the original Cargo.lock. |
Sources: src/isolation.rs:23-30
LockfileHoldGuard
This component ensures data integrity by "holding" the real Cargo.lock. It renames the original file to a backup path and replaces the original with a sentinel string. This prevents other Cargo processes from accidentally using a stale lockfile while cargo-cooldown is speculatively resolving in the isolated space.
Sources: src/isolation.rs:125-132, src/isolation.rs:135-171
Speculation Lifecycle
The lifecycle of workspace isolation follows a strict sequence: initialization, speculative resolution (validation), and publication or restoration.
1. Creation and Cloning
When an IsolatedWorkspace is created, it canonicalizes paths and clones the source workspace. It specifically avoids copying heavy or unnecessary directories like .git to speed up the process. It also detects the target/ directory; if the target is inside the workspace, it is skipped to avoid massive IO overhead.
2. Speculative Resolution
The executor uses the isolated workspace to run Cargo commands like cargo metadata --locked. This allows the system to verify if a specific set of version "pins" (cooled versions) is valid according to Cargo's resolver without affecting the real project state.
Sources: src/executor.rs:59-158, src/executor.rs:1071-1125
3. Argument Rewriting
Because the process runs in a temporary directory, any forwarded Cargo arguments (like --manifest-path) must be rewritten to point to the temporary manifest. The rewrite_cargo_args function handles this transformation.
Sources: src/isolation.rs:77-118
4. Publication and Cleanup
Once a cooled lockfile is validated, it is "published" back to the real workspace. If the process fails or is interrupted, the LockfileHoldGuard drop implementation attempts to restore the original lockfile from backup.
Path Mapping and Canonicalization
To maintain consistency, the system maps the user's current directory and manifest path into the temporary workspace. This ensures that relative path lookups and registry configurations behave identically to the original environment.
map_manifest: Calculates the relative path of the manifest from the workspace root and joins it to the temporary root.map_current_dir: Ensures the process behaves as if it were in the same sub-directory of the workspace, even within the isolation.canonicalize_existing: Used extensively to ensure path comparisons (especially for the "sentinel hold") are accurate across different OS conventions.
Sources: src/isolation.rs:271-302
Sentinel Protection
The sentinel hold mechanism uses a unique ID based on the process ID and system time to prevent collisions. The sentinel content contains a prefix and a backup label.
// Example Sentinel Content
const HELD_LOCKFILE_PREFIX: &str = "cargo-cooldown lockfile hold";
// "cargo-cooldown lockfile hold 1234-167890123\n..."
If cargo-cooldown detects an existing sentinel from a previous interrupted run, it refuses to proceed and instructs the user to manually restore the backup to prevent data loss.
Sources: src/isolation.rs:19-21, src/isolation.rs:304-328, src/isolation.rs:431-435
Conclusion
Workspace Isolation provides a safe sandbox for cargo-cooldown to perform complex dependency graph manipulations. By leveraging temporary directories, sentinel guards, and atomic file operations, the system guarantees that the developer's primary workspace remains in a valid state throughout the speculative resolution process.