# Rollback Implementation

This document explains how the rollback functionality works in the APT wrapper.

## Overview

The rollback system provides a simple way to undo package installations and upgrades. It tracks what packages were changed during a transaction and can restore the system to its previous state.

## How It Works

### Package Tracking

The `AptTransaction` struct tracks two types of package changes:

- **`newly_installed`**: Packages that weren't installed before the transaction
- **`upgraded`**: Packages that were upgraded, with their previous versions stored

### Two-Phase Rollback

When `rollback()` is called, it performs two phases:

1. **Phase 1 - Remove New Packages**: Uses `apt remove -y` to remove all packages in `newly_installed`
2. **Phase 2 - Downgrade Upgraded Packages**: Uses `apt install -y package=oldversion` to restore previous versions

### Example Usage

```rust
use apt_wrapper::AptTransaction;

// Create and commit a transaction
let mut tx = AptTransaction::new()?;
tx.add_package("vim")?;
tx.add_package("curl")?;
tx.commit()?;

// Later, rollback the changes
tx.rollback()?;
```

### Error Handling

The rollback system uses a "fail fast" approach:

- **Critical errors** (package not found, permission denied) cause immediate failure
- **Soft errors** (package already removed) generate warnings but continue
- If a specific version can't be installed, the package is removed instead

### Limitations

This implementation is intentionally simple and handles the most common rollback scenarios:

- ✅ New package installations
- ✅ Package upgrades with available previous versions
- ✅ Mixed transactions (some new, some upgrades)

It does **not** handle:
- Complex dependency changes
- Configuration file modifications
- System state beyond package versions
- Concurrent package operations

For more advanced rollback scenarios, see [rollbacks-not-featured.md](rollbacks-not-featured.md).

## Implementation Details

### Data Structures

```rust
pub struct AptTransaction {
    packages: Vec<String>,
    newly_installed: HashSet<String>,  // packages that weren't installed before
    upgraded: HashMap<String, String>, // package -> old_version for upgrades
}
```

### Key Methods

- `add_package()`: Adds a package to the transaction
- `commit()`: Installs packages and categorizes them as new vs upgraded
- `rollback()`: Performs the two-phase rollback process
- `changed_packages()`: Returns a list of what was changed

### State Management

The tracking fields (`newly_installed`, `upgraded`) are only populated after a successful `commit()`. This ensures the rollback data reflects what actually happened during the transaction.

## Testing

The rollback functionality is tested in the test suite, but actual package installation/removal is not performed in tests to avoid side effects on the test environment.