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(¶ms);
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(¶ms);
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}