daytona-sdk 0.125.0

data/lib/daytona/sandbox.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Daytona
+  class Sandbox # rubocop:disable Metrics/ClassLength
+    DEFAULT_TIMEOUT = 60
+
+    # @return [String] The ID of the sandbox
+    attr_reader :id
+
+    # @return [String] The organization ID of the sandbox
+    attr_reader :organization_id
+
+    # @return [String] The snapshot used for the sandbox
+    attr_reader :snapshot
+
+    # @return [String] The user associated with the project
+    attr_reader :user
+
+    # @return [Hash<String, String>] Environment variables for the sandbox
+    attr_reader :env
+
+    # @return [Hash<String, String>] Labels for the sandbox
+    attr_reader :labels
+
+    # @return [Boolean] Whether the sandbox http preview is public
+    attr_reader :public
+
+    # @return [Boolean] Whether to block all network access for the sandbox
+    attr_reader :network_block_all
+
+    # @return [String] Comma-separated list of allowed CIDR network addresses for the sandbox
+    attr_reader :network_allow_list
+
+    # @return [String] The target environment for the sandbox
+    attr_reader :target
+
+    # @return [Float] The CPU quota for the sandbox
+    attr_reader :cpu
+
+    # @return [Float] The GPU quota for the sandbox
+    attr_reader :gpu
+
+    # @return [Float] The memory quota for the sandbox
+    attr_reader :memory
+
+    # @return [Float] The disk quota for the sandbox
+    attr_reader :disk
+
+    # @return [DaytonaApiClient::SandboxState] The state of the sandbox
+    attr_reader :state
+
+    # @return [DaytonaApiClient::SandboxDesiredState] The desired state of the sandbox
+    attr_reader :desired_state
+
+    # @return [String] The error reason of the sandbox
+    attr_reader :error_reason
+
+    # @return [String] The state of the backup
+    attr_reader :backup_state
+
+    # @return [String] The creation timestamp of the last backup
+    attr_reader :backup_created_at
+
+    # @return [Float] Auto-stop interval in minutes (0 means disabled)
+    attr_reader :auto_stop_interval
+
+    # @return [Float] Auto-archive interval in minutes
+    attr_reader :auto_archive_interval
+
+    # @return [Float] Auto-delete interval in minutes
+    # (negative value means disabled, 0 means delete immediately upon stopping)
+    attr_reader :auto_delete_interval
+
+    # @return [String] The domain name of the runner
+    attr_reader :runner_domain
+
+    # @return [Array<DaytonaApiClient::SandboxVolume>] Array of volumes attached to the sandbox
+    attr_reader :volumes
+
+    # @return [DaytonaApiClient::BuildInfo] Build information for the sandbox
+    attr_reader :build_info
+
+    # @return [String] The creation timestamp of the sandbox
+    attr_reader :created_at
+
+    # @return [String] The last update timestamp of the sandbox
+    attr_reader :updated_at
+
+    # @return [String] The version of the daemon running in the sandbox
+    attr_reader :daemon_version
+
+    # @return [Daytona::SandboxPythonCodeToolbox, Daytona::SandboxTsCodeToolbox]
+    attr_reader :code_toolbox
+
+    # @return [Daytona::Config]
+    attr_reader :config
+
+    # @return [DaytonaApiClient::SandboxApi]
+    attr_reader :sandbox_api
+
+    # @return [DaytonaApiClient::ToolboxApi]
+    attr_reader :toolbox_api
+
+    # @return [Daytona::Process]
+    attr_reader :process
+
+    # @return [Daytona::FileSystem]
+    attr_reader :fs
+
+    # @return [Daytona::Git]
+    attr_reader :git
+
+    # @return [Daytona::ComputerUse]
+    attr_reader :computer_use
+
+    # @params code_toolbox [Daytona::SandboxPythonCodeToolbox, Daytona::SandboxTsCodeToolbox]
+    # @params config [Daytona::Config]
+    # @params sandbox_api [DaytonaApiClient::SandboxApi]
+    # @params sandbox_dto [DaytonaApiClient::Sandbox]
+    # @params toolbox_api [DaytonaApiClient::ToolboxApi]
+    def initialize(code_toolbox:, sandbox_dto:, config:, sandbox_api:, toolbox_api:) # rubocop:disable Metrics/MethodLength
+      process_response(sandbox_dto)
+      @code_toolbox = code_toolbox
+      @config = config
+      @sandbox_api = sandbox_api
+      @toolbox_api = toolbox_api
+      @process = Process.new(
+        sandbox_id: id,
+        code_toolbox:,
+        toolbox_api:,
+        get_preview_link: proc { |port| preview_url(port) }
+      )
+      @fs = FileSystem.new(sandbox_id: id, toolbox_api:)
+      @git = Git.new(sandbox_id: id, toolbox_api:)
+      @computer_use = ComputerUse.new(sandbox_id: id, toolbox_api:)
+    end
+
+    # Archives the sandbox, making it inactive and preserving its state. When sandboxes are
+    # archived, the entire filesystem state is moved to cost-effective object storage, making it
+    # possible to keep sandboxes available for an extended period. The tradeoff between archived
+    # and stopped states is that starting an archived sandbox takes more time, depending on its size.
+    # Sandbox must be stopped before archiving.
+    #
+    # @return [void]
+    def archive
+      sandbox_api.archive_sandbox(id)
+      refresh
+    end
+
+    # Sets the auto-archive interval for the Sandbox.
+    # The Sandbox will automatically archive after being continuously stopped for the specified interval.
+    #
+    # @param interval [Integer]
+    # @return [Integer]
+    # @raise [Daytona:Sdk::Error]
+    def auto_archive_interval=(interval)
+      raise Sdk::Error, 'Auto-archive interval must be a non-negative integer' if interval.negative?
+
+      sandbox_api.set_auto_archive_interval(id, interval)
+      @auto_archive_interval = interval
+    end
+
+    # Sets the auto-delete interval for the Sandbox.
+    # The Sandbox will automatically delete after being continuously stopped for the specified interval.
+    #
+    # @param interval [Integer]
+    # @return [Integer]
+    # @raise [Daytona:Sdk::Error]
+    def auto_delete_interval=(interval)
+      sandbox_api.set_auto_delete_interval(id, interval)
+      @auto_delete_interval = interval
+    end
+
+    # Sets the auto-stop interval for the Sandbox.
+    # The Sandbox will automatically stop after being idle (no new events) for the specified interval.
+    # Events include any state changes or interactions with the Sandbox through the SDK.
+    # Interactions using Sandbox Previews are not included.
+    #
+    # @param interval [Integer]
+    # @return [Integer]
+    # @raise [Daytona:Sdk::Error]
+    def auto_stop_interval=(interval)
+      raise Sdk::Error, 'Auto-stop interval must be a non-negative integer' if interval.negative?
+
+      sandbox_api.set_autostop_interval(id, interval)
+      @auto_stop_interval = interval
+    end
+
+    # Creates an SSH access token for the sandbox.
+    #
+    # @param expires_in_minutes [Integer] TThe number of minutes the SSH access token will be valid for
+    # @return [DaytonaApiClient::SshAccessDto]
+    def create_ssh_access(expires_in_minutes) = sandbox_api.create_ssh_access(id, { expires_in_minutes: })
+
+    # @return [void]
+    def delete
+      sandbox_api.delete_sandbox(id)
+      refresh
+    end
+
+    # Sets labels for the Sandbox.
+    #
+    # @param labels [Hash<String, String>]
+    # @return [Hash<String, String>]
+    def labels=(labels)
+      @labels = sandbox_api.replace_labels(id, DaytonaApiClient::SandboxLabels.build_from_hash(labels:)).labels
+    end
+
+    # Retrieves the preview link for the sandbox at the specified port. If the port is closed,
+    # it will be opened automatically. For private sandboxes, a token is included to grant access
+    # to the URL.
+    #
+    # @param port [Integer]
+    # @return [DaytonaApiClient::PortPreviewUrl]
+    def preview_url(port) = sandbox_api.get_port_preview_url(id, port)
+
+    # Refresh the Sandbox data from the API.
+    #
+    # @return [void]
+    def refresh = process_response(sandbox_api.get_sandbox(id))
+
+    # Revokes an SSH access token for the sandbox.
+    #
+    # @param token [String]
+    # @return [void]
+    def revoke_ssh_access(token) = sandbox_api.revoke_ssh_access(id, token:)
+
+    # Starts the Sandbox and waits for it to be ready.
+    #
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def start(timeout = DEFAULT_TIMEOUT)
+      with_timeout(
+        timeout:,
+        message: "Sandbox #{id} failed to become ready within the #{timeout} seconds timeout period",
+        setup: proc { process_response(sandbox_api.start_sandbox(id)) }
+      ) { wait_for_states(operation: OPERATION_START, target_states: [DaytonaApiClient::SandboxState::STARTED]) }
+    end
+
+    # Stops the Sandbox and waits for it to be stopped.
+    #
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def stop(timeout = DEFAULT_TIMEOUT) # rubocop:disable Metrics/MethodLength
+      with_timeout(
+        timeout:,
+        message: "Sandbox #{id} failed to become stopped within the #{timeout} seconds timeout period",
+        setup: proc {
+          sandbox_api.stop_sandbox(id)
+          refresh
+        }
+      ) do
+        wait_for_states(
+          operation: OPERATION_STOP,
+          target_states: [DaytonaApiClient::SandboxState::STOPPED, DaytonaApiClient::SandboxState::DESTROYED]
+        )
+      end
+    end
+
+    # Creates a new Language Server Protocol (LSP) server instance.
+    # The LSP server provides language-specific features like code completion,
+    # diagnostics, and more.
+    #
+    # @param language_id [Symbol] The language server type (e.g., Daytona::LspServer::Language::PYTHON)
+    # @param path_to_project [String] Path to the project root directory. Relative paths are resolved
+    #                      based on the sandbox working directory.
+    # @return [Daytona::LspServer]
+    def create_lsp_server(language_id:, path_to_project:)
+      LspServer.new(language_id:, path_to_project:, toolbox_api:, sandbox_id: id)
+    end
+
+    #  Validates an SSH access token for the sandbox.
+    #
+    # @param token [String]
+    # @return [DaytonaApiClient::SshAccessValidationDto]
+    def validate_ssh_access(token) = sandbox_api.validate_ssh_access(token)
+
+    # Waits for the Sandbox to reach the 'started' state. Polls the Sandbox status until it
+    # reaches the 'started' state or encounters an error.
+    #
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def wait_for_sandbox_start(_timeout = DEFAULT_TIMEOUT)
+      wait_for_states(operation: OPERATION_START, target_states: [DaytonaApiClient::SandboxState::STARTED])
+    end
+
+    private
+
+    # @params sandbox_dto [DaytonaApiClient::Sandbox]
+    # @return [void]
+    def process_response(sandbox_dto) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      @id = sandbox_dto.id
+      @organization_id = sandbox_dto.organization_id
+      @snapshot = sandbox_dto.snapshot
+      @user = sandbox_dto.user
+      @env = sandbox_dto.env
+      @labels = sandbox_dto.labels
+      @public = sandbox_dto.public
+      @target = sandbox_dto.target
+      @cpu = sandbox_dto.cpu
+      @gpu = sandbox_dto.gpu
+      @memory = sandbox_dto.memory
+      @disk = sandbox_dto.disk
+      @state = sandbox_dto.state
+      @desired_state = sandbox_dto.desired_state
+      @error_reason = sandbox_dto.error_reason
+      @backup_state = sandbox_dto.backup_state
+      @backup_created_at = sandbox_dto.backup_created_at
+      @auto_stop_interval = sandbox_dto.auto_stop_interval
+      @auto_archive_interval = sandbox_dto.auto_archive_interval
+      @auto_delete_interval = sandbox_dto.auto_delete_interval
+      @runner_domain = sandbox_dto.runner_domain
+      @volumes = sandbox_dto.volumes
+      @build_info = sandbox_dto.build_info
+      @created_at = sandbox_dto.created_at
+      @updated_at = sandbox_dto.updated_at
+      @daemon_version = sandbox_dto.daemon_version
+      @network_block_all = sandbox_dto.network_block_all
+      @network_allow_list = sandbox_dto.network_allow_list
+    end
+
+    # Monitors block not to exceed max execution time.
+    #
+    # @param setup [#call, Nil] Optional setup block
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s)
+    # @param message [String] Error message
+    # @return [void]
+    # @raise [Daytona::Sdk::Error]
+    def with_timeout(message:, setup:, timeout: DEFAULT_TIMEOUT, &)
+      start_at = Time.now
+      setup&.call
+
+      Timeout.timeout(
+        setup ? [NO_TIMEOUT, timeout - (Time.now - start_at)].max : timeout,
+        Sdk::Error,
+        message,
+        &
+      )
+    end
+
+    # Waits for the Sandbox to reach the one of the target states. Polls the Sandbox status until it
+    # reaches the one of the target states or encounters an error. It will wait up to 60 seconds
+    # for the Sandbox to reach one of the target states.
+    #
+    # @param operation [#to_s] Operation name for error message
+    # @param target_states [Array<DaytonaApiClient::SandboxState>] List of the target states
+    # @return [void]
+    # @raise [Daytona::Sdk::Error]
+    def wait_for_states(operation:, target_states:)
+      loop do
+        case state
+        when *target_states then return
+        when DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED
+          raise Sdk::Error, "Sandbox #{id} failed to #{operation} with state: #{state}, error reason: #{error_reason}"
+        end
+
+        sleep(IDLE_DURATION)
+        refresh
+      end
+    end
+
+    IDLE_DURATION = 0.1
+    private_constant :IDLE_DURATION
+
+    NO_TIMEOUT = 0
+    private_constant :NO_TIMEOUT
+
+    OPERATION_START = :start
+    private_constant :OPERATION_START
+
+    OPERATION_STOP = :stop
+    private_constant :OPERATION_STOP
+  end
+end

