kaish_client/
traits.rs

1//! Common trait for kernel clients.
2
3use async_trait::async_trait;
4use thiserror::Error;
5
6use kaish_kernel::ast::Value;
7use kaish_kernel::interpreter::ExecResult;
8
9/// Result type for client operations.
10pub type ClientResult<T> = Result<T, ClientError>;
11
12/// Errors that can occur when using a kernel client.
13#[derive(Debug, Error)]
14pub enum ClientError {
15    /// Connection to the kernel failed.
16    #[error("connection error: {0}")]
17    Connection(String),
18
19    /// The kernel returned an error during execution.
20    #[error("execution error: {0}")]
21    Execution(String),
22
23    /// I/O error.
24    #[error("io error: {0}")]
25    Io(#[from] std::io::Error),
26
27    /// UTF-8 decoding error.
28    #[error("utf8 error: {0}")]
29    Utf8(#[from] std::str::Utf8Error),
30
31    /// The kernel is not connected.
32    #[error("not connected")]
33    NotConnected,
34
35    /// Other errors.
36    #[error("{0}")]
37    Other(#[from] anyhow::Error),
38}
39
40/// Common interface for interacting with a kaish kernel.
41///
42/// Both `EmbeddedClient` and custom client implementations can implement this trait,
43/// allowing code to work with any client type.
44#[async_trait(?Send)]
45pub trait KernelClient {
46    /// Execute kaish source code.
47    ///
48    /// Returns the result of the last statement executed.
49    async fn execute(&self, input: &str) -> ClientResult<ExecResult>;
50
51    /// Get a variable value.
52    async fn get_var(&self, name: &str) -> ClientResult<Option<Value>>;
53
54    /// Set a variable value.
55    async fn set_var(&self, name: &str, value: Value) -> ClientResult<()>;
56
57    /// List all variables.
58    async fn list_vars(&self) -> ClientResult<Vec<(String, Value)>>;
59
60    /// Get the current working directory.
61    async fn cwd(&self) -> ClientResult<String>;
62
63    /// Set the current working directory.
64    async fn set_cwd(&self, path: &str) -> ClientResult<()>;
65
66    /// Get the last execution result ($?).
67    async fn last_result(&self) -> ClientResult<ExecResult>;
68
69    /// Reset the kernel to initial state.
70    async fn reset(&self) -> ClientResult<()>;
71
72    /// Ping the kernel (health check).
73    async fn ping(&self) -> ClientResult<String>;
74
75    /// Shutdown the kernel.
76    async fn shutdown(&self) -> ClientResult<()>;
77
78    /// Read a blob by ID.
79    ///
80    /// Returns the blob contents as raw bytes.
81    async fn read_blob(&self, id: &str) -> ClientResult<Vec<u8>>;
82
83    /// Write a blob and return its ID.
84    ///
85    /// The blob is stored in `/v/blobs/{id}` and can be referenced via BlobRef.
86    async fn write_blob(&self, content_type: &str, data: &[u8]) -> ClientResult<String>;
87
88    /// Delete a blob by ID.
89    ///
90    /// Returns true if the blob was deleted, false if it didn't exist.
91    async fn delete_blob(&self, id: &str) -> ClientResult<bool>;
92}
kaish_client/traits.rs

kaish_client/
traits.rs
