Rust SDK

這個頁面還沒有翻譯成繁體中文：以下是英文版。

Install

Calls block and return Result; options are chained …Options; durations are Duration and times SystemTime; the API’s null is Option. Four dependencies (serde_json, rustls with ring, webpki-roots, libc) and no async runtime. The crate is glac on crates.io:

[dependencies]
glac = "0.1"

The client and its products

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

Each product is a namespace of the client’s, a light handle that borrows it:

• client.cube(): Cube, images that run as services, which the API calls apps. The types keep the API’s names: App, AppOptions, Version, Instance. client.workers() is another name for it, marked deprecated.
• client.sandboxes(): sandboxes, with their snapshots (.snapshots()) and the SSH keys that open them (.ssh_keys()).
• client.drives(): Drives, disks of the project’s that outlive their sandboxes, each mounted read-write by one sandbox at a time (Drive, DriveOptions, DriveMount), and their snapshots (DriveSnapshot, DriveSnapshotOptions, DriveForkOptions); client.volumes(), the volumes underneath them (Volume, VolumeOptions, VolumeMount); client.backups(), the backups of volumes (Backup, BackupOptions), a control plane’s.
• client.domains(): the project’s own domains (Domain, DomainOptions), names for an app or a port of a sandbox; a control plane’s.
• client.webhooks() and client.keys(): where the project’s events are sent (Webhook, WebhookOptions), and its API keys (ProjectKey, KeyOptions); a control plane’s.
• client.destinations(): where the logs, metrics and traces of the project’s apps are exported (Destination, DestinationOptions); a control plane’s.
• client.secrets() and client.variables(): the project’s secrets and shared variables.
• client.deploys(): the project’s deploys (/v1/deploys, a control plane’s): several of its services deployed together, in the order of what each waits for, and switched together (a project’s deploy). create([("api", DeployOptions::new().image("ghcr.io/acme/api:2")), ("web", DeployOptions::new())]) gives each service what a deploy of it alone takes and waits for the deploy, following one that took its place; one that fails is an error of kind deploy_failed with the deploy’s code (job_failed, job_timed_out, job_lost, …) and the service as param() (services.<name>). create_with(…, &ProjectDeployOptions::new().no_wait()), get(id), list().
• What is no product’s is the client’s own: the account, usage, the plan and the bill, the project and its events.

The key is read from GLAC_API_KEY and the address from GLAC_API_URL. For another address, key or timeout, build a client:

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())?;

The shorthand. The one-liners of the sandbox SDKs stay, as client.sandboxes() on the client the environment describes (Client::shared(), made on first use): glac::run, glac::run_with, Sandbox::create, Sandbox::get, Sandbox::get_or_create, Sandbox::list, and their _with and _page forms. Everything else takes a client.

Each call with options has two forms: create() and create_with(&options), run(cmd) and run_with(cmd, options). An API the SDK does not wrap: client.request("GET", "/v1/webhooks", &[], None). Three names of the API are Rust keywords and are renamed: an error’s type is kind(), a file’s type is FileEntry::kind, and files/move is rename.

Cube

Below, cube is client.cube().

deploy to an app that is there changes what of the options is the app’s own first (regions, scale, keys, egress rules, metadata, logs, traces, public, depends_on, network: PATCH /v1/apps/{id}, only when any of it is given), then makes a version of the image and the rest (POST /v1/apps/{id}/versions), what is not given of it being what the app has: the same requests as app.update(…) and then app.deploy_with(…). With no app of that name (404 app_not_found), or no name, it makes one with everything (POST /v1/apps); a 409 name_taken there means somebody made it in between, and it deploys to theirs. no_wait() returns as soon as the version is made. A version that does not come up is an error whose kind() is deploy_failed, with the version’s own code and words. Apps are a control plane’s: a node that stands alone answers each of these calls with 404 no_such_route.

Sandbox

Below, sandboxes is 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)?);

A command given as a string runs with sh -c; as an array of strings it is a program and its arguments.

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

Drive

A Drive is a disk of the project’s that outlives its sandboxes: mounted read-write by one sandbox at a time, when the sandbox is made or while it runs, and kept, with what it holds, when the sandbox goes, for the next sandbox to mount: of its region, or of another whose machines read its home’s object store (below). It is copied into its region’s object store as it is written, so a sandbox on another node mounts it too: it is brought there first. Only what is written is billed (used_bytes). A snapshot of a Drive is a version of it in the object store, nothing copied: a fork is a new Drive made of one, a restore makes a snapshot’s content the Drive’s again, and any number of sandboxes mount one read-only at once. Drives are a control plane’s (/v1/drives): against a node that stands alone every call is the node’s 404 no_such_route, and its disks are volumes (below).

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

