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

microsandbox_agent_client/
error.rs
