Java SDK

Trang này chưa được dịch sang Tiếng Việt: đây là bản tiếng Anh.

Install

Java 17 or later, on the JDK’s own java.net.http (HTTP and WebSocket); no dependencies, no framework. Calls block, errors throw GlacException (unchecked), returned objects are records, options are chained …Options, durations are Duration and times Instant. It is on Maven Central as ai.glac:glac, in the package ai.glac:

<dependency>
  <groupId>ai.glac</groupId>
  <artifactId>glac</artifactId>
  <version>0.1.0</version>
</dependency>

The client

Glac glac = new Glac(); // GLAC_API_KEY and GLAC_API_URL; or Glac.builder().apiKey(key).baseUrl(address).build()

App app = glac.cube().deploy("ghcr.io/acme/api:1.4", new AppOptions().name("api").port(8080)); // Cube: waits until it serves
System.out.println(app.url());

Sandbox sbx = glac.sandboxes().create(); // Sandbox: stays until deleted
Result res = sbx.run("python3 -c 'print(6*7)'"); // res.stdout(), res.stderr(), res.exitCode()
System.out.println(res.stdout() + " " + sbx.url(3000));

Drive drive = glac.drives().create(new DriveOptions().name("data").sizeBytes(10L << 30)); // Drive

System.out.print(Sandbox.runOnce("echo hello").stdout()); // the shorthand: a sandbox for one command, on the default client

glac.cube().deploy is glac deploy: a new version of the app called api, which is made first where there is none, waited for until it has the app’s traffic. The last line is the one shorthand there is, the sandbox SDKs’ one-liner without a client. Nothing deletes anything but the one-off sandbox and your own delete(); Sandbox does not implement AutoCloseable, since a sandbox is meant to stay.

