How to sequence cloud work and clean up resources

connect tries an exact ID, then an exact name only after not-found. It does not start or wait for a machine. Start it separately and wait for readiness:

The wait uses server readiness, with a running-state fallback only when the ready field is absent. It does not test your application’s health. A stopped, deleted or error-state machine fails when not ready. Timeout does not delete it. Agent probing is optional and off by default.

For one guest-port change, use workflow/publish or workflow/unpublish:

These read and replace the port set and return updated machine info. Serialize port changes across all callers. The update is not atomic and is not retried. This is different from granting public access with cloud/port-links.

Prepare a branchable source with :branchable? true on both cloud/create and cloud/start. Use a distinct child name. The helper creates the child, waits, executes, then requests deletion:

Nonzero exit is an ordinary exec result. The source is never deleted. Cleanup targets only a child ID returned by successful creation, never a guessed name. Normal success/failure waits for the cleanup attempt. Cleanup failure after successful execution fails the future. If execution also fails, that error is primary and cleanup failure is suppressed.

For children that must survive the call, use cloud/branch or cloud/branch-batch through invoke instead. These do not wait or delete children. Batch names must be distinct. Multiple children with published ports require host port zero for allocation. Track every returned ID for later cleanup.

For a still-pending task, use a limited wait instead of @task:

Timed dereference does not cancel work. Explicit cancellation marks the future cancelled immediately, stops further ordinary scheduling and requests cancellation of active work where possible. Required cleanup can continue. A late branch response containing a child ID still triggers deletion.

A cancelled future is not proof of remote rollback, command termination or finished cleanup. It cannot later deliver cleanup errors or newly learned IDs. Await normal completion when you need a cleanup outcome. After uncertain mutations, inspect remote resources and explicitly reconcile them.

Use a job when remote cancellation is part of the task:

job-wait returns final info for exited jobs, including nonzero exits. A lost job fails. job-read-all returns bytes for one stream through EOF. Its default aggregate limit is 16 MiB, with pages of at most 1 MiB. It does not merge stdout and stderr. Use raw job-output pages for larger output. Empty nonterminal replies pause before another long poll.

Timeout/cancellation of either helper does not cancel the remote job. Invoke cloud/job-cancel explicitly when needed. Before using :user, invoke cloud/user-check. That verifies exec user support, not that jobs honor the account.

To upload a file and apply permissions, use the two-request helper:

Without :mode, chmod is skipped. Zero explicitly removes permissions. The sequence is not atomic. Failed chmod leaves the uploaded file in place. Use raw cloud/file-write when no chmod is required.

Capture returns checkpoint metadata, not a downloaded file:

Restore without an egress policy uses blocked networking, not the checkpoint’s previous policy. Supply :egress-policy explicitly if access is required. cloud/checkpoints lists captures for a machine. Treat download URLs as secrets. After deleting machines that reference the checkpoint, request cloud/checkpoint-delete. Referenced checkpoints can produce HTTP 409.

Keep the nonempty checkpoint file unchanged during transfer. The helper checks file access before allocation, uploads exact file sections, then completes:

Defaults match Go’s part policy: four concurrent parts, four attempts per part, and retry delays of 2, 4 and 8 seconds. Transport failures and every non-2xx part response can retry, within the total deadline and attempt limit. Allocation and completion are not retried. File preparation, validation and callback errors do not become HTTP retries. The default total budget is 30 minutes.

Progress counts sender reads, not storage acknowledgements. Callbacks are serialized across parts. A failed attempt resets that part’s counter to zero, so aggregate progress can move backward. Reaching total does not mean storage accepted the data. Wait for normal future completion. Callback failure stops further scheduling. Keep callbacks short.

The helper closes local part streams. Cancellation is immediate, but active work/resource cleanup can finish later. No partial upload is automatically deleted. Normal failures include a known checkpoint ID. Incomplete-upload abort/deletion semantics are not established.

Use raw steps when the application must record an allocation ID before transfer or supply application scheduling. Determine file size before allocation:

Save allocated-id securely before sending parts. Do not log signed URLs. Validate plan geometry against file size. This fragment sends only the first part, not a complete upload:

The builder performs no file I/O. Invocation opens a fresh bounded section and sends one raw PUT with exact Content-Length. It closes that section afterward. Storage requests receive no API bearer or cookies and follow no redirects. Do not forward authenticated API headers to storage URLs. These are raw parts, not multipart/form-data. Raw invoke does not retry.

Send every exact section to its corresponding URL and wait for every success before completion:

Completion sends no ETags. If any part fails, do not complete until your application has resolved the failure. Use the automatic helper unless you need this control.