withruntime 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8912abd064916dd450a7fb5b9f0c1610c79b65918cf63a3a599b5906d46e3577
-  data.tar.gz: c7e663ef88244b43c2c761bb6f55e43ea147631e7c22b9c19b7d68789510c0e0
+  metadata.gz: 53b4e63218b0587cacbd8e0ad8ec583ba4ce9b32ec0b792208b8f70750b5acd5
+  data.tar.gz: 3461a8000fc4817de3f06c6f6f40b6e5d29b49312a4e1f9c9dc94a649e91b8ae
 SHA512:
-  metadata.gz: 041d53fd9761a1f1e0c9f94cfb70a77c6f0805329dbfbc3523f08cb7024ad4c3bcd06373e08fa6a391823ca48688d786be6643a2b2f460ad1c14c43ee8750c2b
-  data.tar.gz: 4ad9e1df60b31416e7d35abb1499a2fd5e1c329e314a91d9f440f6b56ec2bde9975ae7765a030187f8c6dff540ad8268468188d301de716ae83fd3758117493c
+  metadata.gz: b1bb2aea12c2959b3afcd694ad90124d1c04fcf60201fdece3f5f1264b40bfa3b3f8deec865c5265d806b6e8c389ebacfd4da833648133fdba93b9ece3d7352f
+  data.tar.gz: d0238775905bea2408a2d930a402f49a4001bf900c3a8c13acbd511aaf5c486b7b01da8b5f93dfc188e50b696e135b8b92dfd75a7f9c74f5d4dcbdfcce63b668

data/lib/withruntime/api_defaults.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # Every value this SDK sends the API for a bounded time field when the caller
+  # names none, in one place. packages/cloud/tests/sdk-defaults.test.ts holds
+  # each inside the range the API's registry gives that field, and the same
+  # names in the JavaScript, Python, Go and Java SDKs to theirs. The suffix is
+  # the unit; a new default goes here, under a name that test maps to its field.
+  module ApiDefaults
+    # A server-side wait for a state (GET /v1/sandboxes/{id}?waitFor=).
+    WAIT_FOR_TIMEOUT_SECONDS = 60
+    # A streamed exec's command limit when none is given: the API's longest.
+    STREAMED_EXEC_TIMEOUT_SECONDS = 86_400
+    # The time keep_alive keeps ahead of a time limit, and so the most it extends by.
+    KEEP_ALIVE_MARGIN_SECONDS = 600
+  end
+end

data/lib/withruntime/client.rb

@@ -7,25 +7,36 @@ module WithRuntime
   # is safe for use from many threads and keeps its connections open.
   #
   #   runtime = WithRuntime::Client.new # RUNTIME_API_KEY, or this machine's saved connection
-  #   sbx = runtime.sandboxes.create(funding: "trial")
-  #   puts sbx.exec("python3 -c 'print(6 * 7)'", check: true).stdout
+  #   sbx = runtime.sandboxes.create
+  #   sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n")
+  #   puts sbx.exec("python3 /workspace/invoice.py", check: true).stdout
   #   sbx.stop
   #
   # Every product is +runtime.<product>.<verb>+. Money is integer microdollars
   # (1,000,000 is one US dollar).
+  # The account's networks: +wireguard+, a tunnel from your own network into
+  # your sandboxes.
+  Networks = Struct.new(:wireguard)
+
+  # The day the 6 October 2026 rename stops serving its old names, set when it
+  # ships (packages/cloud/src/product-names.ts); nil until then.
+  RENAME_RETIRES = nil
+
   class Client
     attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :limits, :referrals,
-                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :addresses, :tunnel, :sso, :mcp
+                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp
 
     # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
     # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
+    # Inside a Runtime sandbox, calls for https://api.withruntime.com go to
+    # http://runtime.internal.
     # +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
-    # same key and input, when the trial, quota or region is full (120; 0 fails at once).
+    # +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)
+                   wait_for_capacity: 120, env: ENV, in_sandbox: -> { Credentials.in_runtime_sandbox? })
       origin = Credentials.origin(base_url || env["RUNTIME_API_URL"].then { |url| url.nil? || url.empty? ? DEFAULT_BASE_URL : url })
       key = api_key
       key ||= env["RUNTIME_API_KEY"] unless env["RUNTIME_API_KEY"].to_s.empty?
