pipeops-rexec 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daf648a63c80b783c7701b1543ba59903618e531b5560a484b6274d3dde81bb1
-  data.tar.gz: d02a328b6ace511f14c478d3928f79fd5be132624c9b23ee649c9e77f2e3b0ef
+  metadata.gz: e7ba59743a1e821530bd403adb43dcba9aff15c995197741c9f2c309325b1599
+  data.tar.gz: 902155d9d6f68d257668356fb6854b8b3470271f2f23f9b1905cef0822d5c7cd
 SHA512:
-  metadata.gz: d5e4289f26441de35cc62b9bbd10a354a4ed5b70ef541e90eab7fc9292402986a0e0e99fbc5f34220d4721a08fa1020f41d263f2c97b4b3bd338aac96b7ad91d
-  data.tar.gz: 892d324fd210063705b9722cff702c7680d4b972f6e8529ccbe27c4a84ae9f66cb6ce5acf1e21bc7769ff19ac9adc46fea1d6f0892589ae631dd69a99b0a2410
+  metadata.gz: 5f22905b095e20c123f27b0b4958881f9020e25569856b9112c1d16725fb6bca8acf2b7b9c20a4b1389d17ea57d3a27f75122669df06ff2fd1e8cb7b091f1c56
+  data.tar.gz: 32d3ec942eac748f79adad09d21cc9d004ea85d0050846656b70b35981286e3884b8783f5ee4b7a56569e2f1bac3a090234dd3a9784c4621ff986cef1942bc70

data/README.md

@@ -25,7 +25,7 @@ client = Rexec::Client.new("https://your-instance.com", "your-token")
 
 # Create a container
 container = client.containers.create(
-  image: "ubuntu:24.04",
+  image: "ubuntu",
   name: "my-sandbox"
 )
 puts "Created container: #{container.id}"
