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