• A Drive is one sandbox’s at a time: one that another sandbox has is refused (409 drive_attached), and so is deleting one that is attached. A keyed instance’s Drive goes with its key (409 key_drive).
• One that another node holds is brought to the sandbox’s node first; while the object store does not hold it as it is yet (503 copy_behind), or it could not be brought (503 drive_not_brought), the call is retryable: the client tries again as its retries say, then returns the error, for you to ask again a moment later.
• Across regions (slice D9). A Drive’s home (home) is the region whose object store holds its copy: the region it was made in. A sandbox of another region mounts it too, where that region’s machines read its home’s store (409 not_on_one_machine where they do not): the Drive is let go as a version and taken over there, read from its home’s store as its guest reads it, and what its guest writes goes to the store of the region it is in now (region). Its home follows it once it has been there for an hour, or at once with drives.move_home(drive) (drive.move_home()): its machine copies what is left in its home’s store into its own, and home is the new region once nothing is left there; DriveInfo::home_move says how far the move is (asked_at, asked_by, copied_objects, copied_bytes, objects_left, error). Its old home’s copy goes once no version kept needs it (a day after). A Drive’s home moves once in six hours at the most (409 home_moved_recently); one whose home is the region it is in is 409 home_here.
• The plan’s limits: 3 Drives of at most 10 GiB, 15 GiB together, on Free; 500 of at most 1 TiB on Paid (403 drive_limit_reached).
• A snapshot outlives its Drive: after the Drive is deleted it is listed, read, forked and mounted read-only by the Drive’s id. It is billed for what it keeps alone (exclusive_bytes), by the hour, at the Drives’ data price ($0.02 a GB-month).
• A fork is billed by its used_bytes, its full logical contents, like any Drive: a fork of a 10 GB snapshot is billed as a 10 GB Drive.
• A read-only mount of a snapshot: any number of sandboxes, on any machine of the Drive’s region, at once, whatever has the Drive and after it is deleted. Its blocks come from the object store as the guest reads them: those cold reads cost nothing, and show under that sandbox in usage (UsageOptions::sandbox(id), drive_cold_read_bytes); reads of what that sandbox’s machine already holds cost nothing. The guest cannot write it, and a sandbox that has one cannot move to another machine. An app’s version mounts a Drive read-write only: read-only snapshot mounts are a sandbox’s.
• Where the node copies nothing to an object store, a Drive has no snapshots, forks or restores (409 not_copied).
• UsageOptions::drive(id), kind("drive") and group_by(&["drive"]) report what Drives kept, were written and read cold. The events drive.created, drive.deleted, drive.attached and drive.detached carry an EventDrive or an EventDriveAttached.

client.volumes() is the API’s /v1/volumes, the disks underneath Drives, kept for the transition: what only it has is a node that stands alone, whose disks are volumes, and shared volumes, file systems several sandboxes mount at once. A control plane makes no plain volume for a project’s key.

Backups of volumes. A backup is a copy of a volume (a Drive is one) at one instant, in the object store, kept until it expires: taken by a call, every day by the volume’s rule, or before a service’s new version replaces its instance. Unlike a snapshot of a Drive it is a copy of its own, a volume is made from it alone, and it outlives its volume; a volume’s backups keep only what changed since the one before, and a block several of them need is billed once, on the earliest. It is making until the store has all of it, then ready, and billed from then by what the store holds of it (stored_bytes) at the price of what sleeping sandboxes keep (backups). Backups are a control plane’s.

• A volume made from a backup has the size and kind of the volume it was taken of, in the backup’s region. Its status is restoring until it holds the backup whole, then ready, and nothing attaches it before; from_backup names the backup. Where the machine it was placed on cannot bring it back, the control plane makes it once more on another machine of the region: restore_attempt is Some(2) then, and first_failure says why the first try failed. If that fails too, it is failed (failure), and can only be deleted.
• UsageOptions::new().backup(id), kind("backup") and group_by(&["backup"]) report what backups kept, on the meter of state (state_gb_hours); meters.state.backups_gb_hours of client.billing() says how much of that meter was backups.

Domains

A domain of the project’s is a name that leads to an app, as its default address does, or to a port of a sandbox. Domains are a control plane’s.

Browser

