Example Workspaces
Relevant source files
The following files were used as context for generating this wiki page:
Example Workspaces in the cargo-cooldown project provide concrete, real-world implementations used for manual smoke testing, performance benchmarking, and validating the cooldown logic against actual registry state. Unlike the deterministic test suite which utilizes local mock registries, these examples interact directly with crates.io to simulate production environments. Sources: examples/README.md:1-5, README.md:105-110
These workspaces serve as the primary target for the project's benchmarking infrastructure, allowing developers to measure the wall-clock performance of the cooldown resolver and its fallback mechanisms under various scenarios, such as aggressive 60-day cooldown windows or large dependency graphs. Sources: examples/README.md:8-12, examples/run-crates-io-benchmark.sh:7-15
Workspace Variants
The project includes two primary example workspace structures tailored for different testing depths.
Smoke Workspace
The crates-io-smoke-workspace is a small, crates.io-backed workspace designed for fast manual checks and serving as the default target for standard benchmarks. It contains a minimal dependency set (including chrono, serde, and serde_json) to verify basic integration and API fallback behavior. Sources: examples/README.md:8-9, examples/crates-io-smoke-workspace/src/main.rs:3-6
Large Benchmark Workspace
The crates-io-large-benchmark-workspace provides a significant dependency graph to test the "aggressive 60-day cooldown" scenario. It includes a wide array of common Rust crates across categories like web development, serialization, and async runtimes. Sources: examples/README.md:10-11, examples/crates-io-large-benchmark-workspace/Cargo.toml:11-49
| Dependency Category | Key Crates Included |
|---|---|
| Async & Web | tokio, axum, futures, reqwest, tower |
| Data & Serialization | serde, serde_json, toml, prost, sqlx |
| Utilities | anyhow, chrono, clap, regex, itertools |
| Internal Metadata | cargo_metadata, semver |
Sources: examples/crates-io-large-benchmark-workspace/Cargo.toml:11-49
Benchmark Execution Flow
The project utilizes a canonical runner, run-crates-io-benchmark.sh, to execute cooldown operations against these workspaces. This script manages workspace preparation, environment configuration, and artifact collection. Sources: examples/run-crates-io-benchmark.sh:1-20
The benchmark process clones the example workspace into a temporary directory, strips existing lockfiles, and performs multiple samples to ensure statistical relevance. Sources: examples/run-crates-io-benchmark.sh:58-62, examples/run-crates-io-benchmark.sh:162-185
Key Benchmarking Procedures
- Cache Warming: Before measurement, the script runs
cargo updateandcargo fetchto ensure dependencies are available locally, isolating the cooldown resolver's logic from network latency. Sources: examples/run-crates-io-benchmark.sh:111-125 - Fallback Reporting: The runner identifies "fallback inspections"—cases where the tool had to hit the registry API because local index
pubtimemetadata was missing. Sources: examples/run-crates-io-benchmark.sh:205-225 - Isolation: Benchmarks can be run with an isolated
CARGO_HOMEto prevent interference with the developer's global state. Sources: examples/run-crates-io-benchmark.sh:44-55
Manual Smoke Testing Scenarios
Manual checks are facilitated through specialized shell scripts that wrap the benchmark runner with specific presets. Sources: examples/README.md:13-16
A brief sentence explaining what the diagram shows: This diagram illustrates the delegation from user-facing smoke scripts to the core benchmark runner and the underlying cargo-cooldown binary. Sources: examples/run-crates-io-benchmark.sh:25-38, examples/README.md:15-18
Benchmark Configuration
The behavior of the example workspaces during benchmarks is controlled via environment variables:
| Variable | Default Value | Description |
|---|---|---|
SAMPLES | 3 | Number of measurement iterations. |
COOLDOWN_MINUTES | 131401 | The cooldown window (approx 91 days). |
COOLDOWN_ENFORCEMENT | strict | Policy if fresh versions remain. |
COOLDOWN_VERBOSE | 1 | Enables detailed resolver logging. |
BENCH_OFFLINE | 0 | If 1, runs Cargo in offline mode. |
Sources: examples/run-crates-io-benchmark.sh:9-21
Integration with Testing Frameworks
While the example workspaces are designed for manual probes, they are mirrored by a deterministic integration test suite in tests/integration.rs. The integration tests use a RegistryServer to simulate the same scenarios (smoke, large bundles, backtracking) found in the examples but in a controlled, repeatable environment. Sources: tests/integration.rs:105-130, tests/integration.rs:770-790
Example workspaces are also integrated directly into Cargo's benchmarking suite, allowing them to be invoked via standard commands:
cargo bench --bench crates_io_cooldown -- --scenario large-60d
Sources: README.md:100-103, examples/README.md:20-22
The example workspaces provide essential real-world verification for cargo-cooldown, bridging the gap between unit-tested logic and the unpredictable nature of live registry metadata and complex dependency graphs.