# Dependency Management Guide This guide covers how to manage dependencies in the Attune project. --- ## Current Dependency Versions (as of 2026-01-17) ### Core Dependencies | Category | Package | Version | Purpose | |----------|---------|---------|---------| | **Async Runtime** | tokio | 1.49.0 | Async runtime and I/O | | | tokio-util | 0.7 | Tokio utilities | | | async-trait | 0.1 | Async trait support | | | futures | 0.3 | Futures utilities | | **Web Framework** | axum | 0.7.9 | HTTP server framework | | | tower | 0.5.3 | Service abstraction | | | tower-http | 0.6 | HTTP middleware | | **Database** | sqlx | 0.8.6 | PostgreSQL async driver | | | sea-query | 0.31 | Query builder | | | sea-query-postgres | 0.5 | PostgreSQL dialect | | **Message Queue** | lapin | 2.5.5 | RabbitMQ client | | | redis | 0.27.6 | Redis client | | **Serialization** | serde | 1.0 | Serialization framework | | | serde_json | 1.0 | JSON support | | **Security** | argon2 | 0.5 | Password hashing | | | ring | 0.17 | Cryptography | | | aes-gcm | 0.10 | AES encryption | | | sha2 | 0.10 | SHA hashing | | | base64 | 0.22 | Base64 encoding | --- ## Workspace Dependency Management Attune uses Cargo's workspace feature to manage dependencies centrally. ### Structure ``` attune/ ├── Cargo.toml # Workspace root - defines all dependencies └── crates/ ├── common/ │ └── Cargo.toml # References workspace dependencies ├── api/ │ └── Cargo.toml # References workspace dependencies └── ... ``` ### Adding a New Dependency #### 1. Add to Workspace Root Edit `Cargo.toml` in the workspace root: ```toml [workspace.dependencies] # Add your dependency here my-new-crate = "1.0" ``` #### 2. Reference in Crate Edit the specific crate's `Cargo.toml`: ```toml [dependencies] my-new-crate = { workspace = true } ``` ### Benefits of Workspace Dependencies - ✅ Single version across all crates (no version conflicts) - ✅ Centralized version management - ✅ Easier to update (change once, applies everywhere) - ✅ Consistent feature flags across workspace --- ## Updating Dependencies ### Check for Updates ```bash # Install cargo-outdated cargo install cargo-outdated # Check for outdated dependencies cargo outdated ``` ### Update Specific Dependency ```bash # Update a specific dependency to latest compatible version cargo update -p tokio # Update to a specific version cargo update -p tokio --precise 1.49.0 ``` ### Update All Dependencies ```bash # Update all to latest compatible versions cargo update # Update and allow breaking changes (requires Cargo.toml edits) # 1. Edit version in Cargo.toml # 2. Run: cargo update ``` ### Test After Updates ```bash # Build and test cargo build cargo test --workspace # Check for unused dependencies cargo install cargo-udeps cargo +nightly udeps ``` --- ## Security Auditing ### Cargo Audit Install and run security audit: ```bash # Install cargo install cargo-audit # Audit dependencies for known vulnerabilities cargo audit # Fix vulnerabilities where possible cargo audit fix ``` ### GitHub Dependabot Attune uses GitHub Dependabot to automatically: - Monitor dependencies for security vulnerabilities - Create pull requests for security updates - Track outdated dependencies **Configuration:** `.github/dependabot.yml` --- ## SQLx Offline Compilation SQLx requires special handling for query macros. ### Generate Query Cache ```bash # Set database URL export DATABASE_URL="postgresql://user:pass@localhost:5432/attune" # Generate query metadata cache cargo sqlx prepare --workspace # Commit the cache git add .sqlx/ git commit -m "Update SQLx query cache" ``` ### Compile Without Database Once query cache is generated: ```bash # Compile offline using cached query metadata SQLX_OFFLINE=true cargo build ``` ### When to Update Query Cache Update the cache when: - Database schema changes (after running migrations) - SQL queries are added or modified - SQLx version is upgraded --- ## Dependency Update Strategy ### Security Updates (Immediate) Apply security patches as soon as available: ```bash cargo audit cargo update -p cargo test ``` ### Minor Updates (Monthly) Update minor versions monthly: ```bash cargo outdated cargo update cargo build cargo test --workspace ``` ### Major Updates (Quarterly) Plan for major version upgrades: 1. **Review changelog** for breaking changes 2. **Test in development** environment 3. **Update incrementally** (one major dependency at a time) 4. **Run full test suite** 5. **Deploy to staging** for integration testing 6. **Monitor production** after deployment --- ## Common Issues ### Version Conflicts **Problem:** Different crates require incompatible versions. **Solution:** ```bash # Check dependency tree cargo tree -d # Identify conflicting versions cargo tree -i # Update to compatible versions in Cargo.toml ``` ### Build Cache Issues **Problem:** Stale build artifacts causing errors. **Solution:** ```bash # Clean build cache cargo clean # Rebuild cargo build ``` ### SQLx Type Errors **Problem:** `error[E0282]: type annotations needed` **Solution:** ```bash # Set DATABASE_URL export DATABASE_URL="postgresql://user:pass@localhost:5432/attune" # Or generate query cache cargo sqlx prepare --workspace ``` ### Outdated Lockfile **Problem:** `Cargo.lock` out of sync with `Cargo.toml` **Solution:** ```bash # Regenerate lockfile cargo update # Or delete and regenerate rm Cargo.lock cargo build ``` --- ## Best Practices ### Version Pinning - ✅ **DO** use semantic versioning in `Cargo.toml` - ✅ **DO** commit `Cargo.lock` to version control - ❌ **DON'T** use wildcard versions (`*`) in production - ❌ **DON'T** use git dependencies in production ### Testing Updates Before merging dependency updates: 1. ✅ Run full test suite 2. ✅ Check for deprecation warnings 3. ✅ Review dependency changelog 4. ✅ Test integration points (database, message queue, HTTP) 5. ✅ Verify no new vulnerabilities (`cargo audit`) ### Documentation When adding dependencies: - Document why the dependency is needed - Note any special configuration requirements - Add to this guide if it's a core dependency --- ## Dependency Review Checklist Before adding a new dependency: - [ ] Is there an existing dependency that provides this functionality? - [ ] Is the crate actively maintained? (check last commit date) - [ ] Does it have a reasonable number of downloads? - [ ] Are there known security issues? (`cargo audit`) - [ ] Is the license compatible? (MIT/Apache 2.0 preferred) - [ ] Does it have minimal transitive dependencies? - [ ] Is the API stable? (version 1.0+) - [ ] Does it support async/await if needed? - [ ] Is it well-documented? --- ## Useful Commands ```bash # Show dependency tree cargo tree # Show dependencies for a specific crate cargo tree -p attune-common # Show why a dependency is included cargo tree -i # Check for duplicate dependencies cargo tree -d # Check for outdated dependencies cargo outdated # Audit for security vulnerabilities cargo audit # Find unused dependencies cargo +nightly udeps # Update all dependencies cargo update # Update specific dependency cargo update -p # Clean build artifacts cargo clean # Generate SQLx query cache cargo sqlx prepare --workspace ``` --- ## References - [Cargo Book - Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) - [Cargo Book - Workspaces](https://doc.rust-lang.org/cargo/reference/workspaces.html) - [SQLx Documentation](https://github.com/launchbadge/sqlx) - [Cargo Audit](https://github.com/rustsec/rustsec) - [Semantic Versioning](https://semver.org/) --- ## Maintenance Schedule ### Weekly - Monitor GitHub Dependabot alerts - Review and merge security updates ### Monthly - Run `cargo outdated` - Update minor versions - Run full test suite - Update query cache if needed ### Quarterly - Review major version upgrades - Plan breaking change migrations - Update this documentation - Audit unused dependencies --- **Last Updated:** 2026-01-17 **Last Dependency Update:** 2026-01-17 **Next Scheduled Review:** 2026-02-17