Skip to content

Operations

How slow calls report progress, and how to retry a call safely.

Some calls take a while: creating, starting, stopping and deleting a sandbox, for example. These calls return an operation that tracks the work.

The SDKs wait for you

By default an SDK call waits for its operation and returns the finished resource. Pass wait to limit how many seconds the call waits:

const sandbox = await sutra.sandboxes.create({ id: "build-42", wait: 30 });

wait limits only your call. If it ends first, the work continues, and you can read the resource or the operation later.

Operation resources

An operation has the name operations/{operation} under your project. Its metadata names the resource it works on from the start, and when it is done, its response is that resource. You can get, list and wait for operations, and cancel those where it makes sense.

Access to an operation follows its resource: if you can read the sandbox, you can read the operation that creates it.

Retry safely

Every call that changes something takes a requestId. Send the same requestId again and you get the result of the first call instead of a second change. The SDKs generate one for each call, so their own retries are safe. Pass your own when you retry across process restarts:

await sutra.sandboxes.create({ id: "build-42", requestId: "7d1c6a0e-4f0b-4b4e-9c55-3f0a9b8e2d11" });

A requestId is any string up to 128 bytes; a UUID works well. Reusing one with a different request fails with ALREADY_EXISTS.

Concurrent changes

Every resource you can change has an etag. Pass it to update, delete, stop or start to make the call fail with ABORTED if someone changed the resource since you read it.

Type to search…

↑↓ navigate↵ selectEsc close