1use 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#[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#[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 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 ¤t_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 ¤t_object != expected_object {
727 return Err(TransferReceiverError::DestinationStateChanged);
728 }
729 }
730 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 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 ¤t != 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, ¤t.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 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 ¤t != 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}