Rust SDK

安装

调用是阻塞式的，返回 Result；选项是链式的 …Options；时长为 Duration，时间为 SystemTime；API 的 null 对应 Option。四个依赖（serde_json、带 ring 的 rustls、webpki-roots、libc），不需要异步运行时。crates.io 上的 crate 名是 glac：

[dependencies]
glac = "0.1"

客户端及其产品

use glac::{AppOptions, DriveOptions};

let client = glac::Client::new()?; // GLAC_API_KEY and GLAC_API_URL; another address or key: Client::builder()

let app = client.cube().deploy("ghcr.io/acme/api:1.4", &AppOptions::new().name("api").port(8080))?; // Cube: waits until it serves
println!("{:?}", app.url());

let sbx = client.sandboxes().create()?; // Sandbox
println!("{}", sbx.run("python3 -c 'print(6*7)'")?.stdout);

let drive = client.drives().create_with(&DriveOptions::new().size_bytes(1 << 30))?; // Drive

println!("{}", glac::run("echo hello")?.stdout); // the shorthand: a sandbox for one command, on the client the environment describes

每个产品都是客户端的一个命名空间，即借用客户端的一个轻量句柄：

• client.cube()：方块，作为服务运行的镜像，API 称之为应用。类型沿用 API 的名称：App、AppOptions、Version、Instance。client.workers() 是它的另一个名字，已标记为弃用。
• client.sandboxes()：沙箱，以及它们的快照 (.snapshots()) 和能打开它们的 SSH 密钥 (.ssh_keys())。
• client.drives()：云盘，项目的磁盘，不随沙箱消失，同一时间由一个沙箱以读写方式挂载（Drive、DriveOptions、DriveMount），以及它们的快照（DriveSnapshot、DriveSnapshotOptions、DriveForkOptions）；client.volumes()，云盘底层的存储卷（Volume、VolumeOptions、VolumeMount）；client.backups()，存储卷的备份（Backup、BackupOptions），属于控制平面。
• client.domains()：项目的自定义域名（Domain、DomainOptions），即应用或沙箱某个端口的名称；属于控制平面。
• client.webhooks() 和 client.keys()：项目的事件发往哪里（Webhook、WebhookOptions），以及项目的 API 密钥（ProjectKey、KeyOptions）；属于控制平面。
• client.destinations()：项目中应用的日志、指标和追踪导出到哪里（Destination、DestinationOptions）；属于控制平面。
• client.secrets() 和 client.variables()：项目的机密和共享变量。
• client.deploys()：项目的部署（/v1/deploys，属于控制平面）：多个服务一起部署，按各自等待的对象排序，并一起切换（项目部署）。create([("api", DeployOptions::new().image("ghcr.io/acme/api:2")), ("web", DeployOptions::new())]) 给每个服务单独部署时接受的内容，并等待部署完成，跟随取代它的部署；失败时返回类型为 deploy_failed 的错误，附带部署的错误码（job_failed、job_timed_out、job_lost 等），服务作为 param() (services.<name>)。还有 create_with(…, &ProjectDeployOptions::new().no_wait())、get(id)、list()。
• 不属于任何产品的调用在客户端本身上：账户、用量、套餐和账单、项目及其事件。

密钥从 GLAC_API_KEY 读取，地址从 GLAC_API_URL 读取。要使用其他地址、密钥或超时，请构建一个客户端：

let client = Client::builder().api_key(key).base_url(address).build()?;
let named = client.sandboxes().create_with(&CreateOptions::new().name(&name).env("STAGE", "dev").never_sleep())?;

简写。沙箱 SDK 的一行写法仍然保留，它们就是由环境变量描述的那个客户端（Client::shared()，第一次使用时创建）上的 client.sandboxes()：glac::run、glac::run_with、Sandbox::create、Sandbox::get、Sandbox::get_or_create、Sandbox::list，以及它们的 _with 和 _page 形式。其他一切都需要客户端。

每个带选项的调用都有两种形式：create() 和 create_with(&options)，run(cmd) 和 run_with(cmd, options)。SDK 没有封装的 API：client.request("GET", "/v1/webhooks", &[], None)。API 中有三个名称是 Rust 的关键字，因此改了名：错误的 type 是 kind()，文件的 type 是 FileEntry::kind，files/move 是 rename。

方块

下文中，cube 指 client.cube()。