@@ -34,7 +45,10 @@ module WithRuntime
       raise ArgumentError, "The Runtime API key contains whitespace." if key.match?(/\s/)
       raise ArgumentError, "max_retries cannot be negative." if max_retries.negative?
 
-      @transport = Transport.new(api_key: key, base_url: origin, timeout: timeout, max_retries: max_retries,
+      # The saved key is found by the origin as given; the calls go where that
+      # origin is reachable from here.
+      @transport = Transport.new(api_key: key, base_url: Credentials.reachable(origin, in_sandbox: in_sandbox),
+                                 timeout: timeout, max_retries: max_retries,
                                  max_connections: max_connections, wait_for_capacity: [0, wait_for_capacity].max)
       @sandboxes = Sandboxes.new(@transport)
       @snapshots = Snapshots.new(@transport)
@@ -52,18 +66,23 @@ module WithRuntime
       @support = Support.new(@transport)
       @domains = Domains.new(@transport)
       @ports = Ports.new(@transport)
-      @addresses = Addresses.new(@transport)
-      @tunnel = PrivateTunnel.new(@transport)
+      @ips = Addresses.new(@transport)
+      @networks = Networks.new(PrivateTunnel.new(@transport))
       @sso = SSO.new(@transport)
       @mcp = MCP.new(@transport)
     end
 
+    # Renamed on 6 October 2026, one plural word per product: each old name is the product it became, with a warning,
+    # until RENAME_RETIRES, then raises name_retired.
+    def addresses = renamed("addresses", "ips") { @ips }
+    def tunnel = renamed("tunnel", "networks.wireguard") { @networks.wireguard }
+
     def base_url = @transport.base_url
 
     # Who this key is: organization, agent and credential.
     def me = Record.new(@transport.json("GET", "/v1/me"))
 
-    # The account's credit, holds, trial time and per-resource charges.
+    # The account's credit, holds, free time and per-resource charges.
     def usage = Record.new(@transport.json("GET", "/v1/usage"))
 
     # Calls any API path with this client's key, retries, idempotency keys and
@@ -75,5 +94,20 @@ module WithRuntime
       body = {} if body.nil? && !%w[GET DELETE].include?(method)
       @transport.json(method, path, query: query, body: body)
     end
+
+    private
+
+    def renamed(old, new, retires: RENAME_RETIRES, now: Time.now.utc)
+      if retires && now >= Time.utc(*retires.split("-").map(&:to_i))
+        raise Error.new("runtime.#{old} was renamed runtime.#{new} and stopped working on #{retires}.",
+                        code: "name_retired", status: 410, hint: "Use runtime.#{new}.")
+      end
+      @renamed_said ||= {}
+      unless @renamed_said[old]
+        @renamed_said[old] = true
+        warn("Runtime: runtime.#{old} is now runtime.#{new}.#{retires ? " It stops working on #{retires}." : ""}")
+      end
+      yield
+    end
   end
 end

data/lib/withruntime/credentials.rb

@@ -12,22 +12,48 @@ module WithRuntime
   module Credentials
     KEY = /\Artcloud_[a-f0-9-]{36}_[A-Za-z0-9_-]{43}\z/
 
+    BAD_ORIGIN = "Use an HTTPS API origin (or http://runtime.internal inside a sandbox, http://localhost for tests)."
+    # Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
+    # own host sends each request on to the public API over HTTPS. The API runs
+    # on that host, whose addresses a sandbox cannot reach directly. Plain HTTP
+    # because the hop never leaves the machine: from the program to the guest's
+    # own proxy, then over the sandbox's private channel to its host.
+    SANDBOX_BASE_URL = "http://runtime.internal"
+    # A file every Runtime sandbox has; the guest keeps it current.
+    SANDBOX_MARKER = "/run/runtime/environment.json"
+
     module_function
 
-    # An HTTPS origin, or plain HTTP to localhost for tests, with nothing after the host.
+    def in_runtime_sandbox?(marker = SANDBOX_MARKER)
+      File.exist?(marker)
+    end
+
+    # The origin calls for +api_origin+ are sent to from here. In a sandbox the
+    # public API is its own host, which it cannot reach directly, so calls for
+    # it go to runtime.internal; every other origin is left as it is.
+    def reachable(api_origin, in_sandbox: -> { in_runtime_sandbox? })
+      api_origin == DEFAULT_BASE_URL && in_sandbox.call ? SANDBOX_BASE_URL : api_origin
+    end
+
+    # An HTTPS origin, plain HTTP to runtime.internal inside a sandbox, or plain
+    # HTTP to localhost for tests, with nothing after the host. runtime.internal
+    # is reserved and never resolves outside a sandbox, so a key sent there in
+    # plain HTTP never leaves the sandbox's host.
     def origin(value)
       uri = URI(value)
-      local = %w[localhost 127.0.0.1 [::1] ::1].include?(uri.host)
+      internal = uri.host == "runtime.internal"
+      local = %w[localhost 127.0.0.1 [::1] ::1].include?(uri.host) || internal
       unless uri.host && (uri.scheme == "https" || (local && uri.scheme == "http")) && uri.userinfo.nil? &&
-             uri.query.nil? && uri.fragment.nil? && ["", "/"].include?(uri.path.to_s)
-        raise ArgumentError, "Use an HTTPS API origin (or http://localhost for tests)."
+             uri.query.nil? && uri.fragment.nil? && ["", "/"].include?(uri.path.to_s) &&
+             !(internal && (uri.scheme != "http" || uri.port != 80))
+        raise ArgumentError, BAD_ORIGIN
       end
 
       default_port = uri.scheme == "https" ? 443 : 80
       host = uri.host.include?(":") && !uri.host.start_with?("[") ? "[#{uri.host}]" : uri.host
       "#{uri.scheme}://#{host}#{uri.port == default_port ? "" : ":#{uri.port}"}"
     rescue URI::InvalidURIError
-      raise ArgumentError, "Use an HTTPS API origin (or http://localhost for tests)."
+      raise ArgumentError, BAD_ORIGIN
     end
 
     # Where the CLI keeps this machine's connection for the two origins.

data/lib/withruntime/errors.rb

@@ -7,11 +7,16 @@ module WithRuntime
   # Java SDKs.
   class Error < StandardError
     # 503s that are a deliberate state, not a passing one: retrying cannot change them.
-    DELIBERATE = %w[fork_unavailable previews_unavailable unavailable].freeze
-    # Refusals that pass on their own: a host frees room, a trial slot frees.
-    PASSING = %w[no_capacity trial_busy].freeze
+    DELIBERATE = %w[
+      unavailable unsupported fork_unavailable previews_unavailable
+      network_unavailable network_rules_unavailable secrets_unavailable identity_unavailable env_unavailable
+      resize_unavailable
+    ].freeze
+    # Refusals that pass on their own: a host frees room, a sandbox of an
+    # account without credit stops.
+    PASSING = %w[no_capacity no_credit_running_limit no_credit_total_limit].freeze
     # Refusals of a create that clear when a sandbox stops or a host frees room.
-    WAITS_FOR_ROOM = %w[trial_busy trial_domain_limit trial_capacity quota_exceeded no_capacity].freeze
+    WAITS_FOR_ROOM = %w[no_credit_running_limit no_credit_total_limit no_credit_domain_limit no_credit_capacity_full quota_exceeded no_capacity volume_releasing].freeze
 
     attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after
 

data/lib/withruntime/network_products.rb

@@ -20,24 +20,24 @@ module WithRuntime
   end
 
   class Addresses < Product
-    def reserve(family: 4) = Record.new(@t.json("POST", "/v1/addresses", body: { "family" => family }))
-    def list = @t.json("GET", "/v1/addresses")["data"].map { |row| Record.new(row) }
-    def release(id) = @t.json("DELETE", "/v1/addresses/#{seg(id)}") && nil
+    def reserve(family: 4) = Record.new(@t.json("POST", "/v1/ips", body: { "family" => family }))
+    def list = @t.json("GET", "/v1/ips")["data"].map { |row| Record.new(row) }
+    def release(id) = @t.json("DELETE", "/v1/ips/#{seg(id)}") && nil
   end
 
   # Account WireGuard networking, distinct from Sandbox#open_tunnel.
   class PrivateTunnel < Product
-    def get = Record.new(@t.json("GET", "/v1/tunnel"))
-    def create(subnet: nil) = Record.new(@t.json("POST", "/v1/tunnel", body: { "subnet" => subnet }.compact))
-    def delete = @t.json("DELETE", "/v1/tunnel") && nil
+    def get = Record.new(@t.json("GET", "/v1/networks/wireguard"))
+    def create(subnet: nil) = Record.new(@t.json("POST", "/v1/networks/wireguard", body: { "subnet" => subnet }.compact))
+    def delete = @t.json("DELETE", "/v1/networks/wireguard") && nil
     # Save config even when config_ready is false: its private key is shown once.
     def add_peer(name:, public_key: nil, routes: nil, idempotency_key: nil)
-      Record.new(@t.json("POST", "/v1/tunnel/peers", body: Fields.body(name: name, public_key: public_key, routes: routes), key: idempotency_key, no_retry: public_key.to_s.empty?))
+      Record.new(@t.json("POST", "/v1/networks/wireguard/peers", body: Fields.body(name: name, public_key: public_key, routes: routes), key: idempotency_key, no_retry: public_key.to_s.empty?))
     end
     def rotate_peer(id, public_key: nil)
-      Record.new(@t.json("POST", "/v1/tunnel/peers/#{seg(id)}:rotate", body: { "publicKey" => public_key }.compact, no_retry: public_key.to_s.empty?))
+      Record.new(@t.json("POST", "/v1/networks/wireguard/peers/#{seg(id)}:rotate", body: { "publicKey" => public_key }.compact, no_retry: public_key.to_s.empty?))
     end
-    def remove_peer(id) = Record.new(@t.json("DELETE", "/v1/tunnel/peers/#{seg(id)}"))
+    def remove_peer(id) = Record.new(@t.json("DELETE", "/v1/networks/wireguard/peers/#{seg(id)}"))
   end
 
   class SSO < Product

data/lib/withruntime/parity_products.rb

@@ -45,7 +45,7 @@ module WithRuntime
     def get(id) = Record.new(@t.json("GET", path(id)))
     def list = @t.json("GET", path)["data"].map { |row| Record.new(row) }
     def stop(id) = Record.new(@t.json("POST", "#{path(id)}:stop", body: {}))
-    def download(id) = @t.bytes("GET", "#{path(id)}/video", accept: "video/mp4")
+    def download(id) = @t.file_bytes("#{path(id)}/video", accept: "video/mp4")
     def delete(id) = @t.json("DELETE", path(id)) && nil
   end
 end

data/lib/withruntime/products.rb

@@ -71,6 +71,12 @@ module WithRuntime
 
     def list(state: nil, name: nil, limit: nil) = page("/v1/volumes", { "state" => state, "name" => name, "limit" => limit })
 
+    # Grows a volume no sandbox holds to +size_mib+, on its host, and waits
+    # (up to +wait+ seconds) for it. The answer's +resize+ shows how far it got.
+    def resize(id, size_mib:, wait: 10, idempotency_key: nil)
+      Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:resize", body: Fields.body(size_mib: size_mib), wait: wait, key: idempotency_key))
+    end
+
     # Deletes a volume and everything on it.
     def delete(id) = Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:delete", body: {}))
   end
@@ -98,12 +104,13 @@ 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
 
-  # +runtime.referrals+: the account's referral link and what it earned.
+  # +runtime.referrals+: the account's referral link and what it earned. Money is
+  # integer microdollars in strings.
   class Referrals < Product
     def get = Record.new(@t.json("GET", "/v1/referrals"))
   end