diff --git a/crates/marqdo-host/Cargo.toml b/crates/marqdo-host/Cargo.toml index 7927cf3..8e00c05 100644 --- a/crates/marqdo-host/Cargo.toml +++ b/crates/marqdo-host/Cargo.toml @@ -9,13 +9,16 @@ repository.workspace = true authors.workspace = true [dependencies] +glob = { workspace = true } marqdo-span = { workspace = true } marqdo-value = { workspace = true } marqdo-math = { workspace = true } marqdo-foreign = { workspace = true } -marqdo-plugin-abi = { workspace = true } marqdo-sandbox = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } thiserror = { workspace = true } + +[dev-dependencies] +tempfile = { workspace = true } diff --git a/crates/marqdo-host/src/budget.rs b/crates/marqdo-host/src/budget.rs new file mode 100644 index 0000000..2bbb2c2 --- /dev/null +++ b/crates/marqdo-host/src/budget.rs @@ -0,0 +1,143 @@ +//! Resource budgets: fuel, stack depth, output bytes and wall-clock deadline. + +use std::time::Instant; + +use marqdo_span::Span; +use marqdo_value::{ErrorCategory, RuntimeError}; + +/// Default evaluation fuel for one run. +pub const DEFAULT_FUEL: u64 = 5_000_000; +/// Default call-stack depth. +pub const DEFAULT_STACK_LIMIT: usize = 256; +/// Default program output limit (bytes). +pub const DEFAULT_OUTPUT_BYTES: usize = 1 << 20; + +/// Bounded resources for a run. +#[derive(Debug, Clone)] +pub struct Budget { + /// Remaining evaluation fuel. + pub fuel: u64, + /// Maximum call-stack depth. + pub stack_limit: usize, + /// Maximum program output in bytes. + pub max_output_bytes: usize, + /// Output bytes produced so far. + pub output_bytes: usize, + /// Optional wall-clock deadline. + pub deadline: Option, +} + +impl Default for Budget { + fn default() -> Self { + Self { + fuel: DEFAULT_FUEL, + stack_limit: DEFAULT_STACK_LIMIT, + max_output_bytes: DEFAULT_OUTPUT_BYTES, + output_bytes: 0, + deadline: None, + } + } +} + +impl Budget { + /// Consume fuel, failing with `resource.exhausted` when it runs out. + pub fn consume_fuel(&mut self, amount: u64, span: Option) -> Result<(), RuntimeError> { + if amount > self.fuel { + self.fuel = 0; + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + "evaluation fuel exhausted", + )); + } + self.fuel -= amount; + Ok(()) + } + + /// Remaining fuel. + pub fn remaining_fuel(&self) -> u64 { + self.fuel + } + + /// Check call-stack depth. + pub fn check_stack(&self, depth: usize, span: Option) -> Result<(), RuntimeError> { + if depth > self.stack_limit { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + format!( + "call stack depth limit ({} frames) exceeded", + self.stack_limit + ), + )); + } + Ok(()) + } + + /// Account for program output, failing when the limit is exceeded. + pub fn consume_output( + &mut self, + amount: usize, + span: Option, + ) -> Result<(), RuntimeError> { + let next = self.output_bytes.saturating_add(amount); + if next > self.max_output_bytes { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + format!( + "program output limit ({} bytes) exceeded", + self.max_output_bytes + ), + )); + } + self.output_bytes = next; + Ok(()) + } + + /// Check the wall-clock deadline. + pub fn check_deadline(&self, span: Option) -> Result<(), RuntimeError> { + if let Some(deadline) = self.deadline { + if Instant::now() >= deadline { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + "wall-clock time limit exceeded", + )); + } + } + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn fuel_is_bounded() { + let mut budget = Budget { + fuel: 10, + ..Budget::default() + }; + assert!(budget.consume_fuel(4, None).is_ok()); + assert_eq!(budget.remaining_fuel(), 6); + assert_eq!( + budget.consume_fuel(7, None).unwrap_err().category, + ErrorCategory::ResourceExhausted + ); + } + + #[test] + fn output_and_stack_limits() { + let mut budget = Budget { + max_output_bytes: 5, + stack_limit: 2, + ..Budget::default() + }; + assert!(budget.consume_output(5, None).is_ok()); + assert!(budget.consume_output(1, None).is_err()); + assert!(budget.check_stack(2, None).is_ok()); + assert!(budget.check_stack(3, None).is_err()); + } +} diff --git a/crates/marqdo-host/src/capability.rs b/crates/marqdo-host/src/capability.rs new file mode 100644 index 0000000..5731fcb --- /dev/null +++ b/crates/marqdo-host/src/capability.rs @@ -0,0 +1,195 @@ +//! Capability model. +//! +//! A project manifest can *request* capabilities, but requests are not grants. +//! Effective permissions are the host default for the sandbox mode intersected +//! with what the operator/CLI explicitly granted. Every host operation checks +//! against this set at the point of execution. + +use glob::Pattern; +use marqdo_span::Span; +use marqdo_value::{ErrorCategory, RuntimeError}; + +/// Effective capability grants for one run. +#[derive(Debug, Clone, Default)] +pub struct Capabilities { + /// Write to program standard output (`打印`). + pub console: bool, + /// Use the native math kernel. + pub math: bool, + /// Readable project-relative path patterns. + pub fs_read: Vec, + /// Writable project-relative path patterns. + pub fs_write: Vec, + /// Allowed network hosts (empty = no network). + pub net_hosts: Vec, + /// May spawn processes (foreign kernels). + pub process: bool, + /// May run foreign kernels (Python/Node). + pub foreign: bool, + /// Allowed plugin names. + pub plugins: Vec, +} + +impl Capabilities { + /// Default grants for pure mode: no external I/O, math and console only. + pub fn pure() -> Self { + Self { + console: true, + math: true, + fs_read: Vec::new(), + fs_write: Vec::new(), + net_hosts: Vec::new(), + process: false, + foreign: false, + plugins: Vec::new(), + } + } + + /// Default grants for project mode: the same baseline; operators add + /// explicit grants for files, processes or plugins. + pub fn project() -> Self { + Self::pure() + } + + /// Grant read access to a project-relative glob pattern. + pub fn allow_read(mut self, pattern: impl Into) -> Self { + self.fs_read.push(pattern.into()); + self + } + + /// Grant write access to a project-relative glob pattern. + pub fn allow_write(mut self, pattern: impl Into) -> Self { + self.fs_write.push(pattern.into()); + self + } + + /// Grant foreign kernel execution. + pub fn allow_foreign(mut self) -> Self { + self.foreign = true; + self.process = true; + self + } + + /// Grant a plugin name. + pub fn allow_plugin(mut self, name: impl Into) -> Self { + self.plugins.push(name.into()); + self + } + + /// Whether a project-relative path matches a granted pattern. + /// + /// Patterns and paths are normalised by stripping a leading `./` so that + /// `--allow-read ./data/**` and the path `data/a.csv` agree. + fn matches(patterns: &[String], relative: &str) -> bool { + let relative = relative.trim_start_matches("./"); + patterns.iter().any(|pattern| { + let pattern = pattern.trim_start_matches("./"); + Pattern::new(pattern) + .map(|pattern| pattern.matches(relative)) + .unwrap_or(false) + }) + } + + /// Check read access. + pub fn check_read(&self, relative: &str, span: Option) -> Result<(), RuntimeError> { + if Self::matches(&self.fs_read, relative) { + Ok(()) + } else { + Err(denied( + span, + format!("read access to `{relative}` was not granted"), + format!("grant it with --allow-read {relative} or a project capability"), + )) + } + } + + /// Check write access. + pub fn check_write(&self, relative: &str, span: Option) -> Result<(), RuntimeError> { + if Self::matches(&self.fs_write, relative) { + Ok(()) + } else { + Err(denied( + span, + format!("write access to `{relative}` was not granted"), + format!("grant it with --allow-write {relative} or a project capability"), + )) + } + } + + /// Check network access for a host. + pub fn check_net(&self, host: &str, span: Option) -> Result<(), RuntimeError> { + if self.net_hosts.iter().any(|allowed| allowed == host) { + Ok(()) + } else { + Err(denied( + span, + format!("network access to `{host}` was not granted"), + "network access is denied by default", + )) + } + } + + /// Check foreign kernel execution. + pub fn check_foreign(&self, span: Option) -> Result<(), RuntimeError> { + if self.foreign && self.process { + Ok(()) + } else { + Err(denied( + span, + "foreign kernel execution was not granted", + "grant it with --allow-foreign (project/strict policy permitting)", + )) + } + } + + /// Check plugin execution. + pub fn check_plugin(&self, name: &str, span: Option) -> Result<(), RuntimeError> { + if self.plugins.iter().any(|allowed| allowed == name) { + Ok(()) + } else { + Err(denied( + span, + format!("plugin `{name}` was not granted execution permission"), + "installing a plugin does not grant permission to run it", + )) + } + } +} + +fn denied(span: Option, message: impl Into, hint: impl Into) -> RuntimeError { + let mut error = RuntimeError::new(ErrorCategory::PermissionDenied, span, message); + error.effect_trace.push(format!("hint: {}", hint.into())); + error +} + +#[cfg(test)] +mod tests { + use super::*; + use marqdo_value::ErrorCategory; + + #[test] + fn defaults_deny_external_io() { + let capabilities = Capabilities::pure(); + assert!(capabilities.math); + assert!(capabilities.console); + assert_eq!( + capabilities + .check_read("data/a.txt", None) + .unwrap_err() + .category, + ErrorCategory::PermissionDenied + ); + assert!(capabilities.check_foreign(None).is_err()); + } + + #[test] + fn explicit_grants_are_glob_scoped() { + let capabilities = Capabilities::project() + .allow_read("./data/**") + .allow_write("./output/**"); + assert!(capabilities.check_read("data/a.csv", None).is_ok()); + assert!(capabilities.check_read("secrets/key", None).is_err()); + assert!(capabilities.check_write("output/result.txt", None).is_ok()); + assert!(capabilities.check_write("data/a.csv", None).is_err()); + } +} diff --git a/crates/marqdo-host/src/context.rs b/crates/marqdo-host/src/context.rs new file mode 100644 index 0000000..dd21882 --- /dev/null +++ b/crates/marqdo-host/src/context.rs @@ -0,0 +1,31 @@ +//! Per-call execution context passed to the host boundary. + +use marqdo_span::Span; + +/// Context attached to every host invocation. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ExecutionContext { + /// Canonical module that initiated the operation. + pub module_id: String, + /// Source span of the call site, when known. + pub span: Option, + /// Correlates trace entries belonging to one run. + pub trace_id: u64, +} + +impl ExecutionContext { + /// Create a context. + pub fn new(module_id: impl Into, span: Option) -> Self { + Self { + module_id: module_id.into(), + span, + trace_id: 0, + } + } + + /// Set the trace id. + pub fn with_trace_id(mut self, trace_id: u64) -> Self { + self.trace_id = trace_id; + self + } +} diff --git a/crates/marqdo-host/src/fs.rs b/crates/marqdo-host/src/fs.rs new file mode 100644 index 0000000..6b868fa --- /dev/null +++ b/crates/marqdo-host/src/fs.rs @@ -0,0 +1,208 @@ +//! Project-scoped filesystem access. +//! +//! Paths are always project-relative. Absolute paths, `..` components and +//! symlink escapes outside the project root are rejected before the capability +//! check, and the capability check happens before any I/O. + +use std::path::{Component, Path, PathBuf}; + +use marqdo_span::Span; +use marqdo_value::{ErrorCategory, RuntimeError}; + +/// Maximum size for a single file read. +pub const MAX_READ_BYTES: u64 = 8 * 1024 * 1024; + +/// A filesystem view rooted at the project directory. +#[derive(Debug, Clone)] +pub struct ProjectFs { + root: PathBuf, +} + +impl ProjectFs { + /// Create a filesystem view. The root is canonicalised when possible. + pub fn new(root: impl Into) -> Self { + let root = root.into(); + let root = root.canonicalize().unwrap_or(root); + Self { root } + } + + /// Project root. + pub fn root(&self) -> &Path { + &self.root + } + + /// Normalise a user supplied project-relative path. + /// + /// Returns the normalised relative string (with `/` separators) used for + /// capability matching and the absolute path inside the project root. + pub fn resolve( + &self, + user_path: &str, + span: Option, + ) -> Result<(PathBuf, String), RuntimeError> { + if user_path.is_empty() { + return Err(invalid_path(span, "path must not be empty")); + } + let path = Path::new(user_path); + if path.is_absolute() { + return Err(invalid_path( + span, + format!("absolute paths are not allowed: `{user_path}`"), + )); + } + let mut normalised = PathBuf::new(); + for component in path.components() { + match component { + Component::Normal(part) => normalised.push(part), + Component::CurDir => {} + Component::ParentDir => { + return Err(invalid_path( + span, + format!("path traversal is not allowed: `{user_path}`"), + )); + } + Component::RootDir | Component::Prefix(_) => { + return Err(invalid_path( + span, + format!("absolute paths are not allowed: `{user_path}`"), + )); + } + } + } + if normalised.as_os_str().is_empty() { + return Err(invalid_path(span, "path must name a file")); + } + let relative = normalised + .components() + .map(|component| component.as_os_str().to_string_lossy().to_string()) + .collect::>() + .join("/"); + let absolute = self.root.join(&normalised); + Ok((absolute, relative)) + } + + /// Read a UTF-8 file, bounded by [`MAX_READ_BYTES`]. + pub fn read(&self, user_path: &str, span: Option) -> Result { + let (absolute, relative) = self.resolve(user_path, span)?; + let metadata = std::fs::metadata(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot read `{relative}`: {error}"), + ) + })?; + if !metadata.is_file() { + return Err(RuntimeError::new( + ErrorCategory::HostError, + span, + format!("`{relative}` is not a regular file"), + )); + } + if metadata.len() > MAX_READ_BYTES { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + format!( + "`{relative}` exceeds the {} byte read limit", + MAX_READ_BYTES + ), + )); + } + let canonical = absolute.canonicalize().map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot resolve `{relative}`: {error}"), + ) + })?; + if !canonical.starts_with(&self.root) { + return Err(invalid_path(span, "path escapes the project root")); + } + let bytes = std::fs::read(&canonical).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot read `{relative}`: {error}"), + ) + })?; + String::from_utf8(bytes).map_err(|_| { + RuntimeError::new( + ErrorCategory::Type, + span, + format!("`{relative}` is not valid UTF-8"), + ) + }) + } + + /// Write a file inside the project root, creating parent directories. + pub fn write( + &self, + user_path: &str, + contents: &str, + span: Option, + ) -> Result<(), RuntimeError> { + let (absolute, relative) = self.resolve(user_path, span)?; + // Validate the closest existing ancestor stays inside the root. + let mut ancestor = absolute.parent(); + while let Some(current) = ancestor { + if current.exists() { + let canonical = current.canonicalize().map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot resolve `{relative}`: {error}"), + ) + })?; + if !canonical.starts_with(&self.root) { + return Err(invalid_path(span, "path escapes the project root")); + } + break; + } + ancestor = current.parent(); + } + if let Some(parent) = absolute.parent() { + std::fs::create_dir_all(parent).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot create parent directory for `{relative}`: {error}"), + ) + })?; + } + std::fs::write(&absolute, contents).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot write `{relative}`: {error}"), + ) + }) + } +} + +fn invalid_path(span: Option, message: impl Into) -> RuntimeError { + RuntimeError::new(ErrorCategory::PermissionDenied, span, message) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rejects_traversal_and_absolute_paths() { + let dir = tempfile::tempdir().unwrap(); + let fs = ProjectFs::new(dir.path()); + assert!(fs.resolve("../etc/passwd", None).is_err()); + assert!(fs.resolve("/etc/passwd", None).is_err()); + assert!(fs.resolve("data/../x.txt", None).is_err()); + assert!(fs.resolve("", None).is_err()); + assert_eq!(fs.resolve("./data/a.txt", None).unwrap().1, "data/a.txt"); + } + + #[test] + fn reads_and_writes_inside_root() { + let dir = tempfile::tempdir().unwrap(); + let fs = ProjectFs::new(dir.path()); + fs.write("output/result.txt", "hello", None).unwrap(); + assert_eq!(fs.read("output/result.txt", None).unwrap(), "hello"); + } +} diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs new file mode 100644 index 0000000..3a3f401 --- /dev/null +++ b/crates/marqdo-host/src/host.rs @@ -0,0 +1,293 @@ +//! CapabilityHost: the only entry point for side effects. +//! +//! The runtime never touches files, processes or the math kernel directly; it +//! calls [`Host::invoke`]. Authorization is checked here, at the point of +//! execution, not at parse/compile time. + +use std::time::{Duration, Instant}; + +use marqdo_span::Span; +use marqdo_value::{ErrorCategory, RuntimeError, Value}; + +use crate::budget::Budget; +use crate::capability::Capabilities; +use crate::context::ExecutionContext; +use crate::fs::ProjectFs; +use crate::trace::{EffectTrace, TraceEntry}; +use marqdo_sandbox::{PlatformCapabilities, SandboxMode}; + +/// Host operations reachable from the language surface. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum HostOp { + /// Write a value to program stdout. + Print, + /// Parse a formula. + MathParse, + /// Evaluate a formula. + MathEval, + /// Substitute variables in a formula. + MathSubstitute, + /// Simplify a formula. + MathSimplify, + /// Differentiate a formula. + MathDifferentiate, + /// One-shot foreign execution. + ForeignRun, + /// Typed foreign call. + ForeignCall, + /// Read a project file. + FsRead, + /// Write a project file. + FsWrite, + /// Invoke a plugin export. + PluginInvoke, +} + +impl HostOp { + /// Stable operation name used in traces and diagnostics. + pub const fn name(self) -> &'static str { + match self { + HostOp::Print => "print", + HostOp::MathParse => "math.parse", + HostOp::MathEval => "math.eval", + HostOp::MathSubstitute => "math.substitute", + HostOp::MathSimplify => "math.simplify", + HostOp::MathDifferentiate => "math.differentiate", + HostOp::ForeignRun => "foreign.run", + HostOp::ForeignCall => "foreign.call", + HostOp::FsRead => "fs.read", + HostOp::FsWrite => "fs.write", + HostOp::PluginInvoke => "plugin.invoke", + } + } +} + +/// The host boundary used by the interpreter and future View/IDE frontends. +pub trait Host { + /// Invoke one operation with already-evaluated arguments. + fn invoke( + &mut self, + op: HostOp, + args: Vec, + ctx: &ExecutionContext, + ) -> Result; + + /// Consume evaluation fuel. + fn consume_fuel(&mut self, amount: u64, span: Option) -> Result<(), RuntimeError>; + + /// Check call-stack depth. + fn check_stack(&self, depth: usize, span: Option) -> Result<(), RuntimeError>; + + /// Check the wall-clock deadline. + fn check_deadline(&self, span: Option) -> Result<(), RuntimeError>; + + /// Take the buffered program output. + fn take_output(&mut self) -> Vec; + + /// Recorded effects. + fn trace(&self) -> &[TraceEntry]; +} + +/// Default capability host implementation. +pub struct StdHost { + /// Requested sandbox mode. + pub mode: SandboxMode, + /// Platform capability report. + pub platform: PlatformCapabilities, + /// Effective grants. + pub capabilities: Capabilities, + /// Bounded resources. + pub budget: Budget, + /// Filesystem view. + pub fs: ProjectFs, + /// Effect trace. + pub trace: EffectTrace, + /// Maximum wall-clock time for one foreign kernel call. + pub foreign_timeout: Duration, + /// Maximum captured bytes per foreign stream. + pub foreign_output_limit: usize, + output: Vec, + trace_id: u64, +} + +impl StdHost { + /// Create a host with the given mode and effective capabilities. + pub fn new( + mode: SandboxMode, + capabilities: Capabilities, + project_root: impl Into, + ) -> Self { + let trace_id = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|duration| duration.as_nanos() as u64) + .unwrap_or(0); + Self { + mode, + platform: PlatformCapabilities::detect(), + capabilities, + budget: Budget::default(), + fs: ProjectFs::new(project_root), + trace: EffectTrace::default(), + foreign_timeout: Duration::from_secs(10), + foreign_output_limit: 1024 * 1024, + output: Vec::new(), + trace_id, + } + } + + /// Enable effect tracing. + pub fn with_trace(mut self) -> Self { + self.trace = EffectTrace::enabled(); + self + } + + /// Override the budget. + pub fn with_budget(mut self, budget: Budget) -> Self { + self.budget = budget; + self + } + + /// Current execution context for a call site. + pub fn context(&self, module: impl Into, span: Option) -> ExecutionContext { + ExecutionContext::new(module, span).with_trace_id(self.trace_id) + } + + /// Buffered program output without consuming it. + pub fn output(&self) -> &[u8] { + &self.output + } + + fn dispatch( + &mut self, + op: HostOp, + args: Vec, + ctx: &ExecutionContext, + ) -> Result { + match op { + HostOp::Print => self.op_print(args, ctx), + HostOp::FsRead => self.op_fs_read(args, ctx), + HostOp::FsWrite => self.op_fs_write(args, ctx), + HostOp::MathParse + | HostOp::MathEval + | HostOp::MathSubstitute + | HostOp::MathSimplify + | HostOp::MathDifferentiate => crate::kernels::math(self, op, args, ctx), + HostOp::ForeignRun | HostOp::ForeignCall => { + crate::kernels::foreign(self, op, args, ctx) + } + HostOp::PluginInvoke => Err(RuntimeError::new( + ErrorCategory::KernelUnavailable, + ctx.span, + "no plugin runtime is loaded in this build", + )), + } + } + + fn op_print( + &mut self, + args: Vec, + ctx: &ExecutionContext, + ) -> Result { + if args.len() != 1 { + return Err(arity(ctx.span, "打印", 1, args.len())); + } + let text = format!("{}\n", args[0].display()); + self.budget.consume_output(text.len(), ctx.span)?; + self.output.extend_from_slice(text.as_bytes()); + Ok(Value::Unit) + } + + fn op_fs_read( + &mut self, + args: Vec, + ctx: &ExecutionContext, + ) -> Result { + let path = expect_text(&args, 0, "fs.read path", ctx.span)?; + self.capabilities.check_read(&path, ctx.span)?; + let contents = self.fs.read(&path, ctx.span)?; + self.budget.consume_output(contents.len(), ctx.span)?; + Ok(Value::Text(contents)) + } + + fn op_fs_write( + &mut self, + args: Vec, + ctx: &ExecutionContext, + ) -> Result { + let path = expect_text(&args, 0, "fs.write path", ctx.span)?; + let contents = expect_text(&args, 1, "fs.write contents", ctx.span)?; + self.capabilities.check_write(&path, ctx.span)?; + self.fs.write(&path, &contents, ctx.span)?; + Ok(Value::Unit) + } +} + +impl Host for StdHost { + fn invoke( + &mut self, + op: HostOp, + args: Vec, + ctx: &ExecutionContext, + ) -> Result { + let started = Instant::now(); + let result = self.dispatch(op, args, ctx); + let summary = match &result { + Ok(_) => "ok".to_string(), + Err(error) => error.code().to_string(), + }; + self.trace.record( + op.name(), + ctx.module_id.clone(), + ctx.span, + started.elapsed(), + summary, + ); + result + } + + fn consume_fuel(&mut self, amount: u64, span: Option) -> Result<(), RuntimeError> { + self.budget.consume_fuel(amount, span) + } + + fn check_stack(&self, depth: usize, span: Option) -> Result<(), RuntimeError> { + self.budget.check_stack(depth, span) + } + + fn check_deadline(&self, span: Option) -> Result<(), RuntimeError> { + self.budget.check_deadline(span) + } + + fn take_output(&mut self) -> Vec { + std::mem::take(&mut self.output) + } + + fn trace(&self) -> &[TraceEntry] { + self.trace.entries() + } +} + +/// Type-checked argument helper. +pub fn expect_text( + args: &[Value], + index: usize, + what: &str, + span: Option, +) -> Result { + match args.get(index) { + Some(Value::Text(text)) => Ok(text.clone()), + Some(other) => Err(RuntimeError::type_error( + span, + format!("{what} must be Text, got {}", other.type_name()), + )), + None => Err(arity(span, what, index + 1, args.len())), + } +} + +/// Arity error helper. +pub fn arity(span: Option, name: &str, expected: usize, actual: usize) -> RuntimeError { + RuntimeError::new( + ErrorCategory::Arity, + span, + format!("`{name}` expects {expected} argument(s), got {actual}"), + ) +} diff --git a/crates/marqdo-host/src/kernels.rs b/crates/marqdo-host/src/kernels.rs new file mode 100644 index 0000000..fae2138 --- /dev/null +++ b/crates/marqdo-host/src/kernels.rs @@ -0,0 +1,276 @@ +//! Math and foreign kernel adapters. +//! +//! These functions are the only bridge between the capability host and the +//! native math / foreign crates. Every operation is capability-checked before +//! the kernel is touched; kernel failures are converted to structured runtime +//! errors, never panics. + +use std::collections::BTreeMap; +use std::time::Duration; + +use marqdo_value::{to_wire, ErrorCategory, FormulaValue, RuntimeError, Value}; + +use crate::context::ExecutionContext; +use crate::host::{arity, expect_text, HostOp, StdHost}; + +pub(crate) fn math( + host: &mut StdHost, + op: HostOp, + args: Vec, + ctx: &ExecutionContext, +) -> Result { + if !host.capabilities.math { + return Err(denied(ctx, "the math capability was not granted")); + } + let span = ctx.span; + match op { + HostOp::MathParse => { + let source = expect_text(&args, 0, "math.parse source", span)?; + let formula = marqdo_math::parse(&source).map_err(|error| math_error(error, span))?; + Ok(Value::Formula(FormulaValue { + latex: formula.source, + unit: None, + display: false, + span, + })) + } + HostOp::MathEval => { + if args.len() < 2 { + return Err(arity(span, "math.eval", 2, args.len())); + } + let formula = formula_source(&args[0], span)?; + let bindings = math_bindings(&args[1], span)?; + let target = match args.get(2) { + Some(Value::Text(target)) => Some(target.clone()), + Some(Value::None) | None => None, + Some(other) => { + return Err(RuntimeError::type_error( + span, + format!("math.eval target must be Text, got {}", other.type_name()), + )) + } + }; + let parsed = marqdo_math::parse(&formula).map_err(|error| math_error(error, span))?; + marqdo_math::evaluate(&parsed, &bindings, target.as_deref()) + .map_err(|error| math_error(error, span)) + } + HostOp::MathSubstitute => { + if args.len() < 2 { + return Err(arity(span, "math.substitute", 2, args.len())); + } + let source = formula_source(&args[0], span)?; + let bindings = math_bindings(&args[1], span)?; + let parsed = marqdo_math::parse(&source).map_err(|error| math_error(error, span))?; + let substituted = marqdo_math::substitute(&parsed, &bindings) + .map_err(|error| math_error(error, span))?; + Ok(Value::Formula(FormulaValue { + latex: substituted.source, + unit: None, + display: false, + span, + })) + } + HostOp::MathSimplify | HostOp::MathDifferentiate => Err(RuntimeError::new( + ErrorCategory::MathUnsupported, + span, + format!( + "`{}` is not part of the supported math subset in this build", + op.name() + ), + )), + _ => Err(RuntimeError::new( + ErrorCategory::Internal, + span, + "unexpected math operation", + )), + } +} + +fn formula_source(value: &Value, span: Option) -> Result { + match value { + Value::Formula(formula) => Ok(formula.latex.clone()), + Value::Text(text) => Ok(text.clone()), + other => Err(RuntimeError::type_error( + span, + format!("expected Formula or Text, got {}", other.type_name()), + )), + } +} + +fn math_bindings( + value: &Value, + span: Option, +) -> Result, RuntimeError> { + match value { + Value::Map(map) => { + let mut bindings = BTreeMap::new(); + for (name, value) in map { + match value { + Value::Int(_) | Value::Float(_) => { + bindings.insert(name.clone(), value.clone()); + } + other => { + return Err(RuntimeError::type_error( + span, + format!( + "math binding `{name}` must be Int or Float, got {}", + other.type_name() + ), + )) + } + } + } + Ok(bindings) + } + other => Err(RuntimeError::type_error( + span, + format!("math bindings must be a Map, got {}", other.type_name()), + )), + } +} + +fn math_error(error: marqdo_math::MathError, span: Option) -> RuntimeError { + use marqdo_math::MathErrorKind; + let category = match error.kind { + MathErrorKind::Parse | MathErrorKind::Unsupported => ErrorCategory::MathUnsupported, + MathErrorKind::UndefinedVariable => ErrorCategory::UnknownSymbol, + MathErrorKind::Type => ErrorCategory::Type, + }; + let mut message = error.message; + if let Some(position) = error.position { + message = format!("{message} (at byte {position} of the formula)"); + } + RuntimeError::new(category, span, message) +} + +pub(crate) fn foreign( + host: &mut StdHost, + op: HostOp, + args: Vec, + ctx: &ExecutionContext, +) -> Result { + host.capabilities.check_foreign(ctx.span)?; + let span = ctx.span; + let Some(Value::Code(code)) = args.first() else { + return Err(RuntimeError::type_error( + span, + "foreign kernel expects a Code value from `ref(\"#代码块\")`", + )); + }; + if code.language.trim().is_empty() { + return Err(RuntimeError::new( + ErrorCategory::KernelUnavailable, + span, + "code fence has no language, so no kernel can be selected", + )); + } + let input = match args.get(1) { + None | Some(Value::None) => None, + Some(value) => Some(to_wire(value)), + }; + let request = marqdo_foreign::RunRequest { + language: code.language.clone(), + source: code.source.clone(), + input, + timeout: host.foreign_timeout, + max_output_bytes: host.foreign_output_limit, + }; + match op { + HostOp::ForeignRun => { + let result = + marqdo_foreign::run(&request).map_err(|error| foreign_error(error, span))?; + Ok(foreign_result_map(result)) + } + HostOp::ForeignCall => { + let result = + marqdo_foreign::call(&request).map_err(|error| foreign_error(error, span))?; + if result.status != marqdo_foreign::RunStatus::Success { + return Err(RuntimeError::new( + ErrorCategory::ForeignFailure, + span, + format!( + "foreign call failed (status {:?}): {}", + result.status, result.stderr + ), + )); + } + result.value.ok_or_else(|| { + RuntimeError::new( + ErrorCategory::ForeignFailure, + span, + "foreign call returned no typed value", + ) + }) + } + _ => Err(RuntimeError::new( + ErrorCategory::Internal, + span, + "unexpected foreign operation", + )), + } +} + +fn foreign_result_map(result: marqdo_foreign::RunResult) -> Value { + let mut map = BTreeMap::new(); + map.insert( + "status".to_string(), + Value::text(match result.status { + marqdo_foreign::RunStatus::Success => "success", + marqdo_foreign::RunStatus::Failed => "failed", + marqdo_foreign::RunStatus::TimedOut => "timed_out", + }), + ); + map.insert("stdout".to_string(), Value::text(result.stdout)); + map.insert("stderr".to_string(), Value::text(result.stderr)); + map.insert( + "exit_code".to_string(), + match result.exit_code { + Some(code) => Value::int(code as i64), + None => Value::None, + }, + ); + map.insert( + "duration_ms".to_string(), + Value::int(result.duration.as_millis() as i64), + ); + map.insert( + "value".to_string(), + match result.value { + Some(value) => value, + None => Value::None, + }, + ); + Value::Map(map) +} + +fn foreign_error( + error: marqdo_foreign::ForeignError, + span: Option, +) -> RuntimeError { + use marqdo_foreign::ForeignError; + let (category, message) = match error { + ForeignError::KernelUnavailable { language, hint } => ( + ErrorCategory::KernelUnavailable, + format!("foreign kernel `{language}` is unavailable: {hint}"), + ), + ForeignError::Spawn { message } => (ErrorCategory::HostError, message), + ForeignError::Io { message } => (ErrorCategory::HostError, message), + ForeignError::Timeout { seconds } => ( + ErrorCategory::ResourceExhausted, + format!("foreign kernel exceeded its {seconds}s timeout"), + ), + ForeignError::Protocol { message } => (ErrorCategory::ForeignFailure, message), + ForeignError::OutputTooLarge { limit } => ( + ErrorCategory::ResourceExhausted, + format!("foreign kernel exceeded the {limit} byte output limit"), + ), + }; + RuntimeError::new(category, span, message) +} + +fn denied(ctx: &ExecutionContext, message: impl Into) -> RuntimeError { + RuntimeError::new(ErrorCategory::PermissionDenied, ctx.span, message) +} + +/// Default per-call foreign timeout used by the CLI. +pub const DEFAULT_FOREIGN_TIMEOUT: Duration = Duration::from_secs(10); diff --git a/crates/marqdo-host/src/lib.rs b/crates/marqdo-host/src/lib.rs new file mode 100644 index 0000000..1df0d7b --- /dev/null +++ b/crates/marqdo-host/src/lib.rs @@ -0,0 +1,21 @@ +//! CapabilityHost: capability checks, resource budgets, effect tracing and the +//! only bridge to math, foreign kernels, files and plugins. +//! +//! Blueprint §9 and §7.3: every side effect goes through this boundary, checks +//! happen at the point of execution, and host failures are structured errors. + +pub mod budget; +pub mod capability; +pub mod context; +pub mod fs; +pub mod host; +pub mod kernels; +pub mod trace; + +pub use budget::{Budget, DEFAULT_FUEL, DEFAULT_OUTPUT_BYTES, DEFAULT_STACK_LIMIT}; +pub use capability::Capabilities; +pub use context::ExecutionContext; +pub use fs::ProjectFs; +pub use host::{arity, expect_text, Host, HostOp, StdHost}; +pub use marqdo_sandbox::{PlatformCapabilities, SandboxMode, StrictIsolation}; +pub use trace::{EffectTrace, TraceEntry}; diff --git a/crates/marqdo-host/src/trace.rs b/crates/marqdo-host/src/trace.rs new file mode 100644 index 0000000..72d120f --- /dev/null +++ b/crates/marqdo-host/src/trace.rs @@ -0,0 +1,66 @@ +//! Effect tracing. + +use std::time::Duration; + +use marqdo_span::Span; +use serde::{Deserialize, Serialize}; + +/// One recorded host effect. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct TraceEntry { + /// Operation name (`print`, `fs.read`, `foreign.call`, ...). + pub op: String, + /// Module that initiated it. + pub module: String, + /// Source span of the call site. + #[serde(skip_serializing_if = "Option::is_none")] + pub span: Option, + /// Wall-clock duration. + pub duration_micros: u64, + /// Result summary (`ok`, or a diagnostic code). Never contains secrets. + pub result: String, +} + +/// Collected effects for one run. +#[derive(Debug, Clone, Default)] +pub struct EffectTrace { + entries: Vec, + /// Whether tracing is enabled. + pub enabled: bool, +} + +impl EffectTrace { + /// Enable tracing. + pub fn enabled() -> Self { + Self { + entries: Vec::new(), + enabled: true, + } + } + + /// Record an effect. + pub fn record( + &mut self, + op: impl Into, + module: impl Into, + span: Option, + duration: Duration, + result: impl Into, + ) { + if !self.enabled { + return; + } + self.entries.push(TraceEntry { + op: op.into(), + module: module.into(), + span, + duration_micros: duration.as_micros() as u64, + result: result.into(), + }); + } + + /// Recorded entries. + pub fn entries(&self) -> &[TraceEntry] { + &self.entries + } +}