withruntime 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e403c64b0fd311fd7ba3fb2a9fab6304afda36100ebc1fe0bd30f6b8f82bcece
-  data.tar.gz: a6eb390df90ab8f676704e8181c535d2dd23a41eebec44efdbf0219f46f675c6
+  metadata.gz: f471d00ffe082a8a507a514dda86ce4062342e2b5f0e27153309d094a27fb35b
+  data.tar.gz: 988ff09e0b418238acb50eba94f81bfa59c579e8103a81bd8b43e551c692f70e
 SHA512:
-  metadata.gz: a9994df04fad6ef2af83e9c1bb92e037b42e048bdf2806465d5969e43f7bc4ba9862fcbc77036d61b7d826579f9e0c316e302b05822cf6c326e6739a657ef677
-  data.tar.gz: de3343c87c44ea8dbed899137c0034de4683f64cb2ff44029ffcfbd6da98652f68d4fae8b53fbc90d3dc00a4ba5305d0239190eb756d8dff95ee54f0c0584043
+  metadata.gz: e4e8625a16d34f127de6bda5733b2645b733cb7a06ec3af65d87fc48a6b804d17c6d22f03cc657bd3cb64d8c29e3269cc42047aed28b0cf084f25a6cba9a048e
+  data.tar.gz: 33311be1f0d80a9ff3fd613acd21a02e0535945271e08af9cdf4b83d1021310479681bb7f07e8acb36663654d130fa29c635dcf796b1489cb9fbeec73d1f9a25

data/lib/withruntime/client.rb

@@ -33,7 +33,7 @@ module WithRuntime
     # +timeout+: seconds for each call, retries included (300).
     # +max_retries+: of transport failures, 429, 502, 503 and 504 (4).
     # +max_connections+: calls in flight at once; streams do not count (32).
-    # +wait_for_capacity+: seconds a sandbox create keeps retrying, with the
+    # +wait_for_capacity+: seconds a sandbox create, wake or restart keeps retrying, with the
     # same key and input, when the slots without credit, quota or region are full (120; 0 fails at once).
     def initialize(api_key: nil, base_url: nil, timeout: 300, max_retries: 4, max_connections: 32,
                    wait_for_capacity: 120, env: ENV, in_sandbox: -> { Credentials.in_runtime_sandbox? })

data/lib/withruntime/products.rb

@@ -104,7 +104,7 @@ module WithRuntime
     end
   end
 
-  # +runtime.limits+: whether this key is read-only, and what its agent may still spend today.
+  # +runtime.limits+: whether this key is read-only, and what its agent may still spend today, plus +account+: the account's limits (limit, label, unit, max, used), or nil.
   class Limits < Product
     def get = Record.new(@t.json("GET", "/v1/limits"))
   end

data/lib/withruntime/sandbox.rb

@@ -19,6 +19,12 @@ module WithRuntime
     # free, up to +wait_for_capacity+ seconds (the client's, two minutes by default).
     #
     #   runtime.sandboxes.create(labels: { team: "search" }, timeout_seconds: 900)
