Skip to main content

coven_storage/
provider_ops.rs

1//! Provider calls beneath the common storage contract.
2
3use crate::*;
4use coven_foundation::id_source::{DeviceId, StoreId};
5
6/// Native calls used by [`StorageConnection`]. Consumers use [`Storage`];
7/// implementations handle provider protocols after the connection checks paths,
8/// request sizes and recorded sessions. Construction receives validated settings.
9#[async_trait::async_trait]
10pub trait ProviderOps: Send + Sync {
11    /// This provider's location.
12    fn config(&self) -> StorageConfig;
13    /// Largest complete body accepted by `create` or `replace`.
14    fn single_request_limit(&self) -> u64;
15    /// The size of the parts a ranged read moves whole
16    /// ([`crate::Storage::read_part_size`]); `None` when a range moves only
17    /// its own bytes.
18    fn read_part_size(&self) -> Option<std::num::NonZeroU64> {
19        None
20    }
21    /// Create D10's location marker at the location's root with the
22    /// provider's create-once request. Only first setup at a location that
23    /// holds one store calls this operation. Anything it stages sits in
24    /// `device`'s reserved folder (D10).
25    async fn create_location_marker(
26        &self,
27        _store: coven_foundation::id_source::StoreId,
28        _device: DeviceId,
29    ) -> Result<(), StorageError> {
30        Err(StorageFailure::ProviderUnavailable.into())
31    }
32    /// Read the complete location marker, bounded to D10's UUID byte count.
33    /// Only a location that holds one store calls this operation. A marker
34    /// read that finds nothing confirms the location is still there first.
35    async fn read_location_marker(&self) -> Result<Vec<u8>, StorageError> {
36        Err(StorageFailure::ProviderUnavailable.into())
37    }
38    /// The store's folder's name and web address as this connection's
39    /// account names them now (§20.2). Only a Dropbox shared folder or a
40    /// OneDrive folder has them; nothing asks another location.
41    async fn folder_label(&self) -> Result<FolderLabel, StorageError> {
42        Err(StorageFailure::ProviderUnavailable.into())
43    }
44    /// Signed-in account; coven shares nothing on S3, so it has none.
45    async fn account(&self) -> Result<String, StorageError> {
46        Err(StorageFailure::InvalidConfiguration.with_source("provider has no sharing account"))
47    }
48    /// The signed-in account's id and primary address.
49    async fn account_identity(&self) -> Result<crate::ProviderAccount, StorageError> {
50        Err(StorageFailure::InvalidConfiguration.with_source("provider has no sharing account"))
51    }
52    /// Replace tokens after credential custody commits them.
53    async fn set_oauth_tokens(&self, _tokens: OAuthTokens) -> Result<(), StorageError> {
54        Err(StorageFailure::InvalidConfiguration.with_source("provider does not use OAuth"))
55    }
56    /// The id of the S3 key this provider signs with now, without its secret.
57    async fn s3_access_key_id(&self) -> Option<String> {
58        None
59    }
60    /// Replace the S3 signing key after credential custody commits it.
61    async fn set_s3_credentials(&self, _credentials: S3Credentials) -> Result<(), StorageError> {
62        Err(StorageFailure::InvalidConfiguration.with_source("provider does not use S3 keys"))
63    }
64    /// Create in one request, telling `sent` the body's bytes as the
65    /// provider's client hands them over. A temporary it stages sits in
66    /// `device`'s reserved folder (D10).
67    /// Returns the created object's metadata when the reply carries it.
68    async fn create(
69        &self,
70        publication: &PublicationRequest,
71        path: &ObjectPath,
72        bytes: &[u8],
73        sent: &ByteProgress,
74        device: DeviceId,
75    ) -> Result<Option<StoredObject>, StorageError>;
76    /// Replace the observed object in one atomic conditional publication. A
77    /// temporary it stages sits in `device`'s reserved folder (D10).
78    async fn replace(
79        &self,
80        publication: &PublicationRequest,
81        previous: &StoredObject,
82        bytes: &[u8],
83        device: DeviceId,
84    ) -> Result<(), StorageError>;
85    /// Exact native lookup; only a confirmed missing object returns None.
86    async fn status(&self, path: &ObjectPath) -> Result<Option<StoredObject>, StorageError>;
87    /// Read complete bytes or a range, retaining metadata for those exact bytes.
88    /// The connection hears the stream's reads itself; a client that fetches
89    /// bytes before the stream yields them tells `received` how far through
90    /// the object they reach as they arrive, counted from the object's start.
91    async fn stream_object(
92        &self,
93        path: &ObjectPath,
94        range: Option<ByteRange>,
95        received: &ByteProgress,
96    ) -> Result<crate::ObjectStream<'_>, StorageError>;
97    /// Collect a bounded response through the streaming implementation. Large
98    /// writes and snapshots consume `stream_object` directly. This convenience
99    /// reader holds at most 32 MiB, regardless of provider metadata.
100    async fn read_object(
101        &self,
102        path: &ObjectPath,
103        range: Option<ByteRange>,
104    ) -> Result<ObjectRead, StorageError> {
105        self.stream_object(path, range, &ByteProgress::unread())
106            .await?
107            .collect(crate::object_stream::BUFFERED_READ_LIMIT)
108            .await
109    }
110    /// Consume native pages into the connection's checked listing.
111    async fn list(&self, listing: &mut ObjectListing) -> Result<(), StorageError>;
112
113    /// Delete, accepting an already absent object.
114    async fn delete(&self, path: &ObjectPath) -> Result<(), StorageError>;
115    /// Grant account access, or return S3's console instructions.
116    async fn grant_access(&self, account: &str) -> Result<AccessGrant, StorageError>;
117    /// Accept native sharing material. The connection checks location and reads
118    /// the exact floor status afterwards to verify readability.
119    async fn join(&self, invitation: &StorageInvitation) -> Result<(), StorageError> {
120        if !matches!(invitation.acceptance, crate::invitation::InvitationAcceptance::Granted) {
121            return Err(
122                StorageFailure::InvalidConfiguration.with_source("provider acceptance required")
123            );
124        }
125        Ok(())
126    }
127    /// Undo [`Self::join`]'s acceptance so the invite stays usable
128    /// ([`crate::Storage::leave`]). Access an invite grants without native
129    /// acceptance has nothing to undo.
130    async fn leave(&self, invitation: &StorageInvitation) -> Result<(), StorageError> {
131        if !matches!(invitation.acceptance, crate::invitation::InvitationAcceptance::Granted) {
132            return Err(
133                StorageFailure::InvalidConfiguration.with_source("provider acceptance required")
134            );
135        }
136        Ok(())
137    }
138    /// Remove exclusive grants and return grants that still reach the account.
139    async fn revoke_access(&self, account: &str) -> Result<Vec<RetainedAccess>, StorageError>;
140    /// Begin a nonempty create-once upload at `path`, for `device`, whose
141    /// reserved folder holds its temporaries (D10).
142    async fn begin_upload(
143        &self,
144        publication: &PublicationRequest,
145        path: &ObjectPath,
146        total: u64,
147        device: DeviceId,
148    ) -> Result<UploadSession, StorageError>;
149    /// Recover native progress of a validated, incomplete session.
150    async fn resume_upload(
151        &self,
152        publication: &PublicationRequest,
153        session: &mut UploadSession,
154    ) -> Result<(), StorageError>;
155    /// Send a checked part ending at `end`. The connection validates its length,
156    /// boundary and session; implementations enforce the native protocol.
157    /// `sent` already counts from the part's start in the object.
158    async fn upload_part(
159        &self,
160        publication: &PublicationRequest,
161        session: &mut UploadSession,
162        bytes: &[u8],
163        end: u64,
164        sent: &ByteProgress,
165    ) -> Result<(), StorageError>;
166    /// Send part `offset..` of a session whose parts are independent
167    /// ([`UploadSession::parts_independent`]), leaving the session as it
168    /// is: the provider's confirmation of the part comes back, for the
169    /// caller to add. Several may be in flight at once. The connection
170    /// checks the part is a whole one the session lacks; `sent` already
171    /// counts from the part's start in the object. A provider whose parts
172    /// go in order has none to send this way.
173    async fn send_independent_part(
174        &self,
175        _publication: &PublicationRequest,
176        _session: &UploadSession,
177        _offset: u64,
178        _bytes: &[u8],
179        _sent: &ByteProgress,
180    ) -> Result<ConfirmedPart, StorageError> {
181        Err(StorageFailure::InvalidPart.into())
182    }
183    /// Publish an incomplete session, checking native progress where required.
184    async fn finish_upload(
185        &self,
186        publication: &PublicationRequest,
187        session: &mut UploadSession,
188    ) -> Result<(), StorageError>;
189    /// Abandon an incomplete session without deleting published bytes.
190    async fn abort_upload(
191        &self,
192        publication: &PublicationRequest,
193        session: &UploadSession,
194    ) -> Result<(), StorageError>;
195    /// The uploads `device` left in `store` that this sign-in can see: the
196    /// sessions and temporaries in its reserved folder (D10), and, where the
197    /// provider puts a session at its destination, those under the device's
198    /// file and snapshot folders. Every page of each listing is followed.
199    async fn device_uploads(
200        &self,
201        store: StoreId,
202        device: DeviceId,
203    ) -> Result<Vec<LeftUpload>, StorageError>;
204    /// The unfinished sessions at slots 1 to `through` of `store`, whoever
205    /// began them: where a claim's session sits at its slot's path, one at
206    /// a slot this device has applied can never publish, since create-once
207    /// refuses it there. A provider that puts no session at a slot's path
208    /// returns none.
209    async fn settled_claim_uploads(
210        &self,
211        store: StoreId,
212        through: u64,
213    ) -> Result<Vec<LeftUpload>, StorageError>;
214    /// What S3 detection run `run` left in `store`'s `.coven-check` prefix
215    /// (§20.7): its unfinished multipart uploads, then its probes. Only S3
216    /// detects, so elsewhere no run left anything.
217    async fn detection_leftovers(
218        &self,
219        _store: StoreId,
220        _run: uuid::Uuid,
221    ) -> Result<Vec<LeftUpload>, StorageError> {
222        Ok(Vec::new())
223    }
224    /// End one upload another device left, as this provider listed it: abort
225    /// the session, or delete what it staged. One already ended succeeds,
226    /// and a published object is never touched.
227    async fn end_left_upload(&self, upload: &LeftUpload) -> Result<(), StorageError>;
228}