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