# apt-ostree Client-Daemon Architecture

## Executive Summary

apt-ostree implements the same sophisticated client-daemon architecture as rpm-ostree, providing security, reliability, and concurrent operation support while maintaining 100% compatibility with the rpm-ostree interface. The architecture separates privileged system operations from unprivileged user interactions.

## Architecture Overview

### High-Level Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Client    │    │   GUI Client    │    │   API Client    │
│  (apt-ostree)   │    │  (GNOME/KDE)    │    │  (Python/Go)   │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      D-Bus Interface      │
                    │   (org.aptostree.dev)     │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │   apt-ostreed Daemon      │
                    │   (Privileged Service)    │
                    └─────────────┬─────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
    ┌─────▼─────┐         ┌───────▼──────┐         ┌─────▼─────┐
    │ libapt-pkg│         │   libostree  │         │  System   │
    │ (APT/DEB) │         │ (Filesystem) │         │ Services  │
    └───────────┘         └──────────────┘         └───────────┘
```

### Design Principles

1. **Privilege Separation**: Daemon runs with elevated privileges, clients run unprivileged
2. **D-Bus Communication**: Standard system service interface for inter-process communication
3. **Transaction Management**: Atomic operations with rollback capability
4. **Concurrent Operations**: Multiple clients can interact simultaneously
5. **State Persistence**: Daemon maintains system state across operations
6. **100% Compatibility**: Identical interface to rpm-ostree

## Client Architecture

### CLI Client (`apt-ostree`)

**Purpose**: Command-line interface for user interaction

**Key Components**:
- **Command Parser**: Parse command-line arguments
- **D-Bus Client**: Communicate with daemon
- **Progress Handler**: Display operation progress
- **Error Handler**: Handle and display errors
- **Fallback Handler**: Direct system calls if daemon fails

**Implementation**:
```rust
pub struct AptOstreeClient {
    // D-Bus client
    connection: Option<Connection>,
    
    // Command dispatch
    pub fn execute_command(&mut self, args: &[String]) -> Result<(), Error>;
    
    // D-Bus communication
    pub fn connect_to_daemon(&mut self) -> Result<(), Error>;
    pub fn call_daemon_method(&mut self, method: &str, params: &[&str]) -> Result<(), Error>;
    
    // Fallback handling
    pub fn fallback_to_direct_calls(&mut self, args: &[String]) -> Result<(), Error>;
    
    // Progress handling
    pub fn handle_progress(&self, message: &str, percentage: i32);
    pub fn handle_completion(&self, success: bool, result: &str);
}
```

**Command Flow**:
1. Parse command-line arguments
2. Try to connect to daemon via D-Bus
3. If daemon available: Send operation request
4. If daemon unavailable: Use direct system calls
5. Handle progress updates
6. Display results or errors

### GUI Clients (Planned)

**Purpose**: Graphical user interfaces for system management

**Components**:
- **GNOME Software**: Integration with GNOME Software Center
- **KDE Discover**: Integration with KDE Discover
- **Custom GUIs**: Third-party graphical interfaces

**Implementation**:
- Use D-Bus interface for system operations
- Provide user-friendly progress indicators
- Handle authentication via PolicyKit
- Display system status and deployment information

### API Clients (Planned)

**Purpose**: Programmatic interfaces for automation and integration

**Components**:
- **Python Bindings**: Python library for apt-ostree operations
- **Go Bindings**: Go library for apt-ostree operations
- **REST APIs**: HTTP-based interfaces

**Implementation**:
- Direct D-Bus communication
- High-level abstractions for common operations
- Error handling and recovery mechanisms
- Async operation support

## Daemon Architecture

### Core Daemon (`apt-ostreed`)

**Purpose**: Centralized system service for privileged operations

**Key Components**:
- **D-Bus Service**: Expose system management interface
- **Transaction Manager**: Handle atomic operations
- **State Manager**: Maintain system state
- **Resource Manager**: Manage system resources
- **OSTree Detection**: Environment validation

**Implementation**:
```rust
pub struct AptOstreeDaemon {
    // System integration
    package_manager: PackageManager,
    
    // Transaction management
    transactions: HashMap<String, Transaction>,
    
    // D-Bus interface
    connection: Option<Connection>,
    object_manager: Option<ObjectManager>,
    
    // OSTree detection
    ostree_detection: OstreeDetection,
    
