daytona 0.148.0 → 0.149.0.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2beee2143c5d47184a4d33fb2e598358b85b7f891a2d86b927fdac5b1242a36
-  data.tar.gz: 4ad6f822f59d29259b515690ac269d6a847ac78635f2e514298a6cf0b06723ab
+  metadata.gz: 0111eaa3f2e1edf3951f4fb4c4ab90039a9bd264602f1f0da5c88b89982d6376
+  data.tar.gz: 29fb26a2e6c4f55e3263e5e6f774d0e8625d4bca444d23aae3bf9e3e53731eaf
 SHA512:
-  metadata.gz: 37435c7af9bfb1c90eedc910f59f0e20f96c9801da2750661ad2c0355ebc2e3f9b5f7e3b2fb7d7d21101a5f15b1ebb617bebbe769d17e4896ff861a1d217b1c6
-  data.tar.gz: 0333f8765e0e6924f250d85dadf2071aab3dc98c4220dc0d9330bd0eae6e775e08aad00f5839dde87af7e2096a3da6783dcddd495c799d12bb81a6f53f775470
+  metadata.gz: d2b03e16b5d7d31005cae3d297525415335143717d624b1fd842dfde1ddacebb267189a52077070ef0dd887c3e9d8814a54d2176be154dafb2b4e2050fff3446
+  data.tar.gz: da5ddce3d882d5f7fff7ad2d6f8e0b105fee37401742656c675743c8a41e51fb69c6c6f53815a29a9271818dc181685384c874e30c91ed309710cfc4a75a7cd3

