Skip to main content

passalong_core/store/
mod.rs

1//! Storage: the backend-agnostic [`Store`] trait and its implementations.
2//!
3//! Commands depend only on `dyn Store`. [`FsStore`] implements it on top of
4//! any [`RemoteFs`](crate::fs::RemoteFs), which covers the local and SSH
5//! backends; a future web API or S3 backend can implement [`Store`]
6//! directly.
7
8pub mod factory;
9pub mod format;
10pub mod fs_store;
11
12pub use factory::{
13    AdminFuture, AdminOpener, BackendFuture, BackendOpener, BackendRegistry, FsFuture, FsOpener,
14    open_store,
15};
16pub use fs_store::FsStore;
17
18use std::time::Duration;
19
20use async_trait::async_trait;
21
22use crate::crypto::{CryptoError, KeyId};
23use crate::encryption::EncryptionError;
24use crate::fs::{BoxRead, FsError};
25use crate::model::{ContentDigest, ContentKey, ItemId, ItemMeta, ModelError, NewItem};
26
27/// Result of [`Store::put`].
28#[derive(Debug, Clone, PartialEq, Eq)]
29pub struct PutOutcome {
30    /// The stored item, or the existing item with the same content.
31    pub meta: ItemMeta,
32    /// `false` when identical content was already stored and nothing was
33    /// uploaded.
34    pub created: bool,
35}
36
37/// How many bytes a [`Store::probe_write`] implementation writes, so the
38/// time a probe takes means the same for every backend.
39pub const PROBE_BYTES: usize = 128;
40
41/// Result of [`Store::probe_write`].
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
43#[non_exhaustive]
44pub enum WriteProbe {
45    /// A probe was written where listings never look, then removed.
46    Verified,
47    /// This backend cannot test writing without storing an item.
48    NotSupported,
49}
50
51/// A place items are stored.
52#[async_trait]
53pub trait Store: Send + Sync {
54    /// Stores `content` as a new item, streaming it without buffering the
55    /// whole content. Identical content already in the store is not stored
56    /// again: the existing item is returned with `created: false`.
57    async fn put(&self, item: NewItem, content: BoxRead) -> Result<PutOutcome, StoreError>;
58
59    /// Lists every item, newest first.
60    async fn list(&self) -> Result<Vec<ItemMeta>, StoreError>;
61
62    /// Items newer than `after`, newest first, or every item for `None`.
63    /// Only those items' metadata is read, so polling for new items stays
64    /// cheap on a large store.
65    async fn list_after(&self, after: Option<&ItemId>) -> Result<Vec<ItemMeta>, StoreError>;
66
67    /// Every item's id, newest first, without reading any metadata. The
68    /// default lists every item; backends override it with something
69    /// cheaper.
70    async fn list_ids(&self) -> Result<Vec<ItemId>, StoreError> {
71        Ok(self
72            .list_after(None)
73            .await?
74            .into_iter()
75            .map(|meta| meta.id)
76            .collect())
77    }
78
79    /// The newest item's id, or `None` for an empty store. The default
80    /// lists every item; backends override it with something cheaper.
81    #[deprecated(
82        since = "0.1.3",
83        note = "pull mode no longer uses it; use list_ids and take the first"
84    )]
85    async fn newest_id(&self) -> Result<Option<ItemId>, StoreError> {
86        Ok(self
87            .list_after(None)
88            .await?
89            .into_iter()
90            .next()
91            .map(|meta| meta.id))
92    }
93
94    /// Returns an item's metadata and a stream of its content.
95    async fn get(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError>;
96
97    /// An item's metadata alone, without opening its content. The default
98    /// calls [`Store::get`] and drops the content; backends override it
99    /// with a single metadata read.
100    ///
101    /// # Errors
102    ///
103    /// [`StoreError::NotFound`] for an unknown id, or the backend's error.
104    async fn get_meta(&self, id: &ItemId) -> Result<ItemMeta, StoreError> {
105        Ok(self.get(id).await?.0)
106    }
107
108    /// Whether an item exists.
109    async fn exists(&self, id: &ItemId) -> Result<bool, StoreError>;
110
111    /// Finds the oldest item whose content has `key`.
112    async fn find_by_content_key(&self, key: &ContentKey) -> Result<Option<ItemMeta>, StoreError>;
113
114    /// Turns what a user typed into one item id. Input without `-` is a
115    /// prefix of the content key (for example `2cf2`); input with `-` is a
116    /// prefix of the full id. Case and surrounding spaces are ignored, and
117    /// at least 4 characters are required.
118    async fn resolve(&self, input: &str) -> Result<ItemId, StoreError>;
119
120    /// Deletes an item and returns its metadata. The item disappears from
121    /// listings in one step, even if removing its data then fails.
122    async fn delete(&self, id: &ItemId) -> Result<ItemMeta, StoreError>;
123
124    /// Removes staging directories that interrupted uploads and deletions
125    /// left behind, when older than `older_than`, and returns how many were
126    /// removed. Younger ones may belong to uploads in progress and stay.
127    async fn clean_staging(&self, older_than: Duration) -> Result<usize, StoreError>;
128
129    /// Checks that the store accepts writes without storing an item: a
130    /// probe is written where listings and other devices never look, then
131    /// removed. The default reports [`WriteProbe::NotSupported`].
132    ///
133    /// # Errors
134    ///
135    /// The backend's error when the probe cannot be written or removed.
136    async fn probe_write(&self) -> Result<WriteProbe, StoreError> {
137        Ok(WriteProbe::NotSupported)
138    }
139
140    /// Id of the data key this store seals items with; `None` for a
141    /// plaintext store.
142    fn key_id(&self) -> Option<KeyId> {
143        None
144    }
145
146    /// The content key that identifies content with `digest` in this
147    /// store: the plain [`ContentDigest::content_key`], or a keyed one in an
148    /// encrypted store. Use it to look for content already stored.
149    fn content_key(&self, digest: &ContentDigest) -> ContentKey {
150        digest.content_key()
151    }
152}
153
154/// Storage errors.
155#[derive(Debug, thiserror::Error)]
156#[non_exhaustive]
157pub enum StoreError {
158    /// No item matches the given id or prefix.
159    #[error("no item matches `{0}`")]
160    NotFound(String),
161    /// A prefix matches more than one item.
162    #[error("`{input}` matches {} items: {}", candidates.len(), join_ids(candidates))]
163    Ambiguous {
164        /// What the user typed.
165        input: String,
166        /// Every matching id, newest first.
167        candidates: Vec<ItemId>,
168    },
169    /// The input is too short to identify an item.
170    #[error("`{0}` is too short: give at least 4 characters of the id")]
171    InvalidPrefix(String),
172    /// `server.kind` names a backend this build does not provide.
173    #[error("unsupported storage backend `{0}`")]
174    UnsupportedBackend(String),
175    /// The backend's configuration is incomplete.
176    #[error("storage configuration: {0}")]
177    Config(String),
178    /// A filesystem operation failed.
179    #[error(transparent)]
180    Fs(#[from] FsError),
181    /// Reading the content being stored failed.
182    #[error("reading the content failed: {0}")]
183    Content(String),
184    /// An item's stored data is unreadable or inconsistent.
185    #[error("item {id} is corrupt: {reason}")]
186    Corrupt {
187        /// The item's id.
188        id: String,
189        /// What is wrong.
190        reason: String,
191    },
192    /// Building item metadata failed.
193    #[error(transparent)]
194    Model(#[from] ModelError),
195    /// A backend-specific failure, such as an SSH connection error.
196    #[error("{0}")]
197    Backend(String),
198    /// An encrypted store's data cannot be used.
199    #[error(transparent)]
200    Encryption(#[from] EncryptionError),
201    /// The server no longer accepts this device's credentials, such as an
202    /// API key that expired or was revoked. Trying again cannot help.
203    #[error("{0}")]
204    Denied(String),
205}
206
207impl From<CryptoError> for StoreError {
208    fn from(err: CryptoError) -> Self {
209        Self::Encryption(err.into())
210    }
211}
212
213fn join_ids(ids: &[ItemId]) -> String {
214    ids.iter()
215        .map(ItemId::as_str)
216        .collect::<Vec<_>>()
217        .join(", ")
218}