enya-agent 0.1.0

package/crates/enact-core/src/kernel/artifact/store.rs

@@ -0,0 +1,427 @@
+//! ArtifactStore - Trait for artifact storage backends
+//!
+//! The ArtifactStore trait defines the interface for storing and retrieving
+//! artifacts. Implementations must handle compression, content addressing,
+//! and lifecycle events.
+
+use super::metadata::{ArtifactMetadata, ArtifactType};
+use crate::kernel::ids::{ArtifactId, ExecutionId, StepId};
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use std::io;
+use thiserror::Error;
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/// Errors that can occur during artifact operations
+#[derive(Debug, Error)]
+pub enum ArtifactStoreError {
+    /// Artifact not found
+    #[error("Artifact not found: {0}")]
+    NotFound(ArtifactId),
+
+    /// IO error during storage operation
+    #[error("IO error: {0}")]
+    Io(#[from] io::Error),
+
+    /// Serialization/deserialization error
+    #[error("Serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+
+    /// Compression/decompression error
+    #[error("Compression error: {0}")]
+    Compression(String),
+
+    /// Invalid artifact data
+    #[error("Invalid artifact: {0}")]
+    Invalid(String),
+
+    /// Storage backend error
+    #[error("Storage error: {0}")]
+    Storage(String),
+
+    /// Artifact already exists (for put operations)
+    #[error("Artifact already exists: {0}")]
+    AlreadyExists(ArtifactId),
+}
+
+// =============================================================================
+// Artifact Data
+// =============================================================================
+
+/// Request to store an artifact
+#[derive(Debug, Clone)]
+pub struct PutArtifactRequest {
+    /// Execution that produced this artifact
+    pub execution_id: ExecutionId,
+    /// Step that produced this artifact
+    pub step_id: StepId,
+    /// Name of the artifact
+    pub name: String,
+    /// Type of artifact
+    pub artifact_type: ArtifactType,
+    /// Content type (MIME type)
+    pub content_type: Option<String>,
+    /// Raw content bytes
+    pub content: Vec<u8>,
+    /// Additional metadata
+    pub metadata: Option<serde_json::Value>,
+}
+
+impl PutArtifactRequest {
+    /// Create a new put request
+    pub fn new(
+        execution_id: ExecutionId,
+        step_id: StepId,
+        name: impl Into<String>,
+        artifact_type: ArtifactType,
+        content: Vec<u8>,
+    ) -> Self {
+        Self {
+            execution_id,
+            step_id,
+            name: name.into(),
+            artifact_type,
+            content_type: None,
+            content,
+            metadata: None,
+        }
+    }
+
+    /// Set content type
+    pub fn with_content_type(mut self, content_type: impl Into<String>) -> Self {
+        self.content_type = Some(content_type.into());
+        self
+    }
+
+    /// Set metadata
+    pub fn with_metadata(mut self, metadata: serde_json::Value) -> Self {
+        self.metadata = Some(metadata);
+        self
+    }
+}
+
+/// Response from storing an artifact
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PutArtifactResponse {
+    /// Generated artifact ID
+    pub artifact_id: ArtifactId,
+    /// Full metadata of the stored artifact
+    pub metadata: ArtifactMetadata,
+    /// Size of the compressed content (bytes)
+    pub compressed_size: u64,
+    /// Size of the original content (bytes)
+    pub original_size: u64,
+}
+
+/// Request to retrieve an artifact
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct GetArtifactRequest {
+    /// Artifact ID to retrieve
+    pub artifact_id: ArtifactId,
+}
+
+/// Response from retrieving an artifact
+#[derive(Debug, Clone)]
+pub struct GetArtifactResponse {
+    /// Artifact metadata
+    pub metadata: ArtifactMetadata,
+    /// Decompressed content bytes
+    pub content: Vec<u8>,
+}
+
+/// Query for listing artifacts
+#[derive(Debug, Clone, Default)]
+pub struct ListArtifactsQuery {
+    /// Filter by execution ID
+    pub execution_id: Option<ExecutionId>,
+    /// Filter by step ID
+    pub step_id: Option<StepId>,
+    /// Filter by artifact type
+    pub artifact_type: Option<ArtifactType>,
+    /// Maximum number of results
+    pub limit: Option<usize>,
+    /// Offset for pagination
+    pub offset: Option<usize>,
+}
+
+impl ListArtifactsQuery {
+    /// Create a query for a specific execution
+    pub fn for_execution(execution_id: ExecutionId) -> Self {
+        Self {
+            execution_id: Some(execution_id),
+            ..Default::default()
+        }
+    }
+
+    /// Create a query for a specific step
+    pub fn for_step(step_id: StepId) -> Self {
+        Self {
+            step_id: Some(step_id),
+            ..Default::default()
+        }
+    }
+}
+
+// =============================================================================
+// ArtifactStore Trait
+// =============================================================================
+
+/// Trait for artifact storage backends
+///
+/// Implementations must:
+/// - Generate deterministic artifact IDs
+/// - Compress content before storage (recommended: zstd)
+/// - Handle concurrent access safely
+/// - Support listing and filtering
+#[async_trait]
+pub trait ArtifactStore: Send + Sync {
+    /// Store an artifact
+    ///
+    /// Returns the generated artifact ID and metadata
+    async fn put(&self, request: PutArtifactRequest) -> Result<PutArtifactResponse, ArtifactStoreError>;
+
+    /// Retrieve an artifact by ID
+    async fn get(&self, artifact_id: &ArtifactId) -> Result<GetArtifactResponse, ArtifactStoreError>;
+
+    /// Check if an artifact exists
+    async fn exists(&self, artifact_id: &ArtifactId) -> Result<bool, ArtifactStoreError>;
+
+    /// Delete an artifact
+    async fn delete(&self, artifact_id: &ArtifactId) -> Result<(), ArtifactStoreError>;
+
+    /// List artifacts matching a query
+    async fn list(&self, query: ListArtifactsQuery) -> Result<Vec<ArtifactMetadata>, ArtifactStoreError>;
+
+    /// Get metadata for an artifact without retrieving content
+    async fn get_metadata(&self, artifact_id: &ArtifactId) -> Result<ArtifactMetadata, ArtifactStoreError>;
+
+    /// Get total storage size for an execution
+    async fn get_execution_size(&self, execution_id: &ExecutionId) -> Result<u64, ArtifactStoreError>;
+}
+
+// =============================================================================
+// In-Memory Store (for testing)
+// =============================================================================
+
+use std::collections::HashMap;
+use tokio::sync::RwLock;
+
+/// In-memory artifact store for testing
+pub struct InMemoryArtifactStore {
+    artifacts: RwLock<HashMap<ArtifactId, (ArtifactMetadata, Vec<u8>)>>,
+}
+
+impl InMemoryArtifactStore {
+    /// Create a new in-memory store
+    pub fn new() -> Self {
+        Self {
+            artifacts: RwLock::new(HashMap::new()),
+        }
+    }
+}
+
+impl Default for InMemoryArtifactStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl ArtifactStore for InMemoryArtifactStore {
+    async fn put(&self, request: PutArtifactRequest) -> Result<PutArtifactResponse, ArtifactStoreError> {
+        let artifact_id = ArtifactId::new();
+        let original_size = request.content.len() as u64;
+
+        let metadata = ArtifactMetadata::new(
+            artifact_id.clone(),
+            request.execution_id,
+            request.step_id,
+            request.name,
+            request.artifact_type,
+        )
+        .with_original_size(original_size)
+        .with_compressed_size(original_size) // No compression in memory
+        .with_content_type(request.content_type.unwrap_or_else(|| "application/octet-stream".to_string()));
+
+        {
+            let mut artifacts = self.artifacts.write().await;
+            artifacts.insert(artifact_id.clone(), (metadata.clone(), request.content));
+        }
+
+        Ok(PutArtifactResponse {
+            artifact_id,
+            metadata,
+            compressed_size: original_size,
+            original_size,
+        })
+    }
+
+    async fn get(&self, artifact_id: &ArtifactId) -> Result<GetArtifactResponse, ArtifactStoreError> {
+        let artifacts = self.artifacts.read().await;
+        match artifacts.get(artifact_id) {
+            Some((metadata, content)) => Ok(GetArtifactResponse {
+                metadata: metadata.clone(),
+                content: content.clone(),
+            }),
+            None => Err(ArtifactStoreError::NotFound(artifact_id.clone())),
+        }
+    }
+
+    async fn exists(&self, artifact_id: &ArtifactId) -> Result<bool, ArtifactStoreError> {
+        let artifacts = self.artifacts.read().await;
+        Ok(artifacts.contains_key(artifact_id))
+    }
+
+    async fn delete(&self, artifact_id: &ArtifactId) -> Result<(), ArtifactStoreError> {
+        let mut artifacts = self.artifacts.write().await;
+        artifacts.remove(artifact_id)
+            .ok_or_else(|| ArtifactStoreError::NotFound(artifact_id.clone()))?;
+        Ok(())
+    }
+
+    async fn list(&self, query: ListArtifactsQuery) -> Result<Vec<ArtifactMetadata>, ArtifactStoreError> {
+        let artifacts = self.artifacts.read().await;
+        let mut results: Vec<ArtifactMetadata> = artifacts
+            .values()
+            .filter_map(|(metadata, _)| {
+                // Apply filters
+                if let Some(ref exec_id) = query.execution_id {
+                    if metadata.execution_id != *exec_id {
+                        return None;
+                    }
+                }
+                if let Some(ref step_id) = query.step_id {
+                    if metadata.step_id != *step_id {
+                        return None;
+                    }
+                }
+                if let Some(ref artifact_type) = query.artifact_type {
+                    if metadata.artifact_type != *artifact_type {
+                        return None;
+                    }
+                }
+                Some(metadata.clone())
+            })
+            .collect();
+
+        // Sort by creation time
+        results.sort_by(|a, b| a.created_at.cmp(&b.created_at));
+
+        // Apply pagination
+        if let Some(offset) = query.offset {
+            results = results.into_iter().skip(offset).collect();
+        }
+        if let Some(limit) = query.limit {
+            results.truncate(limit);
+        }
+
+        Ok(results)
+    }
+
+    async fn get_metadata(&self, artifact_id: &ArtifactId) -> Result<ArtifactMetadata, ArtifactStoreError> {
+        let artifacts = self.artifacts.read().await;
+        match artifacts.get(artifact_id) {
+            Some((metadata, _)) => Ok(metadata.clone()),
+            None => Err(ArtifactStoreError::NotFound(artifact_id.clone())),
+        }
+    }
+
+    async fn get_execution_size(&self, execution_id: &ExecutionId) -> Result<u64, ArtifactStoreError> {
+        let artifacts = self.artifacts.read().await;
+        let total: u64 = artifacts
+            .values()
+            .filter(|(m, _)| m.execution_id == *execution_id)
+            .map(|(_, content)| content.len() as u64)
+            .sum();
+        Ok(total)
+    }
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_in_memory_store_put_get() {
+        let store = InMemoryArtifactStore::new();
+        let exec_id = ExecutionId::new();
+        let step_id = StepId::new();
+
+        let request = PutArtifactRequest::new(
+            exec_id.clone(),
+            step_id,
+            "test.txt",
+            ArtifactType::Text,
+            b"Hello, World!".to_vec(),
+        );
+
+        let response = store.put(request).await.unwrap();
+        assert!(response.artifact_id.as_str().starts_with("artifact_"));
+
+        let get_response = store.get(&response.artifact_id).await.unwrap();
+        assert_eq!(get_response.content, b"Hello, World!");
+        assert_eq!(get_response.metadata.name, "test.txt");
+    }
+
+    #[tokio::test]
+    async fn test_in_memory_store_list() {
+        let store = InMemoryArtifactStore::new();
+        let exec_id = ExecutionId::new();
+        let step_id = StepId::new();
+
+        // Store multiple artifacts
+        for i in 0..5 {
+            let request = PutArtifactRequest::new(
+                exec_id.clone(),
+                step_id.clone(),
+                format!("file{}.txt", i),
+                ArtifactType::Text,
+                format!("Content {}", i).into_bytes(),
+            );
+            store.put(request).await.unwrap();
+        }
+
+        // List all for execution
+        let query = ListArtifactsQuery::for_execution(exec_id.clone());
+        let results = store.list(query).await.unwrap();
+        assert_eq!(results.len(), 5);
+
+        // List with limit
+        let query = ListArtifactsQuery {
+            execution_id: Some(exec_id),
+            limit: Some(3),
+            ..Default::default()
+        };
+        let results = store.list(query).await.unwrap();
+        assert_eq!(results.len(), 3);
+    }
+
+    #[tokio::test]
+    async fn test_in_memory_store_delete() {
+        let store = InMemoryArtifactStore::new();
+        let exec_id = ExecutionId::new();
+        let step_id = StepId::new();
+
+        let request = PutArtifactRequest::new(
+            exec_id,
+            step_id,
+            "test.txt",
+            ArtifactType::Text,
+            b"Hello".to_vec(),
+        );
+
+        let response = store.put(request).await.unwrap();
+        assert!(store.exists(&response.artifact_id).await.unwrap());
+
+        store.delete(&response.artifact_id).await.unwrap();
+        assert!(!store.exists(&response.artifact_id).await.unwrap());
+    }
+}