A3S Box
  • 简体中文

      • Rust SDK

      a3s-box-sdk 直接调用 A3S Box 运行时组件，不会启动 CLI。它适合需要类型化本地状态 和生命周期操作的 Rust 管理应用。

      安装

      安装匹配版本的 A3S Box 运行时，然后添加 crate：

      cargo add a3s-box-sdk

      创建 Sandbox

      下面是完整的异步程序：

      use a3s_box_sdk::Sandbox;

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let sandbox = Sandbox::create("python:3.12-alpine").await?;

    let result = sandbox
        .commands
        .run("python -c 'print(6 * 7)'")
        .await?;
    println!("{}", result.stdout);

    sandbox
        .files
        .write("/workspace/note.txt", "hello")
        .await?;
    println!(
        "{}",
        sandbox.files.read_text("/workspace/note.txt").await?
    );

    sandbox.kill().await?;
    Ok(())
}

      MicroVM 是默认隔离。在经过认证的 Linux 主机上显式选择共享内核 Sandbox：

      use a3s_box_sdk::{ExecutionIsolation, Sandbox, SandboxCreateOptions};

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let sandbox = Sandbox::create_with_options(
        SandboxCreateOptions::new("alpine:3.20")
            .isolation(ExecutionIsolation::Sandbox)
            .cpus(2)
            .memory_mb(1024),
    )
    .await?;

    let result = sandbox.commands.run("id").await?;
    println!("{}", result.stdout);

    sandbox.kill().await?;
    Ok(())
}

      在 Box 内构建和测试

      下面的完整程序从 ./ci/Dockerfile 构建镜像、启动 Sandbox 并运行测试：

      use a3s_box_sdk::A3sBoxClient;

#[tokio::main]
async fn main() -> Result<(), a3s_box_sdk::ClientError> {
    let client = A3sBoxClient::new();
    let image = client
        .image("./ci")
        .dockerfile("Dockerfile")
        .tag("local/rust-ci:latest")
        .build_arg("RUST_VERSION", "stable")
        .build()
        .await?;

    let sandbox = client
        .sandbox(image.reference)
        .cpus(4)
        .memory_mb(4096)
        .workdir("/workspace")
        .start()
        .await?;

    let result = sandbox
        .script("cargo test --all-targets\n")
        .interpreter(["/bin/sh", "-se"])
        .env("CI", "true")
        .run()
        .await?;

    sandbox.kill().await?;
    if result.exit_code != 0 {
        return Err(a3s_box_sdk::ClientError::Guest(result.stderr));
    }

    Ok(())
}

      脚本通过标准输入传给所选客体解释器，不会插值到主机 shell 命令。

      低层管理

      A3sBoxClient 提供类型化镜像、卷、网络、盒子、快照、日志、统计、诊断和磁盘占用 操作。测试需要隔离状态目录时使用 A3sBoxClient::from_home(path)。

      生命周期请求与 CLI 共用同一个代际围栏执行管理器。SDK 不会创建第二条记录，也不会 通过抓取进程文本推断状态。

      错误处理

      在应用边界返回带上下文的 ClientError，不要对生产运行时错误执行 panic。主机准入、 镜像解析、客体退出和陈旧代冲突都属于预期的操作错误。

      完整说明见 crate 指南和 API 参考。