Skip to main content

tmux_client/
error.rs

1//! Errors returned by the library.
2
3use std::io;
4use std::time::Duration;
5
6use thiserror::Error;
7
8use crate::{CommandResult, CommandSummary, ReleaseVersion, TmuxVersion};
9
10/// A result returned by `tmux-client`.
11pub type Result<T> = std::result::Result<T, Error>;
12
13/// The kind of tmux object involved in an error.
14#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
15pub enum ObjectKind {
16    /// A server.
17    Server,
18    /// A session.
19    Session,
20    /// A window.
21    Window,
22    /// A pane.
23    Pane,
24    /// A client.
25    Client,
26    /// A buffer.
27    Buffer,
28}
29
30impl std::fmt::Display for ObjectKind {
31    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
32        formatter.write_str(match self {
33            Self::Server => "server",
34            Self::Session => "session",
35            Self::Window => "window",
36            Self::Pane => "pane",
37            Self::Client => "client",
38            Self::Buffer => "buffer",
39        })
40    }
41}
42
43/// A category of option parsing or mutation failure.
44#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
45pub enum OptionErrorKind {
46    /// An option value could not be parsed.
47    Parse,
48    /// An option value had an unsupported representation.
49    Unsupported,
50    /// An indexed option was malformed.
51    SparseIndex,
52}
53
54impl std::fmt::Display for OptionErrorKind {
55    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56        formatter.write_str(match self {
57            Self::Parse => "parse",
58            Self::Unsupported => "unsupported",
59            Self::SparseIndex => "sparse-index",
60        })
61    }
62}
63
64/// A non-exhaustive error produced by configuration, execution, or parsing.
65#[derive(Debug, Error)]
66#[non_exhaustive]
67pub enum Error {
68    /// The configured tmux executable was not found.
69    #[error("tmux executable {executable:?} was not found")]
70    ExecutableNotFound {
71        /// The configured executable path.
72        executable: std::path::PathBuf,
73    },
74
75    /// A process or file operation failed.
76    #[error("{operation} failed: {source}")]
77    Io {
78        /// A static operation name.
79        operation: &'static str,
80        /// The underlying operating-system error.
81        #[source]
82        source: io::Error,
83    },
84
85    /// A command exceeded the configured timeout.
86    #[error("tmux command `{summary}` timed out after {timeout:?}")]
87    Timeout {
88        /// The redacted command description.
89        summary: CommandSummary,
90        /// The configured timeout.
91        timeout: Duration,
92    },
93
94    /// tmux returned a non-zero status for a typed operation.
95    #[error("tmux {operation} failed: {result:?}")]
96    CommandFailed {
97        /// The attempted high-level operation.
98        operation: &'static str,
99        /// The complete byte-preserving result.
100        result: Box<CommandResult>,
101    },
102
103    /// No tmux server was available on the requested socket.
104    #[error("no tmux server is available: {message}")]
105    ServerUnavailable {
106        /// Diagnostic text returned by tmux.
107        message: String,
108    },
109
110    /// A requested tmux object did not exist.
111    #[error("{kind} {target} was not found")]
112    ObjectNotFound {
113        /// The expected object kind.
114        kind: ObjectKind,
115        /// The target used for lookup.
116        target: String,
117    },
118
119    /// A lookup that expected one object returned multiple objects.
120    #[error("query `{query}` matched {count} {kind} objects")]
121    MultipleObjects {
122        /// The object kind.
123        kind: ObjectKind,
124        /// The number of matches.
125        count: usize,
126        /// A redacted query description.
127        query: String,
128    },
129
130    /// An ID did not use the required prefix and numeric suffix.
131    #[error("invalid {kind} ID `{value}`")]
132    InvalidId {
133        /// The ID kind.
134        kind: &'static str,
135        /// The invalid representation.
136        value: String,
137    },
138
139    /// A session name used tmux-reserved target punctuation.
140    #[error("invalid tmux session name `{0}`")]
141    InvalidSessionName(String),
142
143    /// A public argument did not satisfy its contract.
144    #[error("invalid {argument}: {message}")]
145    InvalidArgument {
146        /// The argument name.
147        argument: &'static str,
148        /// The validation failure.
149        message: String,
150    },
151
152    /// tmux returned an unrecognized version.
153    #[error("invalid tmux version `{0}`")]
154    InvalidVersion(String),
155
156    /// The connected tmux version lacks a requested capability.
157    #[error("{capability} requires tmux {required} or newer, found {found}")]
158    Unsupported {
159        /// The requested operation or field.
160        capability: &'static str,
161        /// The minimum release.
162        required: ReleaseVersion,
163        /// The actual connected version.
164        found: TmuxVersion,
165    },
166
167    /// Structured tmux output could not be decoded.
168    #[error("could not decode {context}: {message}")]
169    Decode {
170        /// The output family being decoded.
171        context: &'static str,
172        /// A safe explanation without untrusted output interpolation.
173        message: String,
174    },
175
176    /// An option value or index was invalid.
177    #[error("option {kind} error: {message}")]
178    Option {
179        /// The failure category.
180        kind: OptionErrorKind,
181        /// The failure description.
182        message: String,
183    },
184
185    /// An operation required being inside an attached tmux client.
186    #[error("the operation requires an attached tmux client")]
187    NotInsideTmux,
188
189    /// A wait condition expired before it was satisfied.
190    #[error("timed out waiting for {condition}")]
191    WaitTimeout {
192        /// A description of the condition.
193        condition: String,
194    },
195
196    /// The main operation succeeded but deterministic cleanup failed.
197    #[error("cleanup after {operation} failed: {source}")]
198    Cleanup {
199        /// The operation whose scope was being cleaned up.
200        operation: &'static str,
201        /// The cleanup error.
202        #[source]
203        source: Box<Error>,
204    },
205}