对已有的应用调用 deploy 时，先修改选项中属于应用自身的设置（区域、扩缩容、键、出站规则、元数据、日志、追踪、public、depends_on、网络：PATCH /v1/apps/{id}，只在给出其中某些设置时才修改），然后用镜像和其余设置创建一个版本 (POST /v1/apps/{id}/versions)，没有给出的沿用应用已有的：发出的请求与先调用 app.update(…)、再调用 app.deploy_with(…) 相同。没有该名称的应用 (404 app_not_found) 或不给名称时，它用全部设置创建一个应用 (POST /v1/apps)；这时返回 409 name_taken 表示在此期间有人创建了它，于是部署到对方的应用。no_wait() 在版本创建后立即返回。没能起来的版本是一个 kind() 为 deploy_failed 的错误，附带版本自己的错误码和输出。应用属于控制平面：独立运行的节点对这些调用都返回 404 no_such_route。

沙箱

下文中，sandboxes 指 client.sandboxes()。

let mut sbx = client.sandboxes().create()?; // stays until deleted, also when the value is dropped
let res = sbx.run("python3 -c 'print(6*7)'")?; // res.stdout, res.stderr, res.exit_code
println!("{} {}", res.stdout, sbx.url(3000)?);

以字符串给出的命令用 sh -c 运行；以字符串数组给出时，它是一个程序及其参数。

let cmd = sbx.exec("node server.js")?; // do not wait
for piece in cmd.output() {
    print!("{}", String::from_utf8_lossy(&piece?.data));
}

云盘

云盘是项目的一块磁盘，不随它的沙箱消失：同一时间由一个沙箱以读写方式挂载，可以在沙箱创建时挂载，也可以在沙箱运行时挂载；沙箱没了，云盘连同其中的内容一起保留，供下一个沙箱挂载：可以在它的区域，也可以在别的区域，只要那里的机器能读取它归属区域的对象存储（见下文）。云盘在写入的同时被复制到所在区域的对象存储中，所以其他节点上的沙箱也能挂载它：会先把它搬过去。只按写入的数据计费 (used_bytes)。云盘的快照是它在对象存储中的一个版本，不复制任何数据：分叉是从快照创建的新云盘，恢复让快照的内容重新成为云盘的内容，任意多个沙箱都可以同时以只读方式挂载一个快照。云盘属于控制平面 (/v1/drives)：对着一个独立运行的节点，每个调用都会得到该节点的 404 no_such_route，节点上的磁盘是存储卷（见下文）。

use glac::DriveMount;

let drive = client.drives().create_with(&DriveOptions::new().size_bytes(1 << 30))?; // Drive
let sbx = client.sandboxes().create_with(&CreateOptions::new().drive(DriveMount::new("/data", drive.id())))?;
sbx.run("echo kept > /data/note")?;
client.drives().detach(sbx.id(), drive.id())?;
let other = client.sandboxes().create()?;
client.drives().attach(other.id(), &DriveMount::new("/data", drive.id()))?;
println!("{}", other.run("cat /data/note")?.stdout); // kept

• 一个云盘同一时间只属于一个沙箱：另一个沙箱持有的云盘会被拒绝 (409 drive_attached)，删除已挂载的云盘也一样。键控实例的云盘随它的键一起删除 (409 key_drive)。
• 另一个节点持有的云盘，会先被搬到沙箱所在的节点；对象存储中还没有它的最新状态时 (503 copy_behind)，或无法把它搬过去时 (503 drive_not_brought)，调用为 retryable：客户端会按 retries 的设置重试，之后返回错误，你稍后再请求一次即可。
• 跨区域 (slice D9)。云盘的归属区域 (home) 是保存其副本的对象存储所在的区域：也就是创建它的区域。另一个区域的沙箱也能挂载它，前提是那个区域的机器能读取其归属区域的存储（不能时返回 409 not_on_one_machine）：云盘被释放为一个版本，在那里被接管，客户机读取时从归属区域的存储读出，客户机写入的数据则进入它现在所在区域的存储 (region)。云盘在那里待满一小时后，归属区域会跟过去，用 drives.move_home(drive) (drive.move_home()) 则立即迁移：它的机器把归属区域存储中剩下的内容复制到自己区域的存储中，那里什么都不剩时，home 就变成新区域；DriveInfo::home_move 说明迁移进行到哪一步（asked_at、asked_by、copied_objects、copied_bytes、objects_left、error）。保留的版本都不再需要旧归属区域的副本后（一天后），这份副本会被删除。云盘的归属区域最多每六小时迁移一次 (409 home_moved_recently)；归属区域就是当前所在区域的云盘返回 409 home_here。
• 套餐的限制：免费版最多 3 个云盘，单个最大 10 GiB，合计 15 GiB；付费版最多 500 个，单个最大 1 TiB (403 drive_limit_reached)。
• 快照不随云盘消失：云盘删除后，仍可以按云盘的 id 列出、读取、分叉它的快照，或以只读方式挂载。快照按它单独保留的数据 (exclusive_bytes) 计费，按小时计，价格与云盘的数据相同（每 GB·月 $0.02）。
• 分叉和任何云盘一样，按它的 used_bytes，即完整的逻辑内容计费：从 10 GB 快照分叉出的云盘按 10 GB 的云盘计费。
• 快照的只读挂载：在云盘所在区域的任意机器上，任意多个沙箱都可以同时挂载，无论云盘被谁持有，云盘删除后也可以。数据块在客户机读取时从对象存储取来：这些冷读不收费，并在用量中计在那个沙箱名下（UsageOptions::sandbox(id)，drive_cold_read_bytes）；读取那个沙箱的机器上已有的数据也不收费。客户机不能写入它，挂载了快照的沙箱也不能迁到别的机器上。应用的版本只能以读写方式挂载云盘：快照的只读挂载只供沙箱使用。
• 节点不向对象存储复制任何数据时，云盘没有快照、分叉和恢复 (409 not_copied)。
• UsageOptions::drive(id)、kind("drive") 和 group_by(&["drive"]) 报告云盘保存了多少、写入了多少、冷读了多少。drive.created、drive.deleted、drive.attached 和 drive.detached 事件携带 EventDrive 或 EventDriveAttached。

