Skip to main content

folderbase_core/
transfer_receiver.rs

1//! Durable, capability-rooted receipt and materialization of immutable objects.
2//!
3//! This module owns checkpoint persistence, bounded chunk ingestion, resume
4//! validation, pagination, canonical whole-object verification, and atomic
5//! no-clobber installation beneath caller-opened destination capabilities.
6
7use std::{
8    ffi::OsString,
9    io::{Read, Write},
10    path::{Component, Path, PathBuf},
11    sync::{
12        Mutex,
13        atomic::{AtomicBool, Ordering},
14    },
15};
16
17use cap_fs_ext::{DirExt, FollowSymlinks, OpenOptionsFollowExt};
18use cap_std::fs::{Dir, DirBuilder, OpenOptions};
19#[cfg(unix)]
20use cap_std::fs::{DirBuilderExt, MetadataExt, OpenOptionsExt};
21use serde::Deserialize;
22use sha2::{Digest, Sha256};
23use uuid::{Uuid, Version};
24
25use crate::{
26    physical_identity::RetainedPhysicalIdentity,
27    transfer_manifest::{
28        ChunkDescriptor, ChunkManifest, MAX_ENCODED_MANIFEST_BYTES, ManifestError,
29        ManifestViolation, ObjectVerificationError, TRANSFER_IO_BUFFER_BYTES, VerifiedObject,
30        is_sha256,
31    },
32};
33
34const MANIFEST_FILE: &str = "manifest.json";
35const CHUNKS_DIRECTORY: &str = "chunks";
36const RECEIVER_LOCK_FILE: &str = "receiver.lock";
37const MATERIALIZATION_OBJECT_FILE: &str = "object";
38pub const MAX_MISSING_CHUNKS_PER_PAGE: usize = 4096;
39
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub enum ChunkAcceptance {
42    Accepted,
43    AlreadyPresent,
44}
45
46#[derive(Debug, Clone, PartialEq, Eq)]
47pub struct MissingChunkPage {
48    pub chunk_indices: Vec<u32>,
49    pub next_cursor: Option<u32>,
50}
51
52/// Integrity proof for one exact file installed by this process.
53#[derive(Debug, Clone, PartialEq, Eq)]
54pub struct VerifiedMaterialization {
55    pub object: VerifiedObject,
56    pub relative_destination: PathBuf,
57}
58
59#[derive(Debug, thiserror::Error)]
60pub enum TransferReceiverError {
61    #[error("receiver checkpoint path must be a nonempty relative path")]
62    UnsafeCheckpointPath,
63
64    #[error("receiver checkpoint already exists")]
65    CheckpointAlreadyExists,
66
67    #[error("receiver checkpoint does not exist")]
68    CheckpointNotFound,
69
70    #[error("receiver checkpoint I/O failed: {0}")]
71    Io(#[source] std::io::Error),
72
73    #[error("chunk manifest violates the protocol: {0}")]
74    InvalidManifest(#[from] ManifestViolation),
75
76    #[error("encoded chunk manifest exceeds {maximum_bytes} bytes")]
77    EncodedManifestTooLarge { maximum_bytes: u64 },
78
79    #[error("receiver checkpoint manifest is not valid canonical manifest JSON")]
80    InvalidCheckpointManifest,
81
82    #[error("legacy pre-v1 transfer checkpoints are unsupported")]
83    UnsupportedLegacyCheckpoint,
84
85    #[error("expected manifest digest is not lowercase hexadecimal SHA-256")]
86    InvalidExpectedManifestDigest,
87
88    #[error("manifest digest {actual} differs from expected digest {expected}")]
89    ManifestDigestMismatch { expected: String, actual: String },
90
91    #[error("receiver checkpoint contains an unrecognized entry")]
92    UnrecognizedCheckpointEntry,
93
94    #[error("receiver checkpoint state is accessible outside its owning user")]
95    InsecureCheckpointPermissions,
96
97    #[error("receiver checkpoint state changed during the operation")]
98    CheckpointStateChanged,
99
100    #[error("chunk {0} is not present in the bound manifest")]
101    UnknownChunk(u32),
102
103    #[error("chunk {0} length differs from the manifest")]
104    ChunkLengthMismatch(u32),
105
106    #[error("chunk {0} digest differs from the manifest")]
107    ChunkDigestMismatch(u32),
108
109    #[error("missing-chunk page limit must be between 1 and {maximum}")]
110    InvalidPageLimit { maximum: usize },
111
112    #[error("materialization destination must be an exact nonempty relative path")]
113    UnsafeDestinationPath,
114
115    #[error("materialization destination already exists")]
116    DestinationAlreadyExists,
117
118    #[error("transfer is incomplete beginning with chunk {first_missing_chunk}")]
119    IncompleteTransfer { first_missing_chunk: u32 },
120
121    #[error("materialization destination state changed during the operation")]
122    DestinationStateChanged,
123
124    #[error("received object verification failed: {0}")]
125    ObjectVerification(#[from] ObjectVerificationError),
126}
127
128/// Opaque receiver state bound to one canonical manifest and one opened
129/// capability-rooted checkpoint directory.
130#[derive(Debug)]
131pub struct PersistentTransfer {
132    _directory: Dir,
133    chunks: Dir,
134    receiver_lock: std::fs::File,
135    receiver_lock_identity: RetainedPhysicalIdentity,
136    checkpoint_lease_poisoned: AtomicBool,
137    operation_mutex: Mutex<()>,
138    manifest: ChunkManifest,
139    manifest_digest: String,
140}
141
142impl PersistentTransfer {
143    pub fn create(
144        root: &Dir,
145        relative_checkpoint: impl AsRef<Path>,
146        manifest: ChunkManifest,
147    ) -> Result<Self, TransferReceiverError> {
148        manifest.validate()?;
149        let manifest_digest = manifest.canonical_digest()?;
150        let encoded = serde_json::to_vec_pretty(&manifest)
151            .map_err(|_| TransferReceiverError::InvalidCheckpointManifest)?;
152        if encoded.len() as u64 > MAX_ENCODED_MANIFEST_BYTES {
153            return Err(TransferReceiverError::EncodedManifestTooLarge {
154                maximum_bytes: MAX_ENCODED_MANIFEST_BYTES,
155            });
156        }
157
158        let relative_checkpoint = relative_checkpoint.as_ref();
159        let (parent, name) = open_parent_nofollow(root, relative_checkpoint)?;
160        create_private_dir(&parent, &name).map_err(|source| {
161            if source.kind() == std::io::ErrorKind::AlreadyExists {
162                TransferReceiverError::CheckpointAlreadyExists
163            } else {
164                TransferReceiverError::Io(source)
165            }
166        })?;
167        let directory = parent
168            .open_dir_nofollow(&name)
169            .map_err(TransferReceiverError::Io)?;
170
171        (|| {
172            create_private_dir(&directory, CHUNKS_DIRECTORY).map_err(TransferReceiverError::Io)?;
173            write_private_new(&directory, MANIFEST_FILE, &encoded)?;
174            write_private_new(&directory, RECEIVER_LOCK_FILE, &[])?;
175            sync_directory(&directory)?;
176            sync_directory(&parent)?;
177            Self::from_open_directory(directory, manifest, manifest_digest)
178        })()
179    }
180
181    pub fn open(
182        root: &Dir,
183        relative_checkpoint: impl AsRef<Path>,
184        expected_manifest_digest: &str,
185    ) -> Result<Self, TransferReceiverError> {
186        validate_expected_digest(expected_manifest_digest)?;
187        let relative_checkpoint = relative_checkpoint.as_ref();
188        let (parent, name) = open_parent_nofollow(root, relative_checkpoint)?;
189        let directory = parent.open_dir_nofollow(&name).map_err(|source| {
190            if source.kind() == std::io::ErrorKind::NotFound {
191                TransferReceiverError::CheckpointNotFound
192            } else {
193                TransferReceiverError::Io(source)
194            }
195        })?;
196        validate_private_directory(&directory)?;
197        validate_private_regular_file(&directory, MANIFEST_FILE)?;
198        let encoded = read_file_bounded(&directory, MANIFEST_FILE, MAX_ENCODED_MANIFEST_BYTES)?;
199        let manifest = match ChunkManifest::decode_slice_bounded(&encoded) {
200            Ok(manifest) => manifest,
201            Err(ManifestError::InvalidJson(_)) if is_legacy_manifest(&encoded) => {
202                return Err(TransferReceiverError::UnsupportedLegacyCheckpoint);
203            }
204            Err(ManifestError::InvalidJson(_)) => {
205                return Err(TransferReceiverError::InvalidCheckpointManifest);
206            }
207            Err(ManifestError::InvalidManifest(violation)) => return Err(violation.into()),
208            Err(ManifestError::EncodedManifestTooLarge { maximum_bytes }) => {
209                return Err(TransferReceiverError::EncodedManifestTooLarge { maximum_bytes });
210            }
211        };
212        validate_checkpoint_top_level(&directory)?;
213        let actual = manifest.canonical_digest()?;
214        if actual != expected_manifest_digest {
215            return Err(TransferReceiverError::ManifestDigestMismatch {
216                expected: expected_manifest_digest.to_owned(),
217                actual,
218            });
219        }
220        Self::from_open_directory(directory, manifest, actual)
221    }
222
223    pub fn manifest(&self) -> &ChunkManifest {
224        &self.manifest
225    }
226
227    pub fn manifest_digest(&self) -> &str {
228        &self.manifest_digest
229    }
230
231    pub fn accept_chunk_from(
232        &self,
233        index: u32,
234        mut reader: impl Read,
235    ) -> Result<ChunkAcceptance, TransferReceiverError> {
236        let descriptor = self
237            .manifest
238            .chunks
239            .get(index as usize)
240            .filter(|descriptor| descriptor.index == index)
241            .ok_or(TransferReceiverError::UnknownChunk(index))?;
242        let _in_process = self
243            .operation_mutex
244            .lock()
245            .unwrap_or_else(std::sync::PoisonError::into_inner);
246        let checkpoint_lease =
247            CheckpointLease::acquire(&self.receiver_lock, &self.checkpoint_lease_poisoned)?;
248        let result = (|| {
249            let current_lock = open_named_file_identity(&self._directory, RECEIVER_LOCK_FILE)
250                .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
251            if current_lock != self.receiver_lock_identity {
252                return Err(TransferReceiverError::CheckpointStateChanged);
253            }
254            reclaim_stale_staging(&self.chunks)?;
255
256            let destination = chunk_file_name(index);
257            let staging = format!(".chunk-{}.part", Uuid::now_v7());
258            let mut options = OpenOptions::new();
259            options
260                .write(true)
261                .create_new(true)
262                .follow(FollowSymlinks::No);
263            #[cfg(unix)]
264            options.mode(0o600);
265            let mut staged = self
266                .chunks
267                .open_with(&staging, &options)
268                .map_err(TransferReceiverError::Io)?;
269            let ingestion = copy_exact_chunk(descriptor, &mut reader, &mut staged)
270                .and_then(|()| staged.sync_all().map_err(TransferReceiverError::Io));
271            let staging_identity = RetainedPhysicalIdentity::from_file(staged.into_std())
272                .map_err(TransferReceiverError::Io)?;
273            let result = ingestion.and_then(|()| {
274                let current_staging = open_named_file_identity(&self.chunks, &staging)
275                    .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
276                if current_staging != staging_identity {
277                    return Err(TransferReceiverError::CheckpointStateChanged);
278                }
279
280                match self.chunks.hard_link(&staging, &self.chunks, &destination) {
281                    Ok(()) => {
282                        sync_directory(&self.chunks)?;
283                        let destination_identity =
284                            open_named_file_identity(&self.chunks, &destination)
285                                .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
286                        if destination_identity != staging_identity {
287                            return Err(TransferReceiverError::CheckpointStateChanged);
288                        }
289                        Ok(ChunkAcceptance::Accepted)
290                    }
291                    Err(source) if source.kind() == std::io::ErrorKind::AlreadyExists => {
292                        let mut existing = open_regular_file_nofollow(&self.chunks, &destination)
293                            .map_err(TransferReceiverError::Io)?;
294                        validate_chunk_reader(descriptor, &mut existing)?;
295                        let existing_identity =
296                            RetainedPhysicalIdentity::from_file(existing.into_std())
297                                .map_err(TransferReceiverError::Io)?;
298                        let current_destination =
299                            open_named_file_identity(&self.chunks, &destination)
300                                .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
301                        if current_destination != existing_identity {
302                            return Err(TransferReceiverError::CheckpointStateChanged);
303                        }
304                        sync_directory(&self.chunks)?;
305                        Ok(ChunkAcceptance::AlreadyPresent)
306                    }
307                    Err(source) => Err(TransferReceiverError::Io(source)),
308                }
309            });
310            let cleanup = cleanup_owned_staging(&self.chunks, &staging, &staging_identity);
311            match cleanup {
312                Err(error) => Err(error),
313                Ok(()) => result,
314            }
315        })();
316        checkpoint_lease.complete(result)
317    }
318
319    pub fn missing_chunks(
320        &self,
321        cursor: Option<u32>,
322        limit: usize,
323    ) -> Result<MissingChunkPage, TransferReceiverError> {
324        if limit == 0 || limit > MAX_MISSING_CHUNKS_PER_PAGE {
325            return Err(TransferReceiverError::InvalidPageLimit {
326                maximum: MAX_MISSING_CHUNKS_PER_PAGE,
327            });
328        }
329        let start = cursor.unwrap_or(0);
330        let start = usize::try_from(start).unwrap_or(usize::MAX);
331        let end = start.saturating_add(limit).min(self.manifest.chunks.len());
332        let mut missing = Vec::with_capacity(end.saturating_sub(start));
333        for descriptor in self.manifest.chunks.iter().take(end).skip(start) {
334            let file_name = chunk_file_name(descriptor.index);
335            match open_regular_file_nofollow(&self.chunks, &file_name) {
336                Ok(mut file) => validate_chunk_reader(descriptor, &mut file)?,
337                Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
338                    missing.push(descriptor.index);
339                }
340                Err(source) => return Err(TransferReceiverError::Io(source)),
341            }
342        }
343        Ok(MissingChunkPage {
344            chunk_indices: missing,
345            next_cursor: (end < self.manifest.chunks.len()).then_some(end as u32),
346        })
347    }
348
349    /// Verify and atomically install the complete received object.
350    ///
351    /// The destination is resolved beneath `destination_root` without following
352    /// parent symlinks and must not exist. Object bytes are streamed with fixed
353    /// memory from the accepted chunks through the canonical whole-object
354    /// verifier into private operation-owned staging beside the destination.
355    pub fn materialize_to(
356        &self,
357        destination_root: &Dir,
358        relative_destination: impl AsRef<Path>,
359    ) -> Result<VerifiedMaterialization, TransferReceiverError> {
360        let relative_destination = relative_destination.as_ref();
361        let (destination_parent, destination_name) =
362            open_destination_parent_nofollow(destination_root, relative_destination)?;
363        let relative_destination = relative_destination.to_path_buf();
364        let _in_process = self
365            .operation_mutex
366            .lock()
367            .unwrap_or_else(std::sync::PoisonError::into_inner);
368        let checkpoint_lease =
369            CheckpointLease::acquire(&self.receiver_lock, &self.checkpoint_lease_poisoned)?;
370        let result = (|| {
371            let current_lock = open_named_file_identity(&self._directory, RECEIVER_LOCK_FILE)
372                .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
373            if current_lock != self.receiver_lock_identity {
374                return Err(TransferReceiverError::CheckpointStateChanged);
375            }
376            if let Some(first_missing_chunk) = self.first_missing_chunk()? {
377                return Err(TransferReceiverError::IncompleteTransfer {
378                    first_missing_chunk,
379                });
380            }
381            ensure_destination_absent(&destination_parent, &destination_name)?;
382
383            let mut staging = MaterializationStaging::create(&destination_parent)?;
384            let mut staged = staging.create_object()?;
385
386            let operation = (|| {
387                let reader = AcceptedChunkReader::new(&self.chunks, &self.manifest);
388                let object = self.manifest.verify_object_and_copy(reader, &mut staged)?;
389                staged.sync_all().map_err(TransferReceiverError::Io)?;
390                let current_lock = open_named_file_identity(&self._directory, RECEIVER_LOCK_FILE)
391                    .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
392                if current_lock != self.receiver_lock_identity {
393                    return Err(TransferReceiverError::CheckpointStateChanged);
394                }
395                staging.install(&destination_name)?;
396                Ok(VerifiedMaterialization {
397                    object,
398                    relative_destination,
399                })
400            })();
401
402            drop(staged);
403            let cleanup = staging.cleanup();
404            match cleanup {
405                Err(error) => Err(error),
406                Ok(()) => operation,
407            }
408        })();
409        checkpoint_lease.complete(result)
410    }
411
412    fn first_missing_chunk(&self) -> Result<Option<u32>, TransferReceiverError> {
413        for descriptor in &self.manifest.chunks {
414            let name = chunk_file_name(descriptor.index);
415            match open_regular_file_nofollow(&self.chunks, &name) {
416                Ok(_) => validate_private_regular_file(&self.chunks, &name)?,
417                Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
418                    return Ok(Some(descriptor.index));
419                }
420                Err(source) => return Err(TransferReceiverError::Io(source)),
421            }
422        }
423        Ok(None)
424    }
425
426    fn from_open_directory(
427        directory: Dir,
428        manifest: ChunkManifest,
429        manifest_digest: String,
430    ) -> Result<Self, TransferReceiverError> {
431        let chunks = directory
432            .open_dir_nofollow(CHUNKS_DIRECTORY)
433            .map_err(TransferReceiverError::Io)?;
434        let receiver_lock = open_lock_file_nofollow(&directory)?;
435        let receiver_lock_identity = RetainedPhysicalIdentity::from_file(
436            receiver_lock
437                .try_clone()
438                .map_err(TransferReceiverError::Io)?,
439        )
440        .map_err(TransferReceiverError::Io)?;
441        validate_chunk_entries_for_manifest(&chunks, &manifest)?;
442        let transfer = Self {
443            _directory: directory,
444            chunks,
445            receiver_lock,
446            receiver_lock_identity,
447            checkpoint_lease_poisoned: AtomicBool::new(false),
448            operation_mutex: Mutex::new(()),
449            manifest,
450            manifest_digest,
451        };
452        transfer.validate_installed_chunks()?;
453        Ok(transfer)
454    }
455
456    fn validate_installed_chunks(&self) -> Result<(), TransferReceiverError> {
457        for descriptor in &self.manifest.chunks {
458            match open_regular_file_nofollow(&self.chunks, chunk_file_name(descriptor.index)) {
459                Ok(mut file) => validate_chunk_reader(descriptor, &mut file)?,
460                Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
461                Err(source) => return Err(TransferReceiverError::Io(source)),
462            }
463        }
464        Ok(())
465    }
466}
467
468fn open_destination_parent_nofollow(
469    root: &Dir,
470    relative: &Path,
471) -> Result<(Dir, OsString), TransferReceiverError> {
472    if relative.as_os_str().is_empty() || relative.is_absolute() {
473        return Err(TransferReceiverError::UnsafeDestinationPath);
474    }
475    let mut names = Vec::new();
476    let mut exact = PathBuf::new();
477    for component in relative.components() {
478        let Component::Normal(name) = component else {
479            return Err(TransferReceiverError::UnsafeDestinationPath);
480        };
481        exact.push(name);
482        names.push(name.to_os_string());
483    }
484    if names.is_empty() || !destination_spelling_is_exact(relative, &exact) {
485        return Err(TransferReceiverError::UnsafeDestinationPath);
486    }
487    let destination_name = names
488        .pop()
489        .expect("a validated destination contains a leaf");
490    let mut current = root.try_clone().map_err(TransferReceiverError::Io)?;
491    for name in names {
492        current = current
493            .open_dir_nofollow(&name)
494            .map_err(TransferReceiverError::Io)?;
495    }
496    Ok((current, destination_name))
497}
498
499#[cfg(not(windows))]
500fn destination_spelling_is_exact(relative: &Path, rebuilt: &Path) -> bool {
501    rebuilt.as_os_str() == relative.as_os_str()
502}
503
504#[cfg(windows)]
505fn destination_spelling_is_exact(relative: &Path, _rebuilt: &Path) -> bool {
506    use std::os::windows::ffi::OsStrExt;
507
508    windows_destination_spelling_is_exact(&relative.as_os_str().encode_wide().collect::<Vec<_>>())
509}
510
511#[cfg(any(windows, test))]
512fn windows_destination_spelling_is_exact(spelling: &[u16]) -> bool {
513    fn is_separator(unit: u16) -> bool {
514        unit == u16::from(b'/') || unit == u16::from(b'\\')
515    }
516
517    fn is_exact_segment(segment: &[u16]) -> bool {
518        !segment.is_empty()
519            && segment != [u16::from(b'.')]
520            && segment != [u16::from(b'.'), u16::from(b'.')]
521    }
522
523    let mut segment_start = 0;
524    for (index, unit) in spelling.iter().copied().enumerate() {
525        if is_separator(unit) {
526            if !is_exact_segment(&spelling[segment_start..index]) {
527                return false;
528            }
529            segment_start = index + 1;
530        }
531    }
532    is_exact_segment(&spelling[segment_start..])
533}
534
535fn ensure_destination_absent(
536    parent: &Dir,
537    name: impl AsRef<Path>,
538) -> Result<(), TransferReceiverError> {
539    match parent.symlink_metadata(name) {
540        Ok(_) => Err(TransferReceiverError::DestinationAlreadyExists),
541        Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(()),
542        Err(source) => Err(TransferReceiverError::Io(source)),
543    }
544}
545
546fn open_parent_nofollow(
547    root: &Dir,
548    relative: &Path,
549) -> Result<(Dir, OsString), TransferReceiverError> {
550    let mut components = relative.components();
551    let Some(Component::Normal(name)) = components.next() else {
552        return Err(TransferReceiverError::UnsafeCheckpointPath);
553    };
554    if components.next().is_some() || relative.as_os_str() != name {
555        return Err(TransferReceiverError::UnsafeCheckpointPath);
556    }
557    Ok((
558        root.try_clone().map_err(TransferReceiverError::Io)?,
559        name.to_os_string(),
560    ))
561}
562
563struct AcceptedChunkReader<'a> {
564    chunks: &'a Dir,
565    manifest: &'a ChunkManifest,
566    next_index: usize,
567    current: Option<AcceptedChunkFile>,
568}
569
570struct MaterializationStaging<'a> {
571    parent: &'a Dir,
572    name: String,
573    directory: Option<Dir>,
574    directory_identity: Option<RetainedPhysicalIdentity>,
575    object_identity: Option<RetainedPhysicalIdentity>,
576    object_removed: bool,
577    finished: bool,
578}
579
580impl<'a> MaterializationStaging<'a> {
581    fn create(parent: &'a Dir) -> Result<Self, TransferReceiverError> {
582        let name = format!(".folderbase-materialize-{}.part", Uuid::now_v7());
583        create_private_dir(parent, &name).map_err(TransferReceiverError::Io)?;
584        let directory = match parent.open_dir_nofollow(&name) {
585            Ok(directory) => directory,
586            Err(source) => {
587                if parent.remove_dir(&name).is_ok() {
588                    let _ = sync_directory(parent);
589                }
590                return Err(TransferReceiverError::Io(source));
591            }
592        };
593        let mut staging = Self {
594            parent,
595            name,
596            directory: Some(directory),
597            directory_identity: None,
598            object_identity: None,
599            object_removed: true,
600            finished: false,
601        };
602        validate_private_directory(staging.directory()?)?;
603        staging.directory_identity = Some(
604            RetainedPhysicalIdentity::from_file(
605                staging
606                    .directory()?
607                    .try_clone()
608                    .map_err(TransferReceiverError::Io)?
609                    .into_std_file(),
610            )
611            .map_err(TransferReceiverError::Io)?,
612        );
613        staging.validate_directory_binding()?;
614        Ok(staging)
615    }
616
617    fn create_object(&mut self) -> Result<cap_std::fs::File, TransferReceiverError> {
618        let mut options = OpenOptions::new();
619        options
620            .write(true)
621            .create_new(true)
622            .follow(FollowSymlinks::No);
623        #[cfg(unix)]
624        options.mode(0o600);
625        let object = self
626            .directory()?
627            .open_with(MATERIALIZATION_OBJECT_FILE, &options)
628            .map_err(TransferReceiverError::Io)?;
629        self.object_removed = false;
630        let identity = object
631            .try_clone()
632            .map_err(TransferReceiverError::Io)
633            .and_then(|file| {
634                RetainedPhysicalIdentity::from_file(file.into_std())
635                    .map_err(TransferReceiverError::Io)
636            });
637        match identity {
638            Ok(identity) => {
639                self.object_identity = Some(identity);
640                Ok(object)
641            }
642            Err(error) => {
643                drop(object);
644                self.directory()?
645                    .remove_file(MATERIALIZATION_OBJECT_FILE)
646                    .map_err(TransferReceiverError::Io)?;
647                self.object_removed = true;
648                sync_directory(self.directory()?)?;
649                Err(error)
650            }
651        }
652    }
653
654    fn install(&self, destination_name: impl AsRef<Path>) -> Result<(), TransferReceiverError> {
655        self.validate_directory_binding()?;
656        let expected_object = self
657            .object_identity
658            .as_ref()
659            .ok_or(TransferReceiverError::DestinationStateChanged)?;
660        let directory = self.directory()?;
661        validate_private_regular_file(directory, MATERIALIZATION_OBJECT_FILE)?;
662        let current_object = open_named_file_identity(directory, MATERIALIZATION_OBJECT_FILE)
663            .map_err(|_| TransferReceiverError::DestinationStateChanged)?;
664        if &current_object != expected_object {
665            return Err(TransferReceiverError::DestinationStateChanged);
666        }
667        let destination_name = destination_name.as_ref();
668        match directory.hard_link(MATERIALIZATION_OBJECT_FILE, self.parent, destination_name) {
669            Ok(()) => {}
670            Err(source) if source.kind() == std::io::ErrorKind::AlreadyExists => {
671                return Err(TransferReceiverError::DestinationAlreadyExists);
672            }
673            Err(source) => return Err(TransferReceiverError::Io(source)),
674        }
675        let destination_identity = open_named_file_identity(self.parent, destination_name)
676            .map_err(|_| TransferReceiverError::DestinationStateChanged)?;
677        if &destination_identity != expected_object {
678            return Err(TransferReceiverError::DestinationStateChanged);
679        }
680        sync_directory(self.parent)
681    }
682
683    fn cleanup(mut self) -> Result<(), TransferReceiverError> {
684        let result = self.cleanup_inner();
685        if self.directory.is_none() {
686            self.finished = true;
687        }
688        result
689    }
690
691    fn cleanup_inner(&mut self) -> Result<(), TransferReceiverError> {
692        let directory_binding = self.validate_directory_binding();
693        if !self.object_removed {
694            self.remove_object_with(
695                |directory| {
696                    directory
697                        .remove_file(MATERIALIZATION_OBJECT_FILE)
698                        .map_err(TransferReceiverError::Io)
699                },
700                sync_directory,
701            )?;
702        }
703
704        self.remove_directory_with(|directory| {
705            directory
706                .remove_open_dir()
707                .map_err(TransferReceiverError::Io)
708        })?;
709        sync_directory(self.parent)?;
710        directory_binding
711    }
712
713    fn remove_object_with(
714        &mut self,
715        unlink: impl FnOnce(&Dir) -> Result<(), TransferReceiverError>,
716        sync: impl FnOnce(&Dir) -> Result<(), TransferReceiverError>,
717    ) -> Result<(), TransferReceiverError> {
718        {
719            let expected_object = self
720                .object_identity
721                .as_ref()
722                .ok_or(TransferReceiverError::DestinationStateChanged)?;
723            let directory = self.directory()?;
724            let current_object = open_named_file_identity(directory, MATERIALIZATION_OBJECT_FILE)
725                .map_err(|_| TransferReceiverError::DestinationStateChanged)?;
726            if &current_object != expected_object {
727                return Err(TransferReceiverError::DestinationStateChanged);
728            }
729        }
730        // The retained identity owns an OS handle. Windows denies deletion
731        // while either comparison handle remains open, so relinquish only
732        // after the live name has matched the retained identity.
733        drop(
734            self.object_identity
735                .take()
736                .ok_or(TransferReceiverError::DestinationStateChanged)?,
737        );
738        unlink(self.directory()?)?;
739        self.object_removed = true;
740        sync(self.directory()?)
741    }
742
743    fn remove_directory_with(
744        &mut self,
745        remove: impl FnOnce(Dir) -> Result<(), TransferReceiverError>,
746    ) -> Result<(), TransferReceiverError> {
747        // `remove_open_dir` consumes its Dir handle, but the independent
748        // identity handle must also be closed first on Windows.
749        drop(
750            self.directory_identity
751                .take()
752                .ok_or(TransferReceiverError::DestinationStateChanged)?,
753        );
754        let directory = self
755            .directory
756            .take()
757            .ok_or(TransferReceiverError::DestinationStateChanged)?;
758        remove(directory)
759    }
760
761    fn validate_directory_binding(&self) -> Result<(), TransferReceiverError> {
762        let expected = self
763            .directory_identity
764            .as_ref()
765            .ok_or(TransferReceiverError::DestinationStateChanged)?;
766        let current = open_named_directory_identity(self.parent, &self.name)
767            .map_err(|_| TransferReceiverError::DestinationStateChanged)?;
768        if &current != expected {
769            return Err(TransferReceiverError::DestinationStateChanged);
770        }
771        Ok(())
772    }
773
774    fn directory(&self) -> Result<&Dir, TransferReceiverError> {
775        self.directory
776            .as_ref()
777            .ok_or(TransferReceiverError::DestinationStateChanged)
778    }
779}
780
781impl Drop for MaterializationStaging<'_> {
782    fn drop(&mut self) {
783        if !self.finished {
784            let _ = self.cleanup_inner();
785        }
786    }
787}
788
789struct AcceptedChunkFile {
790    file: cap_std::fs::File,
791    remaining: u64,
792    index: u32,
793    name: String,
794    identity: RetainedPhysicalIdentity,
795}
796
797impl<'a> AcceptedChunkReader<'a> {
798    fn new(chunks: &'a Dir, manifest: &'a ChunkManifest) -> Self {
799        Self {
800            chunks,
801            manifest,
802            next_index: 0,
803            current: None,
804        }
805    }
806}
807
808impl Read for AcceptedChunkReader<'_> {
809    fn read(&mut self, output: &mut [u8]) -> std::io::Result<usize> {
810        if output.is_empty() {
811            return Ok(0);
812        }
813        loop {
814            if let Some(current) = self.current.as_mut() {
815                if current.remaining > 0 {
816                    let wanted = usize::try_from(current.remaining.min(output.len() as u64))
817                        .expect("fixed caller buffer fits usize");
818                    let read = current.file.read(&mut output[..wanted])?;
819                    if read == 0 {
820                        return Err(std::io::Error::new(
821                            std::io::ErrorKind::UnexpectedEof,
822                            format!("accepted chunk {} is truncated", current.index),
823                        ));
824                    }
825                    current.remaining -= read as u64;
826                    return Ok(read);
827                }
828                let mut trailing = [0_u8; 1];
829                if current.file.read(&mut trailing)? != 0 {
830                    return Err(std::io::Error::new(
831                        std::io::ErrorKind::InvalidData,
832                        format!("accepted chunk {} contains trailing bytes", current.index),
833                    ));
834                }
835                let current_identity = open_named_file_identity(self.chunks, &current.name)
836                    .map_err(|error| {
837                        std::io::Error::other(format!(
838                            "accepted chunk {} pathname changed: {error}",
839                            current.index
840                        ))
841                    })?;
842                if current_identity != current.identity {
843                    return Err(std::io::Error::other(format!(
844                        "accepted chunk {} pathname identity changed",
845                        current.index
846                    )));
847                }
848                self.current = None;
849            }
850
851            let Some(descriptor) = self.manifest.chunks.get(self.next_index) else {
852                return Ok(0);
853            };
854            let name = chunk_file_name(descriptor.index);
855            let file = open_regular_file_nofollow(self.chunks, &name)?;
856            validate_private_regular_file(self.chunks, &name)
857                .map_err(|error| std::io::Error::other(error.to_string()))?;
858            let identity = RetainedPhysicalIdentity::from_file(file.try_clone()?.into_std())
859                .map_err(std::io::Error::other)?;
860            self.current = Some(AcceptedChunkFile {
861                file,
862                remaining: descriptor.bytes,
863                index: descriptor.index,
864                name,
865                identity,
866            });
867            self.next_index += 1;
868        }
869    }
870}
871
872fn create_private_dir(parent: &Dir, name: impl AsRef<Path>) -> std::io::Result<()> {
873    let builder = DirBuilder::new();
874    #[cfg(unix)]
875    let builder = {
876        let mut builder = builder;
877        builder.mode(0o700);
878        builder
879    };
880    parent.create_dir_with(name, &builder)
881}
882
883fn write_private_new(
884    directory: &Dir,
885    name: impl AsRef<Path>,
886    bytes: &[u8],
887) -> Result<(), TransferReceiverError> {
888    let mut options = OpenOptions::new();
889    options
890        .write(true)
891        .create_new(true)
892        .follow(FollowSymlinks::No);
893    #[cfg(unix)]
894    options.mode(0o600);
895    let mut file = directory
896        .open_with(name, &options)
897        .map_err(TransferReceiverError::Io)?;
898    file.write_all(bytes).map_err(TransferReceiverError::Io)?;
899    file.sync_all().map_err(TransferReceiverError::Io)
900}
901
902fn read_file_bounded(
903    directory: &Dir,
904    name: impl AsRef<Path>,
905    maximum: u64,
906) -> Result<Vec<u8>, TransferReceiverError> {
907    let mut file =
908        open_regular_file_nofollow(directory, name).map_err(TransferReceiverError::Io)?;
909    let mut bytes = Vec::new();
910    Read::by_ref(&mut file)
911        .take(maximum + 1)
912        .read_to_end(&mut bytes)
913        .map_err(TransferReceiverError::Io)?;
914    if bytes.len() as u64 > maximum {
915        return Err(TransferReceiverError::EncodedManifestTooLarge {
916            maximum_bytes: maximum,
917        });
918    }
919    Ok(bytes)
920}
921
922fn open_regular_file_nofollow(
923    directory: &Dir,
924    name: impl AsRef<Path>,
925) -> std::io::Result<cap_std::fs::File> {
926    let mut options = OpenOptions::new();
927    options.read(true).follow(FollowSymlinks::No);
928    let file = directory.open_with(name, &options)?;
929    if !file.metadata()?.is_file() {
930        return Err(std::io::Error::other(
931            "checkpoint entry is not a regular file",
932        ));
933    }
934    Ok(file)
935}
936
937fn open_lock_file_nofollow(directory: &Dir) -> Result<std::fs::File, TransferReceiverError> {
938    let mut options = OpenOptions::new();
939    options.read(true).write(true).follow(FollowSymlinks::No);
940    let file = directory
941        .open_with(RECEIVER_LOCK_FILE, &options)
942        .map_err(TransferReceiverError::Io)?;
943    if !file
944        .metadata()
945        .map_err(TransferReceiverError::Io)?
946        .is_file()
947    {
948        return Err(TransferReceiverError::UnrecognizedCheckpointEntry);
949    }
950    Ok(file.into_std())
951}
952
953fn open_named_file_identity(
954    directory: &Dir,
955    name: impl AsRef<Path>,
956) -> Result<RetainedPhysicalIdentity, TransferReceiverError> {
957    let file = open_regular_file_nofollow(directory, name).map_err(TransferReceiverError::Io)?;
958    RetainedPhysicalIdentity::from_file(file.into_std()).map_err(TransferReceiverError::Io)
959}
960
961fn open_named_directory_identity(
962    parent: &Dir,
963    name: impl AsRef<Path>,
964) -> Result<RetainedPhysicalIdentity, TransferReceiverError> {
965    let directory = parent
966        .open_dir_nofollow(name)
967        .map_err(TransferReceiverError::Io)?;
968    RetainedPhysicalIdentity::from_file(directory.into_std_file())
969        .map_err(TransferReceiverError::Io)
970}
971
972#[cfg(unix)]
973fn sync_directory(directory: &Dir) -> Result<(), TransferReceiverError> {
974    directory
975        .open_with(
976            ".",
977            OpenOptions::new().read(true).follow(FollowSymlinks::No),
978        )
979        .and_then(|file| file.into_std().sync_all())
980        .map_err(TransferReceiverError::Io)
981}
982
983#[cfg(windows)]
984fn sync_directory(_directory: &Dir) -> Result<(), TransferReceiverError> {
985    // Windows exposes no documented equivalent of POSIX directory fsync.
986    // Every staged regular file is still flushed before its no-clobber install.
987    Ok(())
988}
989
990fn validate_expected_digest(digest: &str) -> Result<(), TransferReceiverError> {
991    if !is_sha256(digest) {
992        return Err(TransferReceiverError::InvalidExpectedManifestDigest);
993    }
994    Ok(())
995}
996
997fn copy_exact_chunk(
998    descriptor: &ChunkDescriptor,
999    reader: &mut impl Read,
1000    writer: &mut impl Write,
1001) -> Result<(), TransferReceiverError> {
1002    let mut remaining = descriptor.bytes;
1003    let mut hasher = Sha256::new();
1004    let mut buffer = [0_u8; TRANSFER_IO_BUFFER_BYTES];
1005    while remaining > 0 {
1006        let wanted = usize::try_from(remaining.min(buffer.len() as u64))
1007            .expect("fixed transfer buffer fits usize");
1008        let read = reader
1009            .read(&mut buffer[..wanted])
1010            .map_err(TransferReceiverError::Io)?;
1011        if read == 0 {
1012            return Err(TransferReceiverError::ChunkLengthMismatch(descriptor.index));
1013        }
1014        writer
1015            .write_all(&buffer[..read])
1016            .map_err(TransferReceiverError::Io)?;
1017        hasher.update(&buffer[..read]);
1018        remaining -= read as u64;
1019    }
1020    let mut trailing = [0_u8; 1];
1021    if reader
1022        .read(&mut trailing)
1023        .map_err(TransferReceiverError::Io)?
1024        != 0
1025    {
1026        return Err(TransferReceiverError::ChunkLengthMismatch(descriptor.index));
1027    }
1028    if format!("{:x}", hasher.finalize()) != descriptor.sha256 {
1029        return Err(TransferReceiverError::ChunkDigestMismatch(descriptor.index));
1030    }
1031    Ok(())
1032}
1033
1034fn validate_chunk_reader(
1035    descriptor: &ChunkDescriptor,
1036    reader: &mut impl Read,
1037) -> Result<(), TransferReceiverError> {
1038    copy_exact_chunk(descriptor, reader, &mut std::io::sink())
1039}
1040
1041fn chunk_file_name(index: u32) -> String {
1042    format!("{index}.chunk")
1043}
1044
1045trait CheckpointLock {
1046    fn lock_exclusive(&self) -> std::io::Result<()>;
1047    fn unlock_exclusive(&self) -> std::io::Result<()>;
1048}
1049
1050impl CheckpointLock for std::fs::File {
1051    fn lock_exclusive(&self) -> std::io::Result<()> {
1052        self.lock()
1053    }
1054
1055    fn unlock_exclusive(&self) -> std::io::Result<()> {
1056        self.unlock()
1057    }
1058}
1059
1060struct CheckpointLease<'a, L: CheckpointLock + ?Sized> {
1061    lock: &'a L,
1062    poisoned: &'a AtomicBool,
1063    released: bool,
1064}
1065
1066impl<'a, L: CheckpointLock + ?Sized> CheckpointLease<'a, L> {
1067    fn acquire(lock: &'a L, poisoned: &'a AtomicBool) -> Result<Self, TransferReceiverError> {
1068        if poisoned.load(Ordering::Acquire) {
1069            return Err(TransferReceiverError::CheckpointStateChanged);
1070        }
1071        lock.lock_exclusive().map_err(TransferReceiverError::Io)?;
1072        Ok(Self {
1073            lock,
1074            poisoned,
1075            released: false,
1076        })
1077    }
1078
1079    fn complete<T>(
1080        mut self,
1081        operation: Result<T, TransferReceiverError>,
1082    ) -> Result<T, TransferReceiverError> {
1083        match self.lock.unlock_exclusive() {
1084            Ok(()) => {
1085                self.released = true;
1086                operation
1087            }
1088            Err(source) => {
1089                self.poisoned.store(true, Ordering::Release);
1090                Err(TransferReceiverError::Io(source))
1091            }
1092        }
1093    }
1094}
1095
1096impl<L: CheckpointLock + ?Sized> Drop for CheckpointLease<'_, L> {
1097    fn drop(&mut self) {
1098        if !self.released && self.lock.unlock_exclusive().is_err() {
1099            self.poisoned.store(true, Ordering::Release);
1100        }
1101    }
1102}
1103
1104fn reclaim_stale_staging(chunks: &Dir) -> Result<(), TransferReceiverError> {
1105    for entry in chunks.entries().map_err(TransferReceiverError::Io)? {
1106        let entry = entry.map_err(TransferReceiverError::Io)?;
1107        let name = entry
1108            .file_name()
1109            .into_string()
1110            .map_err(|_| TransferReceiverError::UnrecognizedCheckpointEntry)?;
1111        if !is_staging_name(&name) {
1112            continue;
1113        }
1114        let metadata = chunks
1115            .symlink_metadata(&name)
1116            .map_err(TransferReceiverError::Io)?;
1117        if !metadata.is_file() || metadata.file_type().is_symlink() {
1118            return Err(TransferReceiverError::CheckpointStateChanged);
1119        }
1120        validate_private_regular_file(chunks, &name)?;
1121        let identity = open_named_file_identity(chunks, &name)
1122            .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
1123        cleanup_owned_staging(chunks, &name, &identity)?;
1124    }
1125    Ok(())
1126}
1127
1128fn cleanup_owned_staging(
1129    chunks: &Dir,
1130    name: &str,
1131    expected: &RetainedPhysicalIdentity,
1132) -> Result<(), TransferReceiverError> {
1133    let current = open_named_file_identity(chunks, name)
1134        .map_err(|_| TransferReceiverError::CheckpointStateChanged)?;
1135    if &current != expected {
1136        return Err(TransferReceiverError::CheckpointStateChanged);
1137    }
1138    chunks
1139        .remove_file(name)
1140        .map_err(TransferReceiverError::Io)?;
1141    sync_directory(chunks)
1142}
1143
1144fn validate_checkpoint_top_level(directory: &Dir) -> Result<(), TransferReceiverError> {
1145    validate_private_directory(directory)?;
1146    let mut has_manifest = false;
1147    let mut has_chunks = false;
1148    let mut has_receiver_lock = false;
1149    for entry in directory.entries().map_err(TransferReceiverError::Io)? {
1150        let entry = entry.map_err(TransferReceiverError::Io)?;
1151        match entry.file_name().to_str() {
1152            Some(MANIFEST_FILE) => has_manifest = true,
1153            Some(CHUNKS_DIRECTORY) => has_chunks = true,
1154            Some(RECEIVER_LOCK_FILE) => has_receiver_lock = true,
1155            _ => return Err(TransferReceiverError::UnrecognizedCheckpointEntry),
1156        }
1157    }
1158    if !has_manifest || !has_chunks || !has_receiver_lock {
1159        return Err(TransferReceiverError::InvalidCheckpointManifest);
1160    }
1161    validate_private_regular_file(directory, MANIFEST_FILE)?;
1162    validate_private_regular_file(directory, RECEIVER_LOCK_FILE)?;
1163    let chunks = directory
1164        .open_dir_nofollow(CHUNKS_DIRECTORY)
1165        .map_err(TransferReceiverError::Io)?;
1166    validate_private_directory(&chunks)?;
1167    Ok(())
1168}
1169
1170fn parse_installed_chunk_index(name: &str) -> Option<u32> {
1171    let index = name.strip_suffix(".chunk")?;
1172    if index.is_empty() || (index.len() > 1 && index.starts_with('0')) {
1173        return None;
1174    }
1175    index.parse().ok()
1176}
1177
1178fn is_staging_name(name: &str) -> bool {
1179    let Some(encoded) = name
1180        .strip_prefix(".chunk-")
1181        .and_then(|suffix| suffix.strip_suffix(".part"))
1182    else {
1183        return false;
1184    };
1185    Uuid::parse_str(encoded).is_ok_and(|uuid| {
1186        uuid.get_version() == Some(Version::SortRand) && uuid.hyphenated().to_string() == encoded
1187    })
1188}
1189
1190fn is_legacy_manifest(encoded: &[u8]) -> bool {
1191    #[derive(Deserialize)]
1192    struct LegacyManifestProbe {
1193        object_digest: serde_json::Value,
1194        bytes: serde_json::Value,
1195        chunks: serde_json::Value,
1196    }
1197    serde_json::from_slice::<LegacyManifestProbe>(encoded)
1198        .map(|probe| {
1199            let _ = (probe.object_digest, probe.bytes, probe.chunks);
1200            true
1201        })
1202        .unwrap_or(false)
1203}
1204
1205fn validate_chunk_entries_for_manifest(
1206    chunks: &Dir,
1207    manifest: &ChunkManifest,
1208) -> Result<(), TransferReceiverError> {
1209    validate_private_directory(chunks)?;
1210    for entry in chunks.entries().map_err(TransferReceiverError::Io)? {
1211        let entry = entry.map_err(TransferReceiverError::Io)?;
1212        let name = entry
1213            .file_name()
1214            .into_string()
1215            .map_err(|_| TransferReceiverError::UnrecognizedCheckpointEntry)?;
1216        let metadata = chunks
1217            .symlink_metadata(&name)
1218            .map_err(TransferReceiverError::Io)?;
1219        if !metadata.is_file() || metadata.file_type().is_symlink() {
1220            return Err(TransferReceiverError::UnrecognizedCheckpointEntry);
1221        }
1222        validate_private_regular_file(chunks, &name)?;
1223        if is_staging_name(&name) {
1224            continue;
1225        }
1226        let Some(index) = parse_installed_chunk_index(&name) else {
1227            return Err(TransferReceiverError::UnrecognizedCheckpointEntry);
1228        };
1229        if manifest
1230            .chunks
1231            .get(index as usize)
1232            .is_none_or(|descriptor| descriptor.index != index)
1233        {
1234            return Err(TransferReceiverError::UnrecognizedCheckpointEntry);
1235        }
1236    }
1237    Ok(())
1238}
1239
1240#[cfg(unix)]
1241fn validate_private_directory(directory: &Dir) -> Result<(), TransferReceiverError> {
1242    if directory
1243        .dir_metadata()
1244        .map_err(TransferReceiverError::Io)?
1245        .mode()
1246        & 0o777
1247        != 0o700
1248    {
1249        return Err(TransferReceiverError::InsecureCheckpointPermissions);
1250    }
1251    Ok(())
1252}
1253
1254#[cfg(not(unix))]
1255fn validate_private_directory(_directory: &Dir) -> Result<(), TransferReceiverError> {
1256    Ok(())
1257}
1258
1259#[cfg(unix)]
1260fn validate_private_regular_file(
1261    directory: &Dir,
1262    name: impl AsRef<Path>,
1263) -> Result<(), TransferReceiverError> {
1264    if directory
1265        .symlink_metadata(name)
1266        .map_err(TransferReceiverError::Io)?
1267        .mode()
1268        & 0o777
1269        != 0o600
1270    {
1271        return Err(TransferReceiverError::InsecureCheckpointPermissions);
1272    }
1273    Ok(())
1274}
1275
1276#[cfg(not(unix))]
1277fn validate_private_regular_file(
1278    _directory: &Dir,
1279    _name: impl AsRef<Path>,
1280) -> Result<(), TransferReceiverError> {
1281    Ok(())
1282}
1283
1284#[cfg(test)]
1285mod tests {
1286    use std::{
1287        cell::Cell,
1288        io,
1289        sync::atomic::{AtomicBool, Ordering},
1290    };
1291
1292    use sha2::{Digest, Sha256};
1293
1294    use super::{
1295        AcceptedChunkReader, CheckpointLease, CheckpointLock, ChunkAcceptance,
1296        MATERIALIZATION_OBJECT_FILE, MaterializationStaging, TransferReceiverError,
1297        windows_destination_spelling_is_exact,
1298    };
1299
1300    #[derive(Default)]
1301    struct InjectedUnlockFailure {
1302        lock_calls: Cell<usize>,
1303        unlock_calls: Cell<usize>,
1304    }
1305
1306    impl CheckpointLock for InjectedUnlockFailure {
1307        fn lock_exclusive(&self) -> io::Result<()> {
1308            self.lock_calls.set(self.lock_calls.get() + 1);
1309            Ok(())
1310        }
1311
1312        fn unlock_exclusive(&self) -> io::Result<()> {
1313            self.unlock_calls.set(self.unlock_calls.get() + 1);
1314            Err(io::Error::other("injected unlock failure"))
1315        }
1316    }
1317
1318    #[test]
1319    fn explicit_unlock_failure_is_reported_and_poisoned_before_relock() {
1320        let lock = InjectedUnlockFailure::default();
1321        let poisoned = AtomicBool::new(false);
1322        let lease = CheckpointLease::acquire(&lock, &poisoned).unwrap();
1323
1324        let result = lease.complete(Ok(ChunkAcceptance::Accepted));
1325
1326        assert!(
1327            matches!(result, Err(TransferReceiverError::Io(ref error))
1328                if error.to_string() == "injected unlock failure"),
1329            "{result:?}"
1330        );
1331        assert!(poisoned.load(Ordering::Acquire));
1332        assert_eq!(lock.lock_calls.get(), 1);
1333        assert_eq!(
1334            lock.unlock_calls.get(),
1335            2,
1336            "ordinary release is explicit and Drop makes one best-effort retry"
1337        );
1338        assert!(matches!(
1339            CheckpointLease::acquire(&lock, &poisoned),
1340            Err(TransferReceiverError::CheckpointStateChanged)
1341        ));
1342        assert_eq!(
1343            lock.lock_calls.get(),
1344            1,
1345            "a poisoned receiver must fail before a platform-dependent relock"
1346        );
1347    }
1348
1349    #[test]
1350    fn windows_raw_destination_segments_reject_aliases_but_allow_either_separator() {
1351        for spelling in ["nested/artifact.bin", r"nested\artifact.bin"] {
1352            assert!(
1353                windows_destination_spelling_is_exact(&spelling.encode_utf16().collect::<Vec<_>>()),
1354                "{spelling:?}"
1355            );
1356        }
1357        for spelling in [
1358            "nested//artifact.bin",
1359            r"nested\\artifact.bin",
1360            "nested/./artifact.bin",
1361            r"nested\.\artifact.bin",
1362            "nested/../artifact.bin",
1363            r"nested\..\artifact.bin",
1364            "nested/",
1365            "nested\\",
1366        ] {
1367            assert!(
1368                !windows_destination_spelling_is_exact(
1369                    &spelling.encode_utf16().collect::<Vec<_>>()
1370                ),
1371                "{spelling:?}"
1372            );
1373        }
1374    }
1375
1376    #[cfg(unix)]
1377    #[test]
1378    fn removed_materialization_object_stays_removed_after_directory_sync_failure() {
1379        use std::io::Write;
1380
1381        use cap_std::{ambient_authority, fs::Dir};
1382
1383        let temporary = tempfile::tempdir().unwrap();
1384        let destination_root =
1385            Dir::open_ambient_dir(temporary.path(), ambient_authority()).unwrap();
1386        let mut staging = MaterializationStaging::create(&destination_root).unwrap();
1387        let staging_name = staging.name.clone();
1388        let mut object = staging.create_object().unwrap();
1389        object.write_all(b"verified original").unwrap();
1390        object.sync_all().unwrap();
1391        drop(object);
1392
1393        let result = staging.remove_object_with(
1394            |directory| {
1395                directory
1396                    .remove_file(MATERIALIZATION_OBJECT_FILE)
1397                    .map_err(TransferReceiverError::Io)
1398            },
1399            |_| {
1400                Err(TransferReceiverError::Io(io::Error::other(
1401                    "injected staging directory sync failure",
1402                )))
1403            },
1404        );
1405
1406        assert!(
1407            matches!(result, Err(TransferReceiverError::Io(ref error))
1408                if error.to_string() == "injected staging directory sync failure"),
1409            "{result:?}"
1410        );
1411        assert!(staging.object_removed);
1412        assert!(!temporary.path().join(&staging_name).join("object").exists());
1413        drop(staging);
1414        assert!(!temporary.path().join(staging_name).exists());
1415    }
1416
1417    #[cfg(unix)]
1418    #[test]
1419    fn object_identity_is_relinquished_before_unlink_is_attempted() {
1420        use std::io::Write;
1421
1422        use cap_std::{ambient_authority, fs::Dir};
1423
1424        let temporary = tempfile::tempdir().unwrap();
1425        let destination_root =
1426            Dir::open_ambient_dir(temporary.path(), ambient_authority()).unwrap();
1427        let mut staging = MaterializationStaging::create(&destination_root).unwrap();
1428        let staging_name = staging.name.clone();
1429        let mut object = staging.create_object().unwrap();
1430        object.write_all(b"verified original").unwrap();
1431        object.sync_all().unwrap();
1432        drop(object);
1433
1434        let result = staging.remove_object_with(
1435            |_| {
1436                Err(TransferReceiverError::Io(io::Error::other(
1437                    "injected unlink failure",
1438                )))
1439            },
1440            |_| panic!("sync must not run after an unlink failure"),
1441        );
1442
1443        assert!(
1444            matches!(result, Err(TransferReceiverError::Io(ref error))
1445                if error.to_string() == "injected unlink failure"),
1446            "{result:?}"
1447        );
1448        assert!(staging.object_identity.is_none());
1449        assert!(!staging.object_removed);
1450        assert!(temporary.path().join(staging_name).join("object").exists());
1451    }
1452
1453    #[cfg(unix)]
1454    #[test]
1455    fn directory_identity_is_relinquished_before_open_directory_removal_is_attempted() {
1456        use cap_std::{ambient_authority, fs::Dir};
1457
1458        let temporary = tempfile::tempdir().unwrap();
1459        let destination_root =
1460            Dir::open_ambient_dir(temporary.path(), ambient_authority()).unwrap();
1461        let mut staging = MaterializationStaging::create(&destination_root).unwrap();
1462        let staging_name = staging.name.clone();
1463
1464        let result = staging.remove_directory_with(|_| {
1465            Err(TransferReceiverError::Io(io::Error::other(
1466                "injected open-directory removal failure",
1467            )))
1468        });
1469
1470        assert!(
1471            matches!(result, Err(TransferReceiverError::Io(ref error))
1472                if error.to_string() == "injected open-directory removal failure"),
1473            "{result:?}"
1474        );
1475        assert!(staging.directory_identity.is_none());
1476        assert!(staging.directory.is_none());
1477        assert!(temporary.path().join(staging_name).exists());
1478    }
1479
1480    #[cfg(unix)]
1481    #[test]
1482    fn identical_replacement_of_an_open_accepted_chunk_fails_at_eof_identity_check() {
1483        use std::{io::Read, os::unix::fs::PermissionsExt};
1484
1485        use cap_std::{ambient_authority, fs::Dir};
1486
1487        use crate::transfer_manifest::{
1488            CHUNKING_ALGORITHM_V1, ChunkDescriptor, ChunkManifest, MANIFEST_FORMAT_V1,
1489            STANDARD_PROFILE_V1,
1490        };
1491
1492        let temporary = tempfile::tempdir().unwrap();
1493        let chunks = Dir::open_ambient_dir(temporary.path(), ambient_authority()).unwrap();
1494        let bytes = b"transfer payload";
1495        let digest = format!("{:x}", Sha256::digest(bytes));
1496        let manifest = ChunkManifest {
1497            format: MANIFEST_FORMAT_V1.to_owned(),
1498            algorithm: CHUNKING_ALGORITHM_V1.to_owned(),
1499            profile: STANDARD_PROFILE_V1.to_owned(),
1500            minimum_chunk_bytes: 256 * 1024,
1501            average_chunk_bytes: 1024 * 1024,
1502            maximum_chunk_bytes: 4 * 1024 * 1024,
1503            object_sha256: digest.clone(),
1504            object_bytes: bytes.len() as u64,
1505            chunks: vec![ChunkDescriptor {
1506                index: 0,
1507                offset: 0,
1508                bytes: bytes.len() as u64,
1509                sha256: digest,
1510            }],
1511        };
1512        let accepted = temporary.path().join("0.chunk");
1513        std::fs::write(&accepted, bytes).unwrap();
1514        std::fs::set_permissions(&accepted, std::fs::Permissions::from_mode(0o600)).unwrap();
1515
1516        let mut reader = AcceptedChunkReader::new(&chunks, &manifest);
1517        let mut prefix = [0_u8; 15];
1518        reader.read_exact(&mut prefix).unwrap();
1519        assert_eq!(&prefix, &bytes[..15]);
1520
1521        let retained = temporary.path().join("retained-original.chunk");
1522        std::fs::rename(&accepted, retained).unwrap();
1523        std::fs::write(&accepted, bytes).unwrap();
1524        std::fs::set_permissions(&accepted, std::fs::Permissions::from_mode(0o600)).unwrap();
1525
1526        let mut final_byte = [0_u8; 1];
1527        reader.read_exact(&mut final_byte).unwrap();
1528        assert_eq!(final_byte[0], bytes[15]);
1529        let error = reader.read(&mut final_byte).unwrap_err();
1530
1531        assert_eq!(error.kind(), io::ErrorKind::Other);
1532        assert!(
1533            error
1534                .to_string()
1535                .contains("accepted chunk 0 pathname identity changed"),
1536            "{error}"
1537        );
1538        assert_eq!(std::fs::read(accepted).unwrap(), bytes);
1539    }
1540
1541    #[cfg(unix)]
1542    #[test]
1543    fn replaced_materialization_staging_directory_is_neither_linked_nor_removed() {
1544        use std::{io::Write, os::unix::fs::PermissionsExt};
1545
1546        use cap_std::{ambient_authority, fs::Dir};
1547
1548        let temporary = tempfile::tempdir().unwrap();
1549        let destination_root =
1550            Dir::open_ambient_dir(temporary.path(), ambient_authority()).unwrap();
1551        let mut staging = MaterializationStaging::create(&destination_root).unwrap();
1552        let staging_name = staging.name.clone();
1553        let mut object = staging.create_object().unwrap();
1554        object.write_all(b"verified original").unwrap();
1555        object.sync_all().unwrap();
1556        drop(object);
1557
1558        let retained = temporary.path().join("retained-original");
1559        std::fs::rename(temporary.path().join(&staging_name), &retained).unwrap();
1560        let replacement = temporary.path().join(&staging_name);
1561        std::fs::create_dir(&replacement).unwrap();
1562        std::fs::set_permissions(&replacement, std::fs::Permissions::from_mode(0o700)).unwrap();
1563        std::fs::write(replacement.join("sentinel"), b"replacement must survive").unwrap();
1564
1565        let install = staging.install("must-not-install.bin");
1566
1567        assert!(
1568            matches!(install, Err(TransferReceiverError::DestinationStateChanged)),
1569            "{install:?}"
1570        );
1571        assert!(!temporary.path().join("must-not-install.bin").exists());
1572        assert!(matches!(
1573            staging.cleanup(),
1574            Err(TransferReceiverError::DestinationStateChanged)
1575        ));
1576        assert_eq!(
1577            std::fs::read(replacement.join("sentinel")).unwrap(),
1578            b"replacement must survive"
1579        );
1580        assert!(
1581            !retained.exists(),
1582            "cleanup must remove the original directory through its retained capability"
1583        );
1584    }
1585}