ol.smolvm.cloud

Returns validated connection configuration from opts.

Starts the HTTP request described by operation using client.

Returns a java.util.concurrent.CompletableFuture of the decoded result. Use @result to wait, or (deref result timeout-ms timeout-value) to bound the wait. The request continues after a wait timeout. HTTP and transport failures complete the future exceptionally with ex-info containing :code, plus :status and :request-id when available. Deref wraps failures in ExecutionException. Its cause carries the error data. Empty successful responses resolve to nil.

An operation’s :timeout overrides the client’s default HTTP timeout. Use job-cancel to terminate a remote job.

Additional result kinds, with the same one-request CompletableFuture contract:

exec-stream resolves to a Closeable event reader. Call stream-read to consume its response, then close it. Cancellation before delivery closes a late body.

checkpoint-upload-part sends one raw PUT to its signed URL, without API bearer, cookies, redirects or automatic retries. Its file section is opened during invocation and closed on completion/failure/cancellation, including failure before the request starts. The future resolves to nil after a successful PUT. Cancellation cannot prove that the remote part was not stored.

Absolute storage URLs are accepted only for the checkpoint part operation, not as a general override to authenticated API operations. All new operations keep existing sanitized errors. File paths, signed URLs, lease tokens and progress callback exception messages/causes are not attached to errors.

Describes listing machines. Result: a vector of full info maps.

Describes fetching machine id. Result: its full info map.

Fields include :id, :name, :state, :ready, :source, :resources, :ports, :labels, and :created-at when supplied by the server. Returned environment values are redacted by the service.

Describes creating a machine from config.

Result: the server’s machine-info record, including its state. Resource allocation defaults come from the server.

Durations round up to whole seconds on the wire.

Additional options:

Nonempty allowlists select restricted networking and cannot be combined with :network? false. Empty lists use :network? or the service setting. The server validates CIDR/host syntax. Create does not start or wait. For a branchable source, separately invoke start with {:branchable? true}. Cache lifetime is independent of the machine. Deleting a machine does not request cache deletion. Cache version/slot overrides are not introduced.

Describes starting machine id from its disks. Result: the server’s response. HTTP timeout defaults to 30 minutes.

Adds an options arity. Existing one-argument behavior is unchanged.

This does not wait for readiness.

Describes stopping machine id without deleting its storage. Result: the server’s response.

Describes pausing machine id with its execution state preserved. Result: machine info. HTTP timeout defaults to 30 minutes.

Describes resuming the preserved execution state of machine id. Result: machine info. HTTP timeout defaults to 30 minutes.

Describes deleting machine id and its storage.

Result: the usage report when requested, otherwise nil.

Describes running nonempty argv vector command on machine id.

Result: :exit-code, :stdout, :stderr, :stdout-bytes, :stderr-bytes, :stdout-truncated?, and :stderr-truncated?. The result includes server metadata such as :machine-id, :duration-ms, and :user. Nonzero exit codes are results. Missing exit status is an invalid response.

Cloud text can be truncated. Byte fields decode base64 when supplied, otherwise encode the returned text as UTF-8. Invalid base64 is an error.

An explicit guest timeout sets the HTTP budget to that rounded timeout plus 30 seconds, with a minimum of 60 seconds.

Additional option:

Sent as the output query parameter. Older servers may ignore it. The existing result shape and strict exit/base64 checks are unchanged. Missing text fields become empty strings, even when byte fields contain output.

Describes a harmless command that checks support for guest user on machine id.

Result: user when the server confirms the requested account. Otherwise it throws with code NOT_SUPPORTED or the command failure. Invoke this check before an exec that specifies :user.

Describes reading absolute guest path on machine id.

Close returned streams after use. Stream mode reads the HTTP body incrementally.

Describes writing data to absolute guest path on machine id.

Accepts a byte array, UTF-8 string, java.io.File, or java.nio.file.Path. File and Path bodies are streamed by the HTTP client during invocation. Uploads are limited to 100 MiB by the service.

