daytona 0.196.0 → 0.198.0

data/lib/daytona/common/socketio_client.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+# Copyright Daytona Platforms Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require 'timeout'
+
+require 'websocket-client-simple'
+require 'json'
+require 'uri'
+
+module Daytona
+  # Minimal Engine.IO/Socket.IO v4 client over raw WebSocket.
+  # Supports connect with auth, heartbeat, and event reception.
+  #
+  # Engine.IO v4 heartbeat protocol (WebSocket transport):
+  #   - Server sends PING (type 2) every pingInterval ms
+  #   - Client must respond with PONG (type 3) within pingTimeout ms
+  #   - Client monitors for missing server PINGs to detect dead connections
+  class SocketIOClient
+    # Engine.IO v4 packet types
+    EIO_OPEN    = '0'
+    EIO_CLOSE   = '1'
+    EIO_PING    = '2'
+    EIO_PONG    = '3'
+    EIO_MESSAGE = '4'
+
+    # Socket.IO v4 packet types (inside Engine.IO messages)
+    SIO_CONNECT       = '0'
+    SIO_DISCONNECT    = '1'
+    SIO_EVENT         = '2'
+    SIO_CONNECT_ERROR = '4'
+
+    attr_reader :connected
+
+    # @param api_url [String] The API URL (e.g., "https://app.daytona.io/api")
+    # @param token [String] Auth token (API key or JWT)
+    # @param organization_id [String, nil] Organization ID for room joining
+    # @param on_event [Proc] Called with (event_name, data_hash) for each Socket.IO event
+    # @param on_disconnect [Proc] Called when the connection is lost
+    # @param connect_timeout [Numeric] Connection timeout in seconds
+    def initialize(api_url:, token:, organization_id: nil, source: nil, sdk_version: nil, on_event: nil,
+                   on_disconnect: nil, connect_timeout: 5)
+      @api_url = api_url
+      @token = token
+      @organization_id = organization_id
+      @source = source
+      @sdk_version = sdk_version
+      @on_event = on_event
+      @on_disconnect = on_disconnect
+      @connect_timeout = connect_timeout
+      @connected = false
+      @mutex = Mutex.new
+      @write_mutex = Mutex.new
+      @health_thread = nil
+      @ping_interval = 25
+      @ping_timeout = 20
+      @last_server_activity = Time.now
+      @ws = nil
+      @close_requested = false
+    end
+
+    # Establish the WebSocket connection and perform Socket.IO handshake.
+    # @return [Boolean] true if connection succeeded
+    # @raise [StandardError] on connection failure
+    def connect
+      ws_url = build_ws_url
+      connected_queue = Queue.new
+
+      # Capture self because websocket-client-simple uses instance_exec for callbacks
+      client = self
+
+      # Register callbacks inside the connect block so they are installed before the
+      # socket dials — otherwise the Engine.IO handshake can arrive before :message
+      # is bound, stalling the connection into a polling fallback/timeout.
+      @ws = WebSocket::Client::Simple.connect(ws_url) do |ws|
+        ws.on :message do |msg|
+          client.send(:handle_raw_message, msg.data.to_s, connected_queue)
+        end
+
+        ws.on :error do |_e|
+          was_connected = client.instance_variable_get(:@mutex).synchronize do
+            prev = client.instance_variable_get(:@connected)
+            client.instance_variable_set(:@connected, false)
+            prev
+          end
+          connected_queue.push(:error) unless was_connected
+        end
+
+        ws.on :close do
+          mutex = client.instance_variable_get(:@mutex)
+          was_connected = mutex.synchronize do
+            prev = client.instance_variable_get(:@connected)
+            client.instance_variable_set(:@connected, false)
+            prev
+          end
+          on_disconnect = client.instance_variable_get(:@on_disconnect)
+          close_requested = client.instance_variable_get(:@close_requested)
+          begin
+            on_disconnect&.call if was_connected && !close_requested
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # Wait for connection with timeout
+      result = nil
+      begin
+        Timeout.timeout(@connect_timeout) { result = connected_queue.pop }
+      rescue Timeout::Error
+        close
+        raise "WebSocket connection timed out after #{@connect_timeout}s"
+      end
+
+      if result != :connected
+        close
+        raise "WebSocket connection failed: #{result}"
+      end
+
+      @mutex.synchronize { @connected }
+    end
+
+    # @return [Boolean]
+    def connected?
+      @mutex.synchronize { @connected }
+    end
+
+    # Gracefully close the connection.
+    def close
+      @close_requested = true
+      @health_thread&.kill
+      @health_thread = nil
+
+      send_raw(EIO_CLOSE) if @ws
+      @ws&.close
+      @mutex.synchronize { @connected = false }
+    rescue StandardError
+      # Ignore errors during close
+    end
+
+    private
+
+    def build_ws_url
+      parsed = URI.parse(@api_url)
+      ws_scheme = parsed.scheme == 'https' ? 'wss' : 'ws'
+      host = parsed.host
+      port = parsed.port
+
+      query_parts = ['EIO=4', 'transport=websocket']
+      query_parts << "organizationId=#{URI.encode_www_form_component(@organization_id)}" if @organization_id
+      query_parts << "source=#{URI.encode_www_form_component(@source)}" if @source
+      query_parts << "sdkVersion=#{URI.encode_www_form_component(@sdk_version)}" if @sdk_version
+
+      port_str = (parsed.scheme == 'https' && port == 443) || (parsed.scheme == 'http' && port == 80) ? '' : ":#{port}"
+      base_path = parsed.path.to_s.chomp('/')
+      "#{ws_scheme}://#{host}#{port_str}#{base_path}/socket.io/?#{query_parts.join('&')}"
+    end
+
+    def handle_raw_message(raw, connected_queue)
+      return if raw.nil? || raw.empty?
+
+      # Track all server activity for health monitoring.
+      # If the server stops sending ANY data (pings, events, etc.)
+      # the health monitor will detect the dead connection.
+      @last_server_activity = Time.now
+
+      case raw[0]
+      when EIO_OPEN
+        # Parse open payload for ping interval
+        begin
+          payload = JSON.parse(raw[1..])
+          @ping_interval = (payload['pingInterval'] || 25_000) / 1000.0
+          @ping_timeout = (payload['pingTimeout'] || 20_000) / 1000.0
+        rescue JSON::ParserError
+          # Use default ping interval
+        end
+        # Send Socket.IO CONNECT with auth
+        auth = JSON.generate({ token: @token })
+        send_raw("#{EIO_MESSAGE}#{SIO_CONNECT}#{auth}")
+
+      when EIO_PING
+        # Server heartbeat — respond immediately with PONG
+        send_raw(EIO_PONG)
+
+      when EIO_PONG
+        # Unexpected in EIO v4 (server doesn't respond to client pings),
+        # but handle gracefully — activity already tracked above.
+        nil
+
+      when EIO_MESSAGE
+        handle_socketio_packet(raw[1..], connected_queue)
+
+      when EIO_CLOSE
+        @mutex.synchronize { @connected = false }
+      end
+    end
+
+    def handle_socketio_packet(data, connected_queue)
+      return if data.nil? || data.empty?
+
+      case data[0]
+      when SIO_CONNECT
+        # Connection acknowledged
+        @mutex.synchronize { @connected = true }
+        start_health_monitor
+        connected_queue&.push(:connected)
+
+      when SIO_CONNECT_ERROR
+        # Connection rejected
+        error_msg = begin
+          payload = JSON.parse(data[1..])
+          payload['message'] || 'Unknown error'
+        rescue JSON::ParserError
+          data[1..]
+        end
+        @mutex.synchronize { @connected = false }
+        connected_queue&.push("Auth rejected: #{error_msg}")
+
+      when SIO_EVENT
+        handle_event(data[1..])
+
+      when SIO_DISCONNECT
+        was_connected = @mutex.synchronize do
+          prev = @connected
+          @connected = false
+          prev
+        end
+        @on_disconnect&.call if was_connected && !@close_requested
+      end
+    end
+
+    def handle_event(json_str)
+      return unless @on_event
+
+      # Skip namespace prefix if present (e.g., "/ns,")
+      if json_str&.start_with?('/')
+        comma_idx = json_str.index(',')
+        json_str = json_str[(comma_idx + 1)..] if comma_idx
+      end
+
+      event_array = JSON.parse(json_str)
+      return unless event_array.is_a?(Array) && event_array.length >= 1
+
+      event_name = event_array[0]
+      event_data = event_array[1]
+
+      @on_event.call(event_name, event_data)
+    rescue JSON::ParserError
+      # Malformed event, ignore
+    end
+
+    # Monitors connection health by checking for server activity.
+    # In Engine.IO v4, the server sends PING every pingInterval ms.
+    # If no server activity (pings, events, any data) is seen within
+    # pingInterval + pingTimeout, the connection is considered dead.
+    HEALTH_CHECK_INTERVAL = 5 # seconds — check frequently for fast detection
+
+    def start_health_monitor
+      @health_thread&.kill
+      @last_server_activity = Time.now
+      @health_thread = Thread.new do
+        loop do
+          sleep(HEALTH_CHECK_INTERVAL)
+          break unless connected?
+
+          if Time.now - @last_server_activity > @ping_interval + @ping_timeout
+            # No server activity within expected window — connection is dead
+            @mutex.synchronize { @connected = false }
+            @on_disconnect&.call unless @close_requested
+            # Force-close the dead WebSocket to ensure cleanup
+            @ws&.close rescue nil # rubocop:disable Style/RescueModifier
+            break
+          end
+        rescue StandardError
+          break
+        end
+      end
+    end
+
+    def send_raw(msg)
+      @write_mutex.synchronize do
+        @ws&.send(msg)
+      end
+    rescue StandardError
+      # Ignore write errors
+    end
+  end
+end

