apt-ostree/docs/apt-ostree-daemon-plan/development-commands-analysis.md

Development Commands Analysis: rpm-ostree Integration

Overview

This document analyzes the missing development and debugging commands from rpm-ostree that should be integrated into apt-ostree. These commands are marked with RPM_OSTREE_BUILTIN_FLAG_HIDDEN and are essential for development, testing, and debugging purposes.

Commands Analysis

1. testutils Command

Purpose: Development debugging tool for testing and development workflows.

Flags: RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN

Subcommands:

• inject-pkglist - Inject package list metadata into OSTree commits
• script-shell - Run scripts in bubblewrap containers
• generate-synthetic-upgrade - Generate synthetic OS updates by modifying ELF files
• integration-read-only - Run integration tests on booted machine
• c-units - Run C unit tests
• moo - Test command for development verification

Implementation Details:

C++ Side (rpmostree-builtin-testutils.cxx)

// inject-pkglist: Creates new commit with pkglist metadata
// - Reads existing commit
// - Creates RPM database package list
// - Writes new commit with pkglist metadata
// - Updates ref to point to new commit

// script-shell: Runs scripts in isolated containers
// - Uses bubblewrap for containerization
// - Mounts root filesystem
// - Executes test scripts safely

Rust Side (testutils.rs)

// generate-synthetic-upgrade: Modifies ELF binaries
// - Finds ELF files in system directories
// - Mutates specified percentage of binaries
// - Creates new OSTree commit with modified files
// - Useful for testing upgrade paths

// integration-read-only: Validates system state
// - Tests status JSON parsing
// - Validates package variants
// - Ensures client bindings work correctly

Integration Plan for apt-ostree:

1. Create src/commands/testutils.rs module
2. Implement all subcommands with APT equivalents
3. Add to CLI with hidden flag
4. Integrate with existing command structure

2. shlib-backend Command

Purpose: Shared library backend for IPC operations and package management.

Flags: RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN

Subcommands:

• get-basearch - Get base architecture
• varsubst-basearch - Variable substitution for architecture
• packagelist-from-commit - Extract package list from OSTree commit

Implementation Details:

// IPC-based communication using Unix domain sockets
// - Creates sealed memfd for data transfer
// - Uses DNF context for package operations
// - Integrates with OSTree repository operations
// - Handles package list extraction and formatting

Integration Plan for apt-ostree:

1. Create src/commands/shlib_backend.rs module
2. Replace DNF with APT equivalents
3. Implement IPC communication layer
4. Add architecture detection and variable substitution
5. Integrate with OSTree operations

3. internals Command

Purpose: Internal system commands for advanced operations.

Status: Referenced in header file but implementation not found in current rpm-ostree source.

Flags: Not specified (likely RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD)

Integration Plan for apt-ostree:

1. Research if this command exists in newer rpm-ostree versions
2. If not implemented, consider what internal operations would be useful
3. Implement as placeholder for future development
4. Add to CLI with appropriate flags

Implementation Strategy

Phase 1: Core Infrastructure

1. Command Structure: Add hidden command support to CLI
2. Flag System: Implement APT_OSTREE_BUILTIN_FLAG_HIDDEN equivalent
3. Module Organization: Create development commands module

Phase 2: testutils Implementation

1. inject-pkglist: APT package list injection
2. script-shell: Bubblewrap container execution
3. synthetic-upgrade: ELF binary modification for testing
4. integration-tests: System validation and testing

Phase 3: shlib-backend Implementation

1. IPC Layer: Unix domain socket communication
2. Package Operations: APT-based package management
3. Architecture Detection: Debian architecture handling
4. Variable Substitution: APT-specific variable handling

Phase 4: Integration and Testing

1. Command Registration: Add to main command dispatch
2. Hidden Flag Support: Implement in CLI help system
3. Testing Framework: Integration with existing test suite
4. Documentation: Developer and testing guides

Technical Considerations

APT vs DNF Differences

• Package Format: DEB vs RPM
• Database Structure: APT cache vs DNF sack
• Architecture Names: Debian vs Red Hat conventions
• Variable Substitution: APT-specific variables

OSTree Integration

• Package Metadata: APT package list format
• Commit Structure: OSTree commit metadata
• Repository Operations: OSTree repo integration
• Deployment Management: System deployment handling

Security and Isolation

• Bubblewrap: Container execution for scripts
• File Descriptors: Secure IPC communication
• Permission Handling: Root and user operations
• Resource Limits: Memory and process constraints

File Structure

src/commands/
├── testutils.rs           # Development testing utilities
├── shlib_backend.rs       # Shared library backend
└── internals.rs           # Internal system commands (future)

src/cli.rs                 # Add hidden command support
src/commands/mod.rs        # Register development commands

CLI Integration

Hidden Command Support

#[derive(Subcommand)]
pub enum Commands {
    // ... existing commands ...
    
    /// Development and debugging tools (hidden)
    #[command(hide = true)]
    Testutils(TestutilsArgs),
    
    /// Shared library backend (hidden)
    #[command(hide = true)]
    ShlibBackend(ShlibBackendArgs),
    
    /// Internal system commands (hidden)
    #[command(hide = true)]
    Internals(InternalsArgs),
}

Flag System

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommandFlags {
    pub local_cmd: bool,
    pub hidden: bool,
    pub requires_root: bool,
    pub container_capable: bool,
    pub supports_pkg_installs: bool,
}

Benefits of Integration

Development Workflow

1. Testing: Automated testing and validation
2. Debugging: Package list inspection and modification
3. Integration: System state validation
4. Scripting: Safe script execution in containers

Quality Assurance

1. Package Management: Validate APT integration
2. OSTree Operations: Test commit and deployment logic
3. System Integration: Verify daemon and client communication
4. Error Handling: Test edge cases and failure modes

Maintenance and Support

1. Troubleshooting: Debug package and deployment issues
2. Development: Rapid iteration and testing
3. Documentation: Generate system state reports
4. Validation: Ensure system consistency

Conclusion

Integrating these development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. The commands are designed to be hidden from normal users while providing powerful capabilities for developers and system administrators.

The implementation should maintain the same logical structure and behavior as rpm-ostree while adapting to APT-specific package management and Debian system conventions. This will ensure that apt-ostree provides the same level of development support as the original rpm-ostree implementation.

Next Steps

1. Research: Verify current rpm-ostree implementation status
2. Design: Create detailed implementation specifications
3. Implementation: Develop commands with proper testing
4. Integration: Add to CLI and command dispatch system
5. Testing: Validate functionality and performance
6. Documentation: Create developer and testing guides