heroforge_core/fs/

transaction.rs

//! Transaction management for filesystem operations
//!
//! This module handles grouping multiple filesystem operations into atomic,
//! committable units. Transactions ensure that either all operations succeed
//! or all are rolled back.

use crate::fs::errors::{FsError, FsResult};
use crate::fs::operations::{FsOperation, OperationSummary};
use sha3::{Digest, Sha3_256};
use std::sync::{Arc, Mutex};

/// Transaction mode
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransactionMode {
    /// Read-only transaction - no writes allowed
    ReadOnly,

    /// Read-write transaction - can read and write
    ReadWrite,

    /// Exclusive transaction - no concurrent access
    Exclusive,
}

impl TransactionMode {
    /// Check if mode allows writes
    pub fn allows_writes(&self) -> bool {
        matches!(
            self,
            TransactionMode::ReadWrite | TransactionMode::Exclusive
        )
    }

    /// Check if mode is exclusive
    pub fn is_exclusive(&self) -> bool {
        *self == TransactionMode::Exclusive
    }
}

/// Transaction state
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransactionState {
    /// Transaction is active and accepting operations
    Active,

    /// Transaction has been committed
    Committed,

    /// Transaction has been rolled back
    RolledBack,

    /// Transaction encountered an error
    Error,
}

/// A single transaction containing multiple operations
///
/// # Example
///
/// ```no_run
/// use heroforge_core::Repository;
/// use heroforge_core::fs::{Transaction, TransactionMode};
///
/// // Create a transaction
/// let tx = Transaction::new(TransactionMode::ReadWrite);
///
/// // Transactions are typically used internally by FileSystem and Modify
/// // For high-level operations, use those APIs instead
/// # Ok::<(), heroforge_core::FossilError>(())
/// ```
#[derive(Clone)]
pub struct Transaction {
    /// Unique transaction ID
    id: String,

    /// Transaction mode
    mode: TransactionMode,

    /// Current state
    state: Arc<Mutex<TransactionState>>,

    /// Operations accumulated in this transaction
    operations: Arc<Mutex<Vec<FsOperation>>>,

    /// Operation summary
    summary: Arc<Mutex<OperationSummary>>,

    /// Parent commit hash (if any)
    parent_commit: Option<String>,

    /// Branch name (if applicable)
    branch: Option<String>,

    /// Timestamp of transaction creation
    created_at: i64,

    /// Maximum operations allowed (0 = unlimited)
    max_operations: usize,
}

impl Transaction {
    /// Create a new transaction
    pub fn new(mode: TransactionMode) -> Self {
        let id = uuid::Uuid::new_v4().to_string();
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs() as i64;

        Self {
            id,
            mode,
            state: Arc::new(Mutex::new(TransactionState::Active)),
            operations: Arc::new(Mutex::new(Vec::new())),
            summary: Arc::new(Mutex::new(OperationSummary::new())),
            parent_commit: None,
            branch: None,
            created_at: now,
            max_operations: 0,
        }
    }

    /// Get transaction ID
    pub fn id(&self) -> &str {
        &self.id
    }

    /// Get current state
    pub fn state(&self) -> TransactionState {
        *self.state.lock().unwrap()
    }

    /// Check if transaction is active
    pub fn is_active(&self) -> bool {
        self.state() == TransactionState::Active
    }

    /// Check if transaction allows writes
    pub fn allows_writes(&self) -> bool {
        self.mode.allows_writes()
    }

    /// Get transaction mode
    pub fn mode(&self) -> TransactionMode {
        self.mode
    }

    /// Get number of operations in transaction
    pub fn operation_count(&self) -> usize {
        self.operations.lock().unwrap().len()
    }

    /// Get all operations
    pub fn operations(&self) -> Vec<FsOperation> {
        self.operations.lock().unwrap().clone()
    }

    /// Get operation summary
    pub fn summary(&self) -> OperationSummary {
        self.summary.lock().unwrap().clone()
    }

    /// Add an operation to the transaction
    pub fn add_operation(&self, op: FsOperation) -> FsResult<()> {
        // Check if transaction is active
        if !self.is_active() {
            return Err(FsError::TransactionError(
                "Cannot add operation to inactive transaction".to_string(),
            ));
        }

        // Check if mode allows this operation
        if !self.allows_writes() {
            return Err(FsError::TransactionError(
                "Cannot add write operation to read-only transaction".to_string(),
            ));
        }

        // Check operation limit
        if self.max_operations > 0 && self.operation_count() >= self.max_operations {
            return Err(FsError::TransactionError(format!(
                "Transaction operation limit ({}) exceeded",
                self.max_operations
            )));
        }

        let mut ops = self.operations.lock().unwrap();
        ops.push(op);

        Ok(())
    }

    /// Set parent commit for this transaction
    pub fn set_parent(&mut self, commit_hash: String) {
        self.parent_commit = Some(commit_hash);
    }

    /// Set branch for this transaction
    pub fn set_branch(&mut self, branch: String) {
        self.branch = Some(branch);
    }

    /// Get parent commit hash
    pub fn parent_commit(&self) -> Option<&str> {
        self.parent_commit.as_deref()
    }

    /// Get branch name
    pub fn branch(&self) -> Option<&str> {
        self.branch.as_deref()
    }

