withruntime 0.1.0

data/lib/withruntime/errors.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # Every failure the SDK raises. +code+ is stable and machine-readable, +hint+
+  # says what to do next, and +request_id+ is what to quote in a report. The
+  # subclasses name the class of failure, as in the JavaScript, Python, Go and
+  # 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
+    # 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
+
+    attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after
+
+    def initialize(message, code:, status: 0, hint: nil, request_id: nil, details: nil, idempotency_key: nil, retry_after: nil)
+      super(message)
+      @code = code
+      @status = status
+      @hint = hint
+      @request_id = request_id
+      @details = details || {}
+      @idempotency_key = idempotency_key
+      @retry_after = retry_after
+    end
+
+    # Whether retrying this exact call, with the same idempotency key, is safe and may work.
+    def retryable?
+      return false if DELIBERATE.include?(code)
+      return details["field"] != "count" if PASSING.include?(code)
+
+      [0, 429, 502, 503, 504].include?(status)
+    end
+
+    def to_s
+      text = +"#{super}"
+      text << " Hint: #{hint}" if hint
+      text << " Request: #{request_id}" if request_id
+      text
+    end
+
+    # The API's one error shape, as the right subclass.
+    def self.from(status, body, idempotency_key)
+      error = body.is_a?(Hash) && body["error"].is_a?(Hash) ? body["error"] : {}
+      retry_ms = error["retryAfterMs"]
+      klass = case status
+              when 401 then AuthenticationError
+              when 403 then PermissionDeniedError
+              when 404 then NotFoundError
+              when 409 then ConflictError
+              when 400, 413, 422 then InvalidRequestError
+              when 429 then RateLimitError
+              else status >= 500 ? ServiceUnavailableError : Error
+              end
+      klass.new(
+        error["message"].is_a?(String) ? error["message"] : "Runtime request failed (#{status}).",
+        code: error["code"].is_a?(String) ? error["code"] : "request_failed",
+        status: status,
+        hint: error["hint"],
+        request_id: error["requestId"],
+        details: error["details"].is_a?(Hash) ? error["details"] : nil,
+        idempotency_key: idempotency_key,
+        retry_after: retry_ms.is_a?(Numeric) ? retry_ms / 1000.0 : nil
+      )
+    end
+
+    def self.missing_key
+      AuthenticationError.new(
+        "No Runtime key found: RUNTIME_API_KEY is not set and this machine is not connected.",
+        code: "missing_api_key",
+        hint: "Run `npx -y withruntime login` (a browser approval; nothing to copy), set RUNTIME_API_KEY to a key " \
+              "from https://withruntime.com/account/keys, or pass api_key:."
+      )
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class PermissionDeniedError < Error; end
+  class NotFoundError < Error; end
+  class ConflictError < Error; end
+  class InvalidRequestError < Error; end
+  class RateLimitError < Error; end
+  class ServiceUnavailableError < Error; end
+
+  # No answer arrived (+connection_error+) or the call ran past its deadline
+  # (+timeout+). A write may or may not have happened; retrying with the same
+  # idempotency key settles it safely.
+  class ConnectionError < Error; end
+
+  # Raised by exec with +check: true+ when a command exits non-zero or times out.
+  class CommandError < Error
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      if result.timed_out
+        super("Command timed out.", code: "command_timeout")
+      else
+        tail = result.stderr.strip
+        tail = tail[-500..] if tail.length > 500
+        super("Command exited with #{result.exit_code.inspect}.#{tail.empty? ? "" : " #{tail}"}", code: "command_failed")
+      end
+    end
+
+    def exit_code = result.exit_code
+    def stdout = result.stdout
+    def stderr = result.stderr
+  end
+
+  # A webhook delivery that is not authentic or is too old.
+  class WebhookVerificationError < StandardError; end
+end

data/lib/withruntime/fields.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # Ruby's snake_case keywords as the API's camelCase fields: +timeout_seconds:+
+  # is timeoutSeconds, +memory_mib:+ is memoryMiB. User data (labels, env,
+  # build_args, headers and the like) is sent as it is.
+  module Fields
+    OPAQUE = %w[labels env buildArgs headers data context detail].freeze
+
+    module_function
+
+    def camel(key)
+      parts = key.to_s.split("_")
+      parts.drop(1).each_with_index { |part, index| parts[index + 1] = part == "mib" ? "MiB" : part.capitalize }
+      parts.join
+    end
+
+    # A request body from keyword arguments; nil values are left out.
+    def body(fields)
+      fields.each_with_object({}) do |(key, value), out|
+        next if value.nil?
+
+        name = key.is_a?(Symbol) ? camel(key) : key.to_s
+        out[name] = OPAQUE.include?(name) ? stringify(value) : convert(value)
+      end
+    end
+
+    def convert(value)
+      case value
+      when Hash then body(value)
+      when Array then value.map { |item| convert(item) }
+      else value
+      end
+    end
+
+    def stringify(value)
+      value.is_a?(Hash) ? value.to_h { |key, item| [key.to_s, item] } : value
+    end
+  end
+end

data/lib/withruntime/file_watch.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  class WatchService < SandboxProduct
+    def path(id = nil) = @s.path("/files/watches") + (id ? "/#{Transport.segment(id)}" : "")
+    def start(path, idempotency_key: nil, **options)
+      answer = @t.json("POST", self.path, body: Fields.body(options.merge(path: path)), key: idempotency_key)
+      FileWatch.new(self, answer)
+    end
+    def list = @t.json("GET", path)["data"].map { |row| Record.new(row) }
+    def read(id, cursor: 0, wait_ms: 0) = Record.new(@t.json("GET", "#{path(id)}/events", query: { "cursor" => cursor, "waitMs" => wait_ms }))
+    def stop(id) = @t.json("DELETE", path(id)) && nil
+    def events(id, cursor, cancel, &block)
+      @t.events("GET", "#{path(id)}/events", query: { "cursor" => cursor, "follow" => true }, timeout: 150, cancel: cancel, &block)
+    end
+  end
+
+  # Each events block retains its cursor. Close only its reader, or stop the guest watch too.
+  class FileWatch
+    attr_reader :id, :path
+    def initialize(service, info)
+      @service, @id, @path, @cursor = service, info["id"], info["path"], info["cursor"] || 0
+      @lock, @stop_lock = Mutex.new, Mutex.new
+      @reading = @stopped = false
+    end
+    def cursor = @lock.synchronize { @cursor }
+    def close
+      cancel = @lock.synchronize { @cancel }
+      cancel&.cancel
+    end
+    def stop
+      @stop_lock.synchronize do
+        return if @lock.synchronize { @stopped }
+        @lock.synchronize { @stopped = true }
+        close
+        begin
+          @service.stop(@id)
+        rescue StandardError
+          @lock.synchronize { @stopped = false }
+          raise
+        end
+      end
+      nil
+    end
+    def events
+      return enum_for(:events) unless block_given?
+      cancel = @lock.synchronize do
+        raise Error.new("The watch is stopped or already being read.", code: "watch_reader_active") if @reading || @stopped
+        @reading = true
+        @cancel = Transport::Cancellation.new
+      end
+      begin
+        loop do
+          again = false
+          @service.events(@id, cursor, cancel) do |event|
+            @lock.synchronize { @cursor = event["cursor"] if event.key?("cursor") }
+            if event["k"] == "continue"
+              again = true
+              break
+            end
+            raise Error.new(event["message"], code: event["code"]) if event["k"] == "failure"
+            yield Record.new(event)
+            return if %w[end paused].include?(event["k"])
+          end
+          break unless again && !cancel.cancelled?
+        end
+      ensure
+        cancel.cancel
+        @lock.synchronize { @reading = false; @cancel = nil }
+      end
+    end
+  end
+end

data/lib/withruntime/images.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module WithRuntime
+  # +runtime.images+: custom images. Build one, then start sandboxes from it
+  # with +runtime.sandboxes.create(image: "app")+.
+  #
+  #   runtime.images.build(name: "app", recipe: { pip: ["pandas"] })
+  #   runtime.images.build(name: "app", dockerfile: File.read("Dockerfile"), context_dir: ".")
+  class Images < Product
+    UUID = /\A[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\z/i
+    CONTEXT_BYTES = 100 * 1_048_576
+    CONTEXT_FILES = 20_000
+    CHUNK = 1_048_576
+
+    # Queues a build and returns at once, in state "queued". Exactly one of
+    # +image:+, +dockerfile:+ or +recipe:+. With +context_dir:+ the folder is
+    # packed and its missing chunks uploaded first.
+    def create(context_dir: nil, idempotency_key: nil, **fields)
+      Record.new(@t.json("POST", "/v1/images", body: prepare(context_dir, fields), key: idempotency_key))
+    end
+
+    # Builds and waits until the image is ready, sending each log line to the
+    # block. Raises with code image_failed, and the build's own error, when it fails.
+    def build(context_dir: nil, idempotency_key: nil, **fields, &on_log)
+      image = create(context_dir: context_dir, idempotency_key: idempotency_key, **fields)
+      image = follow_logs(image.id, &on_log) if on_log
+      while %w[queued building].include?(image.state)
+        sleep 1
+        image = get(image.id)
+      end
+      unless image.state == "ready"
+        raise Error.new("Image #{image.id} #{image.state}: #{image.error || "no error given"}", code: "image_failed",
+                                                                                                 hint: "Read the build log with runtime.images.logs(id).")
+      end
+
+      image
+    end
+
+    def get(id) = Record.new(@t.json("GET", "/v1/images/#{seg(id)}"))
+
+    # An image by id, name (its latest tag), name:tag or name@version.
+    def resolve(ref) = UUID.match?(ref) ? get(ref) : Record.new(@t.json("GET", "/v1/images/resolve", query: { "ref" => ref }))
+
+    # Build output after line +after+: lines, next_after, state, truncated and done.
+    def logs(id, after: 0) = Record.new(@t.json("GET", "/v1/images/#{seg(id)}/logs", query: { "after" => after }))
+
+    # Sends build output after line +after+ to the block as it is written,
+    # until the build ends, and returns the image as it ended. It streams, and
+    # polls when a stream breaks.
+    def follow_logs(id, after: 0)
+      begin
+        loop do
+          resume = false
+          @t.events("GET", "/v1/images/#{seg(id)}/logs", query: { "after" => after, "follow" => "true" }, timeout: 180) do |event|
+            case event["type"]
+            when "line"
+              yield Record.new(event)
+              after = event["seq"]
+            when "done" then return event["image"].is_a?(Hash) && event["image"]["id"] ? Record.new(event["image"]) : get(id)
+            when "continue"
+              after = event["after"]
+              resume = true
+            when "error" then raise Error.new(event.dig("error", "message") || "The log stream failed.", code: event.dig("error", "code") || "stream_failed")
+            end
+          end
+          break unless resume
+        end
+      rescue ConnectionError
+        nil # Fall through to polling.
+      end
+      loop do
+        page = logs(id, after: after)
+        Array(page["lines"]).each { |line| yield Record.new(line) }
+        after = page["nextAfter"]
+        image = get(id)
+        return image if page["done"] || !%w[queued building].include?(image.state)
+
+        sleep 1
+      end
+    end
+
+    def list(state: nil, name: nil, limit: nil) = page("/v1/images", { "state" => state, "name" => name, "limit" => limit })
+
+    # Every version of a name, newest first.
+    def versions(name) = list(name: name, limit: 100)
+
+    # Points +tag+ of the image's name at this version (+ref+ is an id, name:tag or name@version).
+    def tag(ref, tag) = Record.new(@t.json("POST", "/v1/images/#{seg(id_of(ref))}:tag", body: { "tag" => tag }))
+    def untag(ref, tag) = Record.new(@t.json("POST", "/v1/images/#{seg(id_of(ref))}:untag", body: { "tag" => tag }))
+
+    # Deletes one version and its tags.
+    def delete(ref) = Record.new(@t.json("POST", "/v1/images/#{seg(id_of(ref))}:delete", body: {}))
+
+    # Saved credentials for private registries. The secret is never returned.
+    def registries = @t.json("GET", "/v1/images/registries")["data"].map { |registry| Record.new(registry) }
+
+    # A user name and token or password (Docker Hub, GitHub, Google with
+    # username _json_key), or +access_key_id:+ and +secret_access_key:+ for Amazon ECR.
+    def set_registry(registry, username: nil, password: nil, access_key_id: nil, secret_access_key: nil)
+      body = Fields.body(registry: registry, username: username, password: password, access_key_id: access_key_id,
+                         secret_access_key: secret_access_key)
+      Record.new(@t.json("POST", "/v1/images/registries", body: body))
+    end
+
+    def delete_registry(registry) = @t.json("POST", "/v1/images/registries:delete", body: { "registry" => registry })["deleted"] == true
+
+    # Packs a folder as a build context, the way docker build does (its
+    # .dockerignore applied, .git left out when there is none), and uploads the
+    # chunks the server does not have yet. Returns the context and the
+    # .dockerignore to build with.
+    def upload_context(folder, dockerignore: nil)
+      archive, files, applied = self.class.pack(folder, dockerignore)
+      chunks = (0...archive.bytesize).step(CHUNK).map { |at| archive.byteslice(at, CHUNK) }
+      digests = chunks.map { |chunk| Digest::SHA256.hexdigest(chunk) }
+      missing = @t.json("POST", "/v1/images/context/missing", body: { "digests" => digests })["missing"]
+      queue = Queue.new
+      digests.each_with_index { |digest, index| queue << index if missing.include?(digest) }
+      queue.close
+      failure = nil
+      Array.new(4) do
+        Thread.new do
+          while !failure && (index = queue.pop)
+            begin
+              @t.json("PUT", "/v1/images/context/#{digests[index]}", raw: chunks[index])
+            rescue StandardError => e
+              failure ||= e
+            end
+          end
+        end
+      end.each(&:join)
+      raise failure if failure
+
+      { "context" => { "archive" => { "sha256" => Digest::SHA256.hexdigest(archive), "size" => archive.bytesize, "chunks" => digests },
+                       "files" => files },
+        "dockerignore" => applied }
+    end
+
+    # A deterministic gzipped tar of the folder (sorted, no times, no owners,
+    # no links) and its files with their SHA-256.
+    def self.pack(folder, dockerignore = nil)
+      root = File.expand_path(folder)
+      ignore_file = File.join(root, ".dockerignore")
+      dockerignore ||= File.read(ignore_file) if File.file?(ignore_file)
+      ignored = dockerignore_filter(dockerignore || ".git\n")
+      reincludes = dockerignore.to_s.match?(/^\s*!/)
+      tar = "".b
+      files = []
+      walk = lambda do |directory|
+        Dir.children(directory).sort.each do |name|
+          full = File.join(directory, name)
+          relative = full.delete_prefix("#{root}/")
+          stat = File.lstat(full)
+          if stat.directory?
+            walk.call(full) unless ignored.call(relative) && !reincludes
+          elsif stat.file? && !ignored.call(relative)
+            raise Error.new("The build context has more than #{CONTEXT_FILES} files.", code: "context_too_large", hint: "Leave some out with a .dockerignore.") if files.size >= CONTEXT_FILES
+
+            data = File.binread(full)
+            mode = stat.mode & 0o777
+            files << { "path" => relative, "sha256" => Digest::SHA256.hexdigest(data), "size" => data.bytesize, "mode" => mode }
+            tar << Tar.header(relative, data.bytesize, mode, "0") << data << Tar.pad(data.bytesize)
+          end
+        end
+      end
+      walk.call(root)
+      archive = Tar.gzip(tar << ("\0".b * 1024))
+      if archive.bytesize > CONTEXT_BYTES
+        raise Error.new("The build context is #{(archive.bytesize / 1_048_576) + 1} MiB compressed; the most is 100 MiB.",
+                        code: "context_too_large", hint: "Leave build outputs and dependencies out with a .dockerignore.")
+      end
+
+      [archive, files, dockerignore]
+    end
+
+    # A .dockerignore as Docker reads it: # comments, ! re-includes, **
+    # crosses directories, a pattern naming a directory excludes what is in it,
+    # and the last matching pattern decides.
+    def self.dockerignore_filter(text)
+      rules = text.gsub(/\r\n?/, "\n").split("\n").filter_map do |raw|
+        line = raw.strip
+        next if line.empty? || line.start_with?("#")
+
+        negate = line.start_with?("!")
+        line = line[1..].strip if negate
+        line = normalize(line.sub(%r{\A/+}, "")).sub(%r{/+\z}, "")
+        next if line.empty? || line == "."
+
+        [negate, Regexp.new("\\A#{translate(line)}\\z")]
+      end
+      lambda do |path|
+        parts = path.split("/")
+        rules.reduce(false) do |excluded, (negate, regex)|
+          parts.length.downto(1).any? { |n| regex.match?(parts[0, n].join("/")) } ? !negate : excluded
+        end
+      end
+    end
+
+    def self.translate(line)
+      source = +""
+      i = 0
+      while i < line.length
+        char = line[i]
+        if char == "*" && line[i + 1] == "*"
+          if line[i + 2] == "/"
+            source << "(?:.*/)?"
+            i += 2
+          else
+            source << ".*"
+            i += 1
+          end
+        elsif char == "*" then source << "[^/]*"
+        elsif char == "?" then source << "[^/]"
+        elsif char == "["
+          close = line.index("]", i + 1)
+          if close.nil?
+            source << "\\["
+          else
+            set = line[(i + 1)...close]
+            set = "^#{set[1..]}" if set.start_with?("!")
+            source << "[#{set.gsub("\\", "\\\\\\\\")}]"
+            i = close
+          end
+        elsif char == "\\" && i + 1 < line.length
+          i += 1
+          source << Regexp.escape(line[i])
+        else
+          source << Regexp.escape(char)
+        end
+        i += 1
+      end
+      source
+    end
+
+    def self.normalize(path)
+      out = []
+      path.split("/").each do |part|
+        next if part.empty? || part == "."
+
+        part == ".." ? out.pop : out.push(part)
+      end
+      out.empty? ? "." : out.join("/")
+    end
+
+    private
+
+    def id_of(ref) = UUID.match?(ref) ? ref : resolve(ref).id
+
+    def prepare(context_dir, fields)
+      body = Fields.body(fields)
+      return body unless context_dir
+
+      uploaded = upload_context(context_dir, dockerignore: body["dockerignore"])
+      body.merge("context" => uploaded["context"], "dockerignore" => uploaded["dockerignore"]).compact
+    end
+  end
+end

data/lib/withruntime/network_products.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  class Domains < Product
+    def add(hostname:, sandbox_id:, port:, idempotency_key: nil)
+      Record.new(@t.json("POST", "/v1/domains", body: Fields.body(hostname: hostname, sandbox_id: sandbox_id, port: port), key: idempotency_key))
+    end
+    def get(hostname) = Record.new(@t.json("GET", "/v1/domains/#{seg(hostname)}"))
+    def verify(hostname) = Record.new(@t.json("POST", "/v1/domains/#{seg(hostname)}:verify", body: {}))
+    def list = @t.json("GET", "/v1/domains")["data"].map { |row| Record.new(row) }
+    def remove(hostname) = @t.json("DELETE", "/v1/domains/#{seg(hostname)}") && nil
+  end
+
+  class Ports < Product
+    def open(sandbox_id:, port:, idempotency_key: nil)
+      Record.new(@t.json("POST", "/v1/ports", body: Fields.body(sandbox_id: sandbox_id, port: port), key: idempotency_key))
+    end
+    def list(sandbox_id: nil) = @t.json("GET", "/v1/ports", query: { "sandboxId" => sandbox_id })["data"].map { |row| Record.new(row) }
+    def close(id) = @t.json("DELETE", "/v1/ports/#{seg(id)}") && nil
+  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
+  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
+    # 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?))
+    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?))
+    end
+    def remove_peer(id) = Record.new(@t.json("DELETE", "/v1/tunnel/peers/#{seg(id)}"))
+  end
+
+  class SSO < Product
+    def get = Record.new(@t.json("GET", "/v1/sso"))
+  end
+  class MCP < Product
+    def catalog = @t.json("GET", "/v1/mcp/catalog")["data"].map { |row| Record.new(row) }
+  end
+end