Result: nil on success. Use exec with chmod to set permissions.

Describes fetching workload logs for machine id. Result: text.

Describes replacing machine id’s published ports with `ports.

ports is a vector of guest TCP port numbers. An empty vector removes every published port. Result: machine info with allocated host ports.

Returns authenticated endpoint data for guest TCP port on machine id.

Returns {:method :get :uri string :headers map :ws-uri string}. Pass this map directly to babashka.http-client/request. Use assoc to set request options such as :method, :body, or :as. This pure helper uses client to construct the URLs and bearer header. The returned headers contain a credential.

Optional path selects a path beneath the guest service. Defaults to root.

Describes starting a background job with argv vector command on machine id.

Result: job info with :id, :machine-id, :command, :state, and :created-at. Job states are running, exited, or lost. Without :user, the job runs as the image’s configured account.

Guest timeout sends SIGTERM, normally producing exit code 143.

Additional option:

Invoke user-check separately before use. Job replies do not prove user support. Existing timeout rounding and other options are unchanged.

Describes listing jobs on machine id. Result: a vector of job-info maps.

Describes fetching job-id on machine id.

Result: job info, including :exit-code and :finished-at when available. :stdout-bytes and :stderr-bytes are byte counts. A lost job’s machine stopped or restarted while the job was running.

Describes fetching a slice of job-id output on machine id.

Result: {:stream string :offset n :next-offset n :data bytes :eof boolean}. Data decodes base64 when supplied, otherwise encodes returned text as UTF-8. EOF means the job has finished and this slice reaches the end of the stream.

Describes sending SIGTERM to job-id on machine id. Result: job info. A terminated job normally exits with code 143.

Describes fetching the usage report for machine id.

Result: {:machine-id string :from string :to string :usage map :cost map}. Usage includes :total-uptime-seconds, :cpu-hours, :memory-gb-hours, :disk-gb-hours, and :egress-gb. Costs are integer micro-dollars, including :total-micros and :amount-due-micros.

Describes creating child name from branchable source id. Result: child machine info. Name is nonblank. No readiness wait or legacy-route fallback is performed. The source can briefly pause during branching.

Describes one transactional branch batch from source id. Names are a nonempty vector of distinct nonblank strings. Result: a vector of child info maps in service order. No waits or legacy-route fallback occur.

Branchable-child, count and name-prefix selectors are not provided.

Describes capturing machine id. Result: durable checkpoint metadata. HTTP timeout defaults to 30 minutes. No download occurs. Download URLs are sensitive. Local destination/store options do not apply.

Describes listing machine `id’s checkpoints. Result: a vector of metadata maps. Download URLs can be sensitive.

Describes restoring durable checkpoint-id to new machine name. Result: machine info. Both arguments are nonblank. No file upload, start or wait.

Describes allocating an upload of positive size-bytes. Result: a map with checkpoint metadata, positive :part-size-bytes and a vector of :upload-urls. URLs authorize raw storage PUTs and must not be logged. This does not stat/read a file, transfer parts or complete the upload.

Describes one raw PUT of a file section to presigned HTTPS upload-url.

file is a nonblank path string, File or Path. Construction performs no file I/O. The URL cannot contain user info or a fragment. Result: nil on HTTP 2xx. No API authorization, cookies, redirects or retries. URL query bytes are kept.

Invoke opens a fresh file section, checks that it fits a regular file, sends exactly its declared Content-Length and closes its stream on every outcome. Keep the file unchanged until completion. No caller-supplied InputStream is accepted. A new invocation opens a fresh section and starts its count at zero. Progress measures sender reads, not storage acknowledgements. Callbacks can reach length before the HTTP outcome is known. Calls are serialized within one PUT, not across different invocations. Callback failure fails the request with PROGRESS_FAILED. Source file errors use FILE_ERROR. No upload plan, part scheduling, retry/reset policy or aggregate progress is implemented here.

