cogbox 0.190.1

data/lib/cogbox/common/pty.rb

@@ -0,0 +1,310 @@
+# Copyright Daytona Platforms Inc.
+# Copyright Cognifyi
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+require 'json'
+require 'observer'
+
+module Cogbox
+  class PtySize
+    # @return [Integer] Number of terminal rows (height)
+    attr_reader :rows
+
+    # @return [Integer] Number of terminal columns (width)
+    attr_reader :cols
+
+    # Initialize a new PtySize
+    #
+    # @param rows [Integer] Number of terminal rows (height)
+    # @param cols [Integer] Number of terminal columns (width)
+    def initialize(rows:, cols:)
+      @rows = rows
+      @cols = cols
+    end
+  end
+
+  class PtyResult
+    # @return [Integer, nil] Exit code of the PTY process (0 for success, non-zero for errors).
+    #                        nil if the process hasn't exited yet or exit code couldn't be determined.
+    attr_reader :exit_code
+
+    # @return [String, nil] Error message if the PTY failed or was terminated abnormally.
+    #                       nil if no error occurred.
+    attr_reader :error
+
+    # Initialize a new PtyResult
+    #
+    # @param exit_code [Integer, nil] Exit code of the PTY process
+    # @param error [String, nil] Error message if the PTY failed
+    def initialize(exit_code: nil, error: nil)
+      @exit_code = exit_code
+      @error = error
+    end
+  end
+
+  class PtyHandle # rubocop:disable Metrics/ClassLength
+    include Observable
+
+    # @return [String] Session ID of the PTY session
+    attr_reader :session_id
+
+    # @return [Integer, nil] Exit code of the PTY process (if terminated)
+    attr_reader :exit_code
+
+    # @return [String, nil] Error message if the PTY failed
+    attr_reader :error
+
+    # Initialize the PTY handle.
+    #
+    # @param websocket [WebSocket::Client::Simple::Client] Connected WebSocket client connection
+    # @param session_id [String] Session ID of the PTY session
+    # @param handle_resize [Proc, nil] Optional callback for resizing the PTY
+    # @param handle_kill [Proc, nil] Optional callback for killing the PTY
+    def initialize(websocket, session_id:, handle_resize: nil, handle_kill: nil)
+      @websocket = websocket
+      @session_id = session_id
+      @handle_resize = handle_resize
+      @handle_kill = handle_kill
+      @exit_code = nil
+      @error = nil
+      @logger = Sdk.logger
+
+      @status = Status::INIT
+      subscribe
+    end
+
+    # Check if connected to the PTY session
+    #
+    # @return [Boolean] true if connected, false otherwise
+    def connected? = websocket.open?
+
+    # Wait for the PTY connection to be established
+    #
+    # @param timeout [Float] Maximum time in seconds to wait for connection. Defaults to 10.0
+    # @return [void]
+    # @raise [Cogbox::Sdk::Error] If connection timeout is exceeded
+    def wait_for_connection(timeout: DEFAULT_TIMEOUT)
+      return if status == Status::CONNECTED
+
+      start_time = Time.now
+
+      sleep(SLEEP_INTERVAL) until status == Status::CONNECTED || (Time.now - start_time) > timeout
+
+      raise Sdk::Error, 'PTY connection timeout' unless status == Status::CONNECTED
+    end
+
+    # Send input to the PTY session
+    #
+    # @param input [String] Input to send to the PTY
+    # @return [void]
+    def send_input(input)
+      raise Sdk::Error, 'PTY session not connected' unless websocket.open?
+
+      websocket.send(input)
+    end
+
+    # Resize the PTY terminal
+    #
+    # @param pty_size [PtySize] New terminal size
+    # @return [CogboxApiClient::PtySessionInfo] Updated PTY session information
+    def resize(pty_size)
+      raise Sdk::Error, 'No resize handler available' unless handle_resize
+
+      handle_resize.call(pty_size)
+    end
+
+    # Delete the PTY session
+    #
+    # @return [void]
+    def kill
+      raise Sdk::Error, 'No kill handler available' unless handle_kill
+
+      handle_kill.call
+    end
+
+    # Wait for the PTY session to complete
+    #
+    # @param on_data [Proc, nil] Optional callback to handle output data
+    # @return [Cogbox::PtyResult] Result containing exit code and error information
+    def wait(timeout: nil, &on_data)
+      timeout ||= Float::INFINITY
+      return unless status == Status::CONNECTED
+
+      start_time = Time.now
+      add_observer(on_data, :call) if on_data
+
+      sleep(SLEEP_INTERVAL) while status == Status::CONNECTED && (Time.now - start_time) <= timeout
+
+      PtyResult.new(exit_code:, error:)
+    ensure
+      delete_observer(on_data) if on_data
+    end
+
+    # @yieldparam [WebSocket::Frame::Data]
+    # @return [void]
+    def each(&)
+      return unless block_given?
+
+      queue = Queue.new
+      add_observer(proc { queue << _1 }, :call)
+
+      while websocket.open?
+        drain(queue, &)
+        sleep(SLEEP_INTERVAL)
+      end
+
+      drain(queue, &)
+    end
+
+    # Disconnect from the PTY session
+    #
+    # @return [void]
+    def disconnect = websocket.close
+
+    private
+
+    # @return [Symbol]
+    attr_reader :status
+
+    # @return [WebSocket::Client::Simple::Client]
+    attr_reader :websocket
+
+    # @return [Proc, Nil]
+    attr_reader :handle_kill
+
+    # @return [Proc, Nil]
+    attr_reader :handle_resize
+
+    # @return [Logger]
+    attr_reader :logger
+
+    # @return [void]
+    def subscribe
+      websocket.on(:open, &method(:on_websocket_open))
+      websocket.on(:close, &method(:on_websocket_close))
+      websocket.on(:message, &method(:on_websocket_message))
+      websocket.on(:error, &method(:on_websocket_error))
+    end
+
+    # @return [void]
+    def on_websocket_open
+      logger.debug('[Websocket] open')
+      @status = Status::OPEN
+    end
+
+    # @param error [Object, Nil]
+    # @return [void]
+    def on_websocket_close(error)
+      logger.debug("[Websocket] close: #{error.inspect}")
+      @status = Status::CLOSED
+    end
+
+    # @param error [WebSocket::Frame::Incoming::Client]
+    # @return [void]
+    def on_websocket_message(message)
+      logger.debug("[Websocket] message(#{message.type}): #{message.data}")
+
+      case message.type
+      when :binary, :text
+        process_websocket_text_message(message)
+      when :close
+        process_websocket_close_message(message)
+      end
+    end
+
+    # @param error [Object]
+    # @return [void]
+    def on_websocket_error(error)
+      logger.debug("[Websocket] error: #{error.inspect}")
+      logger.debug("[Websocket] error: #{error.class}")
+      @status = Status::ERROR
+    end
+
+    # @param message [WebSocket::Frame::Incoming::Client]
+    # @return [void]
+    def process_websocket_text_message(message)
+      data = JSON.parse(message.data.to_s, symbolize_names: true)
+      process_websocket_control_message(data) if data[:type] == WebSocketMessageType::CONTROL
+    rescue JSON::ParserError, TypeError
+      process_websocket_data_message(message.data.to_s)
+    end
+
+    # @param data [WebSocket::Frame::Data]
+    # @return [void]
+    def process_websocket_data_message(data)
+      changed
+      notify_observers(data)
+    end
+
+    # @param data [WebSocket::Frame::Data]
+    # @return [void]
+    def process_websocket_control_message(data) # rubocop:disable Metrics/MethodLength
+      case data[:status]
+      when WebSocketControlStatus::CONNECTED
+        logger.debug('[control] connected')
+        @status = Status::CONNECTED
+      when WebSocketControlStatus::ERROR
+        logger.debug("[control] error: #{error.inspect}")
+        @status = Status::ERROR
+        @error = data.fetch(:error, 'Unknown connection error')
+      else
+        websocket.close
+        raise Sdk::Error, "Received invalid control message status: #{data[:status]}"
+      end
+    end
+
+    # @param message [WebSocket::Frame::Incoming::Client]
+    # @return [void]
+    def process_websocket_close_message(message)
+      data = JSON.parse(message.data.to_s, symbolize_names: true)
+      @exit_code = data.fetch(:exitCode, nil)
+      @error = data.fetch(:exitReason, nil)
+
+      disconnect
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    # @param queue [Queue]
+    # @yieldparam [WebSocket::Frame::Data]
+    # @return [void]
+    def drain(queue)
+      data = nil
+
+      yield data while (data = queue.pop(true))
+    rescue ThreadError => _e
+      nil
+    end
+
+    DEFAULT_TIMEOUT = 10.0
+    private_constant :DEFAULT_TIMEOUT
+
+    SLEEP_INTERVAL = 0.1
+    private_constant :SLEEP_INTERVAL
+
+    module Status
+      ALL = [
+        INIT = 'init',
+        OPEN = 'open',
+        CONNECTED = 'connected',
+        CLOSED = 'closed',
+        ERROR = 'error'
+      ].freeze
+    end
+
+    module WebSocketMessageType
+      ALL = [
+        CONTROL = 'control'
+      ].freeze
+    end
+
+    module WebSocketControlStatus
+      ALL = [
+        CONNECTED = 'connected',
+        ERROR = 'error'
+      ].freeze
+    end
+  end
+end