client.volumes() 对应 API 的 /v1/volumes，即云盘底层的磁盘，为过渡期而保留：只有它才有的，是独立运行的节点（节点上的磁盘就是存储卷），以及共享存储卷，即可由多个沙箱同时挂载的文件系统。控制平面不会为项目的密钥创建普通存储卷。

存储卷的备份。备份是存储卷（云盘也是存储卷）在某一时刻的副本，保存在对象存储中，直到过期：可以由调用创建，可以按存储卷的规则每天创建，也会在服务的新版本替换其实例之前创建。与云盘的快照不同，它是一份独立的副本，仅凭它就能创建存储卷，而且不随存储卷消失；存储卷的备份只保存自上一个备份以来变化的内容，多个备份都需要的数据块只计费一次，计在最早的备份上。在存储收到全部数据之前为 making，之后为 ready，从那时起按存储中保存的数据量 (stored_bytes)、以休眠沙箱所保存内容的价格计费（备份）。备份属于控制平面。

• 从备份创建的存储卷，大小和类型与备份所来自的存储卷相同，位于备份所在的区域。它的 status 在完整拿到备份之前为 restoring，之后为 ready，在此之前不能挂载；from_backup 指明来源备份。如果被分配到的机器无法恢复它，控制平面会在该区域的另一台机器上再创建一次：这时 restore_attempt 为 Some(2)，first_failure 说明第一次为什么失败。如果这一次也失败，它就是 failed (failure)，只能删除。
• UsageOptions::new().backup(id)、kind("backup") 和 group_by(&["backup"]) 报告备份保存了多少，计在状态计量项上 (state_gb_hours)；client.billing() 的 meters.state.backups_gb_hours 说明该计量项中有多少来自备份。

域名

项目的域名是一个指向应用（和它的默认地址一样）或沙箱某个端口的名称。域名属于控制平面。

浏览器

尚未开放。浏览器还没有向账户开放：下面是开放之前 SDK 目前的样子。

会话是一个托管的 Chromium，由 Chrome DevTools Protocol (CDP) 客户端在它的 cdp_url 上从外部驱动：也就是 Playwright 的 connectOverCDP 和 Puppeteer 的 browserURL 接受的地址。有客户端连接时它保持运行，最后一个客户端离开几秒后进入休眠，页面会保留。地址里带着凭据，所以 {:?} 不包含地址。

会话和任何实例一样，按它使用的方块资源计费：计算时的 CPU、运行时的内存和出站流量（价格与套餐）。session.awake_seconds 是它已运行的时长。

列出、修改、让会话休眠和换新地址，只有 Python 和 TypeScript SDK 以及 glac browsers 才有。会话属于控制平面。

数据库

数据库是托管的 Postgres：运行在云盘上的独立 PostgreSQL，没有任何请求时休眠，有连接时被唤醒，会话都会保留。所有者的密码只出现在 create 和 reset_password 的响应中，任何地方都不保存：只有它们返回的 Database 的 connection_string() 才带有密码。