data/lib/daytona/config.rb

@@ -39,6 +39,16 @@ module Daytona
     # @return [Boolean, nil]
     attr_accessor :otel_enabled
 
+    # Observe sandbox state by legacy polling instead of WebSocket event streaming.
+    # Defaults to false (event streaming). Can also be enabled via the
+    # DAYTONA_USE_DEPRECATED_POLLING environment variable.
+    #
+    # @deprecated Polling-only mode will be removed in a future release;
+    #   event streaming is the default and falls back to polling automatically
+    #   when WebSockets are unavailable.
+    # @return [Boolean]
+    attr_accessor :use_deprecated_polling
+
     # Experimental configuration options
     #
     # @return [Hash, nil] Experimental configuration hash
@@ -52,6 +62,9 @@ module Daytona
     # @param organization_id [String, nil] Daytona organization ID. Defaults to ENV['DAYTONA_ORGANIZATION_ID'].
     # @param target [String, nil] Daytona target. Defaults to ENV['DAYTONA_TARGET'].
     # @param otel_enabled [Boolean, nil] Enable OpenTelemetry tracing for SDK operations.
+    # @param use_deprecated_polling [Boolean, nil] Observe sandbox state by legacy polling instead of
+    #   WebSocket event streaming. Defaults to false (event streaming). Can also be enabled via the
+    #   DAYTONA_USE_DEPRECATED_POLLING environment variable.
     # @param _experimental [Hash, nil] Experimental configuration options.
     def initialize( # rubocop:disable Metrics/ParameterLists
       api_key: nil,
@@ -60,6 +73,7 @@ module Daytona
       organization_id: nil,
       target: nil,
       otel_enabled: nil,
+      use_deprecated_polling: nil,
       _experimental: nil
     )
       @env_reader = daytona_env_reader