data/lib/cogbox/common/resources.rb

@@ -0,0 +1,40 @@
+# Copyright Daytona Platforms Inc.
+# Copyright Cognifyi
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+module Cogbox
+  class Resources
+    # @return [Integer, nil] Number of CPU cores to allocate
+    attr_reader :cpu
+
+    # @return [Integer, nil] Amount of memory in GiB to allocate
+    attr_reader :memory
+
+    # @return [Integer, nil] Amount of disk space in GiB to allocate
+    attr_reader :disk
+
+    # @return [Integer, nil] Number of GPUs to allocate
+    attr_reader :gpu
+
+    # @return [String, Array<String>, nil] Preferred GPU type for the Sandbox
+    attr_reader :gpu_type
+
+    # @param cpu [Integer, nil] Number of CPU cores to allocate
+    # @param memory [Integer, nil] Amount of memory in GiB to allocate
+    # @param disk [Integer, nil] Amount of disk space in GiB to allocate
+    # @param gpu [Integer, nil] Number of GPUs to allocate
+    # @param gpu_type [String, Array<String>, nil] Preferred GPU type for the Sandbox
+    def initialize(cpu: nil, memory: nil, disk: nil, gpu: nil, gpu_type: nil)
+      @cpu = cpu
+      @memory = memory
+      @disk = disk
+      @gpu = gpu
+      @gpu_type = gpu_type
+    end
+
+    # @return [Hash] Hash representation of the resources
+    def to_h = { cpu:, memory:, disk:, gpu:, gpu_type: }.compact
+  end
+end

