#MoonBit WASI 增强库

#特性

• 🛡️ 安全路径：GuestPath 规范化 guest 相对路径，拒绝绝对路径、NUL、反斜杠和 越过 capability 根的父级跳转
• 📁 增强文件系统：支持完整读写、追加、seek/tell、metadata、目录遍历、复制、 rename、硬链接和符号链接
• ⚛️ 原子写入：使用同目录 exclusive 临时文件、完整同步和 rename，失败时自动清理
• 🔒 Capability 模型：只访问 WASI 运行时显式预开放的目录，不接触或推导宿主路径
• 🧭 确定性遍历：分页读取大目录，并以稳定词法顺序返回目录项和深度优先遍历结果
• 🧰 系统能力：封装参数、环境变量、stdio、时钟、睡眠、安全随机数和 descriptor poll
• 🧩 上下文错误：统一保留操作名、guest 路径和原始 WASI Errno
• ✅ 端到端验证：同时提供 MoonBit 单元测试和真实 Wasmtime 集成测试

#Demo

MoonBit WASI diagnostics
arguments: ["main.wasm"]
environment entries: 0
preopens: [{ guest_path: ".", fd: 3 }]
monotonic nanoseconds: 594900
random sample: <Bytes: [...]>

wrote target/moon-wasi-example/demo.txt: enabled=true

target/moon-wasi-example
  demo.txt

#快速开始

#安装依赖

• MoonBit 工具链
• 支持 wasi_snapshot_preview1 的运行时，示例使用 Wasmtime

moon install
moon check --deny-warn

moon add Ag108/moon-wasi

#配置包

import {
  "Ag108/moon-wasi/fs" @wasi_fs,
  "Ag108/moon-wasi/path",
  "Ag108/moon-wasi/sys" @wasi_sys,
  "moonbitlang/core/debug",
}

pkgtype(kind: "executable")
supported_targets = "wasm"

#运行项目

moon build --target wasm --release examples/atomic-config
wasmtime run --dir .::. \
  _build/wasm/release/build/examples/atomic-config/atomic-config.wasm \
  target/moon-wasi-example/config.txt "enabled=true"

moon build --target wasm --release cmd/main
wasmtime run --dir .::. _build/wasm/release/build/cmd/main/main.wasm

moon build --target wasm --release examples/tree
wasmtime run --dir .::. \
  _build/wasm/release/build/examples/tree/tree.wasm target

#使用方法

1. 使用 GuestPath::new 验证来自参数、环境变量或配置的 guest 路径
2. 使用 create_dir_all 创建父目录
3. 调用 read_text、write_text、copy_tree 或 atomic_write_text 等高层 API
4. 捕获 WasiError，记录操作、guest 路径和底层 errno
5. 启动 wasm 时只预开放应用实际需要的宿主目录

///|
fn main {
  try {
    let path = @path.GuestPath::new("state/config.txt")
    match path.parent() {
      Some(parent) => @wasi_fs.create_dir_all(parent)
      None => ()
    }
    @wasi_fs.atomic_write_text(path, "enabled=true\n")
    @wasi_sys.print(@wasi_fs.read_text(path))
  } catch {
    error => {
      @wasi_sys.eprint("failed: \{@debug.to_string(error)}\n") catch {
        _ => ()
      }
      @wasi_sys.exit(1)
    }
  }
}

#技术架构

#核心依赖库

#包结构

#实现原理

1. 路径验证：在进入 capability 敏感 API 前完成纯词法规范化和越界检查
2. Capability 解析：将 guest 路径解析为预开放 descriptor 与相对路径
3. 可靠 I/O：循环处理部分读写，并在高层操作的成功和失败路径关闭自建 descriptor
4. 目录遍历：通过 fd_readdir cookie 分页读取，再按名称稳定排序
5. 复制保护：使用 device/inode 识别硬链接别名，避免把文件复制到自身导致截断
6. 原子发布：先写入 exclusive 临时文件并同步，再 rename；无覆盖创建使用硬链接
7. 系统封装：将 process、clock、random 和 poll_oneoff 转换为 MoonBit 类型与错误

#错误和资源所有权

#配置

#目录 Capability

# 将当前宿主目录映射为 guest 的相对根目录“.”
wasmtime run --dir .::. app.wasm

# 同时传入环境变量
wasmtime run --dir .::. --env APP_MODE=production app.wasm

#测试运行时

MOON_WASI_WASMTIME=/path/to/wasmtime bash scripts/test-wasi.sh

#开发

#项目结构

.
├── cmd/main/                 # WASI 系统能力诊断程序
├── path/                     # 安全 guest 路径
├── fs/                       # 文件系统增强层
├── sys/                      # 进程与系统能力
├── integration/fs/           # Wasmtime 文件系统集成测试
├── integration/sys/          # Wasmtime 系统能力集成测试
├── examples/tree/            # 确定性目录树示例
├── examples/atomic-config/   # 原子配置写入示例
├── docs/                     # 架构与兼容性说明
├── scripts/test-wasi.sh      # 本地完整验收入口
├── moon.mod                  # 模块元数据和依赖
└── README.mbt.md

#代码特点

• 块式组织：MoonBit block 使用 ///| 分隔，方便独立审查和重构
• 类型安全：公开文件系统边界接受 GuestPath，而不是未经验证的宿主字符串
• 稳定输出：目录结果不依赖宿主 readdir 顺序
• 失败清理：descriptor 和原子临时文件覆盖成功与异常退出路径
• 显式策略：目录复制不隐式跟随符号链接，避免循环和 capability 意外
• 接口审计：提交生成的 .mbti 文件，用于追踪所有公开 API 变化

#测试

bash scripts/test-wasi.sh

moon info
moon fmt
moon check --deny-warn
moon test --target wasm
moon package --frozen --list

#兼容性

• 不提供网络、通用异步运行时、Preview 2/3 或宿主路径访问
• atomic_write 无法通过 Preview 1 可移植地同步父目录，掉电语义受宿主文件系统影响
• atomic_write(..., replace=false) 依赖宿主授予 path_link capability
• copy_tree 不会隐式复制或跟随符号链接
• Windows 创建符号链接可能需要开发者模式、管理员权限或额外宿主支持

#项目文档

• 项目方案
• 架构说明
• 安全说明
• 兼容性说明
• 变更记录
• 第三方声明
• AI 辅助开发说明

#许可证

#贡献