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("template expansion request exceeds the 4194304-byte input limit")]
121    TemplateRequestTooLarge,
122
123    #[error("invalid template expansion request: {0}")]
124    InvalidTemplateRequest(String),
125
126    #[error(
127        "template expansion plan digest must be exactly 64 lowercase hexadecimal SHA-256 characters"
128    )]
129    InvalidTemplateExpansionPlanDigest,
130
131    #[error(
132        "template expansion plan changed after approval: expected {expected}, current plan is {actual}"
133    )]
134    TemplateExpansionPlanChanged { expected: String, actual: String },
135
136    #[error("workspace content changed: {0}")]
137    WorkspaceContentChanged(PathBuf),
138
139    #[error("invalid protocol record at {path}: {message}")]
140    InvalidRecord { path: PathBuf, message: String },
141
142    #[error("filesystem operation failed at {path}: {source}")]
143    Io {
144        path: PathBuf,
145        #[source]
146        source: std::io::Error,
147    },
148
149    #[error("JSON operation failed at {path}: {source}")]
150    Json {
151        path: PathBuf,
152        #[source]
153        source: serde_json::Error,
154    },
155}
156
157impl FolderbaseError {
158    pub(crate) fn io(path: impl Into<PathBuf>, source: std::io::Error) -> Self {
159        Self::Io {
160            path: path.into(),
161            source,
162        }
163    }
164
165    pub(crate) fn json(path: impl Into<PathBuf>, source: serde_json::Error) -> Self {
166        Self::Json {
167            path: path.into(),
168            source,
169        }
170    }
171}
172
173pub type Result<T> = std::result::Result<T, FolderbaseError>;