+    #
+    # +spread_from: [id, ...]+ (one to 16 ids of your own sandboxes or snapshots)
+    # starts it on a server none of them is on. With no other server that has
+    # room, the create raises +no_capacity+ and nothing is made or charged.
+    # +sbx.info.placement+ is an opaque tag for its server: the same tag means
+    # the same server.
     def create(wait: true, idempotency_key: nil, wait_for_capacity: nil, **fields)
       room = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
       info = @t.json("POST", "/v1/sandboxes", body: Fields.body(fields), wait: wait ? 60 : 0,
@@ -118,8 +124,12 @@ module WithRuntime
 
     # Carries on a paused sandbox, with its memory and processes;
     # +timeout_seconds+ is its new time limit, for a sandbox that has one.
-    def wake(wait: true, timeout_seconds: nil, idempotency_key: nil)
-      lifecycle("wake", timeout_seconds ? { "timeoutSeconds" => timeout_seconds } : {}, wait, idempotency_key)
+    # When its server has no room (+no_capacity+) it waits for room, as +create+
+    # does, up to +wait_for_capacity+ seconds (the client's, two minutes by
+    # default; 0 fails at once), sending the same idempotency key each time.
+    def wake(wait: true, timeout_seconds: nil, idempotency_key: nil, wait_for_capacity: nil)
+      lifecycle("wake", timeout_seconds ? { "timeoutSeconds" => timeout_seconds } : {}, wait, idempotency_key,
+                room: room_for(wait_for_capacity))
     end
 
     # Moves a sandbox's time limit on, at most an hour ahead of now. A sandbox
@@ -130,7 +140,10 @@ module WithRuntime
     def set_retention(days, idempotency_key: nil) = lifecycle("retention", { "days" => days }, false, idempotency_key)
 
     # Starts a stopped persistent sandbox again from its disk. Memory is not kept.
-    def restart(wait: true, idempotency_key: nil) = lifecycle("restart", {}, wait, idempotency_key)
+    # Waits for room like +wake+ when its server is full.
+    def restart(wait: true, idempotency_key: nil, wait_for_capacity: nil)
+      lifecycle("restart", {}, wait, idempotency_key, room: room_for(wait_for_capacity))
+    end
 
     # Changes name, labels, auto_wake, idle_pause_seconds, persistent or
     # max_total_cost_micros; fields left out stay as they are, and
@@ -203,8 +216,10 @@ module WithRuntime
     end
 
     # Keeps this sandbox's whole machine as a snapshot to start new sandboxes
-    # from. A running sandbox is paused for the moment it takes, then woken; a
-    # paused one stays paused. A sandbox with volumes cannot be snapshotted.
+    # from. A running sandbox is paused by the server for the moment it takes
+    # and woken once the capture is over (one still capturing when the call
+    # answers stays paused until it is ready); a paused one stays paused. A
+    # sandbox with volumes cannot be snapshotted.
     def snapshot(name: nil, labels: nil, retention_days: nil, idempotency_key: nil)
       refresh
       # Straight after a fork or a wake the sandbox is still resuming, and
@@ -213,15 +228,11 @@ module WithRuntime
       if %w[resuming starting].include?(state) then wait_for("running")
       elsif state == "pausing" then wait_for("paused")
       end
-      running = state == "running"
-      pause if running
-      begin
-        Record.new(@t.json("POST", path(":snapshot"),
-                           body: Fields.body(name: name, labels: labels, retention_days: retention_days),
-                           wait: 10, key: idempotency_key))
-      ensure
-        wake if running
-      end
+      # The server pauses a running sandbox itself: a client pause and wake
+      # would be two more round trips.
+      Record.new(@t.json("POST", path(":snapshot"),
+                         body: Fields.body(name: name, labels: labels, retention_days: retention_days),
+                         wait: 10, key: idempotency_key))
     end
 
     # CPU and memory over a range: 15m, 1h, 6h, 24h, 7d or 30d.
@@ -230,19 +241,20 @@ module WithRuntime
     # Runs a command and returns its exit code and output. A String runs under
     # +bash -c+; an Array runs the program directly, with no shell.
     #
-    # +cwd+ (default /workspace), +env+ (merged over the sandbox's; put secrets
-    # here), +stdin+, +timeout+ (seconds, default 60, up to a day; a timeout is
-    # a result, not an error), +on_stdout+ and +on_stderr+ (stream the command;
-    # the result keeps everything), and +check+ (raise CommandError on a
-    # non-zero exit or a timeout).
-    def exec(command, cwd: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
+    # +cwd+ (default /workspace), +user+ ("sandbox", the default, or "root",
+    # through the sandbox's passwordless sudo), +env+ (merged over the
+    # sandbox's; put secrets here), +stdin+, +timeout+ (seconds, default 60, up
+    # to a day; a timeout is a result, not an error), +on_stdout+ and
+    # +on_stderr+ (stream the command; the result keeps everything), and
+    # +check+ (raise CommandError on a non-zero exit or a timeout).
+    def exec(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, on_stdout: nil, on_stderr: nil,
              check: false, idempotency_key: nil)
       streamed = on_stdout || on_stderr || (timeout && timeout > 60)
       result = if streamed
-                 collect(exec_stream(command, cwd: cwd, env: env, stdin: stdin, timeout: timeout,
+                 collect(exec_stream(command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
                                               idempotency_key: idempotency_key), on_stdout, on_stderr)
                else
-                 body = command_body(command, cwd, env, stdin, timeout)
+                 body = command_body(command, cwd, env, stdin, timeout, user)
                  CommandResult.new(@t.json("POST", path(":exec"), body: body, key: idempotency_key,
                                                                   timeout: timeout && (timeout + 60)))
                end
@@ -254,14 +266,14 @@ module WithRuntime
     # Runs a command and yields its events as they happen: start, stdout,
     # stderr, exit (each a Hash). Resumes by itself when the server ends a long
     # stream, so it never drops output. Without a block, an Enumerator.
-    def exec_stream(command, cwd: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, &block)
+    def exec_stream(command, cwd: nil, user: nil, env: nil, stdin: nil, timeout: nil, idempotency_key: nil, &block)
       unless block
-        return enum_for(:exec_stream, command, cwd: cwd, env: env, stdin: stdin, timeout: timeout,
+        return enum_for(:exec_stream, command, cwd: cwd, user: user, env: env, stdin: stdin, timeout: timeout,
                                                idempotency_key: idempotency_key)
       end
 
       longest = ApiDefaults::STREAMED_EXEC_TIMEOUT_SECONDS
-      body = command_body(command, cwd, env, stdin, timeout || longest).merge("stream" => true)
+      body = command_body(command, cwd, env, stdin, timeout || longest, user).merge("stream" => true)
       handed_over = nil
       process_id = nil
       cursor = 0
@@ -350,8 +362,8 @@ module WithRuntime
     # once. It outlives your connection; +process(id)+ gets it back.
     # +pipe_stdin: true+ keeps input open for +write+; +pty: { cols:, rows: }+
     # gives it a terminal.
-    def spawn(command, cwd: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil, idempotency_key: nil)
-      body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout)
+    def spawn(command, cwd: nil, user: nil, env: nil, timeout: nil, stdin: nil, pipe_stdin: false, pty: nil, idempotency_key: nil)
+      body = command_body(command, cwd, env, pipe_stdin ? nil : stdin, timeout, user)
       body["stdinMode"] = "pipe" if pipe_stdin
       body["pty"] = Fields.body(pty) if pty
       SandboxProcess.new(self, @t.json("POST", path("/processes"), body: body, key: idempotency_key))
@@ -367,14 +379,17 @@ module WithRuntime
 
     private
 
-    def lifecycle(verb, body, wait, key)
-      @info = Record.new(@t.json("POST", path(":#{verb}"), body: body, wait: wait ? 60 : 0, key: key))
+    def lifecycle(verb, body, wait, key, room: 0)
+      @info = Record.new(@t.json("POST", path(":#{verb}"), body: body, wait: wait ? 60 : 0, key: key, room: room))
       self
     end
 
-    def command_body(command, cwd, env, stdin, timeout)
+    def room_for(wait_for_capacity) = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
+
+    def command_body(command, cwd, env, stdin, timeout, user)
       body = command.is_a?(Array) ? { "argv" => command.map(&:to_s) } : { "command" => command.to_s }
       body["cwd"] = cwd if cwd
+      body["user"] = user.to_s if user
       body["env"] = env.to_h { |key, value| [key.to_s, value.to_s] } if env
       body["stdinBase64"] = [stdin.to_s.b].pack("m0") unless stdin.nil?
       body["timeoutMs"] = (timeout * 1000).round if timeout

data/lib/withruntime/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WithRuntime
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: withruntime
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Runtime
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies: []
 description: 'Linux sandboxes for agents, and every other Runtime Cloud product: streaming
   commands and terminals, files and watches, images, durable volumes and backups,