- Add a marqdo.provider schema v1 loader (schema/version/ABI/platform library) and StdHost::register_provider_package, reusing the C ABI adapter and shared kind/name checks (ADR-0037). - Add a compiled-provider + provider.json installation test; language use still requires project mode and allow_resource_provider. - Update ADR/spec/status/README/changelog and evidence; no registry, signature or CLI install is claimed. Gate: fmt, clippy -D warnings, 437 tests passed.
1138 lines
40 KiB
Rust
1138 lines
40 KiB
Rust
//! 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::collections::{BTreeMap, BTreeSet};
|
|
use std::net::{SocketAddr, TcpStream};
|
|
use std::sync::{Arc, Mutex};
|
|
use std::time::{Duration, Instant};
|
|
|
|
use marqdo_plugin_abi::{
|
|
ErrorKind as PluginErrorKind, LoadedPlugin, PluginError, PluginKind, PluginManifest,
|
|
};
|
|
use marqdo_span::Span;
|
|
use marqdo_value::{ErrorCategory, ResourceHandle, RuntimeError, Value};
|
|
|
|
use crate::budget::Budget;
|
|
use crate::capability::{Capabilities, CapabilityAudit, CapabilityBroker};
|
|
use crate::context::ExecutionContext;
|
|
use crate::fs::ProjectFs;
|
|
use crate::handles::{contains_plugin_handle, PluginHandleTable};
|
|
use crate::plugin_worker::WorkerPlugin;
|
|
use crate::provider_c::{load_package, CResourceProvider};
|
|
use crate::provider_worker::WorkerResourceProvider;
|
|
use crate::resource::{ResourceProvider, ResourceRead, ResourceTable, SharedResourceProvider};
|
|
use crate::trace::{EffectTrace, SemanticEvent, TraceBudget, TraceEntry, TraceState};
|
|
use marqdo_sandbox::{PlatformCapabilities, SandboxMode};
|
|
|
|
/// Host operations reachable from the language surface.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub enum HostOp {
|
|
/// 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::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>;
|
|
|
|
/// Open a resource/stream by kind, descriptor and requested rights.
|
|
///
|
|
/// Default: unavailable. Only the standard host implements the first
|
|
/// resource kinds (ADR-0025).
|
|
fn resource_open(
|
|
&mut self,
|
|
_kind: &str,
|
|
_descriptor: &str,
|
|
_rights: &[String],
|
|
ctx: &ExecutionContext,
|
|
) -> Result<Value, RuntimeError> {
|
|
Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"this host does not provide resource streams",
|
|
))
|
|
}
|
|
|
|
/// Read up to `max_bytes` from a resource into host memory.
|
|
fn resource_read(
|
|
&mut self,
|
|
_handle: ResourceHandle,
|
|
_max_bytes: usize,
|
|
ctx: &ExecutionContext,
|
|
) -> Result<ResourceRead, RuntimeError> {
|
|
Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"this host does not provide resource streams",
|
|
))
|
|
}
|
|
|
|
/// Write bytes to a resource; returns the accepted count.
|
|
fn resource_write(
|
|
&mut self,
|
|
_handle: ResourceHandle,
|
|
_bytes: &[u8],
|
|
ctx: &ExecutionContext,
|
|
) -> Result<usize, RuntimeError> {
|
|
Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"this host does not provide resource streams",
|
|
))
|
|
}
|
|
|
|
/// Close a resource handle.
|
|
fn resource_close(
|
|
&mut self,
|
|
_handle: ResourceHandle,
|
|
ctx: &ExecutionContext,
|
|
) -> Result<(), RuntimeError> {
|
|
Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"this host does not provide resource streams",
|
|
))
|
|
}
|
|
|
|
/// 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];
|
|
|
|
/// Record one semantic event (Trace v1). Default: ignored.
|
|
fn record_semantic(
|
|
&mut self,
|
|
_kind: &str,
|
|
_function_id: Option<&str>,
|
|
_module_id: Option<&str>,
|
|
_span: Option<Span>,
|
|
_detail: Option<&str>,
|
|
) {
|
|
}
|
|
|
|
/// Recorded semantic events. Default: empty.
|
|
fn semantic_events(&self) -> &[SemanticEvent] {
|
|
&[]
|
|
}
|
|
}
|
|
|
|
/// 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,
|
|
/// Registered foreign kernels (built-in Python/Node plus explicit providers).
|
|
pub kernel_registry: marqdo_foreign::KernelRegistry,
|
|
output: Vec<u8>,
|
|
trace_id: u64,
|
|
/// Explicitly trusted, in-process native plugins.
|
|
plugins: Vec<PluginSlot>,
|
|
/// Complete export name -> index into `plugins` (ADR-0010).
|
|
plugin_exports: BTreeMap<String, usize>,
|
|
/// Trusted vendor capability policy entries for the broker.
|
|
vendor_capabilities: BTreeSet<String>,
|
|
/// Shared audit log for plugin capability requests.
|
|
broker_audit: Arc<Mutex<Vec<CapabilityAudit>>>,
|
|
/// Host-issued opaque plugin handles.
|
|
pub handles: PluginHandleTable,
|
|
/// Host-owned resource/stream table (ADR-0025).
|
|
resources: ResourceTable,
|
|
/// Registered in-process providers keyed by resource kind (ADR-0033).
|
|
resource_providers: BTreeMap<String, (String, SharedResourceProvider)>,
|
|
semantic_events: Vec<SemanticEvent>,
|
|
next_event_seq: u64,
|
|
trace_state: TraceState,
|
|
}
|
|
|
|
struct PluginSlot {
|
|
/// Package name used for capability grants.
|
|
package: String,
|
|
/// Artifact/manifest digest that produced this registration.
|
|
manifest_digest: String,
|
|
/// Complete export name -> declared signature.
|
|
exports: BTreeMap<String, String>,
|
|
plugin: PluginTransport,
|
|
}
|
|
|
|
enum PluginTransport {
|
|
Native(LoadedPlugin),
|
|
Worker(WorkerPlugin),
|
|
}
|
|
|
|
impl PluginTransport {
|
|
fn invoke(
|
|
&mut self,
|
|
request: &marqdo_plugin_abi::WireRequest,
|
|
) -> Result<marqdo_plugin_abi::WireResponse, PluginError> {
|
|
match self {
|
|
PluginTransport::Native(plugin) => plugin.invoke(request),
|
|
PluginTransport::Worker(plugin) => plugin.invoke(request),
|
|
}
|
|
}
|
|
}
|
|
|
|
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,
|
|
kernel_registry: marqdo_foreign::KernelRegistry::builtin(),
|
|
output: Vec::new(),
|
|
trace_id,
|
|
plugins: Vec::new(),
|
|
plugin_exports: BTreeMap::new(),
|
|
vendor_capabilities: BTreeSet::new(),
|
|
broker_audit: Arc::new(Mutex::new(Vec::new())),
|
|
handles: PluginHandleTable::default(),
|
|
resources: ResourceTable::new(),
|
|
resource_providers: BTreeMap::new(),
|
|
semantic_events: Vec::new(),
|
|
next_event_seq: 0,
|
|
trace_state: TraceState::default(),
|
|
}
|
|
}
|
|
|
|
/// Load a native plugin in-process after an explicit trust decision.
|
|
///
|
|
/// In-process native code shares the host address space and is **not**
|
|
/// sandboxed; this build has no isolated worker transport. The caller must
|
|
/// pass `trusted = true` and grant the plugin capability. Every export is
|
|
/// registered by its complete dotted name (ADR-0010); the whole load is
|
|
/// rejected atomically if any name conflicts.
|
|
pub fn load_plugin(
|
|
&mut self,
|
|
manifest: &PluginManifest,
|
|
base_dir: &std::path::Path,
|
|
trusted: bool,
|
|
) -> Result<Vec<String>, RuntimeError> {
|
|
self.capabilities
|
|
.check_plugin(&manifest.plugin.name, None)?;
|
|
manifest.validate().map_err(map_plugin_error)?;
|
|
let mut exports = BTreeMap::new();
|
|
for export in &manifest.plugin.exports {
|
|
if !export.name.contains('.') {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PluginAbi,
|
|
None,
|
|
format!("plugin export `{}` must be namespaced", export.name),
|
|
));
|
|
}
|
|
if self.plugin_exports.contains_key(&export.name) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PluginFailure,
|
|
None,
|
|
format!(
|
|
"plugin export `{}` is already registered by another plugin",
|
|
export.name
|
|
),
|
|
));
|
|
}
|
|
exports.insert(export.name.clone(), export.signature.clone());
|
|
}
|
|
let artifact = manifest
|
|
.resolve_artifact(&marqdo_plugin_abi::HostTarget::current())
|
|
.map_err(map_plugin_error)?;
|
|
let manifest_digest = artifact.sha256.clone();
|
|
let transport = match manifest.plugin.kind {
|
|
PluginKind::Native => {
|
|
if !trusted {
|
|
let mut error = RuntimeError::new(
|
|
ErrorCategory::PermissionDenied,
|
|
None,
|
|
"loading an in-process native plugin requires explicit trust",
|
|
);
|
|
error.effect_trace.push(
|
|
"hint: use `kind: worker` for crash isolation, or pass --trust-native-plugin for in-process native code"
|
|
.to_string(),
|
|
);
|
|
return Err(error);
|
|
}
|
|
let mut broker = CapabilityBroker::with_audit(
|
|
self.capabilities.clone(),
|
|
Arc::clone(&self.broker_audit),
|
|
)
|
|
.with_fs(self.fs.clone());
|
|
for capability in &self.vendor_capabilities {
|
|
broker.allow_vendor(capability.clone());
|
|
}
|
|
let package = manifest.plugin.name.clone();
|
|
let options = marqdo_plugin_abi::LoadOptions {
|
|
host_target: marqdo_plugin_abi::HostTarget::current(),
|
|
capability_handler: Some(Box::new(move |capability, request| {
|
|
broker.execute(&package, capability, request)
|
|
})),
|
|
};
|
|
PluginTransport::Native(
|
|
LoadedPlugin::open_with(manifest, base_dir, options)
|
|
.map_err(map_plugin_error)?,
|
|
)
|
|
}
|
|
PluginKind::Worker => {
|
|
let mut broker = CapabilityBroker::with_audit(
|
|
self.capabilities.clone(),
|
|
Arc::clone(&self.broker_audit),
|
|
)
|
|
.with_fs(self.fs.clone());
|
|
for capability in &self.vendor_capabilities {
|
|
broker.allow_vendor(capability.clone());
|
|
}
|
|
let package = manifest.plugin.name.clone();
|
|
let handler: marqdo_plugin_abi::CapabilityHandler =
|
|
Box::new(move |capability, request| {
|
|
broker.execute(&package, capability, request)
|
|
});
|
|
PluginTransport::Worker(
|
|
WorkerPlugin::spawn(manifest, base_dir, Some(handler))
|
|
.map_err(map_plugin_error)?,
|
|
)
|
|
}
|
|
PluginKind::Wasm => {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::KernelUnavailable,
|
|
None,
|
|
"plugin kind `wasm` is not supported in this build",
|
|
))
|
|
}
|
|
};
|
|
let index = self.plugins.len();
|
|
self.plugins.push(PluginSlot {
|
|
package: manifest.plugin.name.clone(),
|
|
manifest_digest,
|
|
exports: exports.clone(),
|
|
plugin: transport,
|
|
});
|
|
let names: Vec<String> = exports.keys().cloned().collect();
|
|
for name in &names {
|
|
self.plugin_exports.insert(name.clone(), index);
|
|
}
|
|
Ok(names)
|
|
}
|
|
|
|
/// Trust a vendor capability for future plugin loads.
|
|
pub fn allow_vendor_capability(&mut self, capability: impl Into<String>) {
|
|
self.vendor_capabilities.insert(capability.into());
|
|
}
|
|
|
|
/// Registered plugin exports as `(complete name, signature, digest, package)`.
|
|
pub fn plugin_exports(&self) -> Vec<(String, String, String, String)> {
|
|
let mut exports = Vec::new();
|
|
for slot in &self.plugins {
|
|
for (name, signature) in &slot.exports {
|
|
exports.push((
|
|
name.clone(),
|
|
signature.clone(),
|
|
slot.manifest_digest.clone(),
|
|
slot.package.clone(),
|
|
));
|
|
}
|
|
}
|
|
exports.sort();
|
|
exports
|
|
}
|
|
|
|
/// Recorded semantic events (Trace v1).
|
|
pub fn semantic_events(&self) -> &[SemanticEvent] {
|
|
&self.semantic_events
|
|
}
|
|
|
|
fn next_seq(&mut self) -> u64 {
|
|
let seq = self.next_event_seq;
|
|
self.next_event_seq += 1;
|
|
seq
|
|
}
|
|
|
|
/// Trace capacity state for the writer.
|
|
pub fn trace_state(&self) -> &TraceState {
|
|
&self.trace_state
|
|
}
|
|
|
|
/// Override the trace event/byte budget.
|
|
pub fn with_trace_budget(mut self, budget: TraceBudget) -> Self {
|
|
self.trace_state.budget = budget;
|
|
self
|
|
}
|
|
|
|
/// Audited plugin capability decisions.
|
|
pub fn capability_audit(&self) -> Vec<CapabilityAudit> {
|
|
self.broker_audit
|
|
.lock()
|
|
.map(|audit| audit.clone())
|
|
.unwrap_or_default()
|
|
}
|
|
|
|
/// Register an explicit external foreign-kernel provider.
|
|
pub fn register_kernel(
|
|
&mut self,
|
|
descriptor: marqdo_foreign::KernelDescriptor,
|
|
) -> Result<(), RuntimeError> {
|
|
self.kernel_registry.register(descriptor).map_err(|error| {
|
|
RuntimeError::new(ErrorCategory::KernelUnavailable, None, error.to_string())
|
|
})
|
|
}
|
|
|
|
/// Enable effect tracing.
|
|
pub fn with_trace(mut self) -> Self {
|
|
self.trace = EffectTrace::enabled();
|
|
self.trace_state.enabled = true;
|
|
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::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 => self.op_plugin_invoke(args, ctx),
|
|
}
|
|
}
|
|
|
|
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_plugin_invoke(
|
|
&mut self,
|
|
args: Vec<Value>,
|
|
ctx: &ExecutionContext,
|
|
) -> Result<Value, RuntimeError> {
|
|
if args.len() != 2 {
|
|
return Err(arity(ctx.span, "plugin.invoke", 2, args.len()));
|
|
}
|
|
let Value::Text(export_name) = &args[0] else {
|
|
return Err(RuntimeError::type_error(
|
|
ctx.span,
|
|
"plugin export name must be Text",
|
|
));
|
|
};
|
|
let Value::Map(named_args) = &args[1] else {
|
|
return Err(RuntimeError::type_error(
|
|
ctx.span,
|
|
"plugin call arguments must be named",
|
|
));
|
|
};
|
|
let Some(index) = self.plugin_exports.get(export_name).copied() else {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::UnknownSymbol,
|
|
ctx.span,
|
|
format!("no plugin export `{export_name}` is loaded"),
|
|
));
|
|
};
|
|
let package = self.plugins[index].package.clone();
|
|
self.capabilities.check_plugin(&package, ctx.span)?;
|
|
let mut request = marqdo_plugin_abi::WireRequest::new(export_name.clone());
|
|
for (name, value) in named_args {
|
|
request = request.with_arg(name.clone(), value);
|
|
}
|
|
let response = self.plugins[index]
|
|
.plugin
|
|
.invoke(&request)
|
|
.map_err(map_plugin_error)?;
|
|
let value = response.typed_value().map_err(map_plugin_error)?;
|
|
if let Some(value) = &value {
|
|
if contains_plugin_handle(value) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PluginFailure,
|
|
ctx.span,
|
|
"plugin_handle.untrusted: plugin output may not mint host handles",
|
|
));
|
|
}
|
|
}
|
|
Ok(value.unwrap_or(Value::Unit))
|
|
}
|
|
|
|
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)
|
|
}
|
|
|
|
/// Register an explicitly trusted in-process provider (ADR-0033).
|
|
///
|
|
/// In-process providers share the host address space and are not a
|
|
/// sandbox; only trusted adapters may be registered. Registration is not a
|
|
/// language operation and does not grant access by itself.
|
|
pub fn register_resource_provider(
|
|
&mut self,
|
|
provider: Box<dyn ResourceProvider>,
|
|
) -> Result<(), RuntimeError> {
|
|
self.register_provider_checked(provider)
|
|
}
|
|
|
|
/// Register a trusted C ABI resource provider (ADR-0036).
|
|
///
|
|
/// The shared library runs in the host address space and is **trusted**, not
|
|
/// sandboxed. Registration still requires the provider-name grant at
|
|
/// `resource.open` and is project-mode only.
|
|
pub fn register_c_resource_provider(
|
|
&mut self,
|
|
name: &str,
|
|
kinds: &[&str],
|
|
library: &std::path::Path,
|
|
) -> Result<(), RuntimeError> {
|
|
let kinds = kinds
|
|
.iter()
|
|
.map(|kind| (*kind).to_string())
|
|
.collect::<Vec<_>>();
|
|
let provider = CResourceProvider::open(name, &kinds, library)?;
|
|
self.register_provider_checked(Box::new(provider))
|
|
}
|
|
|
|
/// Register a trusted C ABI provider from a `marqdo.provider` manifest
|
|
/// (ADR-0037). The manifest is host-side installation metadata; language
|
|
/// imports cannot install or authorize a provider.
|
|
pub fn register_provider_package(
|
|
&mut self,
|
|
manifest_path: &std::path::Path,
|
|
) -> Result<(), RuntimeError> {
|
|
let provider = load_package(manifest_path)?;
|
|
self.register_provider_checked(Box::new(provider))
|
|
}
|
|
|
|
/// Register a trusted worker-process resource provider (ADR-0035).
|
|
///
|
|
/// The helper speaks framed JSON over stdin/stdout and is **not** an OS
|
|
/// sandbox; only explicitly trusted helpers may be spawned.
|
|
pub fn register_worker_resource_provider(
|
|
&mut self,
|
|
name: &str,
|
|
kinds: &[&str],
|
|
program: &std::path::Path,
|
|
args: &[String],
|
|
) -> Result<(), RuntimeError> {
|
|
let kinds = kinds
|
|
.iter()
|
|
.map(|kind| (*kind).to_string())
|
|
.collect::<Vec<_>>();
|
|
let provider = WorkerResourceProvider::spawn(name, &kinds, program, args)?;
|
|
self.register_provider_checked(Box::new(provider))
|
|
}
|
|
|
|
fn register_provider_checked(
|
|
&mut self,
|
|
provider: Box<dyn ResourceProvider>,
|
|
) -> Result<(), RuntimeError> {
|
|
if provider.protocol_version() != 1 {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
None,
|
|
format!(
|
|
"resource provider `{}` uses unsupported protocol version {}",
|
|
provider.name(),
|
|
provider.protocol_version()
|
|
),
|
|
));
|
|
}
|
|
let name = provider.name().to_string();
|
|
if name.is_empty() || name == "stdio" || name == "file" {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
None,
|
|
format!("resource provider name `{name}` is reserved or empty"),
|
|
));
|
|
}
|
|
let kinds = provider.kind_strings();
|
|
if kinds.is_empty() {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
None,
|
|
format!("resource provider `{name}` declares no kinds"),
|
|
));
|
|
}
|
|
for kind in &kinds {
|
|
if kind.is_empty() || kind == "stdio" || kind == "file" {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
None,
|
|
format!("resource provider `{name}` declares reserved kind `{kind}`"),
|
|
));
|
|
}
|
|
if let Some((existing, _)) = self.resource_providers.get(kind) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
None,
|
|
format!(
|
|
"resource kind `{kind}` is already registered by provider `{existing}`"
|
|
),
|
|
));
|
|
}
|
|
}
|
|
let provider: SharedResourceProvider = std::sync::Arc::new(std::sync::Mutex::new(provider));
|
|
for kind in kinds {
|
|
self.resource_providers
|
|
.insert(kind, (name.clone(), std::sync::Arc::clone(&provider)));
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
fn record_resource_effect(
|
|
&mut self,
|
|
op: &str,
|
|
ctx: &ExecutionContext,
|
|
started: Instant,
|
|
summary: &str,
|
|
) {
|
|
let estimate = TraceState::estimate(
|
|
"effect",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
Some(summary),
|
|
Some(op),
|
|
);
|
|
if !self.trace_state.accept(estimate) {
|
|
return;
|
|
}
|
|
let seq = self.next_seq();
|
|
self.trace.record(
|
|
seq,
|
|
op,
|
|
ctx.module_id.clone(),
|
|
ctx.span,
|
|
started.elapsed(),
|
|
summary.to_string(),
|
|
);
|
|
}
|
|
|
|
fn open_resource_stream(
|
|
&mut self,
|
|
kind: &str,
|
|
descriptor: &str,
|
|
rights: &[String],
|
|
ctx: &ExecutionContext,
|
|
) -> Result<Value, RuntimeError> {
|
|
let started = Instant::now();
|
|
let requested: BTreeSet<&str> = rights.iter().map(String::as_str).collect();
|
|
if self.mode == SandboxMode::Strict {
|
|
// stdio/stdout is the existing console channel already permitted by
|
|
// strict L1 (CM-A11); file/network/process providers are not.
|
|
let stdio_console =
|
|
kind == "stdio" && descriptor == "stdout" && requested == BTreeSet::from(["write"]);
|
|
if !stdio_console {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PermissionDenied,
|
|
ctx.span,
|
|
"strict mode permits only the existing stdio/stdout console channel; \
|
|
other resource streams are refused",
|
|
));
|
|
}
|
|
}
|
|
if self.mode == SandboxMode::Pure && kind == "file" {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PermissionDenied,
|
|
ctx.span,
|
|
"pure mode does not provide project file resources",
|
|
));
|
|
}
|
|
match kind {
|
|
"stdio" => {
|
|
if descriptor != "stdout" || requested != BTreeSet::from(["write"]) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"the first stream slice supports only stdio/stdout with rights [write]",
|
|
));
|
|
}
|
|
if !self.capabilities.console {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PermissionDenied,
|
|
ctx.span,
|
|
"the console capability is required for stdio/stdout",
|
|
));
|
|
}
|
|
let handle = self.resources.open_stdout();
|
|
self.record_semantic(
|
|
"resource.open",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some("kind=stdio descriptor=stdout"),
|
|
);
|
|
self.record_resource_effect("resource.open", ctx, started, "ok");
|
|
Ok(Value::Resource(handle))
|
|
}
|
|
"file" => {
|
|
if requested == BTreeSet::from(["read"]) {
|
|
self.capabilities.check_read(descriptor, ctx.span)?;
|
|
let (_, relative) = self.fs.resolve(descriptor, ctx.span)?;
|
|
let bytes = self.fs.read_bytes(descriptor, ctx.span)?;
|
|
let handle = self.resources.open_file(relative, bytes);
|
|
self.record_semantic(
|
|
"resource.open",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some("kind=file rights=read"),
|
|
);
|
|
self.record_resource_effect("resource.open", ctx, started, "ok");
|
|
return Ok(Value::Resource(handle));
|
|
}
|
|
if requested == BTreeSet::from(["write"]) {
|
|
self.capabilities.check_write(descriptor, ctx.span)?;
|
|
let (_, relative) = self.fs.resolve(descriptor, ctx.span)?;
|
|
let handle = self.resources.open_file_writer(relative);
|
|
self.record_semantic(
|
|
"resource.open",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some("kind=file rights=write"),
|
|
);
|
|
self.record_resource_effect("resource.open", ctx, started, "ok");
|
|
return Ok(Value::Resource(handle));
|
|
}
|
|
Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"project file streams support exactly [read] or [write] in this build",
|
|
))
|
|
}
|
|
"tcp" => {
|
|
if self.mode != SandboxMode::Project {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PermissionDenied,
|
|
ctx.span,
|
|
"tcp resources are available only in project mode",
|
|
));
|
|
}
|
|
if requested != BTreeSet::from(["read", "write"]) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
"tcp resources require exactly [read, write] in this build",
|
|
));
|
|
}
|
|
let address: SocketAddr = descriptor.parse().map_err(|_| {
|
|
RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
format!(
|
|
"tcp descriptor `{descriptor}` must be an IP literal address:port (DNS names are not resolved in this build)"
|
|
),
|
|
)
|
|
})?;
|
|
self.capabilities
|
|
.check_net(&address.ip().to_string(), ctx.span)?;
|
|
let stream = TcpStream::connect_timeout(&address, Duration::from_secs(5)).map_err(
|
|
|error| {
|
|
RuntimeError::new(
|
|
ErrorCategory::HostError,
|
|
ctx.span,
|
|
format!("cannot connect to {address}: {error}"),
|
|
)
|
|
},
|
|
)?;
|
|
let _ = stream.set_read_timeout(Some(Duration::from_secs(5)));
|
|
let _ = stream.set_write_timeout(Some(Duration::from_secs(5)));
|
|
let handle = self.resources.open_tcp(stream);
|
|
self.record_semantic(
|
|
"resource.open",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some(&format!("kind=tcp address={address}")),
|
|
);
|
|
self.record_resource_effect("resource.open", ctx, started, "ok");
|
|
Ok(Value::Resource(handle))
|
|
}
|
|
other => {
|
|
if self.mode != SandboxMode::Project {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::PermissionDenied,
|
|
ctx.span,
|
|
"resource providers are available only in project mode",
|
|
));
|
|
}
|
|
let Some((provider_name, provider)) = self.resource_providers.get(other).cloned()
|
|
else {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::ResourceUnsupported,
|
|
ctx.span,
|
|
format!("resource kind `{other}` is not registered"),
|
|
));
|
|
};
|
|
self.capabilities
|
|
.check_resource_provider(&provider_name, ctx.span)?;
|
|
let handle = self
|
|
.resources
|
|
.open_provider(provider, other, descriptor, rights, ctx.span)?;
|
|
self.record_semantic(
|
|
"resource.open",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some(&format!("kind={other} provider={provider_name}")),
|
|
);
|
|
self.record_resource_effect("resource.open", ctx, started, "ok");
|
|
Ok(Value::Resource(handle))
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
impl Host for StdHost {
|
|
fn invoke(
|
|
&mut self,
|
|
op: HostOp,
|
|
args: Vec<Value>,
|
|
ctx: &ExecutionContext,
|
|
) -> Result<Value, RuntimeError> {
|
|
// Addressable memory is language-local state. Handles must not reach a
|
|
// plugin, foreign kernel or file adapter, where they could not be
|
|
// interpreted safely (RFC-CM-0001 §8, ADR-0022 §4).
|
|
if args.iter().any(Value::contains_memory) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::Type,
|
|
ctx.span,
|
|
format!(
|
|
"Memory values cannot cross the host boundary (`{}`); copy bytes into \
|
|
Text explicitly first",
|
|
op.name()
|
|
),
|
|
));
|
|
}
|
|
if args.iter().any(Value::contains_resource) {
|
|
return Err(RuntimeError::new(
|
|
ErrorCategory::Type,
|
|
ctx.span,
|
|
format!(
|
|
"Resource handles cannot cross the generic host boundary (`{}`); use \
|
|
resource.* operations",
|
|
op.name()
|
|
),
|
|
));
|
|
}
|
|
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(),
|
|
};
|
|
let estimate = TraceState::estimate(
|
|
"effect",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
Some(&summary),
|
|
Some(op.name()),
|
|
);
|
|
if self.trace_state.accept(estimate) {
|
|
let seq = self.next_seq();
|
|
self.trace.record(
|
|
seq,
|
|
op.name(),
|
|
ctx.module_id.clone(),
|
|
ctx.span,
|
|
started.elapsed(),
|
|
summary,
|
|
);
|
|
}
|
|
result
|
|
}
|
|
|
|
fn resource_open(
|
|
&mut self,
|
|
kind: &str,
|
|
descriptor: &str,
|
|
rights: &[String],
|
|
ctx: &ExecutionContext,
|
|
) -> Result<Value, RuntimeError> {
|
|
self.open_resource_stream(kind, descriptor, rights, ctx)
|
|
}
|
|
|
|
fn resource_read(
|
|
&mut self,
|
|
handle: ResourceHandle,
|
|
max_bytes: usize,
|
|
ctx: &ExecutionContext,
|
|
) -> Result<ResourceRead, RuntimeError> {
|
|
let started = Instant::now();
|
|
let kind = self.resources.kind(handle, ctx.span)?;
|
|
let read = self.resources.read(handle, max_bytes, ctx.span)?;
|
|
self.record_semantic(
|
|
"resource.read",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some(&format!(
|
|
"kind={kind} count={} eof={}",
|
|
read.bytes.len(),
|
|
read.eof
|
|
)),
|
|
);
|
|
self.record_resource_effect(
|
|
"resource.read",
|
|
ctx,
|
|
started,
|
|
&format!("kind={kind} count={}", read.bytes.len()),
|
|
);
|
|
Ok(read)
|
|
}
|
|
|
|
fn resource_write(
|
|
&mut self,
|
|
handle: ResourceHandle,
|
|
bytes: &[u8],
|
|
ctx: &ExecutionContext,
|
|
) -> Result<usize, RuntimeError> {
|
|
let started = Instant::now();
|
|
let kind = self.resources.kind(handle, ctx.span)?;
|
|
let count = self.resources.write(handle, bytes, ctx.span)?;
|
|
if kind == "stdio" {
|
|
self.budget.consume_output(count, ctx.span)?;
|
|
self.output.extend_from_slice(bytes);
|
|
}
|
|
self.record_semantic(
|
|
"resource.write",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some(&format!("kind={kind} count={count}")),
|
|
);
|
|
self.record_resource_effect(
|
|
"resource.write",
|
|
ctx,
|
|
started,
|
|
&format!("kind={kind} count={count}"),
|
|
);
|
|
Ok(count)
|
|
}
|
|
|
|
fn resource_close(
|
|
&mut self,
|
|
handle: ResourceHandle,
|
|
ctx: &ExecutionContext,
|
|
) -> Result<(), RuntimeError> {
|
|
let started = Instant::now();
|
|
let pending = self.resources.pending_file_write(handle, ctx.span)?;
|
|
let count = match pending {
|
|
Some((relative, bytes)) => {
|
|
self.fs.write_bytes(&relative, &bytes, ctx.span)?;
|
|
bytes.len()
|
|
}
|
|
None => 0,
|
|
};
|
|
self.resources.close(handle, ctx.span)?;
|
|
self.record_semantic(
|
|
"resource.close",
|
|
None,
|
|
Some(&ctx.module_id),
|
|
ctx.span,
|
|
Some(&format!("flushed_bytes={count}")),
|
|
);
|
|
self.record_resource_effect(
|
|
"resource.close",
|
|
ctx,
|
|
started,
|
|
&format!("flushed_bytes={count}"),
|
|
);
|
|
Ok(())
|
|
}
|
|
|
|
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()
|
|
}
|
|
|
|
fn record_semantic(
|
|
&mut self,
|
|
kind: &str,
|
|
function_id: Option<&str>,
|
|
module_id: Option<&str>,
|
|
span: Option<Span>,
|
|
detail: Option<&str>,
|
|
) {
|
|
let estimate = TraceState::estimate(kind, function_id, module_id, detail, None);
|
|
if !self.trace_state.accept(estimate) {
|
|
return;
|
|
}
|
|
let seq = self.next_seq();
|
|
self.semantic_events.push(SemanticEvent {
|
|
seq,
|
|
kind: kind.to_string(),
|
|
function_id: function_id.map(str::to_string),
|
|
module_id: module_id.map(str::to_string),
|
|
span,
|
|
detail: detail.map(str::to_string),
|
|
});
|
|
}
|
|
|
|
fn semantic_events(&self) -> &[SemanticEvent] {
|
|
&self.semantic_events
|
|
}
|
|
}
|
|
|
|
fn map_plugin_error(error: PluginError) -> RuntimeError {
|
|
let category = match error.kind {
|
|
PluginErrorKind::Abi => ErrorCategory::PluginAbi,
|
|
PluginErrorKind::Capability => ErrorCategory::PermissionDenied,
|
|
PluginErrorKind::Wire => ErrorCategory::Type,
|
|
PluginErrorKind::Unsupported => ErrorCategory::KernelUnavailable,
|
|
_ => ErrorCategory::PluginFailure,
|
|
};
|
|
RuntimeError::new(category, None, format!("{}: {}", error.code, error.message))
|
|
}
|
|
|
|
/// 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}"),
|
|
)
|
|
}
|