cas_serve/protocol.rs
1//! Wire protocol for cas-serve
2//!
3//! Uses newline-delimited JSON (NDJSON) for simplicity and debuggability.
4//! Each message is a single line of JSON followed by a newline.
5
6use serde::{Deserialize, Serialize};
7
8/// Request types that can be sent to cas-serve
9#[derive(Debug, Clone, Serialize, Deserialize)]
10#[serde(tag = "type", rename_all = "snake_case")]
11pub enum Request {
12 /// Download a file by its merkle hash
13 GetFile {
14 /// Hex-encoded merkle hash
15 hash: String,
16 },
17
18 /// Check if a XORB exists
19 Exists {
20 /// Hex-encoded merkle hash
21 hash: String,
22 },
23
24 /// Upload a XORB
25 UploadXorb {
26 /// Base64-encoded XORB data
27 data: String,
28 },
29
30 /// Upload a whole file. The server content-defined-chunks it (Gearhash
31 /// CDC), aggregates the chunks into xorbs (≤64 MiB / ≤8192 chunks each),
32 /// stores every xorb content-addressed under its xorb hash, and stores a
33 /// reconstruction shard (manifest) under the file's merkle hash. This is
34 /// the chunked-upload path that unblocks multi-xorb (>64 MiB) file
35 /// transfer (#390).
36 UploadFile {
37 /// Base64-encoded file data
38 data: String,
39 },
40
41 /// Get file reconstruction info (the reconstruction shard / manifest).
42 GetReconstructionInfo {
43 /// Hex-encoded file merkle hash
44 hash: String,
45 },
46
47 /// Ping to check if server is alive
48 Ping,
49
50 /// Graceful shutdown
51 Shutdown,
52}
53
54/// Response types returned by cas-serve
55#[derive(Debug, Clone, Serialize, Deserialize)]
56#[serde(tag = "type", rename_all = "snake_case")]
57pub enum Response {
58 /// Successful file retrieval
59 File {
60 /// Base64-encoded file data
61 data: String,
62 },
63
64 /// XORB existence check result
65 Exists {
66 /// Whether the XORB exists
67 exists: bool,
68 },
69
70 /// Upload success
71 UploadSuccess {
72 /// Hex-encoded merkle hash of uploaded XORB
73 hash: String,
74 },
75
76 /// File upload success. The file merkle hash addresses the stored
77 /// reconstruction shard; `xorb_hashes` lists each xorb the file was split
78 /// across (one for a ≤64 MiB file, more for multi-xorb files).
79 UploadFileSuccess {
80 /// Hex-encoded file merkle hash (addresses the reconstruction shard).
81 file_hash: String,
82 /// Total file length in bytes.
83 file_len: u64,
84 /// Hex-encoded xorb hashes the file was split across, in order.
85 xorb_hashes: Vec<String>,
86 },
87
88 /// File reconstruction info (the reconstruction shard). `info` carries the
89 /// raw XET `mdb_shard` binary, base64-encoded so it survives the NDJSON
90 /// text transport. A stock xet-core client decodes the base64 and feeds the
91 /// bytes to its `MDBShardFile` reader / `FileReconstructor`.
92 ReconstructionInfo {
93 /// Base64-encoded `mdb_shard` binary (the XET wire format).
94 info: String,
95 },
96
97 /// Pong response to ping
98 Pong,
99
100 /// Error response
101 Error {
102 /// Error code for programmatic handling
103 code: ErrorCode,
104 /// Human-readable error message
105 message: String,
106 },
107
108 /// Shutdown acknowledgment
109 ShutdownAck,
110}
111
112/// Error codes for programmatic error handling
113#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
114#[serde(rename_all = "snake_case")]
115pub enum ErrorCode {
116 /// Invalid request format
117 InvalidRequest,
118 /// Hash not found in storage
119 NotFound,
120 /// IO error during operation
121 IoError,
122 /// Storage backend error
123 StorageError,
124 /// Invalid hash format
125 InvalidHash,
126 /// Upload failed
127 UploadFailed,
128 /// Internal server error
129 InternalError,
130}
131
132impl Response {
133 /// Create an error response
134 pub fn error(code: ErrorCode, message: impl Into<String>) -> Self {
135 Response::Error {
136 code,
137 message: message.into(),
138 }
139 }
140
141 /// Create a file response from raw bytes
142 pub fn file(data: &[u8]) -> Self {
143 use base64::Engine;
144 Response::File {
145 data: base64::engine::general_purpose::STANDARD.encode(data),
146 }
147 }
148}
149
150impl Request {
151 /// Parse hash from hex string
152 pub fn parse_hash(hash: &str) -> Result<merklehash::MerkleHash, String> {
153 merklehash::MerkleHash::from_hex(hash).map_err(|e| format!("Invalid hash: {e}"))
154 }
155}
156
157#[cfg(test)]
158mod tests {
159 use super::*;
160
161 #[test]
162 fn test_request_serialization() -> Result<(), serde_json::Error> {
163 let req = Request::GetFile {
164 hash: "abc123".to_owned(),
165 };
166 let json = serde_json::to_string(&req)?;
167 assert!(json.contains("get_file"));
168 assert!(json.contains("abc123"));
169
170 let parsed: Request = serde_json::from_str(&json)?;
171 match parsed {
172 Request::GetFile { hash } => assert_eq!(hash, "abc123"),
173 _ => panic!("Wrong variant"),
174 }
175 Ok(())
176 }
177
178 #[test]
179 fn test_response_serialization() -> Result<(), serde_json::Error> {
180 let resp = Response::error(ErrorCode::NotFound, "File not found");
181 let json = serde_json::to_string(&resp)?;
182 assert!(json.contains("error"));
183 assert!(json.contains("not_found"));
184
185 let parsed: Response = serde_json::from_str(&json)?;
186 match parsed {
187 Response::Error { code, message } => {
188 assert_eq!(code, ErrorCode::NotFound);
189 assert_eq!(message, "File not found");
190 }
191 _ => panic!("Wrong variant"),
192 }
193 Ok(())
194 }
195}