Sandbox 项目技术文档

1. 安装指南

1.1 使用 npm 安装

要安装 sandbox 项目，可以使用 npm 进行安装：

npm install --save sandbox

1.2 跳过二进制文件下载

默认情况下，安装过程中会尝试下载对应平台的二进制文件。如果你希望跳过这一步骤，可以通过设置环境变量 SANDBOX_SKIP_DOWNLOAD 来实现：

env SANDBOX_SKIP_DOWNLOAD=1 npm install --save sandbox

1.3 手动构建

如果你选择手动构建项目，首先需要确保已经安装了 Rust 工具链。可以通过以下步骤安装 Rust：

1. 访问 Rust 安装页面 并按照说明进行安装。
2. 安装完成后，运行以下命令进行构建：

npm run build

构建完成后，编译的二进制文件将被移动到 ./index.node，此时你可以使用 sandbox 并运行测试：

npm test

2. 项目使用说明

2.1 基本用法

sandbox 是一个用于在 Node.js 中安全执行不受信任代码的工具。以下是一个简单的使用示例：

const s = new Sandbox();

s.eval("const o = { answer: 4.2 }; o", function(err, res) {
  console.log("The answer is: %d", res.answer * 10); // The answer is: 42
});

2.2 注意事项

• 目前，只有可以序列化为 JSON 的值才能被返回。
• 项目通过嵌入一个 JavaScript 解释器来执行代码，该解释器运行在另一个线程中，从而提高了安全性。

3. 项目 API 使用文档

3.1 Sandbox 类

3.1.1 eval(code, callback)

• 参数:
  • code (String): 要执行的 JavaScript 代码。
  • callback (Function): 执行完成后的回调函数，接收两个参数：err 和 res。
• 返回值: 无

示例:

s.eval("const o = { answer: 4.2 }; o", function(err, res) {
  if (err) {
    console.error(err);
  } else {
    console.log("The answer is: %d", res.answer * 10);
  }
});

3.2 错误处理

在执行不受信任的代码时，可能会遇到各种错误。sandbox 提供了优雅的错误处理机制，确保在发生错误时能够及时捕获并处理。

4. 项目安装方式

4.1 自动下载二进制文件

默认情况下，sandbox 会尝试下载对应平台的二进制文件。这是最简单的安装方式，适合大多数用户。

4.2 手动构建

对于需要自定义构建的用户，可以通过以下步骤手动构建项目：

1. 安装 Rust 工具链。
2. 运行 npm run build 进行构建。
3. 构建完成后，编译的二进制文件将被移动到 ./index.node。

4.3 环境变量控制

通过设置 SANDBOX_SKIP_DOWNLOAD 环境变量，可以跳过二进制文件的自动下载，选择手动构建或使用其他方式。

5. 总结

sandbox 项目通过嵌入 JavaScript 解释器和 Rust 语言的强大功能，提供了一个安全、可靠的执行环境，适用于需要执行不受信任代码的场景。通过本技术文档，用户可以轻松了解如何安装、使用和构建该项目，从而更好地利用 sandbox 的功能。