agent-migrate-core 0.6.1

Core models and transactional filesystem engine for agent configuration migration
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

use std::path::Path;

use crate::transaction::conflict::resolve_plan;
use crate::transaction::filesystem::FileSystem;
use crate::transaction::snapshot_store::SnapshotStore;
use crate::transaction::{
    SnapshotId, TransactionError, TransactionOptions, TransactionResult, WritePlan,
};

#[derive(Debug, Clone, Copy)]
pub struct TransactionEngine {
    private_mode: u32,
}

impl Default for TransactionEngine {
    fn default() -> Self {
        Self {
            private_mode: 0o600,
        }
    }
}

impl TransactionEngine {
    /// Applies a write plan atomically enough to restore all touched files on failure.
    ///
    /// # Errors
    ///
    /// Returns an error for conflicts, locks, unsafe paths, I/O failure, or failed doctor.
    pub fn apply<F>(
        self,
        plan: &WritePlan,
        options: &TransactionOptions,
        doctor: F,
    ) -> Result<TransactionResult, TransactionError>
    where
        F: FnOnce(&Path) -> Result<(), String>,
    {
        let filesystem = FileSystem::new(self.private_mode);
        let resolved = resolve_plan(plan, options.root(), options.conflict_policy())?;
        preflight(&resolved, options)?;
        let snapshot_id = SnapshotId::new();
        if options.is_dry_run() {
            return Ok(TransactionResult {
                snapshot_id,
                dry_run: true,
                writes: resolved.len(),
            });
        }
        FileSystem::prepare_roots(options)?;
        let _lock = FileSystem::acquire_lock(options)?;
        let snapshots = SnapshotStore::new(filesystem, options);
        snapshots.create(snapshot_id, &resolved)?;
        for write in resolved.writes() {
            let target = options.root().join(write.path.as_path());
            if let Err(error) =
                filesystem.atomic_write(options.root(), &target, &write.content, write.mode)
            {
                return match snapshots.restore(snapshot_id) {
                    Ok(()) => Err(error),
                    Err(rollback) => Err(TransactionError::RollbackFailed {
                        message: format!("{error}; {rollback}"),
                    }),
                };
            }
        }
        if let Err(message) = doctor(options.root()) {
            return match snapshots.restore(snapshot_id) {
                Ok(()) => Err(TransactionError::DoctorFailed { message }),
                Err(rollback) => Err(TransactionError::RollbackFailed {
                    message: format!("{message}; {rollback}"),
                }),
            };
        }
        Ok(TransactionResult {
            snapshot_id,
            dry_run: false,
            writes: resolved.len(),
        })
    }

    /// Restores every file recorded by a transaction snapshot.
    ///
    /// # Errors
    ///
    /// Returns an error when the snapshot is absent, invalid, locked, or cannot be restored.
    pub fn rollback(
        self,
        snapshot_id: SnapshotId,
        options: &TransactionOptions,
    ) -> Result<(), TransactionError> {
        let filesystem = FileSystem::new(self.private_mode);
        FileSystem::prepare_roots(options)?;
        let _lock = FileSystem::acquire_lock(options)?;
        SnapshotStore::new(filesystem, options).restore(snapshot_id)
    }
}

fn preflight(plan: &WritePlan, options: &TransactionOptions) -> Result<(), TransactionError> {
    for write in plan.writes() {
        FileSystem::ensure_path_safe(options.root(), write.path.as_path())?;
    }
    Ok(())
}