Files
marqdo-cli/crates/marqdo-plugin-abi/src/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

388 lines
15 KiB
Rust

//! Isolated plugin worker transport (length-prefixed JSON frames).
//!
//! The worker is the same core binary invoked with the hidden
//! `__plugin-worker` command. It loads one native plugin in a child process and
//! serves invoke frames over stdin/stdout. This isolates crashes and provides a
//! process boundary; it is **not** an OS sandbox and does not make arbitrary
//! untrusted native code safe.
use std::io::{Read, Write};
use std::path::Path;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use serde_json::{json, Value};
use crate::error::PluginError;
use crate::loader::{LoadOptions, LoadedPlugin};
use crate::manifest::{PluginKind, PluginManifest};
use crate::wire::{WireRequest, WireResponse};
/// Hidden CLI command name used to start a worker.
pub const WORKER_COMMAND: &str = "__plugin-worker";
/// Maximum frame size accepted by either side.
pub const MAX_FRAME_BYTES: usize = 8 * 1024 * 1024;
/// Maximum capability requests a plugin may make during one invocation.
pub const MAX_CAPABILITY_REQUESTS: usize = 64;
/// Maximum serialized bytes of one capability request.
pub const MAX_CAPABILITY_REQUEST_BYTES: usize = 64 * 1024;
/// Read one length-prefixed frame (4-byte big-endian length + JSON).
///
/// `Ok(None)` means a clean EOF at a frame boundary. A partial header or
/// truncated payload is a protocol error, never EOF.
pub fn read_frame<R: Read>(reader: &mut R) -> Result<Option<Value>, PluginError> {
let mut length = [0_u8; 4];
let mut read = 0usize;
while read < length.len() {
match reader.read(&mut length[read..]) {
Ok(0) if read == 0 => return Ok(None),
Ok(0) => {
return Err(PluginError::wire(
"worker_frame_invalid",
"worker stream ended inside a frame header",
))
}
Ok(count) => read += count,
Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
Err(error) => {
return Err(PluginError::invoke(
"plugin.crashed",
format!("worker frame read failed: {error}"),
))
}
}
}
let length = u32::from_be_bytes(length) as usize;
if length == 0 || length > MAX_FRAME_BYTES {
return Err(PluginError::wire(
"worker_frame_invalid",
format!("worker frame length {length} is invalid"),
));
}
let mut bytes = Vec::with_capacity(length.min(64 * 1024));
let read = reader
.take(length as u64)
.read_to_end(&mut bytes)
.map_err(|error| {
PluginError::invoke(
"plugin.crashed",
format!("worker frame read failed: {error}"),
)
})?;
if read != length {
return Err(PluginError::wire(
"worker_frame_invalid",
format!("worker frame declared {length} bytes but only {read} arrived"),
));
}
serde_json::from_slice(&bytes).map(Some).map_err(|error| {
PluginError::wire(
"worker_frame_invalid",
format!("worker frame is not valid JSON: {error}"),
)
})
}
/// Write one length-prefixed frame.
pub fn write_frame<W: Write>(writer: &mut W, value: &Value) -> Result<(), PluginError> {
let bytes = serde_json::to_vec(value).map_err(|error| {
PluginError::wire(
"worker_encode_failed",
format!("cannot encode worker frame: {error}"),
)
})?;
if bytes.len() > MAX_FRAME_BYTES {
return Err(PluginError::wire(
"worker_frame_too_large",
format!("worker frame is {} bytes", bytes.len()),
));
}
writer
.write_all(&(bytes.len() as u32).to_be_bytes())
.and_then(|()| writer.write_all(&bytes))
.and_then(|()| writer.flush())
.map_err(|error| {
PluginError::invoke(
"plugin.crashed",
format!("worker frame write failed: {error}"),
)
})
}
/// Run one worker until shutdown/EOF. Returns a process exit code.
pub fn serve(manifest_path: &Path, base_dir: &Path) -> i32 {
let manifest = match PluginManifest::load(manifest_path) {
Ok(manifest) => manifest,
Err(error) => {
eprintln!("worker: {}: {}", error.code, error.message);
return 2;
}
};
// The worker is the isolated transport; the library itself is loaded
// natively inside this child process.
let mut native_manifest = manifest.clone();
native_manifest.plugin.kind = PluginKind::Native;
let stdin = Arc::new(Mutex::new(std::io::stdin()));
let stdout = Arc::new(Mutex::new(std::io::stdout()));
let next_request_id = Arc::new(AtomicU64::new(1));
let capability_calls = Arc::new(AtomicUsize::new(0));
let handler_stdin = Arc::clone(&stdin);
let handler_stdout = Arc::clone(&stdout);
let handler_ids = Arc::clone(&next_request_id);
let handler_calls = Arc::clone(&capability_calls);
let capability_handler: crate::loader::CapabilityHandler = Box::new(
move |capability, request| {
if handler_calls.fetch_add(1, Ordering::SeqCst) >= MAX_CAPABILITY_REQUESTS {
return Err(PluginError::capability(
"capability.budget_exceeded",
format!(
"plugin exceeded the limit of {MAX_CAPABILITY_REQUESTS} capability requests per invocation"
),
));
}
if request.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.len()
),
));
}
let id = handler_ids.fetch_add(1, Ordering::SeqCst);
let request_value: Value = serde_json::from_slice(request).map_err(|error| {
PluginError::capability(
"capability.request_invalid",
format!("capability request is not valid JSON: {error}"),
)
})?;
{
let mut out = handler_stdout.lock().map_err(|_| {
PluginError::invoke("plugin.crashed", "worker stdout lock is poisoned")
})?;
write_frame(
&mut *out,
&json!({
"kind": "capability_request",
"id": id,
"capability": capability,
"request": request_value,
}),
)?;
}
{
let frame = {
let mut input = handler_stdin.lock().map_err(|_| {
PluginError::invoke("plugin.crashed", "worker stdin lock is poisoned")
})?;
read_frame(&mut *input).map_err(|error| {
PluginError::invoke(
error.code.as_str(),
format!("worker capability reply failed: {}", error.message),
)
})?
};
let Some(frame) = frame else {
return Err(PluginError::invoke(
"plugin.crashed",
"host closed the worker during a capability request",
));
};
if frame.get("id").and_then(Value::as_u64) != Some(id) {
return Err(PluginError::wire(
"worker_frame_invalid",
"capability reply id does not match the request",
));
}
match frame.get("kind").and_then(Value::as_str) {
Some("capability_reply") => {
let data = frame.get("data").and_then(Value::as_str).ok_or_else(|| {
PluginError::wire(
"worker_frame_invalid",
"capability reply has no text data",
)
})?;
Ok(data.as_bytes().to_vec())
}
Some("capability_error") => Err(PluginError::capability(
frame
.get("code")
.and_then(Value::as_str)
.unwrap_or("capability.unavailable"),
frame
.get("message")
.and_then(Value::as_str)
.unwrap_or("capability request failed")
.to_string(),
)),
_ => Err(PluginError::wire(
"worker_frame_invalid",
"expected a capability reply frame",
)),
}
}
},
);
let options = LoadOptions {
host_target: crate::artifact::HostTarget::current(),
capability_handler: Some(capability_handler),
};
let mut plugin = match LoadedPlugin::open_with(&native_manifest, base_dir, options) {
Ok(plugin) => plugin,
Err(error) => {
eprintln!("worker: {}: {}", error.code, error.message);
return 2;
}
};
let exports: Vec<Value> = plugin
.exports()
.map(|export| json!({"name": export.name(), "signature": export.signature()}))
.collect();
if send_frame(&stdout, &json!({"kind": "ready", "exports": exports})).is_err() {
return 1;
}
loop {
let frame = match receive_frame(&stdin) {
Ok(Some(frame)) => frame,
Ok(None) => return 0,
Err(error) => {
eprintln!("worker: {}: {}", error.code, error.message);
return 1;
}
};
match frame.get("kind").and_then(Value::as_str) {
Some("shutdown") => return 0,
Some("invoke") => {
let Some(request_value) = frame.get("request") else {
let _ = send_frame(
&stdout,
&json!({"kind":"error","code":"worker_request_invalid","message":"missing request"}),
);
continue;
};
let request_bytes = match serde_json::to_vec(request_value) {
Ok(bytes) => bytes,
Err(error) => {
let _ = send_frame(
&stdout,
&json!({"kind":"error","code":"worker_request_invalid","message":error.to_string()}),
);
continue;
}
};
let request = match WireRequest::from_json_bytes(&request_bytes) {
Ok(request) => request,
Err(error) => {
let _ = send_frame(
&stdout,
&json!({"kind":"error","code":error.code,"message":error.message}),
);
continue;
}
};
capability_calls.store(0, Ordering::SeqCst);
match plugin.invoke(&request) {
Ok(response) => {
let body = response
.to_json_bytes()
.ok()
.and_then(|bytes| serde_json::from_slice::<Value>(&bytes).ok())
.unwrap_or_else(|| json!({"wire_version":1,"kind":"response"}));
if send_frame(&stdout, &json!({"kind":"response","response":body})).is_err() {
return 1;
}
}
Err(error) => {
if send_frame(
&stdout,
&json!({"kind":"error","code":error.code,"message":error.message,"error_kind":error.kind.as_str()}),
)
.is_err()
{
return 1;
}
}
}
}
_ => {
if send_frame(
&stdout,
&json!({"kind":"error","code":"worker_frame_invalid","message":"unknown frame kind"}),
)
.is_err()
{
return 1;
}
}
}
}
}
fn send_frame(stdout: &Arc<Mutex<std::io::Stdout>>, value: &Value) -> Result<(), PluginError> {
let mut out = stdout
.lock()
.map_err(|_| PluginError::invoke("plugin.crashed", "worker stdout lock is poisoned"))?;
write_frame(&mut *out, value)
}
fn receive_frame(stdin: &Arc<Mutex<std::io::Stdin>>) -> Result<Option<Value>, PluginError> {
let mut input = stdin
.lock()
.map_err(|_| PluginError::invoke("plugin.crashed", "worker stdin lock is poisoned"))?;
read_frame(&mut *input)
}
pub fn response_from_frame(frame: &Value) -> Result<WireResponse, PluginError> {
let body = frame
.get("response")
.ok_or_else(|| PluginError::wire("worker_response_invalid", "missing response body"))?;
let bytes = serde_json::to_vec(body)
.map_err(|error| PluginError::wire("worker_response_invalid", error.to_string()))?;
WireResponse::from_json_bytes(&bytes)
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Cursor;
#[test]
fn frame_roundtrip_and_clean_eof() {
let mut bytes = Vec::new();
write_frame(&mut bytes, &json!({"kind": "shutdown"})).unwrap();
let mut cursor = Cursor::new(bytes.clone());
assert_eq!(
read_frame(&mut cursor).unwrap(),
Some(json!({"kind": "shutdown"}))
);
assert_eq!(read_frame(&mut cursor).unwrap(), None);
}
#[test]
fn partial_header_is_an_error_not_eof() {
let mut cursor = Cursor::new(vec![0_u8, 0]);
let error = read_frame(&mut cursor).unwrap_err();
assert_eq!(error.code, "worker_frame_invalid");
}
#[test]
fn oversized_and_zero_length_frames_are_rejected() {
for length in [0_u32, (MAX_FRAME_BYTES as u32) + 1] {
let mut cursor = Cursor::new(length.to_be_bytes().to_vec());
let error = read_frame(&mut cursor).unwrap_err();
assert_eq!(error.code, "worker_frame_invalid");
}
}
#[test]
fn truncated_payload_is_rejected() {
let mut bytes = 10_u32.to_be_bytes().to_vec();
bytes.extend_from_slice(b"{}");
let error = read_frame(&mut Cursor::new(bytes)).unwrap_err();
assert_eq!(error.code, "worker_frame_invalid");
}
}