data/lib/daytona/sdk/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Daytona
+  module Sdk
+    VERSION = '0.125.0'
+  end
+end

data/lib/daytona/sdk.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+require 'dotenv'
+Dotenv.load('.env.local', '.env')
+require 'daytona_api_client'
+require 'toml'
+require 'websocket-client-simple'
+
+require_relative 'sdk/version'
+require_relative 'config'
+require_relative 'common/charts'
+require_relative 'common/code_language'
+require_relative 'common/daytona'
+require_relative 'common/file_system'
+require_relative 'common/image'
+require_relative 'common/git'
+require_relative 'common/process'
+require_relative 'common/pty'
+require_relative 'common/resources'
+require_relative 'common/response'
+require_relative 'common/snapshot'
+require_relative 'computer_use'
+require_relative 'code_toolbox/sandbox_python_code_toolbox'
+require_relative 'code_toolbox/sandbox_ts_code_toolbox'
+require_relative 'daytona'
+require_relative 'file_system'
+require_relative 'git'
+require_relative 'lsp_server'
+require_relative 'object_storage'
+require_relative 'sandbox'
+require_relative 'snapshot_service'
+require_relative 'util'
+require_relative 'volume'
+require_relative 'volume_service'
+require_relative 'process'
+
+module Daytona
+  module Sdk
+    class Error < StandardError; end
+
+    def self.logger = @logger ||= Logger.new($stdout, level: Logger::INFO)
+  end
+end