    // Service management
    pub fn start_service(&mut self) -> Result<(), Error>;
    pub fn stop_service(&mut self) -> Result<(), Error>;
    pub fn handle_client_connection(&mut self, connection: Connection) -> Result<(), Error>;
}
```

**Service Lifecycle**:
1. Initialize system components
2. Validate OSTree environment
3. Register D-Bus service
4. Start listening for client connections
5. Handle client requests
6. Clean up on shutdown

### D-Bus Interface

**Service Name**: `org.aptostree.dev`

**Main Objects**:
- `/org/aptostree/dev/Sysroot`: System root management
- `/org/aptostree/dev/OS`: Operating system operations

**Key Methods**:
```xml
<interface name="org.aptostree.dev.OS">
    <method name="install_packages">
        <arg name="packages" type="as" direction="in"/>
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="transaction_address" type="s" direction="out"/>
    </method>
    
    <method name="remove_packages">
        <arg name="packages" type="as" direction="in"/>
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="transaction_address" type="s" direction="out"/>
    </method>
    
    <method name="upgrade_system">
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="transaction_address" type="s" direction="out"/>
    </method>
    
    <method name="rollback">
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="transaction_address" type="s" direction="out"/>
    </method>
    
    <method name="show_status">
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="status" type="s" direction="out"/>
    </method>
    
    <method name="list_packages">
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="packages" type="as" direction="out"/>
    </method>
    
    <method name="search_packages">
        <arg name="query" type="s" direction="in"/>
        <arg name="options" type="a{sv}" direction="in"/>
        <arg name="results" type="as" direction="out"/>
    </method>
    
    <method name="show_package_info">
        <arg name="package" type="s" direction="in"/>
        <arg name="info" type="s" direction="out"/>
    </method>
</interface>
```

**Signals**:
```xml
<signal name="TransactionChanged">
    <arg name="transaction_address" type="s"/>
    <arg name="state" type="s"/>
    <arg name="message" type="s"/>
    <arg name="percentage" type="i"/>
</signal>

<signal name="TransactionCompleted">
    <arg name="transaction_address" type="s"/>
    <arg name="success" type="b"/>
    <arg name="result" type="s"/>
</signal>
```

### Transaction Management

**Purpose**: Handle atomic operations with rollback capability

**Transaction Types**:
1. **InstallTransaction**: Package installation with atomic commits
2. **RemoveTransaction**: Package removal with rollback support
3. **UpgradeTransaction**: System upgrades with automatic policies
4. **RollbackTransaction**: Deployment rollback

**Implementation**:
```rust
pub struct Transaction {
    // Transaction state
    state: TransactionState,
    transaction_id: String,
    transaction_type: TransactionType,
    
    // Rollback information
    rollback_points: Vec<RollbackPoint>,
    
    // Progress reporting
    pub fn emit_progress(&self, message: &str, percentage: i32);
    pub fn emit_completion(&self, success: bool, result: &str);
    
    // Atomic execution
    pub fn execute_atomic(&mut self) -> Result<(), Error>;
    pub fn rollback_on_failure(&mut self) -> Result<(), Error>;
    
    // State management
    pub fn set_state(&mut self, new_state: TransactionState);
    pub fn get_state(&self) -> TransactionState;
}
```

**Transaction Lifecycle**:
1. **Initiation**: Client requests operation
2. **Validation**: Validate request parameters and OSTree environment
3. **Preparation**: Set up rollback points
4. **Execution**: Perform operation with progress reporting
5. **Completion**: Finalize operation or rollback
6. **Cleanup**: Clean up resources

### State Management

**Purpose**: Maintain system state across operations

**State Components**:
- **Deployment State**: Current and available deployments
- **Package State**: Installed and layered packages
- **Configuration State**: System configuration
- **Transaction State**: Active and completed transactions

**Implementation**:
```rust
pub struct StateManager {
    // System state
    deployment_state: DeploymentState,
    package_state: PackageState,
    config_state: ConfigurationState,
    
    // State persistence
    pub fn save_state(&self) -> Result<(), Error>;
    pub fn load_state(&mut self) -> Result<(), Error>;
    pub fn sync_state(&mut self) -> Result<(), Error>;
    
    // State queries
    pub fn get_current_deployment(&self) -> Result<DeploymentInfo, Error>;
    pub fn get_available_deployments(&self) -> Result<Vec<DeploymentInfo>, Error>;
    pub fn get_installed_packages(&self) -> Result<Vec<PackageInfo>, Error>;
}
```

## Communication Protocol

### D-Bus Communication

**Connection Setup**:
```rust
// Client connection
let connection = Connection::new_system_sync()?;

