You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by wy...@apache.org on 2026/09/16 01:18:43 UTC
(maka) 24/29: feat(host): bridge native connections and repair explicit WSL remounts
This is an automated email from the ASF dual-hosted git repository.
M4n5ter pushed a commit to branch feat/runtime-host-rust
in repository https://gitbox.apache.org/repos/asf/maka.git
commit a41cb84e60c1a6e16f21ca2c3fa1f2229c9f62e4
Author: Wang <m4...@gmail.com>
AuthorDate: Tue Sep 15 23:29:39 2026 +0800
feat(host): bridge native connections and repair explicit WSL remounts
Generated-by: OpenAI Codex
---
crates/cli/Cargo.toml | 2 +-
crates/cli/src/args.rs | 3 +
crates/cli/src/deployment.rs | 2 +
crates/cli/src/deployment/activation.rs | 61 ++++++---
crates/cli/src/deployment/connect.rs | 192 +++++++++++++++++++++++++++++
crates/cli/src/host_client.rs | 50 +++++---
crates/cli/src/main.rs | 1 +
crates/cli/src/stdio.rs | 69 +++++++++++
crates/cli/tests/integration/deployment.rs | 13 +-
crates/event-log/src/root.rs | 92 +++++++++++++-
crates/event-log/tests/root_authority.rs | 87 +++++++------
crates/event-log/tests/root_lease.rs | 65 ++++++++++
docs/rust-runtime.md | 7 ++
docs/rust-runtime.zh-CN.md | 7 +-
tests/fixtures/client-bridge-entry.mjs | 136 ++++++++++++++++++++
tests/fixtures/client.mjs | 1 +
16 files changed, 707 insertions(+), 81 deletions(-)
diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
index 1899c46650..0ca19955ba 100644
--- a/crates/cli/Cargo.toml
+++ b/crates/cli/Cargo.toml
@@ -50,7 +50,7 @@ serde_json.workspace = true
sha2.workspace = true
sqlx.workspace = true
tokio = { workspace = true, features = ["process"] }
-tokio-util.workspace = true
+tokio-util = { workspace = true, features = ["io-util"] }
uuid.workspace = true
tempfile.workspace = true
diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs
index c3a46e826d..7b74506679 100644
--- a/crates/cli/src/args.rs
+++ b/crates/cli/src/args.rs
@@ -53,6 +53,8 @@ enum HostCommand {
Install(crate::deployment::Install),
/// Activate an installed Host and report its verified loopback endpoint.
Activate(crate::deployment::Activate),
+ /// Connect an installed Host to stdin/stdout using the client wire protocol.
+ Connect(crate::deployment::Connect),
/// Update a deployment to this executable at a safe boundary.
Update(crate::deployment::Update),
/// Finish an interrupted deployment update without choosing another target.
@@ -117,6 +119,7 @@ impl Cli {
Command::Host(HostCommand::Candidate(args)) => args.run().await,
Command::Host(HostCommand::Install(args)) => args.run().await,
Command::Host(HostCommand::Activate(args)) => args.run().await,
+ Command::Host(HostCommand::Connect(args)) => args.run().await,
Command::Host(HostCommand::Update(args)) => args.run(false).await,
Command::Host(HostCommand::Reconcile(args)) => args.run(true).await,
Command::Host(HostCommand::Stop(args)) => {
diff --git a/crates/cli/src/deployment.rs b/crates/cli/src/deployment.rs
index 7e4a9146e2..cf118f5570 100644
--- a/crates/cli/src/deployment.rs
+++ b/crates/cli/src/deployment.rs
@@ -18,6 +18,7 @@
*/
mod activation;
+mod connect;
mod control;
mod entry;
mod logs;
@@ -28,6 +29,7 @@ mod store;
mod update;
mod updates;
pub(super) use activation::Activate;
+pub(super) use connect::Connect;
pub(super) use control::{Control, ControlAction};
pub(super) use entry::ServiceRun;
pub(super) use logs::Logs;
diff --git a/crates/cli/src/deployment/activation.rs b/crates/cli/src/deployment/activation.rs
index 9933162d32..244f5e0971 100644
--- a/crates/cli/src/deployment/activation.rs
+++ b/crates/cli/src/deployment/activation.rs
@@ -40,6 +40,9 @@ pub(crate) struct Activate {
root_id: RootId,
#[arg(long)]
framed: bool,
+ /// Confirm the same Linux filesystem was remounted, preserving root identity.
+ #[arg(long)]
+ repair_root_after_remount: bool,
}
#[derive(Serialize)]
@@ -102,22 +105,7 @@ impl Activate {
}
async fn activate(&self) -> Result<(), HostError> {
- let directory = directory(&self.root_id.0)?;
- // Activation never creates a deployment database.
- if !directory.is_dir() {
- return Err("Host deployment is not installed".into());
- }
- let lease = Arc::new(FileLease::acquire(&directory.join("executor.lock"))?);
- let store::Installation::Installed(deployment) = store::read(&directory).await? else {
- return Err("Host deployment is absent or incomplete".into());
- };
- let root = root::resolve(&deployment.root_path)?;
- if root.root_id() != self.root_id.0 {
- return Err("deployment root identity changed".into());
- }
- deployment.validate(&root, &directory)?;
- deployment.require_active()?;
- lease.validate()?;
+ let (deployment, lease) = prepare(&self.root_id, self.repair_root_after_remount).await?;
let (client, live) = connect_or_launch(&deployment, lease.clone()).await?;
lease.validate()?;
emit(
@@ -143,6 +131,47 @@ impl Activate {
}
}
+pub(super) async fn prepare(
+ root_id: &RootId,
+ repair: bool,
+) -> Result<(Deployment, Arc<FileLease>), HostError> {
+ let directory = directory(&root_id.0)?;
+ // Activation never creates a deployment database.
+ if !directory.is_dir() {
+ return Err("Host deployment is not installed".into());
+ }
+ let lease = Arc::new(FileLease::acquire(&directory.join("executor.lock"))?);
+ let store::Installation::Installed(deployment) = store::read(&directory).await? else {
+ return Err("Host deployment is absent or incomplete".into());
+ };
+ deployment.validate_record(&directory)?;
+ deployment.require_active()?;
+ if deployment.root_id != root_id.0 {
+ return Err("deployment root identity changed".into());
+ }
+ if repair {
+ let path = deployment.root_path.clone();
+ let expected = root_id.0.clone();
+ let lease = lease.clone();
+ tokio::task::spawn_blocking(move || {
+ lease.validate()?;
+ if path.canonicalize()? != path {
+ return Err(std::io::Error::other("deployment root path was rebound"));
+ }
+ root::repair_after_remount(&path, &expected, &RootNamespaces::for_current_account()?)?;
+ lease.validate()
+ })
+ .await??;
+ }
+ let root = root::resolve(&deployment.root_path)?;
+ if root.root_id() != root_id.0 {
+ return Err("deployment root identity changed".into());
+ }
+ deployment.validate(&root, &directory)?;
+ lease.validate()?;
+ Ok((deployment, lease))
+}
+
pub(super) async fn connect_or_launch(
deployment: &Deployment,
lease: Arc<FileLease>,
diff --git a/crates/cli/src/deployment/connect.rs b/crates/cli/src/deployment/connect.rs
new file mode 100644
index 0000000000..1134abc951
--- /dev/null
+++ b/crates/cli/src/deployment/connect.rs
@@ -0,0 +1,192 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use super::{RootId, activation};
+use clap::Args;
+use maka_protocol::{
+ MAX_MESSAGE_BYTES,
+ handshake::{HostHandshake, decode_hello, decode_host_handshake},
+};
+use maka_runtime_host::server::HostError;
+use std::time::Duration;
+use tokio::io::{
+ AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, BufReader,
+};
+use tokio_util::sync::CancellationToken;
+
+#[derive(Args)]
+pub(crate) struct Connect {
+ #[arg(long)]
+ root_id: RootId,
+ #[arg(long = "framed", required = true)]
+ _framed: bool,
+ /// Confirm the same Linux filesystem was remounted, preserving root identity.
+ #[arg(long)]
+ repair_root_after_remount: bool,
+}
+
+impl Connect {
+ pub async fn run(self) -> Result<(), HostError> {
+ let crate::stdio::Stdio {
+ input,
+ mut output,
+ mut output_done,
+ } = crate::stdio::Stdio::open()?;
+ let cancel = CancellationToken::new();
+ let _signals = crate::signals::watch(cancel.clone())?;
+ let result = tokio::select! {
+ result = self.bridge(BufReader::new(input), &mut output) => result,
+ _ = cancel.cancelled() => Ok(()),
+ result = &mut output_done => {
+ result??;
+ return Err("Host bridge output closed".into());
+ }
+ };
+ // Duplex shutdown alone only proves that bytes were queued. Wait for
+ // the stdout worker's final flush, bounded even if the consumer stalls.
+ drop(output);
+ let flushed = tokio::time::timeout(Duration::from_secs(5), output_done)
+ .await
+ .map_err(HostError::from)
+ .and_then(|result| result.map_err(HostError::from))
+ .and_then(|result| result.map_err(HostError::from));
+ result.and(flushed)
+ }
+
+ async fn bridge(
+ &self,
+ mut input: impl AsyncBufRead + Unpin,
+ output: &mut (impl AsyncWrite + Unpin),
+ ) -> Result<(), HostError> {
+ // A silent client must not reserve the deployment executor or start a Host.
+ let hello = tokio::time::timeout(Duration::from_secs(5), frame(&mut input)).await??;
+ decode_hello(&maka_protocol::decode_message(&hello)?)?;
+ let (deployment, lease) =
+ activation::prepare(&self.root_id, self.repair_root_after_remount).await?;
+ let (probe, live) = activation::connect_or_launch(&deployment, lease.clone()).await?;
+ let mut stream = probe.open_bridge().await?;
+ let mut stream = BufReader::new(&mut stream);
+ let accepted = tokio::time::timeout(Duration::from_secs(5), async {
+ stream.write_all(&hello).await?;
+ stream.write_all(b"\n").await?;
+ stream.flush().await?;
+ let reply = frame(&mut stream).await?;
+ let handshake = decode_host_handshake(&maka_protocol::decode_message(&reply)?)?;
+ if let HostHandshake::Accepted {
+ root_id,
+ host_epoch,
+ ..
+ } = &handshake
+ && (root_id != &deployment.root_id || host_epoch != &live.epoch)
+ {
+ return Err::<_, HostError>(
+ "Host changed between activation and bridge handshake".into(),
+ );
+ }
+ Ok((reply, matches!(handshake, HostHandshake::Accepted { .. })))
+ })
+ .await??;
+ lease.validate()?;
+ drop(probe);
+ drop(lease);
+ output.write_all(&accepted.0).await?;
+ output.write_all(b"\n").await?;
+ output.flush().await?;
+ if !accepted.1 {
+ return Ok(());
+ }
+ // Keep both BufReaders: either may already own pipelined bytes beyond hello.
+ relay(&mut input, output, stream).await?;
+ Ok(())
+ }
+}
+
+async fn relay(
+ input: &mut (impl AsyncRead + Unpin),
+ output: &mut (impl AsyncWrite + Unpin),
+ stream: impl AsyncRead + AsyncWrite + Unpin,
+) -> std::io::Result<()> {
+ let (mut read, mut write) = tokio::io::split(stream);
+ let downstream = tokio::io::copy(&mut read, output);
+ tokio::pin!(downstream);
+ tokio::select! {
+ result = tokio::io::copy(input, &mut write) => {
+ result?;
+ #[cfg(unix)]
+ {
+ // Preserve this same copy future: it may own a partially
+ // written response buffer while stdout applies backpressure.
+ write.shutdown().await?;
+ downstream.await?;
+ }
+ // Windows named pipes cannot half-close. EOF disconnects the
+ // client without promising queued writes or final responses;
+ // it never retires the independently owned Host.
+ },
+ result = &mut downstream => { result?; },
+ }
+ Ok(())
+}
+
+async fn frame(reader: &mut (impl AsyncBufRead + Unpin)) -> Result<Vec<u8>, HostError> {
+ let mut bytes = Vec::new();
+ reader
+ .take(MAX_MESSAGE_BYTES as u64 + 2)
+ .read_until(b'\n', &mut bytes)
+ .await?;
+ if bytes.last() != Some(&b'\n') || bytes.len() > MAX_MESSAGE_BYTES + 1 {
+ return Err("Host bridge greeting is incomplete or too large".into());
+ }
+ bytes.pop();
+ Ok(bytes)
+}
+
+#[cfg(all(test, unix))]
+mod tests {
+ use super::*;
+
+ #[tokio::test]
+ async fn input_eof_preserves_a_response_already_blocked_on_output() {
+ tokio::time::timeout(Duration::from_secs(5), async {
+ let (mut sender, mut input) = tokio::io::duplex(16);
+ let (mut output, mut receiver) = tokio::io::duplex(1);
+ let (stream, server) = tokio::io::duplex(16 * 1024);
+ let bridge = tokio::spawn(async move { relay(&mut input, &mut output, stream).await });
+ let (mut server_read, mut server_write) = tokio::io::split(server);
+ let payload: Vec<_> = (0..128 * 1024).map(|index| (index % 251) as u8).collect();
+ let expected = payload.clone();
+ let server = tokio::spawn(async move {
+ server_write.write_all(&payload).await.unwrap();
+ server_write.shutdown().await.unwrap();
+ });
+ let first = receiver.read_u8().await.unwrap();
+ sender.shutdown().await.unwrap();
+ // This EOF proves the bridge handled input EOF while downstream
+ // was blocked, before allowing the output consumer to drain.
+ assert_eq!(server_read.read(&mut [0]).await.unwrap(), 0);
+ let mut actual = vec![first];
+ receiver.read_to_end(&mut actual).await.unwrap();
+ assert_eq!(actual, expected);
+ bridge.await.unwrap().unwrap();
+ server.await.unwrap();
+ })
+ .await
+ .unwrap();
+ }
+}
diff --git a/crates/cli/src/host_client.rs b/crates/cli/src/host_client.rs
index 7a9b6221ad..2916dbd4cd 100644
--- a/crates/cli/src/host_client.rs
+++ b/crates/cli/src/host_client.rs
@@ -37,9 +37,9 @@ use tokio::io::{ReadHalf, WriteHalf};
use tokio_util::sync::CancellationToken;
#[cfg(unix)]
-type Stream = tokio::net::UnixStream;
+pub(super) type Stream = tokio::net::UnixStream;
#[cfg(windows)]
-type Stream = tokio::net::windows::named_pipe::NamedPipeClient;
+pub(super) type Stream = tokio::net::windows::named_pipe::NamedPipeClient;
/// Discovery is only a hint. The live handshake must confirm both root and epoch.
#[derive(Deserialize)]
@@ -72,22 +72,7 @@ impl HostClient {
let root = root.to_owned();
tokio::time::timeout(Duration::from_secs(5), async move {
let discovery = tokio::task::spawn_blocking(move || read_discovery(&root)).await??;
- #[cfg(unix)]
- let stream = Stream::connect(&discovery.endpoint).await?;
- #[cfg(windows)]
- let stream = {
- use tokio::net::windows::named_pipe::ClientOptions;
- loop {
- match ClientOptions::new().open(&discovery.endpoint) {
- Ok(stream) => break stream,
- // An existing pipe instance may be between accepts.
- Err(error) if error.raw_os_error() == Some(231) => {
- tokio::time::sleep(Duration::from_millis(10)).await
- }
- Err(error) => return Err(error.into()),
- }
- }
- };
+ let stream = open_stream(&discovery.endpoint).await?;
let (mut reader, mut writer) =
maka_transport::ndjson::split(stream, CancellationToken::new());
writer
@@ -128,6 +113,16 @@ impl HostClient {
.await?
}
+ /// A fresh connection to this verified epoch, not a second discovery lookup.
+ /// The bridge must still check its own handshake before forwarding requests.
+ pub async fn open_bridge(&self) -> Result<Stream, HostError> {
+ tokio::time::timeout(
+ Duration::from_secs(5),
+ open_stream(&self.discovery.endpoint),
+ )
+ .await?
+ }
+
pub async fn status(&mut self) -> Result<Value, HostError> {
let result = self.request(Operation::HostStatus, json!({})).await?;
if result["hostEpoch"] != self.discovery.host_epoch {
@@ -235,6 +230,25 @@ impl HostClient {
}
}
+async fn open_stream(endpoint: &Path) -> Result<Stream, HostError> {
+ #[cfg(unix)]
+ return Ok(Stream::connect(endpoint).await?);
+ #[cfg(windows)]
+ {
+ use tokio::net::windows::named_pipe::ClientOptions;
+ loop {
+ match ClientOptions::new().open(endpoint) {
+ Ok(stream) => return Ok(stream),
+ // An existing pipe instance may be between accepts.
+ Err(error) if error.raw_os_error() == Some(231) => {
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ Err(error) => return Err(error.into()),
+ }
+ }
+ }
+}
+
fn read_discovery(path: &Path) -> Result<Discovery, HostError> {
let root = root::resolve(path)?;
let path = RootNamespaces::for_current_account()?
diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
index d50ec1fc8b..54565ddcad 100644
--- a/crates/cli/src/main.rs
+++ b/crates/cli/src/main.rs
@@ -26,6 +26,7 @@ mod endpoint;
mod host_client;
mod serve;
mod signals;
+mod stdio;
#[cfg(windows)]
mod windows;
diff --git a/crates/cli/src/stdio.rs b/crates/cli/src/stdio.rs
new file mode 100644
index 0000000000..76f6cd587f
--- /dev/null
+++ b/crates/cli/src/stdio.rs
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use std::io::{self, Read, Write};
+use tokio::{io::DuplexStream, sync::oneshot};
+use tokio_util::io::SyncIoBridge;
+
+/// Process-lifetime stdio workers own no Host, deployment or effect leases.
+/// An open input pipe or blocked output must not hold Tokio shutdown hostage.
+pub(super) struct Stdio {
+ pub input: DuplexStream,
+ pub output: DuplexStream,
+ pub output_done: oneshot::Receiver<io::Result<()>>,
+}
+
+impl Stdio {
+ pub fn open() -> io::Result<Self> {
+ let (input, writer) = tokio::io::duplex(32 * 1024);
+ let (output, reader) = tokio::io::duplex(32 * 1024);
+ let mut writer = SyncIoBridge::new(writer);
+ let mut reader = SyncIoBridge::new(reader);
+ let (done, output_done) = oneshot::channel();
+ std::thread::Builder::new()
+ .name("bridge-stdin".into())
+ .spawn(move || {
+ // EOF drops the duplex writer. The async caller also checks for
+ // a partial greeting before allowing any Host activation.
+ let _ = io::copy(&mut io::stdin().lock(), &mut writer);
+ })?;
+ std::thread::Builder::new()
+ .name("bridge-stdout".into())
+ .spawn(move || {
+ let result = (|| {
+ let mut stdout = io::stdout().lock();
+ let mut bytes = [0; 16 * 1024];
+ loop {
+ let count = reader.read(&mut bytes)?;
+ if count == 0 {
+ return stdout.flush();
+ }
+ stdout.write_all(&bytes[..count])?;
+ stdout.flush()?;
+ }
+ })();
+ let _ = done.send(result);
+ })?;
+ Ok(Self {
+ input,
+ output,
+ output_done,
+ })
+ }
+}
diff --git a/crates/cli/tests/integration/deployment.rs b/crates/cli/tests/integration/deployment.rs
index 49c2cee458..bcd8baa928 100644
--- a/crates/cli/tests/integration/deployment.rs
+++ b/crates/cli/tests/integration/deployment.rs
@@ -242,9 +242,16 @@ fn managed_installation_pins_code_before_migration_and_preserves_live_authority(
assert_eq!(observed["host"]["identity"]["pid"], registration["pid"]);
assert_eq!(observed["host"]["activity"]["state"], "ready");
assert!(RootOwner::open(&fixture.root, &namespaces).is_err());
- let retired = Command::new(env!("CARGO_BIN_EXE_maka"))
- .args(["host", "retire", "--root"])
- .arg(&fixture.root)
+ let retired = Command::new("node")
+ .arg(Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/fixtures/client.mjs"))
+ .args([
+ "--bridge",
+ env!("CARGO_BIN_EXE_maka"),
+ "--root-id",
+ &fixture.root_id,
+ "--host-epoch",
+ registration["hostEpoch"].as_str().unwrap(),
+ ])
.output()
.unwrap();
assert!(
diff --git a/crates/event-log/src/root.rs b/crates/event-log/src/root.rs
index 29d23ae572..afb5d74bc8 100644
--- a/crates/event-log/src/root.rs
+++ b/crates/event-log/src/root.rs
@@ -38,6 +38,7 @@ pub const ROOT_MARKER: &str = ".maka-storage-root.json";
pub const RUST_ROOT_MARKER: &str = ".maka-rust-runtime.json";
pub const ROOT_DATABASE: &str = "runtime-rust.sqlite";
const PROTOTYPE: &[u8] = b"{\"schemaVersion\":1,\"runtime\":\"rust-prototype\"}\n";
+const REMOUNT_STAGING: &str = ".maka-storage-root.next";
#[derive(Debug, Clone)]
pub struct RootNamespaces {
@@ -66,7 +67,7 @@ impl RootNamespaces {
}
}
-#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
struct Marker {
schema_version: u8,
@@ -75,7 +76,7 @@ struct Marker {
root_identity: Identity,
}
-#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
struct Identity {
dev: String,
ino: String,
@@ -117,6 +118,72 @@ pub fn resolve(path: &Path) -> io::Result<RootLocation> {
})
}
+/// Explicitly confirm an unchanged Linux directory after its filesystem was
+/// remounted. Equal inode numbers alone do not establish identity across volumes.
+/// A matching root is a read-only no-op, including while its Host is running.
+pub fn repair_after_remount(
+ path: &Path,
+ expected_root_id: &str,
+ namespaces: &RootNamespaces,
+) -> io::Result<()> {
+ let canonical_path = path.canonicalize()?;
+ let identity = directory_identity(&canonical_path)?;
+ check_layout(&canonical_path)?;
+ let previous = read_marker(&canonical_path)?;
+ if previous.root_id != expected_root_id
+ || directory_identity(&canonical_path)? != identity
+ || canonical_path.canonicalize()? != canonical_path
+ {
+ return Err(io::Error::other("root changed before remount confirmation"));
+ }
+ if previous.root_identity == identity {
+ return Ok(());
+ }
+ if !cfg!(target_os = "linux") || previous.root_identity.ino != identity.ino {
+ return Err(io::Error::other("root is not an unchanged Linux remount"));
+ }
+ let mut next = previous.clone();
+ next.root_identity = identity;
+ // Use the same two ownership locks as normal Host startup, not executor.lock
+ // or FileLease: Linux's TS-compatible OFD locks are distinct from flock.
+ let owner = RootOwner::acquire(canonical_path, next, namespaces)?;
+ let validate = || {
+ owner.check_directory()?;
+ owner.validate_leases()?;
+ if read_marker(&owner.canonical_path)? != previous {
+ return Err(io::Error::other(
+ "root marker changed during remount confirmation",
+ ));
+ }
+ owner.check_directory()
+ };
+ validate()?;
+ let staging = owner.canonical_path.join(REMOUNT_STAGING);
+ match staging.symlink_metadata() {
+ Ok(metadata) if metadata.is_file() => fs::remove_file(&staging)?,
+ Ok(_) => return Err(io::Error::other("remount staging is not a regular file")),
+ Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+ Err(error) => return Err(error),
+ }
+ let mut options = fs::OpenOptions::new();
+ options.write(true).create_new(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt;
+ options.mode(0o600);
+ }
+ let mut file = options.open(&staging)?;
+ file.write_all(&serde_json::to_vec(&owner.marker)?)?;
+ file.sync_all()?;
+ lock::stable(&file, &staging)?;
+ validate()?;
+ fs::rename(&staging, owner.canonical_path.join(ROOT_MARKER))?;
+ // On an uncertain rename/fsync result, stop. The next call re-reads the
+ // official marker; it never promotes or trusts an abandoned staging file.
+ File::open(&owner.canonical_path)?.sync_all()?;
+ owner.validate_current()
+}
+
fn inspect(path: &Path) -> io::Result<(PathBuf, Marker)> {
let canonical_path = path.canonicalize()?;
let identity = directory_identity(&canonical_path)?;
@@ -170,6 +237,16 @@ impl RootOwner {
/// Open only a marked Rust prototype root, rejecting legacy layouts before database access.
pub fn open(path: &Path, namespaces: &RootNamespaces) -> io::Result<Self> {
let (canonical_path, marker) = inspect(path)?;
+ let owner = Self::acquire(canonical_path, marker, namespaces)?;
+ owner.validate_current()?;
+ Ok(owner)
+ }
+
+ fn acquire(
+ canonical_path: PathBuf,
+ marker: Marker,
+ namespaces: &RootNamespaces,
+ ) -> io::Result<Self> {
lock::private_directory(&namespaces.ownership)?;
let lock_path = namespaces
.ownership
@@ -179,16 +256,14 @@ impl RootOwner {
let control_directory = namespaces.control.join(&marker.root_id);
lock::private_directory(&control_directory)?;
let compatibility_lease = lock::acquire(&control_directory.join("owner.lock"))?;
- let owner = Self {
+ Ok(Self {
canonical_path,
marker,
control_directory,
lock_path,
durable_lease,
compatibility_lease,
- };
- owner.validate_current()?;
- Ok(owner)
+ })
}
pub fn canonical_path(&self) -> &Path {
@@ -215,6 +290,10 @@ impl RootOwner {
if marker != self.marker {
return Err(io::Error::other("root marker identity changed"));
}
+ self.validate_leases()
+ }
+
+ fn validate_leases(&self) -> io::Result<()> {
lock::stable(&self.durable_lease, &self.lock_path)?;
lock::stable(
&self.compatibility_lease,
@@ -306,6 +385,7 @@ fn check_layout(path: &Path) -> io::Result<()> {
name.to_str(),
Some(
ROOT_MARKER
+ | REMOUNT_STAGING
| RUST_ROOT_MARKER
| ROOT_DATABASE
| "runtime-rust.sqlite-wal"
diff --git a/crates/event-log/tests/root_authority.rs b/crates/event-log/tests/root_authority.rs
index 2c8b448af8..5121d35320 100644
--- a/crates/event-log/tests/root_authority.rs
+++ b/crates/event-log/tests/root_authority.rs
@@ -18,7 +18,7 @@
*/
use maka_event_log::root::{ROOT_MARKER, RUST_ROOT_MARKER, RootNamespaces, RootOwner};
-use std::{fs, path::Path, process::Command};
+use std::{fs, path::Path};
fn namespaces(base: &Path) -> RootNamespaces {
RootNamespaces {
@@ -64,17 +64,67 @@ fn copied_marker_and_rebound_path_cannot_reuse_identity() {
let path = temp.path().join("root");
let owner = RootOwner::create(&path, &ns).unwrap();
let copy = temp.path().join("copy");
+ maka_event_log::root::repair_after_remount(&path, owner.root_id(), &ns).unwrap();
+ assert!(maka_event_log::root::repair_after_remount(&path, &"0".repeat(64), &ns).is_err());
fs::create_dir(©).unwrap();
for name in [ROOT_MARKER, RUST_ROOT_MARKER] {
fs::copy(path.join(name), copy.join(name)).unwrap();
}
assert!(RootOwner::open(©, &ns).is_err());
assert!(maka_event_log::root::resolve(©).is_err());
+ assert!(maka_event_log::root::repair_after_remount(©, owner.root_id(), &ns).is_err());
fs::rename(&path, temp.path().join("moved")).unwrap();
fs::rename(©, &path).unwrap();
assert!(owner.validate_current().is_err());
}
+#[test]
+#[cfg(target_os = "linux")]
+fn explicit_remount_preserves_authority_and_recovers_only_its_staging_file() {
+ use maka_event_log::root::{repair_after_remount, resolve};
+ let temp = tempfile::tempdir().unwrap();
+ let ns = namespaces(temp.path());
+ let path = temp.path().join("root");
+ let owner = RootOwner::create(&path, &ns).unwrap();
+ let id = owner.root_id().to_owned();
+ let marker = path.join(ROOT_MARKER);
+ let original: serde_json::Value = serde_json::from_slice(&fs::read(&marker).unwrap()).unwrap();
+ let mut stale = original.clone();
+ stale["rootIdentity"]["dev"] = serde_json::json!("0");
+ fs::write(&marker, serde_json::to_vec(&stale).unwrap()).unwrap();
+ assert!(resolve(&path).is_err());
+ assert!(
+ repair_after_remount(&path, &id, &ns).is_err(),
+ "repair bypassed the live owner lease"
+ );
+ assert_eq!(
+ serde_json::from_slice::<serde_json::Value>(&fs::read(&marker).unwrap()).unwrap(),
+ stale
+ );
+ drop(owner);
+ let staging = path.join(".maka-storage-root.next");
+ fs::write(&staging, b"abandoned partial write").unwrap();
+ repair_after_remount(&path, &id, &ns).unwrap();
+ assert!(!staging.exists());
+ assert_eq!(
+ serde_json::from_slice::<serde_json::Value>(&fs::read(&marker).unwrap()).unwrap(),
+ original
+ );
+ let owner = RootOwner::open(&path, &ns).unwrap();
+ fs::write(&staging, b"never promote this").unwrap();
+ repair_after_remount(&path, &id, &ns).unwrap();
+ assert!(
+ staging.exists(),
+ "no-op must not acquire leases just to clean staging"
+ );
+ owner.validate_current().unwrap();
+ drop(owner);
+ stale["rootIdentity"]["ino"] = serde_json::json!("0");
+ fs::write(&marker, serde_json::to_vec(&stale).unwrap()).unwrap();
+ assert!(repair_after_remount(&path, &id, &ns).is_err());
+ assert_eq!(fs::read(staging).unwrap(), b"never promote this");
+}
+
#[test]
#[cfg(unix)]
fn legacy_and_unsafe_markers_fail_closed() {
@@ -104,38 +154,3 @@ fn legacy_and_unsafe_markers_fail_closed() {
fs::write(path.join(ROOT_MARKER), vec![b' '; 1025]).unwrap();
assert!(owner.validate_current().is_err());
}
-
-#[test]
-fn durable_lease_blocks_other_process_even_after_cache_removal() {
- if let Some(base) = std::env::var_os("MAKA_ROOT_AUTHORITY_TEST_BASE") {
- let base = Path::new(&base);
- let error = RootOwner::open(&base.join("root"), &namespaces(base))
- .err()
- .unwrap();
- assert_eq!(error.kind(), std::io::ErrorKind::WouldBlock);
- return;
- }
- let temp = tempfile::tempdir().unwrap();
- let ns = namespaces(temp.path());
- let path = temp.path().join("root");
- let owner = RootOwner::create(&path, &ns).unwrap();
- fs::create_dir(path.join("skills")).unwrap();
- assert_eq!(
- maka_event_log::root::initialize(&path, &ns).unwrap(),
- owner.root_id()
- );
- fs::remove_dir_all(&ns.control).unwrap();
- let status = Command::new(std::env::current_exe().unwrap())
- .args([
- "--exact",
- "durable_lease_blocks_other_process_even_after_cache_removal",
- "--nocapture",
- ])
- .env("MAKA_ROOT_AUTHORITY_TEST_BASE", temp.path())
- .status()
- .unwrap();
- assert!(status.success());
- assert!(owner.validate_current().is_err());
- drop(owner);
- RootOwner::open(&path, &ns).unwrap();
-}
diff --git a/crates/event-log/tests/root_lease.rs b/crates/event-log/tests/root_lease.rs
new file mode 100644
index 0000000000..5051c77305
--- /dev/null
+++ b/crates/event-log/tests/root_lease.rs
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Keep this process-spawning check in its own binary: fork temporarily inherits
+// other test threads' OFD leases even when their files are close-on-exec.
+use maka_event_log::root::{RootNamespaces, RootOwner};
+use std::{fs, path::Path, process::Command};
+
+fn namespaces(base: &Path) -> RootNamespaces {
+ RootNamespaces {
+ ownership: base.join("owners"),
+ control: base.join("control"),
+ }
+}
+
+#[test]
+fn durable_lease_blocks_other_process_even_after_cache_removal() {
+ if let Some(base) = std::env::var_os("MAKA_ROOT_AUTHORITY_TEST_BASE") {
+ let base = Path::new(&base);
+ let error = RootOwner::open(&base.join("root"), &namespaces(base))
+ .err()
+ .unwrap();
+ assert_eq!(error.kind(), std::io::ErrorKind::WouldBlock);
+ return;
+ }
+ let temp = tempfile::tempdir().unwrap();
+ let ns = namespaces(temp.path());
+ let path = temp.path().join("root");
+ let owner = RootOwner::create(&path, &ns).unwrap();
+ fs::create_dir(path.join("skills")).unwrap();
+ assert_eq!(
+ maka_event_log::root::initialize(&path, &ns).unwrap(),
+ owner.root_id()
+ );
+ fs::remove_dir_all(&ns.control).unwrap();
+ let status = Command::new(std::env::current_exe().unwrap())
+ .args([
+ "--exact",
+ "durable_lease_blocks_other_process_even_after_cache_removal",
+ "--nocapture",
+ ])
+ .env("MAKA_ROOT_AUTHORITY_TEST_BASE", temp.path())
+ .status()
+ .unwrap();
+ assert!(status.success());
+ assert!(owner.validate_current().is_err());
+ drop(owner);
+ RootOwner::open(&path, &ns).unwrap();
+}
diff --git a/docs/rust-runtime.md b/docs/rust-runtime.md
index cbbf61e1fa..db9af85680 100644
--- a/docs/rust-runtime.md
+++ b/docs/rust-runtime.md
@@ -58,6 +58,13 @@ Windows MSVC builds use the static CRT required by the official V8 archive.
The two vendored Deno TypeScript files must match `deno_telemetry` exactly;
update them together when upgrading that dependency. They avoid a build-time V8.
+`host connect --root-id <rootId> --framed` activates that deployment and bridges the
+client protocol over stdin/stdout; diagnostics use stderr. Linux/macOS input EOF
+half-closes the connection and drains responses. Windows pipe EOF disconnects;
+clients must receive their responses before closing stdin. WSL passes
+`--repair-root-after-remount`: this explicitly confirms an unchanged Linux inode
+after remount, preserving Root ID. Do not use it to adopt copied or legacy roots.
+
`host install --root <directory>` pins the current executable and on-demand policy;
`--mode supervised` selects persistent serving. Only the returned `executable`
may start that managed root. `host activate --root-id <rootId> --framed` reuses a ready
diff --git a/docs/rust-runtime.zh-CN.md b/docs/rust-runtime.zh-CN.md
index 74b138f3ba..1e87f813a6 100644
--- a/docs/rust-runtime.zh-CN.md
+++ b/docs/rust-runtime.zh-CN.md
@@ -53,8 +53,13 @@ Windows MSVC 构建使用与官方 V8 静态库一致的静态 CRT。
两份随仓库保存的 Deno TypeScript 须与 `deno_telemetry` 完全一致,升级依赖时须同步;
构建直接转译它们,不再加载构建期 V8。
+`host connect --root-id <rootId> --framed` 激活该部署,通过 stdin/stdout 桥接客户端协议,
+诊断写入 stderr。Linux/macOS 的输入 EOF 半关闭连接并排空响应;Windows 管道 EOF 表示断连,
+客户端须先收完响应再关闭 stdin。WSL 传入 `--repair-root-after-remount`,显式确认重挂载后
+Linux inode 未变并保留 Root ID。不要用它接管复制的根或旧版数据。
+
`host install --root <目录>` 固定当前可执行文件和按需策略;`--mode supervised` 选择持续运行。
-此后只有返回的 `executable` 可以启动该托管根。`host activate --root-id <rootId> --framed`
+只有返回的 `executable` 可以启动该托管根。`host activate --root-id <rootId> --framed`
复用就绪 Host,或启动固定版本;supervised 模式会注册并启动账户级 systemd 服务、LaunchAgent
或 Windows 计划任务。Linux 要求用户服务管理器已运行且启用 linger;macOS 要求 Aqua 登录,
Windows 要求交互式用户会话。单独安装不会启动服务或修改账户策略。
diff --git a/tests/fixtures/client-bridge-entry.mjs b/tests/fixtures/client-bridge-entry.mjs
new file mode 100644
index 0000000000..d578320190
--- /dev/null
+++ b/tests/fixtures/client-bridge-entry.mjs
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { parseArgs } from 'node:util';
+import { connectRuntimeHostWslEnvironment } from '../../packages/runtime-host/src/client/wsl-environment.js';
+import { RUNTIME_HOST_COMPATIBILITY_EPOCH } from '../../packages/runtime-host/src/protocol/index.js';
+
+const { values } = parseArgs({
+ options: {
+ bridge: { type: 'string' },
+ 'root-id': { type: 'string' },
+ 'host-epoch': { type: 'string' },
+ },
+});
+const children = [];
+const args = ['host', 'connect', '--framed', '--root-id', values['root-id']];
+function launch(input = args) {
+ const child = spawn(values.bridge, input, { stdio: 'pipe', timeout: 8_000 });
+ child.stderr.pipe(process.stderr, { end: false });
+ const exited = new Promise((resolve) => {
+ child.once('exit', (code, signal) => resolve({ code, signal }));
+ child.once('error', (error) => resolve({ error }));
+ });
+ children.push({ child, exited });
+ return { child, exited };
+}
+const hello = {
+ kind: 'hello',
+ clientInstanceId: 'native-bridge-fixture',
+ protocolMin: 0,
+ protocolMax: 0,
+ compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH,
+ compositionId: 'maka.interactive',
+};
+const line = (frame) => JSON.stringify(frame) + '\n';
+const request = (operation, input, id = 'bridge-request') => ({
+ requestId: id,
+ operation,
+ input,
+});
+
+try {
+ // Exercise the real WSL client and its unchanged launch arguments/transport.
+ // Only the OS process factory is replaced for ordinary three-platform tests.
+ const connection = await connectRuntimeHostWslEnvironment(
+ {
+ distribution: 'Maka-Test',
+ operator: { kind: 'native', platform: 'posix', executablePath: '/maka' },
+ rootId: values['root-id'],
+ clientInstanceId: 'original-wsl-client',
+ },
+ {
+ wslExecutable: 'fixture-wsl',
+ processFactory: (executable, input) => {
+ assert.equal(executable, 'fixture-wsl');
+ assert.deepEqual(input.slice(0, 4), ['--distribution', 'Maka-Test', '--exec', '/maka']);
+ assert(input.includes('--repair-root-after-remount'));
+ return launch(input.slice(4)).child;
+ },
+ },
+ );
+ try {
+ assert.equal(connection.rootId, values['root-id']);
+ assert.equal(connection.hostEpoch, values['host-epoch']);
+ assert.equal(
+ (await connection.request('host.diagnostics.query', {})).hostEpoch,
+ values['host-epoch'],
+ );
+ } finally {
+ await connection.close();
+ }
+
+ if (process.platform !== 'win32') {
+ const { child, exited } = launch();
+ // One write pipelines the request beyond hello; EOF must not discard either
+ // the input prefetch or the Host's final response.
+ child.stdin.end(line(hello) + line(request('host.diagnostics.query', {})));
+ let response;
+ for await (const text of createInterface({ input: child.stdout })) {
+ const frame = JSON.parse(text);
+ if (frame.requestId === 'bridge-request') response = frame;
+ }
+ assert.deepEqual(await exited, { code: 0, signal: null });
+ assert.equal(response?.ok, true, JSON.stringify(response));
+ assert.equal(response.result.hostEpoch, values['host-epoch']);
+ }
+
+ const { child, exited } = launch();
+ child.stdin.write(line(hello));
+ let prepared;
+ for await (const text of createInterface({ input: child.stdout })) {
+ const frame = JSON.parse(text);
+ if (frame.kind === 'accepted') {
+ assert.equal(frame.rootId, values['root-id']);
+ assert.equal(frame.hostEpoch, values['host-epoch']);
+ child.stdin.write(
+ line(
+ request('host.upgrade.prepare', {
+ expectedHostEpoch: values['host-epoch'],
+ allowInterruptActiveTasks: false,
+ allowCooperativeHandoff: true,
+ }),
+ ),
+ );
+ }
+ if (frame.requestId === 'bridge-request') prepared = frame;
+ }
+ // stdin was never ended: a process-lifetime stdio read must not prevent exit.
+ assert.deepEqual(await exited, { code: 0, signal: null });
+ assert.equal(prepared?.ok, true, JSON.stringify(prepared));
+ assert.equal(prepared.result.kind, 'prepared', JSON.stringify(prepared));
+} finally {
+ for (const { child, exited } of children) {
+ if (child.exitCode === null && child.signalCode === null) child.kill();
+ await exited;
+ }
+}
diff --git a/tests/fixtures/client.mjs b/tests/fixtures/client.mjs
index 9afe61c4a5..5fbf98bab4 100644
--- a/tests/fixtures/client.mjs
+++ b/tests/fixtures/client.mjs
@@ -36,6 +36,7 @@ const entries = [
['--project-workspace', 'client-project-entry.mjs'],
['--native-candidate', 'client-candidate-entry.mjs'],
['--activation-frame', 'client-activation-entry.mjs'],
+ ['--bridge', 'client-bridge-entry.mjs'],
['--system-prompt-workspace', 'client-system-prompt-entry.mjs'],
['--model-overrides-workspace', 'client-model-overrides-entry.mjs'],
['--runtime-policy-workspace', 'client-runtime-policy-entry.mjs'],
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org