data/lib/cogbox/common/response.rb

@@ -0,0 +1,84 @@
+# Copyright Daytona Platforms Inc.
+# Copyright Cognifyi
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+module Cogbox
+  # Re-export of api-client enum constants under the Cogbox namespace so
+  # SDK consumers never need to import from CogboxApiClient directly.
+  SandboxClass = CogboxApiClient::SandboxClass
+  SandboxState = CogboxApiClient::SandboxState
+  SandboxListSortField = CogboxApiClient::SandboxListSortField
+  SandboxListSortDirection = CogboxApiClient::SandboxListSortDirection
+  GpuType = CogboxApiClient::GpuType
+
+  class PaginatedResource
+    # @return [Array<Object>]
+    attr_reader :items
+
+    # @return [Float]
+    attr_reader :page
+
+    # @return [Float]
+    attr_reader :total
+
+    # @return [Float]
+    attr_reader :total_pages
+
+    # @param items [Cogbox::Sandbox]
+    # @param page [Float]
+    # @param total [Float]
+    # @param total_pages [Float]
+    def initialize(items:, page:, total:, total_pages:)
+      @items = items
+      @page = page
+      @total = total
+      @total_pages = total_pages
+    end
+  end
+
+  # Query parameters for filtering and sorting when listing Sandboxes.
+  #
+  # All fields are optional and default to +nil+. Constructed via keyword
+  # arguments and immutable (Ruby 3.2+ Data semantics).
+  #
+  # @example
+  #   query = Cogbox::ListSandboxesQuery.new(labels: { 'env' => 'prod' }, limit: 10)
+  #   cogbox.list(query).each { |sandbox| puts sandbox.id }
+  ListSandboxesQuery = Data.define(
+    :limit,
+    :id,
+    :name,
+    :labels,
+    :states,
+    :snapshots,
+    :targets,
+    :min_cpu,
+    :max_cpu,
+    :min_memory_gib,
+    :max_memory_gib,
+    :min_disk_gib,
+    :max_disk_gib,
+    :is_public,
+    :is_recoverable,
+    :created_at_after,
+    :created_at_before,
+    :last_activity_after,
+    :last_activity_before,
+    :sort,
+    :order
+  ) do
+    # All members default to nil so callers pass only the filters they care about.
+    DEFAULTS = members.to_h { |m| [m, nil] }.freeze
+
+    class << self
+      alias_method :_data_new, :new
+      def new(**attrs) = _data_new(**DEFAULTS, **attrs)
+    end
+
+    # Idiomatic Ruby boolean predicate aliases.
+    def public? = is_public
+    def recoverable? = is_recoverable
+  end
+end

data/lib/cogbox/common/snapshot.rb

