recall_wire/
lib.rs

1//! The contract between Recall's client and server: request and response
2//! shapes, and the validation rules that apply to both.
3//!
4//! Keeping this in one crate is the point of a workspace rather than two
5//! programs. Before the implementations were unified, `file_path`
6//! validation and the tombstone/empty-file distinction existed twice — in
7//! JavaScript on the server and in bash on the client — with nothing
8//! keeping them in agreement, so a drift between them would only surface in
9//! production.
10//!
11//! # Layout
12//!
13//! One module per endpoint, since that is the unit that has to stay
14//! compatible. Every type is also re-exported at the crate root, so callers
15//! can write `recall_wire::PushRequest` and never think about which endpoint
16//! a type belongs to.
17//!
18//! | Module | Endpoint |
19//! |---|---|
20//! | [`sync`] | `POST /sync`, `GET /sync` — memory files in both directions |
21//! | [`health`] | `GET /health` — unauthenticated liveness and merge status |
22//! | [`admin`] | `GET /admin/stats` — what is stored, per project |
23//! | [`discovery`] | `GET /.well-known/recall` — what the server is and speaks |
24//! | [`devices`] | `/v1/devices`, `/v1/authkeys` — enrolling and managing devices |
25//! | [`jobs`] | `/v1/jobs` — the merge queue a worker drains |
26//! | [`evaluations`] | `/v1/evaluations` — reports the worker makes on what memory holds |
27//! | [`audit`] | `/v1/audit/*`: the log's checkpoint, leaves and proofs, the tree they hash to, and checking an export offline |
28//! | [`signature`] | not an endpoint: how a device signs every request |
29//! | [`validate`] | the rules both halves enforce |
30//!
31//! # Frozen surface
32//!
33//! **These JSON shapes are frozen.** The deployed Node server speaks them,
34//! its SQLite rows were written against them, and during any migration a
35//! machine on the old client and one on the new binary talk to the same
36//! deployment. Field names and ordering here are compatibility surface, not
37//! style.
38//!
39//! That includes timestamps, which every `updated_at`, `checked_at` and
40//! `last_*_at` field carries as JavaScript's `Date.toISOString()` —
41//! millisecond precision with a `Z` suffix, e.g. `2026-09-03T21:49:55.191Z`.
42//! Rows already in the database are in that shape. `recall_server::now`
43//! produces it.
44//!
45//! The full reference, including status codes and worked `curl` examples,
46//! is in `docs/reference/api.md`.
47
48#![deny(missing_docs)]
49
50pub mod admin;
51pub mod audit;
52pub mod devices;
53pub mod discovery;
54pub mod evaluations;
55pub mod health;
56pub mod jobs;
57pub mod signature;
58pub mod sync;
59pub mod validate;
60
61pub use admin::{AdminStats, AdminTotals, ProjectStats};
62pub use audit::{AuditCapability, AuditCheckpoint, AuditConsistencyResponse, AuditEntriesResponse};
63pub use devices::{
64    ApproveRequest, Authkey, AuthkeyCreated, AuthkeyList, AuthkeyRequest, AuthkeyRevokeRequest,
65    DenyRequest, DenyResponse, Device, DeviceIdentity, DeviceList, DevicesCapability,
66    EnrollApproved, EnrollPending, EnrollPollRequest, EnrollPollResponse, EnrollRequest,
67    PendingEnrollment,
68};
69pub use discovery::{Discovery, DISCOVERY_PATH, PROTOCOL, PROTOCOL_HEADER};
70pub use evaluations::{
71    Details, Evaluation, EvaluationCreated, EvaluationList, EvaluationRequest, EvaluationSummary,
72    FileRef, Finding, FindingDetail, Skipped, SuggestedEdit,
73};
74pub use health::{ClaudeCliStatus, Health, MergeError, MergeStatus, QueueStatus, WorkerStatus};
75pub use jobs::{
76    ClaimRequest, ClaimResponse, ClaudeCliReport, EvaluateFile, EvaluateInput, EvaluateResult, Job,
77    JobList, JobSummary, MergeInput, MergeResult, MergeSide, ResultRequest, ResultResponse,
78};
79/// The hash a push names its base by: SHA-256 of the file's exact bytes, as
80/// lowercase hex.
81///
82/// Computed on both sides of the wire — by the client over what it last
83/// synced, by the server over what it has stored — so it has to be one
84/// function in one place.
85pub fn content_sha256(content: &str) -> String {
86    use sha2::{Digest, Sha256};
87    let digest = Sha256::digest(content.as_bytes());
88    digest.iter().map(|b| format!("{b:02x}")).collect()
89}
90
91#[cfg(test)]
92mod hash_tests {
93    use super::content_sha256;
94
95    /// Known SHA-256 vectors, so the two sides of the wire cannot drift into
96    /// computing something else under the same name.
97    #[test]
98    fn content_sha256_is_plain_sha256_as_lowercase_hex() {
99        assert_eq!(
100            content_sha256(""),
101            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
102        );
103        assert_eq!(
104            content_sha256("abc"),
105            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
106        );
107    }
108
109    /// Exact bytes: a trailing newline is part of the content, and so part of
110    /// the hash.
111    #[test]
112    fn a_trailing_newline_changes_the_hash() {
113        assert_ne!(content_sha256("a"), content_sha256("a\n"));
114    }
115}
116
117pub use sync::{File, PushRequest, PushResponse, SyncResponse};
118pub use validate::{
119    validate_base_sha256, validate_file_path, validate_project_key, ValidationError,
120    MAX_FILE_PATH_BYTES, MAX_PROJECT_KEY_BYTES,
121};
122
123use serde::{Deserialize, Serialize};
124
125/// Body returned for any non-2xx, on every endpoint.
126///
127/// It lives at the root rather than in an endpoint module because it belongs
128/// to all of them: whatever a request was trying to do, this is the shape of
129/// being told no.
130#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
131pub struct ErrorResponse {
132    /// A human-readable reason, safe to show a user.
133    pub error: String,
134}
recall_wire/lib.rs

recall_wire/
lib.rs