数据库在项目网络上按名称访问，来自它的沙箱（用 project_network 创建）和服务：这就是它的 private_uri。有边缘节点提供 PostgreSQL 服务时，也可以从任何地方通过它的公网地址访问（connection_uri，端口 5432，只支持 TLS；连接池的地址：pooled_uri）；没有边缘节点提供、或数据库没有可用来命名的区域时，它们为 None；给出时，连接字符串会使用它们。数据库或分支的 {:?} 既不显示密码，也不显示带密码的连接字符串。数据库属于控制平面。

托管应用

目录中的应用（比如 Rivet）以它自己的方块资源安装到项目中：它的应用、存储卷、机密和存储桶，都带有该安装的标签，只能通过这个安装修改，并按这些资源本身计费（托管应用）。安装的响应包含全部输出，包括机密输出（管理员令牌、带有令牌的端点），之后的读取只对有 admin 权限范围的密钥显示这些输出：安装对象会保留之前的响应给出、而之后的响应隐藏的每个输出。

let rivet = client.catalogue().get("rivet", None)?;       // its parameters, and a month of it in Cube's meters
println!("{:?}", rivet.month);
let engine = client.installations().create("rivet", &InstallationOptions::new().parameters(json!({"disk_gib": 20})))?;
println!("{}", engine.info().outputs["endpoint"]);        // RIVET_ENDPOINT, its token in it

托管应用属于控制平面。

机密与变量

项目、账户与账单

事件的数据。控制平面的每种事件，在这个 crate 中都有一个对应其数据的类型，以描述中该事件的 schema 命名，它的 of(&event) 读取对应类型的事件，其他类型的事件返回 None (glac::EventDatabase::of(&e))。数据库的事件：EventDatabase（database.created，附带它的 region 和 PostgreSQL version；database.deleted，附带 final_snapshot_id，即保留七天的云盘快照）、EventDatabaseBranch（database.branch_created，附带它的 parent；database.branch_deleted，附带它的 reason）、EventDatabaseRestored（database.restored：时刻 at，以及 old_branch_id，即保存恢复之前状态的分支）、EventDatabaseArchive（database.archive_failing：since、连续失败的分段数 failures、archived_until，即在此期间恢复能追溯多远，以及对象存储的 error；database.archive_recovered：recovered_at）和 EventDatabaseGap。其他事件也一样：沙箱的（EventSandboxSlept、EventSandboxWoke、EventSandboxMoved、EventSandboxDeleted 等）、应用及其键的（EventApp、EventAppFailed、EventKeyCreated 等）、项目的部署和密钥、备份、域名、导出目标和云盘快照的（EventProjectDeployed、EventBackup、EventDomain、EventDestination、EventDriveSnapshot 等），以及账户的套餐、充值、退款、撤回、余额、点数、存储、出站流量上限、支出上限、冻结和欠款的（EventSubscriptionPeriod、EventTopupCollected、EventWithdrawalReceived、EventBalance、EventInDebt 等）。某类事件并非都有的字段，或为 null 的字段，类型为 Option。

Webhook、API 密钥、支出上限、项目。client.webhooks().create_with(url, &WebhookOptions::new().events(&[…]).enabled(true)) 把项目的事件发到你的地址（为每次投递签名的 secret 只出现在这次响应中）；还有 get、list、update、delete。client.keys().create_with(&KeyOptions::new().name(…).scopes(&[…])) 创建一个 API 密钥（密钥本身 key 只出现在这次响应中）；还有 get、list、delete。client.limits() 和 client.update_limits(Some(50.0)) 是项目的支出上限和本月已支出的金额（None 去掉上限），sbx.limits()、sbx.update_limits(…) 则是某个沙箱自己的。client.request_limit(limit, wanted, why) 申请提高账户的某项可应要求提高的限制（按名称指定的上限、"volumes" 或 "volume_bytes"；后两者中的大小以字节为单位；同一项限制已有申请在等待时返回 409 limit_request_pending），client.limit_requests(limit, cursor) 和 client.limit_request(id) 读取申请及运营方的答复（LimitRequest：status 为 pending、granted 或 refused，granted、answer）。EventInstanceRestarted::of(&event)、EventInstanceUpgrade::of（instance.upgraded、.reverted、.upgrade_failed）和 EventLimitRequest::of 读取这些事件的数据；instance.start_command()（沙箱的 info().start_command）说明它的启动命令如何运行、在机器中被重新启动了多少次，以及上一次是如何结束的。client.update_project(Some(30)) 设置沙箱休眠多少天后被删除（None：永不删除）。属于控制平面。Webhook 和 API 密钥需要有 admin 权限范围的密钥，设置项目的上限和 update_project 也一样；设置沙箱的上限需要 write。

