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