apt-ostree/docs/apt-ostree-daemon-plan/architecture/architecture.md

apt-ostree Architecture

Overview

apt-ostree follows the same daemon-client architecture as rpm-ostree, providing a robust, secure, and scalable system for atomic package management. The architecture ensures proper privilege separation, transaction management, and system reliability.

Core Architecture

Daemon-Client Model

┌─────────────────────────────────────────────────────────────┐
│                    apt-ostree (Client)                      │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   CLI       │  │   Parser    │  │   Client    │         │
│  │ Commands    │  │   Options   │  │   Library   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ D-Bus Communication
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   apt-ostreed (Daemon)                      │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   D-Bus     │  │ Transaction │  │   System    │         │
│  │ Interface   │  │  Manager    │  │ Operations  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ System Calls
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    System Layer                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   OSTree    │  │     APT     │  │ Bubblewrap  │         │
│  │ Operations  │  │ Operations  │  │ Sandboxing  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Component Details

1. Client (apt-ostree)

Purpose: User interface and command processing

Key Responsibilities:

• Parse command-line arguments
• Validate user input
• Communicate with daemon via D-Bus
• Format output for user consumption
• Handle fallback to client-only operations

Key Components:

• main.rs: Command-line interface and dispatch
• daemon_client.rs: D-Bus communication library
• system.rs: Client-only fallback operations

Architecture Pattern:

// Daemon-based command with fallback
let result = call_daemon_with_fallback(
    |client| Box::pin(client.install_packages(packages.clone(), yes, dry_run)),
    || Box::pin(async {
        // Fallback to client-only if daemon unavailable
        let system = AptOstreeSystem::new("debian/stable/x86_64").await?;
        system.install_packages(&packages, yes).await?;
        Ok("Packages installed successfully".to_string())
    })
).await?;

2. Daemon (apt-ostreed)

Purpose: Privileged operations and system management

Key Responsibilities:

• Handle all privileged operations
• Manage OSTree repository operations
• Execute APT package operations
• Provide transaction management
• Implement security policies

Key Components:

• src/bin/apt-ostreed.rs: Main daemon process
• D-Bus interface implementation
• Transaction management
• System integration

Architecture Pattern:

#[dbus_interface(name = "org.aptostree.dev.Daemon")]
impl AptOstreeDaemon {
    async fn install_packages(&self, packages: Vec<String>, yes: bool, dry_run: bool) -> zbus::fdo::Result<String> {
        // Privileged package installation logic
        // Transaction management
        // Error handling and rollback
    }
}

3. D-Bus Communication

Interface: org.aptostree.dev.Daemon Object Path: /org/aptostree/dev/Daemon

Key Methods:

• ping(): Health check
• status(): System status
• install_packages(): Package installation
• remove_packages(): Package removal
• upgrade_system(): System upgrade
• rollback(): System rollback

Communication Pattern:

// Client side
let client = DaemonClient::new().await?;
let result = client.install_packages(packages, yes, dry_run).await?;

// Daemon side
async fn install_packages(&self, packages: Vec<String>, yes: bool, dry_run: bool) -> zbus::fdo::Result<String> {
    // Implementation
}

Security Architecture

Privilege Separation

┌─────────────────┐    Unprivileged    ┌─────────────────┐
│   User Space    │ ◄────────────────► │   Daemon Space  │
│   (Client)      │                    │   (Privileged)  │
│                 │                    │                 │
│ • CLI Commands  │                    │ • OSTree Ops    │
│ • Option Parsing│                    │ • APT Ops       │
│ • Output Format │                    │ • File System   │
│ • D-Bus Client  │                    │ • D-Bus Server  │
└─────────────────┘                    └─────────────────┘

Security Features

1. D-Bus Policy: Restrictive access control
2. Systemd Service: Proper service isolation
3. Bubblewrap Sandboxing: Script execution isolation
4. Capability Management: Minimal privilege requirements
5. Transaction Rollback: Atomic operations

Transaction Management

Transaction Lifecycle

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Start     │───►│   Execute   │───►│   Commit    │
│ Transaction │    │ Operations  │    │ or Rollback │
└─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Validate    │    │ Monitor     │    │ Update      │
│ Input       │    │ Progress    │    │ System      │
└─────────────┘    └─────────────┘    └─────────────┘

Atomic Operations

