From 0023300b417b2375026750b1b0924adfd94c4e03 Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 21:38:52 +0000 Subject: continuum is a library Everything the node is moves from the binary into a library (`src/lib.rs`), so that other binaries can use it: a party's client of a federation next. The node's binary (`src/main.rs`) runs it (`continuum::run`), which wires things together as `main` did. The library's doc comments are prose, not examples to test (`doctest = false`); its tests are the library's, as `cargo quick` and `cargo sim` run them. --- src/lib.rs | 507 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 507 insertions(+) create mode 100644 src/lib.rs (limited to 'src/lib.rs') diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..323bbc1 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,507 @@ +//! continuum: a replicated Automerge document, read and written by path, synchronized +//! over Mycelium, libp2p or Tor; as a library, which the node (`main.rs`) runs (`run`). +//! +//! `run` only wires things together: arguments, the starting document, the node +//! (`node`), bootstrap and the HTTP server. + +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, Ordering}; + +use anyhow::{Context, Result}; +use tokio::sync::watch; +use tracing::{debug, error, info, warn}; + +mod access; +mod api; +mod backoff; +mod clock; +mod compress; +mod config; +mod document; +#[cfg(feature = "federation")] +mod federation; +mod files; +mod force; +mod identity; +mod locks; +mod logging; +mod node; +mod remake; +#[cfg(test)] +mod simtest; +mod state; +mod swarm; +#[cfg(test)] +mod testrand; +mod transport; +mod units; + +use api::auth::AuthState; +use document::Document; +use document::replica::Epoch; +use swarm::bootstrap; +use transport::Transport; + +/// Runs a node, as its arguments and configuration say, until it stops. +pub async fn run() -> Result<()> { + logging::init(); + + let config = config::load()?; + if config.print_only { + println!( + "{}", + serde_json::to_string_pretty(&config.report(config::Values::Interpolated))? + ); + return Ok(()); + } + let args = &config.settings; + if let Some(format) = logging::LogFormat::parse(&args.log_format) { + logging::set_format(format); + } + for (transport, built, options) in config.unused_transport_options() { + warn!( + transport, + built, + options = ?options, + "Options of a transport this node doesn't use are ignored" + ); + } + // Only with libp2p: without, `config` refuses `relay-only` already. + #[cfg(feature = "libp2p")] + if args.relay_only { + return relay_only(args).await; + } + + // Read before anything starts, so a bad key file fails right away. + let node_key_file = args + .node_key_file + .as_deref() + .context("node-key-file is required")?; + let node_key = Arc::new(identity::NodeKey::load( + node_key_file, + args.node_key_create, + )?); + info!(node_id = %node_key.id(), "Node identity"); + let swarm_key = match &args.swarm_key_file { + Some(path) => Some(Arc::new(swarm::auth::SwarmKey::from_file( + path, + args.swarm_key_create, + )?)), + None => { + warn!("No swarm key: any node that can reach a member may join"); + None + } + }; + + // First thing: until a handler is installed, SIGINT and SIGTERM kill the process on + // the spot, and startup (starting transports, bootstrap) can take minutes. + let stop = watch_for_shutdown().context("Installing signal handlers")?; + // A broken htpasswd will abort startup. + let auth_state = + AuthState::from_settings(&args)?.context("htpasswd or user-header is required")?; + // A new swarm's first users, if it is to have a user registry; the users of the + // htpasswd file that aren't among them may do nothing until they are added. + let first_users = if args.genesis { + access::registry::first_users(&args.bootstrap_users, &args.bootstrap_keys) + .map_err(anyhow::Error::msg)? + } else { + Default::default() + }; + let first_policy = if args.genesis { + access::policy::first(args.bootstrap_policy.as_deref(), &args.bootstrap_keys) + .map_err(anyhow::Error::msg)? + } else { + None + }; + if !first_users.is_empty() + && let Some(path) = args.htpasswd.as_deref() + { + let missing: Vec = api::auth::htpasswd_names(path)? + .into_iter() + .filter(|name| !args.bootstrap_users.contains(name)) + .collect(); + if !missing.is_empty() { + warn!(users = ?missing, "Users of htpasswd not among bootstrap-users: the new swarm's registry doesn't have them, so they may do nothing until added (docs/access.md)"); + } + } + + info!( + bind_addr = ?args.bind_addr.iter().map(ToString::to_string).collect::>(), + transports = ?args.transports, + "Starting replication service" + ); + + let force = force::Force::parse(args.force.iter().map(String::as_str), config::FORCE) + .map_err(anyhow::Error::msg)?; + let files = Arc::new(files::Files::default()); + let mut seeds: Vec = args.seeds.clone(); + let (state_file, remembered) = match &args.state_file { + Some(path) => { + let (file, remembered) = + swarm::state_file::StateFile::open(path.clone(), Arc::clone(&files)); + (Some(Arc::new(file)), remembered) + } + None => (None, None), + }; + logging::set_raw_ids(args.log_raw_ids); + if let Some(remembered) = &remembered { + logging::set_aliases(remembered.aliases.clone().into_iter().collect()); + info!( + swarm_id = %remembered.swarm_id, + seeds = remembered.seeds.len(), + "Remembering a swarm from the state file" + ); + for seed in &remembered.seeds { + if !seeds.contains(seed) { + seeds.push(seed.clone()); + } + } + } else if args.genesis && state_file.is_none() { + warn!( + "--genesis without --state-file: every restart with --genesis starts another new swarm" + ); + } + debug!(seed_count = seeds.len(), "Loaded bootstrap configuration"); + + let starting = bootstrap::starting_document( + &bootstrap::StartOptions { + recover_from: args.recover_from.as_deref(), + document_file: args.document_file.as_deref(), + genesis: args.genesis, + remembered: remembered.as_ref().map(|r| r.swarm_id.as_str()), + }, + &files, + &force, + )?; + // A swarm holding a store: started from its root, or joined by its ID. + #[cfg(feature = "federation")] + let store = + bootstrap::StoreStart::of(args.store_root.as_deref(), args.store_id.as_deref(), &files)?; + #[cfg(feature = "federation")] + let starting = match &store { + Some(store) => { + store.starting(starting, remembered.as_ref().map(|r| r.swarm_id.as_str()))? + } + None => starting, + }; + let ( + initial_doc, + starting_epoch, + starting_swarm, + earlier_actors, + initial_signatures, + resumable, + ) = match starting { + Some(starting) => ( + starting.doc, + Some(starting.epoch), + Some((starting.swarm_id, starting.origin)), + starting.earlier_actors, + starting.signatures, + starting.resumable, + ), + None => (Document::new(), None, None, Vec::new(), Vec::new(), None), + }; + let mut initial_doc = initial_doc; + let document_file = args.document_file.clone().map(|path| { + Arc::new(document::file::DocumentFile::new( + path, + Arc::clone(&files), + args.document_append, + args.document_rewrite, + )) + }); + // A clean stop's mark undone before anything is written, and before deciding the + // actor: a crash from here on leaves a file that doesn't say so. A file that still + // says so (the mark not undone) gets a fresh actor. + let opened = document_file.as_ref().is_none_or(|file| file.open()); + // Writing on as the actor of before, where this node stopped cleanly: everything it + // wrote as that one is in the document, so no change of it comes twice. + match resumable.filter(|_| args.keep_actor && opened) { + Some(actor) => { + info!(actor = %actor, "Writing on as the actor of before (--keep-actor)"); + initial_doc.set_actor(actor); + } + None if args.keep_actor && !opened => { + warn!( + "Writing as a fresh actor: the document file couldn't be marked as opened (--keep-actor)" + ); + } + None if args.keep_actor && starting_epoch.is_some() => { + info!("Writing as a fresh actor: this node didn't stop cleanly (--keep-actor)"); + } + None => {} + } + if let Some(spec) = &args.remake { + remake::remake_genesis(spec, &files, &mut initial_doc) + .with_context(|| format!("Making the genesis document (--remake {spec})"))?; + info!(remake = %spec, "Made the genesis document"); + } + let initial_epoch = match (starting_epoch, args.debug_epoch) { + (Some(epoch), _) => epoch, + (None, Some(generation)) => Epoch { + generation, + id: [0xee; 32], + }, + (None, None) => Epoch::GENESIS, + }; + debug!(epoch = %initial_epoch, "Local epoch"); + + // The enabled, in the order of preference (`--transport-order`, checked when + // loading). + let mut transports: Vec<(&'static str, Arc)> = Vec::new(); + for name in &args.transports { + let Some(transport) = transport::start(name, args, &node_key, stop.clone()).await? else { + return Ok(()); + }; + info!( + transport = transport.0, + address = transport.1.local_id(), + "Transport ready" + ); + transports.push(transport); + } + let delivery_limit = transports + .iter() + .map(|(_, transport)| transport.delivery_limit()) + .max() + .unwrap_or_default(); + // An answer may come over any of them. + let sync_reply_timeout = transports + .iter() + .map(|(_, transport)| transport.sync_reply_timeout()) + .max() + .unwrap_or(state::SYNC_REPLY_TIMEOUT); + let mut transports = transports.into_iter(); + let (scheme, transport) = transports.next().context("No transports")?; + + let node = node::Node::new(node::NodeConfig { + transport, + identity: Some(transport::identity::IdentityConfig { + key: Arc::clone(&node_key), + scheme, + more: transports.collect(), + }), + initial_epoch, + initial_doc, + earlier_actors, + initial_signatures, + timing: state::Timing::new(args.keepalive, sync_reply_timeout, delivery_limit) + .with_probe_max(args.dormant_probe_max), + neighbours_k: args.neighbours, + alias: args.alias.clone(), + dashboard_url: args.dashboard_url.clone(), + electorate_window: args.electorate_window, + clock_skew_warn: args.clock_skew_warn, + stream_heartbeat: args.stream_heartbeat, + superseded_writes: args.superseded_writes, + topology: args.topology, + dissemination: args.dissemination, + // At most 4MiB (`Settings::check`). + blob_chunk_bytes: args.blob_chunk as u32, + swarm_key, + protocol_writers: args.protocol_writers.iter().cloned().collect(), + first_users, + first_policy, + node_key: Some(Arc::clone(&node_key)), + sign_every: args.sign_every, + token_lifetime: args.token_lifetime, + session_lifetime: args.session_lifetime, + challenge_lifetime: args.challenge_lifetime, + genesis_root: args.genesis_root.as_deref().and_then(swarm::roots::parse), + #[cfg(feature = "federation")] + store: store.as_ref().map(|store| store.id), + #[cfg(feature = "federation")] + holding: federation::held::Holding::open( + args.store_file.clone(), + Arc::clone(&files), + args.store_checkpoint + .as_deref() + .and_then(federation::store::Id::from_hex), + args.store_party.clone(), + )? + .near(args.store_neighbour_parties.clone()), + strict_keys: args + .strict_keys + .iter() + .filter_map(|line| access::sshsig::PublicKey::parse(line).ok()) + .collect(), + key_logins_per_user: args.key_logins_per_user, + refused_writes_per_minute: args.refused_writes_per_minute, + cors_origins: args.cors_origins.clone(), + files, + state_file, + document_file, + config_reports: config.reports(), + clock: Default::default(), + }); + let state = node.state.clone(); + + // Join the remembered swarm and no other; HELLOs claim it. A document to start on + // names its swarm itself (checked against the remembered one above). + let start = match starting_swarm { + Some((swarm_id, origin)) => { + state.set_expected_swarm_id(swarm_id).await?; + bootstrap::Start::FromDocument(origin) + } + None => { + let expected = remembered.map(|remembered| remembered.swarm_id); + #[cfg(feature = "federation")] + let expected = expected.or_else(|| store.as_ref().map(bootstrap::StoreStart::swarm_id)); + if let Some(expected) = expected { + state.set_expected_swarm_id(expected).await?; + } + if args.genesis { + bootstrap::Start::Genesis + } else { + bootstrap::Start::Join + } + } + }; + + node.spawn_workers(); + + // The API is up while the node joins: what it serves then is the handlers' business + // (`docs/lifecycle.md`), and /peers and /admin/stats show how joining goes. + let joined = AtomicBool::new(false); + let app = api::router(state.clone(), auth_state, args.debug_api); + + // The node shutting down (`AppState::closing`): the servers drain. + let closing = state.closing.subscribe(); + let server_fut = api::listen::serve(&args.bind_addr, app, move || { + let closing = closing.clone(); + async move { + stopped(closing).await; + info!("Shutdown signal received. Draining API connections...") + } + }) + .await?; + tokio::pin!(server_fut); + + // Joins, then runs until stopped; returns only if joining fails. + let joining = async { + bootstrap::bootstrap(&state, &seeds, start) + .await + .context("Joining swarm")?; + node::spawn_ready_workers(&state); + info!( + swarm_id = ?state.swarm_id().await, + ready = state.is_ready().await, + "Bootstrap completed" + ); + swarm::state_file::update(&state, true).await; + joined.store(true, Ordering::Release); + std::future::pending::>().await + }; + tokio::pin!(joining); + + tokio::select! { + failed = joining.as_mut() => { + state.closing.send_replace(true); + let _ = server_fut.as_mut().await; + return failed; + } + + exit_status = state.transport.wait_for_exit() => { + error!(status = ?exit_status, "A transport stopped"); + state.closing.send_replace(true); + let _ = server_fut.as_mut().await; + } + + server_result = server_fut.as_mut() => { + if let Err(e) = server_result { + error!("Axum HTTP server encountered a runtime error: {:?}", e); + } else { + info!("Axum HTTP engine shutdown cleanly."); + } + } + + _ = stopped(stop.clone()) => { + state.closing.send_replace(true); + let _ = server_fut.as_mut().await; + } + } + + info!("HTTP API server stopped"); + if !joined.load(Ordering::Acquire) { + info!("Stopped while joining the swarm"); + return Ok(()); + } + swarm::peer::farewell(&state).await; + swarm::state_file::update(&state, true).await; + swarm::document_file::flush(&state).await; + swarm::document_file::close(&state).await; + Ok(()) +} + +/// `--relay-only`: libp2p relaying for nodes of swarms, and the HTTP API's relay part +/// (with `--htpasswd`), until stopped. +#[cfg(feature = "libp2p")] +async fn relay_only(args: &config::Settings) -> Result<()> { + let stop = watch_for_shutdown().context("Installing signal handlers")?; + let auth_state = AuthState::from_settings(args)?; + let transport: Arc = Arc::new(transport::libp2p::Libp2pTransport::start( + transport::libp2p::Libp2pConfig::from_settings(args, true)?, + )?); + info!(peer_id = transport.local_id(), "Relaying only (no node)"); + + let server = match auth_state { + Some(auth_state) => { + let app = api::relay_only_router(Arc::clone(&transport), auth_state); + let stop = stop.clone(); + let served = + api::listen::serve(&args.bind_addr, app, move || stopped(stop.clone())).await?; + Some(tokio::spawn(served)) + } + None => { + info!("No htpasswd or user-header: no HTTP API"); + None + } + }; + + tokio::select! { + exit = transport.wait_for_exit() => error!(status = ?exit, "The libp2p transport stopped"), + _ = stopped(stop.clone()) => {} + } + if let Some(server) = server { + let _ = server.await; + } + info!("Relay stopped"); + Ok(()) +} + +/// Turns SIGINT and SIGTERM into a shutdown request. A second signal exits at once (the +/// supervised Mycelium still gets its parent-death signal then). +fn watch_for_shutdown() -> Result> { + use tokio::signal::unix::{SignalKind, signal}; + + let mut interrupt = signal(SignalKind::interrupt())?; + let mut terminate = signal(SignalKind::terminate())?; + let (stop_tx, stop_rx) = watch::channel(false); + + tokio::spawn(async move { + let name = tokio::select! { + _ = interrupt.recv() => "SIGINT", + _ = terminate.recv() => "SIGTERM", + }; + info!( + signal = name, + "Shutting down (send it again to exit immediately)" + ); + let _ = stop_tx.send(true); + + tokio::select! { + _ = interrupt.recv() => {} + _ = terminate.recv() => {} + } + error!("Second signal; exiting immediately"); + std::process::exit(130); + }); + + Ok(stop_rx) +} + +/// Resolves once a shutdown was requested. +async fn stopped(mut stop: watch::Receiver) { + let _ = stop.wait_for(|stop| *stop).await; +} -- cgit v1.3.1