Skip to main content

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}