Not open yet. Browser is not open to accounts yet: what follows is the SDK as it stands, ahead of its opening.

A session is a hosted Chromium that a client of the Chrome DevTools Protocol (CDP) drives from outside, at its cdp_url: what Playwright’s connectOverCDP and Puppeteer’s browserURL take. It is awake while a client is connected and falls asleep, its pages kept, a few seconds after the last one leaves. The addresses carry their credential, so {:?} leaves them out.

A session is billed by the Cube resources it uses, as any instance is: its CPU while it computes, its memory while it is awake and its traffic out (pricing and plans). session.awake_seconds is how long it has been awake.

Listing, changing, putting to sleep and new addresses are the Python and TypeScript SDKs’ and glac browsers’. Sessions are a control plane’s.

Databases

A database is a managed Postgres: a PostgreSQL of its own on a Drive, asleep when nothing asks anything of it and woken by a connection, its sessions kept. The owner’s password is in the answer of create and of reset_password alone, and kept nowhere: connection_string() of the Database one of those returned has it.

A database is reached on the project’s network, from its sandboxes (made with project_network) and its services, at its name: that is its private_uri. Where an edge serves PostgreSQL it is reached from anywhere at its public address too (connection_uri, port 5432, TLS alone; the pooler’s: pooled_uri); they are None where none does, or where the database has no region to be named under, and the connection string takes them where they are given. {:?} of a database or a branch shows neither the password nor a connection string with it. Databases are a control plane’s.

Managed Applications

An application of the catalogue (Rivet, say) is installed in the project as its own Cube resources: its apps, Volumes, secrets and buckets, labelled with the installation, changed through it alone, and billed as they are (Managed Applications). An install’s answer has every output, the secret ones too (an admin token, an endpoint with it in), and a read shows those to a key with the admin scope alone: an installation object keeps each output an earlier answer gave that a later one hides.

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

Managed Applications are a control plane’s.

Secrets and variables

The project, the account and the bill

The data of an event. Every type of event the control plane has has a type of its data in this crate, named after the description’s schema of it, whose of(&event) reads an event of its types and is None of another’s (glac::EventDatabase::of(&e)). A database’s: EventDatabase (database.created, with its region and PostgreSQL version; database.deleted, with final_snapshot_id, the snapshot of its Drive kept seven days), EventDatabaseBranch (database.branch_created, with its parent; database.branch_deleted, with its reason), EventDatabaseRestored (database.restored: the moment at, and old_branch_id, the branch the state before is kept as), EventDatabaseArchive (database.archive_failing: since, how many segments in a row failures, archived_until, how far a restore reaches meanwhile, and the object store’s error; database.archive_recovered: recovered_at) and EventDatabaseGap. The others likewise: a sandbox’s (EventSandboxSlept, EventSandboxWoke, EventSandboxMoved, EventSandboxDeleted, …), an app’s and its keys’ (EventApp, EventAppFailed, EventKeyCreated, …), the project’s deploys and key, backups, domains, destinations and Drives’ snapshots (EventProjectDeployed, EventBackup, EventDomain, EventDestination, EventDriveSnapshot, …), and the account’s plan, top-ups, refunds, withdrawals, balance, Credits, storage, egress cap, spend limits, hold and debts (EventSubscriptionPeriod, EventTopupCollected, EventWithdrawalReceived, EventBalance, EventInDebt, …). A field that not every event of a type has, or that is null, is an Option.

Webhooks, API keys, spend limits, the project. client.webhooks().create_with(url, &WebhookOptions::new().events(&[…]).enabled(true)) sends the project’s events to an address of yours (the secret that signs each delivery is in that answer alone); get, list, update, delete. client.keys().create_with(&KeyOptions::new().name(…).scopes(&[…])) makes an API key (the key itself, key, is in that answer alone); get, list, delete. client.limits() and client.update_limits(Some(50.0)) are the project’s spend limit and what was spent this month (None takes the limit away), and sbx.limits(), sbx.update_limits(…) a sandbox’s own. client.request_limit(limit, wanted, why) asks for one of the account’s limits raised on request (a cap by its name, "volumes" or "volume_bytes"; bytes of the two in bytes; 409 limit_request_pending while one of the same limit waits), and client.limit_requests(limit, cursor) and client.limit_request(id) read them with the operator’s answers (LimitRequest: status pending, granted or refused, granted, answer). EventInstanceRestarted::of(&event), EventInstanceUpgrade::of (instance.upgraded, .reverted, .upgrade_failed) and EventLimitRequest::of read those events’ data; instance.start_command() (a sandbox’s info().start_command) says how its start command runs, how often it was started again in its machine, and how it last ended. client.update_project(Some(30)) sets after how many days asleep its sandboxes are deleted (None: never). A control plane’s. Webhooks and API keys need a key with the admin scope, and so do setting the project’s limit and update_project; setting a sandbox’s limit needs write.