日志导出目标、审计日志、计费文件。client.destinations() 是项目中应用的日志（以及指标和请求的追踪：.signals(&["logs", "traces"])）导出的地方（OpenTelemetry 端点）：create(name, &DestinationOptions::new().endpoint(u).header(name, value)) 创建时会立即用一条记录测试 (status.connected)，还有 get、list、update、delete、test（立即发送一条记录）；请求头的值是凭据，只在创建或修改导出目标时发送，不会出现在任何响应中（返回的内容只有请求头的名称）。client.audit_page(&ListOptions::new().limit(n)) 是项目审计日志的一页，最新的在前（谁、什么方法、什么路径、什么状态）：每一次不是读取的调用（被拒绝的也算），以及运营方对应用日志的每一次读取。client.statement(Some("2026-09")) 是某个月的对账单（None 表示本月），其中每个数据库单独一行（databases：它这个月的用量，其中历史和分层数据单列，以及按标价折合多少），client.invoices() 是 Stripe 上的发票（附 PDF 链接），client.notices() 是发给账户的邮件，client.withdrawals(&ListOptions::new()) 是现在可以撤回的购买和已做的撤回（欧洲经济区或英国的消费者可以在 14 天内撤回一笔购买），client.withdraw(charge_id, name, Some(email)) 是买方本人的撤回声明，立即受理。属于控制平面。创建、修改、测试和删除导出目标、读取审计日志以及撤回，需要有 admin 权限范围的密钥；其他调用只需要有读取权限的密钥。

立即购买 (start_now)。欧洲经济区或英国的消费者（没有已验证或正在验证的税号的账户）可以在 14 天内撤回一笔购买，所购内容只有在其本人明确要求时才会立即提供。start_now() 就带有这一要求：client.top_up_with(20.0, &TopUpOptions::new().start_now())、BillingOptions::new().plan("paid").start_now()（从免费版购买付费版）和 BalanceOptions::new().auto_reload(true).start_now()（自动充值保持开启期间的每一次自动充值），措辞与控制台在勾选框旁显示的相同（GET /v1/billing/withdrawals 中也有，见 right.start_now）：

我要求在可以撤回这笔购买的 14 天内立即提供所购内容。如果我撤回，我需要为此前已提供的部分付费。我理解，一次充值的点数全部用完后，即视为已全部提供，我将不能再撤回。

服务立即开始；在 14 天内，买方仍可撤回，并为此前已提供的部分付费；一旦全部提供（一次充值的点数全部用完），撤回权即丧失。只有在购买者本人提出这一要求时才加上它：SDK 不会自行发送它。没有它时，这类账户的购买会被拒绝：返回一个 Error，状态为 400，错误码为 start_now_required，param() 为 start_now，错误信息会指明账户所在的国家并引用这一要求的原文，什么也不会买。开启了自动充值却没有这一要求的账户不会自动充值，并且每月会收到一次通知（auto_reload.no_request 事件，用 EventAutoReloadNoRequest::of 读取；没有绑定银行卡的账户则是 auto_reload.no_card 和 EventAutoReloadNoCard）。

错误

非零退出码是一个结果：读取 res.exit_code 即可。API 的错误是一个 glac::Error，带有 status()、kind()、code()、param()、retryable()、request_id() 和 message()，以及指向错误页面上对应错误码的 docs_url()。连不上或超时也是这种错误，status() 为 None；is_timeout() 可以判断是否超时。与费用有关的错误（402 account_in_debt、403 trust_limit_exceeded、409 no_card、400 start_now_required 等）带有控制平面自己的错误信息，说明怎样解除。

值得了解的行为

• 休眠的沙箱。不会有调用因为沙箱在休眠或正在启动而失败：它会等待，然后继续。res.wake 说明 run 为唤醒等待了多久；客户端上的 on_response 能看到每个调用的这一信息。
• 重试。没有响应，或出现 retryable 错误时，会重试两次 (retries)，间隔从 0.2 秒开始翻倍。每个 POST 都带有 Idempotency-Key；idempotency_key(key) 让重启后的程序能拿回它之前创建的东西。
• 超时。timeout（默认 15 分钟）是等待 API 的时长；RunOptions::timeout 是命令自己的时限。
• 线程。Client 可以在线程之间共享，各产品的句柄共用它的连接；Sandbox 上的只读调用接受 &self。在 tokio 中，在有异步版本之前，请用 tokio::task::spawn_blocking(move || sbx.run("make")).await??。
• HTTPS 使用内置的 Mozilla 根证书；SSL_CERT_FILE 可以加入你自己的证书。到目前为止，它只在纯 HTTP 的开发机器上运行过。