data/lib/withruntime/parity_products.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  class SandboxProduct
+    def initialize(sandbox)
+      @s = sandbox
+      @t = sandbox.transport
+    end
+  end
+
+  class Mounts < SandboxProduct
+    def add(idempotency_key: nil, **options) = Record.new(@t.json("POST", @s.path("/mounts"), body: Fields.body(options), key: idempotency_key))
+    def list = @t.json("GET", @s.path("/mounts"))["data"].map { |row| Record.new(row) }
+    def remove(path) = @t.json("POST", @s.path("/mounts:unmount"), body: { "path" => path }) && nil
+  end
+
+  class SandboxMCP < SandboxProduct
+    def start(servers:, port: nil, replace: nil, idempotency_key: nil)
+      # Secrets/env/options are customer dictionary keys, not SDK field names.
+      servers = servers.map do |entry|
+        entry.to_h.each_with_object({}) do |(key, value), out|
+          name = Fields.camel(key)
+          out[name] = %w[secrets env options].include?(name) ? Fields.stringify(value) : Fields.convert(value)
+        end
+      end
+      Record.new(@t.json("POST", @s.path("/mcp"), body: { "servers" => servers, "port" => port, "replace" => replace }.compact, key: idempotency_key))
+    end
+    def get = Record.new(@t.json("GET", @s.path("/mcp")))
+    def stop = @t.json("DELETE", @s.path("/mcp")) && nil
+    def ready(timeout: 600)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise @t.connection_error(true, false, nil) unless left.positive?
+        state = Record.new(@t.json("GET", @s.path("/mcp"), timeout: left))
+        return state unless state.running && Array(state.servers).any? { |server| server.status == "installing" }
+        sleep([2, left].min)
+      end
+    end
+  end
+
+  class Recordings < SandboxProduct
+    def path(id = nil) = @s.path("/desktop/recordings") + (id ? "/#{Transport.segment(id)}" : "")
+    def start(idempotency_key: nil, **options) = Record.new(@t.json("POST", path, body: Fields.body(options), key: idempotency_key))
+    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 delete(id) = @t.json("DELETE", path(id)) && nil
+  end
+end