Skip to main content

Crate sapphire_framework_server

Crate sapphire_framework_server 

Source
Expand description

The app server skeleton.

An application builds one of these, adds its own methods, and runs it. Everything a sapphire app needs on the server side — owning its workspace, answering workspace.*, pushing events — is here. A server serves one workspace at a time (#215): see Current.

See docs/superpowers/specs/2026-09-16-process-architecture-design.md §4.

ⓘ
static CTX: AppContext = AppContext::new("sapphire-journal");

AppServer::new(&CTX, env!("CARGO_PKG_VERSION"))
    .extend(|router| router.method("journal.create_entry", create_entry))
    .run()
    .await?;

Application methods are named <app>.<method>. The framework owns workspace.* and server.*; anything else is the application’s.

Re-exports§

pub use command::AppConfigCommand;
pub use command::AppScopeFlags;
pub use command::AppUpdateArgs;
pub use command::FrameworkCommand;
pub use command::LegacyExternalDevice;
pub use command::WorkspaceCommand;
pub use command::WorkspaceSyncCommand;
pub use command::render_workspace;
pub use command::update_bridge;
pub use sync::BackfillTiming;
pub use sync::BridgeConnector;
pub use sync::SyncRuntime;
pub use sync::SyncStatus;
pub use sync::sync_router;
pub use metrics;

Modules§

api_keys
The served workspace’s API keys (#364): the HTTP layer’s verifier.
sync
Replication, from the app server’s side.

Structs§

AppFiles
Where an application’s settings files are, for AppSettings::validate.
AppScopeFlags
The scope flags of an application’s config: at most one of them.
AppServer
An application’s server.
AppUpdateArgs
update’s arguments in an application: its own, and whether the bridge follows.
Current
The server’s current workspace.
FieldError
One problem an owner found while validating.
HttpConfig
The [http] table: the listener every HTTP route shares.
HttpEndpoint
An HTTP endpoint an application declares (AppSettings::http_endpoints).
HttpMcpConfig
The [http.mcp] table.
HttpMetricsConfig
The [http.metrics] table.
LegacyExternalDevice
external-device …, kept one release as a hidden alias of api-key.
ReleaseSource
Where a binary’s releases are published: a GitHub repository whose releases are tagged <prefix><version>, and — for the update command — the file in them.
Selection
What workspace.toml holds.
SelectionFile
The selection file, read and written whole.
ServerConfig
The server’s settings, as config.toml holds them.
SettingDef
The registry’s description of one setting.
Settings
The app server’s settings as the running server sees them: a cheap, clonable handle.
Staged
The edited text of the files a batch touches, before it is written.
StatusReport
The typed answer to a status question, shared by the CLI and the IPC server.info response (spec decision 4).
StatusRow
One application-provided line of the status report.
UpdateArgs
The update subcommand’s arguments: replace this executable with its newest release.
UpdateConfig
The [update] table.
WorkspaceHost
The workspace this server has open.

Enums§

AppConfigCommand
config …: the settings, by key.
Apply
When a changed setting takes effect.
Error
Errors raised while serving an application’s workspaces.
FrameworkCommand
The framework’s commands, flattened into an application’s CLI (spec decision 2).
Kind
The type of a setting’s value, and so what it accepts.
Process
Which process owns a setting: the one that stores, validates and applies it.
Scope
Where a setting is stored. Ordered as declared: device, workgroup, workspace.
Value
A typed setting value.
WorkspaceCommand
The workspace subcommands (#215: one workspace per server).
WorkspaceSyncCommand
The workspace sync subcommands: the server’s workspace’s sync, switched after the fact.

Constants§

SELECTION_FILE
The file’s name inside the application’s config directory.
SERVER_CONFIG_FILE
The device settings file’s name inside the application’s config directory.

Traits§

AppSettings
An application’s own settings: what they are, and a check of the edited files as a whole.
FromValue
A Rust type a setting’s value reads as, for Settings::get_as.

Functions§

app_service_spec
The app server’s service for app_name at version: what AppServer::service_spec returns, for a desktop package to name its service without an AppServer (#357).
render_workspace
Render the server’s workspace as the CLI prints it: root state.
serve_restarting
Serve ctx’s application with the AppServer build makes; on server.restart, read the settings again, build another and serve that, on the same endpoint.
subscribe_method
Add workspace.subscribe to router.
update_bridge
Run the bridge on PATH’s own update with args; returns its exit code. No bridge on PATH is nothing to update. update does it after the application; a desktop package, whose own update ends the process, does it first (#357).
workspace_router
The file methods of workspace.*, on the current workspace (#215).

Type Aliases§

Result
Convenience alias for server results.