Skip to content

ARCHITECTURE_1_software_update.md

Latest commit

 

History

History
298 lines (229 loc) · 14.2 KB

ARCHITECTURE_1_software_update.md

File metadata and controls

298 lines (229 loc) · 14.2 KB
Raw

Software Update Sub-Application Architecture

Overview

The Software Update sub-application is responsible for checking if there is a newer software version available, downloading and updating the ArduPilot Methodic Configurator to the latest version. This ensures users always have access to the latest features, bug fixes, and security updates.

Requirements Analysis

Functional Requirements - Implementation Status

  1. Version Check ✅ IMPLEMENTED

    • ✅ Checks current version against latest via GitHub releases API
    • ✅ Handles network connectivity issues with proper exception handling
    • ✅ Validates version format using packaging.version.parse()
    • ✅ Supports semantic versioning and prerelease versions

  2. Update Detection ✅ IMPLEMENTED

    • ✅ Detects newer versions using semantic version comparison
    • ✅ Distinguishes between version types (major/minor/patch/prerelease)
    • ✅ Uses stable release channel by default (filters pre-releases)
    • ✅ Provides change information from GitHub release body

  3. Download Management ⚠️ PARTIALLY IMPLEMENTED

    • ✅ Downloads from verified GitHub sources with SSL verification
    • ❌ TODO: No checksum or signature validation of downloaded files
    • ❌ TODO: No resume capability for partial downloads
    • ✅ Provides download progress feedback via callback

  4. Installation Process ⚠️ PARTIALLY IMPLEMENTED

    • ✅ Windows: Creates batch file to run installer after app exit
    • ✅ Linux/macOS: Uses pip to install updated package
    • ❌ TODO: No backup of current installation before updating
    • ❌ TODO: No privilege escalation handling for Windows UAC
    • ❌ TODO: No validation of successful installation

  5. User Interface ✅ IMPLEMENTED

    • ✅ Clear update information display with scrollable content
    • ✅ User choice to update or skip with proper button handling
    • ✅ Download and installation progress display
    • ✅ Graceful handling of user cancellation

  6. Error Handling ⚠️ PARTIALLY IMPLEMENTED

    • ✅ Network failures handled with appropriate error messages
    • ❌ TODO: No recovery from corrupted downloads
    • ❌ TODO: No rollback for failed installations
    • ✅ Clear error messages displayed to users

Non-Functional Requirements - Implementation Status

  1. Security ⚠️ PARTIALLY IMPLEMENTED

    • ✅ Downloads from verified GitHub HTTPS sources
    • ✅ SSL certificate validation enabled (verify=True)
    • ❌ TODO: No protection against man-in-the-middle attacks via file integrity checks
    • ✅ Proper certificate and SSL/TLS handling

  2. Performance ✅ IMPLEMENTED

    • ✅ Version checking completes quickly (GitHub API is fast)
    • ✅ Downloads use efficient streaming with 8KB chunks
    • ✅ Non-blocking UI during downloads and installation

  3. Reliability ⚠️ PARTIALLY IMPLEMENTED

    • ❌ TODO: Could corrupt existing installations (no backup mechanism)
    • ✅ Graceful handling of interrupted operations with proper exception handling
    • ✅ System stability maintained during updates (uses separate processes)
    • ❌ TODO: No rollback capabilities if update fails

  4. Usability ✅ IMPLEMENTED

    • ✅ Intuitive update process requiring minimal user intervention
    • ✅ Clear and accurate progress feedback with percentage and status messages
    • ✅ Actionable and user-friendly error messages

Architecture

Components

Components - Implementation Status

Core Module

  • File: data_model_software_updates.py ✅ IMPLEMENTED
  • Purpose: Contains the business logic for version checking, downloading, and installation orchestration
  • Key Classes:
    • UpdateManager: Handles user interaction and installation coordination
    • format_version_info(): Cleans and formats release notes for display
    • check_for_software_updates(): Main entry point function
  • Actual Dependencies:
    • packaging.version for semantic version comparison ✅
    • requests for HTTP operations (via backend_internet) ✅
    • webbrowser for opening GitHub releases page ✅
    • platform for OS-specific installation logic ✅
    • re for release notes formatting ✅

