apt-ostree/.notes/research/rust-apt-ostree-integration-research.md

Rust APT + OSTree Integration Research

Executive Summary

After extensive research into available Rust crates for APT and OSTree integration, I've identified the optimal approach for implementing apt-ostree using Rust. The key findings show that rust-apt and ostree crates provide excellent foundations for the project.

Key Findings

1. rust-apt Crate Analysis

Available Crates:

• rust-apt (0.8.0) - Primary APT bindings from Volian
• oma-apt (0.8.3) - Alternative APT bindings from AOSC
• libapt (1.3.0) - Pure Rust APT repository interface
• apt-pkg-native (0.3.3) - Native APT bindings

Recommended: rust-apt (0.8.0)

Repository: https://gitlab.com/volian/rust-apt License: GPL-3.0-or-later Documentation: https://docs.rs/rust-apt/0.8.0

Key Features:

• Complete libapt-pkg bindings - Full access to APT's core functionality
• Safe Rust API - Memory-safe wrappers around C++ libapt-pkg
• Package management - Install, remove, upgrade operations
• Dependency resolution - Full APT dependency solver access
• Repository management - Source list and metadata handling
• Progress reporting - Built-in progress tracking for operations

API Structure:

// Main entry point
use rust_apt::new_cache;

// Core types
use rust_apt::{
    Cache,           // Main cache interface
    Package,         // Individual package representation
    Version,         // Package version information
    Dependency,      // Dependency relationships
    DepCache,        // Dependency resolution cache
    PackageSort,     // Package filtering and sorting
};

// Error handling
use rust_apt::error::AptErrors;

2. ostree Crate Analysis

Available Crates:

• ostree (0.20.3) - Official Rust bindings for libostree
• ostree-ext (0.15.3) - Extension APIs for OSTree
• ostree-sys (0.15.2) - FFI bindings to libostree-1

Recommended: ostree (0.20.3)

Repository: https://github.com/ostreedev/ostree License: MIT Documentation: https://docs.rs/ostree

Key Features:

• Complete libostree bindings - Full OSTree functionality
• Repository management - Create, open, manage OSTree repositories
• Commit operations - Create, checkout, merge commits
• Deployment management - Deploy, rollback, manage bootable deployments
• Content addressing - SHA256-based content addressing
• Atomic operations - Transactional commit and deployment operations

Integration Architecture

1. Core Architecture Design

pub struct AptOstreeSystem {
    // APT components
    apt_cache: Cache,
    apt_depcache: DepCache,
    
    // OSTree components
    ostree_repo: ostree::Repo,
    ostree_sysroot: ostree::Sysroot,
    
    // Integration state
    current_deployment: Option<ostree::Deployment>,
    package_layers: HashMap<String, PackageLayer>,
}

pub struct PackageLayer {
    package_name: String,
    ostree_commit: String,
    dependencies: Vec<String>,
    metadata: PackageMetadata,
}

2. Package Management Workflow

Installation Process:

impl AptOstreeSystem {
    pub fn install_packages(&mut self, packages: &[String]) -> Result<(), AptOstreeError> {
        // 1. Resolve dependencies using rust-apt
        let resolved_packages = self.resolve_dependencies(packages)?;
        
        // 2. Create OSTree commit with package changes
        let commit = self.create_package_commit(&resolved_packages)?;
        
        // 3. Deploy the new commit
        self.deploy_commit(&commit)?;
        
        Ok(())
    }
    
    fn resolve_dependencies(&self, packages: &[String]) -> Result<Vec<Package>, AptErrors> {
        let mut cache = self.apt_cache.clone();
        
        // Mark packages for installation
        for pkg_name in packages {
            if let Some(pkg) = cache.get(pkg_name) {
                pkg.mark_install()?;
            }
        }
        
        // Resolve dependencies
        let depcache = cache.depcache();
        depcache.resolve_dependencies()?;
        
        // Collect resolved packages
        let resolved = cache.packages()
            .filter(|pkg| pkg.marked_install())
            .collect();
            
        Ok(resolved)
    }
}

3. OSTree Integration Strategy

Commit Creation:

impl AptOstreeSystem {
    fn create_package_commit(&self, packages: &[Package]) -> Result<String, OstreeError> {
        // 1. Create mutable tree for new commit
        let mut tree = self.ostree_repo.prepare_transaction()?;
        
        // 2. Add package files to tree
        for package in packages {
            self.add_package_to_tree(&mut tree, package)?;
        }
        
        // 3. Add package metadata
        let metadata = self.create_package_metadata(packages);
        tree.set_metadata("packages", &metadata)?;
        
        // 4. Commit the transaction
        let commit = tree.commit("Package installation")?;
        
        Ok(commit)
    }
    
    fn add_package_to_tree(&self, tree: &mut ostree::MutableTree, package: &Package) -> Result<(), OstreeError> {
        // Extract package files
        let files = self.extract_package_files(package)?;
        
        // Add files to OSTree tree
        for (path, content) in files {
            tree.add_file(&path, content)?;
        }
        
        Ok(())
    }
}

Implementation Roadmap

Phase 1: Core Integration (Weeks 1-2)

1.1 Set up Rust Development Environment

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install APT development libraries
sudo apt update
sudo apt install libapt-pkg-dev libostree-dev

# Create new Rust project
cargo new apt-ostree
cd apt-ostree

1.2 Cargo.toml Configuration

[package]
name = "apt-ostree"
version = "0.1.0"
edition = "2021"