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}