data/lib/daytona/common/event_subscriber.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# Copyright 2025 Daytona Platforms Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require_relative 'socketio_client'
+
+module Daytona
+  # Manages a Socket.IO connection and dispatches events to per-resource handlers.
+  # Generic — works for sandboxes, volumes, snapshots, runners, etc.
+  class EventSubscriber
+    # @param api_url [String]
+    # @param token [String]
+    # @param organization_id [String, nil]
+    def initialize(api_url:, token:, organization_id: nil)
+      @api_url = api_url
+      @token = token
+      @organization_id = organization_id
+      @client = nil
+      @connected = false
+      @failed = false
+      @fail_error = nil
+      @listeners = {}
+      @registered_events = Set.new
+      @mutex = Mutex.new
+      @disconnect_timer = nil
+      @last_event_at = Time.now
+      @reconnecting = false
+      @close_requested = false
+      @max_reconnects = 10
+    end
+
+    # Idempotent: ensure a connection attempt is in progress or already established.
+    # Non-blocking. Starts a background Thread to connect if not already connected
+    # and no attempt is currently running.
+    # @return [void]
+    def ensure_connected
+      return if @connected
+      return if @connect_thread&.alive?
+
+      @connect_thread = Thread.new do
+        connect
+      rescue StandardError
+        # Callers check connected? when they need it
+      end
+    end
+
+    # Establish the Socket.IO connection.
+    # @return [void]
+    # @raise [StandardError] on connection failure
+    def connect
+      return if @connected
+
+      # Close any existing stale connection before creating a fresh one
+      @client&.close rescue nil # rubocop:disable Style/RescueModifier
+
+      @client = SocketIOClient.new(
+        api_url: @api_url,
+        token: @token,
+        organization_id: @organization_id,
+        on_event: method(:handle_event),
+        on_disconnect: method(:handle_disconnect)
+      )
+
+      @close_requested = false
+      @client.connect
+      @connected = true
+      @failed = false
+      @fail_error = nil
+    rescue StandardError => e
+      @failed = true
+      @fail_error = "WebSocket connection failed: #{e.message}"
+      raise
+    end
+
+    # Subscribe to specific events for a resource.
+    # @param resource_id [String] The ID of the resource (e.g. sandbox ID, volume ID).
+    # @param events [Array<String>] List of Socket.IO event names to listen for.
+    # @yield [event_name, data] Called with raw event name and data hash.
+    # @return [Proc] Unsubscribe function.
+    DISCONNECT_DELAY = 30
+
+    def subscribe(resource_id, events:, &handler)
+      # Cancel any pending delayed disconnect
+      @disconnect_timer&.kill
+      @disconnect_timer = nil
+
+      # Register any new events with the Socket.IO client (idempotent)
+      register_events(events)
+
+      @mutex.synchronize do
+        @listeners[resource_id] ||= []
+        @listeners[resource_id] << handler
+      end
+
+      lambda {
+        should_schedule = false
+        @mutex.synchronize do
+          @listeners[resource_id]&.delete(handler)
+          @listeners.delete(resource_id) if @listeners[resource_id] && @listeners[resource_id].empty?
+          should_schedule = @listeners.empty?
+        end
+
+        # Schedule delayed disconnect when no resources are listening anymore
+        if should_schedule
+          @disconnect_timer = Thread.new do
+            sleep(DISCONNECT_DELAY)
+            empty = @mutex.synchronize { @listeners.empty? }
+            disconnect if empty
+          end
+        end
+      }
+    end
+
+    # @return [Boolean]
+    def connected?
+      @connected
+    end
+
+    # @return [Boolean]
+    def failed?
+      @failed
+    end
+
+    # @return [String, nil]
+    attr_reader :fail_error
+
+    # Disconnect and clean up.
+    def disconnect
+      @close_requested = true
+      @client&.close
+      @connected = false
+      @mutex.synchronize { @listeners.clear }
+      @registered_events.clear
+    end
+
+    private
+
+    # Register Socket.IO event handlers (idempotent - each event is registered once).
+    # The SocketIOClient dispatches all events via the on_event callback, so we just
+    # need to track which events we care about for filtering in handle_event.
+    def register_events(events)
+      events.each { |evt| @registered_events.add(evt) }
+    end
+
+    def handle_event(event_name, data)
+      @last_event_at = Time.now
+
+      # Only dispatch events that have been registered
+      return unless @registered_events.include?(event_name)
+
+      resource_id = extract_id_from_event(data)
+      return unless resource_id
+
+      dispatch(resource_id, event_name, data)
+    end
+
+    # Extract resource ID from an event payload.
+    # Handles two payload shapes:
+    #   - Wrapper: {sandbox: {id: ...}, ...} -> nested resource ID
+    #   - Direct: {id: ...} -> top-level ID
+    def extract_id_from_event(data)
+      return nil unless data.is_a?(Hash)
+
+      %w[sandbox volume snapshot runner].each do |key|
+        nested = data[key]
+        next unless nested.is_a?(Hash)
+
+        sid = nested['id']
+        return sid if sid.is_a?(String)
+      end
+
+      top_id = data['id']
+      return top_id if top_id.is_a?(String)
+
+      nil
+    end
+
+    def dispatch(resource_id, event_name, data)
+      handlers = @mutex.synchronize { @listeners[resource_id]&.dup || [] }
+      handlers.each do |handler|
+        handler.call(event_name, data)
+      rescue StandardError
+        # Don't let handler errors break other handlers
+      end
+    end
+
+    def handle_disconnect
+      @connected = false
+      return if @close_requested
+
+      Thread.new { reconnect_loop }
+    end
+
+    def reconnect_loop
+      return if @reconnecting
+
+      @reconnecting = true
+
+      @max_reconnects.times do |attempt|
+        return if @close_requested
+
+        delay = [2**attempt, 30].min
+        sleep(delay)
+        return if @close_requested
+
+        connect
+        @reconnecting = false
+        return
+      rescue StandardError
+        # Continue retrying
+      end
+
+      # All attempts failed
+      @failed = true
+      @fail_error = "WebSocket reconnection failed after #{@max_reconnects} attempts"
+      @reconnecting = false
+    end
+  end
+end

data/lib/daytona/common/socketio_client.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+# Copyright 2025 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, on_event: nil, on_disconnect: nil, connect_timeout: 5)
+      @api_url = api_url
+      @token = token
+      @organization_id = organization_id
+      @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
+
+      @ws = WebSocket::Client::Simple.connect(ws_url)
+
+      @ws.on :message do |msg|
+        client.send(:handle_raw_message, msg.data.to_s, connected_queue)
+      end
+
+      @ws.on :error do |_e|
+        client.instance_variable_get(:@mutex).synchronize do
+          client.instance_variable_set(:@connected, false)
+        end
+        connected_queue.push(:error) unless client.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)
+        on_disconnect&.call if was_connected && !close_requested
+      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
+
+      raise "WebSocket connection failed: #{result}" if result != :connected
+
+      @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
+
+      port_str = (parsed.scheme == 'https' && port == 443) || (parsed.scheme == 'http' && port == 80) ? '' : ":#{port}"
+      "#{ws_scheme}://#{host}#{port_str}/api/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
+        @mutex.synchronize { @connected = false }
+      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/daytona.rb

