spacedrive/docs/worktable/PERFECT_ACTION_MODEL.md

Perfect Action Model: VolumeTrackAction

Date: 2025-01-27 Status: Perfect Model for All Actions

🎯 The Perfect Unified Action Pattern

The VolumeTrackAction demonstrates the ideal action implementation that all other actions should follow.

✅ Perfect Action Structure:

/// Input for tracking a volume
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VolumeTrackAction {
    /// The fingerprint of the volume to track
    pub fingerprint: VolumeFingerprint,

    /// The library ID to track the volume in
    pub library_id: Uuid,

    /// Optional name for the tracked volume
    pub name: Option<String>,
}

🔧 Constructor Methods (Clean API):

impl VolumeTrackAction {
    /// Create a new volume track action
    pub fn new(fingerprint: VolumeFingerprint, library_id: Uuid, name: Option<String>) -> Self

    /// Create a volume track action with a name
    pub fn with_name(fingerprint: VolumeFingerprint, library_id: Uuid, name: String) -> Self

    /// Create a volume track action without a name
    pub fn without_name(fingerprint: VolumeFingerprint, library_id: Uuid) -> Self
}

🎯 Unified ActionTrait Implementation:

impl ActionTrait for VolumeTrackAction {
    type Output = VolumeTrackOutput;  // Native output type

    async fn execute(self, context: Arc<CoreContext>) -> Result<Self::Output, ActionError> {
        // 1. Get required services from context
        // 2. Execute business logic
        // 3. Return native output type directly
    }

    fn action_kind(&self) -> &'static str {
        "volume.track"  // For logging/identification
    }

    fn library_id(&self) -> Option<Uuid> {
        Some(self.library_id)  // For audit logging
    }

    async fn validate(&self, context: Arc<CoreContext>) -> Result<(), ActionError> {
        // Comprehensive validation:
        // - Library exists
        // - Volume exists and is mounted
        // - Name is valid if provided
    }
}

🚀 Perfect Usage:

// ✅ Clean construction
let action = VolumeTrackAction::with_name(fingerprint, library_id, "My Drive".to_string());

// ✅ Unified execution with native output
let result: VolumeTrackOutput = core.execute_action(action).await?;

// ✅ Direct field access
println!("Tracked volume: {} in library {}", result.volume_name, result.library_id);

🎉 Key Benefits Demonstrated:

1. ✅ Self-Contained - Action includes all necessary context (library_id)
2. ✅ Type Safe - Native output type throughout execution chain
3. ✅ Clean API - Constructor methods for easy creation
4. ✅ Comprehensive Validation - Validates all preconditions
5. ✅ Central Infrastructure - Uses ActionManager for audit logging
6. ✅ No Centralization - No enum dependencies, completely modular

📋 Pattern to Follow:

All actions should follow this exact pattern:

1. Self-contained struct with all required fields including library_id
2. Constructor methods for clean API
3. ActionTrait implementation with:
   • Native output type
   • Comprehensive validation
   • Clean execute method
   • Proper action_kind and library_id

This eliminates all centralization while preserving all infrastructure benefits! 🎯