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