Skip to main content

rcp/
types.rs

1//! types.rs — the RCP/1 wire vocabulary: protocol version, capabilities,
2//! methods, error codes, and the typed error. Values mirror the C++, Python, and
3//! Node.js SDKs byte-for-byte on the wire.
4
5use crate::json::Json;
6use std::fmt;
7
8/// The protocol version this SDK speaks.
9pub const PROTOCOL_VERSION: i64 = 1;
10/// The lowest protocol version this SDK will accept.
11pub const MIN_PROTOCOL_VERSION: i64 = 1;
12
13/// `min(peer, ours)`, clamped — mirrors `rcp::negotiate_version`.
14pub fn negotiate_version(theirs: i64) -> i64 {
15    if theirs < PROTOCOL_VERSION {
16        theirs
17    } else {
18        PROTOCOL_VERSION
19    }
20}
21
22/// The capability lattice (spec §7.2). Each variant maps to a wire JSON key.
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
24pub enum Capability {
25    Embed,
26    SparseEmbed,
27    MultiVector,
28    Rerank,
29    Retrieve,
30    Transform,
31    Graph,
32    Index,
33    Session,
34    Feedback,
35    Memory,
36    Filter,
37    Streaming,
38    Pagination,
39    Citations,
40    Log,
41    Catalog,
42}
43
44impl Capability {
45    /// The wire JSON key for this capability.
46    pub fn wire_key(self) -> &'static str {
47        match self {
48            Capability::Embed => "embed",
49            Capability::SparseEmbed => "sparseEmbed",
50            Capability::MultiVector => "multiVector",
51            Capability::Rerank => "rerank",
52            Capability::Retrieve => "retrieve",
53            Capability::Transform => "transform",
54            Capability::Graph => "graph",
55            Capability::Index => "index",
56            Capability::Session => "session",
57            Capability::Feedback => "feedback",
58            Capability::Memory => "memory",
59            Capability::Filter => "filter",
60            Capability::Streaming => "streaming",
61            Capability::Pagination => "pagination",
62            Capability::Citations => "citations",
63            Capability::Log => "log",
64            Capability::Catalog => "catalog",
65        }
66    }
67
68    /// Every capability, for iteration.
69    pub const ALL: [Capability; 17] = [
70        Capability::Embed,
71        Capability::SparseEmbed,
72        Capability::MultiVector,
73        Capability::Rerank,
74        Capability::Retrieve,
75        Capability::Transform,
76        Capability::Graph,
77        Capability::Index,
78        Capability::Session,
79        Capability::Feedback,
80        Capability::Memory,
81        Capability::Filter,
82        Capability::Streaming,
83        Capability::Pagination,
84        Capability::Citations,
85        Capability::Log,
86        Capability::Catalog,
87    ];
88}
89
90/// RCP/1 method names (spec §9). String constants — usable anywhere a method
91/// name is expected (`server.on(Method::RETRIEVE, …)` or `server.on("retrieve", …)`).
92pub struct Method;
93
94impl Method {
95    pub const INITIALIZE: &'static str = "initialize";
96    pub const INFO: &'static str = "info";
97    pub const EMBED: &'static str = "embed";
98    pub const EMBED_SPARSE: &'static str = "embed/sparse";
99    pub const EMBED_MULTI: &'static str = "embed/multi";
100    pub const RERANK: &'static str = "rerank";
101    pub const RETRIEVE: &'static str = "retrieve";
102    pub const TRANSFORM: &'static str = "query/transform";
103    pub const GRAPH: &'static str = "graph";
104    pub const INDEX_ADD: &'static str = "index/add";
105    pub const INDEX_DELETE: &'static str = "index/delete";
106    pub const FEEDBACK: &'static str = "feedback";
107    pub const MEMORY_BUILD: &'static str = "memory/build";
108    pub const MEMORY_RECALL: &'static str = "memory/recall";
109    pub const CATALOG_LIST: &'static str = "catalog/list";
110    pub const CANCEL: &'static str = "notifications/cancel";
111    pub const PROGRESS: &'static str = "notifications/progress";
112    pub const LOG: &'static str = "notifications/log";
113    pub const PING: &'static str = "ping";
114    pub const SHUTDOWN: &'static str = "shutdown";
115}
116
117/// RCP/1 error codes (spec §12). `-326xx` are JSON-RPC; `-320xx` are RCP-specific.
118pub struct Errc;
119
120impl Errc {
121    pub const PARSE_ERROR: i64 = -32700;
122    pub const INVALID_REQUEST: i64 = -32600;
123    pub const METHOD_NOT_FOUND: i64 = -32601;
124    pub const INVALID_PARAMS: i64 = -32602;
125    pub const INTERNAL_ERROR: i64 = -32603;
126    pub const NOT_INITIALIZED: i64 = -32001;
127    pub const VERSION_MISMATCH: i64 = -32002;
128    pub const CAPABILITY_MISSING: i64 = -32003;
129    pub const UNKNOWN_METHOD: i64 = -32004;
130    pub const OPTION_UNSUPPORTED: i64 = -32005;
131    pub const CANCELLED: i64 = -32006;
132    pub const BACKEND_UNAVAILABLE: i64 = -32010;
133    pub const RATE_LIMITED: i64 = -32011;
134    pub const UNAUTHORIZED: i64 = -32012;
135    pub const PAYLOAD_TOO_LARGE: i64 = -32013;
136    pub const TIMEOUT: i64 = -32014;
137    pub const NOT_FOUND: i64 = -32015;
138    pub const CONFLICT: i64 = -32016;
139}
140
141/// An RCP protocol or transport error.
142///
143/// `Display` renders `"[RCP <code>] <message>"` (matching every other SDK), and
144/// the error carries the structured `data` payload (spec §12) plus retry hints.
145#[derive(Clone, Debug)]
146pub struct RcpError {
147    pub code: i64,
148    pub message: String,
149    pub data: Option<Json>,
150}
151
152impl RcpError {
153    pub fn new(code: i64, message: impl Into<String>) -> RcpError {
154        RcpError {
155            code,
156            message: message.into(),
157            data: None,
158        }
159    }
160
161    pub fn with_data(code: i64, message: impl Into<String>, data: Json) -> RcpError {
162        RcpError {
163            code,
164            message: message.into(),
165            data: Some(data),
166        }
167    }
168
169    /// RateLimited / BackendUnavailable / Timeout are transient by default; an
170    /// explicit `data.retryable` overrides the code-based default (spec §12).
171    pub fn retryable(&self) -> bool {
172        if let Some(d) = &self.data {
173            if let Some(b) = d.get("retryable").and_then(|v| v.as_bool()) {
174                return b;
175            }
176        }
177        self.code == Errc::RATE_LIMITED
178            || self.code == Errc::BACKEND_UNAVAILABLE
179            || self.code == Errc::TIMEOUT
180    }
181
182    /// Server-suggested backoff in ms (`data.retryAfterMs`), or `-1`.
183    pub fn retry_after_ms(&self) -> i64 {
184        self.data
185            .as_ref()
186            .and_then(|d| d.get("retryAfterMs"))
187            .and_then(|v| v.as_i64())
188            .unwrap_or(-1)
189    }
190
191    /// Build an `RcpError` from a JSON-RPC `error` object.
192    pub fn from_json(err: &Json) -> RcpError {
193        RcpError {
194            code: err.get("code").and_then(|v| v.as_i64()).unwrap_or(Errc::INTERNAL_ERROR),
195            message: err
196                .get("message")
197                .and_then(|v| v.as_str())
198                .unwrap_or("error")
199                .to_string(),
200            data: err.get("data").cloned(),
201        }
202    }
203}
204
205impl fmt::Display for RcpError {
206    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
207        write!(f, "[RCP {}] {}", self.code, self.message)
208    }
209}
210
211impl std::error::Error for RcpError {}
212
213/// Which capability gates which method (spec §7.2 / §9).
214pub fn cap_for_method(method: &str) -> Option<Capability> {
215    Some(match method {
216        Method::EMBED => Capability::Embed,
217        Method::EMBED_SPARSE => Capability::SparseEmbed,
218        Method::EMBED_MULTI => Capability::MultiVector,
219        Method::RERANK => Capability::Rerank,
220        Method::RETRIEVE => Capability::Retrieve,
221        Method::TRANSFORM => Capability::Transform,
222        Method::GRAPH => Capability::Graph,
223        Method::INDEX_ADD | Method::INDEX_DELETE => Capability::Index,
224        Method::FEEDBACK => Capability::Feedback,
225        Method::MEMORY_BUILD | Method::MEMORY_RECALL => Capability::Memory,
226        Method::CATALOG_LIST => Capability::Catalog,
227        _ => return None,
228    })
229}