feat(host): capability host, budgets, effect tracing and kernel adapters
Implements the single side-effect boundary from blueprint sections 7.3 and 9: - Capabilities: console/math, project-relative fs globs, net hosts, process, foreign, plugins; pure/project defaults deny external I/O and grants are explicit, checked at execution time (never at parse time). - Budget: evaluation fuel, call-stack depth, program output bytes and a wall-clock deadline, all reported as resource.exhausted. - EffectTrace: op/module/span/duration/result entries with no secret data. - StdHost: canonical Host implementation dispatching print, fs read/write and the math/foreign kernels; all errors are structured RuntimeErrors, including a permission.denied path with a grant hint. - ProjectFs: project-rooted, rejects absolute paths, `..` traversal and symlink escapes outside the root; bounded UTF-8 reads and safe writes. - Math adapter: parse/eval/substitute through marqdo-math with exact rational binding conversion and explicit unsupported-operation errors. - Foreign adapter: capability-gated one-shot run/call through marqdo-foreign, typed wire input, structured result map, timeout/output limits mapped to budget errors.
This commit is contained in:
1 parent
d799617076
commit
17b68da7f9
9 files changed
+1237
-1
No files matched your search
@@ -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 }
|
||||
@@ -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<Instant>,
|
||||
}
|
||||
|
||||
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<Span>) -> 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<Span>) -> 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<Span>,
|
||||
) -> 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<Span>) -> 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());
|
||||
}
|
||||
}
|
||||
@@ -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<String>,
|
||||
/// Writable project-relative path patterns.
|
||||
pub fs_write: Vec<String>,
|
||||
/// Allowed network hosts (empty = no network).
|
||||
pub net_hosts: Vec<String>,
|
||||
/// May spawn processes (foreign kernels).
|
||||
pub process: bool,
|
||||
/// May run foreign kernels (Python/Node).
|
||||
pub foreign: bool,
|
||||
/// Allowed plugin names.
|
||||
pub plugins: Vec<String>,
|
||||
}
|
||||
|
||||
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<String>) -> 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<String>) -> 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<String>) -> 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<Span>) -> 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<Span>) -> 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<Span>) -> 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<Span>) -> 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<Span>) -> 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<Span>, message: impl Into<String>, hint: impl Into<String>) -> 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());
|
||||
}
|
||||
}
|
||||
@@ -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<Span>,
|
||||
/// Correlates trace entries belonging to one run.
|
||||
pub trace_id: u64,
|
||||
}
|
||||
|
||||
impl ExecutionContext {
|
||||
/// Create a context.
|
||||
pub fn new(module_id: impl Into<String>, span: Option<Span>) -> 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
|
||||
}
|
||||
}
|
||||
@@ -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<PathBuf>) -> 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<Span>,
|
||||
) -> 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::<Vec<_>>()
|
||||
.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<Span>) -> Result<String, RuntimeError> {
|
||||
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<Span>,
|
||||
) -> 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<Span>, message: impl Into<String>) -> 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");
|
||||
}
|
||||
}
|
||||
@@ -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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError>;
|
||||
|
||||
/// Consume evaluation fuel.
|
||||
fn consume_fuel(&mut self, amount: u64, span: Option<Span>) -> Result<(), RuntimeError>;
|
||||
|
||||
/// Check call-stack depth.
|
||||
fn check_stack(&self, depth: usize, span: Option<Span>) -> Result<(), RuntimeError>;
|
||||
|
||||
/// Check the wall-clock deadline.
|
||||
fn check_deadline(&self, span: Option<Span>) -> Result<(), RuntimeError>;
|
||||
|
||||
/// Take the buffered program output.
|
||||
fn take_output(&mut self) -> Vec<u8>;
|
||||
|
||||
/// 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<u8>,
|
||||
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<std::path::PathBuf>,
|
||||
) -> 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<String>, span: Option<Span>) -> 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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<Span>) -> Result<(), RuntimeError> {
|
||||
self.budget.consume_fuel(amount, span)
|
||||
}
|
||||
|
||||
fn check_stack(&self, depth: usize, span: Option<Span>) -> Result<(), RuntimeError> {
|
||||
self.budget.check_stack(depth, span)
|
||||
}
|
||||
|
||||
fn check_deadline(&self, span: Option<Span>) -> Result<(), RuntimeError> {
|
||||
self.budget.check_deadline(span)
|
||||
}
|
||||
|
||||
fn take_output(&mut self) -> Vec<u8> {
|
||||
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<Span>,
|
||||
) -> Result<String, RuntimeError> {
|
||||
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<Span>, name: &str, expected: usize, actual: usize) -> RuntimeError {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::Arity,
|
||||
span,
|
||||
format!("`{name}` expects {expected} argument(s), got {actual}"),
|
||||
)
|
||||
}
|
||||
@@ -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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<marqdo_span::Span>) -> Result<String, RuntimeError> {
|
||||
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<marqdo_span::Span>,
|
||||
) -> Result<BTreeMap<String, Value>, 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<marqdo_span::Span>) -> 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<Value>,
|
||||
ctx: &ExecutionContext,
|
||||
) -> Result<Value, RuntimeError> {
|
||||
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<marqdo_span::Span>,
|
||||
) -> 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<String>) -> 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);
|
||||
@@ -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};
|
||||
@@ -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<Span>,
|
||||
/// 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<TraceEntry>,
|
||||
/// 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<String>,
|
||||
module: impl Into<String>,
|
||||
span: Option<Span>,
|
||||
duration: Duration,
|
||||
result: impl Into<String>,
|
||||
) {
|
||||
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
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user