Skip to main content

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}