@@ -44,12 +44,27 @@ module Daytona
       @snapshots_api = DaytonaApiClient::SnapshotsApi.new(api_client)
       @snapshot = SnapshotService.new(snapshots_api:, object_storage_api:, default_region_id: config.target,
                                       otel_state:)
+      # Event subscriber for real-time sandbox updates
+      @event_subscriber = nil
+
+      # Create and start WebSocket event subscriber connection in the background (non-blocking).
+      token = config.api_key || config.jwt_token
+      return unless token
+
+      @event_subscriber = EventSubscriber.new(
+        api_url: config.api_url,
+        token: token,
+        organization_id: config.organization_id
+      )
+      @event_subscriber.ensure_connected
     end
 
     # Shuts down OTel providers, flushing any pending telemetry data.
     #
     # @return [void]
     def close
+      @event_subscriber&.disconnect
+      @event_subscriber = nil
       ::Daytona.shutdown_otel(@otel_state)
       @otel_state = nil
     end
@@ -265,7 +280,8 @@ module Daytona
         config:,
         sandbox_api:,
         code_toolbox:,
-        otel_state: @otel_state
+        otel_state: @otel_state,
+        event_subscriber: @event_subscriber
       )
     end
 

data/lib/daytona/sandbox.rb

@@ -119,12 +119,13 @@ module Daytona
     # @params sandbox_api [DaytonaApiClient::SandboxApi]
     # @params sandbox_dto [DaytonaApiClient::Sandbox]
     # @params otel_state [Daytona::OtelState, nil]
-    def initialize(code_toolbox:, sandbox_dto:, config:, sandbox_api:, otel_state: nil) # rubocop:disable Metrics/MethodLength
+    def initialize(code_toolbox:, sandbox_dto:, config:, sandbox_api:, otel_state: nil, event_subscriber: nil) # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
       process_response(sandbox_dto)
       @code_toolbox = code_toolbox
       @config = config
       @sandbox_api = sandbox_api
       @otel_state = otel_state
+      @event_subscriber = event_subscriber
 
       # Create toolbox API clients with dynamic configuration
       toolbox_api_config = build_toolbox_api_config
@@ -165,6 +166,9 @@ module Daytona
       )
       @lsp_api = lsp_api
       @info_api = info_api
+
+      # Subscribe to real-time events for this sandbox
+      subscribe_to_events
     end
 
     # Archives the sandbox, making it inactive and preserving its state. When sandboxes are
@@ -224,14 +228,26 @@ module Daytona
     # @return [DaytonaApiClient::SshAccessDto]
     def create_ssh_access(expires_in_minutes) = sandbox_api.create_ssh_access(id, { expires_in_minutes: })
 
+    # Deletes the Sandbox and waits for it to reach the 'destroyed' state.
+    #
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
     # @return [void]
-    def delete
-      sandbox_api.delete_sandbox(id)
-      refresh
-    rescue DaytonaApiClient::ApiError => e
-      raise unless e.code == 404
+    def delete(timeout = DEFAULT_TIMEOUT)
+      process_response(sandbox_api.delete_sandbox(id))
 
-      @state = 'destroyed'
+      return if state.to_s == DaytonaApiClient::SandboxState::DESTROYED.to_s
+
+      with_timeout(
+        timeout:,
+        message: "Sandbox #{id} failed to be destroyed within the #{timeout} seconds timeout period",
+        setup: nil
+      ) do
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::DESTROYED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED],
+          safe_refresh: true
+        )
+      end
     end
 
     # Gets the user's home directory path for the logged in user inside the Sandbox.
@@ -340,7 +356,12 @@ module Daytona
         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]) }
+      ) do
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::STARTED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
+        )
+      end
     end
 
     # Recovers the Sandbox from a recoverable error and waits for it to be ready.
@@ -357,7 +378,12 @@ module Daytona
         timeout:,
         message: "Sandbox #{id} failed to recover within the #{timeout} seconds timeout period",
         setup: proc { process_response(sandbox_api.recover_sandbox(id)) }
-      ) { wait_for_states(operation: OPERATION_START, target_states: [DaytonaApiClient::SandboxState::STARTED]) }
+      ) do
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::STARTED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
+        )
+      end
     rescue StandardError => e
       raise Sdk::Error, "Failed to recover sandbox: #{e.message}"
     end
@@ -375,9 +401,9 @@ module Daytona
           refresh
         }
       ) do
