Module upgrade

agpm_cli

Module upgrade 

Source
Expand description

Self-update functionality for AGPM.

This module provides comprehensive self-update capabilities for the AGPM binary, allowing users to upgrade to newer versions directly from the command line. The implementation follows safety-first principles with automatic backups, rollback capabilities, and robust error handling.

§Architecture Overview

The upgrade system consists of four main components working together:

§Core Components

§Update Process Flow

1. Version Check
   ├── Check cache for recent version info
   └── Fetch latest release from GitHub if needed

2. Backup Creation (unless --no-backup)
   ├── Copy current binary to .backup file
   └── Preserve file permissions on Unix systems

3. Binary Update
   ├── Download new binary from GitHub releases
   ├── Verify download integrity
   └── Replace current binary atomically

4. Post-Update
   ├── Clear version cache
   ├── Clean up backup on success
   └── Restore from backup on failure

§Safety Mechanisms

The upgrade system implements multiple safety mechanisms:

§Automatic Backups

  • Creates backups before any binary modification
  • Preserves file permissions and metadata
  • Automatic restoration on upgrade failure
  • Manual rollback capability via --rollback flag

§Robust Error Handling

  • Validates downloads before replacement
  • Atomic file operations where possible
  • Graceful degradation on permission issues
  • Detailed error messages for troubleshooting

§Cross-Platform Compatibility

  • Handles Windows file locking issues with retry logic
  • Preserves Unix executable permissions
  • Works with various file system layouts
  • Supports different installation methods

§Security Considerations

The upgrade system includes several security measures:

  • Verified Downloads: All downloads are verified against expected checksums
  • GitHub Integration: Only downloads from official GitHub releases
  • Permission Preservation: Maintains original file permissions and ownership
  • Atomic Operations: Minimizes windows of vulnerability during updates

§Usage Patterns

§Basic Update Check

agpm upgrade --check          # Check for updates without installing
agpm upgrade --status         # Show current and latest versions

§Safe Upgrade

agpm upgrade                  # Upgrade to latest with automatic backup
agpm upgrade v0.4.0          # Upgrade to specific version

§Advanced Options

agpm upgrade --force          # Force upgrade even if on latest
agpm upgrade --no-backup      # Skip backup creation (not recommended)
agpm upgrade --rollback       # Restore from backup

§Module Structure

Each submodule has a specific responsibility:

  • self_updater: Core update logic and GitHub integration
  • backup: Backup creation, restoration, and management
  • version_check: Version comparison and caching
  • config: Configuration structures and defaults

§Error Handling

All functions return Result<T, E> for proper error propagation:

use agpm_cli::upgrade::SelfUpdater;

let updater = SelfUpdater::new();
match updater.update_to_latest().await {
    Ok(true) => println!("Updated successfully"),
    Ok(false) => println!("Already on latest version"),
    Err(e) => eprintln!("Update failed: {}", e),
}

§Implementation Notes

  • Direct GitHub API integration for fetching releases
  • Implements async/await for non-blocking operations
  • Supports semver version parsing and comparison
  • Includes comprehensive logging for debugging
  • Designed for minimal external dependencies

Re-exports§

pub use self_updater::ChecksumPolicy;
pub use self_updater::SelfUpdater;
pub use verification::ChecksumVerifier;
pub use version_check::VersionChecker;

Modules§

backup
Backup management for AGPM binary upgrades.
config
Configuration structures for upgrade behavior.
self_updater
Core self-update implementation.
verification
Download verification and integrity checking.
version_check
Version checking and comparison utilities.