Skip to main content

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}