1use std::{
9 collections::BTreeMap,
10 fmt::Write as _,
11 fs::{self, File, OpenOptions},
12 io::{Read, Write},
13 path::{Component, Path, PathBuf},
14};
15
16use chrono::Utc;
17use serde::{Deserialize, Serialize};
18use serde_json::Value;
19use sha2::{Digest, Sha256};
20use uuid::Uuid;
21
22use crate::{
23 FolderbaseError, Result,
24 folderbase_state::FolderbaseState,
25 workspace::{
26 canonical_folderbase_root, has_nested_folderbase_marker, is_reserved_workspace_component,
27 refuse_generic_workspace_mutation_path, resolve_existing_workspace_file,
28 },
29};
30
31const OBJECT_SCHEMA: &str = "https://folderbase.ai/protocol/0.1/object.schema.json";
32const OBJECTS_DIRECTORY: &str = ".folderbase/objects";
33const VERSION_RECORDS_DIRECTORY: &str = ".folderbase/versions/records";
34const BLOBS_DIRECTORY: &str = ".folderbase/versions/blobs/sha256";
35const JOURNAL_PATH: &str = ".folderbase/journal/objects.ndjson";
36const JOURNAL_QUARANTINE_DIRECTORY: &str = ".folderbase/journal/quarantine";
37const TRANSACTIONS_DIRECTORY: &str = ".folderbase/transactions";
38const LOCKS_DIRECTORY: &str = ".folderbase/locks";
39const TRANSACTION_LOCK_PATH: &str = ".folderbase/locks/transactions.lock";
40const COPY_BUFFER_BYTES: usize = 64 * 1024;
41const MAX_CAPTURE_PROJECTION_RECORD_BYTES: u64 = 1024 * 1024;
42const PATH_IDENTITIES_DIRECTORY: &str = ".folderbase/local/path-identities";
43const HISTORY_TRANSFER_INTENTS_DIRECTORY: &str = ".folderbase/history-transfers/intents";
44const HISTORY_TRANSFER_OUTGOING_DIRECTORY: &str = ".folderbase/history-transfers/outgoing";
45const HISTORY_TRANSFER_INCOMING_DIRECTORY: &str = ".folderbase/history-transfers/incoming";
46const HISTORY_TRANSFER_STAGING_DIRECTORY: &str = ".folderbase/history-transfers/staging";
47
48#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
50#[serde(transparent)]
51pub struct ObjectId(String);
52
53impl ObjectId {
54 pub fn as_str(&self) -> &str {
55 &self.0
56 }
57
58 pub(crate) fn new() -> Self {
59 Self(format!("obj_{}", Uuid::now_v7()))
60 }
61
62 fn validate(&self, record_path: &Path) -> Result<()> {
63 validate_prefixed_uuid(&self.0, "obj_", record_path)
64 }
65
66 pub fn parse(value: impl Into<String>) -> Result<Self> {
67 let value = Self(value.into());
68 value.validate(Path::new("object-id"))?;
69 Ok(value)
70 }
71}
72
73impl std::fmt::Display for ObjectId {
74 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75 formatter.write_str(&self.0)
76 }
77}
78
79#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
81#[serde(transparent)]
82pub struct VersionId(String);
83
84impl VersionId {
85 pub fn as_str(&self) -> &str {
86 &self.0
87 }
88
89 pub(crate) fn new() -> Self {
90 Self(format!("version_{}", Uuid::now_v7()))
91 }
92
93 fn validate(&self, record_path: &Path) -> Result<()> {
94 validate_prefixed_uuid(&self.0, "version_", record_path)
95 }
96
97 pub fn parse(value: impl Into<String>) -> Result<Self> {
98 let value = Self(value.into());
99 value.validate(Path::new("version-id"))?;
100 Ok(value)
101 }
102}
103
104impl std::fmt::Display for VersionId {
105 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
106 formatter.write_str(&self.0)
107 }
108}
109
110#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
111pub struct ObjectLifecycle {
112 pub status: String,
113 #[serde(flatten)]
114 pub extensions: BTreeMap<String, Value>,
115}
116
117#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
118pub struct ObjectProvenance {
119 pub created_at: String,
120 pub source: String,
121 #[serde(flatten)]
122 pub extensions: BTreeMap<String, Value>,
123}
124
125#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
129pub struct LocalObjectRecord {
130 #[serde(rename = "$schema")]
131 pub schema: String,
132 pub id: ObjectId,
133 #[serde(rename = "type")]
134 pub object_type: String,
135 pub path: String,
136 pub lifecycle: ObjectLifecycle,
137 pub provenance: ObjectProvenance,
138 pub current_version: VersionId,
139 pub versions: Vec<VersionId>,
140 #[serde(flatten)]
141 pub extensions: BTreeMap<String, Value>,
142}
143
144#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
145pub struct ContentDigest {
146 pub algorithm: String,
147 pub digest: String,
148 pub bytes: u64,
149}
150
151#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
153pub struct LocalVersionRecord {
154 pub id: VersionId,
155 pub object_id: ObjectId,
156 pub content: ContentDigest,
157 pub captured_at: String,
158 #[serde(flatten)]
159 pub extensions: BTreeMap<String, Value>,
160}
161
162#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
163pub enum JournalAction {
164 #[serde(rename = "object.tracked")]
165 ObjectTracked,
166 #[serde(rename = "object.relocated")]
167 ObjectRelocated,
168 #[serde(rename = "version.captured")]
169 VersionCaptured,
170 #[serde(rename = "version.restored")]
171 VersionRestored,
172}
173
174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
176pub struct ObjectJournalEvent {
177 pub id: String,
178 pub at: String,
179 pub action: JournalAction,
180 pub object_id: ObjectId,
181 pub path: String,
182 #[serde(skip_serializing_if = "Option::is_none")]
183 pub previous_path: Option<String>,
184 #[serde(skip_serializing_if = "Option::is_none")]
185 pub version_id: Option<VersionId>,
186 #[serde(skip_serializing_if = "Option::is_none")]
187 pub content: Option<ContentDigest>,
188}
189
190#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
191pub struct CaptureResult {
192 pub object: LocalObjectRecord,
193 pub version: LocalVersionRecord,
194 pub object_created: bool,
195 pub version_created: bool,
196}
197
198#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
199pub struct RestoreResult {
200 pub object_id: ObjectId,
201 pub version_id: VersionId,
202 pub path: PathBuf,
203 pub content: ContentDigest,
204}
205
206#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
207#[serde(rename_all = "snake_case")]
208pub enum HistoryTransferState {
209 Proposed,
210 Approved,
211 Applying,
212 DestinationVerified,
213 SourceReleased,
214 Verified,
215 Conflicted,
216}
217
218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219pub struct HistoryTransferPlan {
220 protocol_version: String,
221 id: String,
222 source_root: PathBuf,
223 destination_root: PathBuf,
224 source_folderbase_id: String,
225 destination_folderbase_id: String,
226 source_manifest_sha256: String,
227 destination_manifest_sha256: String,
228 object: LocalObjectRecord,
229 destination_path: String,
230 versions: Vec<LocalVersionRecord>,
231 state: HistoryTransferState,
232 #[serde(default, skip_serializing_if = "Option::is_none")]
233 approval_digest: Option<String>,
234}
235
236impl HistoryTransferPlan {
237 pub fn id(&self) -> &str {
238 &self.id
239 }
240
241 pub fn state(&self) -> HistoryTransferState {
242 self.state
243 }
244
245 pub fn source_folderbase_id(&self) -> &str {
246 &self.source_folderbase_id
247 }
248
249 pub fn destination_folderbase_id(&self) -> &str {
250 &self.destination_folderbase_id
251 }
252
253 pub fn object_id(&self) -> &ObjectId {
254 &self.object.id
255 }
256
257 pub fn version_ids(&self) -> impl Iterator<Item = &VersionId> {
258 self.versions.iter().map(|version| &version.id)
259 }
260}
261
262#[derive(Debug)]
263pub struct ApprovedHistoryTransfer {
264 plan: HistoryTransferPlan,
265 approval_digest: String,
266}
267
268#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
269pub struct HistoryTransferResult {
270 pub transfer_id: String,
271 pub source_folderbase_id: String,
272 pub destination_folderbase_id: String,
273 pub object_id: ObjectId,
274 pub state: HistoryTransferState,
275 pub version_ids: Vec<VersionId>,
276}
277
278#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
279struct HistoryTransferReceipt {
280 protocol_version: String,
281 transfer_id: String,
282 source_folderbase_id: String,
283 destination_folderbase_id: String,
284 object_id: ObjectId,
285 approval_digest: String,
286 version_ids: Vec<VersionId>,
287}
288
289#[derive(Debug, Clone, Copy, PartialEq, Eq)]
290enum HistoryTransferCheckpoint {
291 Applying,
292 DestinationStaged,
293 DestinationVerified,
294 SourceReceiptWritten,
295 SourceReleased,
296 IncomingReceiptWritten,
297 DestinationActivated,
298 Verified,
299}
300
301#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
309struct PendingTransaction {
310 protocol_version: String,
311 id: String,
312 version: Option<LocalVersionRecord>,
313 #[serde(default, skip_serializing_if = "Vec::is_empty")]
314 versions: Vec<LocalVersionRecord>,
315 object: LocalObjectRecord,
316 #[serde(default, skip_serializing_if = "Option::is_none")]
317 restore: Option<PendingRestore>,
318 #[serde(default, skip_serializing_if = "Option::is_none")]
319 replacement: Option<PendingReplacement>,
320 events: Vec<ObjectJournalEvent>,
321}
322
323#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
324struct PendingRestore {
325 version_id: VersionId,
326 destination: String,
327 content: ContentDigest,
328}
329
330#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
331struct PendingReplacement {
332 destination: String,
333 previous_content: ContentDigest,
334 content: ContentDigest,
335 readonly: bool,
336 #[serde(default, skip_serializing_if = "Option::is_none")]
337 unix_mode: Option<u32>,
338 #[serde(default, skip_serializing_if = "Option::is_none")]
339 file_identity: Option<FileSystemIdentity>,
340 #[serde(default, skip_serializing_if = "Option::is_none")]
341 parent_identity: Option<FileSystemIdentity>,
342}
343
344#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
345struct FileSystemIdentity {
346 device: u64,
347 inode: u64,
348}
349
350#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
351struct LocalPathIdentity {
352 object_id: ObjectId,
353 file_system: FileSystemIdentity,
354}
355
356#[derive(Debug, Clone)]
357pub(crate) struct VersionedReplaceResult {
358 pub object_id: ObjectId,
359 pub version_id: VersionId,
360 pub previous_content: ContentDigest,
361 pub content: ContentDigest,
362}
363
364pub(crate) struct StoreTransactionLock {
365 file: File,
366}
367
368struct FolderbaseIdentity {
369 id: String,
370 manifest_sha256: String,
371}
372
373impl Drop for StoreTransactionLock {
374 fn drop(&mut self) {
375 let _ = File::unlock(&self.file);
376 }
377}
378
379#[derive(Debug, Clone)]
381pub struct LocalVersionStore {
382 root: PathBuf,
383}
384
385impl LocalVersionStore {
386 pub fn open(root: impl AsRef<Path>) -> Result<Self> {
392 let store = Self::open_read_only(root)?;
393 match fs::symlink_metadata(store.root.join(TRANSACTIONS_DIRECTORY)) {
394 Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {
395 let _lock = store.acquire_transaction_lock()?;
396 store.ensure_store_layout()?;
397 }
398 Ok(_) => {
399 return Err(FolderbaseError::UnsafePath(
400 store.root.join(TRANSACTIONS_DIRECTORY),
401 ));
402 }
403 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
404 Err(source) => {
405 return Err(FolderbaseError::io(
406 store.root.join(TRANSACTIONS_DIRECTORY),
407 source,
408 ));
409 }
410 }
411 Ok(store)
412 }
413
414 pub(crate) fn open_read_only(root: impl AsRef<Path>) -> Result<Self> {
417 let supplied = root.as_ref();
418 let root = canonical_folderbase_root(supplied)?;
419 Ok(Self { root })
420 }
421
422 pub fn root(&self) -> &Path {
423 &self.root
424 }
425
426 pub(crate) fn tracked_object_id(
427 &self,
428 relative_path: impl AsRef<Path>,
429 ) -> Result<Option<ObjectId>> {
430 let relative_path = safe_content_path(relative_path.as_ref())?;
431 self.find_object_by_path(&relative_path)
432 .map(|record| record.map(|record| record.id))
433 }
434
435 pub fn propose_history_transfer(
436 &self,
437 destination: &LocalVersionStore,
438 source_folderbase_id: &str,
439 destination_folderbase_id: &str,
440 object_id: &ObjectId,
441 destination_path: impl AsRef<Path>,
442 ) -> Result<HistoryTransferPlan> {
443 let source_identity = read_folderbase_identity(&self.root)?;
444 let destination_identity = read_folderbase_identity(&destination.root)?;
445 if source_identity.id != source_folderbase_id {
446 return Err(invalid_record(
447 self.root.join(".folderbase/manifest.json"),
448 "explicit source folderbase ID does not match the active manifest",
449 ));
450 }
451 if destination_identity.id != destination_folderbase_id {
452 return Err(invalid_record(
453 destination.root.join(".folderbase/manifest.json"),
454 "explicit destination folderbase ID does not match the active manifest",
455 ));
456 }
457 let nested_root = destination
458 .root
459 .strip_prefix(&self.root)
460 .map_err(|_| FolderbaseError::UnsafePath(destination.root.clone()))?;
461 let nested_root = safe_content_path(nested_root)?;
462 if !has_nested_folderbase_marker(&destination.root)? {
463 return Err(invalid_record(
464 &destination.root,
465 "history destination must be an active nested folderbase",
466 ));
467 }
468 let destination_path = safe_content_path(destination_path.as_ref())?;
469 let object = self.read_object_record_for_transfer(object_id)?;
470 if Path::new(&object.path) != nested_root.join(&destination_path) {
471 return Err(invalid_record(
472 self.object_record_path(object_id),
473 "tracked source path does not map to the requested nested-folderbase destination",
474 ));
475 }
476 let (materialized, canonical_destination_path) =
477 resolve_existing_workspace_file(&destination.root, &destination_path)?;
478 if canonical_destination_path != destination_path {
479 return Err(FolderbaseError::UnsafePath(destination_path));
480 }
481
482 if read_optional_file_nofollow(&destination.object_record_path(object_id))?.is_some()
483 || destination
484 .find_object_by_path(&canonical_destination_path)?
485 .is_some()
486 {
487 return Err(FolderbaseError::WouldOverwrite(
488 destination.object_record_path(object_id),
489 ));
490 }
491
492 let mut versions = Vec::with_capacity(object.versions.len());
493 for version_id in &object.versions {
494 let version = self.read_version_record(version_id)?;
495 if version.object_id != object.id {
496 return Err(invalid_record(
497 self.version_record_path(version_id),
498 "version belongs to a different object",
499 ));
500 }
501 verify_file_content(&self.blob_path(&version.content.digest), &version.content)?;
502 if let Some(bytes) =
503 read_optional_file_nofollow(&destination.version_record_path(version_id))?
504 {
505 let existing: LocalVersionRecord =
506 serde_json::from_slice(&bytes).map_err(|source| {
507 FolderbaseError::json(destination.version_record_path(version_id), source)
508 })?;
509 if existing != version {
510 return Err(FolderbaseError::WouldOverwrite(
511 destination.version_record_path(version_id),
512 ));
513 }
514 }
515 versions.push(version);
516 }
517 let current = versions
518 .iter()
519 .find(|version| version.id == object.current_version)
520 .ok_or_else(|| {
521 invalid_record(
522 self.object_record_path(object_id),
523 "current version is absent from transfer history",
524 )
525 })?;
526 verify_file_content(&materialized, ¤t.content)?;
527
528 let plan = HistoryTransferPlan {
529 protocol_version: "0.1.0".to_owned(),
530 id: format!("history_transfer_{}", Uuid::now_v7()),
531 source_root: self.root.clone(),
532 destination_root: destination.root.clone(),
533 source_folderbase_id: source_identity.id,
534 destination_folderbase_id: destination_identity.id,
535 source_manifest_sha256: source_identity.manifest_sha256,
536 destination_manifest_sha256: destination_identity.manifest_sha256,
537 object,
538 destination_path: relative_path_to_string(&destination_path)?,
539 versions,
540 state: HistoryTransferState::Proposed,
541 approval_digest: None,
542 };
543 ensure_directory_chain(&self.root, Path::new(HISTORY_TRANSFER_INTENTS_DIRECTORY))?;
544 write_json_new(&history_transfer_plan_path(&self.root, &plan.id), &plan)?;
545 Ok(plan)
546 }
547
548 fn read_object_record_for_transfer(&self, object_id: &ObjectId) -> Result<LocalObjectRecord> {
549 object_id.validate(&self.object_record_path(object_id))?;
550 let path = self.object_record_path(object_id);
551 let record: LocalObjectRecord = read_json(&path)?;
552 if record.id != *object_id
553 || record.versions.is_empty()
554 || !record.versions.contains(&record.current_version)
555 {
556 return Err(invalid_record(
557 path,
558 "object record is inconsistent for history transfer",
559 ));
560 }
561 safe_content_path(Path::new(&record.path))
562 .map_err(|_| invalid_record(path, "object record has an unsafe path"))?;
563 Ok(record)
564 }
565
566 pub fn capture_file(&self, relative_path: impl AsRef<Path>) -> Result<CaptureResult> {
572 let relative_path = safe_content_path(relative_path.as_ref())?;
573 let _lock = self.acquire_transaction_lock()?;
574 self.ensure_store_layout()?;
575 let (materialized_path, relative_path) =
576 resolve_existing_workspace_file(&self.root, &relative_path)?;
577
578 let existing_object = self.find_object_by_path(&relative_path)?;
579 let object_created = existing_object.is_none();
580 let object_id = existing_object
581 .as_ref()
582 .map(|record| record.id.clone())
583 .unwrap_or_else(ObjectId::new);
584
585 let content = self.install_content_blob(&materialized_path)?;
586
587 if let Some(object) = existing_object.as_ref() {
588 let current = self.read_version(&object.current_version)?;
589 if current.content == content {
590 self.persist_canonical_object_path(object)?;
591 self.write_local_file_identity(&object.id, &materialized_path)?;
592 return Ok(CaptureResult {
593 object: object.clone(),
594 version: current,
595 object_created: false,
596 version_created: false,
597 });
598 }
599 }
600
601 let captured_at = Utc::now().to_rfc3339();
602 let version = LocalVersionRecord {
603 id: VersionId::new(),
604 object_id: object_id.clone(),
605 content: content.clone(),
606 captured_at: captured_at.clone(),
607 extensions: BTreeMap::new(),
608 };
609
610 let path_string = relative_path_to_string(&relative_path)?;
611 let object = match existing_object {
612 Some(mut record) => {
613 record.current_version = version.id.clone();
614 record.versions.push(version.id.clone());
615 record
616 }
617 None => LocalObjectRecord {
618 schema: OBJECT_SCHEMA.to_owned(),
619 id: object_id.clone(),
620 object_type: "file".to_owned(),
621 path: path_string.clone(),
622 lifecycle: ObjectLifecycle {
623 status: "canonical".to_owned(),
624 extensions: BTreeMap::new(),
625 },
626 provenance: ObjectProvenance {
627 created_at: captured_at.clone(),
628 source: "local".to_owned(),
629 extensions: BTreeMap::new(),
630 },
631 current_version: version.id.clone(),
632 versions: vec![version.id.clone()],
633 extensions: BTreeMap::new(),
634 },
635 };
636
637 let mut events = Vec::with_capacity(if object_created { 2 } else { 1 });
638 if object_created {
639 events.push(ObjectJournalEvent {
640 id: format!("event_{}", Uuid::now_v7()),
641 at: captured_at.clone(),
642 action: JournalAction::ObjectTracked,
643 object_id: object_id.clone(),
644 path: path_string.clone(),
645 previous_path: None,
646 version_id: None,
647 content: None,
648 });
649 }
650 events.push(ObjectJournalEvent {
651 id: format!("event_{}", Uuid::now_v7()),
652 at: captured_at,
653 action: JournalAction::VersionCaptured,
654 object_id: object_id.clone(),
655 path: path_string,
656 previous_path: None,
657 version_id: Some(version.id.clone()),
658 content: Some(content),
659 });
660 self.commit_transaction(PendingTransaction {
661 protocol_version: "0.1.0".to_owned(),
662 id: format!("transaction_{}", Uuid::now_v7()),
663 version: Some(version.clone()),
664 versions: Vec::new(),
665 object: object.clone(),
666 restore: None,
667 replacement: None,
668 events,
669 })?;
670
671 Ok(CaptureResult {
672 object,
673 version,
674 object_created,
675 version_created: true,
676 })
677 }
678
679 pub(crate) fn replace_file_versioned(
680 &self,
681 relative_path: impl AsRef<Path>,
682 expected: &ContentDigest,
683 new_bytes: &[u8],
684 ) -> Result<VersionedReplaceResult> {
685 let relative_path = safe_content_path(relative_path.as_ref())?;
686 refuse_generic_workspace_mutation_path(&relative_path)?;
687 let _lock = self.acquire_transaction_lock()?;
688 self.ensure_store_layout()?;
689 let (materialized_path, relative_path) =
690 resolve_existing_workspace_file(&self.root, &relative_path)?;
691 refuse_generic_workspace_mutation_path(&relative_path)?;
692
693 let current_file = open_existing_nofollow(&materialized_path)?;
694 let metadata = current_file
695 .metadata()
696 .map_err(|source| FolderbaseError::io(&materialized_path, source))?;
697 let parent = materialized_path
698 .parent()
699 .ok_or_else(|| FolderbaseError::UnsafePath(materialized_path.clone()))?;
700 let parent_metadata =
701 fs::metadata(parent).map_err(|source| FolderbaseError::io(parent, source))?;
702 let current_content = hash_reader(current_file, &materialized_path)?;
703 if current_content != *expected {
704 return Err(FolderbaseError::WorkspaceContentChanged(relative_path));
705 }
706 let captured_current = self.install_content_blob(&materialized_path)?;
707 if captured_current != current_content {
708 return Err(FolderbaseError::WorkspaceContentChanged(relative_path));
709 }
710 let next_content = self.install_content_bytes(new_bytes)?;
711
712 let existing_object = self.find_object_by_path(&relative_path)?;
713 let object_created = existing_object.is_none();
714 let object_id = existing_object
715 .as_ref()
716 .map(|object| object.id.clone())
717 .unwrap_or_else(ObjectId::new);
718 let at = Utc::now().to_rfc3339();
719 let mut pending_versions = Vec::new();
720
721 let previous_version = match existing_object.as_ref() {
722 Some(object) => {
723 let current = self.read_version(&object.current_version)?;
724 if current.content == current_content {
725 current
726 } else {
727 let version = LocalVersionRecord {
728 id: VersionId::new(),
729 object_id: object_id.clone(),
730 content: current_content.clone(),
731 captured_at: at.clone(),
732 extensions: BTreeMap::new(),
733 };
734 pending_versions.push(version.clone());
735 version
736 }
737 }
738 None => {
739 let version = LocalVersionRecord {
740 id: VersionId::new(),
741 object_id: object_id.clone(),
742 content: current_content.clone(),
743 captured_at: at.clone(),
744 extensions: BTreeMap::new(),
745 };
746 pending_versions.push(version.clone());
747 version
748 }
749 };
750
751 let next_version = if next_content == current_content {
752 previous_version.clone()
753 } else {
754 let version = LocalVersionRecord {
755 id: VersionId::new(),
756 object_id: object_id.clone(),
757 content: next_content.clone(),
758 captured_at: at.clone(),
759 extensions: BTreeMap::new(),
760 };
761 pending_versions.push(version.clone());
762 version
763 };
764
765 if pending_versions.is_empty() {
766 return Ok(VersionedReplaceResult {
767 object_id,
768 version_id: next_version.id,
769 previous_content: current_content,
770 content: next_content,
771 });
772 }
773
774 let path_string = relative_path_to_string(&relative_path)?;
775 let mut object = existing_object.unwrap_or_else(|| LocalObjectRecord {
776 schema: OBJECT_SCHEMA.to_owned(),
777 id: object_id.clone(),
778 object_type: "file".to_owned(),
779 path: path_string.clone(),
780 lifecycle: ObjectLifecycle {
781 status: "canonical".to_owned(),
782 extensions: BTreeMap::new(),
783 },
784 provenance: ObjectProvenance {
785 created_at: at.clone(),
786 source: "local".to_owned(),
787 extensions: BTreeMap::new(),
788 },
789 current_version: previous_version.id.clone(),
790 versions: Vec::new(),
791 extensions: BTreeMap::new(),
792 });
793 for version in &pending_versions {
794 if !object.versions.contains(&version.id) {
795 object.versions.push(version.id.clone());
796 }
797 }
798 object.current_version = next_version.id.clone();
799
800 let mut events = Vec::new();
801 if object_created {
802 events.push(ObjectJournalEvent {
803 id: format!("event_{}", Uuid::now_v7()),
804 at: at.clone(),
805 action: JournalAction::ObjectTracked,
806 object_id: object_id.clone(),
807 path: path_string.clone(),
808 previous_path: None,
809 version_id: None,
810 content: None,
811 });
812 }
813 events.extend(pending_versions.iter().map(|version| ObjectJournalEvent {
814 id: format!("event_{}", Uuid::now_v7()),
815 at: at.clone(),
816 action: JournalAction::VersionCaptured,
817 object_id: object_id.clone(),
818 path: path_string.clone(),
819 previous_path: None,
820 version_id: Some(version.id.clone()),
821 content: Some(version.content.clone()),
822 }));
823
824 #[cfg(unix)]
825 let unix_mode = {
826 use std::os::unix::fs::PermissionsExt;
827 Some(metadata.permissions().mode())
828 };
829 #[cfg(not(unix))]
830 let unix_mode = None;
831
832 self.commit_transaction(PendingTransaction {
833 protocol_version: "0.1.0".to_owned(),
834 id: format!("transaction_{}", Uuid::now_v7()),
835 version: None,
836 versions: pending_versions,
837 object,
838 restore: None,
839 replacement: (next_content != current_content).then(|| PendingReplacement {
840 destination: path_string,
841 previous_content: current_content.clone(),
842 content: next_content.clone(),
843 readonly: metadata.permissions().readonly(),
844 unix_mode,
845 file_identity: filesystem_identity(&metadata),
846 parent_identity: filesystem_identity(&parent_metadata),
847 }),
848 events,
849 })?;
850
851 Ok(VersionedReplaceResult {
852 object_id,
853 version_id: next_version.id,
854 previous_content: current_content,
855 content: next_content,
856 })
857 }
858
859 pub fn record_path_change(
864 &self,
865 object_id: &ObjectId,
866 new_relative_path: impl AsRef<Path>,
867 ) -> Result<LocalObjectRecord> {
868 let new_relative_path = safe_content_path(new_relative_path.as_ref())?;
869 let _lock = self.acquire_transaction_lock()?;
870 self.ensure_store_layout()?;
871 let (new_materialized_path, new_relative_path) =
872 resolve_existing_workspace_file(&self.root, &new_relative_path)?;
873
874 let mut object = self.read_object(object_id)?;
875 let new_path = relative_path_to_string(&new_relative_path)?;
876 if object.path == new_path {
877 return Ok(object);
878 }
879
880 let old_relative_path = safe_content_path(Path::new(&object.path))?;
881 match resolve_existing_workspace_file(&self.root, &old_relative_path) {
882 Ok((old_materialized_path, _)) if old_materialized_path != new_materialized_path => {
883 return Err(invalid_record(
884 self.object_record_path(object_id),
885 format!(
886 "tracked path {} still exists; record a path change only after moving it",
887 object.path
888 ),
889 ));
890 }
891 Ok(_) => {}
892 Err(FolderbaseError::Io { source, .. })
893 if source.kind() == std::io::ErrorKind::NotFound => {}
894 Err(error) => return Err(error),
895 }
896
897 let current_version = self.read_version(&object.current_version)?;
898 let expected_identity = self.read_local_file_identity(object_id)?.ok_or_else(|| {
899 invalid_record(
900 self.path_identity_path(object_id),
901 "tracked object has no local file identity; capture it again before relocating",
902 )
903 })?;
904 let destination_file = open_existing_nofollow(&new_materialized_path)?;
905 let destination_metadata = destination_file
906 .metadata()
907 .map_err(|source| FolderbaseError::io(&new_materialized_path, source))?;
908 if filesystem_identity(&destination_metadata).as_ref() != Some(&expected_identity) {
909 return Err(FolderbaseError::WorkspaceContentChanged(new_relative_path));
910 }
911 let current_content = hash_reader(destination_file, &new_materialized_path)?;
912 if current_content != current_version.content {
913 return Err(FolderbaseError::WorkspaceContentChanged(new_relative_path));
914 }
915
916 if let Some(other) = self.find_object_by_path(&new_relative_path)?
917 && other.id != *object_id
918 {
919 return Err(invalid_record(
920 self.object_record_path(&other.id),
921 format!("path {new_path} is already assigned to {}", other.id),
922 ));
923 }
924
925 let previous_path = std::mem::replace(&mut object.path, new_path.clone());
926 self.commit_transaction(PendingTransaction {
927 protocol_version: "0.1.0".to_owned(),
928 id: format!("transaction_{}", Uuid::now_v7()),
929 version: None,
930 versions: Vec::new(),
931 object: object.clone(),
932 restore: None,
933 replacement: None,
934 events: vec![ObjectJournalEvent {
935 id: format!("event_{}", Uuid::now_v7()),
936 at: Utc::now().to_rfc3339(),
937 action: JournalAction::ObjectRelocated,
938 object_id: object_id.clone(),
939 path: new_path,
940 previous_path: Some(previous_path),
941 version_id: Some(object.current_version.clone()),
942 content: None,
943 }],
944 })?;
945 Ok(object)
946 }
947
948 pub fn restore_version(
954 &self,
955 version_id: &VersionId,
956 destination: impl AsRef<Path>,
957 ) -> Result<RestoreResult> {
958 let destination = safe_content_path(destination.as_ref())?;
959 let _lock = self.acquire_transaction_lock()?;
960 self.ensure_store_layout()?;
961 let version = self.read_version(version_id)?;
962 let blob_path = self.blob_path(&version.content.digest);
963 verify_file_content(&blob_path, &version.content)?;
964
965 let (_, destination) = self.prepare_new_destination(&destination)?;
966 let path_string = relative_path_to_string(&destination)?;
967 let object = self.read_object(&version.object_id)?;
968 self.commit_transaction(PendingTransaction {
969 protocol_version: "0.1.0".to_owned(),
970 id: format!("transaction_{}", Uuid::now_v7()),
971 version: None,
972 versions: Vec::new(),
973 object,
974 restore: Some(PendingRestore {
975 version_id: version.id.clone(),
976 destination: path_string.clone(),
977 content: version.content.clone(),
978 }),
979 replacement: None,
980 events: vec![ObjectJournalEvent {
981 id: format!("event_{}", Uuid::now_v7()),
982 at: Utc::now().to_rfc3339(),
983 action: JournalAction::VersionRestored,
984 object_id: version.object_id.clone(),
985 path: path_string,
986 previous_path: None,
987 version_id: Some(version.id.clone()),
988 content: Some(version.content.clone()),
989 }],
990 })?;
991
992 Ok(RestoreResult {
993 object_id: version.object_id,
994 version_id: version.id,
995 path: destination,
996 content: version.content,
997 })
998 }
999
1000 pub fn read_object(&self, object_id: &ObjectId) -> Result<LocalObjectRecord> {
1001 let path = self.object_record_path(object_id);
1002 object_id.validate(&path)?;
1003 self.deny_if_transferred_out(object_id)?;
1004 let record: LocalObjectRecord = read_json(&path)?;
1005 self.validate_object_record(object_id, &record, &path)?;
1006 Ok(record)
1007 }
1008
1009 pub(crate) fn read_capture_object_projection_in(
1010 &self,
1011 state: &FolderbaseState,
1012 object_id: &ObjectId,
1013 ) -> Result<Option<LocalObjectRecord>> {
1014 let path = self.object_record_path(object_id);
1015 object_id.validate(&path)?;
1016 let Some(bytes) = state.read_bounded(
1017 &self.object_record_relative_path(object_id),
1018 MAX_CAPTURE_PROJECTION_RECORD_BYTES,
1019 )?
1020 else {
1021 return Ok(None);
1022 };
1023 let record: LocalObjectRecord = serde_json::from_slice(&bytes)
1024 .map_err(|source| FolderbaseError::json(&path, source))?;
1025 self.validate_object_record(object_id, &record, &path)?;
1026 Ok(Some(record))
1027 }
1028
1029 fn validate_object_record(
1030 &self,
1031 object_id: &ObjectId,
1032 record: &LocalObjectRecord,
1033 path: &Path,
1034 ) -> Result<()> {
1035 let relative_path = self.validate_object_record_membership(object_id, record, path)?;
1036 self.ensure_path_within_current_folderbase_boundary(&relative_path)
1037 }
1038
1039 fn validate_object_record_membership(
1040 &self,
1041 object_id: &ObjectId,
1042 record: &LocalObjectRecord,
1043 path: &Path,
1044 ) -> Result<PathBuf> {
1045 object_id.validate(path)?;
1046 record.id.validate(path)?;
1047 if record.id != *object_id {
1048 return Err(invalid_record(
1049 path.to_path_buf(),
1050 "object ID does not match its filename",
1051 ));
1052 }
1053 let relative_path = safe_content_path(Path::new(&record.path)).map_err(|_| {
1054 invalid_record(
1055 path.to_path_buf(),
1056 "object path is not a safe relative path",
1057 )
1058 })?;
1059 self.ensure_path_within_current_folderbase_boundary(&relative_path)?;
1060 if record.versions.is_empty() || !record.versions.contains(&record.current_version) {
1061 return Err(invalid_record(
1062 path.to_path_buf(),
1063 "current version is absent from the object version history",
1064 ));
1065 }
1066 Ok(relative_path)
1067 }
1068
1069 pub fn read_version(&self, version_id: &VersionId) -> Result<LocalVersionRecord> {
1070 let record = self.read_version_record(version_id)?;
1071 let object = self.read_object(&record.object_id)?;
1072 if !object.versions.contains(version_id) {
1073 return Err(invalid_record(
1074 self.version_record_path(version_id),
1075 "version is absent from its object's version history",
1076 ));
1077 }
1078 Ok(record)
1079 }
1080
1081 pub(crate) fn read_version_record(&self, version_id: &VersionId) -> Result<LocalVersionRecord> {
1082 let path = self.version_record_path(version_id);
1083 version_id.validate(&path)?;
1084 let record: LocalVersionRecord = read_json(&path)?;
1085 self.validate_version_record(version_id, &record, &path)?;
1086 Ok(record)
1087 }
1088
1089 fn validate_version_record(
1090 &self,
1091 version_id: &VersionId,
1092 record: &LocalVersionRecord,
1093 path: &Path,
1094 ) -> Result<()> {
1095 version_id.validate(path)?;
1096 record.id.validate(path)?;
1097 record.object_id.validate(path)?;
1098 if record.id != *version_id {
1099 return Err(invalid_record(
1100 path.to_path_buf(),
1101 "version ID does not match its filename",
1102 ));
1103 }
1104 validate_content_digest(&record.content, path)
1105 }
1106
1107 pub(crate) fn validate_chunk_transfer_membership(
1108 &self,
1109 version_id: &VersionId,
1110 version: &LocalVersionRecord,
1111 object: &LocalObjectRecord,
1112 ) -> Result<PathBuf> {
1113 let version_path = self.version_record_path(version_id);
1114 self.validate_version_record(version_id, version, &version_path)?;
1115 let object_path = self.object_record_path(&version.object_id);
1116 let relative_path =
1117 self.validate_object_record_membership(&version.object_id, object, &object_path)?;
1118 if !object.versions.contains(version_id) {
1119 return Err(invalid_record(
1120 version_path,
1121 "version is absent from its object's version history",
1122 ));
1123 }
1124 Ok(relative_path)
1125 }
1126
1127 pub fn journal_events(&self) -> Result<Vec<ObjectJournalEvent>> {
1133 let _lock = self.acquire_transaction_lock()?;
1134 self.ensure_store_layout()?;
1135 let path = self.root.join(JOURNAL_PATH);
1136 let bytes = match read_optional_file_nofollow(&path)? {
1137 Some(bytes) => bytes,
1138 None => return Ok(Vec::new()),
1139 };
1140 let events = parse_journal_bytes(&path, &bytes, true)?;
1141 let mut checked_objects = std::collections::BTreeSet::new();
1142 for event in &events {
1143 self.ensure_path_within_current_folderbase_boundary(Path::new(&event.path))?;
1144 if let Some(previous_path) = &event.previous_path {
1145 self.ensure_path_within_current_folderbase_boundary(Path::new(previous_path))?;
1146 }
1147 if checked_objects.insert(event.object_id.clone()) {
1148 self.read_object(&event.object_id)?;
1149 }
1150 }
1151 Ok(events)
1152 }
1153
1154 pub(crate) fn ensure_store_layout(&self) -> Result<()> {
1155 for relative in [
1156 OBJECTS_DIRECTORY,
1157 VERSION_RECORDS_DIRECTORY,
1158 BLOBS_DIRECTORY,
1159 ".folderbase/journal",
1160 JOURNAL_QUARANTINE_DIRECTORY,
1161 TRANSACTIONS_DIRECTORY,
1162 LOCKS_DIRECTORY,
1163 PATH_IDENTITIES_DIRECTORY,
1164 ] {
1165 ensure_directory_chain(&self.root, Path::new(relative))?;
1166 }
1167 self.repair_incomplete_journal_tail()?;
1168 self.recover_pending_transactions()?;
1169 Ok(())
1170 }
1171
1172 pub(crate) fn acquire_transaction_lock(&self) -> Result<StoreTransactionLock> {
1173 let state = FolderbaseState::open(&self.root)?;
1174 self.acquire_transaction_lock_in(&state)
1175 }
1176
1177 pub(crate) fn acquire_transaction_lock_in(
1178 &self,
1179 state: &FolderbaseState,
1180 ) -> Result<StoreTransactionLock> {
1181 Self::acquire_transaction_lock_for_state(&self.root, state)
1182 }
1183
1184 pub(crate) fn acquire_transaction_lock_for_state(
1190 display_root: &Path,
1191 state: &FolderbaseState,
1192 ) -> Result<StoreTransactionLock> {
1193 let lock = Self::acquire_transaction_lock_file(display_root, state)?;
1194 if state
1195 .read_bounded_if_present(
1196 Path::new(".folderbase/transactions/protocol-upgrades/active.json"),
1197 16 * 1024 * 1024,
1198 )?
1199 .is_some()
1200 {
1201 return Err(FolderbaseError::ProtocolUpgradeBlocked(
1202 "Folderbase protocol upgrade recovery",
1203 ));
1204 }
1205 Ok(lock)
1206 }
1207
1208 pub(crate) fn acquire_transaction_lock_in_allowing_protocol_upgrade(
1209 &self,
1210 state: &FolderbaseState,
1211 ) -> Result<StoreTransactionLock> {
1212 Self::acquire_transaction_lock_file(&self.root, state)
1213 }
1214
1215 fn acquire_transaction_lock_file(
1216 display_root: &Path,
1217 state: &FolderbaseState,
1218 ) -> Result<StoreTransactionLock> {
1219 state.ensure_private_dir(Path::new(LOCKS_DIRECTORY))?;
1220 let lock_path = display_root.join(TRANSACTION_LOCK_PATH);
1221 match state.publish_new(Path::new(TRANSACTION_LOCK_PATH), b"") {
1222 Ok(()) | Err(FolderbaseError::WouldOverwrite(_)) => {}
1223 Err(error) => return Err(error),
1224 }
1225 let file = state.open_lock_file(Path::new(TRANSACTION_LOCK_PATH))?;
1226 File::lock(&file).map_err(|source| FolderbaseError::io(&lock_path, source))?;
1227 Ok(StoreTransactionLock { file })
1228 }
1229
1230 fn prepare_new_destination(&self, relative_path: &Path) -> Result<(PathBuf, PathBuf)> {
1231 let path = resolve_without_symlinks(&self.root, relative_path, true)?;
1232 let name = relative_path
1233 .file_name()
1234 .ok_or_else(|| FolderbaseError::UnsafePath(relative_path.to_path_buf()))?;
1235 let parent = path
1236 .parent()
1237 .ok_or_else(|| FolderbaseError::UnsafePath(path.clone()))?;
1238 let canonical_parent = parent
1239 .canonicalize()
1240 .map_err(|source| FolderbaseError::io(parent, source))?;
1241 let canonical_relative_parent = canonical_parent
1242 .strip_prefix(&self.root)
1243 .map_err(|_| FolderbaseError::UnsafePath(canonical_parent.clone()))?;
1244 let canonical_relative = safe_content_path(&canonical_relative_parent.join(name))?;
1245 let canonical_path = self.root.join(&canonical_relative);
1246 match fs::symlink_metadata(&canonical_path) {
1247 Ok(_) => Err(FolderbaseError::WouldOverwrite(canonical_path)),
1248 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
1249 Ok((canonical_path, canonical_relative))
1250 }
1251 Err(source) => Err(FolderbaseError::io(canonical_path, source)),
1252 }
1253 }
1254
1255 fn install_content_blob(&self, source: &Path) -> Result<ContentDigest> {
1256 let mut input = open_existing_nofollow(source)?;
1257 let source_before = input
1258 .metadata()
1259 .map_err(|source_error| FolderbaseError::io(source, source_error))?;
1260 let blob_directory = self.root.join(BLOBS_DIRECTORY);
1261 let staged_path = unique_staged_path(&blob_directory, "blob");
1262 let mut staged = open_new(&staged_path)?;
1263 let mut hasher = Sha256::new();
1264 let mut bytes = 0_u64;
1265 let mut buffer = [0_u8; COPY_BUFFER_BYTES];
1266
1267 let copy_result = (|| -> Result<()> {
1268 loop {
1269 let read = input
1270 .read(&mut buffer)
1271 .map_err(|source_error| FolderbaseError::io(source, source_error))?;
1272 if read == 0 {
1273 break;
1274 }
1275 staged
1276 .write_all(&buffer[..read])
1277 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
1278 hasher.update(&buffer[..read]);
1279 bytes = bytes.checked_add(read as u64).ok_or_else(|| {
1280 invalid_record(source, "content length exceeds supported range")
1281 })?;
1282 }
1283 staged
1284 .sync_all()
1285 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
1286 Ok(())
1287 })();
1288 drop(staged);
1289 if let Err(error) = copy_result {
1290 let _ = fs::remove_file(&staged_path);
1291 return Err(error);
1292 }
1293
1294 let source_after_file = match open_existing_nofollow(source) {
1295 Ok(file) => file,
1296 Err(error) => {
1297 let _ = fs::remove_file(&staged_path);
1298 return Err(error);
1299 }
1300 };
1301 let source_after = source_after_file
1302 .metadata()
1303 .map_err(|source_error| FolderbaseError::io(source, source_error))?;
1304 if source_before.len() != source_after.len()
1305 || source_before.modified().ok() != source_after.modified().ok()
1306 || filesystem_identity(&source_before) != filesystem_identity(&source_after)
1307 || source_after.len() != bytes
1308 {
1309 let _ = fs::remove_file(&staged_path);
1310 return Err(invalid_record(
1311 source,
1312 "content changed while the version was being captured",
1313 ));
1314 }
1315
1316 let digest = digest_hex(hasher.finalize().as_slice());
1317 let content = ContentDigest {
1318 algorithm: "sha256".to_owned(),
1319 digest,
1320 bytes,
1321 };
1322 let blob_path = self.blob_path(&content.digest);
1323 match install_no_clobber(&staged_path, &blob_path) {
1324 Ok(()) => sync_parent_directory(&blob_path)?,
1325 Err(source_error) if source_error.kind() == std::io::ErrorKind::AlreadyExists => {
1326 fs::remove_file(&staged_path)
1327 .map_err(|remove_error| FolderbaseError::io(&staged_path, remove_error))?;
1328 verify_file_content(&blob_path, &content)?;
1329 }
1330 Err(source_error) => {
1331 let _ = fs::remove_file(&staged_path);
1332 return Err(FolderbaseError::io(blob_path, source_error));
1333 }
1334 }
1335 Ok(content)
1336 }
1337
1338 pub(crate) fn install_content_reader(
1345 &self,
1346 reader: impl Read,
1347 source_label: &Path,
1348 maximum_bytes: u64,
1349 ) -> Result<ContentDigest> {
1350 let state = FolderbaseState::open(&self.root)?;
1351 self.install_content_reader_in(&state, reader, source_label, maximum_bytes)
1352 }
1353
1354 pub(crate) fn install_content_reader_in(
1355 &self,
1356 state: &FolderbaseState,
1357 reader: impl Read,
1358 source_label: &Path,
1359 maximum_bytes: u64,
1360 ) -> Result<ContentDigest> {
1361 let published = state.publish_reader_sha256(
1362 Path::new(BLOBS_DIRECTORY),
1363 reader,
1364 source_label,
1365 maximum_bytes,
1366 )?;
1367 Ok(ContentDigest {
1368 algorithm: "sha256".to_owned(),
1369 digest: published.digest,
1370 bytes: published.bytes,
1371 })
1372 }
1373
1374 pub(crate) fn install_content_bytes(&self, bytes: &[u8]) -> Result<ContentDigest> {
1375 self.install_content_reader(
1376 std::io::Cursor::new(bytes),
1377 Path::new("in-memory content"),
1378 bytes.len() as u64,
1379 )
1380 }
1381
1382 pub(crate) fn install_content_bytes_in(
1383 &self,
1384 state: &FolderbaseState,
1385 bytes: &[u8],
1386 ) -> Result<ContentDigest> {
1387 self.install_content_reader_in(
1388 state,
1389 std::io::Cursor::new(bytes),
1390 Path::new("in-memory content"),
1391 bytes.len() as u64,
1392 )
1393 }
1394
1395 pub(crate) fn install_or_verify_version_record(
1396 &self,
1397 record: &LocalVersionRecord,
1398 ) -> Result<()> {
1399 let state = FolderbaseState::open(&self.root)?;
1400 self.install_or_verify_version_record_in(&state, record)
1401 }
1402
1403 pub(crate) fn install_or_verify_version_record_in(
1404 &self,
1405 state: &FolderbaseState,
1406 record: &LocalVersionRecord,
1407 ) -> Result<()> {
1408 let path = self.version_record_path(&record.id);
1409 let relative = Path::new(VERSION_RECORDS_DIRECTORY).join(format!("{}.json", record.id));
1410 let encoded = json_bytes(&path, record)?;
1411 match state.publish_new(&relative, &encoded) {
1412 Ok(()) => Ok(()),
1413 Err(FolderbaseError::WouldOverwrite(_)) => {
1414 let existing = state
1415 .read_bounded(&relative, MAX_CAPTURE_PROJECTION_RECORD_BYTES)?
1416 .ok_or_else(|| invalid_record(&path, "immutable version record disappeared"))?;
1417 if existing == encoded {
1418 Ok(())
1419 } else {
1420 Err(invalid_record(
1421 path,
1422 "immutable version record differs from the pending transaction",
1423 ))
1424 }
1425 }
1426 Err(error) => Err(error),
1427 }
1428 }
1429
1430 fn write_object_projection(&self, record: &LocalObjectRecord) -> Result<()> {
1431 let state = FolderbaseState::open(&self.root)?;
1432 self.write_object_projection_in(&state, record)
1433 }
1434
1435 fn write_object_projection_in(
1436 &self,
1437 state: &FolderbaseState,
1438 record: &LocalObjectRecord,
1439 ) -> Result<()> {
1440 let path = self.object_record_path(&record.id);
1441 let encoded = json_bytes(&path, record)?;
1442 state.replace(&self.object_record_relative_path(&record.id), &encoded)
1443 }
1444
1445 pub(crate) fn write_capture_object_projection_in(
1448 &self,
1449 state: &FolderbaseState,
1450 record: &LocalObjectRecord,
1451 ) -> Result<()> {
1452 self.validate_object_record_membership(
1453 &record.id,
1454 record,
1455 &self.object_record_path(&record.id),
1456 )?;
1457 self.write_object_projection_in(state, record)?;
1458 Ok(())
1459 }
1460
1461 pub(crate) fn verify_capture_object_version_in(
1464 &self,
1465 state: &FolderbaseState,
1466 object_id: &ObjectId,
1467 version_id: &VersionId,
1468 expected: &ContentDigest,
1469 ) -> Result<LocalVersionRecord> {
1470 let record = self.read_capture_version_record_in(state, version_id)?;
1471 if record.object_id != *object_id || record.content != *expected {
1472 return Err(invalid_record(
1473 self.version_record_path(version_id),
1474 "Object Version does not match the sealed Folderbase Version reference",
1475 ));
1476 }
1477 state.verify_sha256_blob(
1478 Path::new(BLOBS_DIRECTORY),
1479 &record.content.digest,
1480 record.content.bytes,
1481 )?;
1482 Ok(record)
1483 }
1484
1485 pub(crate) fn verify_capture_version_record_in(
1486 &self,
1487 state: &FolderbaseState,
1488 version_id: &VersionId,
1489 expected: &ContentDigest,
1490 ) -> Result<LocalVersionRecord> {
1491 let record = self.read_capture_version_record_in(state, version_id)?;
1492 if record.content != *expected {
1493 return Err(invalid_record(
1494 self.version_record_path(version_id),
1495 "Object Version bytes do not match the sealed Folderbase Version reference",
1496 ));
1497 }
1498 state.verify_sha256_blob(
1499 Path::new(BLOBS_DIRECTORY),
1500 &record.content.digest,
1501 record.content.bytes,
1502 )?;
1503 Ok(record)
1504 }
1505
1506 pub(crate) fn verify_capture_record_integrity_in(
1507 &self,
1508 state: &FolderbaseState,
1509 object_id: &ObjectId,
1510 version_id: &VersionId,
1511 ) -> Result<LocalVersionRecord> {
1512 let record = self.read_capture_version_record_in(state, version_id)?;
1513 if record.object_id != *object_id {
1514 return Err(invalid_record(
1515 self.version_record_path(version_id),
1516 "Object Version belongs to a different stable Object",
1517 ));
1518 }
1519 state.verify_sha256_blob(
1520 Path::new(BLOBS_DIRECTORY),
1521 &record.content.digest,
1522 record.content.bytes,
1523 )?;
1524 Ok(record)
1525 }
1526
1527 fn read_capture_version_record_in(
1528 &self,
1529 state: &FolderbaseState,
1530 version_id: &VersionId,
1531 ) -> Result<LocalVersionRecord> {
1532 let path = self.version_record_path(version_id);
1533 version_id.validate(&path)?;
1534 let relative = Path::new(VERSION_RECORDS_DIRECTORY).join(format!("{version_id}.json"));
1535 let bytes = state
1536 .read_bounded(&relative, MAX_CAPTURE_PROJECTION_RECORD_BYTES)?
1537 .ok_or_else(|| FolderbaseError::io(&path, std::io::ErrorKind::NotFound.into()))?;
1538 let record: LocalVersionRecord = serde_json::from_slice(&bytes)
1539 .map_err(|source| FolderbaseError::json(&path, source))?;
1540 self.validate_version_record(version_id, &record, &path)?;
1541 Ok(record)
1542 }
1543
1544 fn install_or_verify_restore(&self, restore: &PendingRestore) -> Result<()> {
1545 let destination = safe_content_path(Path::new(&restore.destination))?;
1546 let destination_path = resolve_without_symlinks(&self.root, &destination, true)?;
1547 let blob_path = self.blob_path(&restore.content.digest);
1548 verify_file_content(&blob_path, &restore.content)?;
1549
1550 match fs::symlink_metadata(&destination_path) {
1551 Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
1552 verify_file_content(&destination_path, &restore.content)
1553 }
1554 Ok(_) => Err(FolderbaseError::WouldOverwrite(destination_path)),
1555 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
1556 copy_verified_new(&blob_path, &destination_path, &restore.content)?;
1557 verify_file_content(&destination_path, &restore.content)
1558 }
1559 Err(source) => Err(FolderbaseError::io(destination_path, source)),
1560 }
1561 }
1562
1563 fn install_or_verify_replacement(&self, replacement: &PendingReplacement) -> Result<()> {
1564 let destination = safe_content_path(Path::new(&replacement.destination))?;
1565 let destination_path = resolve_without_symlinks(&self.root, &destination, false)?;
1566 let metadata = fs::symlink_metadata(&destination_path)
1567 .map_err(|source| FolderbaseError::io(&destination_path, source))?;
1568 if !metadata.is_file() || metadata.file_type().is_symlink() {
1569 return Err(FolderbaseError::UnsafePath(destination_path));
1570 }
1571 let parent = destination_path
1572 .parent()
1573 .ok_or_else(|| FolderbaseError::UnsafePath(destination_path.clone()))?;
1574 let parent_metadata =
1575 fs::metadata(parent).map_err(|source| FolderbaseError::io(parent, source))?;
1576 if replacement
1577 .parent_identity
1578 .as_ref()
1579 .is_some_and(|expected| {
1580 filesystem_identity(&parent_metadata).as_ref() != Some(expected)
1581 })
1582 {
1583 return Err(FolderbaseError::WorkspaceContentChanged(destination));
1584 }
1585
1586 let current = hash_reader(
1587 open_existing_nofollow(&destination_path)?,
1588 &destination_path,
1589 )?;
1590 if current == replacement.content {
1591 return Ok(());
1592 }
1593 if current != replacement.previous_content {
1594 return Err(FolderbaseError::WorkspaceContentChanged(destination));
1595 }
1596 if replacement
1597 .file_identity
1598 .as_ref()
1599 .is_some_and(|expected| filesystem_identity(&metadata).as_ref() != Some(expected))
1600 {
1601 return Err(FolderbaseError::WorkspaceContentChanged(destination));
1602 }
1603
1604 let blob_path = self.blob_path(&replacement.content.digest);
1605 verify_file_content(&blob_path, &replacement.content)?;
1606 replace_verified(
1607 &blob_path,
1608 &destination_path,
1609 &replacement.content,
1610 replacement,
1611 )?;
1612 verify_file_content(&destination_path, &replacement.content)
1613 }
1614
1615 fn commit_transaction(&self, transaction: PendingTransaction) -> Result<()> {
1616 validate_pending_transaction(&transaction, Path::new("pending-transaction"))?;
1617 let path = self.pending_transaction_path(&transaction.id);
1618 write_json_new(&path, &transaction)?;
1619 maybe_fail_workspace_checkpoint(&transaction, "intent-durable", &path)?;
1620 self.replay_transaction(&path, &transaction)
1621 }
1622
1623 fn recover_pending_transactions(&self) -> Result<()> {
1624 let directory = self.root.join(TRANSACTIONS_DIRECTORY);
1625 let mut paths = fs::read_dir(&directory)
1626 .map_err(|source| FolderbaseError::io(&directory, source))?
1627 .map(|entry| {
1628 entry
1629 .map(|entry| entry.path())
1630 .map_err(|source| FolderbaseError::io(&directory, source))
1631 })
1632 .collect::<Result<Vec<_>>>()?;
1633 paths.sort();
1634
1635 for path in paths {
1636 let metadata =
1637 fs::symlink_metadata(&path).map_err(|source| FolderbaseError::io(&path, source))?;
1638 if path.extension().and_then(|value| value.to_str()) != Some("json") {
1639 continue;
1640 }
1641 if !metadata.is_file() || metadata.file_type().is_symlink() {
1642 return Err(invalid_record(
1643 path,
1644 "pending transaction is not a regular file",
1645 ));
1646 }
1647 let transaction: PendingTransaction = read_json(&path)?;
1648 validate_pending_transaction(&transaction, &path)?;
1649 if self.pending_transaction_path(&transaction.id) != path {
1650 return Err(invalid_record(
1651 path,
1652 "pending transaction ID does not match its filename",
1653 ));
1654 }
1655 self.replay_transaction(&path, &transaction)?;
1656 }
1657 Ok(())
1658 }
1659
1660 fn replay_transaction(&self, path: &Path, transaction: &PendingTransaction) -> Result<()> {
1661 if transaction.restore.is_none() {
1662 let recorded_path = Path::new(&transaction.object.path);
1663 let (materialized_path, canonical_relative) =
1664 resolve_existing_workspace_file(&self.root, recorded_path)?;
1665 if relative_path_to_string(&canonical_relative)? != transaction.object.path {
1666 return Err(invalid_record(
1667 path,
1668 "pending object path no longer matches the filesystem spelling",
1669 ));
1670 }
1671 if transaction.replacement.is_none() {
1672 let expected_content = match &transaction.version {
1673 Some(version) => version.content.clone(),
1674 None => {
1675 self.read_version(&transaction.object.current_version)?
1676 .content
1677 }
1678 };
1679 let current_content = hash_reader(
1680 open_existing_nofollow(&materialized_path)?,
1681 &materialized_path,
1682 )?;
1683 if current_content != expected_content {
1684 return Err(FolderbaseError::WorkspaceContentChanged(canonical_relative));
1685 }
1686 }
1687 }
1688
1689 if let Some(version) = &transaction.version {
1690 let blob_path = self.blob_path(&version.content.digest);
1691 verify_file_content(&blob_path, &version.content)?;
1692 self.install_or_verify_version_record(version)?;
1693 }
1694 for version in &transaction.versions {
1695 let blob_path = self.blob_path(&version.content.digest);
1696 verify_file_content(&blob_path, &version.content)?;
1697 self.install_or_verify_version_record(version)?;
1698 }
1699 maybe_fail_workspace_checkpoint(transaction, "versions-durable", path)?;
1700 let current = self.read_version_record(&transaction.object.current_version)?;
1701 if current.object_id != transaction.object.id {
1702 return Err(invalid_record(
1703 path,
1704 "pending projection current version belongs to a different object",
1705 ));
1706 }
1707
1708 if let Some(replacement) = &transaction.replacement {
1709 self.install_or_verify_replacement(replacement)?;
1710 maybe_fail_workspace_checkpoint(transaction, "content-replaced", path)?;
1711 self.write_materialized_object_projection(&transaction.object)?;
1712 maybe_fail_workspace_checkpoint(transaction, "projection-durable", path)?;
1713 } else if let Some(restore) = &transaction.restore {
1714 let restored_version = self.read_version(&restore.version_id)?;
1715 if restored_version.object_id != transaction.object.id
1716 || restored_version.content != restore.content
1717 {
1718 return Err(invalid_record(
1719 path,
1720 "pending restore does not match its immutable version",
1721 ));
1722 }
1723 self.install_or_verify_restore(restore)?;
1724 maybe_fail_workspace_checkpoint(transaction, "restore-published", path)?;
1725 } else {
1726 self.write_materialized_object_projection(&transaction.object)?;
1727 }
1728 self.append_journal_events(&transaction.events)?;
1729 maybe_fail_workspace_checkpoint(transaction, "journal-durable", path)?;
1730 fs::remove_file(path).map_err(|source| FolderbaseError::io(path, source))?;
1731 sync_parent_directory(path)
1732 }
1733
1734 fn append_journal_events(&self, events: &[ObjectJournalEvent]) -> Result<()> {
1735 let path = self.root.join(JOURNAL_PATH);
1736 self.repair_incomplete_journal_tail()?;
1737 let existing = match read_optional_file_nofollow(&path)? {
1738 Some(bytes) => parse_journal_bytes(&path, &bytes, false)?,
1739 None => Vec::new(),
1740 };
1741 let mut event_ids = existing
1742 .into_iter()
1743 .map(|event| event.id)
1744 .collect::<std::collections::BTreeSet<_>>();
1745
1746 let mut journal = OpenOptions::new();
1747 journal.create(true).append(true);
1748 #[cfg(unix)]
1749 {
1750 use std::os::unix::fs::OpenOptionsExt;
1751 journal.mode(0o600).custom_flags(libc::O_NOFOLLOW);
1752 }
1753 let mut journal = journal
1754 .open(&path)
1755 .map_err(|source| FolderbaseError::io(&path, source))?;
1756 let mut appended = false;
1757 for event in events {
1758 validate_journal_event(event, &path, 0)?;
1759 if !event_ids.insert(event.id.clone()) {
1760 continue;
1761 }
1762 let mut encoded =
1763 serde_json::to_vec(event).map_err(|source| FolderbaseError::json(&path, source))?;
1764 encoded.push(b'\n');
1765 journal
1766 .write_all(&encoded)
1767 .map_err(|source| FolderbaseError::io(&path, source))?;
1768 appended = true;
1769 }
1770 if appended {
1771 journal
1772 .sync_data()
1773 .map_err(|source| FolderbaseError::io(&path, source))?;
1774 sync_parent_directory(&path)?;
1775 }
1776 Ok(())
1777 }
1778
1779 fn repair_incomplete_journal_tail(&self) -> Result<()> {
1780 let path = self.root.join(JOURNAL_PATH);
1781 let bytes = match read_optional_file_nofollow(&path)? {
1782 Some(bytes) => bytes,
1783 None => return Ok(()),
1784 };
1785 if bytes.is_empty() || bytes.ends_with(b"\n") {
1786 return Ok(());
1787 }
1788
1789 let prefix_length = bytes
1790 .iter()
1791 .rposition(|byte| *byte == b'\n')
1792 .map_or(0, |index| index + 1);
1793 let tail = &bytes[prefix_length..];
1794 match serde_json::from_slice::<ObjectJournalEvent>(tail) {
1795 Ok(event) => {
1796 validate_journal_event(&event, &path, 0)?;
1797 let mut repaired = bytes;
1798 repaired.push(b'\n');
1799 write_bytes_replace(&path, &repaired)
1800 }
1801 Err(_) => {
1802 let quarantine = self
1803 .root
1804 .join(JOURNAL_QUARANTINE_DIRECTORY)
1805 .join(format!("objects-tail-{}.ndjson", Uuid::now_v7()));
1806 write_bytes_new(&quarantine, tail)?;
1807 write_bytes_replace(&path, &bytes[..prefix_length])
1808 }
1809 }
1810 }
1811
1812 fn pending_transaction_path(&self, transaction_id: &str) -> PathBuf {
1813 self.root
1814 .join(TRANSACTIONS_DIRECTORY)
1815 .join(format!("{transaction_id}.json"))
1816 }
1817
1818 fn find_object_by_path(&self, relative_path: &Path) -> Result<Option<LocalObjectRecord>> {
1819 let directory = self.root.join(OBJECTS_DIRECTORY);
1820 let requested_path = relative_path_to_string(relative_path)?;
1821 let entries = match fs::read_dir(&directory) {
1822 Ok(entries) => entries,
1823 Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
1824 Err(source) => return Err(FolderbaseError::io(directory, source)),
1825 };
1826 let mut found = None;
1827 for entry in entries {
1828 let entry = entry.map_err(|source| FolderbaseError::io(&directory, source))?;
1829 let file_type = entry
1830 .file_type()
1831 .map_err(|source| FolderbaseError::io(entry.path(), source))?;
1832 if entry.path().extension().and_then(|value| value.to_str()) != Some("json") {
1833 continue;
1834 }
1835 if !file_type.is_file() || file_type.is_symlink() {
1836 return Err(invalid_record(
1837 entry.path(),
1838 "object record is not a regular file",
1839 ));
1840 }
1841 let mut record: LocalObjectRecord = read_json(&entry.path())?;
1842 record.id.validate(&entry.path())?;
1843 let stored_path = safe_content_path(Path::new(&record.path)).map_err(|_| {
1844 invalid_record(entry.path(), "object path is not a safe relative path")
1845 })?;
1846 let is_match = if stored_path == relative_path {
1847 true
1848 } else {
1849 match resolve_existing_workspace_file(&self.root, &stored_path) {
1850 Ok((_, canonical_path)) => canonical_path == relative_path,
1851 Err(FolderbaseError::Io { source, .. })
1852 if source.kind() == std::io::ErrorKind::NotFound =>
1853 {
1854 if paths_equal_ignoring_ascii_case(&stored_path, relative_path) {
1855 return Err(invalid_record(
1856 entry.path(),
1857 "stored object path alias no longer resolves to its canonical file",
1858 ));
1859 }
1860 false
1861 }
1862 Err(FolderbaseError::UnsafePath(_))
1863 if !paths_equal_ignoring_ascii_case(&stored_path, relative_path) =>
1864 {
1865 false
1866 }
1867 Err(error) => return Err(error),
1868 }
1869 };
1870 if is_match {
1871 self.deny_if_transferred_out(&record.id)?;
1872 if found.is_some() {
1873 return Err(invalid_record(
1874 &directory,
1875 format!("multiple object records claim path {requested_path}"),
1876 ));
1877 }
1878 record.path.clone_from(&requested_path);
1879 found = Some(record);
1880 }
1881 }
1882 Ok(found)
1883 }
1884
1885 fn persist_canonical_object_path(&self, object: &LocalObjectRecord) -> Result<()> {
1886 let persisted = self.read_object(&object.id)?;
1887 if persisted.path == object.path {
1888 return Ok(());
1889 }
1890 let mut expected_persisted = object.clone();
1891 expected_persisted.path.clone_from(&persisted.path);
1892 if persisted != expected_persisted {
1893 return Err(invalid_record(
1894 self.object_record_path(&object.id),
1895 "object record changed while canonicalizing its path",
1896 ));
1897 }
1898
1899 self.commit_transaction(PendingTransaction {
1900 protocol_version: "0.1.0".to_owned(),
1901 id: format!("transaction_{}", Uuid::now_v7()),
1902 version: None,
1903 versions: Vec::new(),
1904 object: object.clone(),
1905 restore: None,
1906 replacement: None,
1907 events: vec![ObjectJournalEvent {
1908 id: format!("event_{}", Uuid::now_v7()),
1909 at: Utc::now().to_rfc3339(),
1910 action: JournalAction::ObjectRelocated,
1911 object_id: object.id.clone(),
1912 path: object.path.clone(),
1913 previous_path: Some(persisted.path),
1914 version_id: Some(object.current_version.clone()),
1915 content: None,
1916 }],
1917 })
1918 }
1919
1920 fn ensure_path_within_current_folderbase_boundary(&self, relative_path: &Path) -> Result<()> {
1921 let mut resolved = self.root.clone();
1922 let mut components = relative_path.components().peekable();
1923 while let Some(component) = components.next() {
1924 let Component::Normal(name) = component else {
1925 return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
1926 };
1927 let requested = resolved.join(name);
1928 let case_folded_child = find_case_folded_child(&resolved, name)?;
1933 let (path, metadata) = match fs::symlink_metadata(&requested) {
1934 Ok(metadata) => (requested, metadata),
1935 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
1936 let Some(alias) = case_folded_child else {
1937 return Ok(());
1938 };
1939 let metadata = fs::symlink_metadata(&alias)
1940 .map_err(|source| FolderbaseError::io(&alias, source))?;
1941 (alias, metadata)
1942 }
1943 Err(source) => return Err(FolderbaseError::io(requested, source)),
1944 };
1945 if metadata.file_type().is_symlink() {
1946 return Err(FolderbaseError::UnsafePath(path));
1947 }
1948 if metadata.is_dir() && has_nested_folderbase_marker(&path)? {
1949 return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
1950 }
1951 if components.peek().is_some() && !metadata.is_dir() {
1952 return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
1953 }
1954 resolved = path;
1955 }
1956 Ok(())
1957 }
1958
1959 fn object_record_path(&self, object_id: &ObjectId) -> PathBuf {
1960 self.root.join(self.object_record_relative_path(object_id))
1961 }
1962
1963 fn path_identity_path(&self, object_id: &ObjectId) -> PathBuf {
1964 self.root
1965 .join(PATH_IDENTITIES_DIRECTORY)
1966 .join(format!("{object_id}.json"))
1967 }
1968
1969 fn write_materialized_object_projection(&self, object: &LocalObjectRecord) -> Result<()> {
1970 self.write_object_projection(object)?;
1971 self.write_local_file_identity(&object.id, &self.root.join(&object.path))
1972 }
1973
1974 fn write_local_file_identity(&self, object_id: &ObjectId, path: &Path) -> Result<()> {
1975 let state = FolderbaseState::open(&self.root)?;
1976 self.write_local_file_identity_in(&state, object_id, path)
1977 }
1978
1979 fn write_local_file_identity_in(
1980 &self,
1981 state: &FolderbaseState,
1982 object_id: &ObjectId,
1983 path: &Path,
1984 ) -> Result<()> {
1985 let file = open_existing_nofollow(path)?;
1986 let metadata = file
1987 .metadata()
1988 .map_err(|source| FolderbaseError::io(path, source))?;
1989 let Some(file_system) = filesystem_identity(&metadata) else {
1990 return Ok(());
1991 };
1992 let path = self.path_identity_path(object_id);
1993 let encoded = json_bytes(
1994 &path,
1995 &LocalPathIdentity {
1996 object_id: object_id.clone(),
1997 file_system,
1998 },
1999 )?;
2000 state.replace(
2001 &Path::new(PATH_IDENTITIES_DIRECTORY).join(format!("{object_id}.json")),
2002 &encoded,
2003 )
2004 }
2005
2006 fn read_local_file_identity(&self, object_id: &ObjectId) -> Result<Option<FileSystemIdentity>> {
2007 let path = self.path_identity_path(object_id);
2008 let Some(bytes) = read_optional_file_nofollow(&path)? else {
2009 return Ok(None);
2010 };
2011 let binding: LocalPathIdentity = serde_json::from_slice(&bytes)
2012 .map_err(|source| FolderbaseError::json(&path, source))?;
2013 if binding.object_id != *object_id {
2014 return Err(invalid_record(
2015 path,
2016 "local path identity belongs to a different object",
2017 ));
2018 }
2019 Ok(Some(binding.file_system))
2020 }
2021
2022 fn version_record_path(&self, version_id: &VersionId) -> PathBuf {
2023 self.root
2024 .join(self.version_record_relative_path(version_id))
2025 }
2026
2027 fn blob_path(&self, digest: &str) -> PathBuf {
2028 self.root.join(self.blob_relative_path(digest))
2029 }
2030
2031 pub(crate) fn version_record_relative_path(&self, version_id: &VersionId) -> PathBuf {
2032 PathBuf::from(VERSION_RECORDS_DIRECTORY).join(format!("{version_id}.json"))
2033 }
2034
2035 pub(crate) fn object_record_relative_path(&self, object_id: &ObjectId) -> PathBuf {
2036 PathBuf::from(OBJECTS_DIRECTORY).join(format!("{object_id}.json"))
2037 }
2038
2039 pub(crate) fn blob_relative_path(&self, digest: &str) -> PathBuf {
2040 PathBuf::from(BLOBS_DIRECTORY).join(digest)
2041 }
2042
2043 fn deny_if_transferred_out(&self, object_id: &ObjectId) -> Result<()> {
2044 let path = outgoing_history_transfer_path(&self.root, object_id);
2045 let Some(bytes) = read_optional_file_nofollow(&path)? else {
2046 return Ok(());
2047 };
2048 validate_chunk_transfer_receipt_bytes(
2049 &bytes,
2050 &path,
2051 object_id,
2052 &read_folderbase_identity(&self.root)?.id,
2053 )
2054 }
2055}
2056
2057impl HistoryTransferPlan {
2058 pub fn reopen(source_root: impl AsRef<Path>, transfer_id: &str) -> Result<Self> {
2059 let source_root = canonical_folderbase_root(source_root.as_ref())?;
2060 load_history_transfer_plan(&source_root, transfer_id)
2061 }
2062}
2063
2064impl HistoryTransferResult {
2065 pub fn recover(source_root: impl AsRef<Path>, transfer_id: &str) -> Result<Self> {
2066 let source_root = canonical_folderbase_root(source_root.as_ref())?;
2067 let plan = load_history_transfer_plan(&source_root, transfer_id)?;
2068 match plan.state {
2069 HistoryTransferState::Approved
2070 | HistoryTransferState::Applying
2071 | HistoryTransferState::DestinationVerified
2072 | HistoryTransferState::SourceReleased => {
2073 replay_history_transfer_with_hook(plan, |_| {})
2074 }
2075 HistoryTransferState::Verified => {
2076 let destination = LocalVersionStore::open(&plan.destination_root)?;
2077 verify_history_transfer_ownership_boundaries(&plan)?;
2078 verify_history_transfer_receipts(&plan)?;
2079 verify_incoming_history(&destination, &plan)?;
2080 cleanup_history_transfer_staging(&destination.root, &plan.id)?;
2081 Ok(history_transfer_result(&plan))
2082 }
2083 HistoryTransferState::Proposed | HistoryTransferState::Conflicted => {
2084 Err(FolderbaseError::InvalidMigrationState {
2085 expected: "approved",
2086 actual: history_transfer_state_name(plan.state).to_owned(),
2087 })
2088 }
2089 }
2090 }
2091}
2092
2093pub fn approve_history_transfer(plan: HistoryTransferPlan) -> Result<ApprovedHistoryTransfer> {
2094 if plan.state != HistoryTransferState::Proposed || plan.approval_digest.is_some() {
2095 return Err(FolderbaseError::InvalidMigrationState {
2096 expected: "proposed",
2097 actual: history_transfer_state_name(plan.state).to_owned(),
2098 });
2099 }
2100 let mut stored = load_history_transfer_plan(&plan.source_root, &plan.id)?;
2101 if stored != plan {
2102 return Err(FolderbaseError::MigrationApprovalMismatch);
2103 }
2104 verify_history_transfer_preconditions(&stored)?;
2105 let approval_digest = history_transfer_digest(&stored)?;
2106 stored.state = HistoryTransferState::Approved;
2107 stored.approval_digest = Some(approval_digest.clone());
2108 persist_history_transfer_plan(&stored)?;
2109 Ok(ApprovedHistoryTransfer {
2110 plan: stored,
2111 approval_digest,
2112 })
2113}
2114
2115pub fn apply_history_transfer(approved: ApprovedHistoryTransfer) -> Result<HistoryTransferResult> {
2116 apply_history_transfer_with_hook(approved, |_| {})
2117}
2118
2119fn apply_history_transfer_with_hook(
2120 approved: ApprovedHistoryTransfer,
2121 checkpoint: impl FnMut(HistoryTransferCheckpoint),
2122) -> Result<HistoryTransferResult> {
2123 if history_transfer_digest(&approved.plan)? != approved.approval_digest {
2124 return Err(FolderbaseError::MigrationApprovalMismatch);
2125 }
2126 let stored = load_history_transfer_plan(&approved.plan.source_root, &approved.plan.id)?;
2127 if stored.state != HistoryTransferState::Approved
2128 || stored.approval_digest.as_deref() != Some(approved.approval_digest.as_str())
2129 || stored != approved.plan
2130 {
2131 return Err(FolderbaseError::MigrationApprovalMismatch);
2132 }
2133 replay_history_transfer_with_hook(stored, checkpoint)
2134}
2135
2136fn replay_history_transfer_with_hook(
2137 mut plan: HistoryTransferPlan,
2138 mut checkpoint: impl FnMut(HistoryTransferCheckpoint),
2139) -> Result<HistoryTransferResult> {
2140 let source = LocalVersionStore::open(&plan.source_root)
2141 .map_err(|error| mark_released_history_transfer_conflicted(&mut plan, error))?;
2142 let destination = LocalVersionStore::open(&plan.destination_root)
2143 .map_err(|error| mark_released_history_transfer_conflicted(&mut plan, error))?;
2144 if plan.state == HistoryTransferState::SourceReleased {
2145 verify_released_history_transfer(&destination, &plan)
2146 .map_err(|error| mark_history_transfer_conflicted(&mut plan, error))?;
2147 } else {
2148 verify_history_transfer_preconditions_for_stores(&source, &destination, &plan)?;
2149 }
2150 let (_first_lock, _second_lock) = if source.root <= destination.root {
2151 (
2152 source.acquire_transaction_lock()?,
2153 destination.acquire_transaction_lock()?,
2154 )
2155 } else {
2156 (
2157 destination.acquire_transaction_lock()?,
2158 source.acquire_transaction_lock()?,
2159 )
2160 };
2161
2162 if plan.state == HistoryTransferState::SourceReleased {
2163 verify_released_history_transfer(&destination, &plan)
2164 .map_err(|error| mark_history_transfer_conflicted(&mut plan, error))?;
2165 } else {
2166 verify_history_transfer_preconditions_for_stores(&source, &destination, &plan)?;
2167 }
2168 if plan.state == HistoryTransferState::Approved {
2169 plan.state = HistoryTransferState::Applying;
2170 persist_history_transfer_plan(&plan)?;
2171 checkpoint(HistoryTransferCheckpoint::Applying);
2172 }
2173 if plan.state == HistoryTransferState::Applying {
2174 stage_history_transfer(&source, &destination, &plan)?;
2175 verify_staged_history(&destination, &plan)?;
2176 checkpoint(HistoryTransferCheckpoint::DestinationStaged);
2177 plan.state = HistoryTransferState::DestinationVerified;
2178 persist_history_transfer_plan(&plan)?;
2179 checkpoint(HistoryTransferCheckpoint::DestinationVerified);
2180 }
2181 if plan.state == HistoryTransferState::DestinationVerified {
2182 let release = (|| -> Result<()> {
2183 verify_staged_history(&destination, &plan)?;
2184 verify_destination_available_for_transfer(&destination, &plan, false)?;
2185 ensure_directory_chain(&source.root, Path::new(HISTORY_TRANSFER_OUTGOING_DIRECTORY))?;
2186 install_or_verify_history_transfer_receipt(
2187 &outgoing_history_transfer_path(&source.root, &plan.object.id),
2188 &history_transfer_receipt(&plan)?,
2189 )
2190 })();
2191 if let Err(error) = release {
2192 return Err(mark_history_transfer_conflicted(&mut plan, error));
2193 }
2194 checkpoint(HistoryTransferCheckpoint::SourceReceiptWritten);
2195 plan.state = HistoryTransferState::SourceReleased;
2196 persist_history_transfer_plan(&plan)?;
2197 checkpoint(HistoryTransferCheckpoint::SourceReleased);
2198 }
2199 if plan.state == HistoryTransferState::SourceReleased {
2200 let activation = (|| -> Result<()> {
2201 verify_history_transfer_ownership_boundaries(&plan)?;
2202 verify_staged_history(&destination, &plan)?;
2203 verify_destination_available_for_transfer(&destination, &plan, true)?;
2204 ensure_directory_chain(
2205 &destination.root,
2206 Path::new(HISTORY_TRANSFER_INCOMING_DIRECTORY),
2207 )?;
2208 install_or_verify_history_transfer_receipt(
2209 &incoming_history_transfer_path(&destination.root, &plan.object.id),
2210 &history_transfer_receipt(&plan)?,
2211 )?;
2212 checkpoint(HistoryTransferCheckpoint::IncomingReceiptWritten);
2213 activate_incoming_history(&destination, &plan)?;
2214 verify_incoming_history(&destination, &plan)
2215 })();
2216 if let Err(error) = activation {
2217 return Err(mark_history_transfer_conflicted(&mut plan, error));
2218 }
2219 checkpoint(HistoryTransferCheckpoint::DestinationActivated);
2220 plan.state = HistoryTransferState::Verified;
2221 persist_history_transfer_plan(&plan)?;
2222 checkpoint(HistoryTransferCheckpoint::Verified);
2223 }
2224 if plan.state != HistoryTransferState::Verified {
2225 return Err(FolderbaseError::InvalidMigrationState {
2226 expected: "verified",
2227 actual: history_transfer_state_name(plan.state).to_owned(),
2228 });
2229 }
2230 verify_history_transfer_ownership_boundaries(&plan)?;
2231 verify_history_transfer_receipts(&plan)?;
2232 verify_incoming_history(&destination, &plan)?;
2233 cleanup_history_transfer_staging(&destination.root, &plan.id)?;
2234 Ok(history_transfer_result(&plan))
2235}
2236
2237fn verify_released_history_transfer(
2238 destination: &LocalVersionStore,
2239 plan: &HistoryTransferPlan,
2240) -> Result<()> {
2241 verify_history_transfer_ownership_boundaries(plan)?;
2242 verify_staged_history(destination, plan)
2243}
2244
2245fn stage_history_transfer(
2246 source: &LocalVersionStore,
2247 destination: &LocalVersionStore,
2248 plan: &HistoryTransferPlan,
2249) -> Result<()> {
2250 let staging = history_transfer_staging_root(&destination.root, &plan.id);
2251 ensure_directory_chain(
2252 &destination.root,
2253 &PathBuf::from(HISTORY_TRANSFER_STAGING_DIRECTORY)
2254 .join(&plan.id)
2255 .join("objects"),
2256 )?;
2257 ensure_directory_chain(
2258 &destination.root,
2259 &PathBuf::from(HISTORY_TRANSFER_STAGING_DIRECTORY)
2260 .join(&plan.id)
2261 .join("versions/records"),
2262 )?;
2263 ensure_directory_chain(
2264 &destination.root,
2265 &PathBuf::from(HISTORY_TRANSFER_STAGING_DIRECTORY)
2266 .join(&plan.id)
2267 .join("versions/blobs/sha256"),
2268 )?;
2269 for version in &plan.versions {
2270 install_or_verify_content_file(
2271 &source.blob_path(&version.content.digest),
2272 &staging
2273 .join("versions/blobs/sha256")
2274 .join(&version.content.digest),
2275 &version.content,
2276 )?;
2277 install_or_verify_json(
2278 &staging
2279 .join("versions/records")
2280 .join(format!("{}.json", version.id)),
2281 version,
2282 )?;
2283 }
2284 let mut object = plan.object.clone();
2285 object.path.clone_from(&plan.destination_path);
2286 install_or_verify_json(
2287 &staging.join("objects").join(format!("{}.json", object.id)),
2288 &object,
2289 )
2290}
2291
2292fn verify_staged_history(
2293 destination: &LocalVersionStore,
2294 plan: &HistoryTransferPlan,
2295) -> Result<()> {
2296 let staging = history_transfer_staging_root(&destination.root, &plan.id);
2297 for version in &plan.versions {
2298 let path = staging
2299 .join("versions/records")
2300 .join(format!("{}.json", version.id));
2301 let installed: LocalVersionRecord = read_json(&path)?;
2302 if installed != *version {
2303 return Err(invalid_record(path, "staged version record changed"));
2304 }
2305 verify_file_content(
2306 &staging
2307 .join("versions/blobs/sha256")
2308 .join(&version.content.digest),
2309 &version.content,
2310 )?;
2311 }
2312 let mut expected = plan.object.clone();
2313 expected.path.clone_from(&plan.destination_path);
2314 let path = staging
2315 .join("objects")
2316 .join(format!("{}.json", expected.id));
2317 let installed: LocalObjectRecord = read_json(&path)?;
2318 if installed != expected {
2319 return Err(invalid_record(path, "staged object projection changed"));
2320 }
2321 Ok(())
2322}
2323
2324fn activate_incoming_history(
2325 destination: &LocalVersionStore,
2326 plan: &HistoryTransferPlan,
2327) -> Result<()> {
2328 destination.ensure_store_layout()?;
2329 let staging = history_transfer_staging_root(&destination.root, &plan.id);
2330 for version in &plan.versions {
2331 install_or_verify_content_file(
2332 &staging
2333 .join("versions/blobs/sha256")
2334 .join(&version.content.digest),
2335 &destination.blob_path(&version.content.digest),
2336 &version.content,
2337 )?;
2338 destination.install_or_verify_version_record(version)?;
2339 }
2340 let object = expected_history_transfer_object(plan);
2341 let object_path = destination.object_record_path(&object.id);
2342 match read_optional_file_nofollow(&object_path)? {
2343 Some(_) => {
2344 let installed: LocalObjectRecord = read_json(&object_path)?;
2345 verify_object_preserves_transferred_history(&installed, plan, &object_path)?;
2346 }
2347 None => install_or_verify_json(&object_path, &object)?,
2348 }
2349 destination.write_local_file_identity(&object.id, &destination.root.join(&object.path))
2350}
2351
2352fn verify_incoming_history(
2353 destination: &LocalVersionStore,
2354 plan: &HistoryTransferPlan,
2355) -> Result<()> {
2356 let object = destination.read_object(&plan.object.id)?;
2357 verify_object_preserves_transferred_history(
2358 &object,
2359 plan,
2360 &destination.object_record_path(&plan.object.id),
2361 )?;
2362 for version in &plan.versions {
2363 if destination.read_version(&version.id)? != *version {
2364 return Err(invalid_record(
2365 destination.version_record_path(&version.id),
2366 "incoming version does not match the approved transfer",
2367 ));
2368 }
2369 verify_file_content(
2370 &destination.blob_path(&version.content.digest),
2371 &version.content,
2372 )?;
2373 }
2374 Ok(())
2375}
2376
2377fn expected_history_transfer_object(plan: &HistoryTransferPlan) -> LocalObjectRecord {
2378 let mut expected = plan.object.clone();
2379 expected.path.clone_from(&plan.destination_path);
2380 expected
2381}
2382
2383fn verify_object_preserves_transferred_history(
2384 object: &LocalObjectRecord,
2385 plan: &HistoryTransferPlan,
2386 path: &Path,
2387) -> Result<()> {
2388 if object.id != plan.object.id
2389 || object.path != plan.destination_path
2390 || !object.versions.starts_with(&plan.object.versions)
2391 || !object.versions.contains(&object.current_version)
2392 {
2393 return Err(invalid_record(
2394 path,
2395 "incoming object no longer preserves the approved transferred history",
2396 ));
2397 }
2398 Ok(())
2399}
2400
2401fn verify_destination_available_for_transfer(
2402 destination: &LocalVersionStore,
2403 plan: &HistoryTransferPlan,
2404 allow_activated_replay: bool,
2405) -> Result<()> {
2406 let object_path = destination.object_record_path(&plan.object.id);
2407 if read_optional_file_nofollow(&object_path)?.is_some() {
2408 if !allow_activated_replay {
2409 return Err(FolderbaseError::WouldOverwrite(object_path));
2410 }
2411 let object: LocalObjectRecord = read_json(&object_path)?;
2412 verify_object_preserves_transferred_history(&object, plan, &object_path)?;
2413 }
2414
2415 if let Some(claimant) = destination.find_object_by_path(Path::new(&plan.destination_path))? {
2416 if !allow_activated_replay || claimant.id != plan.object.id {
2417 return Err(FolderbaseError::WouldOverwrite(
2418 destination.object_record_path(&claimant.id),
2419 ));
2420 }
2421 verify_object_preserves_transferred_history(
2422 &claimant,
2423 plan,
2424 &destination.object_record_path(&claimant.id),
2425 )?;
2426 }
2427
2428 for version in &plan.versions {
2429 let version_path = destination.version_record_path(&version.id);
2430 if read_optional_file_nofollow(&version_path)?.is_some()
2431 && destination.read_version_record(&version.id)? != *version
2432 {
2433 return Err(FolderbaseError::WouldOverwrite(version_path));
2434 }
2435 let blob_path = destination.blob_path(&version.content.digest);
2436 if read_optional_file_nofollow(&blob_path)?.is_some() {
2437 verify_file_content(&blob_path, &version.content)?;
2438 }
2439 }
2440 Ok(())
2441}
2442
2443fn verify_history_transfer_preconditions(plan: &HistoryTransferPlan) -> Result<()> {
2444 let source = LocalVersionStore::open(&plan.source_root)?;
2445 let destination = LocalVersionStore::open(&plan.destination_root)?;
2446 verify_history_transfer_preconditions_for_stores(&source, &destination, plan)
2447}
2448
2449fn verify_history_transfer_preconditions_for_stores(
2450 source: &LocalVersionStore,
2451 destination: &LocalVersionStore,
2452 plan: &HistoryTransferPlan,
2453) -> Result<()> {
2454 verify_history_transfer_boundary_preconditions(plan)?;
2455 let source_identity = read_folderbase_identity(&source.root)?;
2456 let destination_identity = read_folderbase_identity(&destination.root)?;
2457 if source_identity.id != plan.source_folderbase_id
2458 || destination_identity.id != plan.destination_folderbase_id
2459 || source_identity.manifest_sha256 != plan.source_manifest_sha256
2460 || destination_identity.manifest_sha256 != plan.destination_manifest_sha256
2461 {
2462 return Err(FolderbaseError::PlanPreconditionChanged(
2463 plan.source_root.clone(),
2464 ));
2465 }
2466 if !has_nested_folderbase_marker(&destination.root)? {
2467 return Err(FolderbaseError::UnsafePath(destination.root.clone()));
2468 }
2469 let object = source.read_object_record_for_transfer(&plan.object.id)?;
2470 if object != plan.object {
2471 return Err(FolderbaseError::PlanPreconditionChanged(
2472 source.object_record_path(&plan.object.id),
2473 ));
2474 }
2475 for expected in &plan.versions {
2476 let version = source.read_version_record(&expected.id)?;
2477 if version != *expected {
2478 return Err(FolderbaseError::PlanPreconditionChanged(
2479 source.version_record_path(&expected.id),
2480 ));
2481 }
2482 verify_file_content(
2483 &source.blob_path(&expected.content.digest),
2484 &expected.content,
2485 )?;
2486 }
2487 let current = plan
2488 .versions
2489 .iter()
2490 .find(|version| version.id == plan.object.current_version)
2491 .ok_or_else(|| {
2492 invalid_record(
2493 source.object_record_path(&plan.object.id),
2494 "current version is absent from approved history",
2495 )
2496 })?;
2497 let (materialized, canonical_path) =
2498 resolve_existing_workspace_file(&destination.root, Path::new(&plan.destination_path))?;
2499 if canonical_path != Path::new(&plan.destination_path) {
2500 return Err(FolderbaseError::UnsafePath(canonical_path));
2501 }
2502 verify_file_content(&materialized, ¤t.content)
2503}
2504
2505fn verify_history_transfer_boundary_preconditions(plan: &HistoryTransferPlan) -> Result<()> {
2506 verify_history_transfer_ownership_boundaries(plan)?;
2507 let source_identity = read_folderbase_identity(&plan.source_root)?;
2508 let destination_identity = read_folderbase_identity(&plan.destination_root)?;
2509 if source_identity.manifest_sha256 != plan.source_manifest_sha256
2510 || destination_identity.manifest_sha256 != plan.destination_manifest_sha256
2511 {
2512 return Err(FolderbaseError::PlanPreconditionChanged(
2513 plan.source_root.clone(),
2514 ));
2515 }
2516 let current = plan
2517 .versions
2518 .iter()
2519 .find(|version| version.id == plan.object.current_version)
2520 .ok_or_else(|| {
2521 invalid_record(
2522 history_transfer_plan_path(&plan.source_root, &plan.id),
2523 "current version is absent from approved history",
2524 )
2525 })?;
2526 let (materialized, canonical_path) =
2527 resolve_existing_workspace_file(&plan.destination_root, Path::new(&plan.destination_path))?;
2528 if canonical_path != Path::new(&plan.destination_path) {
2529 return Err(FolderbaseError::UnsafePath(canonical_path));
2530 }
2531 verify_file_content(&materialized, ¤t.content)
2532}
2533
2534fn verify_history_transfer_ownership_boundaries(plan: &HistoryTransferPlan) -> Result<()> {
2535 validate_history_transfer_plan(
2536 plan,
2537 &history_transfer_plan_path(&plan.source_root, &plan.id),
2538 )?;
2539 let source_identity = read_folderbase_identity(&plan.source_root)?;
2540 let destination_identity = read_folderbase_identity(&plan.destination_root)?;
2541 if source_identity.id != plan.source_folderbase_id
2542 || destination_identity.id != plan.destination_folderbase_id
2543 {
2544 return Err(FolderbaseError::PlanPreconditionChanged(
2545 plan.source_root.clone(),
2546 ));
2547 }
2548 if !has_nested_folderbase_marker(&plan.destination_root)? {
2549 return Err(FolderbaseError::UnsafePath(plan.destination_root.clone()));
2550 }
2551 let nested_root = plan
2552 .destination_root
2553 .strip_prefix(&plan.source_root)
2554 .map_err(|_| FolderbaseError::UnsafePath(plan.destination_root.clone()))?;
2555 if Path::new(&plan.object.path)
2556 != safe_content_path(nested_root)?.join(Path::new(&plan.destination_path))
2557 {
2558 return Err(invalid_record(
2559 history_transfer_plan_path(&plan.source_root, &plan.id),
2560 "approved source and destination paths no longer map to one materialized object",
2561 ));
2562 }
2563 Ok(())
2564}
2565
2566fn verify_history_transfer_receipts(plan: &HistoryTransferPlan) -> Result<()> {
2567 let expected = history_transfer_receipt(plan)?;
2568 for path in [
2569 outgoing_history_transfer_path(&plan.source_root, &plan.object.id),
2570 incoming_history_transfer_path(&plan.destination_root, &plan.object.id),
2571 ] {
2572 let installed: HistoryTransferReceipt = read_json(&path)?;
2573 validate_history_transfer_receipt(&installed, &path)?;
2574 if installed != expected {
2575 return Err(invalid_record(
2576 path,
2577 "history-transfer receipt does not match the approved transfer",
2578 ));
2579 }
2580 }
2581 Ok(())
2582}
2583
2584fn load_history_transfer_plan(root: &Path, transfer_id: &str) -> Result<HistoryTransferPlan> {
2585 validate_prefixed_uuid(transfer_id, "history_transfer_", root)?;
2586 let path = history_transfer_plan_path(root, transfer_id);
2587 let plan: HistoryTransferPlan = read_json(&path)?;
2588 validate_history_transfer_plan(&plan, &path)?;
2589 if plan.id != transfer_id || plan.source_root != root {
2590 return Err(invalid_record(
2591 path,
2592 "history-transfer plan ID or source root is inconsistent",
2593 ));
2594 }
2595 Ok(plan)
2596}
2597
2598fn validate_history_transfer_plan(plan: &HistoryTransferPlan, path: &Path) -> Result<()> {
2599 if plan.protocol_version != "0.1.0"
2600 || plan.source_root == plan.destination_root
2601 || plan
2602 .destination_root
2603 .strip_prefix(&plan.source_root)
2604 .is_err()
2605 || plan.object.versions.is_empty()
2606 || plan.object.versions.len() != plan.versions.len()
2607 || plan
2608 .object
2609 .versions
2610 .iter()
2611 .zip(&plan.versions)
2612 .any(|(id, version)| id != &version.id || version.object_id != plan.object.id)
2613 || !plan.object.versions.contains(&plan.object.current_version)
2614 || safe_content_path(Path::new(&plan.destination_path)).is_err()
2615 {
2616 return Err(invalid_record(
2617 path,
2618 "history-transfer plan metadata is inconsistent",
2619 ));
2620 }
2621 validate_prefixed_uuid(&plan.id, "history_transfer_", path)?;
2622 validate_prefixed_uuid(&plan.source_folderbase_id, "folderbase_", path)?;
2623 validate_prefixed_uuid(&plan.destination_folderbase_id, "folderbase_", path)?;
2624 let approval_is_consistent = match plan.state {
2625 HistoryTransferState::Proposed => plan.approval_digest.is_none(),
2626 HistoryTransferState::Approved
2627 | HistoryTransferState::Applying
2628 | HistoryTransferState::DestinationVerified
2629 | HistoryTransferState::SourceReleased
2630 | HistoryTransferState::Verified
2631 | HistoryTransferState::Conflicted => plan.approval_digest.is_some(),
2632 };
2633 if !approval_is_consistent {
2634 return Err(invalid_record(
2635 path,
2636 "history-transfer approval metadata is inconsistent with its state",
2637 ));
2638 }
2639 if let Some(approval_digest) = &plan.approval_digest
2640 && history_transfer_digest(plan)? != *approval_digest
2641 {
2642 return Err(FolderbaseError::MigrationApprovalMismatch);
2643 }
2644 Ok(())
2645}
2646
2647fn history_transfer_digest(plan: &HistoryTransferPlan) -> Result<String> {
2648 let bytes = serde_json::to_vec(&(
2649 &plan.protocol_version,
2650 &plan.id,
2651 &plan.source_root,
2652 &plan.destination_root,
2653 &plan.source_folderbase_id,
2654 &plan.destination_folderbase_id,
2655 &plan.source_manifest_sha256,
2656 &plan.destination_manifest_sha256,
2657 &plan.object,
2658 &plan.destination_path,
2659 &plan.versions,
2660 HistoryTransferState::Approved,
2661 ))
2662 .map_err(|source| FolderbaseError::json(&plan.source_root, source))?;
2663 Ok(digest_hex(Sha256::digest(&bytes).as_slice()))
2664}
2665
2666fn persist_history_transfer_plan(plan: &HistoryTransferPlan) -> Result<()> {
2667 write_json_replace(
2668 &history_transfer_plan_path(&plan.source_root, &plan.id),
2669 plan,
2670 )
2671}
2672
2673fn history_transfer_receipt(plan: &HistoryTransferPlan) -> Result<HistoryTransferReceipt> {
2674 Ok(HistoryTransferReceipt {
2675 protocol_version: "0.1.0".to_owned(),
2676 transfer_id: plan.id.clone(),
2677 source_folderbase_id: plan.source_folderbase_id.clone(),
2678 destination_folderbase_id: plan.destination_folderbase_id.clone(),
2679 object_id: plan.object.id.clone(),
2680 approval_digest: plan
2681 .approval_digest
2682 .clone()
2683 .ok_or(FolderbaseError::MigrationApprovalMismatch)?,
2684 version_ids: plan.object.versions.clone(),
2685 })
2686}
2687
2688fn validate_history_transfer_receipt(receipt: &HistoryTransferReceipt, path: &Path) -> Result<()> {
2689 if receipt.protocol_version != "0.1.0" || receipt.version_ids.is_empty() {
2690 return Err(invalid_record(
2691 path,
2692 "history-transfer receipt metadata is inconsistent",
2693 ));
2694 }
2695 validate_prefixed_uuid(&receipt.transfer_id, "history_transfer_", path)?;
2696 validate_prefixed_uuid(&receipt.source_folderbase_id, "folderbase_", path)?;
2697 validate_prefixed_uuid(&receipt.destination_folderbase_id, "folderbase_", path)?;
2698 receipt.object_id.validate(path)?;
2699 for version_id in &receipt.version_ids {
2700 version_id.validate(path)?;
2701 }
2702 Ok(())
2703}
2704
2705fn install_or_verify_history_transfer_receipt(
2706 path: &Path,
2707 receipt: &HistoryTransferReceipt,
2708) -> Result<()> {
2709 validate_history_transfer_receipt(receipt, path)?;
2710 install_or_verify_json(path, receipt)
2711}
2712
2713fn install_or_verify_content_file(
2714 source: &Path,
2715 destination: &Path,
2716 expected: &ContentDigest,
2717) -> Result<()> {
2718 match read_optional_file_nofollow(destination)? {
2719 Some(_) => verify_file_content(destination, expected),
2720 None => copy_verified_new(source, destination, expected),
2721 }
2722}
2723
2724fn install_or_verify_json(path: &Path, value: &impl Serialize) -> Result<()> {
2725 let expected = json_bytes(path, value)?;
2726 match read_optional_file_nofollow(path)? {
2727 Some(existing) if existing == expected => Ok(()),
2728 Some(_) => Err(FolderbaseError::WouldOverwrite(path.to_path_buf())),
2729 None => write_bytes_new(path, &expected),
2730 }
2731}
2732
2733fn history_transfer_result(plan: &HistoryTransferPlan) -> HistoryTransferResult {
2734 HistoryTransferResult {
2735 transfer_id: plan.id.clone(),
2736 source_folderbase_id: plan.source_folderbase_id.clone(),
2737 destination_folderbase_id: plan.destination_folderbase_id.clone(),
2738 object_id: plan.object.id.clone(),
2739 state: plan.state,
2740 version_ids: plan.object.versions.clone(),
2741 }
2742}
2743
2744fn history_transfer_state_name(state: HistoryTransferState) -> &'static str {
2745 match state {
2746 HistoryTransferState::Proposed => "proposed",
2747 HistoryTransferState::Approved => "approved",
2748 HistoryTransferState::Applying => "applying",
2749 HistoryTransferState::DestinationVerified => "destination_verified",
2750 HistoryTransferState::SourceReleased => "source_released",
2751 HistoryTransferState::Verified => "verified",
2752 HistoryTransferState::Conflicted => "conflicted",
2753 }
2754}
2755
2756fn history_transfer_staging_root(root: &Path, transfer_id: &str) -> PathBuf {
2757 root.join(HISTORY_TRANSFER_STAGING_DIRECTORY)
2758 .join(transfer_id)
2759}
2760
2761fn outgoing_history_transfer_path(root: &Path, object_id: &ObjectId) -> PathBuf {
2762 root.join(HISTORY_TRANSFER_OUTGOING_DIRECTORY)
2763 .join(format!("{object_id}.json"))
2764}
2765
2766fn incoming_history_transfer_path(root: &Path, object_id: &ObjectId) -> PathBuf {
2767 root.join(HISTORY_TRANSFER_INCOMING_DIRECTORY)
2768 .join(format!("{object_id}.json"))
2769}
2770
2771fn cleanup_history_transfer_staging(root: &Path, transfer_id: &str) -> Result<()> {
2772 let staging = history_transfer_staging_root(root, transfer_id);
2773 match fs::remove_dir_all(&staging) {
2774 Ok(()) => sync_parent_directory(&staging),
2775 Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(()),
2776 Err(source) => Err(FolderbaseError::io(staging, source)),
2777 }
2778}
2779
2780fn mark_history_transfer_conflicted(
2781 plan: &mut HistoryTransferPlan,
2782 error: FolderbaseError,
2783) -> FolderbaseError {
2784 plan.state = HistoryTransferState::Conflicted;
2785 match persist_history_transfer_plan(plan) {
2786 Ok(()) => error,
2787 Err(persistence_error) => persistence_error,
2788 }
2789}
2790
2791fn mark_released_history_transfer_conflicted(
2792 plan: &mut HistoryTransferPlan,
2793 error: FolderbaseError,
2794) -> FolderbaseError {
2795 if plan.state == HistoryTransferState::SourceReleased {
2796 mark_history_transfer_conflicted(plan, error)
2797 } else {
2798 error
2799 }
2800}
2801
2802fn validate_pending_transaction(transaction: &PendingTransaction, path: &Path) -> Result<()> {
2803 if transaction.protocol_version != "0.1.0"
2804 || !transaction.id.starts_with("transaction_")
2805 || Uuid::parse_str(
2806 transaction
2807 .id
2808 .strip_prefix("transaction_")
2809 .unwrap_or_default(),
2810 )
2811 .is_err()
2812 || transaction.events.is_empty()
2813 {
2814 return Err(invalid_record(
2815 path,
2816 "pending transaction has an invalid protocol version, ID, or empty event list",
2817 ));
2818 }
2819
2820 transaction.object.id.validate(path)?;
2821 safe_content_path(Path::new(&transaction.object.path))
2822 .map_err(|_| invalid_record(path, "pending transaction has an unsafe object path"))?;
2823 if transaction.object.versions.is_empty()
2824 || !transaction
2825 .object
2826 .versions
2827 .contains(&transaction.object.current_version)
2828 {
2829 return Err(invalid_record(
2830 path,
2831 "pending transaction projection has an invalid version history",
2832 ));
2833 }
2834
2835 if let Some(version) = &transaction.version {
2836 version.id.validate(path)?;
2837 version.object_id.validate(path)?;
2838 validate_content_digest(&version.content, path)?;
2839 if version.object_id != transaction.object.id
2840 || version.id != transaction.object.current_version
2841 || !transaction.object.versions.contains(&version.id)
2842 {
2843 return Err(invalid_record(
2844 path,
2845 "pending version does not match the object projection",
2846 ));
2847 }
2848 }
2849
2850 for version in &transaction.versions {
2851 version.id.validate(path)?;
2852 version.object_id.validate(path)?;
2853 validate_content_digest(&version.content, path)?;
2854 if version.object_id != transaction.object.id
2855 || !transaction.object.versions.contains(&version.id)
2856 {
2857 return Err(invalid_record(
2858 path,
2859 "pending version does not match the object projection",
2860 ));
2861 }
2862 }
2863
2864 if let Some(replacement) = &transaction.replacement {
2865 validate_content_digest(&replacement.previous_content, path)?;
2866 validate_content_digest(&replacement.content, path)?;
2867 safe_content_path(Path::new(&replacement.destination))
2868 .map_err(|_| invalid_record(path, "pending replacement has an unsafe destination"))?;
2869 let current = transaction
2870 .versions
2871 .iter()
2872 .chain(transaction.version.iter())
2873 .find(|version| version.id == transaction.object.current_version);
2874 if transaction.restore.is_some()
2875 || replacement.destination != transaction.object.path
2876 || replacement.previous_content == replacement.content
2877 || current.map(|version| &version.content) != Some(&replacement.content)
2878 {
2879 return Err(invalid_record(
2880 path,
2881 "pending replacement does not match the object projection",
2882 ));
2883 }
2884 }
2885
2886 if let Some(restore) = &transaction.restore {
2887 restore.version_id.validate(path)?;
2888 validate_content_digest(&restore.content, path)?;
2889 safe_content_path(Path::new(&restore.destination))
2890 .map_err(|_| invalid_record(path, "pending restore has an unsafe destination"))?;
2891 if transaction.version.is_some()
2892 || !transaction.versions.is_empty()
2893 || transaction.replacement.is_some()
2894 || transaction.events.len() != 1
2895 {
2896 return Err(invalid_record(
2897 path,
2898 "pending restore must contain one restore event and no new version",
2899 ));
2900 }
2901 let event = &transaction.events[0];
2902 if event.action != JournalAction::VersionRestored
2903 || event.version_id.as_ref() != Some(&restore.version_id)
2904 || event.content.as_ref() != Some(&restore.content)
2905 || event.path != restore.destination
2906 || event.previous_path.is_some()
2907 {
2908 return Err(invalid_record(
2909 path,
2910 "pending restore does not match its restore event",
2911 ));
2912 }
2913 }
2914
2915 for event in &transaction.events {
2916 validate_journal_event(event, path, 0)?;
2917 if event.object_id != transaction.object.id {
2918 return Err(invalid_record(
2919 path,
2920 "pending journal event belongs to a different object",
2921 ));
2922 }
2923 }
2924 Ok(())
2925}
2926
2927fn maybe_fail_workspace_checkpoint(
2928 transaction: &PendingTransaction,
2929 checkpoint: &str,
2930 _path: &Path,
2931) -> Result<()> {
2932 let applies_to_workspace_save = transaction.replacement.is_some();
2933 let applies_to_restore = transaction.restore.is_some() && checkpoint == "restore-published";
2934 if !applies_to_workspace_save && !applies_to_restore {
2935 return Ok(());
2936 }
2937 #[cfg(debug_assertions)]
2938 if std::env::var("FOLDERBASE_TEST_FAIL_AFTER_WORKSPACE_CHECKPOINT").as_deref() == Ok(checkpoint)
2939 {
2940 return Err(FolderbaseError::io(
2941 _path,
2942 std::io::Error::new(
2943 std::io::ErrorKind::Interrupted,
2944 format!("simulated interruption after {checkpoint}"),
2945 ),
2946 ));
2947 }
2948 Ok(())
2949}
2950
2951fn parse_journal_bytes(
2952 path: &Path,
2953 bytes: &[u8],
2954 tolerate_incomplete_tail: bool,
2955) -> Result<Vec<ObjectJournalEvent>> {
2956 let mut events = Vec::new();
2957 let mut start = 0;
2958 let mut line_number = 1;
2959
2960 for (index, byte) in bytes.iter().enumerate() {
2961 if *byte != b'\n' {
2962 continue;
2963 }
2964 let line = &bytes[start..index];
2965 if line.is_empty() {
2966 return Err(invalid_record(
2967 path,
2968 format!("journal line {line_number} is empty"),
2969 ));
2970 }
2971 let event: ObjectJournalEvent =
2972 serde_json::from_slice(line).map_err(|source| FolderbaseError::Json {
2973 path: path.to_path_buf(),
2974 source,
2975 })?;
2976 validate_journal_event(&event, path, line_number)?;
2977 events.push(event);
2978 start = index + 1;
2979 line_number += 1;
2980 }
2981
2982 if start < bytes.len() {
2983 match serde_json::from_slice::<ObjectJournalEvent>(&bytes[start..]) {
2984 Ok(event) => {
2985 validate_journal_event(&event, path, line_number)?;
2986 events.push(event);
2987 }
2988 Err(_) if tolerate_incomplete_tail => {}
2989 Err(source) => {
2990 return Err(FolderbaseError::Json {
2991 path: path.to_path_buf(),
2992 source,
2993 });
2994 }
2995 }
2996 }
2997 Ok(events)
2998}
2999
3000fn validate_journal_event(event: &ObjectJournalEvent, path: &Path, line: usize) -> Result<()> {
3001 if !event.id.starts_with("event_")
3002 || Uuid::parse_str(event.id.strip_prefix("event_").unwrap_or_default()).is_err()
3003 {
3004 return Err(invalid_record(
3005 path,
3006 journal_message(line, "has an invalid event ID"),
3007 ));
3008 }
3009 event.object_id.validate(path)?;
3010 if let Some(version_id) = &event.version_id {
3011 version_id.validate(path)?;
3012 }
3013 safe_content_path(Path::new(&event.path))
3014 .map_err(|_| invalid_record(path, journal_message(line, "has an unsafe content path")))?;
3015 if let Some(previous_path) = &event.previous_path {
3016 safe_content_path(Path::new(previous_path)).map_err(|_| {
3017 invalid_record(path, journal_message(line, "has an unsafe previous path"))
3018 })?;
3019 }
3020 if let Some(content) = &event.content {
3021 validate_content_digest(content, path)?;
3022 }
3023 Ok(())
3024}
3025
3026fn journal_message(line: usize, message: &str) -> String {
3027 if line == 0 {
3028 format!("journal event {message}")
3029 } else {
3030 format!("journal line {line} {message}")
3031 }
3032}
3033
3034pub(crate) fn safe_content_path(path: &Path) -> Result<PathBuf> {
3035 if path.as_os_str().is_empty() || path.is_absolute() || path.to_str().is_none() {
3036 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3037 }
3038
3039 let mut normalized = PathBuf::new();
3040 for component in path.components() {
3041 let Component::Normal(name) = component else {
3042 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3043 };
3044 if is_reserved_workspace_component(name) {
3045 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3046 }
3047 normalized.push(name);
3048 }
3049 if normalized.as_os_str().is_empty() {
3050 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3051 }
3052 Ok(normalized)
3053}
3054
3055fn relative_path_to_string(path: &Path) -> Result<String> {
3056 let safe = safe_content_path(path)?;
3057 safe.to_str()
3058 .map(ToOwned::to_owned)
3059 .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))
3060}
3061
3062fn paths_equal_ignoring_ascii_case(left: &Path, right: &Path) -> bool {
3063 left.to_str()
3064 .zip(right.to_str())
3065 .is_some_and(|(left, right)| left.eq_ignore_ascii_case(right))
3066}
3067
3068fn find_case_folded_child(parent: &Path, expected: &std::ffi::OsStr) -> Result<Option<PathBuf>> {
3069 let expected = expected
3070 .to_str()
3071 .ok_or_else(|| FolderbaseError::UnsafePath(parent.join(expected)))?;
3072 let entries = fs::read_dir(parent).map_err(|source| FolderbaseError::io(parent, source))?;
3073 let mut found = None;
3074 for entry in entries {
3075 let entry = entry.map_err(|source| FolderbaseError::io(parent, source))?;
3076 if entry
3077 .file_name()
3078 .to_str()
3079 .is_some_and(|name| name.eq_ignore_ascii_case(expected))
3080 {
3081 if found.is_some() {
3082 return Err(FolderbaseError::UnsafePath(parent.join(expected)));
3083 }
3084 found = Some(entry.path());
3085 }
3086 }
3087 Ok(found)
3088}
3089
3090fn resolve_without_symlinks(
3091 root: &Path,
3092 relative_path: &Path,
3093 create_parents: bool,
3094) -> Result<PathBuf> {
3095 let relative_path = safe_content_path(relative_path)?;
3096 let mut resolved = root.to_path_buf();
3097 let parent = relative_path.parent().unwrap_or_else(|| Path::new(""));
3098 for component in parent.components() {
3099 let Component::Normal(component) = component else {
3100 return Err(FolderbaseError::UnsafePath(relative_path));
3101 };
3102 resolved.push(component);
3103 match fs::symlink_metadata(&resolved) {
3104 Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
3105 return Err(FolderbaseError::UnsafePath(resolved));
3106 }
3107 Ok(_) => {}
3108 Err(source) if create_parents && source.kind() == std::io::ErrorKind::NotFound => {
3109 create_directory_durable(&resolved)?;
3110 }
3111 Err(source) => return Err(FolderbaseError::io(&resolved, source)),
3112 }
3113 if has_nested_folderbase_marker(&resolved)? {
3114 return Err(FolderbaseError::UnsafePath(relative_path));
3115 }
3116 }
3117 Ok(root.join(relative_path))
3118}
3119
3120fn ensure_directory_chain(root: &Path, relative_path: &Path) -> Result<()> {
3121 let mut current = root.to_path_buf();
3122 for component in relative_path.components() {
3123 let Component::Normal(component) = component else {
3124 return Err(FolderbaseError::UnsafePath(relative_path.to_path_buf()));
3125 };
3126 current.push(component);
3127 match fs::symlink_metadata(¤t) {
3128 Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
3129 return Err(FolderbaseError::UnsafePath(current));
3130 }
3131 Ok(_) => {}
3132 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
3133 match create_private_directory_durable(¤t) {
3134 Ok(()) => {}
3135 Err(FolderbaseError::Io { source, .. })
3136 if source.kind() == std::io::ErrorKind::AlreadyExists =>
3137 {
3138 let metadata = fs::symlink_metadata(¤t)
3139 .map_err(|source| FolderbaseError::io(¤t, source))?;
3140 if metadata.file_type().is_symlink() || !metadata.is_dir() {
3141 return Err(FolderbaseError::UnsafePath(current));
3142 }
3143 }
3144 Err(error) => return Err(error),
3145 }
3146 }
3147 Err(source) => return Err(FolderbaseError::io(¤t, source)),
3148 }
3149 }
3150 Ok(())
3151}
3152
3153fn validate_prefixed_uuid(value: &str, prefix: &str, record_path: &Path) -> Result<()> {
3154 let Some(uuid) = value.strip_prefix(prefix) else {
3155 return Err(invalid_record(
3156 record_path,
3157 format!("identifier must start with {prefix}"),
3158 ));
3159 };
3160 Uuid::parse_str(uuid)
3161 .map(|_| ())
3162 .map_err(|_| invalid_record(record_path, "identifier suffix is not a UUID"))
3163}
3164
3165fn read_folderbase_identity(root: &Path) -> Result<FolderbaseIdentity> {
3166 let path = root.join(".folderbase/manifest.json");
3167 let bytes = read_optional_file_nofollow(&path)?
3168 .ok_or_else(|| FolderbaseError::io(&path, std::io::ErrorKind::NotFound.into()))?;
3169 let id = folderbase_id_from_manifest_bytes(&bytes, &path)?;
3170 Ok(FolderbaseIdentity {
3171 id,
3172 manifest_sha256: digest_hex(Sha256::digest(&bytes).as_slice()),
3173 })
3174}
3175
3176pub(crate) fn folderbase_id_from_manifest_bytes(bytes: &[u8], path: &Path) -> Result<String> {
3177 let manifest: Value =
3178 serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))?;
3179 let id = manifest
3180 .get("folderbase")
3181 .and_then(|folderbase| folderbase.get("id"))
3182 .and_then(Value::as_str)
3183 .ok_or_else(|| invalid_record(path, "manifest is missing folderbase.id"))?
3184 .to_owned();
3185 validate_prefixed_uuid(&id, "folderbase_", path)?;
3186 Ok(id)
3187}
3188
3189pub(crate) fn validate_chunk_transfer_receipt_bytes(
3190 bytes: &[u8],
3191 path: &Path,
3192 object_id: &ObjectId,
3193 source_folderbase_id: &str,
3194) -> Result<()> {
3195 let receipt: HistoryTransferReceipt =
3196 serde_json::from_slice(bytes).map_err(|source| FolderbaseError::json(path, source))?;
3197 validate_history_transfer_receipt(&receipt, path)?;
3198 if receipt.object_id != *object_id || receipt.source_folderbase_id != source_folderbase_id {
3199 return Err(invalid_record(
3200 path,
3201 "outgoing history-transfer receipt does not match this folderbase or object",
3202 ));
3203 }
3204 Err(invalid_record(
3205 path,
3206 format!(
3207 "object history transferred to folderbase {}",
3208 receipt.destination_folderbase_id
3209 ),
3210 ))
3211}
3212
3213fn history_transfer_plan_path(root: &Path, transfer_id: &str) -> PathBuf {
3214 root.join(HISTORY_TRANSFER_INTENTS_DIRECTORY)
3215 .join(format!("{transfer_id}.json"))
3216}
3217
3218fn validate_content_digest(content: &ContentDigest, record_path: &Path) -> Result<()> {
3219 if content.algorithm != "sha256"
3220 || content.digest.len() != 64
3221 || !content
3222 .digest
3223 .bytes()
3224 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
3225 {
3226 return Err(invalid_record(
3227 record_path,
3228 "content digest is not a lowercase SHA-256 digest",
3229 ));
3230 }
3231 Ok(())
3232}
3233
3234#[cfg(unix)]
3235fn filesystem_identity(metadata: &fs::Metadata) -> Option<FileSystemIdentity> {
3236 use std::os::unix::fs::MetadataExt;
3237
3238 Some(FileSystemIdentity {
3239 device: metadata.dev(),
3240 inode: metadata.ino(),
3241 })
3242}
3243
3244#[cfg(not(unix))]
3245fn filesystem_identity(_metadata: &fs::Metadata) -> Option<FileSystemIdentity> {
3246 None
3247}
3248
3249fn verify_file_content(path: &Path, expected: &ContentDigest) -> Result<()> {
3250 validate_content_digest(expected, path)?;
3251 let file = open_existing_nofollow(path)?;
3252 let actual = hash_reader(file, path)?;
3253 if actual != *expected {
3254 return Err(invalid_record(
3255 path,
3256 format!(
3257 "content integrity mismatch: expected {} bytes with digest {}, found {} bytes with digest {}",
3258 expected.bytes, expected.digest, actual.bytes, actual.digest
3259 ),
3260 ));
3261 }
3262 Ok(())
3263}
3264
3265fn hash_reader(mut reader: impl Read, path: &Path) -> Result<ContentDigest> {
3266 let mut hasher = Sha256::new();
3267 let mut bytes = 0_u64;
3268 let mut buffer = [0_u8; COPY_BUFFER_BYTES];
3269 loop {
3270 let read = reader
3271 .read(&mut buffer)
3272 .map_err(|source| FolderbaseError::io(path, source))?;
3273 if read == 0 {
3274 break;
3275 }
3276 hasher.update(&buffer[..read]);
3277 bytes = bytes
3278 .checked_add(read as u64)
3279 .ok_or_else(|| invalid_record(path, "content length exceeds supported range"))?;
3280 }
3281 Ok(ContentDigest {
3282 algorithm: "sha256".to_owned(),
3283 digest: digest_hex(hasher.finalize().as_slice()),
3284 bytes,
3285 })
3286}
3287
3288fn copy_verified_new(source: &Path, destination: &Path, expected: &ContentDigest) -> Result<()> {
3289 let parent = destination
3290 .parent()
3291 .ok_or_else(|| FolderbaseError::UnsafePath(destination.to_path_buf()))?;
3292 let mut input = open_existing_nofollow(source)?;
3293 let staged_path = unique_staged_path(parent, "restore");
3294 let mut staged = open_new(&staged_path)?;
3295 let mut hasher = Sha256::new();
3296 let mut bytes = 0_u64;
3297 let mut buffer = [0_u8; COPY_BUFFER_BYTES];
3298
3299 let copy_result = (|| -> Result<()> {
3300 loop {
3301 let read = input
3302 .read(&mut buffer)
3303 .map_err(|source_error| FolderbaseError::io(source, source_error))?;
3304 if read == 0 {
3305 break;
3306 }
3307 staged
3308 .write_all(&buffer[..read])
3309 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3310 hasher.update(&buffer[..read]);
3311 bytes = bytes
3312 .checked_add(read as u64)
3313 .ok_or_else(|| invalid_record(source, "content length exceeds supported range"))?;
3314 }
3315 staged
3316 .sync_all()
3317 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3318 Ok(())
3319 })();
3320 drop(staged);
3321 if let Err(error) = copy_result {
3322 let _ = fs::remove_file(&staged_path);
3323 return Err(error);
3324 }
3325
3326 let copied = ContentDigest {
3327 algorithm: "sha256".to_owned(),
3328 digest: digest_hex(hasher.finalize().as_slice()),
3329 bytes,
3330 };
3331 if copied != *expected {
3332 let _ = fs::remove_file(&staged_path);
3333 return Err(invalid_record(
3334 source,
3335 "blob changed while it was being restored",
3336 ));
3337 }
3338 match install_no_clobber(&staged_path, destination) {
3339 Ok(()) => sync_parent_directory(destination),
3340 Err(source_error) => {
3341 let _ = fs::remove_file(&staged_path);
3342 if source_error.kind() == std::io::ErrorKind::AlreadyExists {
3343 Err(FolderbaseError::WouldOverwrite(destination.to_path_buf()))
3344 } else {
3345 Err(FolderbaseError::io(destination, source_error))
3346 }
3347 }
3348 }
3349}
3350
3351fn replace_verified(
3352 source: &Path,
3353 destination: &Path,
3354 expected: &ContentDigest,
3355 replacement: &PendingReplacement,
3356) -> Result<()> {
3357 let parent = destination
3358 .parent()
3359 .ok_or_else(|| FolderbaseError::UnsafePath(destination.to_path_buf()))?;
3360 let parent_file = open_directory_nofollow(parent)?;
3361 let parent_identity = filesystem_identity(
3362 &parent_file
3363 .metadata()
3364 .map_err(|source_error| FolderbaseError::io(parent, source_error))?,
3365 );
3366 if replacement
3367 .parent_identity
3368 .as_ref()
3369 .is_some_and(|expected| parent_identity.as_ref() != Some(expected))
3370 {
3371 return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3372 &replacement.destination,
3373 )));
3374 }
3375 let destination_file = open_existing_nofollow(destination)?;
3376 let destination_identity = filesystem_identity(
3377 &destination_file
3378 .metadata()
3379 .map_err(|source_error| FolderbaseError::io(destination, source_error))?,
3380 );
3381 if replacement
3382 .file_identity
3383 .as_ref()
3384 .is_some_and(|expected| destination_identity.as_ref() != Some(expected))
3385 {
3386 return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3387 &replacement.destination,
3388 )));
3389 }
3390 let mut input = open_existing_nofollow(source)?;
3391 let staged_path = unique_staged_path(parent, "workspace-save");
3392 let mut staged = open_new(&staged_path)?;
3393 let mut hasher = Sha256::new();
3394 let mut bytes = 0_u64;
3395 let mut buffer = [0_u8; COPY_BUFFER_BYTES];
3396
3397 let copy_result = (|| -> Result<()> {
3398 loop {
3399 let read = input
3400 .read(&mut buffer)
3401 .map_err(|source_error| FolderbaseError::io(source, source_error))?;
3402 if read == 0 {
3403 break;
3404 }
3405 staged
3406 .write_all(&buffer[..read])
3407 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3408 hasher.update(&buffer[..read]);
3409 bytes = bytes
3410 .checked_add(read as u64)
3411 .ok_or_else(|| invalid_record(source, "content length exceeds supported range"))?;
3412 }
3413
3414 #[cfg(unix)]
3415 if let Some(mode) = replacement.unix_mode {
3416 use std::os::unix::fs::PermissionsExt;
3417 staged
3418 .set_permissions(fs::Permissions::from_mode(mode))
3419 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3420 }
3421 #[cfg(not(unix))]
3422 {
3423 let mut permissions = staged
3424 .metadata()
3425 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?
3426 .permissions();
3427 permissions.set_readonly(replacement.readonly);
3428 staged
3429 .set_permissions(permissions)
3430 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3431 }
3432
3433 copy_ordinary_file_metadata(&destination_file, &staged, destination)?;
3434 staged
3435 .sync_all()
3436 .map_err(|source_error| FolderbaseError::io(&staged_path, source_error))?;
3437 Ok(())
3438 })();
3439 drop(staged);
3440 if let Err(error) = copy_result {
3441 let _ = fs::remove_file(&staged_path);
3442 return Err(error);
3443 }
3444
3445 let copied = ContentDigest {
3446 algorithm: "sha256".to_owned(),
3447 digest: digest_hex(hasher.finalize().as_slice()),
3448 bytes,
3449 };
3450 if copied != *expected {
3451 let _ = fs::remove_file(&staged_path);
3452 return Err(invalid_record(
3453 source,
3454 "blob changed while workspace content was being staged",
3455 ));
3456 }
3457
3458 let final_check = (|| -> Result<()> {
3459 let current_parent_identity = filesystem_identity(
3460 &fs::metadata(parent)
3461 .map_err(|source_error| FolderbaseError::io(parent, source_error))?,
3462 );
3463 if current_parent_identity != parent_identity {
3464 return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3465 &replacement.destination,
3466 )));
3467 }
3468
3469 let current_file = open_existing_nofollow(destination)?;
3470 let current_identity = filesystem_identity(
3471 ¤t_file
3472 .metadata()
3473 .map_err(|source_error| FolderbaseError::io(destination, source_error))?,
3474 );
3475 if current_identity != destination_identity {
3476 return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3477 &replacement.destination,
3478 )));
3479 }
3480 let current_content = hash_reader(current_file, destination)?;
3481 if current_content != replacement.previous_content {
3482 return Err(FolderbaseError::WorkspaceContentChanged(PathBuf::from(
3483 &replacement.destination,
3484 )));
3485 }
3486 Ok(())
3487 })();
3488 if let Err(error) = final_check {
3489 let _ = fs::remove_file(&staged_path);
3490 return Err(error);
3491 }
3492
3493 fs::rename(&staged_path, destination).map_err(|source_error| {
3498 let _ = fs::remove_file(&staged_path);
3499 FolderbaseError::io(destination, source_error)
3500 })?;
3501 sync_parent_directory(destination)?;
3502 verify_file_content(destination, expected)
3503}
3504
3505fn open_existing_nofollow(path: &Path) -> Result<File> {
3506 let path_metadata =
3507 fs::symlink_metadata(path).map_err(|source| FolderbaseError::io(path, source))?;
3508 if path_metadata.file_type().is_symlink() || !path_metadata.is_file() {
3509 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3510 }
3511
3512 let mut options = OpenOptions::new();
3513 options.read(true);
3514 #[cfg(unix)]
3515 {
3516 use std::os::unix::fs::OpenOptionsExt;
3517 options.custom_flags(libc::O_NOFOLLOW);
3518 }
3519 let file = options
3520 .open(path)
3521 .map_err(|source| FolderbaseError::io(path, source))?;
3522 let opened_metadata = file
3523 .metadata()
3524 .map_err(|source| FolderbaseError::io(path, source))?;
3525 if !opened_metadata.is_file()
3526 || filesystem_identity(&path_metadata) != filesystem_identity(&opened_metadata)
3527 {
3528 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3529 }
3530 Ok(file)
3531}
3532
3533fn read_optional_file_nofollow(path: &Path) -> Result<Option<Vec<u8>>> {
3534 let mut file = match open_existing_nofollow(path) {
3535 Ok(file) => file,
3536 Err(FolderbaseError::Io { source, .. })
3537 if source.kind() == std::io::ErrorKind::NotFound =>
3538 {
3539 return Ok(None);
3540 }
3541 Err(error) => return Err(error),
3542 };
3543 let mut bytes = Vec::new();
3544 file.read_to_end(&mut bytes)
3545 .map_err(|source| FolderbaseError::io(path, source))?;
3546 Ok(Some(bytes))
3547}
3548
3549fn open_directory_nofollow(path: &Path) -> Result<File> {
3550 let mut options = OpenOptions::new();
3551 options.read(true);
3552 #[cfg(unix)]
3553 {
3554 use std::os::unix::fs::OpenOptionsExt;
3555 options.custom_flags(libc::O_DIRECTORY | libc::O_NOFOLLOW);
3556 }
3557 let file = options
3558 .open(path)
3559 .map_err(|source| FolderbaseError::io(path, source))?;
3560 if !file
3561 .metadata()
3562 .map_err(|source| FolderbaseError::io(path, source))?
3563 .is_dir()
3564 {
3565 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
3566 }
3567 Ok(file)
3568}
3569
3570#[cfg(target_os = "macos")]
3571fn copy_ordinary_file_metadata(source: &File, destination: &File, path: &Path) -> Result<()> {
3572 use std::os::fd::AsRawFd;
3573
3574 let flags = libc::COPYFILE_ACL | libc::COPYFILE_XATTR;
3578 if unsafe {
3579 libc::fcopyfile(
3580 source.as_raw_fd(),
3581 destination.as_raw_fd(),
3582 std::ptr::null_mut(),
3583 flags,
3584 )
3585 } != 0
3586 {
3587 return Err(FolderbaseError::io(path, std::io::Error::last_os_error()));
3588 }
3589 Ok(())
3590}
3591
3592#[cfg(not(target_os = "macos"))]
3593fn copy_ordinary_file_metadata(_source: &File, _destination: &File, _path: &Path) -> Result<()> {
3594 Ok(())
3595}
3596
3597fn read_json<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<T> {
3598 let bytes = read_optional_file_nofollow(path)?.ok_or_else(|| {
3599 FolderbaseError::io(path, std::io::Error::from(std::io::ErrorKind::NotFound))
3600 })?;
3601 serde_json::from_slice(&bytes).map_err(|source| FolderbaseError::json(path, source))
3602}
3603
3604fn write_json_new(path: &Path, value: &impl Serialize) -> Result<()> {
3605 let bytes = json_bytes(path, value)?;
3606 write_bytes_new(path, &bytes)
3607}
3608
3609fn write_json_replace(path: &Path, value: &impl Serialize) -> Result<()> {
3610 let bytes = json_bytes(path, value)?;
3611 write_bytes_replace(path, &bytes)
3612}
3613
3614fn write_bytes_new(path: &Path, bytes: &[u8]) -> Result<()> {
3615 let parent = path
3616 .parent()
3617 .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
3618 let staged_path = unique_staged_path(parent, "record");
3619 write_staged(&staged_path, bytes)?;
3620 match install_no_clobber(&staged_path, path) {
3621 Ok(()) => sync_parent_directory(path),
3622 Err(source) => {
3623 let _ = fs::remove_file(&staged_path);
3624 if source.kind() == std::io::ErrorKind::AlreadyExists {
3625 Err(FolderbaseError::WouldOverwrite(path.to_path_buf()))
3626 } else {
3627 Err(FolderbaseError::io(path, source))
3628 }
3629 }
3630 }
3631}
3632
3633fn write_bytes_replace(path: &Path, bytes: &[u8]) -> Result<()> {
3634 let parent = path
3635 .parent()
3636 .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
3637 let staged_path = unique_staged_path(parent, "projection");
3638 write_staged(&staged_path, bytes)?;
3639 fs::rename(&staged_path, path).map_err(|source| {
3640 let _ = fs::remove_file(&staged_path);
3641 FolderbaseError::io(path, source)
3642 })?;
3643 sync_parent_directory(path)
3644}
3645
3646fn json_bytes(path: &Path, value: &impl Serialize) -> Result<Vec<u8>> {
3647 let mut bytes =
3648 serde_json::to_vec_pretty(value).map_err(|source| FolderbaseError::json(path, source))?;
3649 bytes.push(b'\n');
3650 Ok(bytes)
3651}
3652
3653fn write_staged(path: &Path, bytes: &[u8]) -> Result<()> {
3654 let mut file = open_new(path)?;
3655 let result = file.write_all(bytes).and_then(|()| file.sync_all());
3656 drop(file);
3657 if let Err(source) = result {
3658 let _ = fs::remove_file(path);
3659 return Err(FolderbaseError::io(path, source));
3660 }
3661 Ok(())
3662}
3663
3664fn open_new(path: &Path) -> Result<File> {
3665 let mut options = OpenOptions::new();
3666 options.write(true).create_new(true);
3667 #[cfg(unix)]
3668 {
3669 use std::os::unix::fs::OpenOptionsExt;
3670 options.mode(0o600).custom_flags(libc::O_NOFOLLOW);
3671 }
3672 options
3673 .open(path)
3674 .map_err(|source| FolderbaseError::io(path, source))
3675}
3676
3677fn create_private_directory_durable(path: &Path) -> Result<()> {
3678 let builder = fs::DirBuilder::new();
3679 #[cfg(unix)]
3680 let builder = {
3681 use std::os::unix::fs::DirBuilderExt;
3682 let mut builder = builder;
3683 builder.mode(0o700);
3684 builder
3685 };
3686 builder
3687 .create(path)
3688 .map_err(|source| FolderbaseError::io(path, source))?;
3689 sync_parent_directory(path)
3690}
3691
3692fn create_directory_durable(path: &Path) -> Result<()> {
3693 fs::create_dir(path).map_err(|source| FolderbaseError::io(path, source))?;
3694 sync_parent_directory(path)
3695}
3696
3697fn install_no_clobber(staged: &Path, destination: &Path) -> std::io::Result<()> {
3699 fs::hard_link(staged, destination)?;
3700 fs::remove_file(staged)
3701}
3702
3703fn unique_staged_path(directory: &Path, label: &str) -> PathBuf {
3704 directory.join(format!(".{label}-{}.tmp", Uuid::now_v7()))
3705}
3706
3707#[cfg(unix)]
3708fn sync_parent_directory(path: &Path) -> Result<()> {
3709 let parent = path
3710 .parent()
3711 .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))?;
3712 File::open(parent)
3713 .and_then(|directory| directory.sync_all())
3714 .map_err(|source| FolderbaseError::io(parent, source))
3715}
3716
3717#[cfg(not(unix))]
3718fn sync_parent_directory(_path: &Path) -> Result<()> {
3719 Ok(())
3720}
3721
3722fn digest_hex(bytes: &[u8]) -> String {
3723 let mut output = String::with_capacity(bytes.len() * 2);
3724 for byte in bytes {
3725 let _ = write!(&mut output, "{byte:02x}");
3726 }
3727 output
3728}
3729
3730fn invalid_record(path: impl Into<PathBuf>, message: impl Into<String>) -> FolderbaseError {
3731 FolderbaseError::InvalidRecord {
3732 path: path.into(),
3733 message: message.into(),
3734 }
3735}
3736
3737#[cfg(test)]
3738mod tests {
3739 use std::{
3740 fs::OpenOptions,
3741 panic::{AssertUnwindSafe, catch_unwind},
3742 };
3743
3744 use tempfile::TempDir;
3745
3746 use super::*;
3747 use crate::{
3748 FolderbaseKind, InitializationOptions,
3749 initialization::{initialize, plan_initialization},
3750 };
3751
3752 #[test]
3753 fn generic_versioned_replace_refuses_the_exact_root_ignore_policy_before_writes() {
3754 for policy_path in [".folderbaseignore", ".FOLDERBASEIGNORE"] {
3755 let fixture = tempfile::tempdir().expect("temporary version store");
3756 fs::write(fixture.path().join(policy_path), b"node_modules/\n").expect("ignore policy");
3757 let store = LocalVersionStore::open(fixture.path()).expect("version store");
3758 let expected = ContentDigest {
3759 algorithm: "sha256".to_owned(),
3760 digest: "4d56952b0fb13bf8f9b6c13a6d4c34a075bac3af447636a1df4335d7576e2f97"
3761 .to_owned(),
3762 bytes: 14,
3763 };
3764
3765 let error = store
3766 .replace_file_versioned(policy_path, &expected, b"target/\n")
3767 .expect_err("generic local-version replacement cannot change capture policy");
3768
3769 assert!(matches!(
3770 error,
3771 FolderbaseError::UnsafePath(path) if path == Path::new(policy_path)
3772 ));
3773 assert_eq!(
3774 fs::read(fixture.path().join(policy_path)).unwrap(),
3775 b"node_modules/\n"
3776 );
3777 assert!(
3778 !fixture.path().join(".folderbase").exists(),
3779 "policy refusal must precede lazy version-state creation"
3780 );
3781 }
3782 }
3783
3784 #[test]
3785 fn transaction_lock_is_exclusive_across_independent_handles() {
3786 let fixture = tempfile::tempdir().expect("temporary lock store");
3787 fs::create_dir_all(fixture.path().join(LOCKS_DIRECTORY)).expect("lock directory");
3788 let path = fixture.path().join(TRANSACTION_LOCK_PATH);
3789 let first = OpenOptions::new()
3790 .read(true)
3791 .write(true)
3792 .create(true)
3793 .truncate(false)
3794 .open(&path)
3795 .expect("first handle");
3796 let second = OpenOptions::new()
3797 .read(true)
3798 .write(true)
3799 .open(&path)
3800 .expect("second handle");
3801 File::lock(&first).expect("first exclusive lock");
3802 assert!(matches!(
3803 File::try_lock(&second).expect_err("second handle must contend"),
3804 std::fs::TryLockError::WouldBlock
3805 ));
3806 File::unlock(&first).expect("unlock");
3807 File::lock(&second).expect("second handle acquires after release");
3808 File::unlock(&second).expect("final unlock");
3809 }
3810
3811 #[test]
3812 fn every_history_transfer_checkpoint_reopens_and_recovers() {
3813 for fault in [
3814 HistoryTransferCheckpoint::Applying,
3815 HistoryTransferCheckpoint::DestinationStaged,
3816 HistoryTransferCheckpoint::DestinationVerified,
3817 HistoryTransferCheckpoint::SourceReceiptWritten,
3818 HistoryTransferCheckpoint::SourceReleased,
3819 HistoryTransferCheckpoint::IncomingReceiptWritten,
3820 HistoryTransferCheckpoint::DestinationActivated,
3821 HistoryTransferCheckpoint::Verified,
3822 ] {
3823 let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3824 history_transfer_fixture();
3825 let plan = parent_store
3826 .propose_history_transfer(
3827 &child_store,
3828 &parent_id,
3829 &child_id,
3830 &object_id,
3831 "private.txt",
3832 )
3833 .unwrap();
3834 let transfer_id = plan.id().to_owned();
3835 let approved = approve_history_transfer(plan).unwrap();
3836
3837 let interrupted = catch_unwind(AssertUnwindSafe(|| {
3838 apply_history_transfer_with_hook(approved, |checkpoint| {
3839 if checkpoint == fault {
3840 panic!("simulated process termination");
3841 }
3842 })
3843 }));
3844 assert!(interrupted.is_err());
3845 if fault == HistoryTransferCheckpoint::IncomingReceiptWritten {
3846 assert!(incoming_history_transfer_path(child_store.root(), &object_id).exists());
3847 assert!(child_store.read_object(&object_id).is_err());
3848 }
3849
3850 let recovered = HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap();
3851 assert_eq!(recovered.state, HistoryTransferState::Verified);
3852 assert_eq!(recovered.object_id, object_id);
3853 assert_eq!(
3854 child_store.read_object(&object_id).unwrap().path,
3855 "private.txt"
3856 );
3857 assert!(parent_store.read_object(&object_id).is_err());
3858 assert_eq!(
3859 HistoryTransferResult::recover(fixture.path(), &transfer_id)
3860 .unwrap()
3861 .state,
3862 HistoryTransferState::Verified
3863 );
3864 assert!(!history_transfer_staging_root(child_store.root(), &transfer_id).exists());
3865 }
3866 }
3867
3868 #[test]
3869 fn source_released_recovery_preserves_workspace_and_manifest_changes() {
3870 let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3871 history_transfer_fixture();
3872 let plan = parent_store
3873 .propose_history_transfer(
3874 &child_store,
3875 &parent_id,
3876 &child_id,
3877 &object_id,
3878 "private.txt",
3879 )
3880 .unwrap();
3881 let transfer_id = plan.id().to_owned();
3882 let approved = approve_history_transfer(plan).unwrap();
3883 let interrupted = catch_unwind(AssertUnwindSafe(|| {
3884 apply_history_transfer_with_hook(approved, |checkpoint| {
3885 if checkpoint == HistoryTransferCheckpoint::SourceReleased {
3886 panic!("simulated process termination");
3887 }
3888 })
3889 }));
3890 assert!(interrupted.is_err());
3891
3892 fs::write(
3893 fixture.path().join("Client/private.txt"),
3894 "user edit after source release\n",
3895 )
3896 .unwrap();
3897 for manifest in [
3898 fixture.path().join(".folderbase/manifest.json"),
3899 fixture.path().join("Client/.folderbase/manifest.json"),
3900 ] {
3901 let mut bytes = fs::read(&manifest).unwrap();
3902 bytes.push(b'\n');
3903 fs::write(manifest, bytes).unwrap();
3904 }
3905
3906 let recovered = HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap();
3907
3908 assert_eq!(recovered.state, HistoryTransferState::Verified);
3909 assert_eq!(
3910 fs::read(fixture.path().join("Client/private.txt")).unwrap(),
3911 b"user edit after source release\n"
3912 );
3913 assert_eq!(child_store.read_object(&object_id).unwrap().id, object_id);
3914 assert!(parent_store.read_object(&object_id).is_err());
3915 }
3916
3917 #[test]
3918 fn source_released_destination_capture_enters_durable_conflict() {
3919 let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3920 history_transfer_fixture();
3921 let plan = parent_store
3922 .propose_history_transfer(
3923 &child_store,
3924 &parent_id,
3925 &child_id,
3926 &object_id,
3927 "private.txt",
3928 )
3929 .unwrap();
3930 let transfer_id = plan.id().to_owned();
3931 let approved = approve_history_transfer(plan).unwrap();
3932 let interrupted = catch_unwind(AssertUnwindSafe(|| {
3933 apply_history_transfer_with_hook(approved, |checkpoint| {
3934 if checkpoint == HistoryTransferCheckpoint::SourceReleased {
3935 panic!("simulated process termination");
3936 }
3937 })
3938 }));
3939 assert!(interrupted.is_err());
3940
3941 fs::write(
3942 fixture.path().join("Client/private.txt"),
3943 "captured child edit\n",
3944 )
3945 .unwrap();
3946 let child_capture = child_store.capture_file("private.txt").unwrap();
3947 let error = HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap_err();
3948
3949 assert!(matches!(error, FolderbaseError::WouldOverwrite(_)));
3950 assert_eq!(
3951 HistoryTransferPlan::reopen(fixture.path(), &transfer_id)
3952 .unwrap()
3953 .state,
3954 HistoryTransferState::Conflicted
3955 );
3956 assert_eq!(
3957 child_store
3958 .read_object(&child_capture.object.id)
3959 .unwrap()
3960 .id,
3961 child_capture.object.id
3962 );
3963 assert_eq!(
3964 fs::read(fixture.path().join("Client/private.txt")).unwrap(),
3965 b"captured child edit\n"
3966 );
3967 }
3968
3969 #[test]
3970 fn source_released_staging_tamper_enters_durable_conflict() {
3971 let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
3972 history_transfer_fixture();
3973 let plan = parent_store
3974 .propose_history_transfer(
3975 &child_store,
3976 &parent_id,
3977 &child_id,
3978 &object_id,
3979 "private.txt",
3980 )
3981 .unwrap();
3982 let transfer_id = plan.id().to_owned();
3983 let approved = approve_history_transfer(plan).unwrap();
3984 let interrupted = catch_unwind(AssertUnwindSafe(|| {
3985 apply_history_transfer_with_hook(approved, |checkpoint| {
3986 if checkpoint == HistoryTransferCheckpoint::SourceReleased {
3987 panic!("simulated process termination");
3988 }
3989 })
3990 }));
3991 assert!(interrupted.is_err());
3992
3993 let staged_object = history_transfer_staging_root(child_store.root(), &transfer_id)
3994 .join("objects")
3995 .join(format!("{object_id}.json"));
3996 fs::write(staged_object, b"{}\n").unwrap();
3997
3998 assert!(HistoryTransferResult::recover(fixture.path(), &transfer_id).is_err());
3999 assert_eq!(
4000 HistoryTransferPlan::reopen(fixture.path(), &transfer_id)
4001 .unwrap()
4002 .state,
4003 HistoryTransferState::Conflicted
4004 );
4005 assert!(parent_store.read_object(&object_id).is_err());
4006 assert!(child_store.read_object(&object_id).is_err());
4007 }
4008
4009 #[test]
4010 fn verified_recovery_reports_staging_cleanup_failure_and_retries() {
4011 let (fixture, parent_store, child_store, parent_id, child_id, object_id) =
4012 history_transfer_fixture();
4013 let plan = parent_store
4014 .propose_history_transfer(
4015 &child_store,
4016 &parent_id,
4017 &child_id,
4018 &object_id,
4019 "private.txt",
4020 )
4021 .unwrap();
4022 let transfer_id = plan.id().to_owned();
4023 apply_history_transfer(approve_history_transfer(plan).unwrap()).unwrap();
4024 let staging = history_transfer_staging_root(child_store.root(), &transfer_id);
4025 fs::write(&staging, b"not a removable staging directory").unwrap();
4026
4027 let cleanup_error =
4028 HistoryTransferResult::recover(fixture.path(), &transfer_id).unwrap_err();
4029
4030 assert!(matches!(cleanup_error, FolderbaseError::Io { .. }));
4031 assert!(staging.is_file());
4032 assert_eq!(
4033 HistoryTransferPlan::reopen(fixture.path(), &transfer_id)
4034 .unwrap()
4035 .state,
4036 HistoryTransferState::Verified
4037 );
4038 fs::remove_file(&staging).unwrap();
4039 assert_eq!(
4040 HistoryTransferResult::recover(fixture.path(), &transfer_id)
4041 .unwrap()
4042 .state,
4043 HistoryTransferState::Verified
4044 );
4045 }
4046
4047 fn history_transfer_fixture() -> (
4048 TempDir,
4049 LocalVersionStore,
4050 LocalVersionStore,
4051 String,
4052 String,
4053 ObjectId,
4054 ) {
4055 let fixture = tempfile::tempdir().unwrap();
4056 let parent = initialize(
4057 &plan_initialization(
4058 fixture.path(),
4059 InitializationOptions {
4060 name: Some("Parent".to_owned()),
4061 kind: FolderbaseKind::Organization,
4062 create_agent_adapters: false,
4063 },
4064 )
4065 .unwrap(),
4066 )
4067 .unwrap();
4068 fs::create_dir(fixture.path().join("Client")).unwrap();
4069 fs::write(fixture.path().join("Client/private.txt"), "history\n").unwrap();
4070 let parent_store = LocalVersionStore::open(fixture.path()).unwrap();
4071 let captured = parent_store.capture_file("Client/private.txt").unwrap();
4072
4073 let child_fixture = tempfile::tempdir().unwrap();
4074 let child = initialize(
4075 &plan_initialization(
4076 child_fixture.path(),
4077 InitializationOptions {
4078 name: Some("Child".to_owned()),
4079 kind: FolderbaseKind::Project,
4080 create_agent_adapters: false,
4081 },
4082 )
4083 .unwrap(),
4084 )
4085 .unwrap();
4086 fs::create_dir_all(fixture.path().join("Client/.folderbase")).unwrap();
4087 fs::copy(
4088 child_fixture.path().join(".folderbase/manifest.json"),
4089 fixture.path().join("Client/.folderbase/manifest.json"),
4090 )
4091 .unwrap();
4092 let child_store = LocalVersionStore::open(fixture.path().join("Client")).unwrap();
4093 (
4094 fixture,
4095 parent_store,
4096 child_store,
4097 parent.folderbase_id,
4098 child.folderbase_id,
4099 captured.object.id,
4100 )
4101 }
4102}