sapphire_sync_server/lib.rs
1//! sapphire-sync's app server: what `sapphire-sync serve` runs, in either
2//! edition. A library, not a binary of its own: the server is set up with the
3//! same `sapphire-sync` command that runs it (`sapphire-sync-cli`), so there is
4//! no separate server command to tell from the client's.
5//!
6//! Two builders, bridge-less for one-shot verbs and sync-mounted for serve,
7//! because the bridge connection belongs to the serve path only
8//! (the review of `0acb194` ruled the one-shot verbs bridge-less):
9//!
10//! - [`build_oneshot`] hands every one-shot framework verb that needs a server
11//! (`service`, `update`) a bare [`AppServer`] — `dispatch` needs only the app
12//! name and the service spec, and a CLI invocation must not open a bridge or
13//! fail with a bridge error.
14//! A `status` on a host without a server answers the framework's "no
15//! sapphire-sync server is running" and exits 1; a `workspace init` likewise
16//! reports the absent server. Neither touches the bridge.
17//! - [`build_serve`] additionally mounts a `SyncRuntime` that reaches the
18//! bridge itself (the daemon is always service-managed) with
19//! [`AppServer::sync`], plus the app's own status rows with
20//! [`AppServer::status_rows`]: one row per synced workspace, rendered per
21//! report from the live runtime. The runtime is connect-only — nothing starts
22//! a bridge on demand (the framework's global constraint) — and the framework
23//! connects when the server runs, and again whenever the bridge restarts
24//! (sapphire-framework#244). `serve` on a host whose bridge is not running
25//! yet serves without sync until it is; meanwhile `sync.*` answers "not
26//! connected to sapphire-bridge". A bridge of another API version still
27//! stops the start. `serve` calls it once per round of
28//! `serve_restarting`, so a `server.restart` gets a fresh runtime.
29//!
30//! The IPC endpoint, the stop channel and the signals are `run()`'s business
31//! in both paths; the app installs nothing there.
32//!
33//! `ManagedBy` is the transport's, which `SyncRuntime` takes.
34
35use std::path::Path;
36use std::sync::Arc;
37
38use sapphire_sync_core::CTX;
39use sapphire_sync_core::framework::ipc::ManagedBy;
40use sapphire_sync_core::framework::server::{
41 AppServer, BridgeConnector, ReleaseSource, Settings, SyncRuntime,
42};
43
44mod status;
45
46pub use status::status_rows;
47
48/// The version the server reports, and the command line's clients name: the
49/// editions and this library share it (release-plz.toml).
50pub const VERSION: &str = env!("CARGO_PKG_VERSION");
51
52/// Which edition runs the server: the release file `update` installs is the
53/// edition's own.
54#[derive(Clone, Copy, Debug, PartialEq, Eq)]
55pub enum Edition {
56 /// `sapphire-sync-headless`, the command line alone.
57 Headless,
58 /// `sapphire-sync-desktop`, the desktop app.
59 Desktop,
60}
61
62impl Edition {
63 /// Where the edition's releases are published: what `update` installs
64 /// from, and where the server looks once a day for a newer one. Both are
65 /// in the framework's shared `v{version}` release (release-sync.yml), as
66 /// `<crate>-<os>-<arch>`; only the headless edition is on crates.io.
67 pub fn releases(self) -> ReleaseSource {
68 let source = ReleaseSource::github("sapphire-turtle", "sapphire-framework");
69 match self {
70 Edition::Headless => source
71 .asset("sapphire-sync-headless")
72 .cargo_crate("sapphire-sync-headless"),
73 Edition::Desktop => source.asset("sapphire-sync-desktop"),
74 }
75 }
76}
77
78/// The app's server for one-shot verbs: an `AppServer` with nothing mounted.
79///
80/// Every [`FrameworkCommand`] except `Serve` dispatches with this as its
81/// builder; the framework calls it only for the verbs that read the server
82/// (`service_spec()`, what a service manager starts). The others connect to a
83/// *running* server over IPC themselves. The app has no settings of its own,
84/// so `_settings` holds the framework's alone and nothing here reads them.
85///
86/// [`FrameworkCommand`]: sapphire_sync_core::framework::server::FrameworkCommand
87pub fn build_oneshot(_settings: &Settings, edition: Edition) -> AppServer {
88 AppServer::new(&CTX, VERSION).releases(edition.releases())
89}
90
91/// The app's embedded server: sync runtime, `AppServer`.
92///
93/// Sync is mounted with [`AppServer::sync`]. The runtime is built here rather
94/// than by [`AppServer::sync_via_bridge`], which is the same runtime, because
95/// the status rows read it too. It is not connected yet: [`AppServer::run`]
96/// makes the first attempt, and keeps it connected from there.
97/// The app's own status rows are mounted with [`AppServer::status_rows`] —
98/// built from the same runtime, so a report reads the live sync state. The
99/// server reports the app's API version (`sapphire-sync-api`) in the
100/// handshake, so a client that names another is refused.
101///
102/// A new runtime per call: the framework's `serve_restarting` builds a server
103/// per round, and a server stops the runtime it was given when it stops. `exe`
104/// is this executable, looked up once by the caller; `edition` the one it is.
105pub fn build_serve(_settings: &Settings, exe: &Path, edition: Edition) -> AppServer {
106 let runtime = Arc::new(SyncRuntime::connecting(
107 &CTX,
108 BridgeConnector::standard(CTX.app_name, VERSION),
109 exe.to_path_buf(),
110 ManagedBy::Service,
111 ));
112 AppServer::new(&CTX, VERSION)
113 .releases(edition.releases())
114 .app_api(sapphire_sync_api::API_VERSION)
115 .sync(Arc::clone(&runtime))
116 .status_rows(status_rows(runtime))
117}