User Interface

  • File: frontend_tkinter_software_update.py ✅ IMPLEMENTED
  • Purpose: Provides the GUI dialog for user interaction during update process
  • Key Classes:
    • UpdateDialog: Main dialog window with version info and progress display
  • Actual Dependencies:
    • tkinter and tkinter.ttk for GUI components ✅
    • ScrollFrame for scrollable release notes display ✅
    • BaseWindow for consistent window behavior ✅
    • ❌ TODO: No threading - uses callback-based progress updates instead

Backend Internet Module

  • File: backend_internet.py ✅ IMPLEMENTED
  • Purpose: Handles actual download and installation operations
  • Key Functions:
    • get_release_info(): GitHub API communication
    • download_and_install_on_windows(): Windows-specific installer handling
    • download_and_install_pip_release(): Linux/macOS pip installation
    • download_file_from_url(): File download with progress tracking
  • Actual Dependencies:
    • requests with SSL verification ✅
    • subprocess for Windows batch file execution ✅
    • tempfile for secure temporary directories ✅
    • os for system operations ✅

Data Flow - Implementation Status

  1. Application Startup Check ✅ IMPLEMENTED

    • Main application calls check_for_software_updates() during startup
    • Function checks current version from __version__ and gets git hash
    • Skippable via --skip-check-for-updates command line argument

  2. Version Retrieval and Comparison ✅ IMPLEMENTED

    • Calls get_release_info("/latest", should_be_pre_release=False) from backend_internet
    • Uses GitHub releases API to get latest stable release information
    • Compares versions using packaging.version.parse() for semantic versioning

  3. Update Available Decision ✅ IMPLEMENTED

    • If current >= latest, logs "Already running latest version" and returns False
    • If update available, formats version info and opens GitHub releases page in browser
    • Creates UpdateDialog with version information and download callback

  4. User Interaction Phase ✅ IMPLEMENTED

    • UpdateDialog shows scrollable version information with release notes
    • User can choose to download/install or cancel via dialog buttons
    • Progress bar appears during download/installation process

  5. Download and Installation Phase ⚠️ PARTIALLY IMPLEMENTED

    • Windows: Downloads .exe installer to temp directory, creates batch file for post-exit installation
    • Linux/macOS: Uses pip to install updated package directly
    • ✅ Progress callback provides real-time feedback during download
    • ❌ TODO: No integrity validation of downloaded files
    • ❌ TODO: No backup of current installation before update

  6. Application Exit for Update ✅ IMPLEMENTED

    • Windows: Main application exits (os._exit(0)) to allow installer to run
    • Linux/macOS: Application continues after pip installation completes
    • Update process returns True to signal main application to exit

Integration Points - Implementation Status

  • ✅ Main Application: Called from __main__.py during startup before other sub-applications
  • ❌ TODO: Configuration System: No update preferences stored - uses hardcoded behavior (stable releases only)
  • ✅ Logging System: Uses standard Python logging for all update activities and errors
  • ✅ File System:
    • Windows: Uses tempfile.TemporaryDirectory() for secure temporary file handling
    • Both platforms: Manages installer/package downloads and cleanup
  • ✅ Internet Backend: Uses backend_internet.py for GitHub API communication and file downloads
  • ✅ Frontend Components: Uses BaseWindow and ScrollFrame for consistent UI behavior

Security Considerations

  • ✅ SSL/TLS Verification: All downloads use verify=True for SSL certificate validation
  • ✅ Verified Sources: Updates only come from GitHub releases API with HTTPS
  • ❌ TODO: File Integrity Verification: No checksum or signature validation of downloaded files
  • ❌ TODO: Privilege Escalation Handling: Windows installer runs with inherited privileges, no UAC handling
  • ❌ TODO: Backup Mechanisms: No automatic backup of current installation before update
  • ❌ TODO: Rollback Capabilities: No rollback mechanism if update fails

Error Handling Strategy

  • ✅ Network Errors: Comprehensive handling of RequestException, Timeout, and connection errors
  • ✅ Download Corruption: Validates response status codes and handles stream errors
  • ✅ Installation Failures: Exception handling with logging for Windows and pip installation failures
  • ✅ Permission Errors: Catches OSError for file system permission issues
  • ✅ User Feedback: Clear error messages logged and displayed to users
  • ❌ TODO: Retry Logic: No automatic retry with exponential backoff implemented
  • ❌ TODO: Recovery Mechanisms: No automatic recovery from partial downloads or failed installations

