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