new Glac() reads the key from GLAC_API_KEY and the address from GLAC_API_URL (default https://api.glac.ai). For another address, key or timeout, build a client:

Glac glac = Glac.builder().apiKey(key).baseUrl(address).build();
Sandbox named = glac.sandboxes().create(new CreateOptions().name(name).env("STAGE", "dev").neverSleep());

The namespaces are methods returning an object Glac makes, one per client. The objects keep the API’s names: a Cube is an App (the API calls it an app), and Sandbox, Drive, DriveSnapshot, Volume, Backup, Domain, Snapshot, SshKey, Secret, Variable, Version, Instance, Deploy.

Cube

A Cube, which the API calls an app, is an image that runs as a service at an address of its own, with as many instances as its requests need and none while there are none. Every deploy makes a version, which takes the app’s traffic once it is ready. Apps are a control plane’s: against a node that stands alone every call is the node’s own 404 no_such_route.

A version that does not come up throws a GlacException with type() deploy_failed and the version’s own code and words; the traffic stays where it was. What a version is made of (image, startCommand, port, env, secret, vcpus, memoryBytes, volumes, drives, keyDrives, …) is the whole of a DeployOptions; the rest of what an app has holds at once and makes no version.

Sandbox

The shorthand. Sandbox.runOnce, Sandbox.create, Sandbox.get, Sandbox.getOrCreate, Sandbox.list and Sandbox.listPage are the calls of Glac.shared().sandboxes(), one implementation. No other product has statics without a client. The one-off run is run on the namespace and runOnce on the class, since Java cannot have a static and an instance method with the same signature (sbx.run runs a command in a sandbox), and waiting for a command is waitFor (wait() belongs to Object). A command given as a String runs with sh -c; as a List<String> it is a program and its arguments.

Command cmd = sbx.exec("node server.js"); // do not wait
try (Output out = cmd.output()) {
    for (Piece piece : out) {
        System.out.print(piece.text());
    }
}

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 (usedBytes). Its snapshots are versions of it in that store, and nothing is copied for them: a fork is a new Drive made of one, a restore takes the Drive back to one, and any number of sandboxes mount one read-only at once (below). Drives are a control plane’s (/v1/drives): against a node that stands alone every call throws the node’s 404 no_such_route, and its disks are volumes (below).

Drive data = glac.drives().create(new DriveOptions().name(name).sizeBytes(1L << 30));
Sandbox with = glac.sandboxes().create(new CreateOptions().drive(new DriveMount("/data", data.id())));
with.run("echo kept > /data/note");
glac.drives().detach(with.id(), data.id());
Sandbox other = glac.sandboxes().create();
glac.drives().attach(other.id(), new DriveMount("/data", data.id()));
System.out.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 throws, 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 glac.drives().moveHome(drive) (drive.moveHome()): 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; Drive.Info#homeMove 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).
• new UsageOptions().drive(id), kind("drive") and groupBy("drive") report what Drives kept, were written and read cold. The events drive.created, drive.deleted, drive.attached and drive.detached carry an Event.Drive or an Event.DriveAttached.
• A snapshot outlives its Drive: it is listed, read, forked and mounted read-only after the Drive is deleted, by the Drive’s id. It is billed for what it keeps alone (exclusiveBytes), by the hour, at the Drives’ data price ($0.02 a GB-month).
• A fork is billed by its usedBytes, its full logical contents, like any Drive: a fork of a 10 GB snapshot is billed as a 10 GB Drive.
• Read-only mounts. Any number of sandboxes mount a snapshot at once, on any machine of the Drive’s region, 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 (driveColdReadBytes() of glac.usageReport(new UsageOptions().sandbox(id))); reads of what that sandbox’s machine already holds cost nothing. The guest cannot write it, and a sandbox that has one does not move to another machine. attach takes no mount with a snapshot, attachSnapshot none without, and detachSnapshot no id but a dsnap-…: each is refused before anything is sent.

glac.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. It has create(), create(VolumeOptions) (name, sizeBytes, shared), get(idOrName) and list(); vol.delete() deletes one no sandbox has (one that a sandbox has is 409 volume_in_use). A sandbox mounts one with new CreateOptions().volume(new VolumeMount("/team", vol.id())), an app’s instances with AppOptions.volumes(…).

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 (storedBytes) 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 info().status() is restoring until it holds the backup whole, then ready, and nothing attaches it before; fromBackup() 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: restoreAttempt() is 2 then, and firstFailure() says why the first try failed. If that fails too, it is failed (failure()), and can only be deleted.
• new UsageOptions().backup(id), kind("backup") and groupBy("backup") report what backups kept, on the meter of state (state_gb_hours); meters().state().backupsGbHours() of glac.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: Playwright for Java connects with playwright.chromium().connectOverCDP(session.cdpUrl()). 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 toString() leaves them out.

• glac.browsers().create(new BrowserOptions().name("agent-42")) (or create()) makes one, awake; BrowserOptions has kind (chromium-headless, the default, chromium, on a screen, or lightpanda, a browser without a layout engine), name, region, sleepAfterSeconds, connectionIdleSeconds, deleteAfterIdleSeconds, metadata, profile(name, save) and profile(name, version, save) (a profile of the project’s loaded before the session is answered, saved again when it is deleted where save), proxy(url) (your own HTTP proxy, which takes CONNECT, on Paid: the session’s connections to ports 80 and 443 go out through it by a relay beside the browser, the credentials kept by the platform; 403 proxy_not_on_plan on Free). The name of one there is answers that one, woken, with its pages. One whose sandbox fails before it runs is no session: its create is refused, 503 session_failed.
• glac.browsers().get(idOrName), delete(idOrName) (one made with a profile to save saves it first) and deleteWithoutSavingProfile(idOrName), and a session’s own delete() and deleteWithoutSavingProfile(). A BrowserSession has id(), status(), cdpUrl(), profile() (a BrowserSession.Profile: name, save, version), proxy() (a BrowserSession.Proxy: its own proxy’s url and username, never the password), proxyBytes() (what went through it, both ways) and info(): its kind, liveUrl, times, awakeSeconds, proxySentBytes and proxyReceivedBytes.
• status() is awake, asleep, unavailable (its node cannot be reached) or failed (its sandbox failed after its create was answered: its browser stopped and did not come back, say), and then error() says why (a BrowserSession.Failure: code, message, as its node says it; null unless it failed). The event browser.failed says so too: Event.BrowserFailed.of(event) reads its data.

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.info().awakeSeconds() 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 resetPassword alone, and kept nowhere: connectionString() of the Database one of those returned has it.

• glac.databases().create("shop"), or create("shop", new DatabaseOptions().version("18")), makes one and waits for its first start (status() ready, or creating: get it until it is ready); DatabaseOptions has version, region, databaseName, size(vcpus, memoryBytes), storage(sizeBytes, durability), sleepAfterSeconds, suspendAfterSeconds (paused, a connection answered in a millisecond or two, before its memory is saved and it sleeps for real: 1 to 86400, 300 by default), wakeDailyAt("03:30") (woken every day then while it rests), metadata. The name of one there is answers that one, without its password. glac.databases().setSuspendAfter(idOrName, n) and setWakeDailyAt(idOrName, "04:00") change these two, every branch’s at once; null takes either back (to 300, and to none). On a Free plan a database’s rest is fixed, as Neon’s Free scales to zero: paused a second after its last query (sleep_after_seconds 1) and asleep five minutes later (suspend_after_seconds 300); another value is refused 400 invalid_field, on a create and on a change.
• glac.databases().createBranch(idOrName, "preview", parent, expiresAt) makes a branch of its own (parent null: main; expiresAt null: it stays): its parent as it is now, nothing copied, with a PostgreSQL, an endpoint and a Drive of its own, at <database>-<name> on the project’s network; its roles and passwords are its parent’s (branch.connectionString(ownerPassword)). deleteBranch(idOrName, branch) stops its PostgreSQL and deletes its Drive; not main (409 root_branch), nor a branch others were made of (409 has_branches).
• new DatabaseOptions().historySeconds(n), glac.databases().setHistory(idOrName, n), restore(idOrName, t), restore(idOrName, t, exact) and createBranch(idOrName, name, parent, expiresAt, at), createBranch(…, at, exact) (Database’s historySeconds, history): its history (slices DB8 and DB5): how far back its root branch can be restored, or branched from, by a time: a day unless given; 0 (none) to 30 days on Paid, a day on Free. A restore takes the root branch back in place: to a whole minute or a version’s own moment, the newest version of its Drive’s window at or before it (one every 30 seconds in which it was written, a day of it at the most); further back, to the second, or with exact, the moment itself, to the millisecond, by its WAL archive (its WAL replayed to it: seconds to minutes, the call waits). Its endpoint, its connection strings and its owner’s password stay what they were, its connections drop, and its state before is kept as a branch of its own, main_old_<the restore's moment>; one whose new version does not serve within five minutes is undone (503 database_restore_failed). A branch of a time is made of that moment instead (from: {at, exact}). A time its history does not have is 400 invalid_history, its message saying from when the window and the archive reach. A time to the second (or exact) is the archive’s or refused, never the window’s version before it: 400 invalid_history where the archive does not reach it (a database that keeps none, or a time before its oldest base), 503 database_archive_unavailable (retryable) while the archive’s store refuses its segments; each refusal names the window’s version at or before the time, whose own moment can be asked for instead. One whose blocks the store does not give is refused 503 drive_unreadable (retryable), nothing made. An outage of the object store long enough that more of its WAL waited than its Drive keeps for the log gives that WAL up, so that the database stays up: a gap of its archive, in history().gaps() (Database.Gap: from, to, fromLsn, toLsn): when the WAL given up began, until when the archive restores no time (the end of the first base taken after it; null until there is one), and where in the log it begins and ends. A time in a gap is restored only from its Drive’s window (a whole minute, or a version’s own moment); to the second, or exact, it is 400 invalid_history. The gap is said as events too: database.history_gap when it is first found (once a gap, while the database is awake), and database.history_resumed when the archive restores again after it; Event.DatabaseGap.of(event) reads their data (null for an event of another type): the database, the gap’s from(), to() (null of the first), fromLsn() and toLsn(), segments() (how many segments of 16 MB were given up) and, of the first, error() (what the object store’s last refusal said).
• new DatabaseOptions().tiering(true) and glac.databases().setTiering(idOrName, on) turn its tiered storage on or off (slice DB18: on Paid, where the object gateway serves; off is refused while a branch has partitions tiered, 409 tiered_data_exists; each branch’s PostgreSQL restarts once for it); Database’s tiering says whether it is on and what it bills by now.
• get(idOrName), list(), listNamed(name), delete(idOrName, finalSnapshot) (a snapshot of its Drive kept seven days unless finalSnapshot is false), branches(idOrName) (main first, then its own), branch(idOrName, "main"), sleep and wake (a branch, now), resetPassword(idOrName, role) (a new password in this answer alone; null is the database’s owner).
• glac.databases().roles(idOrName) lists the roles of its root branch that log in, read from PostgreSQL itself (DatabaseRole: name, owner): its owner and the roles you made (CREATE ROLE … LOGIN), the platform’s not among them. resetRolePassword(idOrName, role) gives any of them a new password, in this answer alone: a DatabaseRoleSecret with the role’s password and the root branch’s connection strings of that role (connectionString()); the owner’s is made of the database the API answers. A branch of its own keeps the password it was made with.
• db.connectionString() and branch.connectionString(password): the URI libpq and psql take, the public one where the API gives one, else the one on the project’s network, with the owner’s password (percent-encoded). Database and DatabaseBranch are records of the API’s fields: defaultBranch(), connectionUri(), pooledUri(), privateUri(), endpoint(), state().

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 null where none does, or where the database has no region to be named under, and the connection string takes them where they are given. toString() shows neither the password nor a connection string. 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.

Catalogue.App rivet = glac.catalogue().get("rivet");      // its parameters, and a month of it in Cube's meters
Installation engine = glac.installations().create("rivet", new InstallationOptions().parameters(Map.of("disk_gib", 20)));
System.out.println(rivet.month() + " " + engine.info().outputs().get("endpoint"));   // RIVET_ENDPOINT, its token in it

Managed Applications are a control plane’s.

Secrets and variables

• Secrets. glac.secrets().put("DB_URL", url, List.of("db.example.com")) keeps a value under a name, with the hosts it may be sent to; update(name, hosts) changes only the hosts, list() gives the names (never a value), delete(name) deletes one. An app’s environment takes one by its name (new AppOptions().secret("VAR", "DB_URL")), as do an image that is not public (imagePullSecret) and a sandbox’s egress rules. A call that would send one elsewhere is refused, 403 secret_host_not_allowed.
• Shared variables. glac.variables().put(name, value), list(), delete(name): a value the services’ env refers to ("${{ shared.REGION }}") in the versions made after it is put. A control plane’s.

The project, the account and the bill

The platform’s calls are the client’s own: glac.project() and glac.events(EventsOptions) (the project and a page of its events), glac.account() and glac.updateAccount(AccountOptions) (its month of traffic, its egress settings, its address, the language of its notices, its billing address and tax id), glac.usage(ListOptions) and glac.usageReport(UsageOptions) (what was used), glac.billing() and glac.updateBilling(BillingOptions) (the plan, its meters and credit, the subscription), glac.balance(), glac.updateBalance(BalanceOptions), glac.topUp(usd) and glac.topUp(usd, TopUpOptions) (Credits, auto reload, top-ups), glac.charges() and glac.ledger(). The bill and the project are a control plane’s; a node that stands alone answers them with its own 404.

The data of an event. Every type of event the control plane has has a record of its data inside Event, named after the description’s schema of it, whose of(event) reads an event of its types and is null of another’s (Event.Database.of(e)). A database’s: Event.Database (database.created, with its region and PostgreSQL version; database.deleted, with final_snapshot_id, the snapshot of its Drive kept seven days), Event.DatabaseBranch (database.branch_created, with its parent; database.branch_deleted, with its reason), Event.DatabaseRestored (database.restored: the moment at, and old_branch_id, the branch the state before is kept as), Event.DatabaseArchive (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 Event.DatabaseGap. The others likewise: a sandbox’s (Event.SandboxSlept, Event.SandboxWoke, Event.SandboxMoved, Event.SandboxDeleted, …), an app’s and its keys’ (Event.App, Event.AppFailed, Event.KeyCreated, …), the project’s deploys and key, backups, domains, destinations and Drives’ snapshots (Event.ProjectDeployed, Event.Backup, Event.Domain, Event.Destination, Event.DriveSnapshot, …), and the account’s plan, top-ups, refunds, withdrawals, balance, Credits, storage, egress cap, spend limits, hold and debts (Event.SubscriptionPeriod, Event.TopupCollected, Event.WithdrawalReceived, Event.Balance, Event.InDebt, …). A field that not every event of a type has, or that is null, is null (a number of them a Long or a Double).

Webhooks, API keys, spend limits, the project. glac.webhooks().create(url, new WebhookOptions()…) 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. glac.keys().create(name, scopes, expiresAt) makes an API key (the key itself, key(), is in that answer alone); get, list, delete. glac.limits() and glac.updateLimits(50.0) are the project’s spend limit and what was spent this month (null takes the limit away), and sbx.limits(), sbx.updateLimits(…) a sandbox’s own. glac.requestLimit(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 glac.limitRequests(new ListOptions()) and glac.limitRequest(id) read them with the operator’s answers (a LimitRequest: status pending, granted or refused, granted, answer). Event.InstanceRestarted.of(event), Event.InstanceUpgrade.of (instance.upgraded, .reverted, .upgrade_failed) and Event.LimitRequestAnswer.of read those events’ data; a sandbox’s (and an instance’s) info().startCommand() says how its start command runs, how often it was started again in its machine, and how it last ended. glac.updateProject(30) sets after how many days asleep its sandboxes are deleted (null: 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 updateProject; setting a sandbox’s limit needs write.

Log destinations, the audit log, the billing documents. glac.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, new DestinationOptions().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). glac.audit(new ListOptions().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. glac.statement("2026-09") is a month’s statement (null 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), glac.invoices() the invoices at Stripe (with the PDF’s link), glac.notices() the mail the account was sent, glac.withdrawals(new ListOptions()) 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 glac.withdraw(chargeId, name, 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.

The account’s email() is where its notices go, which new AccountOptions().email(address) sets: emailVerified() says whether it is verified (only a verified address is mailed: one that is not gets a link first), and emailUndeliverable() (an Account.EmailUndeliverable: why, since, detail) that mail to it bounced; meanwhile the notices wait (where notices go). The account’s language() is the language its notices are written in (an Account.Language: code “en”, “de” or “fr”, and source “account”, “billing_address” or “default”); new AccountOptions().language("de") chooses it, and noLanguage() takes the choice back, so that the billing address says again. The acknowledgement of a withdrawal and the confirmation of a purchase are written in it; every other notice is English.

The account’s keeps() (an Account.Keeps, behind a control plane; null on a node by itself) is what the key’s project keeps of Drives and volumes, by the numbers a create is held to (403 drive_limit_reached, volume_limit_reached), each with what the project has: volumes (an Account.KeepsCount: limit, used, and source, “plan” or “operator”), volumeBytes (an Account.KeepsSize: how large one may be, and its source), volumesBytes (an Account.KeepsTotal: how large all of them may be together, limit null for no limit, and used) and unsizedBytes, the size of one made with no size. A number of the account’s own (“operator”) is asked for with glac.requestLimit("volumes", …) or "volume_bytes".

Buying at once (startNow). 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. startNow() carries that request: glac.topUp(20, new TopUpOptions().startNow()), new BillingOptions().plan("paid").startNow() (Paid, bought from Free) and new BalanceOptions().autoReload(true).startNow() (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: a GlacException 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 Event.AutoReloadNoRequest.of; an account with no card on record, auto_reload.no_card and Event.AutoReloadNoCard).

Errors

A non-zero exit code is a result: read res.exitCode(). An error of the API throws GlacException with status(), type(), code(), param(), retryable(), requestId() and message(), and docsUrl(), which leads to the code on the errors page; so does a call that got no answer (status() 0, type() unavailable or timeout). It is the platform’s error, whichever product the call is of. 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; onResponse 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; idempotencyKey(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. Glac, its namespaces, Sandbox, Command and the files object may be used from several threads. The SDK starts one daemon thread of its own, which watches event streams.