diff --git a/Cargo.lock b/Cargo.lock index f499d833..27ee6fb7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3934,6 +3934,7 @@ dependencies = [ "registry", "rustls", "scim", + "serde_json", "services", "smtp", "smtp-proto", diff --git a/crates/common/src/manager/boot.rs b/crates/common/src/manager/boot.rs index df4be206..a156356b 100644 --- a/crates/common/src/manager/boot.rs +++ b/crates/common/src/manager/boot.rs @@ -33,6 +33,9 @@ pub struct BootManager { /// inbuxa: K-S3: started with `--upgrade-store`: no listeners, no /// services; main upgrades the store's layout and exits pub upgrade_store: bool, + /// inbuxa: K-C9: started with `--upgrade-plan`: as `--upgrade-store`, + /// but main only reports what an upgrade would do, and exits + pub upgrade_plan: bool, /// inbuxa: K-S8: started with `--seed `: like `--upgrade-store`, /// and then main applies the seed and exits pub seed: Option, @@ -63,6 +66,7 @@ Options: -o, --console Open the store console -u, --upgrade-store Upgrade the store's layout, then exit --seed Set up a new store from a file, then exit + --upgrade-plan Print what --upgrade-store would do, then exit -h, --help Print help -V, --version Print version @@ -84,6 +88,12 @@ once as the system administrator, where {"$file": ""} stands for that file's contents. It upgrades the store's layout first, as --upgrade-store does, and exits: 0 when the seed was applied (or was before, to this store), 1 when it failed, 2 when it refused because the store was set up already. + +--upgrade-plan reads the store and changes nothing. It prints, as one line +of JSON, the layout steps --upgrade-store would run, and exits: 0 when there +are none, 3 when there are and every one can run with older nodes still up, +4 when one needs every other node stopped first, 2 when a newer release has +changed the store, 1 when it can't tell (the message says why). "# ); @@ -96,6 +106,8 @@ enum StoreOp { UpgradeStore, // inbuxa: K-S8 Seed(PathBuf), + // inbuxa: K-C9 + UpgradePlan, None, } @@ -153,6 +165,9 @@ impl BootManager { ("upgrade-store" | "u", None) => { import_export = StoreOp::UpgradeStore; } + ("upgrade-plan", None) => { + import_export = StoreOp::UpgradePlan; + } ("seed", Some(value)) => { import_export = StoreOp::Seed(value.into()); } @@ -182,7 +197,8 @@ impl BootManager { _ => None, }; // inbuxa: K-S8: a seed run boots as --upgrade-store does - let one_shot = upgrade_store || seed.is_some(); + let upgrade_plan = import_export == StoreOp::UpgradePlan; + let one_shot = upgrade_store || upgrade_plan || seed.is_some(); let registry = RegistryStore::init( PathBuf::from(config_path.unwrap()), import_export == StoreOp::None || one_shot, @@ -226,7 +242,7 @@ impl BootManager { let telemetry = Telemetry::parse(&mut bootstrap, &storage).await; match import_export { - StoreOp::None | StoreOp::UpgradeStore | StoreOp::Seed(_) => { + StoreOp::None | StoreOp::UpgradeStore | StoreOp::UpgradePlan | StoreOp::Seed(_) => { // Parse components let core: Box = Box::new(Box::pin(Core::parse(&mut bootstrap, storage)).await); @@ -242,6 +258,8 @@ impl BootManager { Server(trc::ServerEvent::Startup), Details = if upgrade_store { "Started with --upgrade-store: upgrading the store layout, then exiting" + } else if upgrade_plan { + "Started with --upgrade-plan: reporting what an upgrade would do, then exiting" } else { "Started with --seed: setting up a new store from a file, then exiting" }, @@ -335,6 +353,7 @@ impl BootManager { servers, ipc_rxs, upgrade_store, + upgrade_plan, seed, store_was_new, } diff --git a/crates/main/Cargo.toml b/crates/main/Cargo.toml index 38d7060d..c7277008 100644 --- a/crates/main/Cargo.toml +++ b/crates/main/Cargo.toml @@ -15,6 +15,7 @@ name = "inbuxa" path = "src/main.rs" [dependencies] +serde_json = "1.0" store = { path = "../store" } coordinator = { path = "../coordinator" } jmap = { path = "../jmap" } diff --git a/crates/main/src/main.rs b/crates/main/src/main.rs index 987ba095..83bcb9b7 100644 --- a/crates/main/src/main.rs +++ b/crates/main/src/main.rs @@ -68,6 +68,12 @@ async fn main() -> std::io::Result<()> { std::process::exit(Box::pin(upgrade_store_and_exit(&server)).await); } + // inbuxa: K-C9: --upgrade-plan reports what an upgrade would do + if init.upgrade_plan { + let server = init.inner.build_server(); + std::process::exit(Box::pin(upgrade_plan_and_exit(&server)).await); + } + // inbuxa: K-S8: --seed sets up a new store from a file and exits if let Some(path) = init.seed.clone() { let server = init.inner.build_server(); @@ -260,6 +266,62 @@ async fn seed_and_exit( flush_and_exit_code(code).await } +/// inbuxa: K-C9: `--upgrade-plan`: one line of JSON on stdout, for a +/// script to read, and the exit code a shell can branch on +async fn upgrade_plan_and_exit(server: &common::Server) -> i32 { + use migration::UpgradePlan; + + let target = common::INBUXA_STORE_VERSION; + let (code, plan) = match migration::upgrade_plan(server).await { + Ok(UpgradePlan::NewStore) => ( + 0, + serde_json::json!({"store": null, "target": target, "newStore": true, "steps": [], "stopAllNodes": false}), + ), + Ok(UpgradePlan::Steps { from, steps }) => { + let stop = steps.iter().any(|step| !step.rolling_safe); + let code = match (steps.is_empty(), stop) { + (true, _) => 0, + (false, false) => 3, + (false, true) => 4, + }; + let steps = steps + .iter() + .map(|step| { + serde_json::json!({ + "from": step.from, + "to": step.from + 1, + "rollingSafe": step.rolling_safe, + "what": step.what, + }) + }) + .collect::>(); + ( + code, + serde_json::json!({"store": from, "target": target, "newStore": false, "steps": steps, "stopAllNodes": stop}), + ) + } + Ok(UpgradePlan::Newer(version)) => { + eprintln!( + "A newer release changed this store (layout version {version}; this release reads up to {target})." + ); + ( + 2, + serde_json::json!({"store": version, "target": target, "newer": true}), + ) + } + Ok(UpgradePlan::NeedsMigration(reason)) => { + eprintln!("Can't plan an upgrade: {reason}."); + return flush_and_exit_code(1).await; + } + Err(err) => { + eprintln!("Can't plan an upgrade: {err}"); + return flush_and_exit_code(1).await; + } + }; + println!("{plan}"); + flush_and_exit_code(code).await +} + async fn upgrade_store_only(server: &common::Server) -> (i32, String) { use migration::layout::Outcome; diff --git a/crates/migration/src/layout.rs b/crates/migration/src/layout.rs index 4ba97626..2ed2605a 100644 --- a/crates/migration/src/layout.rs +++ b/crates/migration/src/layout.rs @@ -89,6 +89,27 @@ const STEPS: &[Step] = &[ }, ]; +/// inbuxa: a step an upgrade would run, for `--upgrade-plan` +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PlannedStep { + pub from: u32, + pub rolling_safe: bool, + pub what: &'static str, +} + +/// The steps from layout `version` up to this build's, in order +pub fn steps_from(version: u32) -> Vec { + STEPS + .iter() + .filter(|step| step.from >= version && step.from < INBUXA_STORE_VERSION) + .map(|step| PlannedStep { + from: step.from, + rolling_safe: step.rolling_safe, + what: step.what, + }) + .collect() +} + async fn run_step(server: &Server, from: u32) -> trc::Result { match from { 1 => counters_keep_expiry(server).await, @@ -561,3 +582,18 @@ async fn move_counter_expiry(store: &Store) -> trc::Result { Ok(changed) } + +#[cfg(test)] +mod plan_tests { + use super::*; + + #[test] + fn plans_every_step_from_a_version() { + let all = steps_from(1); + assert_eq!(all.iter().map(|s| s.from).collect::>(), vec![1, 2]); + assert!(all[0].rolling_safe); + assert!(!all[1].rolling_safe); + assert_eq!(steps_from(2).len(), 1); + assert!(steps_from(INBUXA_STORE_VERSION).is_empty()); + } +} diff --git a/crates/migration/src/lib.rs b/crates/migration/src/lib.rs index b5ea4405..12202d41 100644 --- a/crates/migration/src/lib.rs +++ b/crates/migration/src/lib.rs @@ -33,6 +33,56 @@ pub async fn upgrade_store(server: &Server) -> trc::Result { migrate(server, layout::Run::UpgradeOnly).await } +/// inbuxa: what an upgrade of this store to this build would do, for +/// `--upgrade-plan`. Reads only: the decisions are `migrate`'s. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum UpgradePlan { + /// A store nothing has written yet: a first start marks it, no steps + NewStore, + /// The store's layout version and the steps from it; none when current + Steps { + from: u32, + steps: Vec, + }, + /// A newer release changed this store; this build refuses it + Newer(u32), + /// Not something an upgrade does: a migration by hand comes first + NeedsMigration(&'static str), +} + +pub async fn upgrade_plan(server: &Server) -> trc::Result { + let store_version = layout::store_version(server.store()).await?; + if let Some(version) = store_version.filter(|version| *version > INBUXA_STORE_VERSION) { + return Ok(UpgradePlan::Newer(version)); + } + + let schema = server + .store() + .get_value::(AnyKey { + subspace: SUBSPACE_PROPERTY, + key: vec![0u8], + }) + .await + .caused_by(trc::location!())?; + let from = match schema { + Some(DATABASE_SCHEMA_VERSION) => store_version.unwrap_or(1), + None if is_new_install(server).await.caused_by(trc::location!())? => { + return Ok(UpgradePlan::NewStore); + } + _ => { + return Ok(UpgradePlan::NeedsMigration( + "the store is from before 0.16 and needs the migration in \ + https://docs.inbuxa.org/install/migrating/ first", + )); + } + }; + + Ok(UpgradePlan::Steps { + from, + steps: layout::steps_from(from), + }) +} + async fn migrate(server: &Server, run: layout::Run) -> trc::Result { // inbuxa: a store a newer release has changed is refused before anything // below writes to it. diff --git a/tests/src/store_version.rs b/tests/src/store_version.rs index 12b41f64..7174d3c2 100644 --- a/tests/src/store_version.rs +++ b/tests/src/store_version.rs @@ -95,6 +95,7 @@ async fn store_version() { layout_step_1_2(server).await; layout_lease(server).await; upgrade_store_only(server).await; + upgrade_plan(server).await; layout_step_2_3(server).await; } @@ -309,6 +310,51 @@ async fn layout_lease(server: &Server) { assert!(!lease_held(server).await, "lease not released"); } +// inbuxa: K-C9: `--upgrade-plan` names the steps an upgrade would run and +// whether one needs every other node stopped, and writes nothing. +async fn upgrade_plan(server: &Server) { + use migration::UpgradePlan; + + let steps = |plan: UpgradePlan| match plan { + UpgradePlan::Steps { from, steps } => ( + from, + steps + .iter() + .map(|s| (s.from, s.rolling_safe)) + .collect::>(), + ), + other => panic!("expected steps, got {other:?}"), + }; + + write_mark(server, Some(INBUXA_STORE_VERSION)).await; + assert_eq!( + steps(migration::upgrade_plan(server).await.unwrap()), + (INBUXA_STORE_VERSION, vec![]) + ); + + // From 2026.x (layout 1): both steps, the second not rolling-safe + write_mark(server, Some(1)).await; + assert_eq!( + steps(migration::upgrade_plan(server).await.unwrap()), + (1, vec![(1, true), (2, false)]) + ); + assert_eq!(read_mark(server).await, Some(1), "the plan wrote the mark"); + + write_mark(server, Some(2)).await; + assert_eq!( + steps(migration::upgrade_plan(server).await.unwrap()), + (2, vec![(2, false)]) + ); + + write_mark(server, Some(INBUXA_STORE_VERSION + 1)).await; + assert_eq!( + migration::upgrade_plan(server).await.unwrap(), + UpgradePlan::Newer(INBUXA_STORE_VERSION + 1) + ); + + write_mark(server, Some(INBUXA_STORE_VERSION)).await; +} + // inbuxa: K-S3: `--upgrade-store` upgrades and stops; it changes nothing on // a current store, and refuses, rather than waits, while another node holds // the lease.