--upgrade-plan: what --upgrade-store would do, read only #457

Merged
jcoffey-dev merged 1 commits from feat/upgrade-plan into main 2026-11-18 21:01:21 +00:00
7 changed files with 217 additions and 2 deletions

No files matched your search

Generated
+1
View File
@@ -3934,6 +3934,7 @@ dependencies = [
"registry",
"rustls",
"scim",
"serde_json",
"services",
"smtp",
"smtp-proto",
+21 -2
View File
@@ -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 <PATH>`: like `--upgrade-store`,
/// and then main applies the seed and exits
pub seed: Option<PathBuf>,
@@ -63,6 +66,7 @@ Options:
-o, --console Open the store console
-u, --upgrade-store Upgrade the store's layout, then exit
--seed <PATH> 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": "<PATH>"} 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<Core> =
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,
}
+1
View File
@@ -15,6 +15,7 @@ name = "inbuxa"
path = "src/main.rs"
[dependencies]
serde_json = "1.0"
store = { path = "../store" }
coordinator = { path = "../coordinator" }
jmap = { path = "../jmap" }
+62
View File
@@ -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::<Vec<_>>();
(
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;
+36
View File
@@ -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<PlannedStep> {
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<u64> {
match from {
1 => counters_keep_expiry(server).await,
@@ -561,3 +582,18 @@ async fn move_counter_expiry(store: &Store) -> trc::Result<u64> {
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<_>>(), 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());
}
}
+50
View File
@@ -33,6 +33,56 @@ pub async fn upgrade_store(server: &Server) -> trc::Result<layout::Outcome> {
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<layout::PlannedStep>,
},
/// 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<UpgradePlan> {
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::<u32>(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<layout::Outcome> {
// inbuxa: a store a newer release has changed is refused before anything
// below writes to it.
+46
View File
@@ -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::<Vec<_>>(),
),
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.