Add warning prompt for 1.0 -> 2.0 module upgrade path (#4247)

# Description of Changes

Adds a warning prompt for 1.0 -> 2.0 module upgrade path.

# API and ABI breaking changes

None

# Expected complexity level and risk

1

# Testing

This patch checks a wasm module binary compiled with pre-2.0 bindings
into source control. A smoketest was added that first publishes the the
pre-compiled module and then publishes a new module using the 2.0
bindings in its place.

Author: joshua-spacetime

crates/cli/src/subcommands/publish.rs

@@ -134,6 +134,27 @@ fn confirm_and_clear(
     Ok(builder)
 }
 
+fn confirm_major_version_upgrade() -> Result<(), anyhow::Error> {
+    println!(
+        "It looks like you're trying to do a major version upgrade from 1.0 to 2.0. We recommend first looking at the upgrade notes before committing to this upgrade: https://spacetimedb.com/docs/upgrade"
+    );
+    println!();
+    println!("WARNING: Once you publish you cannot revert back to version 1.0.");
+    println!();
+
+    let mut input = String::new();
+    print!("Please type 'upgrade' to accept this change: ");
+    let mut stdout = std::io::stdout();
+    std::io::Write::flush(&mut stdout)?;
+    std::io::stdin().read_line(&mut input)?;
+
+    if input.trim() == "upgrade" {
+        return Ok(());
+    }
+
+    anyhow::bail!("Aborting because major version upgrade was not accepted.");
+}
+
 pub async fn exec(mut config: Config, args: &ArgMatches) -> Result<(), anyhow::Error> {
     let server = args.get_one::<String>("server").map(|s| s.as_str());
     let name_or_identity = args.get_one::<String>("name|identity");
@@ -377,6 +398,14 @@ async fn apply_pre_publish_if_needed(
     )
     .await?
     {
+        let major_version_upgrade = match &pre {
+            PrePublishResult::AutoMigrate(auto) => auto.major_version_upgrade,
+            PrePublishResult::ManualMigrate(manual) => manual.major_version_upgrade,
+        };
+        if major_version_upgrade {
+            confirm_major_version_upgrade()?;
+        }
+
         match pre {
             PrePublishResult::ManualMigrate(manual) => {
                 if clear_database == ClearMode::Never {

crates/client-api-messages/src/name.rs

@@ -131,11 +131,13 @@ pub struct PrePublishAutoMigrateResult {
     pub migrate_plan: Box<str>,
     pub break_clients: bool,
     pub token: spacetimedb_lib::Hash,
+    pub major_version_upgrade: bool,
 }
 
 #[derive(serde::Serialize, serde::Deserialize, Debug)]
 pub struct PrePublishManualMigrateResult {
     pub reason: String,
+    pub major_version_upgrade: bool,
 }
 
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]

crates/client-api/src/routes/database.rs

@@ -942,6 +942,7 @@ pub async fn pre_publish<S: NodeDelegate + ControlStateDelegate + Authorization>
             new_module_hash,
             breaks_client,
             plan,
+            major_version_upgrade,
         } => {
             info!(
                 "planned auto-migration of database {} from {} to {}",
@@ -958,12 +959,17 @@ pub async fn pre_publish<S: NodeDelegate + ControlStateDelegate + Authorization>
                 token,
                 migrate_plan: plan,
                 break_clients: breaks_client,
+                major_version_upgrade,
             }))
         }
-        MigratePlanResult::AutoMigrationError(e) => {
+        MigratePlanResult::AutoMigrationError {
+            error: e,
+            major_version_upgrade,
+        } => {
             info!("database {database_identity} needs manual migration");
             Ok(PrePublishResult::ManualMigrate(PrePublishManualMigrateResult {
                 reason: e.to_string(),
+                major_version_upgrade,
             }))
         }
     }

crates/core/src/host/host_controller.rs

@@ -36,7 +36,7 @@ use spacetimedb_lib::{hash_bytes, AlgebraicValue, Identity, Timestamp};
 use spacetimedb_paths::server::{ModuleLogsDir, ServerDataDir};
 use spacetimedb_sats::hash::Hash;
 use spacetimedb_schema::auto_migrate::{ponder_migrate, AutoMigrateError, MigrationPolicy, PrettyPrintStyle};
-use spacetimedb_schema::def::ModuleDef;
+use spacetimedb_schema::def::{ModuleDef, RawModuleDefVersion};
 use spacetimedb_table::page_pool::PagePool;
 use std::future::Future;
 use std::ops::Deref;
@@ -1161,15 +1161,26 @@ impl Host {
 
         let module_def =
             extract_schema_with_pools(page_pool, bsatn_rlb_pool, host_runtimes, program.bytes, host_type).await?;
+        let major_version_upgrade = matches!(
+            (
+                old_module.module_def.raw_module_def_version(),
+                module_def.raw_module_def_version()
+            ),
+            (RawModuleDefVersion::V9OrEarlier, RawModuleDefVersion::V10)
+        );
 
         let res = match ponder_migrate(&old_module.module_def, &module_def) {
             Ok(plan) => MigratePlanResult::Success {
                 old_module_hash: old_module.module_hash,
                 new_module_hash: program.hash,
                 breaks_client: plan.breaks_client(),
                 plan: plan.pretty_print(style)?.into(),
+                major_version_upgrade,
+            },
+            Err(e) => MigratePlanResult::AutoMigrationError {
+                error: e,
+                major_version_upgrade,
             },
-            Err(e) => MigratePlanResult::AutoMigrationError(e),
         };
 
         Ok(res)
@@ -1194,8 +1205,12 @@ pub enum MigratePlanResult {
         new_module_hash: Hash,
         plan: Box<str>,
         breaks_client: bool,
+        major_version_upgrade: bool,
+    },
+    AutoMigrationError {
+        error: ErrorStream<AutoMigrateError>,
+        major_version_upgrade: bool,
     },
-    AutoMigrationError(ErrorStream<AutoMigrateError>),
 }
 
 const STORAGE_METERING_INTERVAL: Duration = Duration::from_secs(15);

crates/schema/src/def.rs

@@ -148,7 +148,7 @@ pub struct ModuleDef {
     raw_module_def_version: RawModuleDefVersion,
 }
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum RawModuleDefVersion {
     /// Represents [`RawModuleDefV9`] and earlier.
     V9OrEarlier,
@@ -157,6 +157,11 @@ pub enum RawModuleDefVersion {
 }
 
 impl ModuleDef {
+    /// The raw module definition version this module was authored under.
+    pub fn raw_module_def_version(&self) -> RawModuleDefVersion {
+        self.raw_module_def_version
+    }
+
     /// The tables of the module definition.
     pub fn tables(&self) -> impl Iterator<Item = &TableDef> {
         self.tables.values()

crates/smoketests/fixtures/README.md

@@ -0,0 +1,46 @@
+# Smoketest Fixtures
+
+`upgrade_old_module_v1.wasm` is an old-format module fixture used by
+`crates/smoketests/tests/publish_upgrade_prompt.rs` to test the `1.0 -> 2.0`
+upgrade confirmation flow.
+
+It was produced from a pre-`RawModuleDefV10` bindings snapshot and exports
+`__describe_module__` (not `__describe_module_v10__`).
+
+## Regenerate
+
+```bash
+# from repo root
+TMP="$(mktemp -d)"
+git archive --format=tar d3f59480e -o "$TMP/old-repo.tar"
+mkdir -p "$TMP/old-repo"
+tar -xf "$TMP/old-repo.tar" -C "$TMP/old-repo"
+
+mkdir -p "$TMP/old-module/src"
+cat > "$TMP/old-module/Cargo.toml" <<EOF
+[package]
+name = "upgrade_old_module"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+spacetimedb = { path = "$TMP/old-repo/crates/bindings", features = ["unstable"] }
+EOF
+
+cat > "$TMP/old-module/src/lib.rs" <<'EOF'
+use spacetimedb::{reducer, ReducerContext};
+
+#[reducer]
+pub fn noop(_ctx: &ReducerContext) {}
+EOF
+
+CARGO_NET_OFFLINE=true CARGO_TARGET_DIR="$TMP/target-old" \
+  cargo build --release --target wasm32-unknown-unknown \
+  --manifest-path "$TMP/old-module/Cargo.toml"
+
+cp "$TMP/target-old/wasm32-unknown-unknown/release/upgrade_old_module.wasm" \
+  crates/smoketests/fixtures/upgrade_old_module_v1.wasm
+```

crates/smoketests/fixtures/upgrade_old_module_v1.wasm

@@ -57,7 +57,7 @@ use regex::Regex;
 use spacetimedb_guard::{ensure_binaries_built, SpacetimeDbGuard};
 use std::env;
 use std::fs;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::process::{Command, Output, Stdio};
 use std::sync::OnceLock;
 use std::time::Instant;
@@ -607,6 +607,40 @@ impl Smoketest {
         output
     }
 
+    /// Runs a spacetime CLI command with stdin input.
+    ///
+    /// Returns the command output. The command is run but not yet asserted.
+    /// Uses --config-path to isolate test config from user config.
+    /// Callers should pass `--server` explicitly when the command needs it.
+    pub fn spacetime_cmd_with_stdin(&self, args: &[&str], stdin_input: &str) -> Output {
+        let start = Instant::now();
+        let cli_path = ensure_binaries_built();
+        let mut child = Command::new(&cli_path)
+            .arg("--config-path")
+            .arg(&self.config_path)
+            .args(args)
+            .current_dir(self.project_dir.path())
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .expect("Failed to spawn spacetime command");
+
+        {
+            use std::io::Write;
+            let stdin = child.stdin.as_mut().expect("missing child stdin");
+            stdin
+                .write_all(stdin_input.as_bytes())
+                .expect("Failed to write spacetime stdin");
+        }
+
+        let output = child.wait_with_output().expect("Failed to wait for spacetime command");
+
+        let cmd_name = args.first().unwrap_or(&"unknown");
+        eprintln!("[TIMING] spacetime {} (stdin): {:?}", cmd_name, start.elapsed());
+        output
+    }
+
     /// Runs a spacetime CLI command and returns stdout as a string.
     ///
     /// Panics if the command fails.
@@ -624,6 +658,23 @@ impl Smoketest {
         Ok(String::from_utf8_lossy(&output.stdout).to_string())
     }
 
+    /// Runs a spacetime CLI command with stdin and returns stdout as a string.
+    ///
+    /// Panics if the command fails.
+    /// Callers should pass `--server` explicitly when the command needs it.
+    pub fn spacetime_with_stdin(&self, args: &[&str], stdin_input: &str) -> Result<String> {
+        let output = self.spacetime_cmd_with_stdin(args, stdin_input);
+        if !output.status.success() {
+            bail!(
+                "spacetime {:?} failed:\nstdout: {}\nstderr: {}",
+                args,
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        Ok(String::from_utf8_lossy(&output.stdout).to_string())
+    }
+
     /// Writes new module code to the project.
     ///
     /// This switches from precompiled mode to runtime compilation mode.
@@ -692,6 +743,20 @@ log = "0.4"
         self.precompiled_wasm_path = Some(path);
     }
 
+    /// Switches to using an explicit precompiled WASM path.
+    ///
+    /// After calling this, subsequent `publish_module*` calls will use this
+    /// WASM file instead of building from source.
+    pub fn use_precompiled_wasm_path(&mut self, path: impl AsRef<Path>) -> Result<()> {
+        let path = path.as_ref();
+        if !path.exists() {
+            bail!("Pre-compiled wasm not found at {}", path.display());
+        }
+        eprintln!("[PRECOMPILED] Switching to explicit wasm path: {}", path.display());
+        self.precompiled_wasm_path = Some(path.to_path_buf());
+        Ok(())
+    }
+
     /// Runs `spacetime build` and returns the raw output.
     ///
     /// Use this when you need to check for build failures (e.g., wasm_bindgen detection).
@@ -738,16 +803,29 @@ log = "0.4"
 
     /// Publishes the module with name, clear, and break_clients options.
     pub fn publish_module_with_options(&mut self, name: &str, clear: bool, break_clients: bool) -> Result<String> {
-        self.publish_module_internal(Some(name), clear, break_clients)
+        self.publish_module_internal(Some(name), clear, break_clients, None)
+    }
+
+    /// Publishes the module and allows supplying stdin input to the CLI.
+    ///
+    /// Useful for interactive publish prompts which require typed acknowledgements.
+    pub fn publish_module_with_stdin(&mut self, name: &str, stdin_input: &str) -> Result<String> {
+        self.publish_module_internal(Some(name), false, false, Some(stdin_input))
     }
 
     /// Internal helper for publishing with options.
     fn publish_module_opts(&mut self, name: Option<&str>, clear: bool) -> Result<String> {
-        self.publish_module_internal(name, clear, false)
+        self.publish_module_internal(name, clear, false, None)
     }
 
     /// Internal helper for publishing with all options.
-    fn publish_module_internal(&mut self, name: Option<&str>, clear: bool, break_clients: bool) -> Result<String> {
+    fn publish_module_internal(
+        &mut self,
+        name: Option<&str>,
+        clear: bool,
+        break_clients: bool,
+        stdin_input: Option<&str>,
+    ) -> Result<String> {
         let start = Instant::now();
 
         // Determine the WASM path - either precompiled or build it
@@ -811,7 +889,10 @@ log = "0.4"
             args.push(&name_owned);
         }
 
-        let output = self.spacetime(&args)?;
+        let output = match stdin_input {
+            Some(stdin_input) => self.spacetime_with_stdin(&args, stdin_input)?,
+            None => self.spacetime(&args)?,
+        };
         eprintln!(
             "[TIMING] spacetime publish (after build): {:?}",
             publish_start.elapsed()

crates/smoketests/src/lib.rs

@@ -0,0 +1,42 @@
+use std::path::PathBuf;
+
+use spacetimedb_smoketests::{random_string, workspace_root, Smoketest};
+
+const MODULE_CODE: &str = r#"
+use spacetimedb::{reducer, ReducerContext};
+
+#[reducer]
+pub fn noop(_ctx: &ReducerContext) {}
+"#;
+
+fn old_fixture_wasm() -> PathBuf {
+    workspace_root()
+        .join("crates")
+        .join("smoketests")
+        .join("fixtures")
+        .join("upgrade_old_module_v1.wasm")
+}
+
+#[test]
+fn upgrade_prompt_on_publish() {
+    let mut test = Smoketest::builder().autopublish(false).build();
+
+    let old_wasm = old_fixture_wasm();
+    assert!(old_wasm.exists(), "expected old fixture wasm at {}", old_wasm.display());
+
+    let db_name = format!("upgrade-smoke-{}", random_string());
+
+    test.use_precompiled_wasm_path(&old_wasm).unwrap();
+    let initial_identity = test.publish_module_named(&db_name, false).unwrap();
+    assert_eq!(test.database_identity.as_deref(), Some(initial_identity.as_str()));
+
+    // Switch back to source-built module, which uses current bindings.
+    test.write_module_code(MODULE_CODE).unwrap();
+
+    let deny_err = test.publish_module_named(&db_name, false).unwrap_err().to_string();
+    assert!(deny_err.contains("major version upgrade from 1.0 to 2.0"));
+    assert!(deny_err.contains("Please type 'upgrade' to accept this change:"));
+
+    let accepted_identity = test.publish_module_with_stdin(&db_name, "upgrade\n").unwrap();
+    assert_eq!(accepted_identity, initial_identity);
+}

crates/smoketests/tests/publish_upgrade_prompt.rs

@@ -95,6 +95,7 @@ See [`spacetime publish`](/databases/building-publishing) for details on the pub
 
 When you republish to an existing database, SpacetimeDB attempts to automatically migrate the schema. For details on what changes are supported and migration strategies:
 
+- [1.x to 2.0 Upgrade Notes](/upgrade) - Required reading before major-version upgrades.
 - [Automatic Migrations](/databases/automatic-migrations) - Learn which schema changes are safe, breaking, or forbidden.
 - [Incremental Migrations](/databases/incremental-migrations) - Advanced pattern for complex schema changes.