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 wire-protocol error (framing, CBOR, oversize frame).
42    #[error("protocol: {0}")]
43    Protocol(#[from] microsandbox_protocol::ProtocolError),
44
45    /// CBOR encoding or decoding failed.
46    #[error("cbor: {0}")]
47    Cbor(String),
48
49    /// The supplied packet did not contain exactly one complete transport frame.
50    #[error("invalid transport packet: {0}")]
51    InvalidPacket(String),
52
53    /// The connected sandbox's runtime is older than the requested feature
54    /// needs.
55    ///
56    /// Raised before any bytes go out, so a feature the runtime is too old to
57    /// handle fails on its own without disturbing the rest of the session.
58    /// Restarting the sandbox re-provisions agentd at the current version, which
59    /// is the fix. See `VERSIONING.md` in `microsandbox-protocol`.
60    #[error(
61        "the sandbox runtime is too old for '{msg_type}' (needs protocol generation {needs}, the sandbox speaks {peer}); restart the sandbox to update its runtime"
62    )]
63    UnsupportedOperation {
64        /// Wire name of the message type that was gated.
65        msg_type: &'static str,
66        /// Generation the message type was introduced in.
67        needs: u8,
68        /// Generation negotiated with the connected sandbox.
69        peer: u8,
70    },
71
72    /// The reader task closed (socket EOF or client closed) before the
73    /// in-flight request received its response.
74    #[error("reader closed before response for id={0}")]
75    ReaderClosed(u32),
76
77    /// The client has been closed.
78    #[error("client closed")]
79    Closed,
80
81    /// The relay-assigned correlation ID range has no available IDs.
82    #[error("agent correlation id range exhausted")]
83    IdRangeExhausted,
84
85    /// The operation is not implemented yet.
86    #[error("not implemented: {0}")]
87    NotImplemented(&'static str),
88}
microsandbox_agent_client/error.rs

microsandbox_agent_client/
error.rs
