Files
marqdo/src/host/mod.rs
T

364 lines
12 KiB
Rust

//! L0.5 host primitives for official stdlib (`lib/fs`, `time`, `math`, …).
//!
//! User docs should import L1 wrappers; these `host_*` names are the Rust surface.
//! Capabilities default **on** (importing a lib means you intend to use it).
//! Soft side-effects (no process::exit; sleep clamp) apply under view / capture only.
pub mod agent_rt;
pub mod collection;
mod dispatch;
mod cli;
mod csv;
mod datetime;
mod encoding;
pub mod event_bus;
#[cfg(feature = "exec-host")]
pub mod foreign;
#[cfg(feature = "exec-host")]
pub mod foreign_doc;
#[cfg(feature = "exec-host")]
pub mod foreign_session;
mod fs;
mod hash;
mod html_ops;
pub(crate) mod json;
mod log;
pub(crate) mod oracle;
pub mod math;
mod net;
mod path;
mod re;
mod secrets;
mod stats;
mod text_ops;
mod time;
pub(crate) mod toml_ops;
mod url_ops;
mod uuid_ops;
#[cfg(feature = "plugin-host")]
pub mod plugin;
#[cfg(not(feature = "plugin-host"))]
#[path = "plugin_stub.rs"]
pub mod plugin;
#[cfg(feature = "exec-host")]
pub mod subtask;
#[cfg(not(feature = "exec-host"))]
#[path = "subtask_stub.rs"]
pub mod subtask;
pub mod sandbox_fs;
mod sys;
pub mod writeback;
pub use dispatch::{call_host, HostFn};
/// Shared `text` argument extraction for host modules.
///
/// `<TAB>` slimming: this used to be copy-pasted in 17 host modules with two
/// different wordings; one implementation keeps messages consistent.
pub fn as_text<'a>(v: &'a crate::value::Value, label: &str) -> Result<&'a str, String> {
match v {
crate::value::Value::Text(s) => Ok(s.as_str()),
_ => Err(format!("{label} needs text")),
}
}
pub use fs::path_under_root;
pub use plugin::PluginState;
use std::collections::HashMap;
use std::path::{Path, PathBuf};
/// Host capability flags. Default: all enabled.
#[derive(Debug, Clone, Copy)]
pub struct HostCaps {
pub fs_write: bool,
pub exec: bool,
pub net: bool,
pub plugin: bool,
}
impl Default for HostCaps {
fn default() -> Self {
Self {
fs_write: true,
exec: true,
net: true,
plugin: true,
}
}
}
/// SVG plot produced during a run (for CLI auto-write / view embed).
#[derive(Debug, Clone)]
pub struct PlotArtifact {
/// User-requested path, if any.
pub path: Option<String>,
pub svg: String,
}
#[derive(Debug)]
pub struct HostContext {
pub caps: HostCaps,
pub fs_root: Option<PathBuf>,
pub cwd: PathBuf,
pub argv: Vec<String>,
/// Soft mode: do not `process::exit`; honor sleep_limit (view / capture / export).
pub soft_side_effects: bool,
pub sleep_limit_ms: Option<u64>,
/// LCG state for `random` / `random_int`.
pub rng: u64,
pub plots: Vec<PlotArtifact>,
pub oracle_observations: Vec<crate::value::Value>,
/// lang → interpreter argv (from `set_cmd`).
pub foreign_cmds: HashMap<String, Vec<String>>,
/// Process-local language registrations (`register` / `set_cmd`).
pub foreign_specs: HashMap<String, crate::foreign::registry::LangSpec>,
/// Project config specs (`.marqdo/foreign.toml`), lower priority than runtime.
pub foreign_config_specs: HashMap<String, crate::foreign::registry::LangSpec>,
/// Whether project config has been discovered/loaded.
pub foreign_config_loaded: bool,
/// Persistent foreign kernels (`session_open`).
#[cfg(feature = "exec-host")]
pub foreign_sessions: HashMap<String, foreign_session::Session>,
/// Monotonic session id counter.
#[cfg(feature = "exec-host")]
pub foreign_session_seq: u64,
#[cfg(feature = "exec-host")]
pub foreign_protocol_steps: Vec<foreign_session::ProtocolStep>,
#[cfg(feature = "exec-host")]
pub foreign_replay_expected: Option<foreign_session::validation::ReplayCursor>,
#[cfg(feature = "exec-host")]
pub foreign_replay_divergence: Option<String>,
/// Loaded native plugins (ABI v1/v2).
pub plugins: PluginState,
/// Entry `.mq.md` source text (for ABI host_query / context injection).
pub entry_source: Option<String>,
pub entry_path: Option<PathBuf>,
/// Active function names (outer → inner) for call-site injection.
pub call_stack: Vec<String>,
/// Last statement line (updated by interpreters for call-site queries).
pub current_line: u32,
/// Entry-file line of each active user call (for writeback anchoring).
pub call_site_lines: Vec<u32>,
/// Bound Artifact Metadata from the entry `.mq.md` (Phase 1 Binding).
pub entry_metadata: Vec<(String, crate::value::Value)>,
/// Concurrent subtasks (`lib/subtask`): file / function / foreign.
#[cfg_attr(not(feature = "exec-host"), allow(dead_code))]
pub(crate) subtasks: HashMap<u64, subtask::Handle>,
pub subtask_seq: u64,
/// Minimum log level (`lib/log`); default Info (20). See `host::log::Level`.
pub log_min_level: u8,
/// Active `ext/ai/sandbox` CoW session id (nested `sandbox_run`).
pub sandbox_session: Option<String>,
}
impl Default for HostContext {
fn default() -> Self {
Self {
caps: HostCaps::default(),
fs_root: None,
cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
argv: Vec::new(),
soft_side_effects: false,
sleep_limit_ms: Some(30_000),
rng: 0xC0FF_EE42_CAFE_BABE,
plots: Vec::new(),
oracle_observations: Vec::new(),
foreign_cmds: HashMap::new(),
foreign_specs: HashMap::new(),
foreign_config_specs: HashMap::new(),
foreign_config_loaded: false,
#[cfg(feature = "exec-host")]
foreign_sessions: HashMap::new(),
#[cfg(feature = "exec-host")]
foreign_session_seq: 0,
#[cfg(feature = "exec-host")]
foreign_protocol_steps: Vec::new(),
#[cfg(feature = "exec-host")]
foreign_replay_expected: None,
#[cfg(feature = "exec-host")]
foreign_replay_divergence: None,
plugins: PluginState::default(),
entry_source: None,
entry_path: None,
call_stack: Vec::new(),
current_line: 1,
call_site_lines: Vec::new(),
entry_metadata: Vec::new(),
subtasks: HashMap::new(),
subtask_seq: 0,
log_min_level: 20, // Info
sandbox_session: None,
}
}
}
impl Drop for HostContext {
fn drop(&mut self) {
subtask::kill_all(self);
#[cfg(feature = "exec-host")]
foreign_session::shutdown(self);
}
}
impl HostContext {
pub fn for_run(path: Option<&Path>, caps: HostCaps, argv: Vec<String>) -> Self {
let mut ctx = Self::default();
ctx.caps = caps;
ctx.argv = argv;
if let Some(p) = path {
if let Some(parent) = p.parent() {
let parent = if parent.as_os_str().is_empty() {
PathBuf::from(".")
} else {
parent.to_path_buf()
};
ctx.cwd = parent.clone();
ctx.fs_root = Some(parent);
}
}
ctx
}
/// Capture stdout / view / export: soft exit + sleep clamp; same caps as CLI by default.
pub fn for_capture(path: Option<&Path>, caps: HostCaps) -> Self {
let mut ctx = Self::for_run(path, caps, Vec::new());
ctx.soft_side_effects = true;
ctx.sleep_limit_ms = Some(0);
ctx
}
pub fn allow_fs_write(&self) -> bool {
self.caps.fs_write
}
pub fn allow_exec(&self) -> bool {
self.caps.exec
}
pub fn allow_net(&self) -> bool {
self.caps.net
}
pub fn push_call_site_line(&mut self, line: u32) {
self.call_site_lines.push(line);
}
pub fn pop_call_site_line(&mut self) {
self.call_site_lines.pop();
}
pub fn allow_plugin(&self) -> bool {
self.caps.plugin
}
pub fn next_u64(&mut self) -> u64 {
// SplitMix64-ish LCG step
self.rng = self
.rng
.wrapping_mul(6364136223846793005)
.wrapping_add(1);
let mut z = self.rng;
z = (z ^ (z >> 30)).wrapping_mul(0xbf58476d1ce4e5b9);
z = (z ^ (z >> 27)).wrapping_mul(0x94d049bb133111eb);
z ^ (z >> 31)
}
pub fn next_f64(&mut self) -> f64 {
let x = self.next_u64() >> 11;
(x as f64) / ((1u64 << 53) as f64)
}
pub fn resolve_path(&self, rel: &str) -> Result<PathBuf, String> {
let p = Path::new(rel);
let abs = if p.is_absolute() {
p.to_path_buf()
} else {
self.cwd.join(p)
};
if let Some(root) = &self.fs_root {
let abs = if abs.is_absolute() { abs } else {
std::env::current_dir().map_err(|e|e.to_string())?.join(abs)
};
let root = root.canonicalize().map_err(|e| format!("filesystem root: {e}"))?;
// Normalize before checking, including destinations that do not exist yet.
let mut lexical = PathBuf::new();
for component in abs.components() {
match component {
std::path::Component::CurDir => {},
std::path::Component::ParentDir => { lexical.pop(); },
component => lexical.push(component.as_os_str()),
}
}
if !lexical.is_absolute() {
lexical = std::env::current_dir().map_err(|e| e.to_string())?.join(lexical);
}
if !lexical.starts_with(&root) {
return Err(format!("path escapes sandbox root: {}", abs.display()));
}
// The nearest existing ancestor must also be inside root: a symlink
// cannot authorize writes through a not-yet-existing descendant.
let mut ancestor = lexical.as_path();
loop {
match ancestor.canonicalize() {
Ok(real) => {
if !real.starts_with(&root) {
return Err(format!("path escapes sandbox root: {}", abs.display()));
}
break;
}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
if ancestor.symlink_metadata().is_ok() {
return Err(format!("unresolvable symlink: {}", ancestor.display()));
}
ancestor = ancestor.parent().ok_or_else(|| "invalid file path".to_string())?;
}
Err(e) => return Err(format!("resolve path {}: {e}", abs.display())),
}
}
return Ok(lexical);
}
Ok(abs)
}
}
/// Write auto-named plot files for CLI runs when `path` was omitted.
pub fn flush_auto_plots(source_path: Option<&Path>, plots: &[PlotArtifact]) -> Result<(), String> {
let mut auto_i = 0usize;
for plot in plots {
if plot.path.is_some() {
continue;
}
auto_i += 1;
let stem = source_path
.and_then(|p| p.file_stem())
.and_then(|s| s.to_str())
.unwrap_or("out");
let stem = stem.trim_end_matches(".mq");
let name = format!("{stem}-plot-{auto_i}.svg");
let dir = source_path
.and_then(|p| p.parent())
.unwrap_or_else(|| Path::new("."));
let dest = dir.join(&name);
std::fs::write(&dest, plot.svg.as_bytes())
.map_err(|e| format!("failed to write plot {}: {e}", dest.display()))?;
println!("plot: {}", dest.display());
}
Ok(())
}
mod collection_ops;
mod result;
mod fs_ops;
mod document;
mod net_ops;
mod data_ops;
mod task_ops;
mod archive;