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    /// The root's directory name, slugified. Nothing keys by it any more: it was the id
216    /// of the `[workspace]` registry entry `workspace.init` used to write into the
217    /// marker's `config.toml`, and stays for clients that print it.
218    pub workspace_id: String,
219    /// `false` when the workspace already existed (exit 0 either way).
220    pub created: bool,
221}
222/// Notification carrying one [`BackendEvent`].
223pub const EVENT: &str = "workspace.event";
224/// What the server knows about itself.
225pub const SERVER_INFO: &str = "server.info";
226/// What the server last learnt about newer releases of itself: [`UpdateStatus`].
227///
228/// A server older than this method answers method-not-found; a client reads that as
229/// "nothing known" rather than an error.
230pub const SERVER_UPDATE: &str = "server.update";
231
232/// Parameters naming a path inside the workspace.
233#[derive(Clone, Debug, Serialize, Deserialize)]
234pub struct PathParams {
235    /// Workspace-relative path.
236    pub path: PathBuf,
237}
238
239/// Parameters naming a path and the text to put there.
240#[derive(Clone, Debug, Serialize, Deserialize)]
241pub struct ContentParams {
242    /// Workspace-relative path.
243    pub path: PathBuf,
244    /// The text.
245    pub content: String,
246}
247
248/// Parameters of [`SEARCH`].
249#[derive(Clone, Debug, Serialize, Deserialize)]
250pub struct SearchParams {
251    /// The query.
252    pub query: String,
253    /// Maximum number of files to return.
254    pub limit: usize,
255    /// Which retrieval strategy to use.
256    #[serde(default)]
257    pub mode: SearchMode,
258}
259
260/// Result of [`SEARCH`].
261#[derive(Clone, Debug, Serialize, Deserialize)]
262pub struct SearchResult {
263    /// File-level hits, best first.
264    pub hits: Vec<FileSearchResult>,
265}
266
267/// Result of [`READ_FILE`].
268#[derive(Clone, Debug, Serialize, Deserialize)]
269pub struct ReadResult {
270    /// The file's contents.
271    pub content: String,
272}
273
274/// One entry of a directory listing.
275#[derive(Clone, Debug, Serialize, Deserialize)]
276pub struct DirEntry {
277    /// The child's path.
278    pub path: PathBuf,
279    /// Whether it is a directory.
280    pub is_dir: bool,
281}
282
283/// Result of [`LIST_DIR`].
284#[derive(Clone, Debug, Serialize, Deserialize)]
285pub struct ListDirResult {
286    /// The direct children.
287    pub entries: Vec<DirEntry>,
288}
289
290/// Result of [`REINDEX`].
291#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
292pub struct ReindexResult {
293    /// Documents added or updated.
294    pub upserted: usize,
295    /// Documents removed.
296    pub removed: usize,
297}
298
299/// The success payload of a method that returns nothing.
300///
301/// An empty object rather than `null`, so that a later release can add a field without
302/// changing the shape of the response.
303#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize)]
304pub struct Ack {}
305
306/// Parameters of an [`EVENT`] notification.
307#[derive(Clone, Debug, Serialize, Deserialize)]
308pub struct EventParams {
309    /// The root of the workspace the event came from: the current one when it was sent.
310    pub ws: PathBuf,
311    /// What happened.
312    pub event: BackendEvent,
313}
314
315#[cfg(test)]
316mod tests {
317    use super::*;
318
319    fn round_trip<T>(value: &T) -> T
320    where
321        T: serde::Serialize + serde::de::DeserializeOwned,
322    {
323        serde_json::from_value(serde_json::to_value(value).unwrap()).unwrap()
324    }
325
326    #[test]
327    fn search_parameters_round_trip() {
328        let params = SearchParams {
329            query: "hello".into(),
330            limit: 10,
331            mode: SearchMode::Fts,
332        };
333        let back = round_trip(&params);
334        assert_eq!(back.query, "hello");
335        assert_eq!(back.limit, 10);
336        assert_eq!(back.mode, SearchMode::Fts);
337    }
338
339    #[test]
340    fn every_search_mode_has_a_stable_lowercase_name() {
341        for (mode, name) in [
342            (SearchMode::Fts, "fts"),
343            (SearchMode::Semantic, "semantic"),
344            (SearchMode::Hybrid, "hybrid"),
345        ] {
346            assert_eq!(serde_json::to_value(mode).unwrap(), serde_json::json!(name));
347            assert_eq!(
348                serde_json::from_value::<SearchMode>(serde_json::json!(name)).unwrap(),
349                mode
350            );
351        }
352    }
353
354    #[test]
355    fn a_missing_mode_defaults_to_hybrid() {
356        let value = serde_json::json!({ "query": "q", "limit": 5 });
357        let params: SearchParams = serde_json::from_value(value).unwrap();
358        assert_eq!(params.mode, SearchMode::Hybrid);
359    }
360
361    #[test]
362    fn every_backend_event_round_trips() {
363        for event in [
364            BackendEvent::Synced {
365                upserted: 3,
366                removed: 1,
367            },
368            BackendEvent::FileChanged {
369                path: PathBuf::from("a.md"),
370            },
371            BackendEvent::FileRemoved {
372                path: PathBuf::from("b.md"),
373            },
374            BackendEvent::Error {
375                message: "boom".into(),
376            },
377        ] {
378            assert_eq!(round_trip(&event), event);
379        }
380    }
381
382    #[test]
383    fn a_directory_listing_round_trips() {
384        let listing = ListDirResult {
385            entries: vec![
386                DirEntry {
387                    path: PathBuf::from("notes"),
388                    is_dir: true,
389                },
390                DirEntry {
391                    path: PathBuf::from("a.md"),
392                    is_dir: false,
393                },
394            ],
395        };
396        let back = round_trip(&listing);
397        assert_eq!(back.entries.len(), 2);
398        assert!(back.entries[0].is_dir);
399        assert!(!back.entries[1].is_dir);
400    }
401
402    #[test]
403    fn an_ack_is_an_object_not_null() {
404        assert_eq!(serde_json::to_value(Ack {}).unwrap(), serde_json::json!({}));
405    }
406
407    #[test]
408    fn workspace_init_params_and_result_round_trip() {
409        let params = WorkspaceInitParams {
410            dir: PathBuf::from("/home/me/papers"),
411        };
412        let back = round_trip(&params);
413        assert_eq!(back.dir, params.dir);
414
415        let result = WorkspaceInitResult {
416            root: PathBuf::from("/home/me/papers"),
417            workspace_id: "g123".into(),
418            created: true,
419        };
420        let back = round_trip(&result);
421        assert_eq!(back.root, result.root);
422        assert_eq!(back.workspace_id, result.workspace_id);
423        assert!(back.created);
424    }
425
426    #[test]
427    fn the_current_workspace_round_trips() {
428        let current = CurrentWorkspace {
429            root: PathBuf::from("/home/me/notes"),
430            workspace_id: Some(grain_id::GrainId::random()),
431            reachable: true,
432            sync: SyncStatusResult::not_synced(),
433        };
434        let back = round_trip(&WorkspaceCurrentResult {
435            workspace: Some(current.clone()),
436        });
437        let back = back.workspace.unwrap();
438        assert_eq!(back.root, current.root);
439        assert_eq!(back.workspace_id, current.workspace_id);
440        assert!(
441            round_trip(&WorkspaceCurrentResult::default())
442                .workspace
443                .is_none()
444        );
445        assert_eq!(
446            round_trip(&WorkspaceSelectParams {
447                dir: PathBuf::from("/x")
448            })
449            .dir,
450            PathBuf::from("/x")
451        );
452        assert_eq!(API_VERSION, 4, "the crate's major is the API version");
453    }
454
455    #[test]
456    fn method_names_are_namespaced() {
457        for name in [
458            SEARCH,
459            READ_FILE,
460            WRITE_FILE,
461            APPEND_FILE,
462            DELETE_FILE,
463            LIST_DIR,
464            REINDEX,
465            SUBSCRIBE,
466            WORKSPACE_INIT,
467            WORKSPACE_SELECT,
468            WORKSPACE_CURRENT,
469            WORKSPACE_MOVE,
470            WORKSPACE_REMOVE,
471        ] {
472            assert!(name.starts_with("workspace."), "{name}");
473        }
474        assert_eq!(EVENT, "workspace.event");
475    }
476}
477
478/// Start syncing the current workspace.
479pub const SYNC_ENABLE: &str = "sync.enable";
480/// Stop syncing the current workspace. Files stay.
481pub const SYNC_DISABLE: &str = "sync.disable";
482/// Report the current workspace's replication state.
483pub const SYNC_STATUS: &str = "sync.status";
484
485/// Place a workspace's directory, by name or id.
486pub const SYNC_MAP: &str = "sync.map";
487
488/// Parameters of [`SYNC_MAP`]. The mapped directory becomes the current workspace.
489#[derive(Clone, Debug, Deserialize, Serialize)]
490pub struct SyncMapParams {
491    /// The workspace, by name or id, as the workgroup lists it.
492    pub workspace: String,
493    /// Where the workspace's root is on this host.
494    pub dir: PathBuf,
495}
496
497/// Result of [`SYNC_ENABLE`].
498#[derive(Clone, Debug, Deserialize, Serialize)]
499pub struct SyncEnableResult {
500    /// The workspace's identity across devices.
501    pub workspace_id: grain_id::GrainId,
502}
503
504/// How a synced workspace is wired to its peers right now.
505#[derive(Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize)]
506#[serde(tag = "kind", rename_all = "snake_case")]
507pub enum Topology {
508    /// Every device syncs with every other. Also the answer when no device was elected.
509    #[default]
510    Mesh,
511    /// Devices that are neither primary nor secondary sync only with those two.
512    Star {
513        /// The primary device.
514        primary: grain_id::GrainId,
515        /// The secondary device, if there is a second candidate.
516        secondary: Option<grain_id::GrainId>,
517    },
518}
519
520/// Result of [`SYNC_STATUS`].
521#[derive(Clone, Debug, Deserialize, Serialize)]
522pub struct SyncStatusResult {
523    /// Whether this workspace is synced.
524    pub enabled: bool,
525    /// Its identity across devices, when it is.
526    pub workspace_id: Option<grain_id::GrainId>,
527    /// How many other devices the workgroup has.
528    pub peers: usize,
529    /// Why replication is paused, if it is.
530    pub paused: Option<String>,
531    /// The last failure, if any.
532    pub last_error: Option<String>,
533    /// Whether the bridge is reachable. `false` does not mean the app server is down.
534    pub bridge_available: bool,
535    /// How the workspace is wired to its peers. Absent from older servers: a mesh.
536    #[serde(default)]
537    pub topology: Topology,
538    /// How far embedding has got, when this host embeds (#188).
539    #[serde(default, skip_serializing_if = "Option::is_none")]
540    pub embedding: Option<EmbeddingProgress>,
541}
542
543/// How far a workspace's embedding has got on this host.
544#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
545pub struct EmbeddingProgress {
546    /// Documents with a vector.
547    pub vectors: u64,
548    /// Documents still without one.
549    pub pending: u64,
550    /// Whether an embedding pass is running now.
551    pub running: bool,
552}
553
554impl SyncStatusResult {
555    /// The state of a workspace nothing syncs.
556    pub fn not_synced() -> SyncStatusResult {
557        SyncStatusResult {
558            enabled: false,
559            workspace_id: None,
560            peers: 0,
561            paused: None,
562            last_error: None,
563            bridge_available: false,
564            topology: Topology::Mesh,
565            embedding: None,
566        }
567    }
568}
569
570/// The typed answer to a status question, shared by the CLI and the IPC `server.info`
571/// response (spec decision 4).
572///
573/// When a server answers, the CLI prints the framework's fields and then the
574/// application's [rows](StatusReport::app) as `name: value` lines; a GUI could read the
575/// same serialised shape from the IPC method instead. When nothing is listening, the
576/// report is [`StatusReport::running`] = `false` and the app rows are skipped.
577#[derive(Debug, Clone, Serialize, Deserialize)]
578pub struct StatusReport {
579    /// Whether a server is answering at all.
580    pub running: bool,
581    /// The server's version, when it is running.
582    pub version: Option<String>,
583    /// Its pid, when it is running.
584    pub pid: Option<u32>,
585    /// How the running server was started, when it is running.
586    pub managed_by: Option<ManagedBy>,
587    /// The application's own rows, rendered after the framework's.
588    pub app: Vec<StatusRow>,
589}
590
591/// The answer to [`SERVER_UPDATE`]: whether a newer release of the running server exists.
592///
593/// The server only looks; it never downloads or installs anything. Installing the
594/// release and restarting the server are the user's.
595#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
596pub struct UpdateStatus {
597    /// Whether the server looks for releases at all: the application named where its
598    /// releases are published, and `server.toml` did not turn the check off.
599    pub enabled: bool,
600    /// The newest release the last successful check found, whether or not it is newer
601    /// than the running server. `None` until a check has succeeded.
602    pub latest: Option<ReleaseInfo>,
603    /// Whether [`latest`](Self::latest) is newer than the running server.
604    pub update_available: bool,
605    /// Why the last check failed, when it did. A later success clears it; the last
606    /// [`latest`](Self::latest) is kept meanwhile.
607    pub last_error: Option<String>,
608}
609
610/// One published release, as [`UpdateStatus`] reports it.
611#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
612pub struct ReleaseInfo {
613    /// The release's version, without the tag's prefix: `0.20.0`.
614    pub version: String,
615    /// The release's web page, where its notes and downloads are.
616    pub url: String,
617}
618
619/// One application-provided line of the status report.
620#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
621pub struct StatusRow {
622    /// The row's name, e.g. `sync`.
623    pub name: String,
624    /// The value shown beside it.
625    pub value: String,
626}