@@ -71,6 +85,7 @@ module Daytona
       @organization_id = organization_id || @env_reader.call('DAYTONA_ORGANIZATION_ID')
       @otel_enabled = otel_enabled
       @_experimental = _experimental
+      @use_deprecated_polling = resolve_use_deprecated_polling(use_deprecated_polling)
     end
 
     # Reads a DAYTONA_-prefixed environment variable using the same precedence
@@ -105,5 +120,11 @@ module Daytona
     def daytona_filter(env_hash)
       env_hash.select { |k, _| k.start_with?('DAYTONA_') }
     end
+
+    def resolve_use_deprecated_polling(use_deprecated_polling)
+      return use_deprecated_polling unless use_deprecated_polling.nil?
+
+      @env_reader.call('DAYTONA_USE_DEPRECATED_POLLING') == 'true'
+    end
   end
 end

data/lib/daytona/daytona.rb

@@ -48,18 +48,49 @@ module Daytona
       @api_client = build_api_client
       @sandbox_api = DaytonaApiClient::SandboxApi.new(api_client)
       @config_api = DaytonaApiClient::ConfigApi.new(api_client)
+      @analytics_api_url = nil
+      @analytics_api_url_fetched = false
+      @analytics_api_url_mutex = Mutex.new
       @volume = VolumeService.new(DaytonaApiClient::VolumesApi.new(api_client), otel_state:)
       @secret = SecretService.new(DaytonaApiClient::SecretApi.new(api_client), otel_state:)
       @object_storage_api = DaytonaApiClient::ObjectStorageApi.new(api_client)
       @snapshots_api = DaytonaApiClient::SnapshotsApi.new(api_client)