// Service registration
let object_manager = ObjectManager::new("/org/aptostree/dev");
```

**Method Calls**:
```rust
// Client method call
let result = connection.call_method(
    Some("org.aptostree.dev"),
    "/org/aptostree/dev/OS",
    Some("org.aptostree.dev.OS"),
    "install_packages",
    &(packages, options),
)?;
```

**Signal Handling**:
```rust
// Client signal connection
connection.add_match(
    "type='signal',interface='org.aptostree.dev.OS',member='TransactionChanged'",
)?;

// Signal handler
connection.add_signal_handler(
    "org.aptostree.dev.OS",
    "TransactionChanged",
    move |msg: &Message| {
        // Handle transaction change
        Ok(())
    },
)?;
```

### Error Handling

**Error Types**:
1. **Network Errors**: Package download failures
2. **Dependency Errors**: Package dependency conflicts
3. **Filesystem Errors**: OSTree operation failures
4. **Permission Errors**: Insufficient privileges
5. **Transaction Errors**: Transaction failures
6. **OSTree Environment Errors**: Non-OSTree system

**Error Propagation**:
```rust
// Daemon error handling
fn handle_error(error: &str, invocation: &MethodInvocation) -> Result<(), Error> {
    invocation.return_error(
        "org.aptostree.dev.Error",
        error,
    )
}

// Client error handling
fn handle_daemon_error(error: &Error) {
    eprintln!("Error: {}", error);
    
    // Provide user guidance based on error type
    match error.kind() {
        ErrorKind::DaemonUnavailable => {
            eprintln!("Daemon is not running. Using direct system calls.");
        }
        ErrorKind::OstreeEnvironment => {
            eprintln!("This system is not running on an OSTree deployment.");
        }
        _ => {}
    }
}
```

## Security Model

### Privilege Separation

**Principle**: Separate privileged operations from unprivileged user operations

**Implementation**:
- **Daemon**: Runs with elevated privileges (root)
- **Client**: Runs with user privileges
- **D-Bus**: Secure communication channel
- **PolicyKit**: Authentication for privileged operations

### Authentication

**PolicyKit Integration**:
```xml
<policyconfig>
    <action id="org.aptostree.dev.upgrade">
        <description>Upgrade system</description>
        <message>Authentication is required to upgrade the system</message>
        <defaults>
            <allow_any>auth_admin</allow_any>
            <allow_inactive>auth_admin</allow_inactive>
            <allow_active>auth_admin</allow_active>
        </defaults>
        <annotate key="org.freedesktop.policykit.exec.path">/usr/libexec/apt-ostreed</annotate>
    </action>
</policyconfig>
```

### Bubblewrap Sandboxing

**Package Script Execution**:
- Execute package scripts in controlled environment
- Use namespace isolation for security
- Restrict filesystem access
- Limit privilege escalation

**Implementation**:
```rust
pub struct BubblewrapSandbox {
    // Sandbox configuration
    namespaces: Vec<Namespace>,
    bind_mounts: Vec<BindMount>,
    security_options: Vec<SecurityOption>,
    
    // Script execution
    pub fn execute_script(&self, script: &str, context: &ScriptContext) -> Result<(), Error>;
    
    // Security controls
    pub fn set_namespace_isolation(&mut self, enabled: bool);
    pub fn add_bind_mount(&mut self, source: &str, target: &str, read_only: bool);
    pub fn set_privilege_restrictions(&mut self, restrictions: Vec<PrivilegeRestriction>);
}
```

## OSTree Environment Detection

### Detection Methods

apt-ostree automatically detects if it's running in an OSTree environment using multiple methods:

1. **Filesystem Detection**: Check for `/ostree` directory
2. **Boot Detection**: Check for `/run/ostree-booted` file
3. **Kernel Parameter Detection**: Check for `ostree` in `/proc/cmdline`
4. **Library Detection**: Try to load OSTree sysroot
5. **Service Detection**: Check for daemon availability

**Implementation**:
```rust
pub struct OstreeDetection {
    // Detection methods
    pub fn detect_filesystem(&self) -> bool;
    pub fn detect_boot(&self) -> bool;
    pub fn detect_kernel_params(&self) -> bool;
    pub fn detect_library(&self) -> bool;
    pub fn detect_service(&self) -> bool;
    