Describes completing checkpoint-id after every part PUT succeeded. Result: checkpoint metadata. HTTP timeout defaults to 30 minutes. Sends no ETag list. Does not transfer parts, retry or delete a failed upload.

Describes deleting durable checkpoint-id and its stored artifact. Result: nil. The service can return HTTP 409 while referenced. Incomplete-upload abort semantics are not established. This endpoint is a service-docs addition to Go.

Describes creating/retrieving a sharing link for machine id. Result: share metadata. URL/token are credentials. Revoke with unshare.

Describes revoking machine `id’s sharing link. Result: nil.

Describes creating public port links for machine id. Result: integer guest-port to URL map. URLs are credentials. This changes access, unlike endpoint. Revoke all links with port-links-revoke.

Describes revoking every public port link for machine id. Result: nil.

Describes leasing a provisioned child from source machine id. Result: machine-id, secret owner-token and optional machine info. No client wait, heartbeat scheduling or cleanup. Repeated lease IDs use service idempotency, not a retry performed by invoke.

Task/result map keys keep their spelling. Do not log task/files/secrets/token.

Describes renewing lease-id with secret owner-token. Result: nil. Arguments are nonblank. No future heartbeat is scheduled.

Describes completing lease-id with secret owner-token. Result: nil. Completion can trigger child cleanup. Verify resource state separately.

Describes fetching lease-id. Result: full lease status map. Payload fields can contain sensitive task data.

Describes exporting stopped machine id. Result: service metadata map. HTTP timeout defaults to 30 minutes. This can create durable data with no established cleanup operation. Confirm retention/cleanup before invocation.

Describes creating cache name. Result: cache metadata. Name uses lowercase ASCII letters, digits, dots, underscores or hyphens. Requires a supporting plan. Cache storage has a separate lifetime from machines.

This is a pinned Node/service-docs addition to Go.

Describes fetching cache id-or-name. Result: cache metadata and versions. Useful for version inspection and NOT_FOUND verification after deletion.

Describes publishing the configured cache of stopped machine id. Result: cache and newly published version metadata. Timeout is 30 minutes. Appends a version. Does not configure or create the cache resource.

Describes deleting cache id-or-name and ALL versions. Result: nil. The service refuses deletion while used by a running machine. This does not target one version. Confirm no other workload needs this shared resource.

Describes launching detached argv command on machine id. Result includes positive pid parsed from stdout pid=<n>, stdout/stderr and byte fields plus service metadata. Missing PID is INVALID_REPLY. No exit status is synthesized. A launcher status is not remote child completion.

Uses client HTTP timeout. Supplied stdin, guest timeout, background, stream or output flags fail NOT_SUPPORTED. This is not a cancellable job.

Describes SSE execution of argv command on machine id. Result through invoke: a Closeable event reader. Close it after use. Uses pinned /exec/stream, no route fallback, and requires text/event-stream.

Header timeout follows exec’s budget, not a timeout on later body reads. Background/output flags are unsupported. No reconnect, replay or event queue. Closing the reader does not promise remote command termination.

Consumes one event from an already-open cloud exec stream, blocking as needed. Does not submit another HTTP request. Returns stdout/stderr events with :kind and UTF-8 :data bytes, exit with integer :exit-code, or error with :message. Multiple SSE data lines join with newline. This is text, not binary-exact output.

Exit/error is terminal and closes the body before return. Later reads or reads after explicit close return nil. CRLF, fragmented UTF-8 and an unterminated final event are supported. Comments and unrecognized events are ignored. Invalid UTF-8/exit JSON or EOF without a terminal event throws INVALID_REPLY. A frame above 1 MiB raw wire bytes, including ignored lines/line endings, throws LIMIT_EXCEEDED. Enforce bounds while accumulating each line. Read/parse errors close the body. Transport errors are sanitized. Service error-event text can contain sensitive data and is never logged by the SDK. Use one reader thread. Close from another thread releases a blocked read, returning nil if closure caused the failure. Interruption alone is not a guaranteed way to stop body reads.