-        wait_for_states(
-          operation: OPERATION_STOP,
-          target_states: [DaytonaApiClient::SandboxState::STOPPED, DaytonaApiClient::SandboxState::DESTROYED]
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::STOPPED, DaytonaApiClient::SandboxState::DESTROYED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
         )
       end
     end
@@ -420,9 +446,17 @@ module Daytona
     #
     # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s)
     # @return [void]
-    def wait_for_resize_complete(_timeout = DEFAULT_TIMEOUT)
-      wait_for_states(operation: OPERATION_RESIZE, target_states: [DaytonaApiClient::SandboxState::STARTED,
-                                                                   DaytonaApiClient::SandboxState::STOPPED])
+    def wait_for_resize_complete(timeout = DEFAULT_TIMEOUT)
+      with_timeout(
+        timeout:,
+        message: "Sandbox #{id} resize did not complete within the #{timeout} seconds timeout period",
+        setup: nil
+      ) do
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::STARTED, DaytonaApiClient::SandboxState::STOPPED, DaytonaApiClient::SandboxState::ARCHIVED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
+        )
+      end
     end
 
     # Creates a new Language Server Protocol (LSP) server instance.
@@ -448,8 +482,17 @@ module Daytona
     #
     # @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])
+    def wait_for_sandbox_start(timeout = DEFAULT_TIMEOUT)
+      with_timeout(
+        timeout:,
+        message: "Sandbox #{id} failed to start within the #{timeout} seconds timeout period",
+        setup: nil
+      ) do
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::STARTED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
+        )
+      end
     end
 
     # Waits for the Sandbox to reach the 'stopped' state. Polls the Sandbox status until it
@@ -458,9 +501,17 @@ module Daytona
     #
     # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
     # @return [void]
-    def wait_for_sandbox_stop(_timeout = DEFAULT_TIMEOUT)
-      wait_for_states(operation: OPERATION_STOP, target_states: [DaytonaApiClient::SandboxState::STOPPED,
-                                                                 DaytonaApiClient::SandboxState::DESTROYED])
+    def wait_for_sandbox_stop(timeout = DEFAULT_TIMEOUT)
+      with_timeout(
+        timeout:,
+        message: "Sandbox #{id} failed to stop within the #{timeout} seconds timeout period",
+        setup: nil
+      ) do
+        wait_for_state(
+          target_states: [DaytonaApiClient::SandboxState::STOPPED, DaytonaApiClient::SandboxState::DESTROYED],
+          error_states: [DaytonaApiClient::SandboxState::ERROR, DaytonaApiClient::SandboxState::BUILD_FAILED]
+        )
+      end
     end
 
     instrument :archive, :auto_archive_interval=, :auto_delete_interval=, :auto_stop_interval=,
@@ -545,40 +596,105 @@ module Daytona
       )
     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.
+    # Waits for the Sandbox to reach the one of the target states via WebSocket events
+    # with periodic polling safety net.
     #
-    # @param operation [#to_s] Operation name for error message
-    # @param target_states [Array<DaytonaApiClient::SandboxState>] List of the target states
+    # @param target_states [Array<DaytonaApiClient::SandboxState>] States that indicate success.
+    # @param error_states [Array<DaytonaApiClient::SandboxState>] States that indicate failure.
+    # @param safe_refresh [Boolean] If true, wrap refresh in rescue for delete operations (404s).
     # @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}"
+    def wait_for_state(target_states:, error_states:, safe_refresh: false) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      target_strings = target_states.map(&:to_s)
+      error_strings = error_states.map(&:to_s)
+
+      return if target_strings.include?(state.to_s)
+
+      if error_strings.include?(state.to_s)
+        raise Sdk::Error, "Sandbox #{id} is in error state: #{state}, error reason: #{error_reason}"
+      end
+
+      mutex = Mutex.new
+      state_changed = ConditionVariable.new
+      result_state = nil
+
+      unsubscribe = @event_subscriber&.subscribe(id, events: ['sandbox.state.updated']) do |_event_name, data|
+        next unless data.is_a?(Hash)
+        next if result_state # Already resolved
+
+        new_state = data['newState']
+        next unless new_state
+
+        if target_strings.include?(new_state) || error_strings.include?(new_state)
+          mutex.synchronize do
+            result_state = new_state
+            state_changed.signal
+          end
+        end
+      end
+
+      begin
+        mutex.synchronize do
+          until result_state
+            # Wait 1s for WebSocket event, then poll as safety net
+            state_changed.wait(mutex, POLL_SAFETY_INTERVAL)
+
+            break if result_state
+
+            # Poll: refresh data and check state
+
+            if safe_refresh
+              begin
+                refresh
+              rescue DaytonaApiClient::ApiError => e
+                @state = DaytonaApiClient::SandboxState::DESTROYED if e.code == 404
+              rescue StandardError
+                nil # ignore other refresh errors
+              end
+            else
+              refresh rescue nil # rubocop:disable Style/RescueModifier
+            end
+
+            return if target_strings.include?(state.to_s)
+
+            if error_strings.include?(state.to_s)
+              raise Sdk::Error,
+                    "Sandbox #{id} is in error state: #{state}, error reason: #{error_reason}"
+            end
+          end
         end
 