    // Comprehensive detection
    pub fn detect_ostree_environment(&self) -> Result<bool, Error>;
    
    // Error reporting
    pub fn get_detection_error(&self) -> String;
}
```

### Error Handling

When not running in an OSTree environment, apt-ostree provides clear error messages:

```
Error: apt-ostree requires an OSTree environment to operate.

This system does not appear to be running on an OSTree deployment.

To use apt-ostree:
1. Ensure you are running on an OSTree-based system
2. Verify that /ostree directory exists
3. Verify that /run/ostree-booted file exists
4. Ensure you have a valid booted deployment
```

## Concurrent Operations

### Multiple Clients

**Support**: Multiple clients can interact with daemon simultaneously

**Implementation**:
- **Thread-Safe Operations**: All operations are thread-safe
- **Transaction Isolation**: Each operation gets its own transaction
- **Resource Locking**: Prevent conflicting operations
- **Queue Management**: Queue operations when necessary

### Operation Queuing

**Queue Management**:
```rust
pub struct OperationQueue {
    pending_operations: VecDeque<Operation>,
    queue_mutex: Mutex<()>,
    queue_cv: Condvar,
    
    pub fn enqueue_operation(&mut self, operation: Operation);
    pub fn dequeue_operation(&mut self) -> Option<Operation>;
    pub fn has_pending_operations(&self) -> bool;
}
```

## Performance Optimization

### Resource Management

**Memory Management**:
- Efficient memory usage for large operations
- Garbage collection for completed transactions
- Memory pooling for frequently allocated objects

**Disk Management**:
- OSTree deduplication for storage efficiency
- Temporary file cleanup
- Cache management for package downloads

**Network Optimization**:
- Parallel package downloads via APT
- Connection pooling
- Bandwidth optimization

### Caching

**Package Cache**:
- Cache downloaded packages via APT
- Cache package metadata
- Cache dependency resolution results

**State Cache**:
- Cache deployment information
- Cache package lists
- Cache configuration data

## Monitoring and Logging

### Logging

**Log Levels**:
- **DEBUG**: Detailed debugging information
- **INFO**: General information
- **WARNING**: Warning messages
- **ERROR**: Error messages
- **CRITICAL**: Critical errors

**Log Implementation**:
```rust
pub struct Logger {
    pub fn debug(&self, message: &str);
    pub fn info(&self, message: &str);
    pub fn warning(&self, message: &str);
    pub fn error(&self, message: &str);
    pub fn critical(&self, message: &str);
}
```

### Monitoring

**Health Monitoring**:
- Daemon health checks
- Transaction monitoring
- Resource usage monitoring
- Error rate monitoring

**Metrics Collection**:
- Operation success rates
- Performance metrics
- Resource usage statistics
- Error statistics

## Systemd Integration

### Service Definition

**Service File**: `/usr/lib/systemd/system/apt-ostreed.service`

```ini
[Unit]
Description=apt-ostree Daemon
Documentation=man:apt-ostreed(8)
After=network.target

[Service]
Type=dbus
BusName=org.aptostree.dev
ExecStart=/usr/libexec/apt-ostreed
Restart=on-failure
RestartSec=1
User=root
Group=root

[Install]
WantedBy=multi-user.target
Also=apt-ostreed.socket
```

### D-Bus Activation

**Socket File**: `/usr/lib/systemd/system/apt-ostreed.socket`

```ini
[Unit]
Description=apt-ostree D-Bus Socket
Documentation=man:apt-ostreed(8)

[Socket]
ListenStream=/run/dbus/system_bus_socket
SocketUser=root
SocketGroup=root

[Install]
WantedBy=sockets.target
```

## Error Recovery

### Automatic Recovery

**Transaction Rollback**:
- Automatic rollback on transaction failure
- State restoration to previous known good state
- Resource cleanup after rollback

**Daemon Recovery**:
- Automatic daemon restart on failure
- State recovery on daemon restart
- Transaction recovery for incomplete operations

### Manual Recovery

**Recovery Procedures**:
- Manual rollback procedures
- State reset procedures
- Configuration recovery procedures
- Filesystem recovery procedures

## APT Integration

### APT Database Management

**Purpose**: Manage APT database in OSTree context

**Implementation**:
```rust
pub struct AptDatabaseManager {
    // APT integration
    cache: Option<*mut apt_pkg_Cache>,
    depcache: Option<*mut apt_pkg_DepCache>,
    
