Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:
- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.
Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
230 lines
7.9 KiB
Rust
230 lines
7.9 KiB
Rust
//! 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 bytes = self.read_bytes(user_path, span)?;
|
|
String::from_utf8(bytes).map_err(|_| {
|
|
RuntimeError::new(
|
|
ErrorCategory::Type,
|
|
span,
|
|
format!("`{user_path}` is not valid UTF-8"),
|
|
)
|
|
})
|
|
}
|
|
|
|
/// Read a file as raw bytes, bounded by [`MAX_READ_BYTES`].
|
|
///
|
|
/// Used by the resource stream provider; path/capability checks are the
|
|
/// caller's responsibility for grants, while this method still rejects
|
|
/// traversal and symlink escapes.
|
|
pub fn read_bytes(&self, user_path: &str, span: Option<Span>) -> Result<Vec<u8>, 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"));
|
|
}
|
|
std::fs::read(&canonical).map_err(|error| {
|
|
RuntimeError::new(
|
|
ErrorCategory::HostError,
|
|
span,
|
|
format!("cannot read `{relative}`: {error}"),
|
|
)
|
|
})
|
|
}
|
|
|
|
/// Write a file inside the project root, creating parent directories.
|
|
pub fn write(
|
|
&self,
|
|
user_path: &str,
|
|
contents: &str,
|
|
span: Option<Span>,
|
|
) -> Result<(), RuntimeError> {
|
|
self.write_bytes(user_path, contents.as_bytes(), span)
|
|
}
|
|
|
|
/// Write raw bytes inside the project root, creating parent directories.
|
|
///
|
|
/// This is a single validated write, not a transactional replace.
|
|
pub fn write_bytes(
|
|
&self,
|
|
user_path: &str,
|
|
bytes: &[u8],
|
|
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, bytes).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");
|
|
}
|
|
}
|