lightshuttle_runtime/
error.rs

1//! Error types returned by container runtime operations.
2//!
3//! All fallible runtime methods return [`Result<T>`], which is a type alias
4//! for `std::result::Result<T, RuntimeError>`.
5
6use std::time::Duration;
7
8/// Shorthand alias for `std::result::Result<T, `[`RuntimeError`]`>`.
9///
10/// Used throughout this crate so callers never have to spell out the full
11/// error type on every return position.
12pub type Result<T> = std::result::Result<T, RuntimeError>;
13
14/// Errors raised by a [`crate::ContainerRuntime`] implementation.
15#[derive(Debug, thiserror::Error)]
16pub enum RuntimeError {
17    /// The runtime could not establish a connection to the underlying
18    /// container daemon (Docker socket, Podman API, ...).
19    #[error("failed to connect to the container runtime")]
20    Connect(#[source] bollard::errors::Error),
21
22    /// Pulling an image from the registry failed.
23    #[error("failed to pull image `{image}`")]
24    ImagePull {
25        /// The image reference that the runtime tried to pull.
26        image: String,
27        /// Underlying error from the container daemon.
28        #[source]
29        source: bollard::errors::Error,
30    },
31
32    /// The runtime refused to start the container.
33    #[error("failed to start container")]
34    Start(#[source] bollard::errors::Error),
35
36    /// The runtime refused to stop a container.
37    #[error("failed to stop container `{id}`")]
38    Stop {
39        /// Identifier of the container that could not be stopped.
40        id: String,
41        /// Underlying error from the container daemon.
42        #[source]
43        source: bollard::errors::Error,
44    },
45
46    /// The runtime refused to remove a container.
47    #[error("failed to remove container `{name}`")]
48    Remove {
49        /// Name of the container that could not be removed.
50        name: String,
51        /// Underlying error from the container daemon.
52        #[source]
53        source: bollard::errors::Error,
54    },
55
56    /// The runtime could not inspect a container.
57    #[error("failed to inspect container `{id}`")]
58    Inspect {
59        /// Identifier of the container that could not be inspected.
60        id: String,
61        /// Underlying error from the container daemon.
62        #[source]
63        source: bollard::errors::Error,
64    },
65
66    /// The container does not exist on the daemon.
67    #[error("container `{0}` not found")]
68    NotFound(String),
69
70    /// A blocking operation exceeded its allotted time budget.
71    #[error("operation `{operation}` timed out after {after:?}")]
72    Timeout {
73        /// Short name of the operation that timed out.
74        operation: &'static str,
75        /// Configured timeout.
76        after: Duration,
77    },
78
79    /// Streaming logs from a container failed mid-flight.
80    #[error("log stream error")]
81    LogStream(#[source] bollard::errors::Error),
82
83    /// Creating the per-project Docker bridge network failed.
84    #[error("failed to create network `{name}`")]
85    NetworkCreate {
86        /// Name of the network that could not be created.
87        name: String,
88        /// Underlying error from the container daemon.
89        #[source]
90        source: bollard::errors::Error,
91    },
92
93    /// Removing the per-project Docker bridge network failed.
94    #[error("failed to remove network `{name}`")]
95    NetworkRemove {
96        /// Name of the network that could not be removed.
97        name: String,
98        /// Underlying error from the container daemon.
99        #[source]
100        source: bollard::errors::Error,
101    },
102
103    /// Building an image from a Dockerfile failed.
104    #[error("failed to build image from Dockerfile")]
105    Build(#[source] bollard::errors::Error),
106
107    /// The `BuildKit` builder reported a failure in its progress stream.
108    #[error("image build failed: {0}")]
109    BuildFailed(String),
110
111    /// The provided [`crate::ContainerSpec`] is structurally invalid.
112    #[error("invalid container spec: {0}")]
113    InvalidSpec(String),
114}
lightshuttle_runtime/error.rs

lightshuttle_runtime/
error.rs
