microsandbox_agent_client/
error.rs

1//! Error type for the agent client.
2
3use std::path::PathBuf;
4
5//--------------------------------------------------------------------------------------------------
6// Types
7//--------------------------------------------------------------------------------------------------
8
9/// Result alias for agent client operations.
10pub type AgentClientResult<T> = std::result::Result<T, AgentClientError>;
11
12/// Errors raised by [`AgentClient`](super::AgentClient).
13#[derive(Debug, thiserror::Error)]
14pub enum AgentClientError {
15    /// Failed to open the Unix socket connection to the relay.
16    #[error("connect {path}: {source}")]
17    Connect {
18        /// Socket path that was attempted.
19        path: PathBuf,
20        /// Underlying I/O error.
21        #[source]
22        source: std::io::Error,
23    },
24
25    /// Handshake with the relay failed (timeout, EOF, or malformed frame).
26    #[error("handshake: {0}")]
27    Handshake(String),
28
29    /// Sandbox name could not be resolved to an agent socket path.
30    #[error("sandbox '{0}' not found")]
31    SandboxNotFound(String),
32
33    /// Sandbox name failed SDK validation before socket resolution.
34    #[error("invalid sandbox name: {0}")]
35    InvalidSandboxName(String),
36
37    /// An I/O error occurred on the socket after connect.
38    #[error("io: {0}")]
39    Io(#[from] std::io::Error),
40
41    /// A WebSocket transport error occurred.
42    #[error("websocket: {0}")]
43    WebSocket(String),
44
45    /// A wire-protocol error (framing, CBOR, oversize frame).
46    #[error("protocol: {0}")]
47    Protocol(#[from] microsandbox_protocol::ProtocolError),
48
49    /// CBOR encoding or decoding failed.
50    #[error("cbor: {0}")]
51    Cbor(String),
52
53    /// The supplied packet did not contain exactly one complete transport frame.
54    #[error("invalid transport packet: {0}")]
55    InvalidPacket(String),
56
57    /// The connected sandbox's runtime is older than the requested feature
58    /// needs.
59    ///
60    /// Raised before any bytes go out, so a feature the runtime is too old to
61    /// handle fails on its own without disturbing the rest of the session.
62    /// Restarting the sandbox re-provisions agentd at the current version, which
63    /// is the fix. See `VERSIONING.md` in `microsandbox-protocol`.
64    #[error(
65        "the sandbox runtime is too old for '{msg_type}' (needs protocol generation {needs}, the sandbox speaks {peer}); restart the sandbox to update its runtime"
66    )]
67    UnsupportedOperation {
68        /// Wire name of the message type that was gated.
69        msg_type: &'static str,
70        /// Generation the message type was introduced in.
71        needs: u8,
72        /// Generation negotiated with the connected sandbox.
73        peer: u8,
74    },
75
76    /// The reader task closed (socket EOF or client closed) before the
77    /// in-flight request received its response.
78    #[error("reader closed before response for id={0}")]
79    ReaderClosed(u32),
80
81    /// The client has been closed.
82    #[error("client closed")]
83    Closed,
84
85    /// The relay-assigned correlation ID range has no available IDs.
86    #[error("agent correlation id range exhausted")]
87    IdRangeExhausted,
88
89    /// The operation is not implemented yet.
90    #[error("not implemented: {0}")]
91    NotImplemented(&'static str),
92}
microsandbox_agent_client/error.rs

microsandbox_agent_client/
error.rs