Testing Strategy

  • ✅ Unit Tests: Comprehensive unit tests for version comparison, format functions, and core logic (574 lines of tests)
  • ✅ Integration Tests: Tests for download and installation workflows with mocking
  • ✅ Mock Testing: Extensive mocking of network operations and external dependencies
  • ✅ Error Path Testing: Tests for various error conditions and exception handling
  • ✅ UI Testing: Frontend dialog tests with proper setup and teardown
  • ✅ Platform Testing: Tests for Windows, Linux, and macOS specific code paths
  • ✅ Version Handling: Tests for prerelease versions, malformed tags, and edge cases
  • ❌ TODO: Security Testing: No tests for SSL/TLS verification or malicious download protection
  • ❌ TODO: Real Network Testing: All tests use mocking, no integration with actual GitHub API

File Structure - Implementation Status

data_model_software_updates.py          # Core update logic and orchestration ✅
frontend_tkinter_software_update.py     # GUI dialog interface ✅
backend_internet.py                     # Download and installation backend ✅
tests/test_data_model_software_updates.py        # Unit tests for core logic ✅
tests/test_frontend_tkinter_software_update.py   # UI dialog tests ✅

Additional Supporting Files ✅:

  • backend_filesystem.py - Used for git hash retrieval
  • frontend_tkinter_base_window.py - Base window class
  • frontend_tkinter_scroll_frame.py - Scrollable content widget

Dependencies

Actual Implementation Dependencies

Core Module (data_model_software_updates.py):

  • packaging.version for version comparison (✅ present)
  • requests for HTTP operations (✅ present)
  • webbrowser for opening release URLs (✅ present)
  • platform for OS detection (✅ present)
  • re for text processing (✅ present)

Backend Internet (backend_internet.py):

  • requests with timeout and SSL verification (✅ present)
  • subprocess for Windows installer execution (✅ present)
  • tempfile for secure temporary file handling (✅ present)
  • os for system operations and environment variables (✅ present)

Frontend (frontend_tkinter_software_update.py):

  • tkinter and tkinter.ttk for GUI components (✅ present)
  • Custom ScrollFrame for scrollable content (✅ present)
  • BaseWindow for consistent UI behavior (✅ present)

Missing Dependencies:

  • ❌ hashlib - listed but not used for file verification
  • ❌ shutil - listed but not used in actual implementation
  • ❌ threading - listed but GUI uses callback-based progress updates instead

Code Quality Analysis

Strengths

  1. Comprehensive Error Handling: All major exception types are caught and handled
  2. Internationalization Support: All user-facing strings use _() for translation
  3. Clean Separation of Concerns: Business logic separated from UI logic
  4. Progress Feedback: Real-time progress updates during downloads
  5. Cross-Platform Support: Different installation methods for Windows vs Linux/macOS
  6. Extensive Test Coverage: 574 lines of comprehensive unit tests
  7. SSL Security: Proper SSL verification and certificate handling

Critical Security Gaps

  1. No File Integrity Verification: Downloaded files are not validated with checksums
  2. No Backup Mechanism: Current installation could be corrupted without recovery
  3. No Rollback Capability: Failed installations cannot be automatically reversed
  4. Windows Security: Batch file execution could be exploited if temp directory is compromised

Performance Considerations

  1. Efficient Downloads: Uses streaming with 8KB chunks for large files
  2. Non-blocking UI: Progress callbacks prevent UI freezing
  3. Process Isolation: Windows installer runs in separate detached process

Missing Production-Ready Features

  1. Retry Logic: No automatic retry with exponential backoff for failed downloads
  2. Resume Capability: Cannot resume interrupted downloads
  3. Installation Validation: No verification that installation completed successfully
  4. Configuration Management: No user preferences for update behavior

Recommendations for Production Deployment

High Priority TODO Items

  1. Implement file integrity verification using checksums from GitHub release assets
  2. Add backup mechanism before attempting installation
  3. Implement rollback capability for failed installations
  4. Add retry logic with exponential backoff for network operations

Medium Priority TODO Items

  1. Add installation validation to verify successful updates
  2. Implement resume capability for interrupted downloads
  3. Add user configuration for update preferences
  4. Enhance Windows security by validating temp directory permissions

Low Priority TODO Items

  1. Add real network integration tests (currently all tests use mocking)
  2. Implement update scheduling based on user preferences
  3. Add differential updates for smaller download sizes
  4. Enhance logging with structured logging for better debugging