Skip to main content

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}