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}