Phase 1: Self-Update Core Infrastructure

🎯 Objective

Implement the foundational infrastructure for a robust, cross-platform self-update mechanism. This phase establishes version management, GitHub API integration, platform detection, and asset selection logic.

📦 Current Release Asset Convention

Based on .github/workflows/release.yml, releases follow this naming:

• Pattern: zy-{VERSION}-{TARGET}[.exe]
• Examples:
  • zy-1.0.1-x86_64-unknown-linux-gnu
  • zy-1.0.1-aarch64-apple-darwin
  • zy-1.0.1-x86_64-pc-windows-msvc.exe
• Checksums: SHA256SUMS.txt (combined file with all binary hashes)
• Supported Targets:
  • x86_64-unknown-linux-gnu
  • aarch64-unknown-linux-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin
  • x86_64-pc-windows-msvc

🏗️ Implementation Requirements

1. Module Structure

Create src/update/ module with the following files:

src/update/
├── mod.rs              # Public API and exports
├── version.rs          # Semantic version comparison
├── github.rs           # GitHub Releases API client
├── platform.rs         # OS/arch detection
├── asset.rs            # Asset selection logic
├── channel.rs          # Release channel management
└── error.rs            # Typed error definitions

2. Version Management (version.rs)

• Parse semantic versions from Git tags (e.g., v1.0.1 → 1.0.1)
• Compare versions correctly (e.g., 1.0.1 < 1.2.0 < 2.0.0)
• Support pre-release versions (alpha, beta, rc)
• Detect current binary version from env!("CARGO_PKG_VERSION")

Required functionality:

pub struct Version {
    pub major: u64,
    pub minor: u64,
    pub patch: u64,
    pub pre_release: Option<String>,
}

impl Version {
    pub fn parse(s: &str) -> Result<Self, VersionError>;
    pub fn current() -> Self;
    pub fn is_newer_than(&self, other: &Version) -> bool;
}

3. GitHub Releases API Client (github.rs)

• Query GitHub Releases API: GET https://api.github.com/repos/CloudzyVPS/cli/releases
• Handle rate limiting (check X-RateLimit-Remaining header)
• Implement exponential backoff retry logic (max 3 retries)
• Parse release JSON responses
• Filter releases by channel (stable/pre-release)
• Handle network failures gracefully

Required functionality:

pub struct GitHubClient {
    repo_owner: String,
    repo_name: String,
    client: reqwest::Client,
}

pub struct Release {
    pub tag_name: String,
    pub version: Version,
    pub prerelease: bool,
    pub assets: Vec<Asset>,
    pub download_url: String,
}

impl GitHubClient {
    pub fn new(repo_owner: String, repo_name: String) -> Self;
    pub async fn get_latest_release(&self, channel: Channel) -> Result<Release, UpdateError>;
    pub async fn get_all_releases(&self) -> Result<Vec<Release>, UpdateError>;
}

Rate limiting requirements:

• Check X-RateLimit-Remaining and X-RateLimit-Reset headers
• If rate limit is exceeded, return clear error message with reset time
• Implement retry with exponential backoff: 1s, 2s, 4s delays

4. Platform Detection (platform.rs)

Detect the current platform at runtime and map to the correct target triple.

Required functionality:

pub struct Platform {
    pub target: String,
    pub os: String,
    pub arch: String,
    pub extension: Option<String>, // Some(".exe") for Windows, None otherwise
}

impl Platform {
    pub fn current() -> Self;
    pub fn to_target_triple(&self) -> String;
}

Detection logic:

• Use std::env::consts::OS and std::env::consts::ARCH
• Map to exact target triples:
  • Linux x64 → x86_64-unknown-linux-gnu
  • Linux ARM64 → aarch64-unknown-linux-gnu
  • macOS x64 → x86_64-apple-darwin
  • macOS ARM64 → aarch64-apple-darwin
  • Windows x64 → x86_64-pc-windows-msvc
• Set .exe extension only for Windows

5. Asset Selection (asset.rs)

Select the correct binary asset from a GitHub release based on the current platform.

Required functionality:

pub struct Asset {
    pub name: String,
    pub download_url: String,
    pub size: u64,
    pub content_type: String,
}

pub fn select_asset_for_platform(
    assets: &[Asset],
    platform: &Platform,
) -> Result<Asset, UpdateError>;

pub fn parse_asset_name(name: &str) -> Option<(String, String)>; // (version, target)

Selection logic:

• Match asset name against pattern: zy-{VERSION}-{TARGET}[.exe]
• Verify target triple matches current platform
• Validate file extension (.exe for Windows, none for Unix)
• Return error if no matching asset found

6. Channel Management (channel.rs)

Manage release channels (stable, beta, alpha, rc).

Required functionality:

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Channel {
    Stable,
    Beta,
    Alpha,
    ReleaseCandidate,
}

impl Channel {
    pub fn from_version(version: &str) -> Self;
    pub fn should_include_prerelease(&self) -> bool;
}

**Detection logic (matching CI workflow...