feat(fs): add append, read_at and recursive walk
This commit is contained in:
1 parent
7859c26213
commit
6338fa10e9
13 files changed
+479
-10
No files matched your search
@@ -202,8 +202,11 @@ fn fs_test_exercises_the_file_operation_surface() {
|
||||
assert_eq!(items[7]["value"], true);
|
||||
assert_eq!(items[8]["value"], true);
|
||||
assert_eq!(items[9]["value"], "你好\n");
|
||||
assert_eq!(items[10]["value"], true);
|
||||
assert_eq!(items[11]["value"], true);
|
||||
assert_eq!(items[10]["decimal"], "7");
|
||||
assert_eq!(items[11]["value"], "你好\n世界\n");
|
||||
assert_eq!(items[12]["items"][0]["value"], "fs-b.txt");
|
||||
assert_eq!(items[13]["value"], true);
|
||||
assert_eq!(items[14]["value"], true);
|
||||
assert!(
|
||||
!stdlib_dir().join("tests/out").exists(),
|
||||
"the fs test did not remove its directory"
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
//! symlink escapes outside the project root are rejected before the capability
|
||||
//! check, and the capability check happens before any I/O.
|
||||
|
||||
use std::io::{Read, Seek, SeekFrom, Write};
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
|
||||
use marqdo_span::Span;
|
||||
@@ -321,6 +322,131 @@ impl ProjectFs {
|
||||
}
|
||||
Ok(fs_ok(Value::None))
|
||||
}
|
||||
"append" => {
|
||||
if args.len() != 2 {
|
||||
return Err(fs_arity(operation, 2, args.len(), span));
|
||||
}
|
||||
let (absolute, relative) = self.resolve(&args[0], span)?;
|
||||
self.ensure_parent_inside(&absolute, &relative, span)?;
|
||||
let bytes = args[1].as_bytes();
|
||||
if bytes.len() > MAX_READ_BYTES as usize {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::ResourceExhausted,
|
||||
span,
|
||||
format!(
|
||||
"append to `{relative}` exceeds the {} byte limit",
|
||||
MAX_READ_BYTES
|
||||
),
|
||||
));
|
||||
}
|
||||
let mut file = std::fs::OpenOptions::new()
|
||||
.append(true)
|
||||
.create(true)
|
||||
.open(&absolute)
|
||||
.map_err(|error| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::HostError,
|
||||
span,
|
||||
format!("cannot append to `{relative}`: {error}"),
|
||||
)
|
||||
})?;
|
||||
file.write_all(bytes).map_err(|error| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::HostError,
|
||||
span,
|
||||
format!("cannot append to `{relative}`: {error}"),
|
||||
)
|
||||
})?;
|
||||
Ok(fs_ok(Value::int(bytes.len() as i64)))
|
||||
}
|
||||
"read_at" => {
|
||||
if args.len() != 3 {
|
||||
return Err(fs_arity(operation, 3, args.len(), span));
|
||||
}
|
||||
let (absolute, relative) = self.resolve(&args[0], span)?;
|
||||
let offset = parse_offset(&args[1], span)?;
|
||||
let length = parse_offset(&args[2], span)?;
|
||||
if length > MAX_READ_BYTES {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::ResourceExhausted,
|
||||
span,
|
||||
format!("read_at length exceeds the {} byte limit", MAX_READ_BYTES),
|
||||
));
|
||||
}
|
||||
let mut file = std::fs::File::open(&absolute).map_err(|error| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::HostError,
|
||||
span,
|
||||
format!("cannot read `{relative}`: {error}"),
|
||||
)
|
||||
})?;
|
||||
file.seek(SeekFrom::Start(offset)).map_err(|error| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::HostError,
|
||||
span,
|
||||
format!("cannot seek `{relative}`: {error}"),
|
||||
)
|
||||
})?;
|
||||
let mut buffer = Vec::new();
|
||||
file.take(length)
|
||||
.read_to_end(&mut buffer)
|
||||
.map_err(|error| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::HostError,
|
||||
span,
|
||||
format!("cannot read `{relative}`: {error}"),
|
||||
)
|
||||
})?;
|
||||
let text = String::from_utf8(buffer).map_err(|_| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::Type,
|
||||
span,
|
||||
format!("`{relative}` slice is not valid UTF-8"),
|
||||
)
|
||||
})?;
|
||||
Ok(fs_ok(Value::text(text)))
|
||||
}
|
||||
"walk" => {
|
||||
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 entries = Vec::new();
|
||||
walk_directory(&absolute, "", &mut entries, 0).map_err(|error| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::HostError,
|
||||
span,
|
||||
format!("cannot walk `{relative}`: {error}"),
|
||||
)
|
||||
})?;
|
||||
if entries.len() > 4096 {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::ResourceExhausted,
|
||||
span,
|
||||
"walk exceeds the 4096 entry limit",
|
||||
));
|
||||
}
|
||||
Ok(fs_ok(Value::List(
|
||||
entries.into_iter().map(Value::text).collect(),
|
||||
)))
|
||||
}
|
||||
"rename" => {
|
||||
if args.len() != 2 {
|
||||
return Err(fs_arity(operation, 2, args.len(), span));
|
||||
@@ -461,6 +587,50 @@ impl ProjectFs {
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_offset(raw: &str, span: Option<Span>) -> Result<u64, RuntimeError> {
|
||||
raw.parse::<u64>().map_err(|_| {
|
||||
RuntimeError::new(
|
||||
ErrorCategory::Type,
|
||||
span,
|
||||
format!("`{raw}` is not a non-negative integer offset"),
|
||||
)
|
||||
})
|
||||
}
|
||||
|
||||
fn walk_directory(
|
||||
dir: &Path,
|
||||
prefix: &str,
|
||||
out: &mut Vec<String>,
|
||||
depth: usize,
|
||||
) -> std::io::Result<()> {
|
||||
if depth > 64 {
|
||||
return Err(std::io::Error::new(
|
||||
std::io::ErrorKind::InvalidInput,
|
||||
"directory depth exceeds 64",
|
||||
));
|
||||
}
|
||||
let mut entries = std::fs::read_dir(dir)?.collect::<Result<Vec<_>, _>>()?;
|
||||
entries.sort_by_key(|entry| entry.file_name());
|
||||
for entry in entries {
|
||||
let file_type = entry.file_type()?;
|
||||
if file_type.is_symlink() {
|
||||
continue;
|
||||
}
|
||||
let name = entry.file_name().to_string_lossy().to_string();
|
||||
let relative = if prefix.is_empty() {
|
||||
name.clone()
|
||||
} else {
|
||||
format!("{prefix}/{name}")
|
||||
};
|
||||
if file_type.is_dir() {
|
||||
walk_directory(&entry.path(), &relative, out, depth + 1)?;
|
||||
} else {
|
||||
out.push(relative);
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn invalid_path(span: Option<Span>, message: impl Into<String>) -> RuntimeError {
|
||||
RuntimeError::new(ErrorCategory::PermissionDenied, span, message)
|
||||
}
|
||||
|
||||
@@ -879,6 +879,123 @@ impl Host for StdHost {
|
||||
format!("unsupported resource operation `{operation}`"),
|
||||
));
|
||||
};
|
||||
if name == "read_at" {
|
||||
if args.len() != 3 {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::Arity,
|
||||
ctx.span,
|
||||
format!(
|
||||
"resource operation `fs.read_at` expects 3 arguments, got {}",
|
||||
args.len()
|
||||
),
|
||||
));
|
||||
}
|
||||
let path_type = args[0].type_name();
|
||||
let Value::Text(path) = args[0].clone() else {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("fs.read_at path must be Text, got {path_type}"),
|
||||
));
|
||||
};
|
||||
let offset = match &args[1] {
|
||||
Value::Int(value) => value.to_string(),
|
||||
other => {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("fs.read_at offset must be Int, got {}", other.type_name()),
|
||||
))
|
||||
}
|
||||
};
|
||||
let length = match &args[2] {
|
||||
Value::Int(value) => value.to_string(),
|
||||
other => {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("fs.read_at length must be Int, got {}", other.type_name()),
|
||||
))
|
||||
}
|
||||
};
|
||||
self.capabilities.check_read(&path, ctx.span)?;
|
||||
let result = self
|
||||
.fs
|
||||
.request("read_at", &[path, offset, length], ctx.span)?;
|
||||
self.record_semantic(
|
||||
"resource.request",
|
||||
None,
|
||||
Some(&ctx.module_id),
|
||||
ctx.span,
|
||||
Some("op=fs.read_at"),
|
||||
);
|
||||
self.record_resource_effect("resource.request", ctx, started, "fs.read_at");
|
||||
return Ok(result);
|
||||
}
|
||||
if name == "append" {
|
||||
if args.len() != 2 {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::Arity,
|
||||
ctx.span,
|
||||
format!(
|
||||
"resource operation `fs.append` expects 2 arguments, got {}",
|
||||
args.len()
|
||||
),
|
||||
));
|
||||
}
|
||||
let path_type = args[0].type_name();
|
||||
let Value::Text(path) = args[0].clone() else {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("fs.append path must be Text, got {path_type}"),
|
||||
));
|
||||
};
|
||||
let text_type = args[1].type_name();
|
||||
let Value::Text(text) = args[1].clone() else {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("fs.append text must be Text, got {text_type}"),
|
||||
));
|
||||
};
|
||||
self.capabilities.check_write(&path, ctx.span)?;
|
||||
let result = self.fs.request("append", &[path, text], ctx.span)?;
|
||||
self.record_semantic(
|
||||
"resource.request",
|
||||
None,
|
||||
Some(&ctx.module_id),
|
||||
ctx.span,
|
||||
Some("op=fs.append"),
|
||||
);
|
||||
self.record_resource_effect("resource.request", ctx, started, "fs.append");
|
||||
return Ok(result);
|
||||
}
|
||||
if name == "walk" {
|
||||
if args.len() != 1 {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::Arity,
|
||||
ctx.span,
|
||||
format!(
|
||||
"resource operation `fs.walk` expects 1 argument, got {}",
|
||||
args.len()
|
||||
),
|
||||
));
|
||||
}
|
||||
let path_type = args[0].type_name();
|
||||
let Value::Text(path) = args[0].clone() else {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("fs.walk path must be Text, got {path_type}"),
|
||||
));
|
||||
};
|
||||
self.capabilities.check_read(&path, ctx.span)?;
|
||||
let result = self.fs.request("walk", &[path], ctx.span)?;
|
||||
self.record_semantic(
|
||||
"resource.request",
|
||||
None,
|
||||
Some(&ctx.module_id),
|
||||
ctx.span,
|
||||
Some("op=fs.walk"),
|
||||
);
|
||||
self.record_resource_effect("resource.request", ctx, started, "fs.walk");
|
||||
return Ok(result);
|
||||
}
|
||||
let expected = match name {
|
||||
"exists" | "metadata" | "list" | "mkdir" | "remove" => 1,
|
||||
"rename" => 2,
|
||||
|
||||
@@ -744,3 +744,54 @@ fn process_run_requires_an_exact_program_grant() {
|
||||
.unwrap_err();
|
||||
assert_eq!(missing.category, ErrorCategory::PermissionDenied);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fs_append_read_at_and_walk_are_bounded() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let capabilities = Capabilities::project()
|
||||
.allow_read("out")
|
||||
.allow_read("out/**")
|
||||
.allow_write("out")
|
||||
.allow_write("out/**");
|
||||
let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path());
|
||||
let ctx = context();
|
||||
host.resource_request("fs.mkdir", vec![Value::text("out")], &ctx)
|
||||
.unwrap();
|
||||
let appended = host
|
||||
.resource_request(
|
||||
"fs.append",
|
||||
vec![Value::text("out/data.txt"), Value::text("hello")],
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(field(&appended, "value"), &Value::int(5));
|
||||
host.resource_request(
|
||||
"fs.append",
|
||||
vec![Value::text("out/data.txt"), Value::text(" world")],
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
let slice = host
|
||||
.resource_request(
|
||||
"fs.read_at",
|
||||
vec![Value::text("out/data.txt"), Value::int(6), Value::int(5)],
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(field(&slice, "value"), &Value::text("world"));
|
||||
let walked = host
|
||||
.resource_request("fs.walk", vec![Value::text("out")], &ctx)
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
field(&walked, "value"),
|
||||
&Value::List(vec![Value::text("data.txt")])
|
||||
);
|
||||
let error = host
|
||||
.resource_request(
|
||||
"fs.read_at",
|
||||
vec![Value::text("out/data.txt"), Value::int(-1), Value::int(1)],
|
||||
&ctx,
|
||||
)
|
||||
.unwrap_err();
|
||||
assert_eq!(error.category, ErrorCategory::Type);
|
||||
}
|
||||
+4
-3
@@ -58,7 +58,7 @@ byte-identical).
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace --locked PASS
|
||||
478 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
|
||||
479 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
|
||||
```
|
||||
|
||||
The documentation and test migration is local work; re-run this block after it
|
||||
@@ -200,13 +200,14 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
`Value::Table`; inputs are never mutated; GFM AST laziness and physical T0
|
||||
storage are unchanged. `std:fs/file` provides bounded `读文本`/`写文本`/`复制文件`
|
||||
over the existing `resource.*` ABI plus `存在`/`元数据`/`列出目录`/`创建目录`/
|
||||
`删除`/`重命名` over `resource.request` (ADR-0041); `data/json`/`data/csv`
|
||||
`删除`/`重命名`/`追加文本`/`读取片段`/`遍历` over `resource.request`
|
||||
(ADR-0041/0045); `data/json`/`data/csv`
|
||||
provide recursive JSON and quoted single-row CSV product parsers; `path` and a
|
||||
`regex` subset are pure `.mq.md`; `datetime` is pure UTC ISO-8601 and
|
||||
`clock.现在` reads `clock.now` in project mode (ADR-0042); `env.读取` reads
|
||||
only exact `--allow-env NAME` grants in project mode (ADR-0043); `process.运行`
|
||||
runs an exact `--allow-process PROGRAM` grant with 5 s timeout and 1 MiB caps
|
||||
(ADR-0044, not an OS sandbox). Append/seek/watch, recursive walk, streaming
|
||||
(ADR-0044, not an OS sandbox). File watch, binary offset reads, streaming
|
||||
JSON/CSV, a JSON depth bound, regex groups/alternation, secure random and
|
||||
compression remain open.
|
||||
- Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
# ADR-0045: `fs.append`, `fs.read_at` and `fs.walk`
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-21
|
||||
Relates to: ADR-0041
|
||||
Specs: `spec/evaluation.md`
|
||||
Evidence: `docs/evidence/2026-11-21-fs-extended.md`
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0041 added metadata/directory operations, but file content still required
|
||||
a whole-file `resource.open` read and a whole-buffer write. That leaves append,
|
||||
offset reads and recursive directory discovery unavailable to `.mq.md` without
|
||||
adding Rust algorithms to the standard library.
|
||||
|
||||
## Decision
|
||||
|
||||
Extend the existing `fs.*` group of `resource.request`:
|
||||
|
||||
```text
|
||||
resource.request("fs.append", [path, text]) -> {ok:true, value:count}
|
||||
resource.request("fs.read_at", [path, offset, len])-> {ok:true, value:Text}
|
||||
resource.request("fs.walk", [dir]) -> {ok:true, value:List<Text>}
|
||||
```
|
||||
|
||||
* `fs.append` writes UTF-8 text to the end of a project file, creating it when
|
||||
missing. It requires `fs_write`, is bounded by the existing 8 MiB file limit,
|
||||
and never bypasses the path policy.
|
||||
* `fs.read_at` reads at most `len` bytes from `offset` and returns Text. Both
|
||||
values are non-negative integers; `len` is capped at 8 MiB. Invalid UTF-8 is
|
||||
a fatal type error, not silent loss.
|
||||
* `fs.walk` recursively lists regular files under a directory, relative to the
|
||||
project root. It requires `fs_read`, skips symlinks, has a depth limit of 64
|
||||
and a 4096-entry limit. The list is sorted by name at each level.
|
||||
* All three are project-mode only, use the same path/grant checks as the other
|
||||
`fs.*` operations, and record one `resource.request` effect event.
|
||||
* No new builtin or host trait method is added; the operation strings extend
|
||||
the existing ABI.
|
||||
|
||||
## Consequences
|
||||
|
||||
* `std:fs/file` exposes `追加文本`, `读取片段` and `遍历` in `.mq.md`.
|
||||
* Binary offset reads, append handles and filesystem watch remain open; a
|
||||
watch API needs a separate event model and ADR.
|
||||
* The operations allocate at most the existing 8 MiB read limit; `walk` is
|
||||
metadata-only and returns names, not contents.
|
||||
@@ -90,7 +90,7 @@ review RFC, not a new crate per provider.
|
||||
| stdio stderr | `resource.open("stdio","stderr",["write"])`; separate from stdout and CLI diagnostics | implemented | `resource_streams`, `stdlib_product` |
|
||||
| project file read | `resource.open("file", path, ["read"])`; path/grant checked; bounded | implemented, project mode | `resource_streams`, `stdlib_product` |
|
||||
| project file write | `resource.open("file", path, ["write"])`; buffers until `close`, never flush-on-drop | implemented, project mode | `resource_streams`, `stdlib_product` |
|
||||
| `std:fs/file` | `fs.读文本`, `fs.写文本`, `fs.复制文件` over `resource.open/read/write/close` and `Memory`; bounded at 8 MiB | implemented (read/write/copy) | `stdlib_product` |
|
||||
| `std:fs/file` | `读文本/写文本/复制文件/存在/元数据/列出目录/创建目录/删除/重命名/追加文本/读取片段/遍历` over `resource.*`; bounded at 8 MiB | implemented; no watch/binary offset read | `stdlib_product` |
|
||||
| `resource.request` | `resource.request("fs.exists|metadata|list|mkdir|remove|rename", paths)`; project mode, grant-checked, recoverable fs Result | implemented `fs.*`; no seek/append/watch | `resource_streams`, `stdlib_product` |
|
||||
| `std:data/json` | `json.解析(文本)` -> Result with nested Value; `json.格式化(值)` -> Text | implemented (recursive, recoverable errors) | `stdlib_product` |
|
||||
| `std:data/csv` | `csv.解析行(文本)` -> Result with List<Text>; `csv.格式化行(列表)` -> Text | implemented (single row, quoted) | `stdlib_product` |
|
||||
@@ -125,8 +125,8 @@ that a phase is complete.
|
||||
|---|---|---|
|
||||
| P0 | Stdlib release is a bundle in this repo; extraction is deferred (ADR-0039) | accepted, keep in repo |
|
||||
| P0 | Documentation drift between `STATUS.md`, the architecture index and the evidence | being fixed by this migration and the docs gate |
|
||||
| P1 | `std:fs/file` read/write/copy and `resource.request` fs metadata/directory operations are implemented; append/seek/watch/recursive walk remain open | open |
|
||||
| P1 | No file append/seek/watch/recursive directory walk | open; future Resource Operation extension |
|
||||
| P1 | `std:fs/file` read/write/copy, metadata/directory, append/read_at/walk are implemented; watch and binary offset reads remain open | open |
|
||||
| P1 | No file watch or binary `read_at` | open; future Resource Operation extension |
|
||||
| P1 | JSON/CSV product parsers are implemented; no streaming/multi-line CSV or depth-bounded JSON walker | open |
|
||||
| P1 | CLI split into `commands/{sandbox,run,check,inspect,init,package,tool}.rs`; host split into `host/{resource_ops,providers,effects,dispatch}.rs` plus `process.rs`; `commands.rs` keeps shared project/runtime helpers and `host.rs` keeps the `Host` trait methods and capability checks | split; shared helpers and trait methods remain by design |
|
||||
| P2 | HTTP parsing is Unicode-codepoint oriented; a general byte body is not the only path | open; convert before a general network release |
|
||||
@@ -165,5 +165,6 @@ that a phase is complete.
|
||||
- [ADR-0042: `clock.now` resource operation](../adr/0042-clock-resource-operation.md) — accepted project-mode Unix-millis clock.
|
||||
- [ADR-0043: `env.get` resource operation](../adr/0043-env-resource-operation.md) — accepted exact-name environment grants.
|
||||
- [ADR-0044: `process.run` resource operation](../adr/0044-process-resource-operation.md) — accepted exact-path process grant; not a sandbox.
|
||||
- [ADR-0045: fs append/read_at/walk](../adr/0045-fs-append-read-at-walk.md) — accepted bounded content and directory walk.
|
||||
- [Compute-machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) and [core/stdlib RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) — design input.
|
||||
- [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) — review input for this migration.
|
||||
@@ -49,6 +49,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and
|
||||
| `clock.now` resource operation | [0042](../adr/0042-clock-resource-operation.md) | Accepted (project mode, Unix millis) |
|
||||
| `env.get` resource operation | [0043](../adr/0043-env-resource-operation.md) | Accepted (exact-name project grant) |
|
||||
| `process.run` resource operation | [0044](../adr/0044-process-resource-operation.md) | Accepted (exact program grant, project only, not a sandbox) |
|
||||
| `fs.append`/`fs.read_at`/`fs.walk` | [0045](../adr/0045-fs-append-read-at-walk.md) | Accepted (bounded content, directory walk) |
|
||||
| Table physical storage (T1/T2/T3), strict stdin/stderr/file/network resources | — | **Not decided**; do not implement by implication |
|
||||
|
||||
## Evidence and status
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# Evidence: `fs.append`, `fs.read_at` and `fs.walk`
|
||||
|
||||
Date: 2026-11-21 (Asia/Shanghai)
|
||||
Source baseline: `7859c26213bda30b34a5379a4ab1f75430967494`
|
||||
Repository: `marqdo-cli`
|
||||
Decision record: [ADR-0045](../adr/0045-fs-append-read-at-walk.md)
|
||||
|
||||
## Implemented
|
||||
|
||||
`resource.request` now supports:
|
||||
|
||||
- `fs.append(path, text)` -> `{ok:true, value:count}`; creates the file,
|
||||
requires `fs_write`, 8 MiB cap.
|
||||
- `fs.read_at(path, offset, length)` -> `{ok:true, value:Text}`; non-negative
|
||||
integers, 8 MiB cap, invalid UTF-8 is fatal.
|
||||
- `fs.walk(dir)` -> `{ok:true, value:List<Text>}`; recursive regular files,
|
||||
skips symlinks, depth 64, 4096-entry cap.
|
||||
|
||||
`std:fs/file` exposes `追加文本`, `读取片段`, `遍历`.
|
||||
|
||||
## Tests
|
||||
|
||||
`stdlib/tests/fs.mq.md` appends, reads a slice and walks the output directory;
|
||||
`crates/marqdo-host/tests/resource_streams.rs` pins host behavior and the
|
||||
negative-offset type error.
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace 479 passed, 0 failed, 2 ignored
|
||||
cargo test -p marqdo-host --test resource_streams 24 passed
|
||||
cargo test -p marqdo-cli --test stdlib_product 14 passed
|
||||
python3 tools/pack-stdlib.py PASS
|
||||
```
|
||||
|
||||
## Not covered
|
||||
|
||||
No file watch, no binary offset read into `Memory`, no seek/resume handle, no
|
||||
write-at-offset, no recursive delete and no symlink traversal.
|
||||
@@ -205,6 +205,9 @@ resource.request("fs.list", [path]) -> {ok:true, value:List<Text>}
|
||||
resource.request("fs.mkdir", [path]) -> {ok:true, value:None}
|
||||
resource.request("fs.remove", [path]) -> {ok:true, value:None}
|
||||
resource.request("fs.rename", [from, to]) -> {ok:true, value:None}
|
||||
resource.request("fs.append", [path, text]) -> {ok:true, value:count}
|
||||
resource.request("fs.read_at", [path, offset, len]) -> {ok:true, value:Text}
|
||||
resource.request("fs.walk", [dir]) -> {ok:true, value:List<Text>}
|
||||
resource.request("clock.now", []) -> {ok:true, value:UnixMillis}
|
||||
resource.request("env.get", [name]) -> {ok:true, value:Text}
|
||||
resource.request("process.run", [program, args])-> {ok:true, value:{status, stdout, stderr}}
|
||||
@@ -224,6 +227,10 @@ resource.request("process.run", [program, args])-> {ok:true, value:{status, stdo
|
||||
(`remove` on a non-empty directory). Unknown operations, traversal,
|
||||
capability denial and I/O failures stay fatal.
|
||||
* `remove` never recurses; `rename` never overwrites; `mkdir` is single-level.
|
||||
* `append` writes UTF-8 text to the end of a file (creating it) and returns the
|
||||
written count; `read_at` returns at most `len` bytes from `offset` as Text;
|
||||
`walk` recursively lists regular files under a directory, skipping symlinks,
|
||||
with depth 64 / 4096-entry limits (ADR-0045).
|
||||
* The operation never moves file bytes. Content still uses
|
||||
`resource.open/read/write/close`.
|
||||
* `clock.now` takes no arguments and returns UTC Unix milliseconds. It is
|
||||
|
||||
@@ -177,3 +177,30 @@ import:
|
||||
目标已存在时返回 `fs.exists`,不覆盖。
|
||||
|
||||
*resource.request("fs.rename", [源, 目标])*
|
||||
|
||||
## 追加文本
|
||||
|
||||
`(路径, 文本)`
|
||||
|
||||
把文本追加到项目文件;文件不存在时创建。仍受 8 MiB 单次读取上限和
|
||||
`fs_write` 授权约束。
|
||||
|
||||
*resource.request("fs.append", [路径, 文本])*
|
||||
|
||||
## 读取片段
|
||||
|
||||
`(路径, 偏移, 长度)`
|
||||
|
||||
从偏移处读取最多 `长度` 字节,按 UTF-8 解码后返回文本。偏移/长度必须
|
||||
是非负整数,长度上限 8 MiB。
|
||||
|
||||
*resource.request("fs.read_at", [路径, 偏移, 长度])*
|
||||
|
||||
## 遍历
|
||||
|
||||
`(路径)`
|
||||
|
||||
递归列出目录下的普通文件,返回相对项目根的路径列表。跳过符号链接,
|
||||
深度上限 64,条目上限 4096。
|
||||
|
||||
*resource.request("fs.walk", [路径])*
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "marqdo-stdlib",
|
||||
"version": "0.1.0",
|
||||
"digest": "sha256:c7208520e3eef1fdc98327055092f9d52081851f652dd970d4f602e30e58e75f"
|
||||
"digest": "sha256:6974496a9826f977189804bae0959e494bfc7443543ed4afffcea1ac390b0ce9"
|
||||
}
|
||||
@@ -23,8 +23,14 @@ import:
|
||||
|
||||
**读取 = fs.读文本("out/fs-b.txt")**
|
||||
|
||||
**追加 = fs.追加文本("out/fs-b.txt", "世界\n")**
|
||||
|
||||
**片段 = fs.读取片段("out/fs-b.txt", 0, 100)**
|
||||
|
||||
**遍历 = fs.遍历("out")**
|
||||
|
||||
**删除 = fs.删除("out/fs-b.txt")**
|
||||
|
||||
**删除目录 = fs.删除("out")**
|
||||
|
||||
*[创建.ok, 写入.value.count, 存在.value, 元数据.value.kind, 元数据.value.size, 列表.value, 是文件.value, 是目录.value, 重命名.ok, 读取.value, 删除.ok, 删除目录.ok]*
|
||||
*[创建.ok, 写入.value.count, 存在.value, 元数据.value.kind, 元数据.value.size, 列表.value, 是文件.value, 是目录.value, 重命名.ok, 读取.value, 追加.value, 片段.value, 遍历.value, 删除.ok, 删除目录.ok]*
|
||||
Reference in new issue
Block a user