Skip to main content

coven_storage/
memory_upload.rs

1//! Atomic conditional publication in the deterministic provider.
2use super::*;
3use crate::session::{part_span, Confirmation, PlanStart, StartSent};
4
5/// A planned session's start as it goes out: past any hold, the publication
6/// gate is checked again, as S3 checks it as the request goes out, and a start
7/// it lets through has gone out (Appendix E.10).
8pub(super) struct MemoryStart<'a> {
9    publication: &'a PublicationRequest,
10    sent: &'a StartSent,
11}
12
13impl MemoryStart<'_> {
14    pub(super) fn go(&self) -> Result<(), StorageError> {
15        self.publication.check()?;
16        self.sent.going();
17        Ok(())
18    }
19}
20
21pub(super) struct Pending {
22    device: coven_foundation::id_source::DeviceId,
23    path: ObjectPath,
24    total: u64,
25    pub(super) bytes: Vec<u8>,
26    /// An independent session's parts, by index from zero: each kept once,
27    /// a part sent again taking its own place.
28    parts: BTreeMap<u64, Vec<u8>>,
29    part_size: usize,
30}
31impl Pending {
32    fn check(&self, session: &UploadSession) -> Result<(), StorageError> {
33        if self.path != session.path
34            || self.total != session.total
35            || self.part_size != session.part_size
36        {
37            return Err(StorageFailure::SessionMismatch.into());
38        }
39        let lost = match &session.state {
40            SessionState::MemoryParts { parts, .. } => {
41                parts.iter().any(|index| !self.parts.contains_key(index))
42            }
43            _ => {
44                (self.bytes.len() as u64) < session.confirmed
45                    || self.bytes.len() as u64 > self.total
46            }
47        };
48        if lost {
49            return Err(
50                StorageFailure::Protocol.with_source("memory provider lost confirmed progress")
51            );
52        }
53        Ok(())
54    }
55    /// The bytes publishing hands over: an independent session's parts in
56    /// order, which must be every one; another's bytes as they arrived.
57    fn assembled(self) -> Result<Vec<u8>, StorageError> {
58        if self.parts.is_empty() {
59            return Ok(self.bytes);
60        }
61        let count = self.total.div_ceil(self.part_size as u64);
62        if self.parts.len() as u64 != count {
63            return Err(StorageFailure::InvalidPart.into());
64        }
65        Ok(self.parts.into_values().flatten().collect())
66    }
67}
68fn confirm_published(
69    state: &MemoryState,
70    session: &mut UploadSession,
71    id: u64,
72) -> Result<(), StorageError> {
73    let object = state.objects.get(session.path()).ok_or(StorageFailure::SessionExpired)?;
74    if object.upload_id != Some(id) || object.bytes.len() as u64 != session.total {
75        return Err(StorageFailure::AlreadyExists.into());
76    }
77    session.confirmed = session.total;
78    session.state = SessionState::Memory { id, complete: true };
79    Ok(())
80}
81
82/// Whether every session at a planned one's name is its own: a name its
83/// device alone uses, a path in its own file or snapshot folders, as on S3
84/// (Appendix E.10). A shared slot or floor path proves nothing.
85fn owns_name(session: &UploadSession) -> bool {
86    session.path().device() == Some(session.device)
87}
88
89/// End every session at a planned one's name it owns: one its first part
90/// started, whose start's reply was lost or never recorded.
91fn end_planned(state: &mut MemoryState, session: &UploadSession) {
92    state.uploads.retain(|_, pending| pending.path != session.path);
93}
94
95fn check_free(state: &MemoryState, path: &ObjectPath) -> Result<(), StorageError> {
96    if state.objects.contains_key(path) && !state.faults.overwrite_create {
97        return Err(StorageFailure::AlreadyExists.into());
98    }
99    Ok(())
100}
101
102impl MemoryStorage {
103    /// A four-byte upload to `path` the provider holds unpublished: begun,
104    /// then started by its first and only part, as an S3 multipart upload
105    /// is (Appendix E.10).
106    pub async fn started_upload(&self, path: &ObjectPath) -> Result<UploadSession, StorageError> {
107        let mut session = self.begin_upload(path, 4).await?;
108        self.upload_part(&mut session, b"part").await?;
109        Ok(session)
110    }
111    /// Whether the provider holds the unfinished session `session` names; a
112    /// plan names none until its first part starts it.
113    pub async fn holds(&self, session: &UploadSession) -> bool {
114        match session.state {
115            SessionState::Memory { id, .. } | SessionState::MemoryParts { id, .. } => {
116                self.provider.state.lock().await.uploads.contains_key(&id)
117            }
118            _ => false,
119        }
120    }
121    /// Each session still unfinished, in the order it began: the device
122    /// whose connection began it, and its destination.
123    pub async fn unfinished_uploads(
124        &self,
125    ) -> Vec<(coven_foundation::id_source::DeviceId, ObjectPath)> {
126        let state = self.provider.state.lock().await;
127        state.uploads.values().map(|pending| (pending.device, pending.path.clone())).collect()
128    }
129}
130
131impl MemoryProvider {
132    /// The sessions `device`'s connections began in `store`.
133    pub(super) async fn memory_device_uploads(
134        &self,
135        store: coven_foundation::id_source::StoreId,
136        device: coven_foundation::id_source::DeviceId,
137    ) -> Result<Vec<LeftUpload>, StorageError> {
138        self.before(MemoryRequest::Other("device_uploads")).await?;
139        let state = self.state.lock().await;
140        Ok(state
141            .uploads
142            .iter()
143            .filter(|(_, pending)| pending.device == device && pending.path.store() == store)
144            .map(|(id, _)| LeftUpload(crate::left_upload::Left::Memory(*id)))
145            .collect())
146    }
147    /// The sessions at slots 1 to `through` of `store`, whoever began them:
148    /// the deterministic provider holds a claim's session at its slot, as
149    /// conditional completion on S3 does.
150    pub(super) async fn memory_settled_claim_uploads(
151        &self,
152        store: coven_foundation::id_source::StoreId,
153        through: u64,
154    ) -> Result<Vec<LeftUpload>, StorageError> {
155        self.before(MemoryRequest::Other("settled_claim_uploads")).await?;
156        let state = self.state.lock().await;
157        Ok(state
158            .uploads
159            .iter()
160            .filter(|(_, pending)| {
161                let path = &pending.path;
162                path.store() == store
163                    && path.slot_number().is_some_and(|slot| slot.get() <= through)
164            })
165            .map(|(id, _)| LeftUpload(crate::left_upload::Left::Memory(*id)))
166            .collect())
167    }
168    /// End one session another device left; one already ended succeeds.
169    pub(super) async fn memory_end_left_upload(
170        &self,
171        upload: &LeftUpload,
172    ) -> Result<(), StorageError> {
173        let crate::left_upload::Left::Memory(id) = upload.0 else {
174            return Err(StorageFailure::SessionMismatch.into());
175        };
176        self.before(MemoryRequest::Other("end_left_upload")).await?;
177        self.state.lock().await.uploads.remove(&id);
178        Ok(())
179    }
180    pub(super) async fn memory_begin_upload(
181        &self,
182        publication: &PublicationRequest,
183        path: &ObjectPath,
184        total: u64,
185        device: coven_foundation::id_source::DeviceId,
186    ) -> Result<UploadSession, StorageError> {
187        publication.check()?;
188        self.before(MemoryRequest::Other("begin_upload")).await?;
189        self.refuse_file_upload(path).await?;
190        check_free(&*self.state.lock().await, path)?;
191        // The caller records the plan; the first part starts the session.
192        Ok(UploadSession {
193            device,
194            location: self.config(),
195            path: path.clone(),
196            total,
197            confirmed: 0,
198            part_size: self.part_size,
199            state: SessionState::MemoryPlanned { started: PlanStart::Unstarted },
200        })
201    }
202    pub(super) async fn memory_resume_upload(
203        &self,
204        publication: &PublicationRequest,
205        session: &mut UploadSession,
206    ) -> Result<(), StorageError> {
207        if let SessionState::MemoryPlanned { started } = session.state {
208            // Nothing is at the name of a plan whose first part was never
209            // sent, and nothing tells a stray at a shared name from another
210            // device's session (Appendix E.10).
211            if started != PlanStart::MayHaveStarted {
212                return Ok(());
213            }
214            publication.check()?;
215            self.before(MemoryRequest::Other("resume_upload")).await?;
216            let mut state = self.state.lock().await;
217            if owns_name(session) {
218                end_planned(&mut state, session);
219            } else {
220                // A shared name aborts nothing: its destination decides. A
221                // plan finding it empty starts fresh beside the stray its lost
222                // start may have begun, which can never publish.
223                check_free(&state, session.path())?;
224            }
225            session.state = SessionState::MemoryPlanned { started: PlanStart::Unstarted };
226            return Ok(());
227        }
228        publication.check()?;
229        self.before(MemoryRequest::Other("resume_upload")).await?;
230        let id = self.session_id(session)?;
231        let state = self.state.lock().await;
232        match state.uploads.get(&id) {
233            Some(pending) => {
234                pending.check(session)?;
235                match &mut session.state {
236                    // Every part the provider holds, whichever arrived first.
237                    SessionState::MemoryParts { parts, .. } => {
238                        *parts = pending.parts.keys().copied().collect();
239                        session.confirmed = pending
240                            .parts
241                            .keys()
242                            .filter_map(|index| part_span(pending.total, pending.part_size, *index))
243                            .map(|span| span.end - span.start)
244                            .sum();
245                    }
246                    _ => session.confirmed = pending.bytes.len() as u64,
247                }
248            }
249            None => confirm_published(&state, session, id)?,
250        }
251        Ok(())
252    }
253    pub(super) async fn memory_upload_part(
254        &self,
255        publication: &PublicationRequest,
256        session: &mut UploadSession,
257        bytes: &[u8],
258        end: u64,
259        sent: &ByteProgress,
260    ) -> Result<(), StorageError> {
261        if let SessionState::MemoryPlanned { started } = &mut session.state {
262            // A restored marked plan resumes first, and one whose start this
263            // process sent may have started a session already.
264            if *started == PlanStart::MayHaveStarted {
265                return Err(StorageFailure::SessionMismatch.into());
266            }
267            // Until it settles, the start may go out at any moment.
268            *started = PlanStart::MayHaveStarted;
269            let start = StartSent::default();
270            if let Err(error) = self.initiate(publication, session, &start).await {
271                session.start_failed(&start);
272                return Err(error);
273            }
274        }
275        if matches!(session.state, SessionState::MemoryParts { .. }) {
276            let offset = end - bytes.len() as u64;
277            let part = self.memory_send_part(publication, session, offset, bytes, sent).await?;
278            return session.confirm(part);
279        }
280        publication.check()?;
281        // The whole part is taken as the call starts, as for a create.
282        sent.moved(bytes.len() as u64);
283        self.before(MemoryRequest::Other("upload_part")).await?;
284        let gate = self.state.lock().await.part_gate.clone();
285        if let Some(gate) = gate {
286            gate.acquire()
287                .await
288                .map_err(|closed| StorageFailure::Protocol.with_source(closed))?
289                .forget();
290        }
291        let id = self.session_id(session)?;
292        let mut state = self.state.lock().await;
293        let pending = state.uploads.get(&id).ok_or(StorageFailure::SessionExpired)?;
294        pending.check(session)?;
295        if pending.bytes.len() as u64 != session.confirmed {
296            return Err(StorageFailure::InvalidPart.into());
297        }
298        if std::mem::replace(&mut state.faults.drop_part, false) {
299            return Err(StorageFailure::Network.into());
300        }
301        state
302            .uploads
303            .get_mut(&id)
304            .ok_or(StorageFailure::SessionExpired)?
305            .bytes
306            .extend_from_slice(bytes);
307        if std::mem::replace(&mut state.faults.lose_part_reply, false) {
308            return Err(StorageFailure::Network.into());
309        }
310        state.sent_bytes += bytes.len() as u64;
311        state.largest_part = state.largest_part.max(bytes.len());
312        session.confirmed = end;
313        Ok(())
314    }
315    /// Send part `offset..` of an independent session, as S3 takes a
316    /// multipart upload's part: kept by its index, replacing one sent
317    /// before, and confirmed for the caller to add to its session.
318    pub(super) async fn memory_send_part(
319        &self,
320        publication: &PublicationRequest,
321        session: &UploadSession,
322        offset: u64,
323        bytes: &[u8],
324        sent: &ByteProgress,
325    ) -> Result<crate::ConfirmedPart, StorageError> {
326        let SessionState::MemoryParts { id, .. } = session.state else {
327            return Err(StorageFailure::SessionMismatch.into());
328        };
329        publication.check()?;
330        // The whole part is taken as the call starts, as for a create.
331        sent.moved(bytes.len() as u64);
332        self.before(MemoryRequest::Other("upload_part")).await?;
333        let gate = self.state.lock().await.part_gate.clone();
334        if let Some(gate) = gate {
335            gate.acquire()
336                .await
337                .map_err(|closed| StorageFailure::Protocol.with_source(closed))?
338                .forget();
339        }
340        let index = offset / session.part_size as u64;
341        let mut state = self.state.lock().await;
342        let pending = state.uploads.get(&id).ok_or(StorageFailure::SessionExpired)?;
343        pending.check(session)?;
344        if !offset.is_multiple_of(session.part_size as u64)
345            || part_span(session.total, session.part_size, index)
346                .is_none_or(|span| span.end - span.start != bytes.len() as u64)
347        {
348            return Err(StorageFailure::InvalidPart.into());
349        }
350        if std::mem::replace(&mut state.faults.drop_part, false) {
351            return Err(StorageFailure::Network.into());
352        }
353        state
354            .uploads
355            .get_mut(&id)
356            .ok_or(StorageFailure::SessionExpired)?
357            .parts
358            .insert(index, bytes.to_vec());
359        if std::mem::replace(&mut state.faults.lose_part_reply, false) {
360            return Err(StorageFailure::Network.into());
361        }
362        state.sent_bytes += bytes.len() as u64;
363        state.largest_part = state.largest_part.max(bytes.len());
364        Ok(crate::ConfirmedPart(Confirmation::Memory { index }))
365    }
366    /// Start a planned session's upload, as its first part does on S3,
367    /// telling `sent` once the start goes out.
368    async fn initiate(
369        &self,
370        publication: &PublicationRequest,
371        session: &mut UploadSession,
372        sent: &StartSent,
373    ) -> Result<(), StorageError> {
374        let start = MemoryStart { publication, sent };
375        self.before_going(MemoryRequest::Other("initiate_upload"), Some(start)).await?;
376        let mut state = self.state.lock().await;
377        let id = state.next_id()?;
378        state.uploads.insert(
379            id,
380            Pending {
381                device: session.device,
382                path: session.path.clone(),
383                total: session.total,
384                bytes: Vec::new(),
385                parts: BTreeMap::new(),
386                part_size: session.part_size,
387            },
388        );
389        if std::mem::replace(&mut state.faults.lose_initiation_reply, false) {
390            return Err(StorageFailure::Network.into());
391        }
392        session.state = if self.independent_parts {
393            SessionState::MemoryParts { id, parts: Vec::new(), complete: false }
394        } else {
395            SessionState::Memory { id, complete: false }
396        };
397        Ok(())
398    }
399    pub(super) async fn memory_finish_upload(
400        &self,
401        publication: &PublicationRequest,
402        session: &mut UploadSession,
403    ) -> Result<(), StorageError> {
404        publication.check()?;
405        self.before(MemoryRequest::Other("finish_upload")).await?;
406        if matches!(session.state, SessionState::MemoryPlanned { .. }) {
407            // Nothing is sent before the first part starts the session.
408            return Err(StorageFailure::InvalidPart.into());
409        }
410        let id = self.session_id(session)?;
411        let mut state = self.state.lock().await;
412        let Some(pending) = state.uploads.get(&id) else {
413            return confirm_published(&state, session, id);
414        };
415        pending.check(session)?;
416        let whole = match &session.state {
417            SessionState::MemoryParts { .. } => {
418                pending.parts.len() as u64 == session.total.div_ceil(session.part_size as u64)
419            }
420            _ => pending.bytes.len() as u64 == session.total,
421        };
422        if !whole || session.confirmed != session.total {
423            return Err(StorageFailure::InvalidPart.into());
424        }
425        check_free(&state, session.path())?;
426        let revision = state.next_id()?;
427        let pending = state.uploads.remove(&id).ok_or(StorageFailure::SessionExpired)?;
428        let path = pending.path.clone();
429        state.objects.insert(
430            path,
431            Object {
432                revision,
433                bytes: pending.assembled()?.into(),
434                stored_at: self.storage_time()?,
435                upload_id: Some(id),
436            },
437        );
438        if std::mem::replace(&mut state.faults.lose_completion_reply, false) {
439            return Err(StorageFailure::Network.into());
440        }
441        session.state = SessionState::Memory { id, complete: true };
442        Ok(())
443    }
444    pub(super) async fn memory_abort_upload(
445        &self,
446        publication: &PublicationRequest,
447        session: &UploadSession,
448    ) -> Result<(), StorageError> {
449        if let SessionState::MemoryPlanned { started } = session.state {
450            // A plan whose first part was never sent has nothing to end
451            // (Appendix E.10).
452            if started != PlanStart::MayHaveStarted || !owns_name(session) {
453                return Ok(());
454            }
455        }
456        publication.check()?;
457        self.before(MemoryRequest::Other("abort_upload")).await?;
458        let id = match session.state {
459            SessionState::MemoryPlanned { .. } => None,
460            _ => Some(self.session_id(session)?),
461        };
462        let mut state = self.state.lock().await;
463        if state.faults.abort_failures > 0 {
464            state.faults.abort_failures -= 1;
465            return Err(StorageFailure::Network.into());
466        }
467        let Some(id) = id else {
468            end_planned(&mut state, session);
469            return Ok(());
470        };
471        if let Some(pending) = state.uploads.get(&id) {
472            pending.check(session)?;
473        }
474        state.uploads.remove(&id);
475        Ok(())
476    }
477}
478
479#[cfg(test)]
480#[path = "memory_upload_tests.rs"]
481mod tests;