    /// Commit the transaction
    ///
    /// This finalizes all operations and creates a new commit in the repository.
    ///
    /// # Arguments
    ///
    /// * `message` - Commit message describing the changes
    /// * `author` - Author of the commit
    ///
    /// # Returns
    ///
    /// Returns the commit hash on success
    pub fn commit(&self, message: &str, author: &str) -> FsResult<String> {
        // Verify transaction is active
        if !self.is_active() {
            return Err(FsError::TransactionError(format!(
                "Cannot commit {} transaction",
                match self.state() {
                    TransactionState::Committed => "already-committed",
                    TransactionState::RolledBack => "rolled-back",
                    TransactionState::Error => "error",
                    TransactionState::Active => "unknown",
                }
            )));
        }

        let ops = self.operations.lock().unwrap();
        if ops.is_empty() {
            return Err(FsError::TransactionError(
                "Cannot commit empty transaction".to_string(),
            ));
        }

        // TODO: Perform actual commit in repository
        let mut hasher = Sha3_256::new();
        hasher.update(format!("{}{}{}", message, author, self.id).as_bytes());
        let hash = hasher.finalize();
        let commit_hash = format!("commit_{:x}", hash);

        // Mark as committed
        *self.state.lock().unwrap() = TransactionState::Committed;

        Ok(commit_hash)
    }

    /// Rollback the transaction
    ///
    /// This discards all pending operations.
    pub fn rollback(&self) -> FsResult<()> {
        if !self.is_active() {
            return Err(FsError::TransactionError(
                "Cannot rollback inactive transaction".to_string(),
            ));
        }

        self.operations.lock().unwrap().clear();
        *self.state.lock().unwrap() = TransactionState::RolledBack;

        Ok(())
    }

    /// Set error state
    pub fn set_error(&self) {
        *self.state.lock().unwrap() = TransactionState::Error;
    }

    /// Create a savepoint within the transaction
    ///
    /// Returns a handle that can be used to rollback to this point.
    pub fn savepoint(&self) -> FsResult<SavePoint> {
        if !self.is_active() {
            return Err(FsError::TransactionError(
                "Cannot create savepoint in inactive transaction".to_string(),
            ));
        }

        let ops = self.operations.lock().unwrap();
        Ok(SavePoint {
            transaction_id: self.id.clone(),
            operation_count: ops.len(),
        })
    }

    /// Rollback to a specific savepoint
    pub fn rollback_to_savepoint(&self, savepoint: &SavePoint) -> FsResult<()> {
        if self.id != savepoint.transaction_id {
            return Err(FsError::TransactionError(
                "Savepoint is from a different transaction".to_string(),
            ));
        }

        let mut ops = self.operations.lock().unwrap();
        if savepoint.operation_count < ops.len() {
            ops.truncate(savepoint.operation_count);
            Ok(())
        } else {
            Err(FsError::TransactionError(
                "Invalid savepoint state".to_string(),
            ))
        }
    }
}

impl std::fmt::Debug for Transaction {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Transaction")
            .field("id", &self.id)
            .field("mode", &self.mode)
            .field("state", &self.state())
            .field("operations", &self.operation_count())
            .field("parent_commit", &self.parent_commit)
            .field("branch", &self.branch)
            .field("created_at", &self.created_at)
            .finish()
    }
}

/// A savepoint within a transaction
#[derive(Debug, Clone)]
pub struct SavePoint {
    /// ID of the transaction this savepoint belongs to
    transaction_id: String,

    /// Number of operations at this savepoint
    operation_count: usize,
}

impl SavePoint {
    /// Get the transaction ID
    pub fn transaction_id(&self) -> &str {
        &self.transaction_id
    }

    /// Get the operation count at this savepoint
    pub fn operation_count(&self) -> usize {
        self.operation_count
    }
}

/// Handle for managing a transaction's lifecycle
pub struct TransactionHandle {
    transaction: Arc<Transaction>,
}

impl TransactionHandle {
    /// Create a new transaction handle
    pub fn new(mode: TransactionMode) -> Self {
        Self {
            transaction: Arc::new(Transaction::new(mode)),
        }
    }

    /// Get reference to the underlying transaction
    pub fn transaction(&self) -> &Transaction {
        &self.transaction
    }

    /// Commit and consume the handle
    pub fn commit(self, message: &str, author: &str) -> FsResult<String> {
        self.transaction.commit(message, author)
    }

    /// Rollback and consume the handle
    pub fn rollback(self) -> FsResult<()> {
        self.transaction.rollback()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_transaction_creation() {
        let tx = Transaction::new(TransactionMode::ReadWrite);
        assert!(tx.is_active());
        assert!(tx.allows_writes());
        assert_eq!(tx.operation_count(), 0);
    }

    #[test]
    fn test_transaction_state() {
        let tx = Transaction::new(TransactionMode::ReadOnly);
        assert_eq!(tx.state(), TransactionState::Active);
        assert!(!tx.allows_writes());
    }

    #[test]
    fn test_transaction_mode() {
        let rw = TransactionMode::ReadWrite;
        let ro = TransactionMode::ReadOnly;

        assert!(rw.allows_writes());
        assert!(!ro.allows_writes());
        assert!(!rw.is_exclusive());
        assert!(TransactionMode::Exclusive.is_exclusive());
    }

    #[test]
    fn test_operation_count() {
        let tx = Transaction::new(TransactionMode::ReadWrite);
        assert_eq!(tx.operation_count(), 0);
    }
}