data/lib/daytona/snapshot_service.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Daytona
+  class SnapshotService
+    SNAPSHOTS_FETCH_LIMIT = 200
+
+    # @param snapshots_api [DaytonaApiClient::SnapshotsApi] The snapshots API client
+    # @param object_storage_api [DaytonaApiClient::ObjectStorageApi] The object storage API client
+    def initialize(snapshots_api:, object_storage_api:)
+      @snapshots_api = snapshots_api
+      @object_storage_api = object_storage_api
+    end
+
+    # List all Snapshots.
+    #
+    # @param page [Integer, Nil]
+    # @param limit [Integer, Nil]
+    # @return [Daytona::PaginatedResource] Paginated list of all Snapshots
+    # @raise [Daytona::Sdk::Error]
+    #
+    # @example
+    #   daytona = Daytona::Daytona.new
+    #   response = daytona.snapshot.list(page: 1, limit: 10)
+    #   snapshots.items.each { |snapshot| puts "#{snapshot.name} (#{snapshot.image_name})" }
+    def list(page: nil, limit: nil)
+      raise Sdk::Error, 'page must be positive integer' if page && page < 1
+
+      raise Sdk::Error, 'limit must be positive integer' if limit && limit < 1
+
+      response = snapshots_api.get_all_snapshots(page:, limit:)
+      PaginatedResource.new(
+        total: response.total,
+        page: response.page,
+        total_pages: response.total_pages,
+        items: response.items.map { |snapshot_dto| Snapshot.from_dto(snapshot_dto) }
+      )
+    end
+
+    # Delete a Snapshot.
+    #
+    # @param snapshot [Daytona::Snapshot] Snapshot to delete
+    # @return [void]
+    #
+    # @example
+    #   daytona = Daytona::Daytona.new
+    #   snapshot = daytona.snapshot.get("demo")
+    #   daytona.snapshot.delete(snapshot)
+    #   puts "Snapshot deleted"
+    def delete(snapshot) = snapshots_api.remove_snapshot(snapshot.id)
+
+    # Get a Snapshot by name.
+    #
+    # @param name [String] Name of the Snapshot to get
+    # @return [Daytona::Snapshot] The Snapshot object
+    #
+    # @example
+    #   daytona = Daytona::Daytona.new
+    #   snapshot = daytona.snapshot.get("demo")
+    #   puts "#{snapshot.name} (#{snapshot.image_name})"
+    def get(name) = Snapshot.from_dto(snapshots_api.get_snapshot(name))
+
+    # Creates and registers a new snapshot from the given Image definition.
+    #
+    # @param params [Daytona::CreateSnapshotParams] Parameters for snapshot creation
+    # @param on_logs [Proc, Nil] Callback proc handling snapshot creation logs
+    # @return [Daytona::Snapshot] The created snapshot
+    #
+    # @example
+    #   image = Image.debianSlim('3.12').pipInstall('numpy')
+    #   params = CreateSnapshotParams.new(name: 'my-snapshot', image: image)
+    #   snapshot = daytona.snapshot.create(params) do |chunk|
+    #     print chunk
+    #   end
+    def create(params, on_logs: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      create_snapshot_req = DaytonaApiClient::CreateSnapshot.new(name: params.name)
+
+      if params.image.is_a?(String)
+        create_snapshot_req.image_name = params.image
+        create_snapshot_req.entrypoint = params.entrypoint
+      else
+        create_snapshot_req.build_info = DaytonaApiClient::CreateBuildInfo.new(
+          context_hashes: self.class.process_image_context(object_storage_api, params.image),
+          dockerfile_content: if params.entrypoint
+                                params.image.entrypoint(params.entrypoint).dockerfile
+                              else
+                                params.image.dockerfile
+                              end
+        )
+      end
+
+      if params.resources
+        create_snapshot_req.cpu = params.resources.cpu
+        create_snapshot_req.gpu = params.resources.gpu
+        create_snapshot_req.memory = params.resources.memory
+        create_snapshot_req.disk = params.resources.disk
+      end
+
+      snapshot = snapshots_api.create_snapshot(create_snapshot_req)
+
+      snapshot = stream_logs(snapshot, on_logs:) if on_logs
+
+      if [DaytonaApiClient::SnapshotState::ERROR, DaytonaApiClient::SnapshotState::BUILD_FAILED].include?(snapshot.state)
+        raise Sdk::Error, "Failed to create snapshot #{snapshot.name}, reason: #{snapshot.error_reason}"
+      end
+
+      Snapshot.from_dto(snapshot)
+    end
+
+    # Activate a snapshot
+    #
+    # @param snapshot [Daytona::Snapshot] The snapshot instance
+    # @return [Daytona::Snapshot]
+    def activate(snapshot) = Snapshot.from_dto(snapshots_api.activate_snapshot(snapshot.id))
+
+    # Processes the image context by uploading it to object storage
+    #
+    # @param image [Daytona::Image] The Image instance
+    # @return [Array<String>] List of context hashes stored in object storage
+    def self.process_image_context(object_storage_api, image) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return [] unless image.context_list && !image.context_list.empty?
+
+      push_access_creds = object_storage_api.get_push_access
+
+      object_storage = ObjectStorage.new(
+        endpoint_url: push_access_creds.storage_url,
+        aws_access_key_id: push_access_creds.access_key,
+        aws_secret_access_key: push_access_creds.secret,
+        aws_session_token: push_access_creds.session_token,
+        bucket_name: push_access_creds.bucket
+      )
+
+      image.context_list.map do |context|
+        object_storage.upload(
+          context.source_path,
+          push_access_creds.organization_id,
+          context.archive_path
+        )
+      end
+    end
+
+    private
+
+    # @return [DaytonaApiClient::SnapshotsApi] The snapshots API client
+    attr_reader :snapshots_api
+
+    # @return [DaytonaApiClient::ObjectStorageApi, nil] The object storage API client
+    attr_reader :object_storage_api
+
+    # @param snapshot [DaytonaApiClient::SnapshotDto]
+    # @param on_logs [Proc]
+    # @return [DaytonaApiClient::SnapshotDto]
+    def stream_logs(snapshot, on_logs:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      terminal_states = [
+        DaytonaApiClient::SnapshotState::ACTIVE,
+        DaytonaApiClient::SnapshotState::ERROR,
+        DaytonaApiClient::SnapshotState::BUILD_FAILED
+      ]
+
+      thread = nil
+      previous_state = snapshot.state
+      until terminal_states.include?(snapshot.state)
+        Sdk.logger.debug("Waiting for snapshot to be created: #{snapshot.state}")
+        if thread.nil? && snapshot.state != DaytonaApiClient::SnapshotState::BUILD_PENDING
+          thread = start_log_streaming(snapshot, on_logs:)
+        end
+
+        on_logs.call("Creating snapshot #{snapshot.name} (#{snapshot.state})") if previous_state != snapshot.state
+
+        sleep(1)
+        previous_state = snapshot.state
+        snapshot = snapshots_api.get_snapshot(snapshot.id)
+      end
+
+      thread&.join
+
+      if snapshot.state == DaytonaApiClient::SnapshotState::ACTIVE
+        on_logs.call("Created snapshot #{snapshot.name} (#{snapshot.state})")
+      end
+
+      snapshot
+    end
+
+    # @param snapshot [DaytonaApiClient::SnapshotDto]
+    # @param on_logs [Proc]
+    # @return [Thread]
+    def start_log_streaming(snapshot, on_logs:)
+      uri = URI.parse(snapshots_api.api_client.config.base_url)
+      uri.path = "/api/snapshots/#{snapshot.id}/build-logs"
+      uri.query = 'follow=true'
+
+      headers = {}
+      snapshots_api.api_client.update_params_for_auth!(headers, nil, ['bearer'])
+      Util.stream_async(uri:, headers:, on_chunk: on_logs)
+    end
+  end
+end

data/lib/daytona/util.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Daytona
+  module Util
+    def self.demux(line) # rubocop:disable Metrics/MethodLength
+      stdout = ''.dup
+      stderr = ''.dup
+
+      until line.empty?
+        buff = line.start_with?(STDOUT_PREFIX) ? stdout : stderr
+        line = line[3..]
+
+        end_index = [
+          line.index(STDOUT_PREFIX),
+          line.index(STDERR_PREFIX)
+        ].compact.min || line.length
+        data = line[...end_index]
+        buff << data
+
+        line = line[end_index..]
+      end
+
+      [stdout, stderr]
+    end
+
+    # @param uri [URI]
+    # @param on_chunk [Proc]
+    # @param headers [Hash<String, String>]
+    # @return [Thread]
+    def self.stream_async(uri:, on_chunk:, headers: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      Sdk.logger.debug("Starting async stream: #{uri}")
+      Thread.new do
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          request = Net::HTTP::Get.new(uri, headers)
+
+          http.request(request) do |response|
+            response.read_body do |chunk|
+              Sdk.logger.debug("Chunked response received: #{chunk.inspect}")
+              on_chunk.call(chunk)
+            end
+          end
+        end
+      rescue Net::ReadTimeout => e
+        Sdk.logger.debug("Async stream (#{uri}) timeout: #{e.inspect}")
+      end
+    end
+
+    STDOUT_PREFIX = "\x01\x01\01"
+    private_constant :STDOUT_PREFIX
+
+    STDERR_PREFIX = "\x02\x02\02"
+    private_constant :STDERR_PREFIX
+  end
+end