Files
marqdo-cli/crates/marqdo-host/src/plugin_worker.rs
T
cflmy f69c563afd fix(plugin): bound worker capability calls per invocation (H3-A)
- enforce at most 64 capability requests and 64 KiB per serialized request
  in both the worker handler and the host bridge
- return structured capability.budget_exceeded / request_too_large errors and
  kill the worker on a host-side violation
- add a real C loop fixture and CLI test proving a runaway plugin is stopped
  without producing file contents
- update ADR-0018, plugin-abi and STATUS
2026-11-20 13:11:24 +08:00

355 lines
13 KiB
Rust

//! Host side of the isolated plugin worker transport (ADR-0010).
//!
//! The worker is a child process running the same core binary with the hidden
//! `__plugin-worker` command. It isolates crashes and keeps native code out of
//! the interpreter process. A plain process is **not** an OS sandbox; strict
//! mode still refuses without a real isolation adapter.
use std::collections::BTreeMap;
use std::path::Path;
use std::process::{Child, ChildStdin, Command, Stdio};
use std::sync::mpsc::{self, Receiver};
use std::thread;
use std::time::Duration;
use marqdo_plugin_abi::worker::{
read_frame, write_frame, MAX_CAPABILITY_REQUESTS, MAX_CAPABILITY_REQUEST_BYTES, WORKER_COMMAND,
};
use marqdo_plugin_abi::{
CapabilityHandler, PluginError, PluginManifest, WireRequest, WireResponse,
};
use serde_json::json;
/// A native plugin running in an isolated worker process.
pub struct WorkerPlugin {
child: Child,
stdin: ChildStdin,
frames: Receiver<Result<serde_json::Value, PluginError>>,
exports: BTreeMap<String, String>,
dead: bool,
capability_handler: Option<CapabilityHandler>,
}
const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(30);
const CALL_TIMEOUT: Duration = Duration::from_secs(10);
impl std::fmt::Debug for WorkerPlugin {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("WorkerPlugin")
.field("pid", &self.child.id())
.field("exports", &self.exports.keys().collect::<Vec<_>>())
.finish()
}
}
impl WorkerPlugin {
/// Spawn a worker for `manifest` and wait for its ready frame.
pub fn spawn(
manifest: &PluginManifest,
base_dir: &Path,
capability_handler: Option<CapabilityHandler>,
) -> Result<Self, PluginError> {
// The worker receives an explicit serialized manifest, so it does not
// depend on the manifest file being named `plugin.yaml`.
let manifest_path = std::env::temp_dir().join(format!(
"marqdo-plugin-worker-manifest-{}-{}.json",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_nanos())
.unwrap_or(0)
));
let manifest_bytes = serde_json::to_vec(manifest).map_err(|error| {
PluginError::manifest(
"worker_manifest_encode_failed",
format!("cannot encode manifest for worker: {error}"),
)
})?;
std::fs::write(&manifest_path, manifest_bytes).map_err(|error| {
PluginError::load(
"worker_manifest_unwritable",
format!("cannot write worker manifest: {error}"),
)
})?;
let executable = std::env::current_exe().map_err(|error| {
PluginError::load(
"worker_spawn_failed",
format!("cannot find the current executable: {error}"),
)
})?;
let mut child = match Command::new(executable)
.arg(WORKER_COMMAND)
.arg(&manifest_path)
.arg(base_dir)
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::inherit())
.spawn()
{
Ok(child) => child,
Err(error) => {
let _ = std::fs::remove_file(&manifest_path);
return Err(PluginError::load(
"worker_spawn_failed",
format!("cannot start plugin worker: {error}"),
));
}
};
let Some(stdin) = child.stdin.take() else {
let _ = child.kill();
return Err(PluginError::load(
"worker_spawn_failed",
"worker stdin unavailable",
));
};
let Some(mut stdout) = child.stdout.take() else {
let _ = child.kill();
let _ = std::fs::remove_file(&manifest_path);
return Err(PluginError::load(
"worker_spawn_failed",
"worker stdout unavailable",
));
};
let (sender, frames) = mpsc::channel();
thread::Builder::new()
.name("marqdo-plugin-worker-reader".to_string())
.spawn(move || loop {
match read_frame(&mut stdout) {
Ok(Some(frame)) => {
if sender.send(Ok(frame)).is_err() {
break;
}
}
Ok(None) => {
let _ = sender.send(Err(PluginError::invoke(
"plugin.crashed",
"plugin worker closed its output stream",
)));
break;
}
Err(error) => {
let _ = sender.send(Err(error));
break;
}
}
})
.map_err(|error| {
let _ = child.kill();
PluginError::load(
"worker_spawn_failed",
format!("cannot start worker reader: {error}"),
)
})?;
let ready = match frames.recv_timeout(HANDSHAKE_TIMEOUT) {
Ok(frame) => frame,
Err(_) => {
let _ = std::fs::remove_file(&manifest_path);
let _ = child.kill();
return Err(PluginError::invoke(
"plugin.timeout",
"plugin worker handshake timed out",
));
}
};
let _ = std::fs::remove_file(&manifest_path);
let ready = ready?;
if ready.get("kind").and_then(serde_json::Value::as_str) != Some("ready") {
let _ = child.kill();
return Err(PluginError::load(
"worker_handshake_failed",
"worker did not report ready",
));
}
let mut exports = BTreeMap::new();
if let Some(entries) = ready.get("exports").and_then(serde_json::Value::as_array) {
for entry in entries {
let Some(name) = entry.get("name").and_then(serde_json::Value::as_str) else {
continue;
};
let signature = entry
.get("signature")
.and_then(serde_json::Value::as_str)
.unwrap_or_default()
.to_string();
exports.insert(name.to_string(), signature);
}
}
let declared: std::collections::BTreeSet<&str> = manifest
.plugin
.exports
.iter()
.map(|export| export.name.as_str())
.collect();
let actual: std::collections::BTreeSet<&str> = exports.keys().map(String::as_str).collect();
if declared != actual {
let _ = child.kill();
return Err(PluginError::manifest(
"worker_export_mismatch",
"worker exports do not match the manifest",
));
}
Ok(Self {
child,
stdin,
frames,
exports,
dead: false,
capability_handler,
})
}
/// Invoke one export in the worker.
pub fn invoke(&mut self, request: &WireRequest) -> Result<WireResponse, PluginError> {
if self.dead {
return Err(PluginError::invoke(
"plugin.crashed",
"plugin worker is no longer usable after a transport failure",
));
}
let request_value: serde_json::Value = serde_json::from_slice(&request.to_json_bytes()?)
.map_err(|error| PluginError::wire("worker_encode_failed", error.to_string()))?;
if let Err(error) = write_frame(
&mut self.stdin,
&json!({"kind": "invoke", "request": request_value}),
) {
self.mark_dead();
return Err(error);
}
let deadline = std::time::Instant::now() + CALL_TIMEOUT;
let mut capability_requests = 0usize;
loop {
let remaining = deadline.saturating_duration_since(std::time::Instant::now());
if remaining.is_zero() {
self.mark_dead();
return Err(PluginError::invoke(
"plugin.timeout",
"plugin worker exceeded its invocation timeout",
));
}
let frame = match self.frames.recv_timeout(remaining) {
Ok(Ok(frame)) => frame,
Ok(Err(error)) => {
self.mark_dead();
return Err(error);
}
Err(_) => {
self.mark_dead();
return Err(PluginError::invoke(
"plugin.timeout",
"plugin worker exceeded its invocation timeout",
));
}
};
match frame.get("kind").and_then(serde_json::Value::as_str) {
Some("capability_request") => {
capability_requests += 1;
if capability_requests > MAX_CAPABILITY_REQUESTS {
self.mark_dead();
return Err(PluginError::capability(
"capability.budget_exceeded",
format!(
"plugin exceeded the limit of {MAX_CAPABILITY_REQUESTS} capability requests per invocation"
),
));
}
if let Err(error) = self.handle_capability_request(&frame) {
self.mark_dead();
return Err(error);
}
}
Some("response") => {
return marqdo_plugin_abi::worker::response_from_frame(&frame);
}
Some("error") => {
return Err(PluginError::invoke(
frame
.get("code")
.and_then(serde_json::Value::as_str)
.unwrap_or("plugin_call_failed"),
frame
.get("message")
.and_then(serde_json::Value::as_str)
.unwrap_or("worker reported an error"),
))
}
_ => {
self.mark_dead();
return Err(PluginError::invoke(
"plugin.crashed",
"plugin worker closed or violated the frame protocol",
));
}
}
}
}
fn handle_capability_request(&mut self, frame: &serde_json::Value) -> Result<(), PluginError> {
let id = frame
.get("id")
.and_then(serde_json::Value::as_u64)
.ok_or_else(|| {
PluginError::wire("worker_frame_invalid", "capability request has no id")
})?;
let capability = frame
.get("capability")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PluginError::wire("worker_frame_invalid", "capability request has no name")
})?;
let request_value = frame.get("request").cloned().unwrap_or_else(|| json!({}));
let request_bytes = serde_json::to_vec(&request_value)
.map_err(|error| PluginError::wire("worker_encode_failed", error.to_string()))?;
if request_bytes.len() > MAX_CAPABILITY_REQUEST_BYTES {
return Err(PluginError::capability(
"capability.request_too_large",
format!(
"capability request is {} bytes; limit is {MAX_CAPABILITY_REQUEST_BYTES}",
request_bytes.len()
),
));
}
let result = match &mut self.capability_handler {
Some(handler) => handler(capability, &request_bytes),
None => Err(PluginError::capability(
"capability.unavailable",
"this worker has no host capability bridge",
)),
};
let reply = match result {
Ok(data) => match String::from_utf8(data) {
Ok(data) => json!({"kind":"capability_reply","id":id,"data":data}),
Err(_) => json!({
"kind":"capability_error",
"id":id,
"code":"capability.reply_invalid",
"message":"capability reply is not UTF-8 text",
}),
},
Err(error) => json!({
"kind":"capability_error",
"id":id,
"code":error.code,
"message":error.message,
}),
};
if let Err(error) = write_frame(&mut self.stdin, &reply) {
self.mark_dead();
return Err(error);
}
Ok(())
}
fn mark_dead(&mut self) {
self.dead = true;
let _ = self.child.kill();
}
}
impl Drop for WorkerPlugin {
fn drop(&mut self) {
let _ = write_frame(&mut self.stdin, &json!({"kind": "shutdown"}));
let _ = self.child.kill();
let _ = self.child.wait();
}
}