polykit_core/remote_cache/
backend.rs

1//! Backend trait for remote cache storage.
2
3use async_trait::async_trait;
4
5use crate::error::Result;
6
7use super::artifact::Artifact;
8use super::cache_key::CacheKey;
9
10/// Error types for remote cache backend operations.
11#[derive(thiserror::Error, Debug)]
12pub enum BackendError {
13    #[error("Network error: {0}")]
14    Network(String),
15
16    #[error("Authentication failed: {0}")]
17    Authentication(String),
18
19    #[error("Artifact not found")]
20    NotFound,
21
22    #[error("Invalid response: {0}")]
23    InvalidResponse(String),
24
25    #[error("IO error: {0}")]
26    Io(#[from] std::io::Error),
27
28    #[error("Backend error: {0}")]
29    Other(String),
30}
31
32/// Trait for remote cache backends.
33///
34/// Backends are responsible for storing and retrieving artifacts.
35/// All operations are async and should support streaming for large artifacts.
36#[async_trait]
37pub trait RemoteCacheBackend: Send + Sync {
38    /// Uploads an artifact to the remote cache.
39    ///
40    /// # Arguments
41    ///
42    /// * `key` - The cache key for this artifact
43    /// * `artifact` - The artifact to upload
44    ///
45    /// # Errors
46    ///
47    /// Returns an error if upload fails. Errors should be non-fatal and allow
48    /// fallback to local execution.
49    async fn upload_artifact(&self, key: &CacheKey, artifact: &Artifact) -> Result<()>;
50
51    /// Fetches an artifact from the remote cache.
52    ///
53    /// # Arguments
54    ///
55    /// * `key` - The cache key to fetch
56    ///
57    /// # Returns
58    ///
59    /// Returns `Some(artifact)` if found, `None` if not found.
60    ///
61    /// # Errors
62    ///
63    /// Returns an error only for unexpected failures (network errors, etc.).
64    /// Cache misses should return `Ok(None)`.
65    async fn fetch_artifact(&self, key: &CacheKey) -> Result<Option<Artifact>>;
66
67    /// Checks if an artifact exists in the remote cache.
68    ///
69    /// # Arguments
70    ///
71    /// * `key` - The cache key to check
72    ///
73    /// # Returns
74    ///
75    /// Returns `true` if the artifact exists, `false` otherwise.
76    ///
77    /// # Errors
78    ///
79    /// Returns an error only for unexpected failures. Cache misses should return `Ok(false)`.
80    async fn has_artifact(&self, key: &CacheKey) -> Result<bool>;
81}
polykit_core/remote_cache/backend.rs

polykit_core/remote_cache/
backend.rs
