Skip to main content

coven_storage/
test_utils.rs

1//! An in-memory provider, fault injection and the shared provider conformance suite.
2/// The store shared by the deterministic storage and format fixtures.
3pub const STORE_ID: coven_foundation::id_source::StoreId =
4    coven_foundation::id_source::StoreId(uuid::Uuid::from_bytes([0x10; 16]));
5/// The device a test connection writes for, unless a test names another.
6pub const DEVICE: coven_foundation::id_source::DeviceId =
7    coven_foundation::id_source::DeviceId(4242);
8
9use crate::session::SessionState;
10use crate::*;
11use async_trait::async_trait;
12use coven_foundation::clock::ClockRef;
13use std::collections::BTreeMap;
14use std::sync::Arc;
15use std::time::Duration;
16use tokio::sync::Mutex;
17
18#[path = "memory_upload.rs"]
19mod memory_upload;
20use memory_upload::Pending;
21
22#[path = "memory_reads.rs"]
23mod memory_reads;
24pub use memory_reads::BodyFailure;
25#[path = "memory_listing.rs"]
26mod memory_listing;
27#[path = "memory_requests.rs"]
28mod memory_requests;
29pub use memory_requests::{KeyRefusal, MemoryRequest};
30
31#[path = "memory_faults.rs"]
32mod memory_faults;
33#[path = "memory_objects.rs"]
34mod memory_objects;
35pub use memory_faults::{Faults, Garble};
36
37struct Object {
38    upload_id: Option<u64>,
39    bytes: Arc<[u8]>,
40    stored_at: coven_format::value::StorageTime,
41    revision: u64,
42}
43impl Object {
44    fn metadata(&self, path: &ObjectPath, time_resolution: Duration) -> StoredObject {
45        StoredObject {
46            path: path.clone(),
47            size: self.bytes.len() as u64,
48            stored_at: self.stored_at,
49            time_resolution,
50            object_id: path.as_str().into(),
51            revision: self.revision.to_string(),
52            replace_token: self.revision.to_string(),
53            checksum: None,
54        }
55    }
56}
57/// The account holding a fake store, as `account()` reports it to its owner.
58const OWNER_ACCOUNT: &str = "owner@example.test";
59
60/// The id the fake gives the account with this address.
61pub fn account_id(address: &str) -> String {
62    format!("id:{}", address.to_ascii_lowercase())
63}
64
65#[derive(Clone)]
66enum Account {
67    Owner,
68    Recipient(String),
69}
70enum AccountAccess {
71    Invited,
72    Joined,
73}
74struct MemoryState {
75    location_marker: Option<Vec<u8>>,
76    /// The store's folder's name, which `rename_folder` changes.
77    folder_name: String,
78    objects: memory_objects::MemoryObjects,
79    uploads: BTreeMap<u64, Pending>,
80    next: u64,
81    accounts: BTreeMap<String, AccountAccess>,
82    retained_access: BTreeMap<String, Vec<RetainedAccess>>,
83    faults: Faults,
84    /// The test's barrier and gate each create waits at, the gate each part
85    /// waits at, and the gate each read waits at (`MemoryStorage::hold_creations`
86    /// and the gates).
87    creation_barrier: Option<Arc<tokio::sync::Barrier>>,
88    creation_gate: Option<Arc<tokio::sync::Semaphore>>,
89    part_gate: Option<Arc<tokio::sync::Semaphore>>,
90    read_gate: Option<Arc<tokio::sync::Semaphore>>,
91    ranges: Vec<ByteRange>,
92    reads: Vec<(ObjectPath, u64, u64)>,
93    /// The bytes reads of each object moved (`MemoryStorage::moved_bytes`).
94    moved: BTreeMap<ObjectPath, u64>,
95    received_buffers: Vec<usize>,
96    sent_bytes: u64,
97    largest_part: usize,
98    held_listing: Option<HeldRequest>,
99    held_read: Option<memory_reads::HeldRead>,
100    held_body: Option<memory_reads::HeldBody>,
101    held_creation: Option<HeldRequest>,
102    held_request: Option<HeldNext>,
103    held_access: Option<memory_requests::HeldAccess>,
104    rejected_tokens: std::collections::BTreeSet<String>,
105    /// S3 keys storage refuses, by key id (`MemoryStorage::refuse_s3_key`).
106    refused_s3_keys: BTreeMap<String, memory_requests::KeyRefusal>,
107}
108
109impl MemoryState {
110    fn next_id(&mut self) -> Result<u64, StorageError> {
111        let id = self.next;
112        self.next = id
113            .checked_add(1)
114            .ok_or(StorageFailure::Protocol.with_source("memory ids exhausted"))?;
115        Ok(id)
116    }
117
118    /// Answer a write that stored its object with a 429 while
119    /// `refuse_after_storing` lasts.
120    fn refused_after_storing(&mut self, provider: CloudProvider) -> Result<(), StorageError> {
121        if self.faults.refuse_after_storing == 0 {
122            return Ok(());
123        }
124        self.faults.refuse_after_storing -= 1;
125        Err(crate::providers::ProviderResponse::injected(
126            provider,
127            StorageFailure::RateLimited,
128            429,
129            None,
130        ))
131    }
132}
133
134/// Hears each request this provider's connections attempt, counted from the
135/// first, failed ones included (`MemoryStorage::subscribe_requests`).
136pub struct RequestWatch(tokio::sync::watch::Receiver<u64>);
137
138impl RequestWatch {
139    /// How many requests have been attempted, which later waits count on
140    /// from.
141    pub fn current(&mut self) -> u64 {
142        *self.0.borrow_and_update()
143    }
144
145    /// Resolves once another request is attempted; an error once the
146    /// provider is gone.
147    pub async fn changed(&mut self) -> Result<(), tokio::sync::watch::error::RecvError> {
148        self.0.changed().await
149    }
150
151    /// Resolves once `reached` holds of the count of requests attempted; an
152    /// error once the provider is gone first.
153    pub async fn wait_for(
154        &mut self,
155        reached: impl FnMut(&u64) -> bool,
156    ) -> Result<(), tokio::sync::watch::error::RecvError> {
157        self.0.wait_for(reached).await.map(drop)
158    }
159}
160
161/// The next request, of any kind or only `request`, held once it is
162/// recorded.
163struct HeldNext {
164    request: Option<MemoryRequest>,
165    started: tokio::sync::oneshot::Sender<()>,
166    resume: tokio::sync::oneshot::Receiver<()>,
167}
168
169struct HeldRequest {
170    prefix: ObjectPrefix,
171    listed: tokio::sync::oneshot::Sender<()>,
172    resume: tokio::sync::oneshot::Receiver<()>,
173}
174
175/// Clones share a provider's durable objects and sessions across simulated crashes.
176/// Publication is timestamped by the injected clock and retains the upload's
177/// identity after pending parts are discarded. [`Faults`] can lose part/completion
178/// replies or expire pending sessions without losing published objects.
179///
180/// [`Self::for_recipient`] shares the backend with a separate account and sign-in.
181/// Grants and acceptance govern that account's reads, writes and uploads; revoking
182/// it leaves the owner and other recipients untouched. Clones share their account's
183/// tokens, and replacement tokens govern subsequent calls on the same adapter.
184/// A token named by [`Self::reject_access_token`] is refused as a provider 401
185/// would be: the call refreshes once through its connection's custody and
186/// retries once, as the HTTP adapters do (§20.2).
187/// S3 console keys are outside this account-sharing model.
188/// Implements [`crate::providers::StorageConnector`] so application tests can
189/// exercise saved settings and credential custody through the `test-utils`
190/// builder's connector hook.
191pub type MemoryStorage = StorageConnection<MemoryProvider>;
192
193/// In-memory native calls used beneath the shared storage connection.
194#[derive(Clone)]
195pub struct MemoryProvider {
196    config: StorageConfig,
197    online: Arc<std::sync::atomic::AtomicBool>,
198    single_limit: u64,
199    part_size: usize,
200    /// Whether its sessions' parts are independent, as an S3 multipart
201    /// upload's are, rather than taken in order.
202    independent_parts: bool,
203    /// Whether a read moves every part it touches whole, as CloudKit's do.
204    whole_part_reads: bool,
205    listing_page: usize,
206    requests: Arc<tokio::sync::watch::Sender<u64>>,
207    request_trace: Arc<std::sync::Mutex<Vec<MemoryRequest>>>,
208    active_requests: Arc<std::sync::atomic::AtomicUsize>,
209    peak_requests: Arc<std::sync::atomic::AtomicUsize>,
210    account: Account,
211    clock: ClockRef,
212    time_resolution: Duration,
213    tokens: Arc<Mutex<Option<Arc<crate::HeldTokens>>>>,
214    s3_key: Arc<Mutex<Option<S3Credentials>>>,
215    state: Arc<Mutex<MemoryState>>,
216}
217impl Clone for MemoryStorage {
218    fn clone(&self) -> Self {
219        Self::with_gate(
220            self.provider.clone(),
221            self.device,
222            self.publications.clone(),
223            self.cooldown.clone(),
224            self.transfers.clone(),
225            self.provider.clock.clone(),
226        )
227    }
228}
229
230/// Custody for tokens installed directly on a fake connection: a rejection
231/// cannot be refreshed and reaches the caller as `Authentication`.
232pub struct RefusedRefresh;
233#[async_trait]
234impl crate::TokenCustody for RefusedRefresh {
235    async fn replace(&self, _: &OAuthTokens) -> Result<OAuthTokens, StorageError> {
236        Err(StorageFailure::Authentication.with_source("this sign-in has no custody to refresh it"))
237    }
238}
239
240/// Authority for raw provider fixtures, which seed objects without a sync owner.
241pub struct UnrestrictedPublications;
242impl PublicationGate for UnrestrictedPublications {
243    fn check(&self, _: &ObjectPath) -> Result<(), StorageError> {
244        Ok(())
245    }
246}
247
248/// Admit `bytes` as `session`'s next part as a connection does with no
249/// cooldown live and every destination open, for a fake [`Storage`] of a
250/// test: the part must fit the session, and a plan's first part marks it.
251pub fn admitted_part<'a>(
252    session: &mut UploadSession,
253    bytes: &'a [u8],
254) -> Result<PartPermit<'a>, StorageError> {
255    let part = session.next_part(bytes.len())?;
256    let publication =
257        PublicationRequest::new(Arc::new(UnrestrictedPublications), session.path().clone());
258    Ok(PartPermit::admit(session, bytes, part, publication))
259}
260
261impl MemoryStorage {
262    /// Compose a connection over `provider` as `from_provider` does, timing
263    /// its requests by the provider's own clock.
264    pub(crate) fn from_memory(provider: Arc<MemoryProvider>) -> Self {
265        let clock = provider.clock.clone();
266        Self::with_gate(
267            provider,
268            DEVICE,
269            Arc::new(UnrestrictedPublications),
270            Arc::new(crate::NoCooldown),
271            Arc::new(crate::TransferBudget::new(crate::TransferLimits::default())),
272            clock,
273        )
274    }
275    /// An S3 test location at the Unix epoch, with four-MiB single requests
276    /// and 64-KiB parts. Override only the choices relevant to the scenario.
277    pub fn builder() -> MemoryStorageBuilder {
278        MemoryStorageBuilder::new()
279    }
280    /// A separate non-owner account using the same provider location. Its sign-in
281    /// is independent; access requires a grant and, where needed, recipient joining.
282    /// S3 keys are administered outside the fake's account-sharing model.
283    pub fn for_recipient(owner: &Self, email: &str) -> Result<Self, StorageError> {
284        if owner.provider.config.provider() == CloudProvider::S3 || email.is_empty() {
285            return Err(StorageFailure::InvalidConfiguration
286                .with_source("recipient requires a sharing account"));
287        }
288        Ok(Self::from_memory(Arc::new(MemoryProvider {
289            config: owner.config(),
290            online: Arc::new(std::sync::atomic::AtomicBool::new(true)),
291            single_limit: owner.provider.single_limit,
292            part_size: owner.provider.part_size,
293            independent_parts: owner.provider.independent_parts,
294            whole_part_reads: owner.provider.whole_part_reads,
295            listing_page: owner.provider.listing_page,
296            requests: owner.provider.requests.clone(),
297            request_trace: owner.provider.request_trace.clone(),
298            active_requests: owner.provider.active_requests.clone(),
299            peak_requests: owner.provider.peak_requests.clone(),
300            account: Account::Recipient(email.to_ascii_lowercase()),
301            clock: owner.provider.clock.clone(),
302            time_resolution: owner.provider.time_resolution,
303            tokens: Arc::new(Mutex::new(None)),
304            s3_key: Arc::new(Mutex::new(None)),
305            state: owner.provider.state.clone(),
306        })))
307    }
308    /// Another device connected to the same durable backend, with independent
309    /// credentials, request notifications and network availability.
310    pub fn for_device(&self) -> Self {
311        let mut device = (*self.provider).clone();
312        device.online = Arc::new(std::sync::atomic::AtomicBool::new(true));
313        device.tokens = Arc::new(Mutex::new(None));
314        device.s3_key = Arc::new(Mutex::new(None));
315        device.requests = Arc::new(tokio::sync::watch::channel(0).0);
316        device.request_trace = Arc::new(std::sync::Mutex::new(Vec::new()));
317        device.active_requests = Arc::new(std::sync::atomic::AtomicUsize::new(0));
318        device.peak_requests = Arc::new(std::sync::atomic::AtomicUsize::new(0));
319        Self::from_memory(Arc::new(device))
320    }
321    /// Construct a candidate device connection whose credentials can be inspected
322    /// independently from the source's credentials and durable provider objects.
323    pub async fn connect_device(
324        &self,
325        config: StorageConfig,
326        auth: crate::ProviderAuth,
327    ) -> Result<Self, StorageError> {
328        crate::ConnectionCredentials { location: config.clone(), credentials: auth.credentials() }
329            .validate()?;
330        if !config.same_location(&self.provider.config) {
331            return Err(StorageFailure::InvalidConfiguration
332                .with_source("memory connector location mismatch"));
333        }
334        let mut connection = (*self.provider).clone();
335        connection.config = config;
336        // Candidate setup must not mutate the old adapter's sign-in. Network
337        // controls and request observations still belong to this test device.
338        connection.tokens = Arc::new(Mutex::new(None));
339        connection.s3_key = Arc::new(Mutex::new(None));
340        match auth {
341            crate::ProviderAuth::OAuth { tokens, custody } => {
342                *connection.tokens.lock().await =
343                    Some(Arc::new(crate::HeldTokens::new(tokens, custody)));
344            }
345            crate::ProviderAuth::S3(keys) => connection.set_s3_credentials(keys).await?,
346            crate::ProviderAuth::CloudKit => {}
347        }
348        Ok(Self::from_memory(Arc::new(connection)))
349    }
350
351    /// Set this connection's network availability without changing other devices.
352    pub fn set_online(&self, online: bool) {
353        self.provider.online.store(online, std::sync::atomic::Ordering::SeqCst);
354    }
355    /// Request notifications include failed attempts, so tests can wait without polling.
356    pub fn subscribe_requests(&self) -> RequestWatch {
357        RequestWatch(self.provider.requests.subscribe())
358    }
359    /// Greatest number of requests overlapping an injected delay or barrier.
360    pub fn peak_requests(&self) -> usize {
361        self.provider.peak_requests.load(std::sync::atomic::Ordering::SeqCst)
362    }
363    /// Reset the peak for subsequent request starts, retaining active requests.
364    pub fn reset_request_peak(&self) {
365        self.provider.peak_requests.store(0, std::sync::atomic::Ordering::SeqCst);
366    }
367    /// Every attempted provider request, including injected failures.
368    pub fn request_count(&self) -> u64 {
369        *self.provider.requests.borrow()
370    }
371    /// The key currently installed on this simulated provider connection.
372    pub async fn s3_credentials(&self) -> Option<S3Credentials> {
373        self.provider.s3_key.lock().await.clone()
374    }
375    /// The most recently installed S3 access-key id, without exposing its secret.
376    pub async fn s3_access_key_id(&self) -> Option<String> {
377        self.s3_credentials().await.map(|key| key.access_key_id)
378    }
379    /// Opened ranged responses, in order.
380    pub async fn ranges(&self) -> Vec<ByteRange> {
381        self.provider.state.lock().await.ranges.clone()
382    }
383    /// Opened responses as (path, offset, declared byte count), including whole objects.
384    pub async fn reads(&self) -> Vec<(ObjectPath, u64, u64)> {
385        self.provider.state.lock().await.reads.clone()
386    }
387    /// The bytes the reads of `path` moved as their bodies delivered them:
388    /// each byte, or, on a provider whose reads move whole parts, each part
389    /// whole once a body delivered a byte of it.
390    pub async fn moved_bytes(&self, path: &ObjectPath) -> u64 {
391        self.provider.state.lock().await.moved.get(path).copied().unwrap_or(0)
392    }
393    /// Part bytes with successful replies and their largest buffer, across sessions.
394    pub async fn transferred(&self) -> (u64, usize) {
395        let state = self.provider.state.lock().await;
396        (state.sent_bytes, state.largest_part)
397    }
398    /// Damage one stored byte without issuing a provider request.
399    pub async fn corrupt_byte(&self, path: &ObjectPath, offset: usize) -> Result<(), StorageError> {
400        let mut state = self.provider.state.lock().await;
401        let object = state.objects.get_mut(path).ok_or(StorageFailure::NotFound)?;
402        let byte =
403            Arc::make_mut(&mut object.bytes).get_mut(offset).ok_or(StorageFailure::InvalidRange)?;
404        *byte ^= 1;
405        Ok(())
406    }
407    /// Store an object without a request or this connection's size limits,
408    /// as anyone holding the storage's credentials could (§3).
409    pub async fn plant(&self, path: &ObjectPath, bytes: &[u8]) -> Result<(), StorageError> {
410        let stored_at = self.provider.storage_time()?;
411        let mut state = self.provider.state.lock().await;
412        let revision = state.next_id()?;
413        state.objects.insert(
414            path.clone(),
415            Object { revision, upload_id: None, bytes: bytes.into(), stored_at },
416        );
417        Ok(())
418    }
419    /// Resolves once the provider holds an object at a path `wanted`
420    /// accepts, with that path; no request is made. A request is in the
421    /// trace as it goes out, before its object is stored, so the trace
422    /// can't tell this.
423    pub async fn wait_for_object(&self, wanted: impl Fn(&ObjectPath) -> bool) -> ObjectPath {
424        let mut changes = self.provider.state.lock().await.objects.watch();
425        loop {
426            let state = self.provider.state.lock().await;
427            if let Some(path) = state.objects.keys().find(|path| wanted(path)) {
428                return path.clone();
429            }
430            drop(state);
431            changes.changed().await;
432        }
433    }
434    /// Refuse this access token from now on, on every connection, as a
435    /// provider 401 would (§20.2).
436    pub async fn reject_access_token(&self, token: &str) {
437        self.provider.state.lock().await.rejected_tokens.insert(token.into());
438    }
439    /// Set faults absolutely, so repeating the command has the same effect.
440    pub async fn set_faults(&self, faults: Faults) {
441        self.provider.state.lock().await.faults = faults;
442    }
443    /// Hold each create, including injected failures, until all writers
444    /// arrive at the test's `barrier`.
445    pub async fn hold_creations(&self, barrier: Arc<tokio::sync::Barrier>) {
446        self.provider.state.lock().await.creation_barrier = Some(barrier);
447    }
448    /// Hold each create until the test adds a permit to `gate`; each create
449    /// takes one, oldest first, so a test releases held creates one at a time.
450    pub async fn gate_creations(&self, gate: Arc<tokio::sync::Semaphore>) {
451        self.provider.state.lock().await.creation_gate = Some(gate);
452    }
453    /// Hold each part, its bytes taken, until the test adds a permit to
454    /// `gate`; each part takes one, oldest first.
455    pub async fn gate_parts(&self, gate: Arc<tokio::sync::Semaphore>) {
456        self.provider.state.lock().await.part_gate = Some(gate);
457    }
458    /// Hold each read until the test adds a permit to `gate`; each read takes
459    /// one, oldest first.
460    pub async fn gate_reads(&self, gate: Arc<tokio::sync::Semaphore>) {
461        self.provider.state.lock().await.read_gate = Some(gate);
462    }
463    /// Whether the store is shared with `account`: granted and not since
464    /// revoked.
465    pub async fn shared_with(&self, account: &str) -> bool {
466        self.provider.state.lock().await.accounts.contains_key(&account.to_ascii_lowercase())
467    }
468    /// Whether `account` has accepted the store's share, as a Dropbox mount
469    /// does, and not since left it or lost it.
470    pub async fn joined(&self, account: &str) -> bool {
471        matches!(
472            self.provider.state.lock().await.accounts.get(&account.to_ascii_lowercase()),
473            Some(AccountAccess::Joined)
474        )
475    }
476    /// Model native grants that remain until the owner changes them in the provider.
477    pub async fn set_retained_access(&self, account: &str, shares: Vec<RetainedAccess>) {
478        let mut state = self.provider.state.lock().await;
479        let account = account.to_ascii_lowercase();
480        if shares.is_empty() {
481            state.retained_access.remove(&account);
482        } else {
483            state.retained_access.insert(account, shares);
484        }
485    }
486}
487
488impl MemoryProvider {
489    /// Refuse the upload of the file at `path` as it starts, while
490    /// `Faults::refuse_file_uploads` counts refusals left, or panic in it
491    /// while `Faults::panic_file_uploads` counts panics left; any other path
492    /// goes through.
493    async fn refuse_file_upload(&self, path: &ObjectPath) -> Result<(), StorageError> {
494        if path.object_id().is_none() {
495            return Ok(());
496        }
497        let mut state = self.state.lock().await;
498        if state.faults.panic_file_uploads > 0 {
499            state.faults.panic_file_uploads -= 1;
500            drop(state);
501            panic!("the upload of {path:?} panicked");
502        }
503        if state.faults.refuse_file_uploads == 0 {
504            return Ok(());
505        }
506        state.faults.refuse_file_uploads -= 1;
507        let faults = &state.faults;
508        Err(self.injected((faults.failure, faults.response, faults.retry_after)))
509    }
510    fn session_id(&self, session: &UploadSession) -> Result<u64, StorageError> {
511        match session.state {
512            SessionState::Memory { id, .. } | SessionState::MemoryParts { id, .. } => Ok(id),
513            _ => Err(StorageFailure::SessionMismatch.into()),
514        }
515    }
516}
517
518#[async_trait]
519impl ProviderOps for MemoryProvider {
520    async fn create_location_marker(
521        &self,
522        store: coven_foundation::id_source::StoreId,
523        _device: coven_foundation::id_source::DeviceId,
524    ) -> Result<(), StorageError> {
525        self.before(MemoryRequest::Other("create_location_marker")).await?;
526        let mut state = self.state.lock().await;
527        if state.location_marker.is_some() {
528            return Err(StorageFailure::AlreadyExists.into());
529        }
530        state.location_marker = Some(store.to_string().into_bytes());
531        if std::mem::replace(&mut state.faults.lose_completion_reply, false) {
532            return Err(StorageFailure::Network.into());
533        }
534        Ok(())
535    }
536    async fn read_location_marker(&self) -> Result<Vec<u8>, StorageError> {
537        self.before(MemoryRequest::Other("read_location_marker")).await?;
538        self.state.lock().await.location_marker.clone().ok_or(StorageFailure::NotFound.into())
539    }
540    /// A Dropbox shared folder's or a OneDrive folder's address is under
541    /// `storage.example.test`, after its id.
542    async fn folder_label(&self) -> Result<crate::FolderLabel, StorageError> {
543        self.before(MemoryRequest::Other("folder_label")).await?;
544        let id = match &self.config {
545            StorageConfig::Dropbox {
546                location: crate::DropboxLocation::SharedFolder { namespace_id },
547                ..
548            } => namespace_id,
549            StorageConfig::OneDrive { folder_id, .. } => folder_id,
550            _ => return Err(StorageFailure::ProviderUnavailable.into()),
551        };
552        let mut web_url = url::Url::parse("https://storage.example.test/folders/")
553            .expect("a fixed address parses");
554        web_url.path_segments_mut().expect("an https address holds paths").pop_if_empty().push(id);
555        Ok(crate::FolderLabel { name: self.state.lock().await.folder_name.clone(), web_url })
556    }
557    async fn account(&self) -> Result<String, StorageError> {
558        self.before_request(MemoryRequest::Other("account")).await?;
559        Ok(match &self.account {
560            Account::Owner => OWNER_ACCOUNT.into(),
561            Account::Recipient(account) => account.clone(),
562        })
563    }
564    /// The fake's id for an account is its address behind `id:`.
565    async fn account_identity(&self) -> Result<crate::ProviderAccount, StorageError> {
566        let address = ProviderOps::account(self).await?;
567        Ok(crate::ProviderAccount { id: Some(account_id(&address)), address })
568    }
569    async fn s3_access_key_id(&self) -> Option<String> {
570        self.s3_key.lock().await.as_ref().map(|key| key.access_key_id.clone())
571    }
572    async fn set_s3_credentials(&self, credentials: S3Credentials) -> Result<(), StorageError> {
573        credentials.validate()?;
574        if self.config.provider() != CloudProvider::S3 {
575            return Err(StorageFailure::InvalidConfiguration.with_source("invalid S3 key"));
576        }
577        *self.s3_key.lock().await = Some(credentials);
578        Ok(())
579    }
580    fn config(&self) -> StorageConfig {
581        self.config.clone()
582    }
583    async fn set_oauth_tokens(&self, tokens: OAuthTokens) -> Result<(), StorageError> {
584        if !self.config.provider().signs_in_with_oauth() {
585            return Err(
586                StorageFailure::InvalidConfiguration.with_source("provider does not use OAuth")
587            );
588        }
589        let mut held = self.tokens.lock().await;
590        match held.as_ref() {
591            Some(held) => held.install(tokens).await,
592            None => {
593                *held = Some(Arc::new(crate::HeldTokens::new(tokens, Arc::new(RefusedRefresh))))
594            }
595        }
596        Ok(())
597    }
598    fn single_request_limit(&self) -> u64 {
599        self.single_limit
600    }
601    fn read_part_size(&self) -> Option<std::num::NonZeroU64> {
602        std::num::NonZeroU64::new(self.part_size as u64).filter(|_| self.whole_part_reads)
603    }
604    #[expect(
605        clippy::map_err_ignore,
606        reason = "a send fails only when the receiver is gone, which this names"
607    )]
608    async fn create(
609        &self,
610        publication: &PublicationRequest,
611        path: &ObjectPath,
612        bytes: &[u8],
613        sent: &ByteProgress,
614        _device: coven_foundation::id_source::DeviceId,
615    ) -> Result<Option<StoredObject>, StorageError> {
616        publication.check()?;
617        // The whole body is taken as the call starts; a held create waits
618        // for its reply with every byte sent.
619        sent.moved(bytes.len() as u64);
620        self.before(MemoryRequest::Create(path.clone())).await?;
621        self.refuse_file_upload(path).await?;
622        let mut state = self.state.lock().await;
623        if let Some((failure, status)) = state.faults.create_failures.get(path) {
624            return Err(crate::providers::ProviderResponse::injected(
625                self.config.provider(),
626                *failure,
627                *status,
628                None,
629            ));
630        }
631        let held = if state.held_creation.as_ref().is_some_and(|held| held.prefix.contains(path)) {
632            state.held_creation.take()
633        } else {
634            None
635        };
636        drop(state);
637        if let Some(held) = held {
638            held.listed
639                .send(())
640                .map_err(|_| StorageFailure::Protocol.with_source("creation observer dropped"))?;
641            held.resume
642                .await
643                .map_err(|_| StorageFailure::Protocol.with_source("creation release dropped"))?;
644        }
645        let mut state = self.state.lock().await;
646        if state.objects.contains_key(path) && !state.faults.overwrite_create {
647            if state.faults.fail_duplicate_cleanup {
648                return Err(StorageError::Cleanup {
649                    operation: Box::new(StorageError::Failure(StorageFailure::AlreadyExists)),
650                    cleanup: Box::new(StorageError::Failure(StorageFailure::Network)),
651                });
652            }
653            return Err(StorageFailure::AlreadyExists.into());
654        }
655        let revision = state.next_id()?;
656        let object = Object {
657            revision,
658            upload_id: None,
659            bytes: bytes.into(),
660            stored_at: self.storage_time()?,
661        };
662        let created = object.metadata(path, self.time_resolution);
663        state.objects.insert(path.clone(), object);
664        if std::mem::replace(&mut state.faults.lose_completion_reply, false)
665            || state.faults.lose_reply_at.remove(path)
666        {
667            return Err(StorageFailure::Network.into());
668        }
669        state.refused_after_storing(self.config.provider())?;
670        Ok(Some(created))
671    }
672
673    async fn replace(
674        &self,
675        publication: &PublicationRequest,
676        previous: &StoredObject,
677        bytes: &[u8],
678        _device: coven_foundation::id_source::DeviceId,
679    ) -> Result<(), StorageError> {
680        let path = &previous.path;
681        publication.check()?;
682        self.before(MemoryRequest::Replace(path.clone())).await?;
683        let mut state = self.state.lock().await;
684        if state
685            .objects
686            .get(path)
687            .is_none_or(|object| object.revision.to_string() != previous.replace_token)
688        {
689            return Err(StorageFailure::Conflict.into());
690        }
691        if state.faults.refuse_replacements > 0 {
692            state.faults.refuse_replacements -= 1;
693            return Err(StorageFailure::Conflict.into());
694        }
695        let revision = state.next_id()?;
696        state.objects.insert(
697            path.clone(),
698            Object {
699                revision,
700                upload_id: None,
701                bytes: bytes.into(),
702                stored_at: self.storage_time()?,
703            },
704        );
705        if std::mem::replace(&mut state.faults.lose_completion_reply, false)
706            || state.faults.lose_reply_at.remove(path)
707        {
708            return Err(StorageFailure::Network.into());
709        }
710        state.refused_after_storing(self.config.provider())
711    }
712    async fn status(&self, path: &ObjectPath) -> Result<Option<StoredObject>, StorageError> {
713        self.before(MemoryRequest::Status(path.clone())).await?;
714        let state = self.state.lock().await;
715        if let Some(failure) = state.faults.status_failures.get(path) {
716            return Err((*failure).into());
717        }
718        Ok(state.objects.get(path).map(|object| object.metadata(path, self.time_resolution)))
719    }
720    async fn stream_object(
721        &self,
722        path: &ObjectPath,
723        range: Option<ByteRange>,
724        // The response body yields bytes as they arrive; the connection
725        // hears its reads.
726        _received: &ByteProgress,
727    ) -> Result<ObjectStream<'_>, StorageError> {
728        self.stream_recorded(path, range).await
729    }
730
731    #[expect(
732        clippy::map_err_ignore,
733        reason = "a send fails only when the receiver is gone, which this names"
734    )]
735    async fn list(&self, listing: &mut ObjectListing) -> Result<(), StorageError> {
736        let prefix = listing.prefix();
737        self.before(MemoryRequest::List(prefix.clone())).await?;
738        let now = self.storage_time()?;
739        let state = self.state.lock().await;
740        if let Some(failure) = state.faults.list_failures.get(prefix) {
741            return Err((*failure).into());
742        }
743        let objects: Vec<_> = state
744            .objects
745            .iter()
746            .filter(|(path, object)| {
747                !state.faults.hide_listings
748                    && prefix.contains(path)
749                    && state.faults.listing_lag.is_none_or(|lag| {
750                        now.duration_since(object.stored_at).is_some_and(|age| age > lag)
751                    })
752            })
753            .map(|(path, object)| object.metadata(path, self.time_resolution))
754            .collect::<Vec<_>>();
755        drop(state);
756        self.further_pages(MemoryRequest::List(prefix.clone()), objects.len()).await?;
757        let mut state = self.state.lock().await;
758        let hold = if state.held_listing.as_ref().is_some_and(|held| &held.prefix == prefix) {
759            state.held_listing.take()
760        } else {
761            None
762        };
763        drop(state);
764        if let Some(held) = hold {
765            held.listed
766                .send(())
767                .map_err(|_| StorageFailure::Protocol.with_source("listing observer dropped"))?;
768            held.resume
769                .await
770                .map_err(|_| StorageFailure::Protocol.with_source("listing release dropped"))?;
771        }
772        for object in objects {
773            listing.insert(object)?;
774        }
775        Ok(())
776    }
777    async fn delete(&self, path: &ObjectPath) -> Result<(), StorageError> {
778        self.before(MemoryRequest::Delete(path.clone())).await?;
779        let mut state = self.state.lock().await;
780        if let Some(failure) = state.faults.delete_failures.get(path) {
781            return Err((*failure).into());
782        }
783        state.objects.remove(path);
784        Ok(())
785    }
786    async fn grant_access(&self, account: &str) -> Result<AccessGrant, StorageError> {
787        self.hold_access(account, true).await;
788        self.before_request(MemoryRequest::Other("grant_access")).await?;
789        if self.config.provider() == CloudProvider::S3 {
790            return Ok(AccessGrant::CreateAccessKey);
791        }
792        if !matches!(self.account, Account::Owner) {
793            return Err(StorageFailure::NotStoreOwner.into());
794        }
795        if account.is_empty() {
796            return Err(StorageFailure::InvalidConfiguration.with_source("empty sharing account"));
797        }
798        if account.eq_ignore_ascii_case(OWNER_ACCOUNT) {
799            return Err(StorageFailure::InviteeIsStoreOwner.into());
800        }
801        if let Some(failure) = self.state.lock().await.faults.grant_failure {
802            return Err(failure.into());
803        }
804        let shared = crate::SharedWith::new(account, Some(account_id(account)))?;
805        let invitation = match self.config.provider() {
806            CloudProvider::CloudKit => StorageInvitation::new(
807                self.config(),
808                crate::invitation::InvitationAcceptance::CloudKitShare {
809                    url: coven_crypto::SecretText::new("https://icloud.com/share/memory".into()),
810                },
811            )?,
812            CloudProvider::OneDrive => StorageInvitation::new(
813                self.config(),
814                crate::invitation::InvitationAcceptance::OneDriveShare {
815                    token: coven_crypto::SecretText::new(account.to_ascii_lowercase()),
816                },
817            )?,
818            _ => StorageInvitation::for_account(self.config())?,
819        };
820        let invitation = match self.config.provider() {
821            CloudProvider::Dropbox | CloudProvider::OneDrive => invitation.shared_with(shared),
822            _ => invitation,
823        };
824        self.state
825            .lock()
826            .await
827            .accounts
828            .entry(account.to_ascii_lowercase())
829            .or_insert(AccountAccess::Invited);
830        Ok(AccessGrant::Granted { invitation })
831    }
832    async fn join(&self, invitation: &StorageInvitation) -> Result<(), StorageError> {
833        self.before_request(MemoryRequest::Other("join")).await?;
834        {
835            let mut state = self.state.lock().await;
836            if state.faults.accept_failures > 0 {
837                state.faults.accept_failures -= 1;
838                return Err(StorageFailure::Network.into());
839            }
840        }
841        use crate::invitation::InvitationAcceptance as Acceptance;
842        if matches!(invitation.acceptance, Acceptance::Granted) {
843            return Ok(());
844        }
845        if let Acceptance::CloudKitShare { url } = &invitation.acceptance {
846            if url.as_str() != "https://icloud.com/share/memory" {
847                return Err(StorageFailure::InvitationMismatch.into());
848            }
849        }
850        if let Account::Recipient(email) = &self.account {
851            match &invitation.acceptance {
852                Acceptance::OneDriveShare { token } if token.as_str() != email => {
853                    return Err(StorageFailure::InvitationMismatch.into())
854                }
855                _ => {}
856            }
857            let mut state = self.state.lock().await;
858            let access = state.accounts.get_mut(email).ok_or(StorageFailure::PermissionDenied)?;
859            *access = AccountAccess::Joined;
860        }
861        Ok(())
862    }
863    /// As Dropbox's unmount, the only provider undo: a mounted recipient
864    /// goes back to invited; one not joined, or no longer shared, is done.
865    /// Other providers' acceptance stays, as theirs does.
866    async fn leave(&self, invitation: &StorageInvitation) -> Result<(), StorageError> {
867        self.before_request(MemoryRequest::Other("leave")).await?;
868        {
869            let mut state = self.state.lock().await;
870            if state.faults.leave_failures > 0 {
871                state.faults.leave_failures -= 1;
872                return Err(StorageFailure::Network.into());
873            }
874        }
875        use crate::invitation::InvitationAcceptance as Acceptance;
876        if let (Acceptance::DropboxMount, Account::Recipient(email)) =
877            (&invitation.acceptance, &self.account)
878        {
879            if let Some(access) = self.state.lock().await.accounts.get_mut(email) {
880                *access = AccountAccess::Invited;
881            }
882        }
883        Ok(())
884    }
885    async fn revoke_access(&self, account: &str) -> Result<Vec<RetainedAccess>, StorageError> {
886        self.hold_access(account, false).await;
887        self.before_request(MemoryRequest::Other("revoke_access")).await?;
888        if self.config.provider() == CloudProvider::S3 {
889            return Err(
890                StorageFailure::InvalidConfiguration.with_source("S3 has no account sharing")
891            );
892        }
893        if !matches!(self.account, Account::Owner) {
894            return Err(StorageFailure::NotStoreOwner.into());
895        }
896        let mut state = self.state.lock().await;
897        let account = account.to_ascii_lowercase();
898        if let Some(shares) = state.retained_access.get(&account) {
899            return Ok(shares.clone());
900        }
901        state.accounts.remove(&account);
902        Ok(Vec::new())
903    }
904    async fn begin_upload(
905        &self,
906        publication: &PublicationRequest,
907        path: &ObjectPath,
908        total: u64,
909        device: coven_foundation::id_source::DeviceId,
910    ) -> Result<UploadSession, StorageError> {
911        self.memory_begin_upload(publication, path, total, device).await
912    }
913    async fn device_uploads(
914        &self,
915        store: coven_foundation::id_source::StoreId,
916        device: coven_foundation::id_source::DeviceId,
917    ) -> Result<Vec<LeftUpload>, StorageError> {
918        self.memory_device_uploads(store, device).await
919    }
920    async fn settled_claim_uploads(
921        &self,
922        store: coven_foundation::id_source::StoreId,
923        through: u64,
924    ) -> Result<Vec<LeftUpload>, StorageError> {
925        self.memory_settled_claim_uploads(store, through).await
926    }
927    async fn end_left_upload(&self, upload: &LeftUpload) -> Result<(), StorageError> {
928        self.memory_end_left_upload(upload).await
929    }
930    async fn resume_upload(
931        &self,
932        publication: &PublicationRequest,
933        session: &mut UploadSession,
934    ) -> Result<(), StorageError> {
935        self.memory_resume_upload(publication, session).await
936    }
937    async fn upload_part(
938        &self,
939        publication: &PublicationRequest,
940        session: &mut UploadSession,
941        bytes: &[u8],
942        end: u64,
943        sent: &ByteProgress,
944    ) -> Result<(), StorageError> {
945        self.memory_upload_part(publication, session, bytes, end, sent).await
946    }
947    async fn send_independent_part(
948        &self,
949        publication: &PublicationRequest,
950        session: &UploadSession,
951        offset: u64,
952        bytes: &[u8],
953        sent: &ByteProgress,
954    ) -> Result<crate::ConfirmedPart, StorageError> {
955        self.memory_send_part(publication, session, offset, bytes, sent).await
956    }
957    async fn finish_upload(
958        &self,
959        publication: &PublicationRequest,
960        session: &mut UploadSession,
961    ) -> Result<(), StorageError> {
962        self.memory_finish_upload(publication, session).await
963    }
964    async fn abort_upload(
965        &self,
966        publication: &PublicationRequest,
967        session: &UploadSession,
968    ) -> Result<(), StorageError> {
969        self.memory_abort_upload(publication, session).await
970    }
971}
972
973#[path = "conformance.rs"]
974mod conformance;
975pub use conformance::Conformance;
976
977#[cfg(test)]
978#[path = "test_utils_tests.rs"]
979mod tests;
980
981#[path = "memory_connector.rs"]
982mod connector;
983pub use connector::{conforming_detection, DETECTED_S3_SETTINGS};
984
985#[path = "memory_storage_builder.rs"]
986mod builder;
987pub use builder::MemoryStorageBuilder;