Skip to main content

folderbase_core/
error.rs

1use std::path::PathBuf;
2
3#[derive(Debug, Clone, Copy, PartialEq, Eq)]
4pub enum InitializationInventoryLimitKind {
5    Entries,
6    Depth,
7    PathBytes,
8    EncodedInventoryBytes,
9    PathComponentWork,
10    DirectoryEntryWork,
11}
12
13impl std::fmt::Display for InitializationInventoryLimitKind {
14    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
15        formatter.write_str(match self {
16            Self::Entries => "entries",
17            Self::Depth => "depth",
18            Self::PathBytes => "path_bytes",
19            Self::EncodedInventoryBytes => "encoded_inventory_bytes",
20            Self::PathComponentWork => "path_component_work",
21            Self::DirectoryEntryWork => "directory_entry_work",
22        })
23    }
24}
25
26/// Errors that prevent an operation from producing a trustworthy result.
27#[derive(Debug, thiserror::Error)]
28pub enum FolderbaseError {
29    #[error("folderbase root does not exist or is not a directory: {0}")]
30    InvalidRoot(PathBuf),
31
32    #[error("path escapes the folderbase root: {0}")]
33    UnsafePath(PathBuf),
34
35    #[error("folder appears to be controlled by another file provider: {0}")]
36    ProviderControlled(PathBuf),
37
38    #[error("initialization plan was created for {planned_root}, not {actual_root}")]
39    PlanRootMismatch {
40        planned_root: PathBuf,
41        actual_root: PathBuf,
42    },
43
44    #[error("folderbase root changed after the initialization plan was created: {0}")]
45    PlanRootIdentityChanged(PathBuf),
46
47    #[error("preserved path changed after the initialization plan was created: {0}")]
48    PlanPreconditionChanged(PathBuf),
49
50    #[error(
51        "initialization plan digest must be exactly 64 lowercase hexadecimal SHA-256 characters"
52    )]
53    InvalidInitializationPlanDigest,
54
55    #[error(
56        "initialization plan changed after approval: expected {expected}, current plan is {actual}"
57    )]
58    InitializationPlanChanged { expected: String, actual: String },
59
60    #[error(
61        "protocol upgrade plan digest must be exactly 64 lowercase hexadecimal SHA-256 characters"
62    )]
63    InvalidProtocolUpgradePlanDigest,
64
65    #[error(
66        "protocol upgrade plan changed after approval: expected {expected}, current plan is {actual}"
67    )]
68    ProtocolUpgradePlanChanged { expected: String, actual: String },
69
70    #[error("protocol upgrade is blocked by pending work: {0}")]
71    ProtocolUpgradeBlocked(&'static str),
72
73    #[error("Folderbase recovery is required before this migration can continue: {work}")]
74    RecoveryRequired { work: String },
75
76    #[error("initialization destination changed after approval: {0}")]
77    InitializationDestinationChanged(PathBuf),
78
79    #[error("initialization inventory exceeded the {limit} limit of {maximum}")]
80    InitializationInventoryLimitExceeded {
81        limit: InitializationInventoryLimitKind,
82        maximum: u64,
83    },
84
85    #[error(
86        "nested Folderbase boundary inspection exceeded the shared entry-work limit of {maximum} at: {path}"
87    )]
88    NestedBoundaryWorkLimitExceeded { path: PathBuf, maximum: u64 },
89
90    #[error("migration is not in the required state: expected {expected}, found {actual}")]
91    InvalidMigrationState {
92        expected: &'static str,
93        actual: String,
94    },
95
96    #[error("migration approval does not match the planned migration")]
97    MigrationApprovalMismatch,
98
99    #[error("migration source changed after analysis: {0}")]
100    MigrationSourceChanged(PathBuf),
101
102    #[error("migration verification failed at: {0}")]
103    MigrationVerificationFailed(PathBuf),
104
105    #[error("refusing to overwrite existing path: {0}")]
106    WouldOverwrite(PathBuf),
107
108    #[error("restore namespace repair is required before retrying at: {0}")]
109    RestoreNamespaceRepairRequired(PathBuf),
110
111    #[error("migration filesystem is unsupported at {path}: {reason}")]
112    UnsupportedMigrationFilesystem { path: PathBuf, reason: String },
113
114    #[error("template expansion contains structural changes that require an approved migration")]
115    StructuralTemplateChangeRequiresApproval,
116
117    #[error("template expansion contains blocked paths")]
118    TemplateExpansionBlocked,
119
120    #[error("workspace content changed: {0}")]
121    WorkspaceContentChanged(PathBuf),
122
123    #[error("invalid protocol record at {path}: {message}")]
124    InvalidRecord { path: PathBuf, message: String },
125
126    #[error("filesystem operation failed at {path}: {source}")]
127    Io {
128        path: PathBuf,
129        #[source]
130        source: std::io::Error,
131    },
132
133    #[error("JSON operation failed at {path}: {source}")]
134    Json {
135        path: PathBuf,
136        #[source]
137        source: serde_json::Error,
138    },
139}
140
141impl FolderbaseError {
142    pub(crate) fn io(path: impl Into<PathBuf>, source: std::io::Error) -> Self {
143        Self::Io {
144            path: path.into(),
145            source,
146        }
147    }
148
149    pub(crate) fn json(path: impl Into<PathBuf>, source: serde_json::Error) -> Self {
150        Self::Json {
151            path: path.into(),
152            source,
153        }
154    }
155}
156
157pub type Result<T> = std::result::Result<T, FolderbaseError>;