-        sleep(IDLE_DURATION)
-        refresh
+        if result_state && error_strings.include?(result_state)
+          raise Sdk::Error,
+                "Sandbox #{id} entered error state: #{result_state}, error reason: #{error_reason}"
+        end
+      ensure
+        unsubscribe&.call
       end
     end
 
-    IDLE_DURATION = 0.1
-    private_constant :IDLE_DURATION
+    def subscribe_to_events
+      return unless @event_subscriber
 
-    NO_TIMEOUT = 0
-    private_constant :NO_TIMEOUT
+      @event_subscriber.ensure_connected
+
+      @event_subscriber.subscribe(
+        id,
+        events: ['sandbox.state.updated', 'sandbox.desired-state.updated', 'sandbox.created']
+      ) do |_event_name, data|
+        next unless data.is_a?(Hash)
 
-    OPERATION_START = :start
-    private_constant :OPERATION_START
+        raw = data['sandbox'] || data
+        process_response(DaytonaApiClient::Sandbox.build_from_hash(raw)) if raw.is_a?(Hash)
+      rescue StandardError
+        nil # Event payload may be incomplete
+      end
+    end
 
-    OPERATION_STOP = :stop
-    private_constant :OPERATION_STOP
+    POLL_SAFETY_INTERVAL = 1
+    private_constant :POLL_SAFETY_INTERVAL
 
-    OPERATION_RESIZE = :resize
-    private_constant :OPERATION_RESIZE
+    NO_TIMEOUT = 0
+    private_constant :NO_TIMEOUT
   end
 end

data/lib/daytona/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module Daytona
   module Sdk
-    VERSION = '0.148.0'
+    VERSION = '0.149.0.alpha.1'
   end
 end

data/lib/daytona/sdk.rb

@@ -27,6 +27,8 @@ require_relative 'computer_use'
 require_relative 'code_toolbox/sandbox_python_code_toolbox'
 require_relative 'code_toolbox/sandbox_ts_code_toolbox'
 require_relative 'code_toolbox/sandbox_js_code_toolbox'
+require_relative 'common/socketio_client'
+require_relative 'common/event_subscriber'
 require_relative 'daytona'
 require_relative 'file_system'
 require_relative 'git'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: daytona
 version: !ruby/object:Gem::Version
-  version: 0.148.0
+  version: 0.149.0.alpha.1
 platform: ruby
 authors:
 - Daytona Platforms Inc.
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-exporter-otlp
@@ -86,28 +85,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.148.0
+        version: 0.149.0.alpha.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.148.0
+        version: 0.149.0.alpha.1
 - !ruby/object:Gem::Dependency
   name: daytona_toolbox_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.148.0
+        version: 0.149.0.alpha.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.148.0
+        version: 0.149.0.alpha.1
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -172,6 +171,7 @@ files:
 - lib/daytona/common/code_interpreter.rb
 - lib/daytona/common/code_language.rb
 - lib/daytona/common/daytona.rb
+- lib/daytona/common/event_subscriber.rb
 - lib/daytona/common/file_system.rb
 - lib/daytona/common/git.rb
 - lib/daytona/common/image.rb
@@ -180,6 +180,7 @@ files:
 - lib/daytona/common/resources.rb
 - lib/daytona/common/response.rb
 - lib/daytona/common/snapshot.rb
+- lib/daytona/common/socketio_client.rb
 - lib/daytona/computer_use.rb
 - lib/daytona/config.rb
 - lib/daytona/daytona.rb
@@ -207,7 +208,6 @@ metadata:
   source_code_uri: https://github.com/daytonaio/daytona
   changelog_uri: https://github.com/daytonaio/daytona/releases
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -222,8 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for Daytona
 test_files: []