    // Database operations
    pub fn initialize_database(&mut self) -> Result<(), Error>;
    pub fn update_database(&mut self) -> Result<(), Error>;
    pub fn sync_database(&mut self) -> Result<(), Error>;
    
    // Package tracking
    pub fn track_package(&mut self, package: &str) -> Result<(), Error>;
    pub fn untrack_package(&mut self, package: &str) -> Result<(), Error>;
    pub fn get_tracked_packages(&self) -> Result<Vec<String>, Error>;
}
```

### Package Management

**Purpose**: Handle APT package operations in OSTree context

**Implementation**:
```rust
pub struct AptPackageManager {
    // APT integration
    database_manager: AptDatabaseManager,
    
    // Package operations
    pub fn install_packages(&mut self, packages: &[String]) -> Result<(), Error>;
    pub fn remove_packages(&mut self, packages: &[String]) -> Result<(), Error>;
    pub fn upgrade_system(&mut self) -> Result<(), Error>;
    
    // Package information
    pub fn list_packages(&self) -> Result<Vec<PackageInfo>, Error>;
    pub fn search_packages(&self, query: &str) -> Result<Vec<PackageInfo>, Error>;
    pub fn show_package_info(&self, package: &str) -> Result<PackageInfo, Error>;
}
```

## Future Enhancements

### Planned Features

1. **Container Integration**: Direct container support
2. **Cloud Integration**: Cloud deployment support
3. **Advanced Monitoring**: Enhanced monitoring capabilities
4. **Performance Optimization**: Further performance improvements

### Architecture Improvements

1. **Microservices**: Split daemon into microservices
2. **API Gateway**: REST API gateway for external access
3. **Event Streaming**: Event streaming for real-time updates
4. **Distributed Operations**: Support for distributed operations

### APT Enhancements

1. **Advanced Dependency Resolution**: Enhanced dependency handling
2. **Package Conflict Resolution**: Improved conflict resolution
3. **Repository Management**: Enhanced repository management
4. **Package Verification**: Enhanced package verification

## Daemon Setup and Testing

### Installation and Setup
```bash
# Install daemon binary
sudo cp target/release/apt-ostreed /usr/libexec/

# Install D-Bus configuration
sudo cp src/daemon/org.aptostree.dev.conf /etc/dbus-1/system.d/

# Install systemd service
sudo cp src/daemon/apt-ostreed.service /etc/systemd/system/

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable apt-ostreed
sudo systemctl start apt-ostreed
```

### D-Bus Testing Commands
```bash
# Check daemon status
systemctl status apt-ostreed.service

# List D-Bus services
gdbus list --system | grep aptostree

# Test D-Bus introspection
gdbus introspect --system --dest org.aptostree.dev --object-path /org/aptostree/dev

# Test Ping method
gdbus call --system --dest org.aptostree.dev --object-path /org/aptostree/dev --method org.aptostree.dev.Daemon.Ping

# Test client-daemon communication
apt-ostree daemon-ping
apt-ostree daemon-status
```

### Troubleshooting
```bash
# Check daemon logs
journalctl -u apt-ostreed.service --no-pager -n 20

# Restart daemon
sudo systemctl restart apt-ostreed.service

# Test with authentication
pkexec gdbus call --system --dest org.aptostree.dev --object-path /org/aptostree/dev --method org.aptostree.dev.Daemon.Ping
```

### Directory Structure
```
/usr/
├── bin/apt-ostree                    # Client binary
├── libexec/apt-ostreed               # Daemon binary
└── share/
    ├── dbus-1/system-services/
    │   └── org.aptostree.dev.service # D-Bus activation
    └── polkit-1/actions/
        └── org.aptostree.dev.policy  # Authorization policies

/etc/
├── apt-ostree/apt-ostreed.conf       # Daemon configuration
├── dbus-1/system.d/
│   └── org.aptostree.dev.conf        # D-Bus policy
└── systemd/system/
    ├── apt-ostreed.service           # Main daemon service
    ├── apt-ostree-bootstatus.service # Boot status service
    ├── apt-ostree-countme.service    # Usage reporting service
    ├── apt-ostree-countme.timer      # Weekly timer
    ├── apt-ostreed-automatic.service # Automatic updates
    └── apt-ostreed-automatic.timer   # Daily timer

/var/
├── lib/apt-ostree/                   # OSTree repository and state
├── cache/apt-ostree/                 # APT cache
└── log/apt-ostree/                   # Log files
``` 