-      @snapshot = SnapshotService.new(snapshots_api:, object_storage_api:, default_region_id: config.target,
-                                      otel_state:)
+      @snapshot = SnapshotService.new(
+        snapshots_api:,
+        object_storage_api:,
+        default_region_id: config.target,
+        otel_state:
+      )
+      token = config.api_key || config.jwt_token
+
+      if config.use_deprecated_polling
+        warn(
+          '[DEPRECATION] Polling-only mode (use_deprecated_polling / DAYTONA_USE_DEPRECATED_POLLING) ' \
+          'is deprecated and will be removed in a future release.',
+          uplevel: 1
+        )
+      else
+        @event_dispatcher = EventDispatcher.new(
+          api_url: config.api_url,
+          token: token,
+          organization_id: config.organization_id,
+          source: SOURCE_RUBY,
+          sdk_version: Sdk::VERSION
+        )
+        @event_dispatcher.ensure_connected
+      end
+
+      @subscription_manager = EventSubscriptionManager.new(@event_dispatcher)
     end
 
     # Shuts down OTel providers, flushing any pending telemetry data.
     #
     # @return [void]
     def close
+      @subscription_manager&.shutdown
+      @subscription_manager = nil
+      @event_dispatcher&.disconnect
+      @event_dispatcher = nil
       ::Daytona.shutdown_otel(@otel_state)
       @otel_state = nil
     end
@@ -68,7 +99,8 @@ module Daytona
     #
     # @param params [Daytona::CreateSandboxFromSnapshotParams, Daytona::CreateSandboxFromImageParams, Nil] Sandbox creation parameters
     # @return [Daytona::Sandbox] The created sandbox
-    # @raise [Daytona::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    # @raise [Daytona::Sdk::Error] If auto_stop_interval, auto_pause_interval, or auto_archive_interval is negative,
+    #   or if auto_stop_interval and auto_pause_interval are both non-zero
     def create(params = nil, on_snapshot_create_logs: nil)
       if params.nil?
         params = CreateSandboxFromSnapshotParams.new(language: CodeLanguage::PYTHON)
@@ -87,8 +119,9 @@ module Daytona
     # Deletes a Sandbox.
     #
     # @param sandbox [Daytona::Sandbox]
+    # @param wait [Boolean] When +true+, block until the Sandbox is destroyed.
     # @return [void]
-    def delete(sandbox) = sandbox.delete
+    def delete(sandbox, wait: false) = sandbox.delete(wait:)
 
     # Gets a Sandbox by its ID.
     #
@@ -148,6 +181,18 @@ module Daytona
     # @return [Daytona::OtelState, nil]
     attr_reader :otel_state
 
+    # Resolves the deployment's Analytics API URL via /config, cached (including a nil
+    # result) for the client's lifetime. Errors are not cached, so failed lookups retry.
+    def analytics_api_url
+      @analytics_api_url_mutex.synchronize do
+        unless @analytics_api_url_fetched
+          @analytics_api_url = @config_api.config_controller_get_config.analytics_api_url
+          @analytics_api_url_fetched = true
+        end
+        @analytics_api_url
+      end
+    end
+
     # Fetches a single page of sandboxes. Each call produces one OTel span
     # ("Daytona.list_fetch_page") so that paginated iteration emits N spans
     # for N pages.
@@ -192,7 +237,8 @@ module Daytona
     # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
     # @param on_snapshot_create_logs [Proc]
     # @return [Daytona::Sandbox] The created sandbox
-    # @raise [Daytona::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    # @raise [Daytona::Sdk::Error] If auto_stop_interval, auto_pause_interval, or auto_archive_interval is negative,
+    #   or if auto_stop_interval and auto_pause_interval are both non-zero
     def _create(params, timeout: 60, on_snapshot_create_logs: nil)
       raise Sdk::Error, 'Timeout must be a non-negative number' if timeout.negative?
 
@@ -200,6 +246,17 @@ module Daytona
 
       raise Sdk::Error, 'auto_stop_interval must be a non-negative integer' if params.auto_stop_interval&.negative?
 
+      raise Sdk::Error, 'auto_pause_interval must be a non-negative integer' if params.auto_pause_interval&.negative?
+
+      if params.auto_stop_interval&.positive? && params.auto_pause_interval&.positive?
+        raise Sdk::Error,
+              'auto_stop_interval and auto_pause_interval are mutually exclusive. Set at most one of them to a non-zero value'
+      end
+
+      if params.auto_pause_interval&.positive? && params.auto_delete_interval&.zero?
+        raise Sdk::Error, 'Ephemeral sandboxes cannot have auto-pause enabled. Set auto_pause_interval to 0'
+      end
+
       if params.auto_archive_interval&.negative?
         raise Sdk::Error, 'auto_archive_interval must be a non-negative integer'
       end
@@ -214,6 +271,7 @@ module Daytona
         public: params.public,
         target: config.target,
         auto_stop_interval: params.auto_stop_interval,
