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. - AppScope
Flags - The scope flags of an application’s
config: at most one of them. - AppServer
- An application’s server.
- AppUpdate
Args update’s arguments in an application: its own, and whether the bridge follows.- Current
- The server’s current workspace.
- Field
Error - One problem an owner found while validating.
- Http
Config - The
[http]table: the listener every HTTP route shares. - Http
Endpoint - An HTTP endpoint an application declares (
AppSettings::http_endpoints). - Http
McpConfig - The
[http.mcp]table. - Http
Metrics Config - The
[http.metrics]table. - Legacy
External Device external-device …, kept one release as a hidden alias ofapi-key.- Release
Source - Where a binary’s releases are published: a GitHub repository whose releases are tagged
<prefix><version>, and — for theupdatecommand — the file in them. - Selection
- What
workspace.tomlholds. - Selection
File - The selection file, read and written whole.
- Server
Config - The server’s settings, as
config.tomlholds them. - Setting
Def - 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.
- Status
Report - The typed answer to a status question, shared by the CLI and the IPC
server.inforesponse (spec decision 4). - Status
Row - One application-provided line of the status report.
- Update
Args - The
updatesubcommand’s arguments: replace this executable with its newest release. - Update
Config - The
[update]table. - Workspace
Host - The workspace this server has open.
Enums§
- AppConfig
Command config …: the settings, by key.- Apply
- When a changed setting takes effect.
- Error
- Errors raised while serving an application’s workspaces.
- Framework
Command - 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.
- Workspace
Command - The
workspacesubcommands (#215: one workspace per server). - Workspace
Sync Command - The
workspace syncsubcommands: 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.
- From
Value - A Rust type a setting’s value reads as, for
Settings::get_as.
Functions§
- app_
service_ spec - The app server’s service for
app_nameatversion: whatAppServer::service_specreturns, for a desktop package to name its service without anAppServer(#357). - render_
workspace - Render the server’s workspace as the CLI prints it:
root state. - serve_
restarting - Serve
ctx’s application with theAppServerbuildmakes; onserver.restart, read the settings again, build another and serve that, on the same endpoint. - subscribe_
method - Add
workspace.subscribetorouter. - update_
bridge - Run the bridge on
PATH’s ownupdatewithargs; returns its exit code. No bridge onPATHis nothing to update.updatedoes 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.