attune/docs/dependencies/dependency-management.md

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:

[workspace.dependencies]
# Add your dependency here
my-new-crate = "1.0"

2. Reference in Crate

Edit the specific crate's Cargo.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

# Install cargo-outdated
cargo install cargo-outdated

# Check for outdated dependencies
cargo outdated

Update Specific Dependency

# 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

# 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

# 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:

# 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

# 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:

# 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:

cargo audit
cargo update -p <vulnerable-package>
cargo test

Minor Updates (Monthly)

Update minor versions monthly:

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:

# Check dependency tree
cargo tree -d

# Identify conflicting versions
cargo tree -i <package-name>

# Update to compatible versions in Cargo.toml

Build Cache Issues

Problem: Stale build artifacts causing errors.

Solution:

# Clean build cache
cargo clean

# Rebuild
cargo build

SQLx Type Errors

Problem: error[E0282]: type annotations needed

Solution:

# 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:

# 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

# 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 <package-name>

# 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 <package-name>

# Clean build artifacts
cargo clean

# Generate SQLx query cache
cargo sqlx prepare --workspace

---

References

• Cargo Book - Dependencies
• Cargo Book - Workspaces
• SQLx Documentation
• Cargo Audit
• Semantic Versioning

---

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