1. Pre-transaction: Validate system state
2. Transaction: Execute operations atomically
3. Post-transaction: Update system state
4. Rollback: Restore previous state on failure

Filesystem Architecture

OSTree Integration

/ostree/
├── repo/                    # OSTree repository
│   ├── objects/            # Content-addressed objects
│   ├── refs/               # Branch references
│   └── config              # Repository configuration
├── deploy/                 # Deployments
│   ├── debian/stable/x86_64/  # State root
│   │   ├── deploy/         # Deployment directories
│   │   └── var/            # Persistent state
└── boot/                   # Boot configuration
    ├── loader/             # Bootloader configuration
    └── ostree/             # OSTree boot data

Package Layering

┌─────────────────────────────────────────┐
│              User Packages              │
│  (Layered on top of base deployment)   │
├─────────────────────────────────────────┤
│              Base Deployment            │
│  (Immutable base system)               │
├─────────────────────────────────────────┤
│              OSTree Repository          │
│  (Content-addressed storage)           │
└─────────────────────────────────────────┘

Bubblewrap Integration

Sandboxing Architecture

┌─────────────────────────────────────────┐
│           Bubblewrap Sandbox            │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐      │
│  │   Script    │  │   Package   │      │
│  │ Execution   │  │  Extraction │      │
│  └─────────────┘  └─────────────┘      │
├─────────────────────────────────────────┤
│  Namespace Isolation                    │
│  • User namespace                       │
│  • PID namespace                        │
│  • Mount namespace                      │
│  • Network namespace                    │
└─────────────────────────────────────────┘

Security Controls

1. Namespace Isolation: Complete process isolation
2. Bind Mounts: Read-only system directories
3. Capability Dropping: Minimal capabilities
4. Environment Control: Controlled execution environment

Error Handling

Error Hierarchy

AptOstreeError
├── PermissionDenied
├── DaemonError
│   ├── ConnectionFailed
│   ├── MethodCallFailed
│   └── TransactionFailed
├── PackageError
│   ├── DownloadFailed
│   ├── InstallationFailed
│   └── DependencyError
├── OSTreeError
│   ├── RepositoryError
│   ├── CommitError
│   └── DeploymentError
└── SystemError
    ├── FilesystemError
    ├── NetworkError
    └── ConfigurationError

Recovery Mechanisms

1. Automatic Rollback: Transaction rollback on failure
2. Fallback Operations: Client-only fallback when daemon unavailable
3. Graceful Degradation: Continue operation with reduced functionality
4. Error Reporting: Clear error messages and recovery suggestions

Performance Considerations

Optimization Strategies

1. Parallel Operations: Concurrent package downloads
2. Caching: Package metadata and content caching
3. Hardlink Optimization: OSTree hardlink deduplication
4. Streaming: Large file streaming operations
5. Memory Management: Efficient memory usage patterns

Monitoring

1. Transaction Monitoring: Real-time progress reporting
2. Resource Usage: Memory and CPU monitoring
3. Performance Metrics: Operation timing and throughput
4. Error Tracking: Error rate and type monitoring

Deployment Architecture

System Integration

┌─────────────────────────────────────────┐
│              System Boot                │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐      │
│  │   GRUB      │  │  systemd    │      │
│  │ Bootloader  │  │   Boot      │      │
│  └─────────────┘  └─────────────┘      │
├─────────────────────────────────────────┤
│              OSTree Deployment          │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐      │
│  │   apt-ostree│  │ apt-ostreed │      │
│  │   Client    │  │   Daemon    │      │
│  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────┘

Service Management

1. systemd Integration: Proper service lifecycle management
2. D-Bus Activation: Automatic daemon startup
3. Service Dependencies: Proper dependency management
4. Health Monitoring: Service health checks

Future Architecture Considerations

Scalability

1. Multi-Client Support: Multiple concurrent clients
2. Distributed Operations: Network-based operations
3. Caching Layer: Distributed caching
4. Load Balancing: Operation distribution

Extensibility

1. Plugin Architecture: Extensible functionality
2. API Evolution: Backward-compatible API changes
3. Feature Flags: Optional feature enablement
4. Configuration Management: Flexible configuration

Security Enhancements

1. AppArmor Integration: Mandatory access control
2. SELinux Support: Security context management
3. Audit Integration: Comprehensive audit logging
4. Cryptographic Verification: Package integrity verification