feat(resource): add grant-checked fs resource operations

This commit is contained in:
Marqdo Agent committed 2026-11-21 08:20:31 +08:00
1 parent cd90f059b4
commit fbe36bcc43
16 files changed
+812 -31

No files matched your search

+296 -1
View File
@@ -7,7 +7,8 @@
use std::path::{Component, Path, PathBuf};
use marqdo_span::Span;
use marqdo_value::{ErrorCategory, RuntimeError};
use marqdo_value::{ErrorCategory, RuntimeError, Value};
use std::collections::BTreeMap;
/// Maximum size for a single file read.
pub const MAX_READ_BYTES: u64 = 8 * 1024 * 1024;
@@ -143,6 +144,266 @@ impl ProjectFs {
})
}
/// Execute a path operation on the project filesystem.
///
/// This is the host side of `resource.request`; it validates every path
/// against the project root, then returns the recoverable `Result` map.
/// Capability checks are performed by the host before this method is
/// called. Unknown operations are a programming error and stay fatal.
pub fn request(
&self,
operation: &str,
args: &[String],
span: Option<Span>,
) -> Result<Value, RuntimeError> {
match operation {
"exists" => {
let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?;
if !absolute.exists() {
return Ok(fs_ok(Value::Bool(false)));
}
self.ensure_inside(&absolute, &relative, span)?;
Ok(fs_ok(Value::Bool(true)))
}
"metadata" => {
let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?;
if !absolute.exists() {
return Ok(fs_error(
"fs.not_found",
&format!("`{relative}` does not exist"),
));
}
let absolute = self.ensure_inside(&absolute, &relative, span)?;
let metadata = std::fs::metadata(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot stat `{relative}`: {error}"),
)
})?;
let kind = if metadata.is_file() {
"file"
} else if metadata.is_dir() {
"directory"
} else {
"other"
};
let size = if metadata.is_file() {
metadata.len()
} else {
0
};
let mut value = BTreeMap::new();
value.insert("kind".to_string(), Value::text(kind));
value.insert(
"size".to_string(),
Value::int(size.min(i64::MAX as u64) as i64),
);
Ok(fs_ok(Value::Map(value)))
}
"list" => {
let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?;
if !absolute.exists() {
return Ok(fs_error(
"fs.not_found",
&format!("`{relative}` does not exist"),
));
}
let absolute = self.ensure_inside(&absolute, &relative, span)?;
let metadata = std::fs::metadata(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot stat `{relative}`: {error}"),
)
})?;
if !metadata.is_dir() {
return Ok(fs_error(
"fs.not_directory",
&format!("`{relative}` is not a directory"),
));
}
let mut names = Vec::new();
let entries = std::fs::read_dir(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot list `{relative}`: {error}"),
)
})?;
for entry in entries {
let entry = entry.map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot list `{relative}`: {error}"),
)
})?;
names.push(entry.file_name().to_string_lossy().to_string());
}
names.sort();
Ok(fs_ok(Value::List(
names.into_iter().map(Value::text).collect(),
)))
}
"mkdir" => {
let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?;
self.ensure_parent_inside(&absolute, &relative, span)?;
if absolute.exists() {
return Ok(fs_error(
"fs.exists",
&format!("`{relative}` already exists"),
));
}
match std::fs::create_dir(&absolute) {
Ok(()) => Ok(fs_ok(Value::None)),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(fs_error(
"fs.not_found",
&format!("parent directory of `{relative}` does not exist"),
)),
Err(error) => Err(RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot create directory `{relative}`: {error}"),
)),
}
}
"remove" => {
let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?;
if !absolute.exists() {
return Ok(fs_error(
"fs.not_found",
&format!("`{relative}` does not exist"),
));
}
let absolute = self.ensure_inside(&absolute, &relative, span)?;
let metadata = std::fs::metadata(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot stat `{relative}`: {error}"),
)
})?;
if metadata.is_dir() {
let mut entries = std::fs::read_dir(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot list `{relative}`: {error}"),
)
})?;
if entries.next().is_some() {
return Ok(fs_error(
"fs.not_empty",
&format!("`{relative}` is not empty"),
));
}
std::fs::remove_dir(&absolute).map_err(|error| {
RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot remove `{relative}`: {error}"),
)
})?;
} else {
std::fs::remove_file(&absolute).map_err(|error| {
let category = if error.kind() == std::io::ErrorKind::PermissionDenied {
ErrorCategory::PermissionDenied
} else {
ErrorCategory::HostError
};
RuntimeError::new(
category,
span,
format!("cannot remove `{relative}`: {error}"),
)
})?;
}
Ok(fs_ok(Value::None))
}
"rename" => {
if args.len() != 2 {
return Err(fs_arity(operation, 2, args.len(), span));
}
let (from_absolute, from) = self.resolve(&args[0], span)?;
let (to_absolute, to) = self.resolve(&args[1], span)?;
if !from_absolute.exists() {
return Ok(fs_error(
"fs.not_found",
&format!("`{from}` does not exist"),
));
}
let from_absolute = self.ensure_inside(&from_absolute, &from, span)?;
self.ensure_parent_inside(&to_absolute, &to, span)?;
if to_absolute.exists() {
return Ok(fs_error("fs.exists", &format!("`{to}` already exists")));
}
match std::fs::rename(&from_absolute, &to_absolute) {
Ok(()) => Ok(fs_ok(Value::None)),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(fs_error(
"fs.not_found",
&format!("parent directory of `{to}` does not exist"),
)),
Err(error) => Err(RuntimeError::new(
ErrorCategory::HostError,
span,
format!("cannot rename `{from}` to `{to}`: {error}"),
)),
}
}
other => Err(RuntimeError::new(
ErrorCategory::ResourceUnsupported,
span,
format!("unsupported filesystem operation `{other}`"),
)),
}
}
fn ensure_inside(
&self,
absolute: &Path,
relative: &str,
span: Option<Span>,
) -> Result<PathBuf, RuntimeError> {
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"));
}
Ok(canonical)
}
fn ensure_parent_inside(
&self,
absolute: &Path,
relative: &str,
span: Option<Span>,
) -> Result<(), RuntimeError> {
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"));
}
return Ok(());
}
ancestor = current.parent();
}
Ok(())
}
/// Write a file inside the project root, creating parent directories.
pub fn write(
&self,
@@ -204,6 +465,40 @@ fn invalid_path(span: Option<Span>, message: impl Into<String>) -> RuntimeError
RuntimeError::new(ErrorCategory::PermissionDenied, span, message)
}
fn one_arg<'a>(
operation: &str,
args: &'a [String],
span: Option<Span>,
) -> Result<&'a str, RuntimeError> {
if args.len() != 1 {
return Err(fs_arity(operation, 1, args.len(), span));
}
Ok(&args[0])
}
fn fs_arity(operation: &str, expected: usize, actual: usize, span: Option<Span>) -> RuntimeError {
RuntimeError::new(
ErrorCategory::Arity,
span,
format!("filesystem operation `{operation}` expects {expected} argument(s), got {actual}"),
)
}
fn fs_ok(value: Value) -> Value {
let mut map = BTreeMap::new();
map.insert("ok".to_string(), Value::Bool(true));
map.insert("value".to_string(), value);
Value::Map(map)
}
fn fs_error(code: &str, message: &str) -> Value {
let mut map = BTreeMap::new();
map.insert("ok".to_string(), Value::Bool(false));
map.insert("code".to_string(), Value::text(code));
map.insert("message".to_string(), Value::text(message));
Value::Map(map)
}
#[cfg(test)]
mod tests {
use super::*;
+104
View File
@@ -139,6 +139,23 @@ pub trait Host {
))
}
/// Execute one non-streaming resource operation (ADR-0041).
///
/// Default: unavailable. The standard host implements the `fs.*` group;
/// every call is capability-checked and project-mode only.
fn resource_request(
&mut self,
_operation: &str,
_args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
Err(RuntimeError::new(
ErrorCategory::ResourceUnsupported,
ctx.span,
"this host does not provide resource operations",
))
}
/// Consume evaluation fuel.
fn consume_fuel(&mut self, amount: u64, span: Option<Span>) -> Result<(), RuntimeError>;
@@ -1089,6 +1106,93 @@ impl Host for StdHost {
Ok(())
}
fn resource_request(
&mut self,
operation: &str,
args: Vec<Value>,
ctx: &ExecutionContext,
) -> Result<Value, RuntimeError> {
let started = Instant::now();
if self.mode != SandboxMode::Project {
return Err(RuntimeError::new(
ErrorCategory::PermissionDenied,
ctx.span,
"resource operations are available only in project mode",
));
}
if args.iter().any(Value::contains_memory) || args.iter().any(Value::contains_resource) {
return Err(RuntimeError::new(
ErrorCategory::ResourceUnsupported,
ctx.span,
"resource operations accept only Text path arguments",
));
}
let Some(name) = operation.strip_prefix("fs.") else {
return Err(RuntimeError::new(
ErrorCategory::ResourceUnsupported,
ctx.span,
format!("unsupported resource operation `{operation}`"),
));
};
let expected = match name {
"exists" | "metadata" | "list" | "mkdir" | "remove" => 1,
"rename" => 2,
other => {
return Err(RuntimeError::new(
ErrorCategory::ResourceUnsupported,
ctx.span,
format!("unsupported filesystem operation `{other}`"),
))
}
};
if args.len() != expected {
return Err(RuntimeError::new(
ErrorCategory::Arity,
ctx.span,
format!(
"resource operation `{operation}` expects {expected} argument(s), got {}",
args.len()
),
));
}
let mut paths = Vec::with_capacity(args.len());
for value in args {
let value_type = value.type_name();
let Value::Text(path) = value else {
return Err(RuntimeError::type_error(
ctx.span,
format!(
"resource operation `{operation}` expects Text paths, got {value_type}"
),
));
};
paths.push(path);
}
match name {
"exists" | "metadata" | "list" => {
self.capabilities.check_read(&paths[0], ctx.span)?;
}
"mkdir" | "remove" => {
self.capabilities.check_write(&paths[0], ctx.span)?;
}
"rename" => {
self.capabilities.check_write(&paths[0], ctx.span)?;
self.capabilities.check_write(&paths[1], ctx.span)?;
}
_ => unreachable!(),
}
let result = self.fs.request(name, &paths, ctx.span)?;
self.record_semantic(
"resource.request",
None,
Some(&ctx.module_id),
ctx.span,
Some(&format!("op=fs.{name}")),
);
self.record_resource_effect("resource.request", ctx, started, &format!("fs.{name}"));
Ok(result)
}
fn consume_fuel(&mut self, amount: u64, span: Option<Span>) -> Result<(), RuntimeError> {
self.budget.consume_fuel(amount, span)
}