change_capsule/error.rs
1//! Error type shared by every operation in this crate.
2
3use std::path::PathBuf;
4
5/// Everything that can go wrong in a capsule operation.
6///
7/// Variants are deliberately specific so callers can branch on failure without
8/// parsing messages. The `capsule` binary maps each variant to a stable `kind`
9/// string in its JSON error output.
10#[derive(Debug, thiserror::Error)]
11#[non_exhaustive]
12pub enum Error {
13 /// The given path is not inside a Git repository.
14 #[error("not a Git repository: {0}")]
15 NotRepository(PathBuf),
16 /// No capsule with this identifier exists.
17 #[error("capsule not found: {0}")]
18 NotFound(String),
19 /// The identifier is not a well-formed capsule ID.
20 #[error("invalid capsule id: {0}")]
21 InvalidId(String),
22 /// Caller input was missing, malformed, or out of bounds.
23 #[error("invalid input: {0}")]
24 InvalidInput(String),
25 /// An existing key is permanently bound to a materially different creation request.
26 #[error("idempotency key is already bound to a different creation request")]
27 IdempotencyConflict,
28 /// No reservation exists for the requested state-root-scoped idempotency key.
29 #[error("idempotency reservation not found")]
30 IdempotencyNotFound,
31 /// The operation is not allowed from the capsule's current state.
32 #[error("capsule {id} is {state}; expected {expected}")]
33 InvalidState {
34 /// Capsule the operation targeted.
35 id: String,
36 /// State it was actually in.
37 state: String,
38 /// State or states the operation requires.
39 expected: String,
40 },
41 /// Stored state is inconsistent, unsafely shaped, or self-contradictory.
42 #[error("unsafe state path: {0}")]
43 UnsafeState(String),
44 /// A path no longer proves it is the worktree the capsule created.
45 ///
46 /// Returned instead of deleting anything, even under `--force`.
47 #[error("refusing to remove a foreign or replaced worktree: {0}")]
48 ForeignWorktree(PathBuf),
49 /// Cleanup was requested for a capsule whose work is not sealed.
50 #[error("capsule has unsealed changes; close it first or pass --force: {0}")]
51 UnsealedChanges(String),
52 /// Tracked content or result artifacts changed after the result was sealed.
53 #[error("closed capsule has drifted since its result was sealed: {0}")]
54 ResultDrift(String),
55 /// The integration target has uncommitted changes.
56 #[error("integration target is not clean: {0}")]
57 DirtyIntegrationTarget(PathBuf),
58 /// A Git subprocess exited unsuccessfully.
59 #[error("Git command failed ({command}, exit {status}): {stderr}")]
60 Git {
61 /// Command that was run.
62 command: String,
63 /// Exit status it returned.
64 status: i32,
65 /// Captured standard error, bounded in size.
66 stderr: String,
67 },
68 /// A Git subprocess produced more output than its in-memory bound allows.
69 #[error("Git output exceeded the {cap}-byte bound for: {command}")]
70 GitOutputTooLarge {
71 /// Command that produced the output.
72 command: String,
73 /// Bound that was exceeded, in bytes.
74 cap: usize,
75 },
76 /// A path cannot be represented in the UTF-8 result inventory.
77 #[error("unsupported non-UTF-8 path: {0:?}")]
78 NonUtf8Path(PathBuf),
79 /// Stored state was written by an incompatible schema version.
80 #[error("state schema version {found} is incompatible with supported version {supported}")]
81 SchemaVersion {
82 /// Version found on disk.
83 found: u32,
84 /// Version this build supports.
85 supported: u32,
86 },
87 /// The requested artifact is not part of this capsule's sealed result.
88 #[error("artifact not found: {0}")]
89 ArtifactNotFound(String),
90 /// An exported receipt failed verification.
91 #[error("bundle verification failed: {0}")]
92 Verification(String),
93 /// A filesystem operation failed.
94 #[error("I/O error at {path}: {source}")]
95 Io {
96 /// Path being operated on.
97 path: PathBuf,
98 /// Underlying failure.
99 #[source]
100 source: std::io::Error,
101 },
102 /// Stored or supplied JSON could not be decoded or encoded.
103 #[error("invalid JSON at {path}: {source}")]
104 Json {
105 /// Path the JSON came from.
106 path: PathBuf,
107 /// Underlying failure.
108 #[source]
109 source: serde_json::Error,
110 },
111 /// An internal thread draining Git output failed.
112 #[error("internal worker failed while capturing Git output")]
113 CaptureWorker,
114}
115
116/// Convenience alias for results produced by this crate.
117pub type Result<T> = std::result::Result<T, Error>;
118
119pub(crate) fn io(path: impl Into<PathBuf>, source: std::io::Error) -> Error {
120 Error::Io {
121 path: path.into(),
122 source,
123 }
124}