@@ -0,0 +1,125 @@
+# Copyright Daytona Platforms Inc.
+# Copyright Cognifyi
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+module Cogbox
+  class CreateSnapshotParams
+    # @return [String] Name of the snapshot
+    attr_reader :name
+
+    # @return [String, Cogbox::Image] Image of the snapshot. If a string is provided,
+    #   it should be available on some registry. If an Image instance is provided,
+    #   it will be used to create a new image in Cogbox.
+    attr_reader :image
+
+    # @return [Cogbox::Resources, nil] Resources of the snapshot
+    attr_reader :resources
+
+    # @return [Array<String>, nil] Entrypoint of the snapshot
+    attr_reader :entrypoint
+
+    # @return [String, nil] ID of the region where the snapshot will be available.
+    #   Defaults to organization default region if not specified.
+    attr_reader :region_id
+
+    # @return [CogboxApiClient::SandboxClass, nil] Target sandbox class.
+    attr_reader :sandbox_class
+
+    # @param name [String] Name of the snapshot
+    # @param image [String, Cogbox::Image] Image of the snapshot
+    # @param resources [Cogbox::Resources, nil] Resources of the snapshot
+    # @param entrypoint [Array<String>, nil] Entrypoint of the snapshot
+    # @param region_id [String, nil] ID of the region where the snapshot will be available
+    # @param sandbox_class [CogboxApiClient::SandboxClass, nil] Target sandbox class
+    def initialize(name:, image:, resources: nil, entrypoint: nil, region_id: nil, sandbox_class: nil)
+      @name = name
+      @image = image
+      @resources = resources
+      @entrypoint = entrypoint
+      @region_id = region_id
+      @sandbox_class = sandbox_class
+    end
+  end
+
+  class Snapshot
+    # @return [String] Unique identifier for the Snapshot
+    attr_reader :id
+
+    # @return [String, nil] Organization ID of the Snapshot
+    attr_reader :organization_id
+
+    # @return [Boolean, nil] Whether the Snapshot is general
+    attr_reader :general
+
+    # @return [String] Name of the Snapshot
+    attr_reader :name
+
+    # @return [String] Name of the Image of the Snapshot
+    attr_reader :image_name
+
+    # @return [String] State of the Snapshot
+    attr_reader :state
+
+    # @return [Float, nil] Size of the Snapshot
+    attr_reader :size
+
+    # @return [Array<String>, nil] Entrypoint of the Snapshot
+    attr_reader :entrypoint
+
+    # @return [Float] CPU of the Snapshot
+    attr_reader :cpu
+
+    # @return [Float] GPU of the Snapshot
+    attr_reader :gpu
+
+    # @return [Float] Memory of the Snapshot in GiB
+    attr_reader :mem
+
+    # @return [Float] Disk of the Snapshot in GiB
+    attr_reader :disk
+
+    # @return [String, nil] Error reason of the Snapshot
+    attr_reader :error_reason
+
+    # @return [String] Timestamp when the Snapshot was created
+    attr_reader :created_at
+
+    # @return [String] Timestamp when the Snapshot was last updated
+    attr_reader :updated_at
+
+    # @return [String, nil] Timestamp when the Snapshot was last used
+    attr_reader :last_used_at
+
+    # @return [CogboxApiClient::BuildInfo, nil] Build information for the snapshot
+    attr_reader :build_info
+
+    # @param snapshot_dto [CogboxApiClient::SnapshotDto] The snapshot DTO from the API
+    def initialize(snapshot_dto) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      @id = snapshot_dto.id
+      @organization_id = snapshot_dto.organization_id
+      @general = snapshot_dto.general
+      @name = snapshot_dto.name
+      @image_name = snapshot_dto.image_name
+      @state = snapshot_dto.state
+      @size = snapshot_dto.size
+      @entrypoint = snapshot_dto.entrypoint
+      @cpu = snapshot_dto.cpu
+      @gpu = snapshot_dto.gpu
+      @mem = snapshot_dto.mem
+      @disk = snapshot_dto.disk
+      @error_reason = snapshot_dto.error_reason
+      @created_at = snapshot_dto.created_at
+      @updated_at = snapshot_dto.updated_at
+      @last_used_at = snapshot_dto.last_used_at
+      @build_info = snapshot_dto.build_info
+    end
+
+    # Creates a Snapshot instance from a SnapshotDto
+    #
+    # @param dto [CogboxApiClient::SnapshotDto] The snapshot DTO from the API
+    # @return [Cogbox::Snapshot] The snapshot instance
+    def self.from_dto(dto) = new(dto)
+  end
+end