CodexRustDownload Documentation

A comprehensive technical documentation guide for the Rust desktop downloader application.

This documentation is written in English and follows rustdoc writing principles for clear summaries, layered detail, and practical guidance.

Table of Contents

• 1. Overview
• 2. High-Level Architecture
• 3. Runtime and Application Lifecycle
• 4. UI Architecture and Interaction Flow
• 5. Download Backends
  • 5.1 HTTP Backend
  • 5.2 Azure Blob SDK Backend
• 6. Download Artifacts and File Layout
• 7. Progress, Speed, and ETA Model
• 8. Pause, Resume, and Cancel Semantics
• 9. Error Handling and Reliability
• 10. Localization
• 11. Icons, Fonts, and Visual Behavior
• 12. Module Reference
• 13. Build and Run
• 14. Testing Scenarios
• 15. Known Tradeoffs

---

1. Overview

CodexRustDownload is a native desktop downloader built with egui/eframe and tokio.

It supports:

• Product selection from a remote API.
• Resumable chunk-based downloads.
• Multiple backends (HTTP and Azure Blob SDK alternative path).
• Pause / Resume / Cancel lifecycle operations.
• Progress reporting with stabilized ETA.
• Download integrity verification via hash checks.

The application is optimized for practical installer distribution workflows where reliability, resumability, and a responsive UI are required.

---

2. High-Level Architecture

The system is organized into 3 main layers:

1. UI Layer (app.rs, app/actions.rs)

   • Renders controls, status, and dialogs.
   • Handles user actions and UI state transitions.
   • Polls async channels/handles and reacts to terminal statuses.

2. Download Orchestration Layer (downloader.rs)

   • Exposes start APIs and backend selection.
   • Manages progress channels and task spawning.
   • Coordinates retry loops and lifecycle transitions.