+        auto_pause_interval: params.auto_pause_interval,
         auto_archive_interval: params.auto_archive_interval,
         auto_delete_interval: params.auto_delete_interval,
         volumes: params.volumes,
@@ -322,7 +380,9 @@ module Daytona
         sandbox_dto:,
         config:,
         sandbox_api:,
-        otel_state: @otel_state
+        otel_state: @otel_state,
+        analytics_api_url_provider: method(:analytics_api_url),
+        subscription_manager: @subscription_manager
       )
     end
 

data/lib/daytona/file_system.rb

@@ -402,7 +402,7 @@ module Daytona
     #     end
     #   end
     def replace_in_files(files:, pattern:, new_value:)
-      replace_request = DaytonaApiClient::ReplaceRequest.new(
+      replace_request = DaytonaToolboxApiClient::ReplaceRequest.new(
         files: files,
         pattern: pattern,
         new_value: new_value

data/lib/daytona/lsp_server.rb

@@ -56,7 +56,7 @@ module Daytona
           language_id:,
           path_to_project:,
           uri: uri(path),
-          position: DaytonaApiClient::Position.new(line: position.line, character: position.character)
+          position: DaytonaToolboxApiClient::LspPosition.new(line: position.line, character: position.character)
         )
       )
     end

data/lib/daytona/process.rb

@@ -3,6 +3,8 @@
 
 # frozen_string_literal: true
 
+require 'base64'
+require 'json'
 require 'uri'
 
 module Daytona
@@ -410,19 +412,32 @@ module Daytona
     #   pty_handle.disconnect
     #
     # @raise [Daytona::Sdk::Error] If the PTY session creation fails or the session ID is already in use.
-    def create_pty_session(id:, cwd: nil, envs: nil, pty_size: nil) # rubocop:disable Metrics/MethodLength
-      response = toolbox_api.create_pty_session(
-        DaytonaToolboxApiClient::PtyCreateRequest.new(
-          id:,
-          cwd:,
-          envs:,
-          cols: pty_size&.cols,
-          rows: pty_size&.rows,
-          lazy_start: true
-        )
-      )
+    def create_pty_session(id:, cwd: nil, envs: nil, pty_size: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      cols = pty_size&.cols || 80
+      rows = pty_size&.rows || 24
+
+      preview_link = get_preview_link.call(WS_PORT)
+      url = URI.parse(preview_link.url)
+      url.scheme = url.scheme == 'https' ? 'wss' : 'ws'
+      url.path = '/process/pty/create-connect'
 
-      connect_pty_session(response.session_id)
+      params = { id:, cols:, rows: }
+      params[:cwd] = cwd if cwd
+      url.query = URI.encode_www_form(params)
+
+      headers = toolbox_api.api_client.default_headers.dup.merge(
+        'X-Daytona-Preview-Token' => preview_link.token
+      )
+      protocols = [headers['Sec-WebSocket-Protocol'], PTY_EXIT_CONTROL_SUBPROTOCOL].compact
+      protocols << "X-Daytona-Pty-Envs~#{Base64.urlsafe_encode64(envs.to_json, padding: false)}" if envs
+      headers['Sec-WebSocket-Protocol'] = protocols.join(', ')
+
+      PtyHandle.new(
+        WebSocket::Client::Simple.connect(url.to_s, headers:),
+        session_id: id,
+        handle_resize: ->(pty_size_arg) { resize_pty_session(id, pty_size_arg) },
+        handle_kill: -> { delete_pty_session(id) }
+      ).tap(&:wait_for_connection)
     end
 
     # Connects to an existing PTY session in the Sandbox.
@@ -448,13 +463,14 @@ module Daytona
       url.scheme = url.scheme == 'https' ? 'wss' : 'ws'
       url.path = "/process/pty/#{session_id}/connect"
 
+      headers = toolbox_api.api_client.default_headers.dup.merge(
+        'X-Daytona-Preview-Token' => preview_link.token
+      )
+      headers['Sec-WebSocket-Protocol'] =
+        [headers['Sec-WebSocket-Protocol'], PTY_EXIT_CONTROL_SUBPROTOCOL].compact.join(', ')
+
       handle = nil
-      WebSocket::Client::Simple.connect(
-        url.to_s,
-        headers: toolbox_api.api_client.default_headers.dup.merge(
-          'X-Daytona-Preview-Token' => preview_link.token
-        )
-      ) do |client|
+      WebSocket::Client::Simple.connect(url.to_s, headers:) do |client|
         handle = PtyHandle.new(
           client,
           session_id:,