Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

fix(modules): a contended module import is not "nothing to import"

M3gA-Minde7c36ea53dd8
diff --git a/crates/openhuman-core/src/mcp/module_client.rs b/crates/openhuman-core/src/mcp/module_client.rs
index 43bd122440..71dab42dee 100644
--- a/crates/openhuman-core/src/mcp/module_client.rs
+++ b/crates/openhuman-core/src/mcp/module_client.rs
@@ -375,12 +375,18 @@ impl McpConfiguredClient {
// module's idempotent receipt after a cancelled caller.
// Servers and audit rows from before the storage contract
// move into the module's storage before it reads them.
- // Best effort: a failure is retried at the next open.
- let _ = crate::modules::import_legacy_mcp(
- &crate::core::runtime::DispatchCtx::ambient(),
- std::path::Path::new(&self.data_dir),
- )
- .await;
+ // Best effort: a failure is retried at the next open. While
+ // another process holds the import, opening would serve
+ // none of the legacy servers, so wait for the next call.
+ if let Err(crate::modules::LegacyImportError::ClaimHeld) =
+ crate::modules::import_legacy_mcp(
+ &crate::core::runtime::DispatchCtx::ambient(),
+ std::path::Path::new(&self.data_dir),
+ )
+ .await
+ {
+ return Err(ModuleCallError::Unavailable);
+ }
let reply = self.port.open_configured(&self.data_dir, &config).await;
state.open_replied(reply.clone().map_err(|_| ()));
reply?;
diff --git a/crates/openhuman-core/src/modules/mod.rs b/crates/openhuman-core/src/modules/mod.rs
index d783d74937..dfd4987eac 100644
--- a/crates/openhuman-core/src/modules/mod.rs
+++ b/crates/openhuman-core/src/modules/mod.rs
@@ -169,13 +169,23 @@ pub fn client(config: crate::config::Config) -> tinybus::module::ModuleClient {
pub use types::{LoadPolicy, ModuleRecord, ModuleSource, ModuleState, ModuleStatus, PlatformAsset};
+/// Why a legacy import did not finish on this call.
+#[derive(Debug)]
+pub enum LegacyImportError {
+ /// Another process holds the import claim, so nothing was imported yet.
+ ClaimHeld,
+ /// The import failed; it is retried at the next call.
+ Failed(String),
+}
+
/// Imports tinymcp's legacy SQLite files under `data_dir` into the module's
-/// storage, once per directory. Never fails the caller: an error is logged and
-/// the import is retried at the next open.
+/// storage, once per directory. A failure is logged and the import is retried
+/// at the next open; [`LegacyImportError::ClaimHeld`] means the caller should
+/// not open yet.
pub async fn import_legacy_mcp(
ctx: &crate::core::runtime::DispatchCtx,
data_dir: &std::path::Path,
-) -> Result<(), String> {
+) -> Result<(), LegacyImportError> {
#[cfg(all(feature = "modules", feature = "legacy-import"))]
{
match storage_import_tinymcp::import_legacy(ctx, data_dir).await {
@@ -188,9 +198,15 @@ pub async fn import_legacy_mcp(
.await;
Ok(())
}
+ Err(error) if error.is::<storage_import_support::ImportClaimHeld>() => {
+ log::debug!("[mcp] legacy storage import is held by another process");
+ Err(LegacyImportError::ClaimHeld)
+ }
Err(error) => {
log::warn!("[mcp] legacy storage import failed, will retry: {error:#}");
- Err(format!("legacy TinyMCP storage import failed: {error:#}"))
+ Err(LegacyImportError::Failed(format!(
+ "legacy TinyMCP storage import failed: {error:#}"
+ )))
}
}
}
@@ -199,7 +215,7 @@ pub async fn import_legacy_mcp(
let _ = (ctx, data_dir);
let error = "legacy storage import is unavailable: enable the `legacy-import` feature";
log::error!("[mcp] {error}");
- Err(error.to_owned())
+ Err(LegacyImportError::Failed(error.to_owned()))
}
#[cfg(not(feature = "modules"))]
{
diff --git a/crates/openhuman-core/src/modules/storage_import_support.rs b/crates/openhuman-core/src/modules/storage_import_support.rs
index c348305b4e..36938c4756 100644
--- a/crates/openhuman-core/src/modules/storage_import_support.rs
+++ b/crates/openhuman-core/src/modules/storage_import_support.rs
@@ -129,10 +129,12 @@ pub(super) fn module_scope(
/// payload writes and the completion marker. A lost claim therefore prevents
/// late payload or completion writes.
///
-/// Returns `Ok(None)` at once when another holder's claim is live, so an
+/// `Ok(None)` means no storage backend is installed. When another holder's
+/// claim is live this returns [`ImportClaimHeld`] at once instead of waiting, so an
/// import on the compaction path never blocks a runtime worker (or the
-/// once-per-process import lock) for the claim TTL; it is retried at the next
-/// call.
+/// once-per-process import lock) for the claim TTL. The error keeps the import
+/// unsettled and makes callers that gate on it (the x402 ledger) refuse for
+/// this call; it is retried at the next one.
pub(super) fn with_module_claim<T>(
ctx: &crate::core::runtime::DispatchCtx,
module_id: &str,
@@ -178,9 +180,24 @@ where
body(scoped)
},
)?;
- Ok(claimed)
+ claimed
+ .map(Some)
+ .ok_or_else(|| anyhow::Error::new(ImportClaimHeld))
}
+/// Another holder's live claim is importing this source. The import has not
+/// happened, so it must be retried, never read as "nothing to import".
+#[derive(Debug)]
+pub(crate) struct ImportClaimHeld;
+
+impl std::fmt::Display for ImportClaimHeld {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str("another process holds this legacy import claim; retrying at the next call")
+ }
+}
+
+impl std::error::Error for ImportClaimHeld {}
+
/// A stable marker id for one source path: `<prefix>@<16 hex of sha256(path)>`.
pub(super) fn marker_id(prefix: &str, source: &Path) -> String {
let digest = sha2::Sha256::digest(source.as_os_str().as_encoded_bytes());
diff --git a/crates/openhuman-core/src/modules/storage_import_tinymcp_tests.rs b/crates/openhuman-core/src/modules/storage_import_tinymcp_tests.rs
index ae9aadb16f..36b78a9ab0 100644
--- a/crates/openhuman-core/src/modules/storage_import_tinymcp_tests.rs
+++ b/crates/openhuman-core/src/modules/storage_import_tinymcp_tests.rs
@@ -505,3 +505,49 @@ async fn a_captured_import_claim_cannot_write_after_profile_lease_takeover() {
.unwrap();
assert_eq!(attempt, Some(()));
}
+
+/// Another process holding the import claim is reported as `ClaimHeld`, so the
+/// lifecycle does not open (and serve no legacy servers) on this call.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn a_live_foreign_claim_is_reported_as_claim_held() {
+ use crate::storage::import_state;
+ use std::sync::mpsc;
+
+ let backend = crate::storage::test_support::memory_backend();
+ let _installed =
+ crate::storage::test_support::install_for_test("memory:mcp-claim", Arc::clone(&backend));
+ let ctx = DispatchCtx::host_default();
+ let data_dir = tempfile::tempdir().unwrap();
+ let clients = data_dir.path().join(CLIENTS_DB);
+ std::fs::create_dir_all(clients.parent().unwrap()).unwrap();
+ std::fs::write(&clients, b"").unwrap();
+ let scope = super::super::storage_host::current_module_scope(&ctx, MODULE_ID).unwrap();
+ let repo = crate::storage::documents::Repo::on(
+ &backend,
+ &scope,
+ "storage_import",
+ import_state::collection_specs,
+ )
+ .unwrap();
+ let step = import_state::step_id(MARKER_COLLECTION, &marker_id(data_dir.path()));
+ let (held_tx, held_rx) = mpsc::channel::<()>();
+ let (release_tx, release_rx) = mpsc::channel::<()>();
+ let holder = std::thread::spawn(move || {
+ import_state::with_claim(&repo, import_state::HOST_OWNER, &step, |_| {
+ held_tx.send(()).unwrap();
+ release_rx.recv().unwrap();
+ Ok(())
+ })
+ .unwrap()
+ });
+ held_rx.recv().unwrap();
+
+ let imported = crate::modules::import_legacy_mcp(&ctx, data_dir.path()).await;
+ release_tx.send(()).unwrap();
+ holder.join().unwrap();
+
+ assert!(
+ matches!(imported, Err(crate::modules::LegacyImportError::ClaimHeld)),
+ "{imported:?}"
+ );
+}
diff --git a/crates/openhuman-core/src/modules/storage_import_tinywallet_tests.rs b/crates/openhuman-core/src/modules/storage_import_tinywallet_tests.rs
index 8e3782523b..18dadd7432 100644
--- a/crates/openhuman-core/src/modules/storage_import_tinywallet_tests.rs
+++ b/crates/openhuman-core/src/modules/storage_import_tinywallet_tests.rs
@@ -168,3 +168,55 @@ async fn an_unreadable_ledger_is_retried_instead_of_marked_done() {
}
);
}
+
+/// Another process holding the import claim is not "no backend": the import
+/// stays unsettled and the ledger gate refuses, instead of x402 opening an
+/// empty ledger with a fresh allowance.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn a_live_foreign_claim_keeps_the_ledger_closed() {
+ use crate::storage::import_state;
+ use std::sync::{mpsc, Arc};
+
+ let backend = crate::storage::test_support::memory_backend();
+ let _installed =
+ crate::storage::test_support::install_for_test("memory:x402-claim", Arc::clone(&backend));
+ let ctx = DispatchCtx::host_default();
+ let legacy = legacy_workspace();
+ let scope = super::super::storage_host::current_module_scope(&ctx, MODULE_ID).unwrap();
+ let repo = crate::storage::documents::Repo::on(
+ &backend,
+ &scope,
+ "storage_import",
+ import_state::collection_specs,
+ )
+ .unwrap();
+ let step = import_state::step_id(
+ MARKER_COLLECTION,
+ &support::marker_id("x402", legacy.path()),
+ );
+ let (held_tx, held_rx) = mpsc::channel::<()>();
+ let (release_tx, release_rx) = mpsc::channel::<()>();
+ let holder = std::thread::spawn(move || {
+ import_state::with_claim(&repo, import_state::HOST_OWNER, &step, |_| {
+ held_tx.send(()).unwrap();
+ release_rx.recv().unwrap();
+ Ok(())
+ })
+ .unwrap()
+ });
+ held_rx.recv().unwrap();
+
+ let outcome = import_legacy(&ctx, legacy.path()).await;
+ let ledger_may_open = crate::modules::import_legacy_x402(&ctx, legacy.path()).await;
+ release_tx.send(()).unwrap();
+ holder.join().unwrap();
+
+ assert!(
+ outcome.is_err(),
+ "a contended import must not settle as {outcome:?}"
+ );
+ assert!(
+ !ledger_may_open,
+ "the ledger must not open while another process holds the import"
+ );
+}