vtcode_acp_client/
jsonrpc.rs

1//! JSON-RPC 2.0 types for ACP protocol compliance
2//!
3//! This module implements the JSON-RPC 2.0 specification as required by the
4//! Agent Client Protocol (ACP). All ACP methods use JSON-RPC 2.0 as the
5//! transport layer.
6//!
7//! Reference: https://agentclientprotocol.com/llms.txt
8
9use serde::{Deserialize, Serialize};
10use serde_json::Value;
11
12/// JSON-RPC 2.0 version string (always "2.0")
13pub const JSONRPC_VERSION: &str = "2.0";
14
15/// JSON-RPC 2.0 request object
16#[derive(Debug, Clone, Serialize, Deserialize)]
17pub struct JsonRpcRequest {
18    /// Protocol version (always "2.0")
19    pub jsonrpc: String,
20
21    /// Method name to invoke
22    pub method: String,
23
24    /// Method parameters (positional or named)
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub params: Option<Value>,
27
28    /// Request ID for correlation (null for notifications)
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub id: Option<JsonRpcId>,
31}
32
33/// JSON-RPC 2.0 response object
34#[derive(Debug, Clone, Serialize, Deserialize)]
35pub struct JsonRpcResponse {
36    /// Protocol version (always "2.0")
37    pub jsonrpc: String,
38
39    /// Result on success (mutually exclusive with error)
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub result: Option<Value>,
42
43    /// Error on failure (mutually exclusive with result)
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub error: Option<JsonRpcError>,
46
47    /// Request ID this response corresponds to
48    pub id: Option<JsonRpcId>,
49}
50
51/// JSON-RPC 2.0 error object
52#[derive(Debug, Clone, Serialize, Deserialize)]
53pub struct JsonRpcError {
54    /// Error code (integer)
55    pub code: i32,
56
57    /// Short error description
58    pub message: String,
59
60    /// Additional error data
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub data: Option<Value>,
63}
64
65/// JSON-RPC 2.0 request/response ID
66///
67/// Per spec, ID can be a string, number, or null
68#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
69#[serde(untagged)]
70pub enum JsonRpcId {
71    /// String ID
72    String(String),
73    /// Numeric ID
74    Number(i64),
75}
76
77impl JsonRpcId {
78    /// Create a new string ID
79    pub fn string(s: impl Into<String>) -> Self {
80        Self::String(s.into())
81    }
82
83    /// Create a new numeric ID
84    pub fn number(n: i64) -> Self {
85        Self::Number(n)
86    }
87
88    /// Generate a new UUID-based string ID
89    pub fn new_uuid() -> Self {
90        Self::String(uuid::Uuid::new_v4().to_string())
91    }
92}
93
94impl std::fmt::Display for JsonRpcId {
95    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
96        match self {
97            JsonRpcId::String(s) => write!(f, "{}", s),
98            JsonRpcId::Number(n) => write!(f, "{}", n),
99        }
100    }
101}
102
103/// Standard JSON-RPC 2.0 error codes
104pub mod error_codes {
105    /// Parse error: Invalid JSON was received
106    pub const PARSE_ERROR: i32 = -32700;
107
108    /// Invalid request: The JSON sent is not a valid Request object
109    pub const INVALID_REQUEST: i32 = -32600;
110
111    /// Method not found: The method does not exist / is not available
112    pub const METHOD_NOT_FOUND: i32 = -32601;
113
114    /// Invalid params: Invalid method parameter(s)
115    pub const INVALID_PARAMS: i32 = -32602;
116
117    /// Internal error: Internal JSON-RPC error
118    pub const INTERNAL_ERROR: i32 = -32603;
119
120    /// Server error range: -32000 to -32099 (reserved for implementation-defined server-errors)
121    pub const SERVER_ERROR_START: i32 = -32099;
122    pub const SERVER_ERROR_END: i32 = -32000;
123
124    // ACP-specific error codes (in server error range)
125
126    /// Authentication required
127    pub const AUTH_REQUIRED: i32 = -32001;
128
129    /// Permission denied
130    pub const PERMISSION_DENIED: i32 = -32002;
131
132    /// Session not found
133    pub const SESSION_NOT_FOUND: i32 = -32003;
134
135    /// Rate limited
136    pub const RATE_LIMITED: i32 = -32004;
137
138    /// Resource not found
139    pub const RESOURCE_NOT_FOUND: i32 = -32005;
140}
141
142impl JsonRpcRequest {
143    /// Create a new JSON-RPC 2.0 request
144    pub fn new(method: impl Into<String>, params: Option<Value>, id: Option<JsonRpcId>) -> Self {
145        Self {
146            jsonrpc: JSONRPC_VERSION.to_string(),
147            method: method.into(),
148            params,
149            id,
150        }
151    }
152
153    /// Create a request with auto-generated UUID ID
154    pub fn with_uuid(method: impl Into<String>, params: Option<Value>) -> Self {
155        Self::new(method, params, Some(JsonRpcId::new_uuid()))
156    }
157
158    /// Create a notification (request without ID, no response expected)
159    pub fn notification(method: impl Into<String>, params: Option<Value>) -> Self {
160        Self::new(method, params, None)
161    }
162
163    /// Check if this is a notification (no ID means no response expected)
164    pub fn is_notification(&self) -> bool {
165        self.id.is_none()
166    }
167}
168
169impl JsonRpcResponse {
170    /// Create a successful response
171    pub fn success(result: Value, id: Option<JsonRpcId>) -> Self {
172        Self {
173            jsonrpc: JSONRPC_VERSION.to_string(),
174            result: Some(result),
175            error: None,
176            id,
177        }
178    }
179
180    /// Create an error response
181    pub fn error(error: JsonRpcError, id: Option<JsonRpcId>) -> Self {
182        Self {
183            jsonrpc: JSONRPC_VERSION.to_string(),
184            result: None,
185            error: Some(error),
186            id,
187        }
188    }
189
190    /// Check if response is successful
191    pub fn is_success(&self) -> bool {
192        self.error.is_none() && self.result.is_some()
193    }
194
195    /// Check if response is an error
196    pub fn is_error(&self) -> bool {
197        self.error.is_some()
198    }
199
200    /// Get result, returning error if response was an error
201    pub fn into_result(self) -> Result<Value, JsonRpcError> {
202        if let Some(error) = self.error {
203            Err(error)
204        } else {
205            Ok(self.result.unwrap_or(Value::Null))
206        }
207    }
208}
209
210impl JsonRpcError {
211    /// Create a new error
212    pub fn new(code: i32, message: impl Into<String>) -> Self {
213        Self {
214            code,
215            message: message.into(),
216            data: None,
217        }
218    }
219
220    /// Create error with additional data
221    pub fn with_data(code: i32, message: impl Into<String>, data: Value) -> Self {
222        Self {
223            code,
224            message: message.into(),
225            data: Some(data),
226        }
227    }
228
229    /// Create a parse error
230    pub fn parse_error(details: impl Into<String>) -> Self {
231        Self::new(error_codes::PARSE_ERROR, details)
232    }
233
234    /// Create an invalid request error
235    pub fn invalid_request(details: impl Into<String>) -> Self {
236        Self::new(error_codes::INVALID_REQUEST, details)
237    }
238
239    /// Create a method not found error
240    pub fn method_not_found(method: impl Into<String>) -> Self {
241        Self::new(
242            error_codes::METHOD_NOT_FOUND,
243            format!("Method not found: {}", method.into()),
244        )
245    }
246
247    /// Create an invalid params error
248    pub fn invalid_params(details: impl Into<String>) -> Self {
249        Self::new(error_codes::INVALID_PARAMS, details)
250    }
251
252    /// Create an internal error
253    pub fn internal_error(details: impl Into<String>) -> Self {
254        Self::new(error_codes::INTERNAL_ERROR, details)
255    }
256
257    /// Create an authentication required error with list of available methods
258    /// 
259    /// Per ACP spec, includes authMethods in error data to help clients
260    /// present appropriate UI for authentication options.
261    pub fn auth_required(auth_methods: Vec<super::AuthMethod>) -> Self {
262        let data = serde_json::json!({
263            "authMethods": auth_methods,
264        });
265        Self::with_data(
266            error_codes::AUTH_REQUIRED,
267            "Authentication required",
268            data,
269        )
270    }
271
272    /// Create a permission denied error
273    pub fn permission_denied(details: impl Into<String>) -> Self {
274        Self::new(error_codes::PERMISSION_DENIED, details)
275    }
276
277    /// Create a session not found error
278    pub fn session_not_found(session_id: impl Into<String>) -> Self {
279        Self::new(
280            error_codes::SESSION_NOT_FOUND,
281            format!("Session not found: {}", session_id.into()),
282        )
283    }
284
285    /// Create a rate limited error
286    pub fn rate_limited(details: impl Into<String>) -> Self {
287        Self::new(error_codes::RATE_LIMITED, details)
288    }
289
290    /// Create a resource not found error
291    pub fn resource_not_found(resource: impl Into<String>) -> Self {
292        Self::new(
293            error_codes::RESOURCE_NOT_FOUND,
294            format!("Resource not found: {}", resource.into()),
295        )
296    }
297}
298
299#[cfg(test)]
300mod tests {
301    use super::*;
302    use serde_json::json;
303
304    #[test]
305    fn test_request_serialization() {
306        let req = JsonRpcRequest::new(
307            "initialize",
308            Some(json!({"protocolVersions": ["2025-01-01"]})),
309            Some(JsonRpcId::string("req-1")),
310        );
311
312        let json = serde_json::to_string(&req).unwrap();
313        assert!(json.contains("\"jsonrpc\":\"2.0\""));
314        assert!(json.contains("\"method\":\"initialize\""));
315        assert!(json.contains("\"id\":\"req-1\""));
316    }
317
318    #[test]
319    fn test_response_success() {
320        let resp = JsonRpcResponse::success(
321            json!({"session_id": "sess-123"}),
322            Some(JsonRpcId::string("req-1")),
323        );
324
325        assert!(resp.is_success());
326        assert!(!resp.is_error());
327    }
328
329    #[test]
330    fn test_response_error() {
331        let resp = JsonRpcResponse::error(
332            JsonRpcError::method_not_found("unknown"),
333            Some(JsonRpcId::string("req-1")),
334        );
335
336        assert!(resp.is_error());
337        assert!(!resp.is_success());
338    }
339
340    #[test]
341    fn test_notification() {
342        let notif = JsonRpcRequest::notification("session/update", Some(json!({"delta": "hello"})));
343
344        assert!(notif.is_notification());
345        assert!(notif.id.is_none());
346    }
347
348    #[test]
349    fn test_id_types() {
350        let string_id = JsonRpcId::string("abc");
351        let number_id = JsonRpcId::number(123);
352
353        assert_eq!(format!("{}", string_id), "abc");
354        assert_eq!(format!("{}", number_id), "123");
355    }
356
357    #[test]
358    fn test_auth_required_error() {
359        use super::super::AuthMethod;
360
361        let auth_methods = vec![
362            AuthMethod::Agent {
363                id: "agent_auth".to_string(),
364                name: "Agent Auth".to_string(),
365                description: None,
366            },
367            AuthMethod::EnvVar {
368                id: "openai_key".to_string(),
369                name: "OpenAI Key".to_string(),
370                description: None,
371                var_name: "OPENAI_API_KEY".to_string(),
372                link: None,
373            },
374        ];
375
376        let error = JsonRpcError::auth_required(auth_methods);
377        
378        assert_eq!(error.code, error_codes::AUTH_REQUIRED);
379        assert_eq!(error.message, "Authentication required");
380        assert!(error.data.is_some());
381
382        let data = error.data.unwrap();
383        assert!(data["authMethods"].is_array());
384        assert_eq!(data["authMethods"].as_array().unwrap().len(), 2);
385    }
386
387    #[test]
388    fn test_auth_required_error_serialization() {
389        use super::super::AuthMethod;
390
391        let auth_methods = vec![
392            AuthMethod::EnvVar {
393                id: "test".to_string(),
394                name: "Test".to_string(),
395                description: None,
396                var_name: "TEST_VAR".to_string(),
397                link: Some("https://example.com".to_string()),
398            },
399        ];
400
401        let error = JsonRpcError::auth_required(auth_methods);
402        let json = serde_json::to_value(&error).unwrap();
403
404        assert_eq!(json["code"], -32001);
405        assert_eq!(json["message"], "Authentication required");
406        assert_eq!(json["data"]["authMethods"][0]["type"], "env_var");
407        assert_eq!(json["data"]["authMethods"][0]["id"], "test");
408    }
409
410    #[test]
411    fn test_acp_error_helpers() {
412        let err_perm = JsonRpcError::permission_denied("Not allowed");
413        assert_eq!(err_perm.code, error_codes::PERMISSION_DENIED);
414
415        let err_session = JsonRpcError::session_not_found("sess-123");
416        assert_eq!(err_session.code, error_codes::SESSION_NOT_FOUND);
417        assert!(err_session.message.contains("sess-123"));
418
419        let err_rate = JsonRpcError::rate_limited("Too many requests");
420        assert_eq!(err_rate.code, error_codes::RATE_LIMITED);
421
422        let err_resource = JsonRpcError::resource_not_found("file.txt");
423        assert_eq!(err_resource.code, error_codes::RESOURCE_NOT_FOUND);
424        assert!(err_resource.message.contains("file.txt"));
425    }
426}
vtcode_acp_client/jsonrpc.rs

vtcode_acp_client/
jsonrpc.rs
