@ b4run/ 工作空间
B4. 运行代理工作空间的文件系统和 shell后端合同.
当 : 您正在向 B4 运行应用程序提供文件系统或 shell 后端、 中间软件或工作空间工具 .
安装
pnpm add @b4run/workspace
示例
import { compose, type FilesystemBackend, withFilesystemLogging } from "@b4run/workspace"
import { localFilesystem } from "@b4run/workspace/node"
const base: FilesystemBackend = localFilesystem({ maxFileBytes: 512 * 1024 })
const filesystem = compose(withFilesystemLogging())(base)
运行时间和稳定性
获取初始源
节点入口提供 captureWorkspaceSource, (中文(简体) ), createSourceBundle, (中文(简体) ),
verifySourceBundle,以及 readSourceFile 对于不可改变的源捆.
import { captureWorkspaceSource, readSourceFile } from "@b4run/workspace/node"
const source = await captureWorkspaceSource(appRoot, {
directory: "fixtures/demo",
include: ["index.ts", "package.json"],
files: [{ path: "TASK.md", text: "Repair the failing example.\n" }],
})
const original = readSourceFile(source, "index.ts")
路径解析相对 appRoot。 。 。 . include 确切的文件目录;
意外文件导致抓取失败 . excludeDirectories 可明确省略
已有目录子树, 如已安装的依赖 。 其他条目
能够声明 file 路径相对 appRoot 而不是内含 text。 。 。 .
抓取会保存二进制字节和可执行标记,拒绝符号链接和 模糊路径,并返回一个内容不可变的经过验证的文摘。 限制是 10 000个不同的文件系统路径(包括应用程序根和祖先) 目录),每个文件有16个米B,以及64个米B的总文件内容. 源路径 使用具有一致目录外壳的便携式ASCII子集.
抓取读取信任的应用程序树并拒绝在 读取; 这不是原子文件系统快照 。 它不会创造出一个沙盒, 注册运行时间配置,或提供工作空间生命周期恢复.
检查文本工作空间
inspectWorkspace 接受权限约束 ctx.fs 作者手柄, a
SandboxHandle,或任何 WorkspaceReadSource - 包括 SandboxWorkspaceReader
提供商的手从 openWorkspaceReader。它们都使用相同的有界限的横道
并需要叶元数据(stat 编号 : lstat)和原始二进制读取;缺少支持
未关闭 .
import { inspectWorkspace } from "@b4run/workspace"
const inventory = await inspectWorkspace(ctx.fs, {
signal: ctx.signal,
excludeRootDirectories: [".git"],
expectedRootSymlinks: { node_modules: "/opt/project/node_modules" },
})
// inventory.files: relative path → exact UTF-8 text (including a leading BOM)
// inventory.symlinks: validated root name → exact readlink target
默认为一万个条目,每个文件有2个米B,以及16个米B文件总字节;
maxEntries, (中文(简体) ), maxFileBytes,以及 maxTotalBytes 接受非负式安全整数.
目录和省略的根项数到条目限制; 工作空间
根本身没有。 限制检查报告大小和实际返回的字节.
结果还包括: entries 财务报告和审定财务报表 totalBytes。文件和链接记录
无效原型,所以文件名如下: __proto__ 仍然是普通键.
排除的根名可能缺失,但当存在时必须是目录. 预期 根链接是需要的,必须与其准确、非正常的目标相匹配。 他们 目标从不穿越。 嵌入式条目没有根排除. 所有其他 符号链接,非文件/非目录条目,可执行文件,无效的UTF-8和 含有NUL的二进制数据被拒绝. 叶名不能穿行目录 . 接受没有NUL的UTF-8文本;这不是一个文件格式的分类器.
读取另一个线程的工作空间
withWorkspaceReader(provider, { threadId, signal }, operation) 打开提供者的
对一个线程的工作空间存储的可选只读视图, 将其交给 operation, (中文(简体) ),
并在成功和失败的道路上关闭它。 读者不带文字
方法和没有命令后端,读取不会扰乱线程的活性
沙盒 openWorkspaceReader 可选于 SandboxProvider; 提供者
省略它制造出来的 withWorkspaceReader 而不是默默无声地还原.
这是已经信任的呼叫者的主机侧 API 。 这不是授权 边框,不是代理人可以调用的工具,也不是HTTP表面.
通过一个信号检查每个文件系统调用周围的取消; 沙盒后端
他们也会收到 BackendContext。作者手柄保留现有的
许可政策和取消行为。 帮助者无法中断
正在飞行中。 它使用无外壳和主机文件系统API.
视察不是原子快照,也不是新的隔离边界。 元数据, 列出,并读取单独的后端调用,并可以与并行的作者进行比赛; 写作时要经过考核 或重新鉴定 精确链接验证链接身份, 而不是其外部目标的内容。 后端读取必须尊重所提供的 返回数据前绑定分配的字节上限 .
支持的表面
@b4run/workspace是一个边缘安全、支持的应用程序表面.@b4run/workspace/node是一个唯一的节点,支持应用程序表面.
工作空间后端定义了运行地点;它们本身不是孤立的边界. 在未信任的执行必须离开主机进程时使用沙盒提供者.
相关
- 工作空间 API 参考 ——精确的后端,中件,以及工具合同.
- 工作空间文件系统 ——应用程序配置和后端行为.
@b4run/sandbox——工作空间操作隔离执行供应商.
成熟和支持
B4.run为1.0前置,其公用地表可以改变. 所有可公布的 B4. 运行包作为一个固定组一起发布; 审查 @b4run/workspace 更改日志 财务报告和审定财务报表 升级指南 升级前。 用于支持, 使用 GitHub 讨论; 报告缺陷 GitHub 问题。 。 。 .
许可证
麻省理工学院. 见 仓库许可证。 。 。 .