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