@@ -74,7 +74,7 @@ container = client.containers.get("container-id")
 
 # Create a container
 container = client.containers.create(
-  image: "ubuntu:24.04",
+  image: "ubuntu",
   name: "my-container",
   environment: { "MY_VAR" => "value" },
   labels: { "project" => "demo" }
@@ -176,7 +176,7 @@ def create_batch(client, count)
   futures = (0...count).map do |i|
     Concurrent::Future.execute do
       client.containers.create(
-        image: "ubuntu:24.04",
+        image: "ubuntu",
         name: "worker-#{i}"
       )
     end

data/lib/rexec/client.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Rexec
+  # Main client for interacting with Rexec API.
+  #
+  # @example
+  #   client = Rexec::Client.new("https://rexec.sh", "your-token")
+  #   sandboxes = client.sandboxes.list
+  #   # Legacy: client.containers is the same service
+  #
+  class Client
+    attr_reader :base_url, :sandboxes, :files, :terminal
+
+    # Deprecated alias for {#sandboxes}.
+    # @return [SandboxService]
+    def containers
+      sandboxes
+    end
+
+    # Initialize a new Rexec client.
+    #
+    # @param base_url [String] Base URL of your Rexec instance
+    # @param token [String] API token for authentication
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    def initialize(base_url, token, timeout: 30)
+      @base_url = base_url.chomp("/")
+      @token = token
+      @timeout = timeout
+
+      @http = Faraday.new(url: @base_url) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+        f.options.timeout = timeout
+        f.headers["Authorization"] = "Bearer #{token}"
+        f.headers["Accept"] = "application/json"
+      end
+
+      @sandboxes = SandboxService.new(self)
+      @files = FileService.new(self)
+      @terminal = TerminalService.new(self)
+    end
+
+    # Make an API request.
+    # @api private
+    def request(method, path, body: nil, params: nil)
+      response = @http.run_request(method, path, body, nil) do |req|
+        req.params = params if params
+      end
+
+      handle_response(response)
+    end
+
+    # Make a raw request and return bytes.
+    # @api private
+    def request_bytes(method, path)
+      raw_http = Faraday.new(url: @base_url) do |f|
+        f.adapter Faraday.default_adapter
+        f.options.timeout = @timeout
+        f.headers["Authorization"] = "Bearer #{@token}"
+      end
+
+      response = raw_http.run_request(method, path, nil, nil)
+      
+      if response.status >= 400
+        raise APIError.new(response.status, "Request failed")
+      end
+
+      response.body
+    end
+
+    # Get WebSocket URL.
+    # @api private
+    def ws_url(path)
+      uri = URI.parse(@base_url)
+      ws_scheme = uri.scheme == "https" ? "wss" : "ws"
+      "#{ws_scheme}://#{uri.host}:#{uri.port || (uri.scheme == 'https' ? 443 : 80)}#{path}"
+    end
+
+    # Get the API token.
+    # @api private
+    attr_reader :token
+
+    private
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 401, 403
+        raise AuthError.new(extract_error_message(response))
+      when 404
+        raise APIError.new(404, extract_error_message(response))
+      else
+        raise APIError.new(response.status, extract_error_message(response), response.body)
+      end
+    end
+
+    def extract_error_message(response)
+      if response.body.is_a?(Hash)
+        response.body["error"] || response.body["message"] || "Unknown error"
+      else
+        "Unknown error"
+      end
+    end
+  end
+end

data/lib/rexec/container.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Rexec
+  # Represents a Rexec sandbox (isolated Linux environment).
+  class Sandbox
+    attr_reader :id, :name, :image, :status, :created_at, :started_at, :labels, :environment
+
+    def initialize(data)
+      @id = data["id"]
+      @name = data["name"]
+      @image = data["image"]
+      @status = data["status"]
+      @created_at = data["created_at"]
+      @started_at = data["started_at"]
+      @labels = data["labels"] || {}
+      @environment = data["environment"] || {}
+    end
+
+    def running?
+      status == "running"
+    end
+
+    def stopped?
+      status == "stopped"
+    end
+  end
+
+  # @deprecated Use {Sandbox}
+  Container = Sandbox
+
+  # Service for managing sandboxes. HTTP paths remain /api/containers.
+  class SandboxService
+    def initialize(client)
+      @client = client
+    end
+
+    # List all sandboxes.
+    #
+    # @return [Array<Sandbox>]
+    def list
+      data = @client.request(:get, "/api/containers")
+      # API returns { "containers" => [...], "count" => N, "limit" => M }
+      items = data.is_a?(Array) ? data : (data && data["containers"]) || []
+      items.map { |c| Sandbox.new(c) }
+    end
+
+    # Get a sandbox by ID.
+    #
+    # @param id [String] Sandbox ID
+    # @return [Sandbox]
+    def get(id)
+      data = @client.request(:get, "/api/containers/#{id}")
+      Sandbox.new(data)
+    end
+
+    # Create a new sandbox.
+    #
+    # @param image [String] Image alias (e.g. "ubuntu")
+    # @param name [String, nil] Optional sandbox name
+    # @param environment [Hash] Environment variables
+    # @param labels [Hash] Labels
+    # @return [Sandbox]
+    #
+    # @example
+    #   sandbox = client.sandboxes.create(
+    #     image: "ubuntu",
+    #     name: "my-sandbox",
+    #     environment: { "MY_VAR" => "value" }
+    #   )
+    def create(image:, name: nil, environment: {}, labels: {})
+      body = { image: image }
+      body[:name] = name if name
+      body[:environment] = environment unless environment.empty?
+      body[:labels] = labels unless labels.empty?
+
+      data = @client.request(:post, "/api/containers", body: body)
+      Sandbox.new(data)
+    end
+
+    # Delete a sandbox.
+    #
+    # @param id [String] Sandbox ID
+    def delete(id)
+      @client.request(:delete, "/api/containers/#{id}")
+      nil
+    end
+
+    # Start a sandbox.
+    #
+    # @param id [String] Sandbox ID
+    def start(id)
+      @client.request(:post, "/api/containers/#{id}/start")
+      nil
+    end
+
+    # Stop a sandbox.
+    #
+    # @param id [String] Sandbox ID
+    def stop(id)
+      @client.request(:post, "/api/containers/#{id}/stop")
+      nil
+    end
+  end
+
+  # @deprecated Use {SandboxService}
+  ContainerService = SandboxService
+end

data/lib/rexec/error.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Rexec
+  # Base error class for all Rexec errors.
+  class Error < StandardError; end
+
+  # API error with status code.
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(status_code, message, response_body = nil)
+      @status_code = status_code
+      @response_body = response_body
+      super("API error #{status_code}: #{message}")
+    end
+  end
+
+  # Authentication error (401/403).
+  class AuthError < APIError
+    def initialize(message = "Authentication failed")
+      super(401, message)
+    end
+  end
+
+  # Resource not found (404).
+  class NotFoundError < APIError
+    attr_reader :resource, :resource_id
+
+    def initialize(resource, resource_id)
+      @resource = resource
+      @resource_id = resource_id
+      super(404, "#{resource} '#{resource_id}' not found")
+    end
+  end
+
+  # Connection error.
+  class ConnectionError < Error; end
+
+  # Terminal connection closed.
+  class TerminalClosedError < Error
+    def initialize
+      super("Terminal connection closed")
+    end
+  end
+end

data/lib/rexec/file_service.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Rexec
+  # Represents file metadata.
+  class FileInfo
+    attr_reader :name, :path, :size, :mode, :mod_time, :is_dir
+
+    def initialize(data)
+      @name = data["name"]
+      @path = data["path"]
+      @size = data["size"] || 0
+      @mode = data["mode"]
+      @mod_time = data["mod_time"]
+      @is_dir = data["is_dir"] || false
+    end
+
+    alias directory? is_dir
+
+    def file?
+      !is_dir
+    end
+  end
+
+  # Service for file operations in containers.
+  class FileService
+    def initialize(client)
+      @client = client
+    end
+
+    # List files in a directory.
+    #
+    # @param container_id [String] Container ID
+    # @param path [String] Directory path
+    # @return [Array<FileInfo>]
+    def list(container_id, path = "/")
+      encoded_path = URI.encode_www_form_component(path)
+      data = @client.request(:get, "/api/containers/#{container_id}/files/list?path=#{encoded_path}")
+      data.map { |f| FileInfo.new(f) }
+    end
+
+    # Download a file.
+    #
+    # @param container_id [String] Container ID
+    # @param path [String] File path
+    # @return [String] File contents
+    def download(container_id, path)
+      encoded_path = URI.encode_www_form_component(path)
+      @client.request_bytes(:get, "/api/containers/#{container_id}/files?path=#{encoded_path}")
+    end
+
+    # Create a directory.
+    #
+    # @param container_id [String] Container ID
+    # @param path [String] Directory path
+    def mkdir(container_id, path)
+      @client.request(:post, "/api/containers/#{container_id}/files/mkdir", body: { path: path })
+      nil
+    end
+
+    # Delete a file or directory.
+    #
+    # @param container_id [String] Container ID
+    # @param path [String] Path to delete
+    def delete(container_id, path)
+      encoded_path = URI.encode_www_form_component(path)
+      @client.request(:delete, "/api/containers/#{container_id}/files?path=#{encoded_path}")
+      nil
+    end
+  end
+end

data/lib/rexec/terminal.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rexec
+  # WebSocket terminal connection.
+  class Terminal
+    attr_reader :closed
+
+    def initialize(ws)
+      @ws = ws
+      @closed = false
+      @data_handlers = []
+      @close_handlers = []
+      @error_handlers = []
+
+      setup_handlers
+    end
+
+    # Send data to the terminal.
+    #
+    # @param data [String] Data to send
+    def write(data)
+      raise TerminalClosedError if @closed
+
+      @ws.send(data)
+    end
+
+    # Resize the terminal.
+    #
+    # @param cols [Integer] Number of columns
+    # @param rows [Integer] Number of rows
+    def resize(cols, rows)
+      raise TerminalClosedError if @closed
+
+      msg = { type: "resize", cols: cols, rows: rows }.to_json
+      @ws.send(msg)
+    end
+
+    # Register a handler for incoming data.
+    #
+    # @yield [data] Block called with each chunk of data
+    def on_data(&block)
+      @data_handlers << block
+    end
+
+    # Register a handler for connection close.
+    #
+    # @yield Block called when connection closes
+    def on_close(&block)
+      @close_handlers << block
+    end
+
+    # Register a handler for errors.
+    #
+    # @yield [error] Block called with error
+    def on_error(&block)
+      @error_handlers << block
+    end
+
+    # Close the terminal connection.
+    def close
+      return if @closed
+
+      @closed = true
+      @ws.close
+    end
+
+    alias closed? closed
+
+    private
+
+    def setup_handlers
+      @ws.on :message do |msg|
+        @data_handlers.each { |h| h.call(msg.data) }
+      end
+
+      @ws.on :close do
+        @closed = true
+        @close_handlers.each(&:call)
+      end
+
+      @ws.on :error do |e|
+        @error_handlers.each { |h| h.call(e) }
+      end
+    end
+  end
+
+  # Service for terminal WebSocket connections.
+  class TerminalService
+    def initialize(client)
+      @client = client
+    end
+
+    # Connect to a container's terminal.
+    #
+    # @param container_id [String] Container ID
+    # @param cols [Integer] Terminal width (default: 80)
+    # @param rows [Integer] Terminal height (default: 24)
+    # @return [Terminal]
+    #
+    # @example
+    #   terminal = client.terminal.connect(container.id)
+    #   terminal.on_data { |data| print data }
+    #   terminal.write("ls -la\n")
+    def connect(container_id, cols: 80, rows: 24)
+      begin
+        require "websocket-client-simple"
+      rescue LoadError
+        raise LoadError, "websocket-client-simple is required for terminal connections (gem install websocket-client-simple)"
+      end
+      ws_url = @client.ws_url("/ws/terminal/#{container_id}")
+
+      ws = WebSocket::Client::Simple.connect(ws_url, headers: {
+        "Authorization" => "Bearer #{@client.token}"
+      })
+
+      terminal = Terminal.new(ws)
+
+      # Wait for connection
+      sleep 0.1 until ws.open?
+
+      # Set initial size
+      terminal.resize(cols, rows)
+
+      terminal
+    end
+  end
+end

data/lib/rexec/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rexec
+  VERSION = "1.1.0"
+end

data/lib/rexec.rb

@@ -7,19 +7,20 @@ require_relative "rexec/container"
 require_relative "rexec/file_service"
 require_relative "rexec/terminal"
 
-# Rexec Ruby SDK - Official SDK for Rexec Terminal as a Service.
+# Rexec Ruby SDK — official client for AI-native sandboxes.
 #
 # @example Basic usage
 #   client = Rexec::Client.new("https://your-instance.com", "your-token")
-#   
-#   container = client.containers.create(image: "ubuntu:24.04")
-#   puts "Created: #{container.id}"
-#   
-#   terminal = client.terminal.connect(container.id)
+#
+#   sandbox = client.sandboxes.create(image: "ubuntu")
+#   puts "Created: #{sandbox.id}"
+#
+#   terminal = client.terminal.connect(sandbox.id)
 #   terminal.write("echo hello\n")
 #   terminal.on_data { |data| puts data }
-#   
-#   client.containers.delete(container.id)
+#
+#   client.sandboxes.delete(sandbox.id)
+#   # Legacy: client.containers is the same service
 #
 module Rexec
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pipeops-rexec
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - PipeOpsHQ
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -105,6 +105,12 @@ files:
 - LICENSE
 - README.md
 - lib/rexec.rb
+- lib/rexec/client.rb
+- lib/rexec/container.rb
+- lib/rexec/error.rb
+- lib/rexec/file_service.rb
+- lib/rexec/terminal.rb
+- lib/rexec/version.rb
 homepage: https://github.com/PipeOpsHQ/rexec
 licenses:
 - MIT