Skip to main content

sapphire_framework_server_api/
lib.rs

1//! What a client says to an application's server, and how the server answers: the
2//! framework's methods every app server serves, their parameters and their results.
3//!
4//! Kept apart from the rest of the framework so that its version moves only when this
5//! API does. An application's own API crate depends on this one and nothing heavier;
6//! a client that only talks to a server links neither the search stack nor the IPC
7//! transport through it. Its types are plain serde data: the transport is
8//! `sapphire-framework-ipc`, the typed client `IpcBackend` in
9//! `sapphire-framework-backend`.
10//!
11//! A server serves one workspace at a time (#215), so no request names one: every
12//! `workspace.*` and `sync.*` method acts on the server's current workspace, which
13//! [`WORKSPACE_SELECT`] and [`WORKSPACE_INIT`] change and [`WORKSPACE_CURRENT`] reports.
14
15#![warn(missing_docs)]
16
17use std::path::PathBuf;
18
19use serde::{Deserialize, Serialize};
20
21pub use grain_id::GrainId;
22
23/// The version of the app server's API: the framework's methods below and their types.
24///
25/// It is this crate's major version, parsed at compile time, so the two cannot drift: a
26/// breaking change to a method, a parameter or a result here is a major release of this
27/// crate, and that release is the new API version. The handshake compares this number,
28/// not the framework's version, so a framework release that leaves this crate alone
29/// does not demand a service restart.
30///
31/// 2: `workspace.list`, `workspace.forget`.
32///
33/// 3: search results carry `snippet` in place of `chunks` (#184).
34///
35/// 4: one workspace per server (#215): no `ws` parameter, `workspace.select` and
36/// `workspace.current` in place of `workspace.list` and `workspace.forget`.
37pub const API_VERSION: u32 = parse_major(env!("CARGO_PKG_VERSION_MAJOR"));
38
39/// `CARGO_PKG_VERSION_MAJOR` as a number. Cargo guarantees it is decimal digits.
40const fn parse_major(s: &str) -> u32 {
41    let bytes = s.as_bytes();
42    let mut i = 0;
43    let mut n = 0u32;
44    while i < bytes.len() {
45        n = n * 10 + (bytes[i] - b'0') as u32;
46        i += 1;
47    }
48    n
49}
50
51/// How a server process came to exist, as `server.info` reports it.
52///
53/// The same shape as `sapphire_ipc::ManagedBy`, defined here so this crate does not
54/// depend on the transport.
55#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "lowercase")]
57pub enum ManagedBy {
58    /// Started by the OS service manager.
59    Service,
60    /// Started on demand by a client.
61    Spawned,
62}
63
64/// Which retrieval strategy a search uses.
65#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
66#[serde(rename_all = "lowercase")]
67pub enum SearchMode {
68    /// Full-text search only (BM25 / trigram).
69    Fts,
70    /// Semantic (vector) search only. Falls back to full text if no embedder is
71    /// configured.
72    Semantic,
73    /// Combine full-text and semantic results via Reciprocal Rank Fusion (default).
74    #[default]
75    Hybrid,
76}
77
78/// One file matching a search.
79#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
80pub struct FileSearchResult {
81    /// The index's id for the file. Stable only within one server's index.
82    pub id: i64,
83    /// The file's path, relative to the workspace root.
84    pub path: String,
85    /// Full text: BM25 (higher is better). Semantic: L2 distance (lower is better).
86    /// Hybrid: RRF (higher is better).
87    pub score: f64,
88    /// A short excerpt, on one line: the match's surroundings, else the leading text.
89    pub snippet: String,
90}
91
92/// Events a server publishes so a client can react without polling.
93#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
94pub enum BackendEvent {
95    /// A sync cycle finished.
96    Synced {
97        /// Documents added/updated.
98        upserted: usize,
99        /// Documents removed.
100        removed: usize,
101    },
102    /// A single file changed through the server.
103    FileChanged {
104        /// The affected path.
105        path: PathBuf,
106    },
107    /// A single file was removed through the server.
108    FileRemoved {
109        /// The affected path.
110        path: PathBuf,
111    },
112    /// A background operation failed. Carries a human-readable message.
113    Error {
114        /// Failure description.
115        message: String,
116    },
117}
118
119/// Search the workspace.
120pub const SEARCH: &str = "workspace.search";
121/// Read a text file in full.
122pub const READ_FILE: &str = "workspace.read_file";
123/// Create or overwrite a text file.
124pub const WRITE_FILE: &str = "workspace.write_file";
125/// Append to a text file.
126pub const APPEND_FILE: &str = "workspace.append_file";
127/// Delete a file.
128pub const DELETE_FILE: &str = "workspace.delete_file";
129/// List a directory's direct children.
130pub const LIST_DIR: &str = "workspace.list_dir";
131/// Rebuild the index from disk.
132///
133/// Named `reindex`, not `sync`: `WorkspaceBackend::sync`
134/// means "walk the files and update the index", which reads as peer-to-peer sync once the
135/// bridge exists.
136pub const REINDEX: &str = "workspace.reindex";
137/// Start receiving [`EVENT`] notifications for the current workspace, and for whichever
138/// workspace is current after a switch.
139pub const SUBSCRIBE: &str = "workspace.subscribe";
140/// Create this app's workspace home in a directory — the marker and a registry entry —
141/// and make it the current workspace.
142pub const WORKSPACE_INIT: &str = "workspace.init";
143/// Make an existing workspace of this app the current one.
144pub const WORKSPACE_SELECT: &str = "workspace.select";
145/// Report the current workspace.
146pub const WORKSPACE_CURRENT: &str = "workspace.current";
147
148/// Parameters of [`WORKSPACE_SELECT`].
149#[derive(Clone, Debug, Deserialize, Serialize)]
150pub struct WorkspaceSelectParams {
151    /// The workspace's root: absolute, or relative to the server's cwd.
152    pub dir: PathBuf,
153}
154
155/// Result of [`WORKSPACE_CURRENT`].
156#[derive(Clone, Debug, Default, Deserialize, Serialize)]
157pub struct WorkspaceCurrentResult {
158    /// The current workspace; `None` before one is selected.
159    pub workspace: Option<CurrentWorkspace>,
160}
161
162/// The workspace a server serves, as [`WORKSPACE_CURRENT`] and [`WORKSPACE_SELECT`]
163/// report it.
164#[derive(Clone, Debug, Deserialize, Serialize)]
165pub struct CurrentWorkspace {
166    /// Its root on this host.
167    pub root: PathBuf,
168    /// Its identity across devices, when one has been minted. Read, never minted.
169    pub workspace_id: Option<grain_id::GrainId>,
170    /// Whether the root still holds this application's marker directory.
171    pub reachable: bool,
172    /// Its replication state, as [`SYNC_STATUS`] reports it.
173    pub sync: SyncStatusResult,
174}
175
176/// Parameters of [`WORKSPACE_INIT`].
177#[derive(Clone, Debug, Deserialize, Serialize)]
178pub struct WorkspaceInitParams {
179    /// Where the workspace root goes, relative to nothing: absolute, or relative
180    /// to the process's cwd, resolved by the server.
181    pub dir: PathBuf,
182}
183
184/// Result of [`WORKSPACE_INIT`].
185#[derive(Clone, Debug, Deserialize, Serialize)]
186pub struct WorkspaceInitResult {
187    /// The workspace's canonical root.
188    pub root: PathBuf,
189    /// Its stable id, as the registry keys it.
190    pub workspace_id: String,
191    /// `false` when the workspace already existed (exit 0 either way).
192    pub created: bool,
193}
194/// Notification carrying one [`BackendEvent`].
195pub const EVENT: &str = "workspace.event";
196/// What the server knows about itself.
197pub const SERVER_INFO: &str = "server.info";
198
199/// Parameters naming a path inside the workspace.
200#[derive(Clone, Debug, Serialize, Deserialize)]
201pub struct PathParams {
202    /// Workspace-relative path.
203    pub path: PathBuf,
204}
205
206/// Parameters naming a path and the text to put there.
207#[derive(Clone, Debug, Serialize, Deserialize)]
208pub struct ContentParams {
209    /// Workspace-relative path.
210    pub path: PathBuf,
211    /// The text.
212    pub content: String,
213}
214
215/// Parameters of [`SEARCH`].
216#[derive(Clone, Debug, Serialize, Deserialize)]
217pub struct SearchParams {
218    /// The query.
219    pub query: String,
220    /// Maximum number of files to return.
221    pub limit: usize,
222    /// Which retrieval strategy to use.
223    #[serde(default)]
224    pub mode: SearchMode,
225}
226
227/// Result of [`SEARCH`].
228#[derive(Clone, Debug, Serialize, Deserialize)]
229pub struct SearchResult {
230    /// File-level hits, best first.
231    pub hits: Vec<FileSearchResult>,
232}
233
234/// Result of [`READ_FILE`].
235#[derive(Clone, Debug, Serialize, Deserialize)]
236pub struct ReadResult {
237    /// The file's contents.
238    pub content: String,
239}
240
241/// One entry of a directory listing.
242#[derive(Clone, Debug, Serialize, Deserialize)]
243pub struct DirEntry {
244    /// The child's path.
245    pub path: PathBuf,
246    /// Whether it is a directory.
247    pub is_dir: bool,
248}
249
250/// Result of [`LIST_DIR`].
251#[derive(Clone, Debug, Serialize, Deserialize)]
252pub struct ListDirResult {
253    /// The direct children.
254    pub entries: Vec<DirEntry>,
255}
256
257/// Result of [`REINDEX`].
258#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
259pub struct ReindexResult {
260    /// Documents added or updated.
261    pub upserted: usize,
262    /// Documents removed.
263    pub removed: usize,
264}
265
266/// The success payload of a method that returns nothing.
267///
268/// An empty object rather than `null`, so that a later release can add a field without
269/// changing the shape of the response.
270#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize)]
271pub struct Ack {}
272
273/// Parameters of an [`EVENT`] notification.
274#[derive(Clone, Debug, Serialize, Deserialize)]
275pub struct EventParams {
276    /// The root of the workspace the event came from: the current one when it was sent.
277    pub ws: PathBuf,
278    /// What happened.
279    pub event: BackendEvent,
280}
281
282#[cfg(test)]
283mod tests {
284    use super::*;
285
286    fn round_trip<T>(value: &T) -> T
287    where
288        T: serde::Serialize + serde::de::DeserializeOwned,
289    {
290        serde_json::from_value(serde_json::to_value(value).unwrap()).unwrap()
291    }
292
293    #[test]
294    fn search_parameters_round_trip() {
295        let params = SearchParams {
296            query: "hello".into(),
297            limit: 10,
298            mode: SearchMode::Fts,
299        };
300        let back = round_trip(&params);
301        assert_eq!(back.query, "hello");
302        assert_eq!(back.limit, 10);
303        assert_eq!(back.mode, SearchMode::Fts);
304    }
305
306    #[test]
307    fn every_search_mode_has_a_stable_lowercase_name() {
308        for (mode, name) in [
309            (SearchMode::Fts, "fts"),
310            (SearchMode::Semantic, "semantic"),
311            (SearchMode::Hybrid, "hybrid"),
312        ] {
313            assert_eq!(serde_json::to_value(mode).unwrap(), serde_json::json!(name));
314            assert_eq!(
315                serde_json::from_value::<SearchMode>(serde_json::json!(name)).unwrap(),
316                mode
317            );
318        }
319    }
320
321    #[test]
322    fn a_missing_mode_defaults_to_hybrid() {
323        let value = serde_json::json!({ "query": "q", "limit": 5 });
324        let params: SearchParams = serde_json::from_value(value).unwrap();
325        assert_eq!(params.mode, SearchMode::Hybrid);
326    }
327
328    #[test]
329    fn every_backend_event_round_trips() {
330        for event in [
331            BackendEvent::Synced {
332                upserted: 3,
333                removed: 1,
334            },
335            BackendEvent::FileChanged {
336                path: PathBuf::from("a.md"),
337            },
338            BackendEvent::FileRemoved {
339                path: PathBuf::from("b.md"),
340            },
341            BackendEvent::Error {
342                message: "boom".into(),
343            },
344        ] {
345            assert_eq!(round_trip(&event), event);
346        }
347    }
348
349    #[test]
350    fn a_directory_listing_round_trips() {
351        let listing = ListDirResult {
352            entries: vec![
353                DirEntry {
354                    path: PathBuf::from("notes"),
355                    is_dir: true,
356                },
357                DirEntry {
358                    path: PathBuf::from("a.md"),
359                    is_dir: false,
360                },
361            ],
362        };
363        let back = round_trip(&listing);
364        assert_eq!(back.entries.len(), 2);
365        assert!(back.entries[0].is_dir);
366        assert!(!back.entries[1].is_dir);
367    }
368
369    #[test]
370    fn an_ack_is_an_object_not_null() {
371        assert_eq!(serde_json::to_value(Ack {}).unwrap(), serde_json::json!({}));
372    }
373
374    #[test]
375    fn workspace_init_params_and_result_round_trip() {
376        let params = WorkspaceInitParams {
377            dir: PathBuf::from("/home/me/papers"),
378        };
379        let back = round_trip(&params);
380        assert_eq!(back.dir, params.dir);
381
382        let result = WorkspaceInitResult {
383            root: PathBuf::from("/home/me/papers"),
384            workspace_id: "g123".into(),
385            created: true,
386        };
387        let back = round_trip(&result);
388        assert_eq!(back.root, result.root);
389        assert_eq!(back.workspace_id, result.workspace_id);
390        assert!(back.created);
391    }
392
393    #[test]
394    fn the_current_workspace_round_trips() {
395        let current = CurrentWorkspace {
396            root: PathBuf::from("/home/me/notes"),
397            workspace_id: Some(grain_id::GrainId::random()),
398            reachable: true,
399            sync: SyncStatusResult::not_synced(),
400        };
401        let back = round_trip(&WorkspaceCurrentResult {
402            workspace: Some(current.clone()),
403        });
404        let back = back.workspace.unwrap();
405        assert_eq!(back.root, current.root);
406        assert_eq!(back.workspace_id, current.workspace_id);
407        assert!(
408            round_trip(&WorkspaceCurrentResult::default())
409                .workspace
410                .is_none()
411        );
412        assert_eq!(
413            round_trip(&WorkspaceSelectParams {
414                dir: PathBuf::from("/x")
415            })
416            .dir,
417            PathBuf::from("/x")
418        );
419        assert_eq!(API_VERSION, 4, "the crate's major is the API version");
420    }
421
422    #[test]
423    fn method_names_are_namespaced() {
424        for name in [
425            SEARCH,
426            READ_FILE,
427            WRITE_FILE,
428            APPEND_FILE,
429            DELETE_FILE,
430            LIST_DIR,
431            REINDEX,
432            SUBSCRIBE,
433            WORKSPACE_INIT,
434            WORKSPACE_SELECT,
435            WORKSPACE_CURRENT,
436        ] {
437            assert!(name.starts_with("workspace."), "{name}");
438        }
439        assert_eq!(EVENT, "workspace.event");
440    }
441}
442
443/// Start syncing the current workspace.
444pub const SYNC_ENABLE: &str = "sync.enable";
445/// Stop syncing the current workspace. Files stay.
446pub const SYNC_DISABLE: &str = "sync.disable";
447/// Report the current workspace's replication state.
448pub const SYNC_STATUS: &str = "sync.status";
449
450/// Place a workspace's directory, by name or id.
451pub const SYNC_MAP: &str = "sync.map";
452
453/// Parameters of [`SYNC_MAP`]. The mapped directory becomes the current workspace.
454#[derive(Clone, Debug, Deserialize, Serialize)]
455pub struct SyncMapParams {
456    /// The workspace, by name or id, as the workgroup lists it.
457    pub workspace: String,
458    /// Where the workspace's root is on this host.
459    pub dir: PathBuf,
460}
461
462/// Result of [`SYNC_ENABLE`].
463#[derive(Clone, Debug, Deserialize, Serialize)]
464pub struct SyncEnableResult {
465    /// The workspace's identity across devices.
466    pub workspace_id: grain_id::GrainId,
467}
468
469/// How a synced workspace is wired to its peers right now.
470#[derive(Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize)]
471#[serde(tag = "kind", rename_all = "snake_case")]
472pub enum Topology {
473    /// Every device syncs with every other. Also the answer when no device was elected.
474    #[default]
475    Mesh,
476    /// Devices that are neither primary nor secondary sync only with those two.
477    Star {
478        /// The primary device.
479        primary: grain_id::GrainId,
480        /// The secondary device, if there is a second candidate.
481        secondary: Option<grain_id::GrainId>,
482    },
483}
484
485/// Result of [`SYNC_STATUS`].
486#[derive(Clone, Debug, Deserialize, Serialize)]
487pub struct SyncStatusResult {
488    /// Whether this workspace is synced.
489    pub enabled: bool,
490    /// Its identity across devices, when it is.
491    pub workspace_id: Option<grain_id::GrainId>,
492    /// How many other devices the workgroup has.
493    pub peers: usize,
494    /// Why replication is paused, if it is.
495    pub paused: Option<String>,
496    /// The last failure, if any.
497    pub last_error: Option<String>,
498    /// Whether the bridge is reachable. `false` does not mean the app server is down.
499    pub bridge_available: bool,
500    /// How the workspace is wired to its peers. Absent from older servers: a mesh.
501    #[serde(default)]
502    pub topology: Topology,
503    /// How far embedding has got, when this host embeds (#188).
504    #[serde(default, skip_serializing_if = "Option::is_none")]
505    pub embedding: Option<EmbeddingProgress>,
506}
507
508/// How far a workspace's embedding has got on this host.
509#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
510pub struct EmbeddingProgress {
511    /// Documents with a vector.
512    pub vectors: u64,
513    /// Documents still without one.
514    pub pending: u64,
515    /// Whether an embedding pass is running now.
516    pub running: bool,
517}
518
519impl SyncStatusResult {
520    /// The state of a workspace nothing syncs.
521    pub fn not_synced() -> SyncStatusResult {
522        SyncStatusResult {
523            enabled: false,
524            workspace_id: None,
525            peers: 0,
526            paused: None,
527            last_error: None,
528            bridge_available: false,
529            topology: Topology::Mesh,
530            embedding: None,
531        }
532    }
533}
534
535/// The typed answer to a status question, shared by the CLI and the IPC `server.info`
536/// response (spec decision 4).
537///
538/// When a server answers, the CLI prints the framework's fields and then the
539/// application's [rows](StatusReport::app) as `name: value` lines; a GUI could read the
540/// same serialised shape from the IPC method instead. When nothing is listening, the
541/// report is [`StatusReport::running`] = `false` and the app rows are skipped.
542#[derive(Debug, Clone, Serialize, Deserialize)]
543pub struct StatusReport {
544    /// Whether a server is answering at all.
545    pub running: bool,
546    /// The server's version, when it is running.
547    pub version: Option<String>,
548    /// Its pid, when it is running.
549    pub pid: Option<u32>,
550    /// How the running server was started, when it is running.
551    pub managed_by: Option<ManagedBy>,
552    /// The application's own rows, rendered after the framework's.
553    pub app: Vec<StatusRow>,
554}
555
556/// One application-provided line of the status report.
557#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
558pub struct StatusRow {
559    /// The row's name, e.g. `sync`.
560    pub name: String,
561    /// The value shown beside it.
562    pub value: String,
563}