Log destinations, the audit log, the billing documents. client.destinations() is where the logs (and the metrics and the requests’ traces: .signals(&["logs", "traces"])) of the project’s apps are exported (OpenTelemetry endpoints): create(name, &DestinationOptions::new().endpoint(u).header(name, value)), which tries it at once with one record (status.connected), get, list, update, delete, test (one record now); a header’s value is a credential, sent when a destination is made or changed and in no answer (what is returned has the headers’ names alone). client.audit_page(&ListOptions::new().limit(n)) is a page of the project’s audit log, the newest first (who, what method, what path, what status): every call that was no reading, a refused one too, and every reading of an app’s log by an operator. client.statement(Some("2026-09")) is a month’s statement (None is this month’s) with each database’s own line in it (databases: what it used in the month, its history and its tiered data apart, and what that comes to at the list prices), client.invoices() the invoices at Stripe (with the PDF’s link), client.notices() the mail the account was sent, client.withdrawals(&ListOptions::new()) what it may withdraw from now and the withdrawals it made (a consumer in the EEA or the UK may withdraw from a purchase within 14 days), and client.withdraw(charge_id, name, Some(email)) the buyer’s own statement of withdrawal, received at once. A control plane’s. Making, changing, testing and deleting a destination, reading the audit log and withdrawing need a key with the admin scope; the rest, one that may read.

Buying at once (start_now). A consumer in the European Economic Area or the United Kingdom (an account with no tax id that is verified or being verified) may withdraw from a purchase within 14 days, and what it buys is provided at once only at its own express request. start_now() carries that request: client.top_up_with(20.0, &TopUpOptions::new().start_now()), BillingOptions::new().plan("paid").start_now() (Paid, bought from Free) and BalanceOptions::new().auto_reload(true).start_now() (for every auto reload while auto reload stays on), in the words the console shows beside its box (and GET /v1/billing/withdrawals has, right.start_now):

I ask for this purchase to be provided at once, within the 14 days in which I may withdraw from it. If I withdraw, I pay for what was provided until then. I understand that once all the Credits of a top-up are used, it has been provided in full and I can no longer withdraw from it.

The service starts now; within the 14 days the buyer may still withdraw, and pays for what was provided until then; once it is fully provided (a top-up whose Credits are all used), the right to withdraw is lost. Give it only when the person buying asks for that: the SDK never sends it unless it is given. Without it, such an account is refused: an Error of status 400, code start_now_required, param() start_now, in words that name its country and quote the request, and nothing is bought. An account whose auto reload is on without the request reloads nothing, and is told once a month (the event auto_reload.no_request, read with EventAutoReloadNoRequest::of; an account with no card on record, auto_reload.no_card and EventAutoReloadNoCard).

Errors

A non-zero exit code is a result: read res.exit_code. An error of the API is a glac::Error with status(), kind(), code(), param(), retryable(), request_id() and message(), and docs_url(), which leads to the code on the errors page. No connection or a timeout is one too, with status() None; is_timeout() tells a timeout. Errors about money (402 account_in_debt, 403 trust_limit_exceeded, 409 no_card, 400 start_now_required, …) carry the control plane’s own message, which says what lifts them.

Behaviour worth knowing

• Sleeping sandboxes. No call fails because a sandbox sleeps or is starting: it waits and goes on. res.wake says how long run waited for a wake; on_response on the client sees it for every call.
• Retries. No answer, or a retryable error, is retried twice (retries), from 0.2 s doubling. Every POST carries an Idempotency-Key; idempotency_key(key) lets a program that restarts get back what it made.
• Timeouts. timeout (15 minutes unless you say) is how long to wait for the API; RunOptions::timeout is the command’s own limit.
• Threads. A Client may be shared between threads, and its products’ handles use its connections; read-only calls on a Sandbox take &self. In tokio, use tokio::task::spawn_blocking(move || sbx.run("make")).await?? until there is an async version.
• HTTPS uses the Mozilla root certificates built in; SSL_CERT_FILE adds your own. It has so far run against plain-HTTP development machines only.