flowsta-hc-lines
Runs Holochain inside a desktop app: the conductor, the key store, and everything around them that a shipped app needs.
This library is not about identity. An app can link to Flowsta without it, and an app with no Flowsta sign-in can use it. It is here because every Holochain desktop app has to solve the same problems around its conductor, and they are easy to get subtly wrong: a conductor that outlives the app, a start that hangs with no network, a device that drops off its peers' lists, a Holochain upgrade that strands a person's data.
New here? The Rust side shows where this library sits beside the others.
Install
[dependencies]
flowsta-hc-lines = { git = "https://github.com/WeAreFlowsta/flowsta-hc-lines", rev = "<commit>", default-features = false, features = ["line-07"] }Version 0.1, MIT, Rust 1.93 or later. Before 1.0: the interface still changes, so pin a commit. It runs Flowsta Vault's own conductors.
Lines are features
A Holochain line is a series of releases that share a network and a data format: 0.6.x is one line, 0.7.x the next. Each line is a Cargo feature that pins the exact client crates its conductor needs.
| Feature | Conductor | holochain_client | holochain_types | lair_keystore_api |
|---|---|---|---|---|
line-07 | 0.7.1 | =0.9.1 | =0.7.1 | =0.7.1 |
line-06 | 0.6.1 | =0.8.1 | =0.6.1 | =0.6.3 |
A new app needs line-07 only. Both features are on by default, for apps that already have people on 0.6; turn the defaults off as above when you start on 0.7.
Use the pinned crates through the library's re-exports (flowsta_hc_lines::v07::holochain_client and so on), so your app and the library always agree on one version.
Your app bundles the conductor and key store binaries for its line (holochain and lair-keystore) as sidecars. The library starts the ones you bundle; it does not download them.
What is in it
Every part is optional. The first row is the base for most of the others.
| Job | Modules | How to |
|---|---|---|
| Start a conductor and key store, and talk to them | supervisor, conductor, keystore, sidecar, admin, client | Run a conductor |
| Stop them when the app quits, and after a crash | process, reap | Stop cleanly |
| Start with no network; stay listed for peers | rendezvous, keeper | Offline starts and staying listed |
| Bring back a stopped conductor; restart for memory | watch | Keep it running |
| Restore a key's history on a new device | admin, restore | Restore on a new device |
| Run two lines and move data between them | marker, pass, policy, versions, kit | Two versions side by side |
| Fix a window crash on Linux with NVIDIA graphics | webview | The Linux window fix |
Run a conductor
start_line does one line's whole start: the key store (created on the first run), the agent keys, a free admin port, the conductor's config, the conductor, and its admin interface. If any step fails, what was started is stopped.
use flowsta_hc_lines::{conductor, keystore::SocketPlan, rendezvous::Rendezvous, resolve_sidecar, Line, SidecarSource};
use flowsta_hc_lines::conductor::NetworkTuning;
use flowsta_hc_lines::supervisor::{start_line, KeySource, LineStart, Timeouts};
let source = SidecarSource {
dev_dir: Some(dev_binaries_dir), // src-tauri/binaries in a Tauri app
exe_dir: None, // the running executable's folder
kit_dirs: vec![],
allow_path_lookup: false,
};
let origin = conductor::fresh_origin("yourapp");
let process = start_line(
&LineStart {
line: Line::V07,
lair_bin: &resolve_sidecar("lair-keystore", &source)?,
conductor_bin: &resolve_sidecar("holochain", &source)?,
lair_dir: &profile_dir.join("lair"),
conductor_dir: &profile_dir.join("conductor"),
passphrase: &passphrase,
sockets: &SocketPlan::new("yourapp", "lair"),
admin_ports: &[4470, 4471, 4472],
origin: &origin,
rendezvous: &Rendezvous::new("https://bootstrap.example.com"),
tuning: &NetworkTuning::for_line(Line::V07),
agents: &[KeySource::NewSeed { tag: "device".into() }],
timeouts: Timeouts::default(),
},
|step| log::info!("starting: {step:?}"),
)
.await?;Where the agent key comes from is KeySource:
| Variant | The key |
|---|---|
NewSeed { tag } | A random seed that never leaves the key store. A tag already present is that key |
Seed { seed, tag } | A seed your app holds. This is how the device key from flowsta-vault-client gets into the key store, so a backup can carry it |
Existing { tag } | A key that must already be in the store |
The supervisor. For an app that keeps a conductor for hours, Supervisor owns the running lines: it knows which line is serving and on which ports, starts and stops them in the right order, and hands out the admin and app connections. Your app supplies a LineHooks implementation with two methods that matter, start (normally one call to start_line with your settings) and setup (install your DNAs on a conductor that just came up and attach the app interface), then calls Supervisor::start_lines(Line::V07, None, hooks).
Talking to the conductor. AdminClient::connect(line, port, origin) installs, enables and lists apps, and connect_app gives an AppClient whose call(role, zome, fn_name, payload) makes a zome call. Two things your app would otherwise write itself:
ZomeErrorKindsorts a failed call into kinds your code can act on (ChainHeadMoved,CellNotRunning,Timeout, ...), withis_transient()for "try again" andoutcome_unknown()for "the write may have happened".wait_ready_withwaits for a cell to be ready without writing to it.
With Signing::KeyStore, zome calls are signed with the agent's own key from the key store, and nothing is written to the person's chain to authorize them.
Stop cleanly
A conductor that keeps running after the app has quit holds its ports and files, and the next launch fails in confusing ways. Three calls cover it.
fn main() {
// 1. First line of main, before anything else.
flowsta_hc_lines::process::interrupt_helper_or_continue();
// 2. Before the first conductor of this launch starts: end any that
// a crashed run left behind. Pass your sidecars' file names.
flowsta_hc_lines::reap::reap_orphaned_sidecars(&["holochain", "lair-keystore"]);
// ... your app ...
}- At quit,
Supervisor::stop()(orLineProcess::stop()) asks each conductor to shut down, waits a short grace, and only then ends it.
What each one is for:
interrupt_helper_or_continuematters on Windows, which has no signal that asks another program to exit. With this call in place, a conductor is asked to shut down the same way on all three systems, so it closes its databases properly. On macOS and Linux the call does nothing. Sidecars also start with their console windows hidden.reap_orphaned_sidecarsmatches by your sidecars' file names only, and only processes whose parent app is gone, so it never touches another app's conductor. Give your bundled binaries names of your own if another Holochain app might be installed beside yours.- Tied lifetimes. On Linux and Windows a sidecar is also tied to your app's process, so it ends even if your app is killed. On macOS that tie is not there yet; the sweep at the next launch covers it.
Offline starts and staying listed
Starting with no network. A conductor configured with a bootstrap server it cannot reach can sit waiting on it. Rendezvous::for_start(timeout) checks whether the server answers first and gives back the settings to start with either way, so your app opens in seconds on a plane and connects when the network returns.
Staying listed. A conductor tells its bootstrap server where it can be reached, and peers find it there. A device that is awake but cut off for a few minutes (Wi-Fi drops, the server restarts) can fall off that list and stay off until its conductor restarts; meanwhile it looks fine locally and syncs with nobody. Supervisor::start_keeper(servers) runs a small task that, once a minute, reads the conductor's own fresh address notes and re-sends the ones a server lacks. It also tells the conductor about listed peers it has not heard of.
Keeper::same_key_elsewhere() reports when another install is running as the same key, which is worth telling the person about.
In the page, @flowsta/holochain's keepRegistered does the same job for apps without a Rust side.
Keep it running
watch holds the decisions, so every app recovers the same way; your app does the work.
watch::decidelooks at the lines as the supervisor sees them and answers with one action: nothing, restart the session, attach a line again, or hold because it has already recovered as often as yourWatchPolicyallows.MemoryPolicywithconductor_memory(pid)andmemory_restart_due(...): a Holochain 0.7.1 conductor's memory grows over a long session and is given back by a restart. This tells you when a restart is due: over your size limit, running long enough, not restarted recently, and at a moment your app says is quiet.
Restore on a new device
On Holochain 0.7, a key that already has a history on the network can get it back on a new device: the conductor rebuilds the chain from peers. This is the second half of carrying on from a new computer, after the device key itself has arrived from the Vault backup.
One thing needs care. The peers may not yet hold the last records the old device wrote. A restore then completes anyway, shorter than the real history, and writing on top of it would lose those last records for good. So record the length of the chain in your backup, and let the library compare:
AdminClient::install_restoring, once per app of the key.restore::finish(admin, app_id, backup_head, accept_short, waited).Restored::Wholemeans the app is enabled.Restored::Short { have, want }means it is not.- On
Short: callrestore::set_aside, and tell the person that the old device's last changes have not reached the network yet. They can open the app on the old device so it can hand them over, or go on without them. On their word, go back to step 1, passingaccept_short: trueif they chose to go on.
Two versions side by side
Moving an app from one Holochain line to the next is a breaking change: the conductor and key store change version, your DNAs get new hashes and so new networks, and a person's data sits where the new conductor cannot open it. With both line-06 and line-07 compiled in, the library lets one app get through that without putting anyone's data at risk:
- Run both.
Supervisor::start_lines(primary, Some(secondary), hooks)runs the old line's conductor and key store beside the new one. Importing one seed into both key stores (KeySource::Seed) gives the same key on both. - Copy the person's own records from the old line to the new one with
pass::PassRunner. It can be run again safely and resumes after a crash. - Keep writing to both while another of the person's devices is still on the older version of your app (
policy::write_targets). - Retire the old line once nothing needs it (
policy,marker). - Keep a verified copy of each line's conductor in your app's data folder with
kit::KitCache, so a later release of your app, which no longer bundles the old conductor, can still open old data for a person who skipped a few updates.
An app that starts on 0.7 needs none of this today. It is what you will reach for when the next line arrives.
The Linux window fix
On Linux computers where NVIDIA's driver draws the window, a WebKitGTK app (every Tauri app on Linux) can crash when the page changes. webview::apply() checks for that setup and, only there, sets two environment variables that avoid it.
fn main() {
flowsta_hc_lines::process::interrupt_helper_or_continue();
flowsta_hc_lines::webview::apply(); // before any thread starts
// ...
}It does nothing on other systems and on Linux computers that do not need it. A person can turn it off with FLOWSTA_WEBVIEW_FIX=0. webview::set_here() names the variables it set, for programs you start that should not inherit them, such as the Vault.
Smaller helpers
files::write_private,write_atomic,write_atomic_private: write a file with owner-only permissions, or through a temporary file and a rename so a crash never leaves half a file.keystore::repoint_config: point a key store's config at its folder after the folder moved. Safe on every start.conductor::read_logs,files::log_excerpt: the conductor's recent log lines, for your app's own diagnostics.
A complete example
ProofPoll runs both lines on this library. In its src-tauri/src/ folder: conductor.rs (the supervisor, hooks, keeper and watch), dna.rs (installs, the restore), instance_guard.rs (the sweep) and kits.rs (the kit cache).