3. Backend/Execution Layer (downloader/*)

   • HTTP chunk worker, assembly, verify, retry helpers.
   • Azure SDK architecture path (service-style decomposition).
   • File artifact management (.partN, .download_info).

---

3. Runtime and Application Lifecycle

Entry point: src/main.rs

Startup sequence

1. Initialize logging (stderr sink).
2. Build a multithread Tokio runtime.
3. Configure native viewport (title, size, icon).
4. Apply custom font stack to egui context.
5. Start Codex365App.

Why runtime is not entered on main thread

The runtime is intentionally not entered on the UI thread to avoid event-loop contention between Tokio IO drivers and window message pumping on Windows.

This keeps the app responsive during intensive async activity.

---

4. UI Architecture and Interaction Flow

Primary UI state is stored in Codex365App:

• API loading phase (LoadingApi, Ready, ApiError).
• Selected product and backend.
• Active DownloadHandle (or terminal cached status).
• Timing information (download_start, download_elapsed).
• Dialog flags and error messaging.

UI flow summary

1. App loads product catalog from API asynchronously.
2. User selects product, method, and folder.
3. User starts download.
4. UI polls progress handle each frame.
5. Terminal states (Done, Failed, Cancelled) update UI and cleanup behavior.

---

5. Download Backends

Backend enum: DownloaderBackend

• Http
• AzureBlobSdk

Selection is done via UI ComboBox in the Status/Controls section.

5.1 HTTP Backend

Implemented by downloader.rs + downloader/chunk_worker.rs.

Key characteristics:

• Parallel range requests over HTTP.
• Per-chunk resumability based on existing .partN size.
• Chunk worker cancellation and pause-aware loops.
• Retry wrapper with backoff for transient failures.

5.2 Azure Blob SDK Backend

Implemented in downloader/azure_blob_sdk.rs with a Core-style decomposition:

• AzureDownloadConfiguration
• AzureBlobStorageService
• AzureStateRepository
• AzureDownloadService

Key characteristics:

• Uses token credential chain (Azure Identity) and Blob SDK client.
• Parallel ranged chunk retrieval.
• State snapshot writes to .download_info.
• Reuses shared assembly and verification modules.

---

6. Download Artifacts and File Layout

For a selected file <filename> in selected download directory:

• <filename>.part0
• <filename>.part1
• ...
• <filename>.partN
• <filename>.download_info

Behavior:

• .partN files are partial chunk data.
• .download_info is state/progress artifact.
• On successful assembly and completion, final target file is produced.
• On cancel, cleanup removes .partN, .download_info, and legacy temp artifacts.

---

7. Progress, Speed, and ETA Model

Progress type: DownloadProgress.

Fields include:

• bytes_done
• total_bytes
• speed_bps
• eta_secs
• status

ETA stabilization

ETA uses elapsed-time average speed:

• avg_speed = bytes_done / elapsed_total
• eta = remaining / avg_speed

This avoids heavy fluctuations seen with very short instantaneous windows.

---

8. Pause, Resume, and Cancel Semantics

Pause

• Sets paused flag in DownloadHandle.
• Workers flush buffers and wait on resume/cancel notification.

Resume

• Clears paused flag.
• Notifies waiting workers.
• Workers reconnect/re-enter chunk streaming loop.

Cancel

• Cancels token and wakes paused workers.
• UI transitions to cancelled state and performs asynchronous cleanup.
• Guard window prevents immediate restart race after cancel.

---

9. Error Handling and Reliability

Error type: AppError (src/error.rs).

Main categories:

• Network / IO failures
• Missing URI / invalid data
• Hash mismatch
• Cancelled flow
• Assemble failures

Reliability techniques:

• Retry loop with delay/backoff.
• Cancellation-aware select loops.
• Background cleanup to avoid blocking UI thread.
• Clear terminal status propagation to UI.

---

10. Localization

Localization source: src/localization.rs

• Supports English and Georgian.
• Uses Strings struct with all UI text keys.
• Language toggle swaps static string table at runtime.

---

11. Icons, Fonts, and Visual Behavior

Fonts

Configured in main.rs:

• Segoe UI (primary Latin/English quality)
• Sylfaen (Georgian support)
• Embedded NotoSans fallback

Application icon

• Build-time embedding via build.rs (winres + app.ico).
• Runtime viewport icon assignment in main.rs.

UI styling

Current UI uses card-style section frames and compact control layout for a more modern appearance.

---

12. Module Reference

src/main.rs

Application bootstrap, runtime creation, font/icon setup, app startup.

src/app.rs

Main UI state, frame update loop, view rendering, terminal status reactions.

src/app/actions.rs

Action handlers:

• start download
• restart download
• cancel confirm
• cancel artifact cleanup

src/downloader.rs

Top-level downloader orchestration and backend dispatch.

src/downloader/chunk_worker.rs

HTTP chunk worker implementation with pause/cancel-aware loops.

src/downloader/azure_blob_sdk.rs

Azure backend architecture and orchestration service.

src/downloader/assemble.rs

Part concatenation into final file.

src/downloader/verify.rs

Hash verification with progress updates.

src/downloader/progress.rs

Progress send helper + repaint trigger.

src/downloader/retry.rs

Retry wait helper with cancellation awareness.

src/models.rs

Domain models: downloads, status enums, progress snapshots.

src/error.rs

Unified application error enum.

src/localization.rs

Language enum and localized string tables.

---

13. Build and Run

From project root (Codex365DownloaderV3):

cargo build
cargo run

Build with Azure backend feature enabled:

cargo run --features azure_blob_sdk

Windows GNU setup details (recommended for this repository):

• docs/windows-gnu-setup.md

---

14. Testing Scenarios

Recommended manual scenarios:

1. Start HTTP download → pause → resume → cancel.
2. Start HTTP download → cancel → immediate restart.
3. Start Azure SDK download path on blob URL.
4. Verify .partN + .download_info creation in selected folder.
5. Confirm cleanup after cancel.
6. Hash verification success/failure path.

---

15. Known Tradeoffs

• HTTP backend is the most mature path.
• Azure SDK backend is architecturally integrated but may not yet have exact parity for all nuanced retry/circuit-breaker behavior.
• Task manager icon display can still be influenced by Windows icon cache behavior outside application code.

---

Documentation Notes

This file is intended as the primary engineering documentation for contributors and maintainers.

For API-level docs, continue adding targeted /// and //! rustdoc comments directly to public modules, structs, and functions.