coven_storage/storage.rs
1use crate::{
2 ByteProgress, CloudProvider, ObjectPath, ObjectPrefix, ObjectRead, PublicationRequest,
3 StorageConfig, StorageError, StorageFailure, StoredObject, UploadSession,
4};
5use async_trait::async_trait;
6
7/// A nonempty half-open byte range; end must not exceed the object's length.
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
9pub struct ByteRange {
10 start: u64,
11 end: u64,
12}
13
14#[cfg(test)]
15#[path = "storage_tests.rs"]
16mod tests;
17
18impl ByteRange {
19 /// Validate the bounds before issuing a ranged request.
20 pub fn new(start: u64, end: u64) -> Result<Self, StorageError> {
21 if start >= end {
22 return Err(StorageFailure::InvalidRange.into());
23 }
24 Ok(Self { start, end })
25 }
26 /// First byte included.
27 pub fn start(self) -> u64 {
28 self.start
29 }
30 /// First byte excluded.
31 pub fn end(self) -> u64 {
32 self.end
33 }
34 /// Number of requested bytes.
35 pub fn len(self) -> u64 {
36 self.end - self.start
37 }
38 /// A validated range is never empty.
39 pub fn is_empty(self) -> bool {
40 false
41 }
42 pub(crate) fn header(self) -> String {
43 format!("bytes={}-{}", self.start, self.end - 1)
44 }
45 #[cfg(any(test, feature = "test-utils"))]
46 pub(crate) fn select(self, bytes: &[u8]) -> Result<Vec<u8>, StorageError> {
47 let start = usize::try_from(self.start)
48 .map_err(|error| StorageFailure::InvalidRange.with_source(error))?;
49 let end = usize::try_from(self.end)
50 .map_err(|error| StorageFailure::InvalidRange.with_source(error))?;
51 bytes
52 .get(start..end)
53 .map(<[u8]>::to_vec)
54 .ok_or(StorageError::Failure(StorageFailure::InvalidRange))
55 }
56}
57
58/// A part the connection admitted (§17.9): no provider cooldown was live, the
59/// session names the connection's location, the part fits the session, and
60/// its destination could be published. Admitting a planned session's first
61/// part marked its plan. Sending the part consumes the permit.
62#[must_use = "a part goes to the provider only through its permit"]
63pub struct PartPermit<'a> {
64 pub(crate) bytes: &'a [u8],
65 /// Where the part starts and ends in the object.
66 pub(crate) part: std::ops::Range<u64>,
67 pub(crate) publication: PublicationRequest,
68 marked: bool,
69}
70
71impl<'a> PartPermit<'a> {
72 /// Admit `bytes` as the part `part` covers, marking a planned session's
73 /// plan.
74 pub(crate) fn admit(
75 session: &mut UploadSession,
76 bytes: &'a [u8],
77 part: std::ops::Range<u64>,
78 publication: PublicationRequest,
79 ) -> Self {
80 let marked = session.mark_start();
81 Self { bytes, part, publication, marked }
82 }
83 /// Whether admitting the part marked the session's plan, changing what
84 /// the caller records: save the session before sending the part, so a
85 /// recording that may name an upload says so (Appendix E.10).
86 pub fn marked(&self) -> bool {
87 self.marked
88 }
89}
90
91/// How a removed device's member cuts off its provider access (§14.2, E9).
92#[derive(Clone, Debug, PartialEq, Eq)]
93pub enum ProviderSignOut {
94 /// Remove the app's access, then sign in again on retained devices.
95 RemoveAppAccess {
96 /// Dropbox or OneDrive.
97 provider: CloudProvider,
98 },
99 /// Remove the device from the Apple account.
100 RemoveFromAppleAccount,
101}
102
103pub use coven_format::MemberAccess;
104
105/// Granting access succeeds either through the provider or through an admin action.
106pub enum AccessGrant {
107 /// The provider shared the store with the account.
108 Granted {
109 /// Provider acceptance information to include in the encrypted invite code.
110 invitation: crate::StorageInvitation,
111 },
112 /// The admin makes a key in the provider console and enters it in the invite.
113 CreateAccessKey,
114}
115
116/// A grant that revocation left for the owner to inspect.
117#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
118pub struct RetainedAccess {
119 /// The native permission, membership or group id, scoped to this store.
120 pub provider_id: String,
121 /// Why removing this grant cannot revoke only the requested account.
122 pub reason: RetainedAccessReason,
123}
124
125/// The provider's reason that a grant was retained.
126#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
127pub enum RetainedAccessReason {
128 /// The grant also reaches other accounts, including public or group access.
129 OtherAccounts,
130 /// The grant comes from a parent location.
131 Inherited,
132 /// The provider did not identify the recipient sufficiently to remove it safely.
133 UnidentifiedAccount,
134 /// The grant belongs to the store's owner, whose access cannot be removed.
135 StoreOwner,
136}
137
138/// The operations coven needs from a provider (§20.1).
139///
140/// Implementations are capabilities assembled at composition roots. They own no
141/// database or key custody. Every mutation is awaited and failures reach the
142/// caller; no hidden background work repairs failed operations.
143#[async_trait]
144pub trait Storage: Send + Sync {
145 /// Install a member's replacement S3 key after credential custody commits.
146 /// Other provider kinds refuse this operation without changing sign-in state.
147 async fn set_s3_credentials(
148 &self,
149 _credentials: crate::S3Credentials,
150 ) -> Result<(), StorageError> {
151 Err(StorageFailure::InvalidConfiguration.with_source("provider does not use S3 keys"))
152 }
153 /// The id of the S3 key this connection signs with now, without its
154 /// secret; `None` on a provider that doesn't use S3 keys.
155 async fn s3_access_key_id(&self) -> Option<String> {
156 None
157 }
158 /// This provider's nonsecret location settings.
159 fn config(&self) -> StorageConfig;
160 /// The signed-in sharing account, for the member's admin access entry.
161 /// S3 uses its supplied access key id instead of an account lookup.
162 async fn account(&self) -> Result<String, StorageError> {
163 Err(StorageFailure::InvalidConfiguration.with_source("provider has no sharing account"))
164 }
165 /// The signed-in account as the provider identifies it: its id and primary
166 /// address, which an invite's shared-with account is compared with.
167 async fn account_identity(&self) -> Result<crate::ProviderAccount, StorageError> {
168 Err(StorageFailure::InvalidConfiguration.with_source("provider has no sharing account"))
169 }
170 /// Largest complete encrypted body the provider takes in one request, in
171 /// bytes. Objects past it, or past [`crate::BUFFERED_REQUEST_LIMIT`], go
172 /// in parts through resumable or multipart uploads
173 /// ([`crate::goes_in_parts`]). Floor pointer replacements accept
174 /// complete bodies up to this limit; OneDrive stages
175 /// the body in a revision-bound session before conditional publication.
176 /// Callers retaining sessions across crashes record `begin_upload`
177 /// sessions.
178 /// S3 uses 5 GiB, Dropbox 150 MiB and OneDrive 250,000,000 bytes.
179 /// CloudKit uses bounded 8 MiB assets.
180 fn single_request_limit(&self) -> u64;
181 /// The size of the parts a ranged read moves whole, counted from the
182 /// object's start, the last shorter: a range moves every part it
183 /// touches, as iCloud's reads do (Appendix E.1). `None` when a range
184 /// moves only its own bytes.
185 fn read_part_size(&self) -> Option<std::num::NonZeroU64> {
186 None
187 }
188 /// Install replacement OAuth tokens after the owner commits them to key custody.
189 /// S3 and CloudKit refuse OAuth tokens; they use different account credentials.
190 async fn set_oauth_tokens(&self, _tokens: crate::OAuthTokens) -> Result<(), StorageError> {
191 Err(StorageFailure::InvalidConfiguration.with_source("provider does not use OAuth"))
192 }
193 /// Create a complete encrypted object, refusing an occupied path with
194 /// [`StorageFailure::AlreadyExists`]. Occupation alone proves nothing: a
195 /// retry compares the occupant's complete bytes itself (§5.1, §19.3).
196 /// Bodies [`crate::goes_in_parts`] sends in parts use a session; a writes
197 /// slot can contain multiple writes in one object.
198 /// A failed transfer aborts the session;
199 /// if abort fails too, [`StorageError::Cleanup`] retains both causes.
200 /// Returns the object's metadata when the provider's one-request reply
201 /// carries it; otherwise exact status supplies it (§21.1).
202 async fn create(
203 &self,
204 path: &ObjectPath,
205 bytes: &[u8],
206 ) -> Result<Option<StoredObject>, StorageError> {
207 self.create_reporting(path, bytes, &ByteProgress::unread()).await
208 }
209 /// [`Self::create`], telling `sent` how many of the object's bytes the
210 /// connection has taken, as it takes them: Dropbox's, OneDrive's and
211 /// S3's bodies say as they go, CloudKit's client as the fraction of each
212 /// asset sent (§6.7).
213 async fn create_reporting(
214 &self,
215 path: &ObjectPath,
216 bytes: &[u8],
217 sent: &ByteProgress,
218 ) -> Result<Option<StoredObject>, StorageError>;
219 /// Replace the floor only if its observed native revision still matches.
220 /// A stale observation returns `Conflict` without changing the object.
221 /// The new bytes become visible together, or not at all. A body above
222 /// [`Self::single_request_limit`] returns [`StorageFailure::SingleRequestTooLarge`].
223 async fn replace(&self, previous: &StoredObject, bytes: &[u8]) -> Result<(), StorageError>;
224 /// Exact lookup. None means confirmed absence; failed lookups remain errors.
225 /// Pending multipart assets must not be reported as complete objects.
226 async fn status(&self, path: &ObjectPath) -> Result<Option<StoredObject>, StorageError>;
227 /// Read bytes and metadata from the same object revision. A range still
228 /// reports the complete encrypted size and whole-object checksum semantics.
229 async fn stream_object(
230 &self,
231 path: &ObjectPath,
232 range: Option<ByteRange>,
233 ) -> Result<crate::ObjectStream<'_>, StorageError> {
234 self.stream_object_reporting(path, range, &ByteProgress::unread()).await
235 }
236 /// [`Self::stream_object`], telling `received` how far through the
237 /// object the bytes received reach, as they arrive: as the stream reads
238 /// them, and for CloudKit, whose client fetches a record's asset whole,
239 /// as the fetch goes (§6.7).
240 async fn stream_object_reporting(
241 &self,
242 path: &ObjectPath,
243 range: Option<ByteRange>,
244 received: &ByteProgress,
245 ) -> Result<crate::ObjectStream<'_>, StorageError>;
246 /// Collect a bounded response through the streaming implementation. Large
247 /// writes and snapshots consume `stream_object` directly. This convenience
248 /// reader holds at most 32 MiB, regardless of provider metadata.
249 async fn read_object(
250 &self,
251 path: &ObjectPath,
252 range: Option<ByteRange>,
253 ) -> Result<ObjectRead, StorageError> {
254 self.stream_object(path, range)
255 .await?
256 .collect(crate::object_stream::BUFFERED_READ_LIMIT)
257 .await
258 }
259 /// Read a bounded whole encrypted object; the limit is the same as `read_object`.
260 async fn read(&self, path: &ObjectPath) -> Result<Vec<u8>, StorageError> {
261 Ok(self.read_object(path, None).await?.bytes)
262 }
263 /// Fetch only the requested bytes; never silently shorten a range.
264 async fn read_range(
265 &self,
266 path: &ObjectPath,
267 range: ByteRange,
268 ) -> Result<Vec<u8>, StorageError> {
269 Ok(self.read_object(path, Some(range)).await?.bytes)
270 }
271 /// List every object under the prefix, across all pages.
272 /// Missing or malformed metadata fails the call.
273 async fn list(&self, prefix: &ObjectPrefix) -> Result<Vec<StoredObject>, StorageError>;
274
275 /// Delete an object. An already absent object succeeds, making operation retries safe.
276 /// Sync chooses the deleting device under §16.6; storage exposes no deletion-rights
277 /// query. A provider refusal retains its cause, including a refused owned-object deletion.
278 async fn delete(&self, path: &ObjectPath) -> Result<(), StorageError>;
279 /// [`Self::delete`] for a caller that wants the object gone and has no use
280 /// for the difference between deleting it and finding nothing: a
281 /// `NotFound` failure, such as a provider reporting its folder missing,
282 /// is done too. Every other failure reaches the caller.
283 async fn delete_if_present(&self, path: &ObjectPath) -> Result<(), StorageError> {
284 match self.delete(path).await {
285 Err(error) if error.failure() == StorageFailure::NotFound => Ok(()),
286 result => result,
287 }
288 }
289 /// Share the store using its owner's account, or tell an S3 admin to create a key.
290 /// A signed-in sharing account that does not own the location gets `NotStoreOwner`.
291 /// Ownership comes from Dropbox's folder `access_type`,
292 /// OneDrive's current-account drive id, or CloudKit's current user record id compared with the zone owner.
293 /// S3's console-key instructions need no sharing-account check.
294 /// Inviting the account that holds the store gets
295 /// [`StorageFailure::InviteeIsStoreOwner`]. Dropbox and OneDrive refuse
296 /// before any sharing change; CloudKit learns it from the saved share,
297 /// which then lists only the owner.
298 ///
299 /// Dropbox upgrades viewers in place with `update_folder_member`; a pending
300 /// viewer without a native account id gets [`StorageFailure::AccountIdUnavailable`]
301 /// and keeps its invitation.
302 async fn grant_access(&self, account: &str) -> Result<AccessGrant, StorageError>;
303 /// Finish provider onboarding under the invited account, then check that the
304 /// location can be read. The facade verifies coven's store identity and keys.
305 /// Dropbox mounts the shared namespace. OneDrive checks the share's drive/folder
306 /// before redeeming it; CloudKit checks share metadata before native acceptance.
307 /// Native acceptance material comes from the encrypted [`crate::StorageInvitation`],
308 /// not a revocation grant id. Removal during joining returns the provider's
309 /// permission failure; an admin can invite again.
310 async fn join(
311 &self,
312 store: coven_foundation::id_source::StoreId,
313 invitation: &crate::StorageInvitation,
314 ) -> Result<(), StorageError> {
315 invitation.check(&self.config())?;
316 if !matches!(invitation.acceptance, crate::invitation::InvitationAcceptance::Granted) {
317 return Err(
318 StorageFailure::InvalidConfiguration.with_source("provider acceptance required")
319 );
320 }
321 self.status(&ObjectPath::floor(store)).await?;
322 Ok(())
323 }
324 /// Undo [`Self::join`]'s acceptance under the invited account, for a join
325 /// cancelled before its request was sent, keeping the invite usable
326 /// (§13.2, E.2). Dropbox unmounts the shared namespace, which leaves the
327 /// account a member, so joining again mounts it again; finding it
328 /// unmounted already, or the account no longer a member, is done. S3
329 /// accepts nothing. OneDrive and CloudKit undo nothing: Graph documents no
330 /// way for the recipient to give up a redeemed link's access, and a
331 /// CloudKit participant that deletes the share is removed from it.
332 async fn leave(&self, invitation: &crate::StorageInvitation) -> Result<(), StorageError> {
333 invitation.check(&self.config())?;
334 if !matches!(invitation.acceptance, crate::invitation::InvitationAcceptance::Granted) {
335 return Err(
336 StorageFailure::InvalidConfiguration.with_source("provider acceptance required")
337 );
338 }
339 Ok(())
340 }
341 /// Unshare through the owner's account. Coven shares nothing on S3, so
342 /// there is nothing to take back.
343 /// Ownership is checked as for [`Self::grant_access`]. Only grants exclusive to
344 /// this account are removed; owner, inherited, shared or unidentified grants
345 /// are returned for owner action. An empty list confirms revocation.
346 ///
347 /// OneDrive resolves native identities across all permission pages and keeps
348 /// email-bearing grants until dependent ID-only removals succeed. Dropbox pages direct and
349 /// inherited memberships separately and waits for the native removal job,
350 /// preserving its failure cause; group and parent access remain reported.
351 async fn revoke_access(&self, account: &str) -> Result<Vec<RetainedAccess>, StorageError>;
352 /// Begin a create-once upload, returning the value to record before parts are sent.
353 async fn begin_upload(
354 &self,
355 path: &ObjectPath,
356 total: u64,
357 ) -> Result<UploadSession, StorageError>;
358 /// Begin a fresh recorded session after resumption or publication reports
359 /// `SessionExpired`. A conflicted S3 session must be aborted first; failed
360 /// cleanup prevents a replacement from starting.
361 /// The destination and total stay fixed; the caller records the returned value
362 /// and supplies the retained encrypted bytes again, starting at offset zero.
363 async fn restart_upload(&self, expired: &UploadSession) -> Result<UploadSession, StorageError> {
364 expired.check(&self.config())?;
365 if expired.is_complete() {
366 return Err(StorageFailure::InvalidPart.into());
367 }
368 if matches!(expired.state, crate::session::SessionState::S3Restart { .. }) {
369 self.abort_upload(expired).await?;
370 }
371 self.begin_upload(expired.path(), expired.total_bytes()).await
372 }
373 /// Refresh a recorded session from the provider after interruption.
374 /// Persist the returned state even on failure, as with `finish_upload`.
375 async fn resume_upload(&self, session: &mut UploadSession) -> Result<(), StorageError>;
376 /// Admit `bytes` as the session's next part, the first it has still to
377 /// send ([`UploadSession::parts_to_send`]), sending nothing. Refused
378 /// while a provider cooldown is live, for a session naming another
379 /// location, for a part that doesn't fit the session, and while its
380 /// destination can't be published (§17.9). Admitting a planned
381 /// session's first part marks its plan, before any request that may
382 /// start its upload: when [`PartPermit::marked`] says so, save the
383 /// session before sending the part (Appendix E.10).
384 fn admit_part<'a>(
385 &self,
386 session: &mut UploadSession,
387 bytes: &'a [u8],
388 ) -> Result<PartPermit<'a>, StorageError>;
389 /// Send an admitted part, advancing the value only after confirmation,
390 /// and telling `sent` how far through the object the part's bytes the
391 /// connection has taken reach, as [`Self::create_reporting`] does. After
392 /// a lost publication reply this verifies the stored bytes instead; see
393 /// [`UploadSession`].
394 async fn send_part(
395 &self,
396 permit: PartPermit<'_>,
397 session: &mut UploadSession,
398 sent: &ByteProgress,
399 ) -> Result<(), StorageError>;
400 /// Send part `offset..` of a session whose parts are independent
401 /// ([`UploadSession::parts_independent`]), leaving the session as it is:
402 /// the provider's confirmation comes back, for the caller to add with
403 /// [`UploadSession::confirm`] and then record. Several parts may be in
404 /// flight at once and come back in any order (§17.9). Refused, sending
405 /// nothing, while a provider cooldown is live, for a session naming
406 /// another location or whose parts go in order, for a part that isn't a
407 /// whole one the session lacks, and while its destination can't be
408 /// published. `sent` hears the part's bytes as [`Self::send_part`]'s do.
409 async fn send_independent_part(
410 &self,
411 session: &UploadSession,
412 offset: u64,
413 bytes: &[u8],
414 sent: &ByteProgress,
415 ) -> Result<crate::ConfirmedPart, StorageError>;
416 /// Admit and send the next part, for a caller that records the session
417 /// only after the part: one that never resumes a planned session from a
418 /// recording.
419 async fn upload_part(
420 &self,
421 session: &mut UploadSession,
422 bytes: &[u8],
423 ) -> Result<(), StorageError> {
424 let permit = self.admit_part(session, bytes)?;
425 self.send_part(permit, session, &ByteProgress::unread()).await
426 }
427 /// Publish all stored parts at the destination. A repeated completion is safe.
428 /// Persist the session even on failure. `SessionExpired` requires a fresh
429 /// session with the same bytes; a `Cleanup` error must not bypass failed abort.
430 async fn finish_upload(&self, session: &mut UploadSession) -> Result<(), StorageError>;
431 /// Explicitly abandon an upload. Dropping a recorded value does not abort it.
432 /// Already closed or absent sessions succeed; published objects are preserved.
433 async fn abort_upload(&self, session: &UploadSession) -> Result<(), StorageError>;
434 /// End every unfinished session at slots 1 to `through` of `store`,
435 /// which this device has applied, whoever began it (§17.10): create-once
436 /// refuses each of them there, so none can ever publish, and a claimant
437 /// whose session is ended settles its claim as lost, as a refused one
438 /// does. Ending one already ended succeeds. Only S3 under conditional
439 /// completion puts a claim's session at its slot's path.
440 async fn end_settled_claims(
441 &self,
442 store: coven_foundation::id_source::StoreId,
443 through: u64,
444 ) -> Result<(), StorageError>;
445 /// End every upload `device` left in `store` that this sign-in can see
446 /// (§17.10): abort its unfinished sessions and delete what it staged in
447 /// its reserved folder. One already ended succeeds, so devices may do it
448 /// at once. A Dropbox session, and a OneDrive native one, is seen by no
449 /// one else and expires on its own: on Dropbox this ends nothing, and on
450 /// OneDrive only staged temporaries (Appendix E.2).
451 async fn end_device_uploads(
452 &self,
453 store: coven_foundation::id_source::StoreId,
454 device: coven_foundation::id_source::DeviceId,
455 ) -> Result<(), StorageError>;
456}